Get started

How much of a bill the record can price

Source

One window of somebody's spend, bucketed by whether the record holds a figure for it.

bash
npm run aperture:bill -- --window 2026-08-01..2026-08-31 --spend ./august.json

Nothing is written. It is a report over the record, exactly as `aperture:counterfactual` is, and a customer's negotiated rate never enters the record from here.

The file is the one aperture:reconcile already takes: an array of lines, each carrying amountUsd and optionally the sku it covers, where a line with no sku is the whole window's stated spend. One file, two questions. The reconciliation asks what a window would have cost at list. This asks how much of it the record can speak to at all.

Three buckets, never one number

BucketWhat it meansWhat it is for
PricedResolves to a sku the record held a figure for across the whole windowThe claim
Declared, unpricedFalls in a class the record declares and holds no figure forThe roadmap, in the customer's own money
Outside the recordNames no sku the record carriesThe scope question, and sometimes the answer is that it stays outside

The middle bucket carries two different facts and the run says which one every line is. A class the record declares and has never wired is one. A sku the record knows, in a class it does price, that carried no figure over the window is the other. Both are honestly unpriced, and somebody deciding what to wire next needs to know which they are looking at.

Priced means the whole window, not a corner of it

A price period either covers the window or it does not, and the same walk aperture:reconcile uses decides it. A rate first read three weeks before a four month window ends overlaps that window and prices almost none of it, so it is not priced here; it is declared and unpriced, with the reason naming how much of the window it did cover.

This was wrong until 2026-09-10, and the run that found it is worth keeping. A real bill over 130 days came back at a hundred percent priced, because every sku on it carries an open period that began in late August. The record held figures over about 21 of those days. The test asked whether a period overlapped the window, and the answer to that question is not the answer to this one.

So a long window is now legible rather than flattering: the header prints the window's length, a priced line says it was priced over all of it, and a partial line says how many days of how many it actually had. If any line is partial the caveats name the thinnest one, because that is the number a reader would otherwise never meet.

A bill line names a sku and not a meter, so coverage is asked of each of that sku's dimensions and the best-covered one answers. A sku whose input rate spans the window and whose batch rate does not is one the record can price across the window.

That is a claim about the sku, and on 2026-09-10 the same bill showed what it does not claim. It carried $18.44 of cache-write spend and reported it priced, correctly by this rule, because the sku it was spent on is one the record prices. The record held no cache-write meter at all. Nothing was miscounted and the fix was not here: the dimension was registered instead, and the model class carries two of them now. What the run still does not do is say when a bill's own vocabulary is finer than the record's, which is an open call in CAPTURE.md rather than a defect with a patch waiting.

The denominator is the whole design

A coverage figure computed over only the lines somebody itemised would flatter itself exactly where it matters, so the run states what it divided by:

  • A bill that states a window total is measured against that total, and the difference between the total and the lines is printed as unitemised. That money is neither priced nor unpriced, because nobody said what it bought.
  • A bill that states no total is measured against the sum of its own lines, and the run says so in as many words. If those lines are a subset of the invoice, the figure is higher than the invoice's own would be.

The percentage travels inside the sentence rather than above it, because that sentence is the one that gets pasted into a message, and a coverage figure that travels without the money it was taken over is the failure this command is shaped to avoid.

This is also why a percentage is allowed here and refused on /coverage. A share of one bill has a denominator the reader is holding. A share of the AI market has none that anybody publishes.

What it refuses

It refusesBecause
A bill stating two window totalsTwo denominators, and no answer uses both
A negative lineA credit is not spend, and netting one against the total hides what was bought
A line with no amountUsdA line that is not money cannot be a share of one
Lines exceeding the stated totalIt reports the overrun rather than clamping it, since a clamp would print a share against a total nobody wrote

An unknown sku is not a refusal. It is the third bucket, which is the point.

It takes no workload, and it needs a database

No workload, deliberately. The reconciliation needs one because it weighs units against prices and units come from an imported usage export. A bill needs none: the question is what the record prices, and the answer is the same whether or not anybody has registered the work that produced the spend. That is what lets this run against the first bill a prospect sends rather than only against a customer already through the loop.

A database is required and there is no fallback to the committed snapshot, because the question is dated. "Priced over your window" is a claim about what the record held in that month, and the snapshot holds today's figures with today's read date. Answering from it would be a coverage figure quietly computed against the wrong month.