vitna.ai/docs/routing/usage-import Machine view
Raw .md llms.txt
> Source: https://vitna.ai/docs/routing/usage-import
> Raw Markdown: https://vitna.ai/docs/routing/usage-import.md
> Corpus index: https://vitna.ai/llms.txt

# Importing usage

`aperture:usage:import` reads a consumer's own usage export back into the
record, so it can say what actually served a workload.

```bash
npm run aperture:usage:import -- \
  --workload convexity/conversational --file ./august.csv \
  --window 2026-08-01..2026-08-31 --source-ref "console export, 1 Sep"
```

## Flags

| Flag | Meaning |
|---|---|
| `--workload <id>` | Whose usage this is |
| `--file <path>` | The export |
| `--window a..b` | Calendar dates, inclusive at both ends |
| `--source-ref <text>` | Where the export came from. Required. |
| `--format json\|jsonl\|csv` | The file's format, guessed from the extension |
| `--no-adopt` | Read the window without moving the workload's incumbent |

## It fetches nothing

The export is a file somebody made. `--source-ref` is required for the same
reason a measurement requires one: a reading with no provenance is a number.

`jsonl` is the one format this repository also writes: a
[runtime ledger](../runtime/ledger.md) is read by this command unmodified, with
the same two fields and the same arithmetic as a console export.

## Units are the workload's own units

Deliberately unclever about what an export contains. Units are reduced by
whoever ran the export, because only they know whether a request is a unit or a
hundred tokens are.

Two columns are required and the rest ignored: the model as the provider names
it, and the units it served. A row with no model, no units, or units that are
not a whole number is a refusal naming the row. A usage file is somebody's
afternoon of exporting, and a silently dropped row is a share that is quietly
wrong.

A third column, `provider`, is read where the export carries one and is never
inferred where it does not. A blank cell and a missing column say the same
thing, which is that this row did not say. Nothing is guessed from the model's
own vendor: a model served through a substrate is served by somebody other than
whoever trained it, which is the entire reason the column is worth having. A
runtime's own ledger has written the field on every line since R1, so a `.jsonl`
import carries providers without anybody adding a column.

## Windows

`2026-08-01..2026-08-31`, inclusive at both ends, which is how a billing period
reads and how anybody says "the first to the last". A window that ends before it
starts is refused.

## Shares, and when a window is unambiguous

Models are totalled, mapped onto skus where they are recognised, and each sku's
share of the window computed.

One sku must hold **95 percent** of a window before it is called what the
workload is running. Not 100: a lane with a cross-vendor fallback answers a few
calls elsewhere in any real month, and a rule that only fires on a clean sweep
would never fire.

## Read against the lane's route, where there is one

The threshold says whether one sku swept the window. It cannot say whether what
else answered was supposed to, and until the import read the lane's published
[route](fallbacks.md) those were the same question. A declared fallback holding
3 percent passed because 3 is under 5, and an undeclared sku holding the same 3
percent passed for exactly the same reason. They are opposite facts.

A lane with a chain is now read against it as well:

| What the window shows | What the import says |
|---|---|
| Only the primary and its declared fallbacks | The route was honoured, with each fallback's share named |
| A sku the route does not name, at any share | A finding, whatever the share, because production is running something no decision covers |
| A declared fallback leading the window | A finding about the primary, which is the model a decision named and the one meant to serve |

None of this changes when the incumbent moves. Adoption still needs one sku to
hold the window and to be the sku the standing decision named, so a finding can
stand beside a confirmation: a primary that swept its window did sweep it, and
an undeclared sliver beside it is a separate fact worth printing.

A workload with no chain is read exactly as it was before chains existed. An
environment target declares no fallbacks, and asserting a route for it would be
judging a window against a policy nobody published.

## A model the registry does not hold

Gets no row, and its units still count toward the window total.

So a workload running something Vitna cannot price shows up as rows that do not
sum to their window, rather than as a clean sweep. The denominator is stored on
every row rather than derived, so one row still says what share it was, and a
later import cannot quietly change what an earlier reading meant.

## What gets written

One `aperture.deployment_observation` row per sku per window:

| Column | Meaning |
|---|---|
| `workload_id`, `sku_id` | What ran, and for whom |
| `window_start`, `window_end` | The period, inclusive |
| `units`, `window_units` | This sku's units, and every unit the export carried |
| `confirms_decision_id` | The accepted decision this reading confirms, where it confirms one |
| `source_ref` | Where the export came from |
| `imported_at`, `note` | When it was read, and any remark |
| `provider` | Who served this sku's units, where the export named one provider for all of them. Null where it named none, where it named more than one, or where a runtime pushed the reading |
| `origin` | `import` here; `runtime` on a reading [a runtime pushed](../api/v1/engine/usage.md) |

Constraints: the window is ordered, units are positive, units fit inside the
window total, and one reading exists per sku per window. Importing the same
export twice is the same fact and must not become two readings.

A null `confirms_decision_id` is the ordinary case for a workload nobody has
ruled on lately, and is not a defect.

## Reading a window back at list price

```bash
npm run aperture:reconcile -- --workload <id> --window 2026-08-01..2026-08-31
npm run aperture:reconcile -- --workload <id> --window 2026-08-01..2026-08-31 --spend bill.json
```

What an imported window cost at the tape's own prices, printed and written
nowhere. Each sku's units are priced from the price periods that stood over
the window and the workload's unit profile; a sku the record cannot price
across the whole window is counted as coverage rather than costed at zero, and
a window whose tape moved is a bound rather than a guess, because a reading is
a window total and the record does not know how the units fell around the
move.

`--spend` takes lines off the bill, as JSON: `{ "amountUsd": 240 }` for the
whole window, or with a `"sku"` for one row of it. Each comparable line prints
the implied discount off list. A whole-window line is refused unless every
unit in the window is priced, because a discount computed against part of the
bill is a number that only looks like one. Nothing from a spend file enters
the record: a negotiated price is [not a market](../concepts/source.md), and
this is how it stays on the customer's side of the line.

The workload page at `/console` renders the same reconciliation of the newest
window, from the same module, so the page and the command cannot disagree.

## No new privileges

Written by this command and by `aperture:workload:edit` as the owning role. No
application role is granted anything, so the register still holds no `DELETE`
and the site reads these rows only to put them on `/console`.
Human Machine Shift+M