Operator Reports
Trace budget exposure, settlement work, and evidence readiness from a report back to the receipts and coverage behind it.
On this page
An operator can answer questions that span many receipts: which delegation consumed a budget, which settlements still need attention, how authorization was represented, and which evidence is ready for review.
The combined operator report composes eight read models into one response, and focused endpoints return each part alone. Reports admit only the admin principal, the service token the trust control plane is started with; a tenant read token is refused here and uses the scoped receipt query and export paths in Tenancy & Read Scoping.
One node composes eight parts
The builder queries the eight parts in sequence from the responding node’s stores and returns them as one unsigned OperatorReport. A failed subquery fails the whole response, and generatedAt stamps the composition without making it one transaction across the receipt and budget databases. Operator reports.
GET /v1/reports/operator: each row is a part of the response, and each dot a store that part reads. The focused endpoints, the comptroller and exposure projections, and the row limits are left out.A report answers from the responding node's local state
Report handlers build each view from the store state of the node that receives the request. Report reads are never forwarded to the leader, and no report is a fleet-wide snapshot.
Three things move the answer from node to node: how far receipt replication has reached, the reconciliation annotations written on that node, and its current budget state. Record the node, the filters, and generatedAt with every report you compare.
Read more in Replication & Convergence.
Eleven endpoints, each for one question
The core reporting routes sit under GET /v1/reports/; the names below are relative to that prefix. Credit, capital, and liability operations add reports of their own in Economy.
| Endpoint | Answers | Response |
|---|---|---|
operator | Activity, spend, evidence, and reconciliation together | Unsigned; receipt and budget stores |
comptroller-surface | Decisions, budgets, settlements, and credit exposure | Unsigned, schema-bound; anchor required |
cost-attribution | Recorded cost across a delegation chain | Unsigned summary and receipt detail |
settlements | Pending or failed settlements needing action | Unsigned backlog |
metered-billing | Metered calls missing evidence or mismatched | Unsigned reconciliation |
economic-receipts | Economic metadata on selected receipts | Unsigned projection |
economic-completion-flow | Receipts joined to underwriting and credit | Unsigned; anchored query |
exposure-ledger | Per-currency exposure and its decisions | Signed envelope; anchor and key |
behavioral-feed | Activity an operator shares with a risk reviewer | Signed envelope |
authorization-context | Authorization details in the receipts | Unsigned projection |
authorization-review-pack | What an IAM reviewer inspects together | Unsigned reviewer pack |
A signature on the envelope, a registered schema, and evidence of the execution are three separate properties. The HTTP comptroller surface carries a registered schema and returns an unsigned body; the behavioral feed adds selection and privacy metadata and an optional subject reputation section.
A bounded request names its anchor and its limits
Set CONTROL_URL, CONTROL_TOKEN to the admin service token, and TOOL_SERVER to the server you want to inspect (pricing for the quote service), on a service with receipt and budget storage configured.
curl --fail-with-body --silent --show-error --get \
"$CONTROL_URL/v1/reports/operator" \
--header "Authorization: Bearer $CONTROL_TOKEN" \
--data-urlencode "toolServer=$TOOL_SERVER" \
--data-urlencode "groupLimit=20" \
--data-urlencode "attributionLimit=20"Query names are camelCase: capabilityId, agentSubject, toolServer, toolName, since, and until, with times in Unix seconds. Read generatedAt, the echoed filters, and each part's coverage and truncation fields before using a number. For the comptroller projection of the same server, change the endpoint to /v1/reports/comptroller-surface and keep the tool-server anchor.
Budget totals count holds before spend is realized
In budgetUtilization, totalCostCharged is the store's committed cost: outstanding exposed cost plus realized spend. A hold raises it before any amount is realized, and remainingCostUnits subtracts it from the grant limit, saturating at zero.
A row is exhausted when usage reaches a configured limit and nearLimit at 80% utilization in either dimension, or when exhausted. These are report thresholds; the spending authority itself is in Budgets Across Nodes. Budget usage is current state, so since and until move the activity numbers and leave the budget totals alone. The budget summary adds unit counts across rows without currency conversion, so read each row's currency first.
Missing lineage and filters on budget rows
The builder resolves a budget row's grant and subject through capability lineage. Missing lineage or an invalid grant projection leaves scopeResolved: false with a resolution error. Tool filters exclude rows whose tool scope cannot be resolved; an agent filter excludes rows whose lineage subject is absent or different, and a known subject can still have an invalid grant projection. The missing-scope counters are computed after these filters, so remove a filter when rows disappear from the report.
Two reports arrive signed, and you choose the signer to trust
exposure-ledger and behavioral-feed return envelopes of body, signer_key, and signature, where the signature covers canonical JSON of the body. Configure exactly one signing source: --authority-seed-file or --authority-db.
On the --authority-db path the report key is the locally stored keypair, which after an authority rotation can differ from the cluster's advertised authority. The envelope helper verifies against the embedded key, so pin the key you expect and compare. A valid signature binds the body to that key; the counts and selected records inside remain report output, with receipts as their evidence.
Signing and schema details
Report signing skips the current-authority check that fences capability signing after replicated authority changes. The seed-file loader creates key material when the file is absent, so provision the intended key before requesting signed reports. The behavioral feed anchors its reputation trust set on the signing public key and builds its optional reputation section when an agent subject is selected.
The comptroller surface has a registered JSON Schema and a library signing helper; its HTTP handler returns the unsigned projection. Other report schema strings are identifiers in their Rust contracts, registered only where Schemas & Errors lists them.
Report parts, limits, and checks
Try proofsComplete, groupLimit, retry_scheduled, or 409.
Operator response parts
activity: matching decision counts, recorded cost, and derived ratios, with bounded agent, tool, and time groupings.costAttribution: root and leaf delegation attribution and per-receipt chains;lineageCompletemarks a chain that could not be fully resolved.budgetUtilization: current per-grant usage from the budget store, joined to capability scope in the receipt store.compliance: checkpoint-range counts, stored-lineage presence, and export-scope metadata.settlementReconciliation: pending and failed settlement records joined to local operator annotations.meteredBillingReconciliation: missing metered evidence and quoted-unit, billed-unit, quoted-cost, or financial mismatches.authorizationContext: the authorization-details and transaction-context projection over receipt metadata.sharedEvidence: evidence-share references and their matching local receipts.
The builder queries the parts in sequence and returns the composition after all succeed; a subquery failure fails the combined response. generatedAt is not a transaction boundary across these reads or across the receipt and budget databases, so use a focused endpoint for one part on its own.
Query limits
| Field | Default | Controls |
|---|---|---|
groupLimit | 50 | Activity groupings and shared-evidence rows |
attribution | 100 | Cost- |
budgetLimit | 50 | Budget utilization rows |
settlementLimit | 50 | Settlement backlog rows |
meteredLimit | 50 | Metered-billing detail |
authorization | 50 | Authorization-context detail |
economicLimit | 50 | The separate economic- |
Limits clamp to 1 to 200, so a larger value returns at most 200 rows. Reports carry no continuation cursor: narrow the filters when detail is truncated. Time windows trim receipt detail and leave current budget rows whole.
Budget, attribution, reconciliation, authorization, and shared-evidence summaries expose matching counts and a truncation flag. Activity's summary covers every matching row while its groupings are bounded and carry no flag, and compliance aggregates the matching set with no row limit. Returned detail rows can therefore sum to less than the summary beside them.
Comptroller surface
The comptroller surface combines the operator response with an exposure-ledger read model. Its chio.comptroller.surface-report.v1 body carries credit exposure positions beside decision counts, settlement reconciliation, and budget utilization, each with its own units and selection rules.
Supply at least one of capabilityId, agentSubject, or toolServer; a bare request fails exposure validation with 400 once its stores are available. toolName requires toolServer, filter values must be nonempty and unpadded, and since must not exceed until.
The exposure half selects 100 receipts and 50 underwriting decisions by default, and the operator query exposes no control for either. The projection copies the positions and drops the exposure summary with its truncation flags, while decision counts come from activity's full matching set; read the standalone exposure ledger when selection completeness matters. For each currency position with a nonzero governed ceiling, validation adds reserved and pending units with checked addition and refuses an overflow or a sum above the ceiling; a zero ceiling skips the check, which compares credit units only.
Exposure ledger and settlement queue
The exposure ledger accumulates selected receipt amounts and underwriting premiums into positions by currency, with no cross-currency netting. Its summary reports matching and returned counts, separate receipt and decision truncation flags, and whether several currencies appear; positions describe the selected rows, so a truncated selection is a partial book. The receipt selection applies the time window, the underwriting query copies the capability, agent, and tool filters without since or until, and the declared support boundary excludes claim adjudication and a recovery lifecycle.
The settlement report is a work queue over receipts whose signed financial status is pending or failed. A local annotation decides whether a row still needs action: open (also the default with no annotation) and retry_scheduled keep it in the queue, and reconciled and ignored close it.
The settlement and metered-billing reconciliation endpoints write local sidecar tables on the node that handles them, without leader forwarding, and replication carries neither table, so direct a workflow to one node and read that node's report. An annotation leaves the receipt's signed settlement status as signed; Reconciliation handles the underlying obligation.
Checkpoint coverage counts
The compliance part reports evidenceReadyReceipts, uncheckpointedReceipts, and the derived proofsComplete flag as summary counts over the receipt store. Checkpoint batch ranges index the combined tool-and-child claim log, and a tool receipt's sequence in that log is resolved only when an evidence export selects it.
The export collector resolves each selected tool receipt by id to its combined-log position, then builds its inclusion proof. Gate admission or publication on the export's verified proofs and its uncheckpointed list, and read proofsComplete as an indicator of checkpoint coverage. Receipt Aggregation explains the checkpoint chain; Evidence Export explains the package.
Evidence classes in projections
Authorization-context reports and reviewer packs keep asserted, observed, and verified call-chain evidence apart, so an asserted upstream statement stays asserted beside signed local metadata. The compliance lineage count records whether a stored lineage row exists; each delegation statement is verified on its own.
Tool filters narrow the operator report, while direct evidence export scopes by capability, agent, time, and read boundary. With tool filters set, directEvidenceExportSupported is false and the export-scope note names the mismatch; child-receipt scope is read separately.
Trust-market-context verifier
The trust-market-context verifier checks the artifacts in a supplied transaction bundle. Its policy contract refuses required claims that Chio operated a permissionless marketplace, global trust score, liquidity pool, risk syndication, underwriter market, autonomous guarantee sale, or slashing court, and the policy discloses a nonempty subset of those recognized claims with no unknown additions. These are verifier-contract rules, separate from fetching a report; Risk Comptroller Reports covers the signed risk artifact.
Refused report requests
| Response | Condition | Fix |
|---|---|---|
401 | Missing or wrong bearer token | Supply the admin service token |
403 | Admin receipt read authority required | Use the admin service token; tenants use scoped queries |
409 | Receipt or budget store required | Configure both for operator and comptroller |
400 | Exposure anchor or query invalid | Add an anchor; pair toolName with toolServer |
500 | Signing material unavailable | Configure exactly one key source |
500 | Comptroller consistency check failed | Inspect the position, ceiling, and reserved plus pending sum |
500 | Store or subreport failure | Read the cause and the node's storage state |
The combined builder returns the whole report or an error, never a partial success.
Comparing reports
Keep the responding node and the filters with every report. Check row caps, time-window differences, unresolved budget scope, currency units, local annotations, and the intended signer before comparing totals, and verify exported evidence for any claim about receipt inclusion.
Source files
crates/platform/chio-control-plane/src/trust_control/reports.rs: composition and exposure selection.crates/platform/chio-control-plane/src/trust_control/underwriting_and_support/policy_support.rs: budget interpretation and local signing-key selection.crates/kernel/chio-kernel/src/operator_report/queries.rsandoperator_report/comptroller_surface.rs: limits, projection, and consistency checks, with the comptroller consistency tests.crates/platform/chio-store-sqlite/src/receipt_store/reports/compliance.rsandcrates/platform/chio-store-sqlite/src/evidence_export.rs: the compliance summary and the export's claim-log mapping.