Node Overview

The other side of the core boundary

Core and Shell documents what a kernel evaluation refuses to do. This page is the process standing on the other side of that refusal. The refusal is written down in one place, as a module doc comment on the file that performs the evaluation:

//! What it does NOT do (fenced into `chio-kernel` proper):
//!
//! - Revocation membership lookup (stateful `RevocationStore`).
//! - Budget mutation (stateful `BudgetStore`).

Six more items follow, and Core and Shell reads the whole list out. Every line on it needs a handle the function does not have: a store, a socket, a clock, a lock file. The node holds those handles.

The kernel decides whether one governed action is permitted; the node decides whether this process is still fit to decide at all, and answers that by reading its own disk. That is the filing test for this rung. Two excluded items leave the ladder rather than land here: budget mutation is priced and metered work belonging to Economy, and governed-transaction evaluation can require a co-signature under a key the operator does not hold, which climbs to Swarm.

What a node is

Five objects carry the whole rung, each with one canonical name in the code.

The fence is what makes a node singular

A second process attempting to serve the same session database fails before it can write anything. Node State on Disk works the fence through store by store; the shape of it is this. open_serving canonicalizes the database path, requires both the lock root and the database's parent directory to be owned by the effective user and not group or world writable, then takes an advisory lock on the per-store lock file; a lock held elsewhere maps WouldBlock to SqliteServingOwnerError::AlreadyServing. The test for this spawns a real second process rather than a second handle: concurrent_process_open_is_fenced_before_serving.

Exclusivity alone is not enough, because a lock can be released and reacquired. So the epoch is monotonic. Every successful open increments owner_epoch, closes the previous lease at the current authority head, and inserts a new lease row starting there. A superseded handle then fails closed on budget writes with BudgetStoreError::Fenced and on revocation access, including reads such as is_revoked, with RevocationStoreError::Fenced. The lease history lets the node answer, from its own disk and nothing else, which lease authored a given commit: verify_historical_revocation_commit joins chio_serving_leases against admission_authority_commits and requires the commit index to fall inside that lease's open range.

Boot, in order

serve_async in crates/platform/chio-control-plane/src/trust_control/service_runtime/init.rs is the reference sequence. Each step returns an error that aborts the boot.

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 alongside --budget-db or --revocation-db; a session database configured alongside peers; and any two configured databases that resolve to the same file.
2. Claim the disk, if a session database was given. 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. With no session database this step does not run and the process has no serving lease.
3. Bind the listener. The TCP bind happens 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, which is the branch a session database excludes. A node with no budget database still serves; it has no budget authority to offer.
5. Decide whether it is clustered. build_cluster_state(&config, local_addr) returns 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 post-signal drain.

One more step, on the protocol-edge shapes only

A bare trust-control process never validates a manifest. A protocol edge adds that step to the sequence above, and does not exist until every manifest it was handed passes chio_manifest::validate_manifest. The check runs inside the constructor, so a bad manifest returns an error instead of a serving edge. ChioMcpEdge::new routes through build_exposed_tool_bindings, which validates each manifest and then rejects a tool name that appears in two of them with ManifestError::DuplicateToolName. Validation is structural: schema identifier, identity fields, unique tool names, JSON-object schemas, pricing completeness, duplicate-free permissions. It authenticates nothing. The fullest of those edge shapes, with Streamable HTTP, bearer and sender-constrained admission, and one kernel per session, is Remote MCP Edge.

Stopping is part of the contract

chio-http-serve exists so every Chio serve site converges on one implementation of three obligations: notice the stop signal, stop accepting and drain inside a bounded window, and refuse abusive load with an explicit denial rather than unbounded growth. Node Lifecycle is the whole of that path. Its defaults are a 25 second drain, a 20 second per-request timeout set below the drain so a late-admitted request reaches its own 408 rather than being severed, 1024 concurrent requests with load shedding to 503, and 2048 accepted connections. An oversized body is a 413, and the body cap defaults to None so a site with a large route-local upload limit is not clobbered by a global one.

Trust-control changes two of those fields and says why. It sets the 1 MiB body cap the default leaves unset, and disables the per-request timeout, because a clustered budget authorize parks in the quorum wait; a blanket timeout firing after the local exposure write but before that wait returned would drop the handler before its rollback branch, leaving a charged, leader-visible write the client saw fail. The post-drain join of the cluster sync loop then gets only what remains of the same drain window, never a fresh wait on top of it.

The standalone node is the default

A single node is not a cluster missing its peers. It is the shape the code treats as ordinary, and on the one dimension where the two differ measurably, it is the stronger of the two.

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);
    }

The return type is the whole argument. No peers means Ok(None), and so does a peer list that normalizes down to nothing once the node's own advertise URL is filtered out of it. In init.rs the sync task is spawned 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. The health response reports clustered as exactly that boolean; what else it reports, and what a tripped level costs, is Health & Readiness.

The same asymmetry runs through the write path. wait_for_budget_write_quorum_commit returns Ok(None) immediately when the node has no cluster progress handle: no quorum to wait for, so no quorum wait to time out and 503. The release runbook states the same ceiling, setting single-node atomic on one SQLite store against a clustered mode that admits a documented overrun bound and is not distributed-linearizable. ADR-0006 puts a number on that bound, max_cost_per_invocation * node_count, exercised by the concurrent_charge_overrun_bound test in budget_store.

Five things a node hands up

Adding peers does not change what a node is. It adds exactly five obligations the node supplies and the cluster consumes. What the cluster does with them belongs to Trust Control Plane.

The lease is where the cluster's shared authority is pinned to a term. The election term is persisted in the capability-authority store, and on boot build_cluster_state reads it only when --authority-db is configured, and adopts it only when the recorded generation and rotation timestamp still match the live authority. A rotated authority makes that fence stale: the node logs the discard and starts from term zero rather than carrying a lease across a key change. A persisted leader URL is kept only if it still normalizes and still names either this node or a configured peer.

If you reach Chio through an SDK

Consuming Chio through the TypeScript, Python, or Go SDK makes you a client of someone else's node: every entry point takes that node's base URL, and the serving lock, the epoch, the drain window, and the advertise URL are the operator's obligation, not yours. One part travels with you. The invariant helpers for canonical JSON, hashing, signing, receipts, capabilities, and manifests are local computation and need no node, which is what lets a client verify evidence without trusting the process that handed it over.

Guarantees and limits

Next Steps

• Node State on Disk · the serving owner, the single-writer rule, and the refusals before every write
• Node Lifecycle · the stop signal, the bounded drain, and the numbers a platform recipe must satisfy
• Remote MCP Edge · the fullest single-process shape: Streamable HTTP, three bearer modes, one kernel per session
• Health & Readiness · what one process answers about itself, and why a tripped level never self-heals
• Budget Store · authorize, capture, release, reconcile as one process performs them
• Revocation Store · the revoked set on this disk, and the gate that refuses to dispatch without one
• Core and Shell · the Kernel half of this boundary
• Trust Control Plane · the next rung, where the five obligations are consumed