Policy Rollout

The absent mechanism, named

Chio has no policy control plane. Not a partial one, not a feature-gated one, not one behind a flag. A node loads one file from its own filesystem at process start, fingerprints it, and never looks at it again. Every other node does the same thing independently. Nothing compares the results.

This needs saying out loud because the surrounding system looks like it would have one. The trust control plane has a leader, peer authentication, delta replication for five streams, and an authority snapshot that propagates key rotation. Assuming policy travels the same way is expensive: two nodes under one authority key can enforce different guard pipelines indefinitely, answer every health probe green, and issue capabilities the other node would have denied.

Five negatives, each checkable

What actually exists

Three objects, and one of them is only a pair of strings.

• The document. A YAML file at a path the operator passes on the command line. It is either a Chio YAML policy or a HushSpec policy; load_policy decides by looking for a hushspec: top-level key.
• The materialization. LoadedPolicy: kernel config, default capabilities, a compiled guard pipeline, a post-invocation pipeline, and the optional reputation, runtime-assurance, and threshold-approval policies. It exists in process memory and is moved into the kernel at construction.
• The identity. PolicyIdentity { source_hash, runtime_hash }. This is the whole of Chio’s policy versioning. Everything below is about what those two hashes do and do not cover.

Only one of the two reaches a receipt. build_kernel sets KernelConfig.policy_hash = identity.runtime_hash, and the source hash goes to a log line and to evidence exports. policy_hash is a plain String everywhere in the type system, and nothing on the receipt path constrains its shape. Its derivation is not uniform across edges:

Compare hashes only within one edge class. A fleet mixing sidecars and kernels has two populations of policy hash that were never meant to match.

How policy reaches a node, in order

1. Read, once

load_policy does a read_to_string on the path, hashes those bytes into source_hash, and branches on format. That is the entire ingestion path. There is no watcher, no SIGHUP handler, no reload verb.

2. Resolve, on the local filesystem only

A HushSpec document may carry extends. resolve_from_path follows the chain with a filesystem loader, canonicalizing each hop, detecting cycles by comparing canonical paths, and refusing past DEFAULT_MAX_EXTENDS_DEPTH = 32 or a document larger than DEFAULT_MAX_POLICY_DOCUMENT_BYTES (4 MiB, applied per document, not to the chain). The depth check counts the entry document, which is already on the stack before the first hop, so the ceiling is 32 documents and 31 extends hops. The built-in rulesets (default, strict, permissive, ai-agent, cicd, remote-desktop, panic) are include_str! blobs compiled into the binary and reachable through the library, not through extends on this path. chio mcp serve --preset code-agent writes its embedded YAML to a temp file for exactly that reason: the ordinary path-based loader, and therefore the ordinary hashing, then applies unchanged.

3. Fingerprint, over a curated field set

The runtime hash is not a digest of the compiled policy. It is a SHA-256 over a canonical JSON object built by hand, and the field list is the whole story:

let fingerprint = serde_json::json!({
    "format": PolicyFormat::HushSpec.as_str(),
    "kernel": kernel,
    "default_capabilities": default_capabilities,
    "rules": {
        "forbidden_paths": rules.and_then(|entry| entry.forbidden_paths.as_ref()),
        "path_allowlist": rules.and_then(|entry| entry.path_allowlist.as_ref()),
        "egress": rules.and_then(|entry| entry.egress.as_ref()),
        "secret_patterns": rules.and_then(|entry| entry.secret_patterns.as_ref()),
        "patch_integrity": rules.and_then(|entry| entry.patch_integrity.as_ref()),
        "shell_commands": rules.and_then(|entry| entry.shell_commands.as_ref()),
        "tool_access": rules.and_then(|entry| entry.tool_access.as_ref()),
    },
    "reputation": extensions.and_then(|entry| entry.reputation.as_ref()),
    "auxiliary_assets": auxiliary_assets,
});

Two of those fields carry less than they look like. kernel on the HushSpec path is KernelPolicyConfig::default(), the same constant for every HushSpec document, because the format has no way to set kernel config; it distinguishes nothing. And reputation is the only member of extensions present at all.

RULE_BLOCK_NAMES in chio-policy/src/models/rules.rs is a fourteen-element array. Seven are named above. Of the seven that are not, human_in_loop can move the hash indirectly, but only conditionally: compile_scope reads it solely on the branch where tool_access is present and enabled, and the compiled scope is what appears as default_capabilities. Without a tool_access block the scope is permissive and human_in_loop is invisible to both hashes. The other six do not move the hash at all, and each compiles into a real guard that changes verdicts: velocity, computer_use, remote_desktop_channels, input_injection, browser_automation, and code_execution. Change code_execution on one node and not another and the two nodes deny different calls under an identical runtime hash.

The gap is wider than the rule blocks. Four more inputs materialize into the running kernel from compile_policy_with_options and load_hushspec_policy, and none of them appears in the fingerprint:

The Chio-YAML path is stricter: it serializes the whole guards config into the fingerprint, and has no extensions tree to miss. The gap above is a HushSpec property, not a universal one.

4. Build, adding guards the policy never mentioned

build_kernel registers chio_guards::default_runtime_guard_profile() before it registers the policy-compiled pipeline: an internal-network guard, an agent-velocity guard on default config, and an advisory pipeline. It then appends that profile’s sanitizer hook to the post-invocation pipeline. Those four come from the binary, not from the file, and they are outside both hashes. Two nodes running the same policy on different Chio builds can differ in the base profile with no hash change to show for it. The policy hash identifies a document, never a deployment.

5. Stamp, on every mediated decision

This is the part that works, and it is stronger than a field on a record. ChioReceiptIdInput includes policy_hash, and the receipt id is the content-addressed SHA-256 over that canonical input, so the hash is bound into the receipt’s identity rather than carried alongside it:

/// Compute the authoritative receipt id from canonical receipt body fields.
pub fn chio_receipt_id(body: &ChioReceiptBody) -> Result<String> {
    let input = ChioReceiptIdInput::from(body);
    let canonical = canonical_json_bytes(&input)?;
    Ok(sha256_hex(&canonical))
}

/// Validate, bind the caller nonce, and compute the authoritative receipt id.
pub fn prepare_receipt_body_for_signing(mut body: ChioReceiptBody) -> Result<ChioReceiptBody> {
    body.validate_signable_semantics()?;
    bind_receipt_signing_nonce(&mut body);
    body.id = chio_receipt_id(&body)?;
    Ok(body)
}

Read that for what it is. Editing policy_hash after signing changes the id, so the edit is detectable by anyone who recomputes it. It does not, on its own, establish that the hash in the body is the one the decision was actually taken under.

The check that does bite is on the durable admission path, on by default because DurableAdmissionMode defaults to SideEffecting. The admission binding folds policy_hash into the operation’s identity, and terminal projection refuses a receipt whose hash differs from the binding it completes, so an operation admitted under one policy cannot be finished under another across a restart. Child request receipts and lineage statements carry the field but pass through neither gate.

6. Stop

KernelConfig is consumed by ChioKernel::new and policy_hash has no setter. Applying a new policy means restarting the process. That is the whole rollout primitive, and the platform you deploy on owns the ordering.

What to do instead

The absence has a workable shape if you stop treating policy as runtime configuration and start treating it as a build input.

• Ship the file with the artifact. Bake the policy into the image or mount it read-only from the same versioned source as the binary. The base chio stage in deploy/docker/Dockerfile ships no policy at all (its CMD is --help); the chio-mcp-demo stage layered on it bakes one in with --policy /opt/chio/examples/policy.yaml. Copy the pattern, not the demo. Because the base guard profile is compiled in, pinning the binary and pinning the policy are one decision, not two.
• Compute the expected hashes offline. chio check --policy ./policy.yaml --tool read_file --json prints policy_hash and policy_source_hash alongside the verdict. --params defaults to {} and --server to *. Record the pair with the release. One trap in a release script: the command exits 2 when the sample verdict is a deny, so pick a probe your policy allows or handle the exit code, otherwise the step that reads your policy identity fails the build.
• Replay before you roll. chio replay traffic --from capture.ndjson --against path:./candidate.yaml --tenant-pubkey ./tenant.pub --json builds a fresh ephemeral kernel under the candidate policy, allocates a replay receipt partition type-fenced against production, re-runs every captured invocation through the pre-invocation pipeline, and reports matches, drifts, and errors, with ok() true only when drifts and errors are both zero. Receipts are namespaced replay:<run_id>:<frame_id>. Three limits to plan around. A policy with post-invocation guards is rejected, because tee frames carry a response digest rather than redacted bytes; so is any default capability with a server-specific grant, because frames do not carry the original tool server id. And a frame counts as a match only when the verdict, the attributed guard, and the deny reason string all agree, so a build that reworded a reason registers as drift. This is the closest thing to a canary in the tree, and it runs on your workstation rather than on traffic.
• Sequence the restart yourself. Nothing in Chio orders a fleet-wide change. Use the platform’s rollout, and keep the window short: while it is open, the cluster is genuinely running two policies. If the change tightens a guard, roll the strictest nodes last so a permissive node is never the leader; if it loosens one, the ordering does not matter, but the receipts still record which node allowed what.
• Verify from receipts, not from health. The trust-control health body reports issuancePolicyConfigured and runtimeAssurancePolicyConfigured as booleans and never a digest, and TrustServiceConfig does not retain the policy identity at all. The receipt store is where the answer lives.

That last check is a direct query, because the API layer has no policy dimension: ReceiptQuery filters on capability, tool server, tool name, outcome, time, cost, agent subject, and tenant, but not policy hash; receipt analytics groups by none of it; and while policy_hash is a NOT NULL column on chio_tool_receipts, the table indexes timestamp, capability, subject, grant, tool, and decision, not it. Read the file on each node, remembering that timestamp is an INTEGER of Unix seconds:

SELECT policy_hash,
       COUNT(*)      AS receipts,
       MIN(timestamp) AS first_seen,
       MAX(timestamp) AS last_seen
FROM chio_tool_receipts
WHERE timestamp >= :rollout_started_at
GROUP BY policy_hash
ORDER BY last_seen DESC;

One row per node after the rollout window closes is convergence. Two rows that both keep advancing last_seen is drift, and the node whose hash you do not recognize is the one to look at. For an auditable version of the same evidence, POST /v1/evidence/export attaches the policy source file itself plus a metadata block carrying format, sourceHash, runtimeHash, sourcePath, and sourceBytes.

Guarantees and limits

Next Steps

• Cluster Overview · the four bounded claims this page expands, and the three failure domains a per-node probe cannot report
• chio.yaml Configuration · the schema of the file that has to reach every node by hand
• Replication & Convergence · what the pull round does replicate, and the contract violations that demote a peer
• Authority & Rotation · the one object that is propagated between nodes, and how that snapshot differs from a policy
• HushSpec Policy Format · the fourteen rule blocks, seven of which the runtime hash names