vitna.ai/docs/cli/aperture/bill Machine view
Raw .md llms.txt
> Source: https://vitna.ai/docs/cli/aperture/bill
> Raw Markdown: https://vitna.ai/docs/cli/aperture/bill.md
> Corpus index: https://vitna.ai/llms.txt

# How much of a bill the record can price

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`](counterfactual.md) 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

| Bucket | What it means | What it is for |
|---|---|---|
| Priced | Resolves to a sku the record held a figure for across the whole window | The claim |
| Declared, unpriced | Falls in a class the record declares and holds no figure for | The roadmap, in the customer's own money |
| Outside the record | Names no sku the record carries | The 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](../../concepts/dimension.md) 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](https://vitna.ai/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 refuses | Because |
|---|---|
| A bill stating two window totals | Two denominators, and no answer uses both |
| A negative line | A credit is not spend, and netting one against the total hides what was bought |
| A line with no `amountUsd` | A line that is not money cannot be a share of one |
| Lines exceeding the stated total | It 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.
Human Machine Shift+M