> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vainona.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Freshness

> Whether an answer reflects the document's current revision, and when answers are computed.

Answers are computed asynchronously, seconds behind writes while the engine is healthy. Instead of hiding that, every answer says how current it is.

## Freshness states

Freshness is worked out when the answer is read, from the answer, the document and the judgment's policy. The first row that applies wins:

| `freshness`   | When                                                                                                                      |
| ------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `unavailable` | The document has never been judged in its current incarnation.                                                            |
| `stale`       | The document changed since the answer, and the namespace's budget has paused evaluation.                                  |
| `pending`     | The document changed since the answer, and the policy is `on_change`: the new answer is on its way.                       |
| `stale`       | The document changed since the answer, and the policy is `on_read`, `manual` or `periodic`, so nothing recomputes it yet. |
| `failed`      | The newest attempt, for the current revision, failed.                                                                     |
| `stale`       | A `periodic` answer is older than its interval.                                                                           |
| `fresh`       | Otherwise: computed for the document's current revision.                                                                  |

For a judgment with [related documents](/guides/related-documents), "the document changed since the answer" means that a write after the answer's `watermark` touched it: a write to the document itself, or to a document that pointed at it before or after the write. So a new ticket makes its account `pending`, and the account is `fresh` again once an answer lands with a watermark at or above the ticket's write.

`stale` and `failed` answers still carry the last good numbers and the `revision` they were computed for. A `failed` answer for a document that was never judged successfully has no numbers. The next write to a document starts a new attempt, so `failed` gives way to `pending` or `stale`. A document that failed for a reason of its own, or is still failing 24 hours after it last changed, keeps its `failed` answer until it is written again, rather than being retried; see [evaluations](/concepts/evaluations).

To read only fresh answers, pass `answers: "fresh_only"` to a query. To wait for an answer after a write, pass `wait_for` to the write; an answer not ready when it times out comes back `pending` in the write's response, whatever this table would say on a get. To wait on a read, pass `wait_ms` (at most 10,000) to a get.

## Freshness policies

A judgment's policy decides when its answers are computed. It is a setting: changing it creates no new version.

| Policy                                      | Computes                                                                                     | Use it for                                         |
| ------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `on_read` (default)                         | The first time a get or query includes the answer, then caches it until the document changes | Judgments read one document at a time              |
| `on_change`                                 | Whenever the document changes                                                                | Judgments you filter or sort on across a namespace |
| `periodic` with `interval` (`"1h"`, `"1d"`) | On every interval, whether or not the document changed                                       | Time-bound judgments, such as churn within 30 days |
| `manual`                                    | Only in backfills                                                                            | One-off analyses                                   |

Any policy can set `debounce_ms`. A document that changed more recently than that is not judged until it settles, so a burst of writes costs one evaluation. Any policy can also set `max_wait_ms`, the ceiling: a document that never settles is still judged once that long has passed since its oldest unjudged change. It defaults to 12 × `debounce_ms` for a judgment with related documents and a `debounce_ms` above 0, and to none otherwise. Rapid writes to one document also coalesce: twelve changes in a second are judged once, on the latest revision.

A `get` of a document with `on_read` judgments starts their evaluation. The first read returns them `pending`, unless it passes `wait_ms`.

See [choosing a freshness policy](/guides/freshness-policies) for the cost of each.