Runtime Contract

One process owns the session database, and every boot raises its epoch

open_serving canonicalizes the database path and requires the lock root and the database's parent directory to be owned by the effective user and closed to group and world writes. Then it takes an advisory lock on the per-store lock file, and a held lock maps WouldBlock to SqliteServingOwnerError::AlreadyServing. The test concurrent_process_open_is_fenced_before_serving proves it by spawning a second operating-system process.

Because a lock can be released and taken again, each successful open also increments owner_epoch, closes the previous lease at the current authority head, and inserts a new lease row that starts there.

A handle from a superseded epoch fails closed. Budget writes return BudgetStoreError::Fenced, and revocation access, reads such as is_revoked included, returns RevocationStoreError::Fenced. The lease history answers from the node's own disk which lease wrote a commit: verify_historical_revocation_commit joins chio_serving_leases against admission_authority_commits and requires the commit index to fall inside that lease's range.

• Joint session store. The global --session-db flag (joint_authority_db_path in TrustServiceConfig) puts budget and revocation state behind the serving owner, its lock, and its epoch. For chio run and chio mcp serve-http this is the default: the policy default for durable_admission_mode is side_effecting, which requires a session database.
• Separate stores. --budget-db and --revocation-db open through SqliteBudgetStore::open and SqliteRevocationStore::open with serving_owner: None. They take no lock, so two processes can hold the same file.

The two layouts never share a file: both separate stores refuse a database that already carries a serving-owner table, and config.validate() rejects a configuration that names both. Setting durable admission to off needs allow_unsafe_durable_admission_off and an ephemeral receipt log. Choose the layout before you make single-writer or recovery claims.

Read more in Node State on Disk.

Boot claims the disk before it binds, and any failed step aborts it

Trust control starts through serve_async, which runs six steps in order. Each returns an error that aborts the boot, so a node that serves has passed all six.

1. Validate the config. config.validate() rejects a service token that is empty, whitespace-padded, or carries control characters; a zero cluster sync interval; a zero certification metadata TTL; a tenant read token equal to the service token; a session database configured beside --budget-db, --revocation-db, or peers; and two configured databases that resolve to the same file.
2. Claim the disk. With a session database, the lock root is a .locks sibling of that database, created at mode 0700. provision establishes or re-verifies the store identity, then open_serving takes the lock and advances the epoch. Without one, the step is skipped and the process holds no serving lease.
3. Bind the listener. The TCP bind comes before the remaining stores open, because build_cluster_state needs the resolved local_addr to default the advertise URL.
4. Open the separate stores. Budget and revocation stores open only when their own paths are configured, the branch a session database excludes. A node with no budget database still serves, with no budget authority to offer.
5. Decide whether it is clustered. build_cluster_state(&config, local_addr) returns an Option, and the sync loop is spawned only on Some.
6. Install, wrap, and serve. ShutdownController::install fans one signal handler out over a watch channel, apply_server_hygiene wraps the router, MaxConnListener caps accepted connections, and run_until_drained bounds the drain after the signal.

Stopping is bounded: 25 seconds to drain, then the serve future is dropped

Every Chio serve site takes its stop path from chio-http-serve. It notices the stop signal, stops accepting and drains inside a bounded window, and answers excess load with an explicit status.

The request timeout sits below the drain, so a request admitted late reaches its own 408 before the drain severs it. The body cap stays unset by default, so a site with a large route-local upload limit keeps it. Trust control disables the request timeout because a clustered budget authorize parks in the quorum wait. A timeout firing after the local exposure write, before that wait returned, would drop the handler before its rollback branch and leave a charged, leader-visible write the client saw fail.

The post-drain join of the cluster sync loop gets only what remains of the same window. A drain that reaches its deadline is logged and reported as DrainOutcome::Forced, and the serve future is dropped to release the accept loop. Axum runs each connection on a detached task that a bounded drain can neither join nor cancel, so a handler can still be finishing after a forced report.

Trust control passes a no-op flush hook, since its handlers write budget and revocation state synchronously. ServeError::Flush covers the sites whose receipts are buffered.

Read more in Node Lifecycle.

A standalone node carries the stronger budget guarantee

With no peers configured, trust control runs as one node with one SQLite joint authority store. That shape provides the single_node_atomic budget guarantee durable admission requires. It is one failure domain, so its availability comes from a supervisor, a restart, and a backup.

pub(crate) fn build_cluster_state(
    config: &TrustServiceConfig,
    local_addr: SocketAddr,
) -> Result<Option<Arc<Mutex<ClusterRuntimeState>>>, CliError> {
    config.validate()?;
    // ... rejects peers configured alongside --authority-seed-file
    if config.peer_urls.is_empty() {
        return Ok(None);
    }

No peers means Ok(None), and so does a peer list that normalizes to nothing once the node's own advertise URL is filtered out. init.rs spawns the sync task through state.cluster.is_some().then(...), so an unclustered node runs no replication loop, opens no peer connections, and has no background work to fail. Its health response reports clustered as that boolean; Health & Readiness covers the rest of the response.

budget_authority_guarantee_level returns single_node_atomic when state.cluster is None and advisory_posthoc otherwise. AdmissionCombinedCaptureCommit::validate and verify_historical_revocation_commit accept only SingleNodeAtomic. On the write path, wait_for_budget_write_quorum_commit returns Ok(None) at once when the node has no cluster progress handle, so there is no quorum wait to time out into a 503.

Each layer of a deployment establishes one thing

The process hosts transports, runtimes, state, and lifecycle. One process may host several kernels, and trust control is a separate service composition. The joint session store gives one serving owner and epoch-fenced local authority mutations, which separate stores and a clustered node run without.

A protocol edge carries a governed request to the kernel along its configured path; transport errors and compatibility passthrough produce no governed receipt. Admission can refuse dispatch, and a later failure leaves an external effect in place, a limit shared by every kernel and stated at the mediation boundary.

An application that connects through an SDK supplies the node URL and credentials, while the operator manages serving locks, state, health, and shutdown. The TypeScript, Python, and Go SDKs also check canonical JSON, signatures, capabilities, and receipts locally, with no live node. The Quickstart shows an allowed call and its receipt.

Next: see what the node keeps on disk