> Source: https://vitna.ai/docs/concepts/observation
> Raw Markdown: https://vitna.ai/docs/concepts/observation.md
> Corpus index: https://vitna.ai/llms.txt

# Observation

One figure, parsed out of one document, at one moment. The atom of the record.

`witness.observation` is append-only. An observation is never edited and never
deleted, so anything derived from it can be recomputed and checked later.

## Fields

| Field | Meaning |
|---|---|
| `id` | Serial id, the thing `/api/v1/observations/{id}/proof` takes |
| `fetchId` | The read this came out of |
| `skuId` | What was priced |
| `dimensionId` | What it was priced by |
| `amountUsd` | The figure, `numeric(14,6)` |
| `observedAt` | When it was read |
| `derived` | Whether Vitna computed this rather than read it |
| `derivation` | How, when `derived` is true |
| `locator` | Where in the document it was found |
| `parserVersion` | Which version of the adapter read it |

## One figure per cell per read

A unique index on the fetch, the sku, the dimension and the
[context band](../api/v1/prices/tape.md#context-bands) means one read of one
document yields at most one figure for any one cell. A page that lists the same model
twice cannot produce two conflicting observations from a single fetch.

## Derived figures announce themselves

Some numbers are not printed on the page. A provider that prices a 20-minute
sandbox session has an hourly rate implied but not published, and Vitna
computes it.

A database constraint requires `derivation` to be non-null whenever `derived` is
true, so a computed figure cannot enter the record without saying how it was
computed. `derived` travels all the way out to the API, on every tape row and
every spread entry.

## `locator` and `parserVersion` exist for the argument you will have later

When a figure looks wrong, the question is always the same: did the provider
change the price, or did Vitna misread the page? `locator` says where in the
document the parser looked and `parserVersion` says which parser looked there,
so that question is answerable a year later against an archived document rather
than debated.

## From observation to price

An observation is a reading, not yet a price. Readings accumulate into
[price periods](price-period.md), and change detection publishes a move only on
the second consistent read.
