Get started

Importing usage

Source

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

FlagMeaning
--workload <id>Whose usage this is
--file <path>The export
--window a..bCalendar 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-adoptRead 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 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 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 showsWhat the import says
Only the primary and its declared fallbacksThe route was honoured, with each fallback's share named
A sku the route does not name, at any shareA finding, whatever the share, because production is running something no decision covers
A declared fallback leading the windowA 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:

ColumnMeaning
workload_id, sku_idWhat ran, and for whom
window_start, window_endThe period, inclusive
units, window_unitsThis sku's units, and every unit the export carried
confirms_decision_idThe accepted decision this reading confirms, where it confirms one
source_refWhere the export came from
imported_at, noteWhen it was read, and any remark
providerWho 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
originimport here; runtime on a reading a runtime pushed

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, 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.