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