Operator Reports

Read models, composed per request, over one node’s disk

A Chio report is not a stored document. Every route on this page opens the node’s local SQLite receipt store, and sometimes its local budget store, runs a fixed set of queries, and returns the result. There is no cache, no cursor, no materialized view, and no report table. Two consecutive requests against the same node can differ, because the second one recomposes from whatever the last replication round left on disk.

None of these routes forwards to the leader. handle_operator_report, handle_comptroller_surface_report, handle_cost_attribution_report, handle_settlement_report, and handle_exposure_ledger_report each resolve a read principal, open a store, and answer locally. That is the published class, not an oversight: docs/standards/CHIO_BOUNDED_OPERATIONAL_PROFILE.md rates trust-control reads leader-local, shipped as "bounded clustered visibility over local SQLite-backed state", with "no globally linearizable control-plane view" as the explicit non-claim. A report from node B and a report from node C over the same filters are two observations, not one truth.

The status is registered. docs/standards/CHIO_OPERATOR_CONTROL_SURFACE_PROFILE.json carries status: operator_control_surfaces_qualified_locally and names six entries: operator-report, settlement-reconciliation, metered-billing-reconciliation, authorization-context, underwriting-credit-capital-liability, and comptroller-surface. Its own constraints block says what that does and does not mean: the profile proves the routes are "defined and exercised locally", it "does not prove independent third-party operator adoption", and promotion outside the operator boundary "still requires qualification bundles and explicit service-auth governance".

The report families

Eleven GET routes under /v1/reports/ are in scope here. They divide cleanly on two axes that matter more than their names: does the response carry a schema id, and does it carry a signature.

Seven of the eleven have no CLI path at all. The trust-control client does carry operator_report, comptroller_surface, and cost_attribution_report methods, and all three are marked #[allow(dead_code)] under an in-tree comment saying they are "kept for API parity with the trust-control service surface even though the current CLI command set does not invoke it directly". Reach those three over HTTP with a bearer token; there is no chio subcommand to reach for.

What /v1/reports/operator composes

build_operator_report runs eight read models in a fixed order and packs them into one struct with a generated_at stamp and an echo of the filters. Every one of the eight maps its own store error to 500, so a single failing sub-query fails the whole report and the response body is the store error string.

let activity = receipt_store
    .query_receipt_analytics(&query.to_receipt_analytics_query())
    .map_err(|error| plain_http_error(StatusCode::INTERNAL_SERVER_ERROR, &error.to_string()))?;
let cost_attribution = receipt_store
    .query_cost_attribution_report(&query.to_cost_attribution_query())
    .map_err(|error| plain_http_error(StatusCode::INTERNAL_SERVER_ERROR, &error.to_string()))?;
let budget_utilization = build_budget_utilization_report(receipt_store, budget_store, query)?;
let compliance = receipt_store.query_compliance_report(query)...;
let settlement_reconciliation = receipt_store.query_settlement_reconciliation_report(query)...;
let metered_billing_reconciliation = receipt_store.query_metered_billing_reconciliation_report(query)...;
let authorization_context = receipt_store.query_authorization_context_report(query)...;
let shared_evidence = receipt_store.query_shared_evidence_report(&query.to_shared_evidence_query())...;

The budget half reads a different store, and a different number

build_budget_utilization_report lists usages from the budget store, then resolves each row’s capability scope by reading get_lineage out of the receipt store and parsing grants_json. That is where toolServer, toolName, maxInvocations, maxTotalCostUnits, and currency come from. A budget row whose lineage snapshot is absent still appears, with scopeResolved: false and scopeResolutionError set to capability lineage snapshot not found for budget row, and it is counted in both rowsMissingLineage and rowsMissingScope.

Read the tool filters against that ordering. A row whose scope did not resolve has no tool_server, so a request that passes toolServer drops it silently rather than reporting it as unresolved. Both counters are incremented after the three continue guards, so a toolServer, toolName, or agentSubject filter removes every unresolved row before it can be counted. A capabilityId filter does not: it is applied by list_usages and drops nothing on scope grounds. since and until are never read by this half at all, so a time window narrows the receipt-side numbers next to it and leaves the budget rows untouched.

Every part is capped, and most caps report themselves

OperatorReportQuery carries a group limit and six row limits, each with a default and each clamped into 1..=200 before it reaches SQL. Five clamp in an _or_default accessor on the query itself. groupLimit and attributionLimit are passed through raw and clamped inside the store query that consumes them. The clamp is silent: asking for 5,000 rows returns 200 and no warning.

Most halves report their own truncation. budgetUtilization, costAttribution, settlementReconciliation, meteredBillingReconciliation, authorizationContext, and sharedEvidence each carry a matching* count computed without the limit and a truncated boolean, and every one of them but sharedEvidence also carries a returned* count. Two halves do not. activity is a ReceiptAnalyticsResponse, whose only fields are summary, byAgent, byTool, and byTime, so the three groupings are cut at groupLimit with nothing in the body saying they were. compliance carries matchingReceipts and neither a returned count nor a flag, because it aggregates the whole matching set under no row limit at all. Where the boolean exists, alert on it rather than on the row count, and remember there is no cursor: a truncated report has no page two. Narrow the filters or the time window instead.

One field on the query is never accepted from a caller. read_context is #[serde(skip)] on OperatorReportQuery, BehavioralFeedQuery, SharedEvidenceQuery, and CostAttributionQuery, under a doc comment on each that reads "auth-derived read authority. This is never accepted from request bodies." The handler overwrites it from the resolved principal before the store is opened.

The comptroller-surface projection, and the anchor it demands

/v1/reports/comptroller-surface is a pure projection over two read models it does not own. It builds a full OperatorReport, builds an ExposureLedgerReport against the same principal, and keeps five projected fields: exposurePositions from the credit half, and decisionSummary, settlementReconciliation, budgetUtilization, and filters from the operator half. A sixth field is declared and never filled. from_parts sets source_refs to ComptrollerSurfaceSourceRefs::default(), and nothing in the workspace ever populates operatorReportRef, exposureLedgerRef, or riskComptrollerReportRef, so every response carries sourceRefs: {}. The schema reserves three digest slots binding the projection back to the read models it projects, and the projection fills none of them. Two further fields, executionNonceRef and holdRef, are reserved and omitted from JSON entirely until a later schema revision; test_comptroller_surface_report_endpoint asserts their absence.

The projection validates itself before it is returned, and the check is fail-closed on overflow rather than saturating.

pub fn validate_consistency(&self) -> Result<(), String> {
    for position in &self.exposure_positions {
        if position.governed_max_exposure_units == 0 {
            continue;
        }
        let Some(outstanding) = position.reserved_units.checked_add(position.pending_units)
        else {
            return Err(format!(
                "exposure position {} outstanding holds overflow u64 (reserved {} + pending {})",
                position.currency, position.reserved_units, position.pending_units
            ));
        };
        if outstanding > position.governed_max_exposure_units {
            return Err(format!(
                "exposure position {} outstanding holds {} exceed governed ceiling {}",
                position.currency, outstanding, position.governed_max_exposure_units
            ));
        }
    }
    Ok(())
}

Read the exemptions. A governed ceiling of zero means "no governed ceiling" and is skipped, so a currency position with no governed maximum never fails this check no matter how large its holds are. The module comment states the other boundary outright: this is a credit-domain check only, and it deliberately does not compare against kernel budget cost units, "whose unit mapping to exposure units is undefined". The report carries both numbers side by side and asserts no relationship between them. A failed check is a 500 with comptroller surface consistency check failed: prefixed onto the message.

The two halves are also computed over different windows. to_exposure_ledger_query sets receipt_limit: None and decision_limit: None, which default to 100 receipts and 50 decisions, and no query field on the operator query can raise them. The decision counts, meanwhile, come from operator.activity.summary, which is aggregated over every matching receipt with no limit at all. ComptrollerSurfaceReport::from_parts then copies exposure.positions and drops exposure.summary, so the exposure half’s own truncatedReceipts and truncatedDecisions flags never reach the response. Positions computed over the first 100 matching receipts sit next to decision counts computed over all of them, and nothing in the body says so.

Exposure, settlement, and the sidecar that does not replicate

/v1/reports/exposure-ledger accumulates per-currency positions across nine counters (governedMaxExposureUnits, reservedUnits, settledUnits, pendingUnits, failedUnits, provisionalLossUnits, recoveredUnits, quotedPremiumUnits, activeQuotedPremiumUnits) and pairs them with underwriting decision entries. Its summary carries mixedCurrencyBook, true whenever more than one currency appears, and its supportBoundary block is a constant: governed receipts, underwriting decisions, and settlement reconciliation are marked authoritative; cross-currency netting, claim adjudication, and recovery lifecycle are marked unsupported. Positions in different currencies are never summed.

/v1/reports/settlements is a backlog, not a ledger. Its SQL filters json_extract(r.raw_json, '$.metadata.financial.settlement_status') IN ('pending', 'failed'), so a receipt that settled cleanly never appears. Each row left-joins a mutable sidecar table, settlement_reconciliations, keyed by receipt_id and defaulting to open. The derived actionRequired flag is the conjunction: the signed status is pending or failed and the operator has not set the sidecar to reconciled or ignored. The four sidecar states are open, reconciled, ignored, and retry_scheduled, and retry_scheduled still counts as actionable.

The signed half of the row is unaffected by any of this. The receipt carries financial.settlement_status inside its signature and that value replicates with the receipt; only the operator’s annotation is local. Same shape on the metered side: POST /v1/metered-billing/reconcile writes evidence and a state into a local sidecar, and /v1/reports/metered-billing reads it back on that node only. The economics of the underlying obligation belong to Reconciliation.

Which reports are signed, by which key, and what that proves

Two of the eleven routes sign. /v1/reports/exposure-ledger wraps its body in SignedExposureLedgerReport and /v1/reports/behavioral-feed in SignedBehavioralFeed. Both are SignedExportEnvelope<T>: three fields, body, signer_key, and signature, with the signature taken over the canonical JSON of the body.

The key comes from load_behavioral_feed_signing_keypair, which takes exactly one of --authority-seed-file or --authority-db. Passing both is an error reading behavioral feed export requires either --authority-seed-file or --authority-db, not both; passing neither is an error reading ... so the export can be signed. On the seed path it loads or creates a keypair from the file. On the database path it calls SqliteCapabilityAuthority::local_keypair.

pub fn current_keypair(&self) -> Result<Keypair, AuthorityStoreError> {
    self.read_current_keypair()
}

pub fn local_keypair(&self) -> Result<Keypair, AuthorityStoreError> {
    let connection = Self::open_connection(&self.path)?;
    Self::read_keypair_from_connection(&connection)
}

Read the verification helper narrowly too. SignedExportEnvelope::verify_signature verifies the signature against the signer_key carried inside the same envelope. It proves the body was not edited after signing. It proves nothing about who signed, because the claimed signer travels with the claim. A consumer that cares must pin the expected public key out of band and compare it. That is the same discipline the signed-report builders already apply internally: both the behavioral feed and the credit scorecard load the keypair first and seed the reputation trust set from its public key, with a comment noting that chio-reputation::receipt_integrity_valid fails closed on an empty set.

There is a third signed report in the tree with no way to ask for it. build_signed_comptroller_surface_report exists, revalidates consistency, and produces a SignedComptrollerSurfaceReport. Its only caller in the workspace is its own unit test, signed_comptroller_surface_report_verifies_and_is_canonical. No route returns it and no CLI verb produces it. The HTTP route returns the unsigned ComptrollerSurfaceReport.

Read authority and denial behavior

Every route on this page resolves an admin read context before it opens anything. resolve_admin_report_read_context accepts only ResolvedControlReadPrincipal::AdminService and answers a tenant read token with 403 {surface} requires admin receipt read authority, where the string is the report’s own name. Which token produces which principal is Tenancy & Read Scoping.

A second, independent gate sits inside the store. A dozen report queries call the same helper before touching SQL, and it names the reason directly.

fn require_admin_receipt_read_context(
    context: Option<&ReceiptReadContext>,
    surface: &str,
) -> Result<(), ReceiptStoreError> {
    match context {
        Some(ReceiptReadContext { boundary: ReceiptReadBoundary::AdminAll, .. }) => Ok(()),
        Some(ReceiptReadContext { boundary: ReceiptReadBoundary::TenantScoped { .. }, .. }) =>
            Err(ReceiptStoreError::ReadBoundary(format!(
                "{surface} requires admin receipt read authority until tenant-scoped report filtering is implemented"
            ))),
        None => Err(ReceiptStoreError::ReadBoundary(format!(
            "{surface} requires an explicit receipt read context"
        ))),
    }
}

The refusal says why, and the why is worth reading: reports are admin-only because tenant-scoped report filtering does not exist, not because reporting is privileged by design. The handler gate fires first on every HTTP path, so this one is defense in depth rather than an observable behavior, and it is the gate that catches a library caller that forgot to set a context at all.

Informational-only: what a derived projection may not become

docs/standards/CHIO_BOUNDED_OPERATIONAL_PROFILE.md rates the authorization-context report and the reviewer pack informational-only, and neither response says so. The reviewer pack gets closer than the report does: it embeds a ChioOAuthAuthorizationMetadataReport whose supportBoundary block is twelve booleans, among them delegatedCallChainProjection, senderConstrainedProjection, and runtimeAssuranceProjection, plus a discovery.discoveryInformationalOnly flag. The authorization-context report carries no boundary block at all: its four fields are schema, profile, summary, and receipts. Both are given the same two columns in the profile. The shipped truth is "derived projection over signed receipt metadata". The explicit non-claim is that the projection "does not upgrade asserted call-chain fields into verified upstream truth". The same document states the rule in general form: no report or export surface may collapse asserted lineage into verified truth.

That rule is enforced, not just stated. delegated_call_chain_is_sender_bound returns false immediately whenever the call chain’s evidence_class is Asserted, before it inspects anything else, and a row that claims senderConstraint.delegatedCallChainBound without corroborated provenance is rejected as an invalid profile with senderConstraint.delegatedCallChainBound requires corroborated call-chain provenance. The summary counts the three classes separately, as assertedCallChainReceipts, observedCallChainReceipts, and verifiedCallChainReceipts, so a reviewer can see the split rather than a single total.

Two more scope notes ride along in the same report family, and both are text the report writes about itself. compliance.directEvidenceExportSupported is false whenever a tool filter is set, because EvidenceExportQuery can scope by capability, agent, and time window but not by tool. When that happens, exportScopeNote says so: tool filters narrow the operator report only; direct evidence export can scope by capability, agent, and time window. The child-receipt note has two forms, and EvidenceExportQuery::child_receipt_scope picks between them. A capability or agent scope carrying a time window reads time_window_context_only and notes that child receipts are included only as time-window context for this export scope. The same scope without a time window, and any tenant-filtered or tenant-scoped export, reads omitted_no_join_path with child receipts are omitted for this export scope because no capability/agent join exists yet. Outside those cases, a query with neither a subject nor a capability scope reads full_query_window and writes no note at all. What that means for a package you hand to someone else is Evidence Export.

The seven market claims a verifier policy may not require

One crate in this family verifies rather than reports. chio-trust-market-context checks the trust-market section of a transaction proof bundle: provider discovery, provider selection, trust scorecards, portable reputation imports, SLA commitments and performance, collateral, guarantees, adjudication jurisdiction, and the risk-comptroller report that binds them to reserves. Its README states its scope in one sentence: it "verifies a bundle after the fact and does not select providers, update reputation, enforce SLAs live, or authorize settlement".

Among its responsibilities is a refusal list. The crate enumerates seven market capabilities Chio does not implement, and rejects any verifier policy that requires one of them.

const BLOCKED_MARKET_CLAIMS: &[&str] = &[
    "claim.market.permissionless_provider_marketplace_operated",
    "claim.market.global_trust_score_published",
    "claim.market.liquidity_pool_operated",
    "claim.market.risk_syndication_operated",
    "claim.market.underwriter_market_operated",
    "claim.market.autonomous_guarantee_product_sold",
    "claim.market.slashing_court_operated",
];

In plain terms, Chio does not operate a permissionless provider marketplace, does not publish a global trust score, does not operate a liquidity pool, does not syndicate risk, does not run an underwriter market, does not sell autonomous guarantee products, and does not operate a slashing court. A verifier policy that lists any of these under required_claims is rejected before a single artifact is parsed, by reject_required_unsupported_market_claims, with unsupported market claim cannot be required: {claim}.

The check has a second direction that is easy to miss. validate_unsupported_claims requires the policy’s unsupported_claims list to be non-empty and to contain only entries from that same seven. An empty list fails with unsupported market claims missing; an entry outside the set fails with unknown unsupported market claim: {claim}. A policy must therefore disclose the refusals explicitly, and only then does the verifier record claim.trust_market.unsupported_market_claims_limited among its verified claims. Silence about what is not supported is itself a verification failure. The report format the verifier binds to is Risk Comptroller Reports.

Guarantees and limits

Next Steps

• Receipt Aggregation · what converges into the store these reports read, and the checkpoint plane that does not
• Tenancy & Read Scoping · the two bearer tokens, and why only one of them can ask for a report
• Budgets Across Nodes · what committed cost means once several nodes are writing to the same grant
• Evidence Export · the digest-bound package a report cannot substitute for
• Risk Comptroller Reports · the verifier on the other side of the boundary, and the report it binds to a proof bundle