Comptroller Console

Watch spend as it happens, learn before a budget runs out, and catch patterns no single grant reveals, from signed receipts alone.

On this page

A budget stops spend before dispatch, and it stops it at one grant’s ceiling. It cannot say that the ceiling will be reached at ten tonight, or that three sibling workers, each well inside its own limit, are together spending at three times the rate anyone intended. The comptroller console answers those questions while money is moving. Every number it reports is a projection of receipts the kernel already signed, computed in integer arithmetic over a range the reader can prove complete, so an auditor can recompute it and arrive at the same bytes.

Its outputs are evidence. Detectors and webhooks never revoke, clamp, or deny; the grant, its guards, and its budget remain the authority before each call. A window the console cannot prove complete produces a signed chio.spend.incomplete-corpus.v1 record and no number at all.

A burn-rate projection is integer arithmetic a verifier can redo

The projection names one budget authority and a trailing window W. It sums the cost charged in the window and divides the remaining budget by that rate, with integer division, and it reports null when the window holds no spend.

Burn rateDrag t along the day.

spend in window: USD 6.00
budget remaining: USD 7.80
time to exhaustion: 5 h 12 min
crossings fired: 50%

\begin{aligned} T_{\mathrm{exhaust}} &= \left\lfloor \frac{B_{\mathrm{remaining}} \cdot W}{S_W} \right\rfloor \\[6pt] S_W &= \textstyle\sum_{\rho \,\in\, [t-W,\, t)} \mathrm{cost}(\rho) \end{aligned}

Three siblings together run past the bound

Each triage worker stays under its own ceiling of 30 calls an hour, so no single grant trips the velocity guard. Under one lineage root they run 84 calls an hour against a declared bound of 60, and the detector signs a chio.spend.anomaly-finding.v1 over the window 13:00 to 17:00.

Each crossing fired once, as a signed chio.spend.budget-threshold-crossing.v1 webhook: 50 percent at 15:47.

One budget authority of USD 20.00 over one day, a four-hour trailing window, the integer burn-rate projection, the threshold crossings that fire webhooks, and one velocity-clustering finding. The spend series is illustrative; delegation amplification and spend-pattern drift are left out.

The fixer’s grant for issues #417 to #419 holds USD 20.00 for the day. When three triage workers start at 14:00 the slope triples, and by 17:00 the projection reaches the budget at 22:12. The same request from the command line returns the signed projection:

Terminalbash

chio --control-url https://kernel.larkfield.example spend burn-rate \
  --capability cap-01d2…6c13 --window 4h

Output

authority    cap-01d2…6c13, grant 0, USD 20.00
window       13:00 to 17:00, checkpoint 44, time-index range proof verified
spend        USD 6.00 in window, USD 12.20 total, USD 7.80 remaining
exhaustion   18720 s, at 22:12
projection   chio.spend.burn-rate-projection.v1, signed

The signed chio.spend.burn-rate-projection.v1 carries the window bounds, its inputs, the checkpoint, and a range proof over the tenant’s time index, so a verifier recomputes 7.80 × 14,400 ÷ 6.00 = 18,720 seconds exactly. A window that spans currencies returns a total per currency and a null combined total unless oracle conversion evidence is attached.

The spend stream is a projection of signed receipts

Each event copies one receipt’s financial metadata, with its receipt id, content hash, tool, timestamp, and sequence number. An event is bound to its receipt by digest and carries no signature of its own:

spend.tsspend.pysrc/main.rs · in mainTerminal

for await (const event of project.spend.stream({ capability: "cap-01d2…6c13" })) {
  console.log(event.summary);
}

Output

seq 4308  15:46  triage-418  models  USD 0.02   remaining USD 10.04 of USD 20.00
seq 4309  15:46  triage-419  models  USD 0.02   remaining USD 10.02 of USD 20.00
seq 4310  15:47  triage-417  models  USD 0.02   remaining USD 10.00 of USD 20.00
cursor    9c1d…77ae, complete through seq 4310, checkpoint 43

for event in project.spend.stream(capability="cap-01d2…6c13"):
    print(event.summary)

Output

seq 4308  15:46  triage-418  models  USD 0.02   remaining USD 10.04 of USD 20.00
seq 4309  15:46  triage-419  models  USD 0.02   remaining USD 10.02 of USD 20.00
seq 4310  15:47  triage-417  models  USD 0.02   remaining USD 10.00 of USD 20.00
cursor    9c1d…77ae, complete through seq 4310, checkpoint 43

let mut events = project.spend().stream().capability("cap-01d2…6c13");
while let Some(event) = events.next().await {
    println!("{}", event?.summary());
}

Output

seq 4308  15:46  triage-418  models  USD 0.02   remaining USD 10.04 of USD 20.00
seq 4309  15:46  triage-419  models  USD 0.02   remaining USD 10.02 of USD 20.00
seq 4310  15:47  triage-417  models  USD 0.02   remaining USD 10.00 of USD 20.00
cursor    9c1d…77ae, complete through seq 4310, checkpoint 43

chio --control-url https://kernel.larkfield.example spend stream --capability cap-01d2…6c13

Output

seq 4308  15:46  triage-418  models  USD 0.02   remaining USD 10.04 of USD 20.00
seq 4309  15:46  triage-419  models  USD 0.02   remaining USD 10.02 of USD 20.00
seq 4310  15:47  triage-417  models  USD 0.02   remaining USD 10.00 of USD 20.00
cursor    9c1d…77ae, complete through seq 4310, checkpoint 43

The stream is served at GET /v1/spend/stream as long-poll or Server-Sent Events. Its cursor is opaque and authenticated: it binds your tenant, the filter, the last sequence scanned, and the store generation. Each batch reports the sequences it scanned and how far the stream is complete, under a signed stream checkpoint, and a cursor that is stale or from another tenant gets a typed gap with the earliest sequence still available, never a silent jump forward.

Thresholds fire once per budget authority

A webhook fires when spend under one verified budget authority crosses 50, 80, 95, or 100 percent of its max_total_cost. Registration takes a secret reference and a URL that the operator’s egress policy must allow:

Terminalbash

chio --control-url https://kernel.larkfield.example spend webhook add \
  --url https://siem.larkfield.example/chio/spend --secret-ref credential:spend-webhook \
  --capability cap-01d2…6c13

Output

webhook     wh-01e2…3c90, thresholds 50, 80, 95, 100 percent of max_total_cost
authority   cap-01d2…6c13, grant 0, USD 20.00, digest 71aa…0c3f
egress      siem.larkfield.example:443, path /chio/spend, redirects denied

Each crossing is a signed chio.spend.budget-threshold-crossing.v1 with an id derived from the authority, the threshold, and the first receipt that crossed it. Delivery is at least once, so receivers deduplicate on that id; a crossing does not re-arm when spend falls back, and only a newly signed budget authority starts a new set.

POST /chio/spend · the 50 percent crossing at 15:47json

{
  "schema": "chio.spend.budget-threshold-crossing.v1",
  "crossing_id": "b4e0…92d1",
  "capability_id": "cap-01d2…6c13",
  "grant_index": 0,
  "budget_authority_digest": "71aa…0c3f",
  "currency": "USD",
  "threshold_bps": 5000,
  "first_crossing_seq": 4310,
  "prior_state": "below",
  "current_state": "crossed"
}

Anomaly findings are signed and recomputable

Three detectors read a complete window. Delegation amplification compares a child subtree’s spend with its parent’s in basis points. Spend-pattern drift compares the mean cost per call for one subject and tool against a trailing baseline. Velocity clustering sums sibling grants under one lineage root and flags an aggregate rate above a declared multiple of the per-grant ceiling:

Terminalbash

chio --control-url https://kernel.larkfield.example spend anomalies export \
  --since 12:00 --output ./findings.json

Output

finding    velocity clustering under lineage root cap-01d2…6c13
statistic  84 calls per hour across 3 sibling grants, declared bound 60
window     13:00 to 17:00, 252 evidence receipts, checkpoint 44
id         5e7a…c2f8, chio.spend.anomaly-finding.v1, signed
wrote      ./findings.json

A finding’s id is the SHA-256 of its unsigned body, which includes the detector’s configuration digest, so the same evidence under a different threshold is a different finding. Severity is derived from that configuration and the statistic, never supplied. Findings feed underwriting only through an active, signed anomaly-evidence policy, and the default policy accepts none.

The surface report reads exposure beside decisions

chio.comptroller.surface-report.v1 joins the operator report and the credit exposure ledger: decision counts, settlement reconciliation, budget utilization, and one exposure position per currency. chio trust serve serves it to an administrator at /v1/reports/comptroller-surface:

Terminalbash

curl -s -H "Authorization: Bearer $CHIO_CONTROL_TOKEN" \
  "https://kernel.larkfield.example/v1/reports/comptroller-surface?capabilityId=cap-01d2…6c13" \
  | jq '{schema, decisionSummary, exposurePositions}'

Output

{
  "schema": "chio.comptroller.surface-report.v1",
  "decisionSummary": { "allowCount": 1219, "denyCount": 7, "cancelledCount": 0, "incompleteCount": 1 },
  "exposurePositions": [
    {
      "currency": "USD",
      "governedMaxExposureUnits": 250000,
      "reservedUnits": 4000,
      "settledUnits": 61200,
      "pendingUnits": 1500,
      "failedUnits": 0,
      "provisionalLossUnits": 0,
      "recoveredUnits": 0,
      "quotedPremiumUnits": 0,
      "activeQuotedPremiumUnits": 0
    }
  ]
}

The route fails closed on an inconsistent position: reserved plus pending exposure may not overflow or pass the governed ceiling, where a ceiling of 0 means none is governed. The HTTP body is unsigned, and the control plane can sign the same report as a SignedExportEnvelope. Operator Reports covers its query parameters and coverage fields.

Next: stress the economy before it runs

Economic Wind TunnelReplay seeded attacks against the validators that hold the money.Risk ReportsRead the signed risk artifact underwriting consumes.

PreviousMoney Conservation NextEconomic Wind Tunnel