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

# The model

Vitna is a record of what AI infrastructure costs, and an engine that decides
when a change to a production stack is worth making. Two systems, one
repository, one database with a schema each.

## Witness, the record

Witness reads pricing pages that providers publish, archives what it read, and
accumulates a price history from it.

The chain runs one way and never doubles back:

```
source  ->  fetch  ->  observation  ->  price period  ->  market event
```

A [source](source.md) is a fetchable document. A fetch is one read of it, with
the bytes archived under their sha256. An [observation](observation.md) is one
figure parsed out of that document, pinned to the fetch it came from. A
[price period](price-period.md) is a stretch during which that figure did not
move. A [market event](market-event.md) is a published statement that something
happened.

Everything in that chain is append-only. A price does not get corrected by
editing it; a correction is a later row that names the one it replaces.

## Aperture, the engine

Aperture holds workloads: a thing you run, the sku it currently runs on, the
candidates in play, and the evidence measured about them. It arms triggers,
watches the record for them, and when one fires it produces a brief arguing for
or against a change.

It proposes. It does not act. See [decision.md](decision.md).

## The honesty contract

The rules the whole system is built to keep, because a price record that is
occasionally wrong is worth less than no price record at all:

**Nothing is asserted without a document behind it.** Every figure on the tape
names the sha256 of the archived page it was read from, and the URL a human
should read.

**A figure read once is not yet a price.** Change detection publishes a move on
the second consistent read, so one bad parse of one malformed page does not
enter the record as a price change.

**Absence is stated, never filled.** A cell no source publishes is missing from
the tape rather than present and zero. A class with no wired market answers an
empty tape. An endpoint that cannot reach the record answers `503` rather than
an empty list, because an empty list reads as "nothing is there" when the truth
is "I could not look."

**The record signs itself.** Each day's observations are hashed into a Merkle
root and signed. See [attestation.md](attestation.md).

**Derived figures say so.** A number Vitna computed rather than read carries
`derived: true` and a `derivation` string saying how.

## Two ways of serving

The same code answers from two places, and `meta.source` on every response
says which:

| `meta.source` | Meaning |
|---|---|
| `database` | The live record. This is what `vitna.ai` serves. |
| `snapshot` | The JSON committed under `app/data/`, a picture of one moment. |

A checkout with no `DATABASE_URL` runs entirely from the snapshot, which is how
the tests run and how `npm run dev` works. Endpoints that can only be answered
from the record (history, attestations, proofs, proposals, watches) say so
rather than improvising an answer from the snapshot.

## What Vitna is not

It is not a broker, a proxy, or a router. It holds no keys to anything and
sends no traffic anywhere. It reads published list prices, which is a narrower
claim than "what you will pay": no negotiated rate, committed-spend discount or
private agreement is visible to it, and it says so rather than implying its
numbers are yours.
