Approval Store & Channels

The half that remembers

An approval store answers two questions for one process: what is still outstanding, and what has already been spent. Both are answerable by reading one node’s own filesystem, which is what files them here rather than a rung up. Nothing on this page contacts a peer. Running two nodes is precisely where the single-use guarantee stops holding, and that limit is stated below rather than papered over.

The contract is ApprovalStore in crates/kernel/chio-kernel/src/approval.rs, deliberately synchronous because the kernel does not run on an async executor and both implementations (an in-memory reference and SqliteApprovalStore) are synchronous too. The store is real and durable. Be exact about what drives it.

• The guard is test-only. ApprovalGuard is constructed in one file, chio-kernel/src/kernel/tests/approval_flow.rs; everywhere else it is a re-export in lib.rs. The seven-guard pipeline does not stand in for it either: kernel/dispatch.rs treats a Guard that returns PendingApproval as an unsupported state and fails closed.
• The sidecar writes rows over HTTP. POST /approvals/submit takes operator-supplied context, materializes an ApprovalRequest with governed_intent: None and a default policy_id of policy-hermes-hitl, and names the sidecar’s own signing key as the sole entry in trusted_approvers. Its doc comment states the boundary: manual flow only, the held call is not auto-resumed. Resolving records a decision; it does not release anything.
• The kernel’s own pending path skips this store. Verdict::PendingApproval is raised by budget admission when a grant’s cumulative-approval requirement trips with no token attached. It signs a ThresholdApprovalProposal, parks it on the durable admission operation, and returns a Deny receipt reading cumulative approval required. No chio_hitl_pending row is written on that path.

Five tables, two stores

SqliteApprovalStore creates every table below on open, all with CREATE TABLE IF NOT EXISTS, alongside the shared chio_store_schema_versions row it stamps. One type implements two traits against them: ApprovalStore for the first three, ThresholdApprovalCollectorStore for the last two.

Batch approvals are a second store type entirely. SqliteBatchApprovalStore takes its own path and holds one table, chio_hitl_batches, indexed on (subject_id, revoked). No shipped binary opens it.

Both are own-file stores in the sense Node State on Disk defines: they take a path, open it directly, and never join the serving-owner arrangement the authority database uses. The schema gate is the shared one, under the store key approval at revision 2 and batch_approval at revision 0. What is specific here is the anchor set. A standalone open accepts exactly one anchor, chio_hitl_pending, so a path mistargeted at a receipt, revocation, budget, or authority database is refused rather than written with HITL tables. open_colocated_with_receipt_store widens the set with three receipt anchors, because chio api protect keeps both stores in one file and opens the receipt store first, so the approval store meets a database already carrying somebody else’s anchor and no approval table yet. The pair is pinned by standalone_open_refuses_a_receipt_sidecar_that_colocated_open_adopts.

Pending row to resolved row

Writing the request

store_pending is idempotent on approval_id, but only for a byte-identical payload. The whole rule is one statement:

INSERT INTO chio_hitl_pending (...) VALUES (?1, ..., ?9)
ON CONFLICT(approval_id) DO UPDATE SET payload = excluded.payload
  WHERE chio_hitl_pending.payload = excluded.payload
RETURNING payload

A retry carrying the same request updates a row to itself and returns it. A retry carrying a different one fails the WHERE, so the update is skipped, RETURNING yields nothing, and the call reports approval_id ... already exists with different payload rather than overwriting in-flight HITL state. The in-memory store reaches the same outcome with an equality compare before insert. Two things about that refusal are worth knowing. It is an ApprovalStoreError::Backend, not a typed conflict, so a duplicate /approvals/submit comes back as 500 internal_error. And the comparison is on the serialized string, not on JSON semantics, so a payload that changes shape across a binary upgrade reads as a conflicting retry rather than a matching one.

Leaving the process

A channel is a delivery sink, and the trait is two methods: name and dispatch. Two implementations exist in-tree and neither has a caller outside tests, because the only code that dispatches channels is ApprovalGuard::evaluate. In the shipped sidecar, notification is poll-only: GET /approvals/pending is the whole delivery mechanism, and it returns every matching row unless the caller passes a limit.

WebhookChannel is a blocking ureq POST with a 5s default timeout and one optional static header, deliberately one because every real caller uses a single auth secret. Being static it cannot be a per-body HMAC, whatever the doc comment suggests, and the channel retries nothing even though the trait says implementations own retries. Its body is { event, approval, callback_url } with event fixed at approval_requested, approval the entire serialized request including its trusted approver keys, and callback_url a host-less relative path. RecordingChannel appends every dispatch to an unbounded in-memory vector; its doc comment attributes it to an api-poll dispatch mode that does not exist in the tree.

Where the guard does run, dispatch failure is not a refusal. It iterates channels sequentially, logs a redacted warning on Transport, Remote, or Config, and leaves the pending row in place so the poll route still serves it. A webhook outage delays a call; it does not drop or allow one.

The resolve transaction

resolve is one SQLite transaction doing six things in a fixed order: read the pending row’s policy_id and parameter_hash inside the transaction to avoid a check-then-act race, refuse if the bound token is already in the consumed registry, refuse if a resolution row already exists, insert the resolved row by selecting straight from the pending row, insert the consumed-token row, and delete the pending row. Either the request stops being pending and the token stops being spendable, or neither happens. That shape is why record_consumed and is_consumed are separate trait methods rather than folded into resolve, as the trait comments say. One consequence of the order: because the pending row is read first and deleted last, a second resolve of the same id returns NotFound, not AlreadyResolved. The already-resolved branch is only reachable when a pending row was reinserted after a resolution.

The caller above it is resume_with_decision, and its ordering carries a stated reason. It loads the pending record, reports already resolved: {id} ({outcome}) when only a resolution exists, checks the replay registry, verifies the token against the stored request, and only then compares the HTTP envelope’s outcome to the signed decision. That last check runs before the store is touched: a mismatched pair, where the token says denied and the body says approved, would otherwise have already flipped the request to resolved and moved the approved counter before the error was returned.

Read that third column carefully. The resume path collapses every distinction into one string-carrying variant, and the HTTP mapping recovers 409 by testing whether the message contains replay. Anything the resume path does not classify as ApprovalRejected becomes 500. The typed mapping that turns NotFound into 404 and AlreadyResolved into 409 is real, but it applies only where a handler calls the store directly, as GET /approvals/{id} does. Match on the code, and do not read a 403 on respond as a signature failure.

The batch endpoint, POST /approvals/batch/respond, runs the same path per entry and never aborts the set: each decision lands as resolved or rejected with its own message, under one summary of total, approved, denied, and rejected. It is a loop over independent transactions, not a transaction over the loop. The list is uncapped, and the response is 200 even when every entry was rejected, so the summary is the only thing worth reading.

The TTL ceiling, and the deadline that is not one

MAX_APPROVAL_TTL_SECS = 3600 caps the token lifetime: expires_at - issued_at above an hour is rejected in verify_against, because the single-use registry’s retention horizon is pinned to that value and a longer token could outlive its own replay entry. The sidecar clamps in the same units on the way in, ttl_seconds.min(3600) with 3600 as the default when the field is zero or absent, and mints 600-second tokens on the operator-respond shortcut.

Two paths beside the single request

Threshold: m-of-n on one node

The threshold collector is the shipped multi-approver path. chio api protect routes four endpoints at it under /approvals/threshold/proposals for create, get, respond, and deliver, and opens SqliteApprovalStore a second time against the same file to back it. Those routes are the only writers of the collector tables; the kernel’s own cumulative-approval proposal is parked on the durable admission operation instead. A proposal must be signed by a trusted policy authority, and in the sidecar that set holds one key, the sidecar’s own signer, which is also the key its embedded kernel signs proposals with. It must further agree with its requirement on threshold and eligible-set digest before it is stored.

Each submitted token must agree with the proposal on request id, intent hash, subject, and the proposal’s own artifact digest, sit inside three proposal-relative bounds (issued_at at or after creation, before the deadline, and expires_at no later than the deadline) as well as its own validity window against now, come from an approver in the eligible set, and survive a submitter-separation check when one is required. Its decision must be Approved: the collector has no way to record a denial, only cancel.

Storage is optimistic. Every mutation reads the record inside a transaction, refuses if the version moved or the state is terminal, and writes with the expected version and previous state in the WHERE clause; a row count other than one is a conflict, not a retry. The vote table enforces the rest in SQL:

canonical_token_digest TEXT NOT NULL UNIQUE,
...
PRIMARY KEY (proposal_id, token_id),
UNIQUE (proposal_id, approver_fingerprint),
UNIQUE (proposal_id, canonical_token_digest),
FOREIGN KEY (proposal_id)
    REFERENCES chio_threshold_approval_collectors(proposal_id)

The column-level constraint is the strict one: a canonical token digest is unique across the whole file, not per proposal, so one signed token cannot be submitted to two proposals even where the rest would allow it. The foreign key is weaker than it looks, because PRAGMA foreign_keys is set only on the connection that ran the migration.

Revision 2 exists for the primary key. The v1 table made token_id globally unique, so two proposals collided on an id that only has to be unique within one; opening a v1 database rebuilds the table scoped to the proposal and copies every row across in one transaction, asserted by open_migrates_v1_threshold_vote_ids_to_proposal_scope. Delivery has one more subtlety worth knowing: token expiry is bounded above by the proposal deadline but not below, so a set that was quorate at submission can hold lapsed tokens by delivery time. deliver filters to currently valid tokens and fails with threshold approval quorum is no longer satisfied rather than delivering a stale set, and the proposal stays Ready so the same signer can replace their expired token.

Batch: pre-approving a class

A BatchApproval lets one human pre-approve a class of calls: a subject, a server and tool pattern, an optional per-call and total amount, an optional call count, a time window, and used counters carried on the row so consumption can be reconciled without going back to the receipt log. find_matching narrows in SQL to non-revoked rows for the subject inside the window, then applies pattern, count, and amount filters in Rust and returns the first hit. There is no ORDER BY, so which batch wins when several match is unspecified. Pattern matching is exact, full wildcard, or one trailing-star prefix. Amount handling has one rule worth stating plainly: a call carrying no monetary intent matches only a batch that constrains neither per-call nor total amount, so putting a cap on a batch narrows it to priced calls and nothing announces that. Consumption is not atomic with matching either. record_usage is a separate unconditional UPDATE, so concurrent callers can both clear a max_calls check and overshoot it, and store is INSERT OR REPLACE, so re-storing a batch id overwrites its used counters.

Guarantees and limits

Next Steps

• Approval & HITL · the guard, the constraints that trigger it, and the seven binding checks a presented token must survive
• The Three Verdicts · who may construct PendingApproval, and what every other runner does on sight of it
• Node State on Disk · the schema stamp this store passes through, the sidecar file it shares, and the fence it does not take
• Revocation Store · the other node-local list the kernel consults before an allow
• Fail-Closed Semantics · what the node does when a store refuses to open mid-flight