Treaties

Each kernel folds the ladders, and the stricter requirement wins

For every shared action class, the verifier resolves the class in each participant's ladder and folds the declarations into one set of terms.

for participant in &treaty_scope.participant_kernel_ids {
    // … find this participant's action class
    let rank = ladder_mode_rank(&action.mode)?;
    if rank > mode_rank {
        mode_rank = rank;
        mode.clone_from(&action.mode);
    }
    destructive |= action.destructive;
    if let Some(existing) = consistency_model.as_ref() {
        if existing != &action.consistency_model {
            return rejected(
                "chio_federation_ladder_consistency_mismatch",
                "governance ladder consistency models do not intersect",
            );
        }
    } else {
        consistency_model = Some(action.consistency_model.clone());
    }
    if co_sign_requirement_rank(&action.co_sign)? > co_sign_requirement_rank(&co_sign)? {
        co_sign.clone_from(&action.co_sign);
    }
    // … merge the co-sign quorum
    for item in &action.evidence_required {
        evidence_required.insert(item.clone());
    }
    // … record participant_modes
}
if destructive && mode_rank < ladder_mode_rank("receipt_backed")? {
    return rejected(
        "chio_federation_ladder_destructive_below_floor",
        "intersected destructive action resolves below receipt backed mode",
    );
}
// … then the destructive crdt-commutative check

Mode and co-signing take the highest declared rank, evidence requirements combine by union, and one participant calling an action destructive makes it destructive. Consistency models must be equal, and any rejection stops the whole intersection, so a participant's requirement survives into the shared decision or the treaty refuses the class.

The verifier supplies the scope and manifests from its own trusted inputs and computes the expected intersection itself. The treaty library validates those records; fetching peer documents and deciding whether to trust them stays with the verifier. A scope is a structured record, and its digest binds the exact content used in admission.

An application opens a treaty with one call

From the Computer facade, a treaty names the partner, the actions, and a lifetime. Both kernels sign it.

import { Computer } from "@chio-protocol/sdk";

const project = await Computer.open("quickstart");
const partner = await Computer.connect("partner");
const treaty = await project.treaty({
  partner: partner,
  actions: ["workspace.read", "workspace.write", "model.invoke", "merge"],
  expiresIn: "7d",
});
console.log(treaty.describe());

treaty           trt-01aa…4c19, signed by both kernels
participants     you · partner (did:chio:z6MkpA7…c2T)
action           you       them      admitted as
workspace.read   allow     allow     either kernel admits under its own policy
workspace.write  allow     allow     either kernel admits under its own policy
model.invoke     allow     allow     charged at your door
merge            co-sign   co-sign   both kernels sign
expires          in 7 days

from chio import Computer

project = Computer.open("quickstart")
partner = Computer.connect("partner")
treaty = project.treaty(
    partner=partner,
    actions=["workspace.read", "workspace.write", "model.invoke", "merge"],
    expires_in="7d",
)
print(treaty.describe())

treaty           trt-01aa…4c19, signed by both kernels
participants     you · partner (did:chio:z6MkpA7…c2T)
action           you       them      admitted as
workspace.read   allow     allow     either kernel admits under its own policy
workspace.write  allow     allow     either kernel admits under its own policy
model.invoke     allow     allow     charged at your door
merge            co-sign   co-sign   both kernels sign
expires          in 7 days

use chio::{Computer, Treaty};

let project = Computer::open("quickstart").await?;
let partner = Computer::connect("partner").await?;
let treaty = project
    .treaty(
        Treaty::with(&partner)
            .actions(["workspace.read", "workspace.write", "model.invoke", "merge"])
            .expires_in("7d"),
    )
    .await?;
println!("{}", treaty.describe());

treaty           trt-01aa…4c19, signed by both kernels
participants     you · partner (did:chio:z6MkpA7…c2T)
action           you       them      admitted as
workspace.read   allow     allow     either kernel admits under its own policy
workspace.write  allow     allow     either kernel admits under its own policy
model.invoke     allow     allow     charged at your door
merge            co-sign   co-sign   both kernels sign
expires          in 7 days

You should see one row per action with what each side requires. Every action is admitted by the kernel that serves it, under that kernel's own policy, and merge resolves to co-sign on both sides.

Read more in Agree on what crosses.

Admission checks one action class against the bound contract

chio federation treaty admit emits an admission report for one class. A structurally invalid input returns an error before any report; a later failure produces a report with accepted: false and a failure code. The checks run in this order:

1. Structure. The scope and the intersection both validate, seeding checks with chio_federation.treaty.scope_valid and chio_federation.treaty.intersection_valid.
2. Freshness. --now-unix-ms sits inside the scope window and the intersection window, at or after generatedAtUnixMs.
3. Identity. The intersection's treatyId, ladderManifestSha256s, and participantKernelIds equal the scope's, element for element.
4. Binding. --expected-ladder-intersection-sha256 is supplied and equals the digest computed from the intersection handed in.
5. Scope membership. The action class appears in the scope's allowedActionClasses and in the intersection's actionClasses. A miss in either raises the same code.
6. Evidence presence, then evidence verification. Every required label is present, and each carries a verified: true reference.

The expected intersection digest comes from the verifier's own computation. Hashing an intersection you received and passing that hash back proves only that the intersection matches itself, never that it reflects your governance ladders.

At runtime the serving kernel applies the same contract at its own door. It reads the scope and intersection from its own store after checking the federated grant and its DPoP proof, and a stale treaty records chio_treaty_stale in chio_runtime.failure_code. Cross-org admission documents the same report and its failure codes from the boundary side.

The example treaty admits analysis.read and refuses a changed manifest

The federation guide project starts with a non-destructive analysis action, so the first workflow can verify every input it produced locally. The program writes both signed manifests, the pinned scope, the canonical intersection, and the clock and digest context the CLI reads.

Create complete treaty inputs

Generate fresh operator keys, signed ladder manifests, their pinned scope, and an intersection. Verify a permitted action and reject a changed manifest.

Complete the project setup, then run the program from federation-guide/. The download includes every constructor and input.

cargo run --locked --bin treaty

analysis.read: mode guarded, accepted true
changed pinned manifest: federation treaty rejected: chio_federation_ladder_manifest_hash_mismatch: computed ladder manifest hashes do not match treaty scope
wrote complete scope, signed manifests, intersection, and verification context

The manifests are locally signed and verified; scope revocation/trust digests identify example declarations. This action requires no external evidence. The separate billing reference demonstrates caller-asserted evidence classes; neither example executes a payment.

use chio_core_types::{
    crypto::{sha256_hex, Keypair},
    receipt::lineage::SignedExportEnvelope,
};
use chio_federation::treaty::*;
use federation_guide::now;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let now = now() * 1000;
    std::fs::create_dir("treaty-inputs")?;
    let keys = [Keypair::generate(), Keypair::generate()];
    let mut manifests = Vec::new();
    for (i, mode) in ["observation", "guarded"].into_iter().enumerate() {
        let manifest = GovernanceLadderManifest {
            schema: CHIO_FEDERATION_GOVERNANCE_LADDER_MANIFEST_SCHEMA.into(),
            manifest_id: format!("operator-{i}-ladder"),
            kernel_id: format!("operator-{i}"),
            issuer: keys[i].public_key().to_hex(),
            key_id: format!("operator-{i}-key"),
            issued_at_unix_ms: now - 1000,
            expires_at_unix_ms: now + 600_000,
            destructive_floor: "receipt_backed".into(),
            default_unknown_mode: "deny".into(),
            action_classes: vec![GovernanceLadderActionClass {
                action_class_id: "analysis.read".into(),
                mode: mode.into(),
                destructive: false,
                consistency_model: "single-kernel".into(),
                co_sign: "none".into(),
                co_sign_quorum: None,
                evidence_required: vec![],
                aliases: vec!["read".into()],
            }],
        };
        validate_governance_ladder_manifest(&manifest)?;
        // The manifest has no signature field. A signed export envelope can
        // authenticate distribution; the treaty separately pins the body hash.
        let signed = SignedExportEnvelope::sign(manifest.clone(), &keys[i])?;
        assert_eq!(signed.signer_key, keys[i].public_key());
        assert!(signed.verify_signature()?);
        std::fs::write(
            format!("treaty-inputs/operator-{i}-signed.json"),
            serde_json::to_vec_pretty(&signed)?,
        )?;
        std::fs::write(
            format!("treaty-inputs/operator-{i}.json"),
            serde_json::to_vec_pretty(&manifest)?,
        )?;
        manifests.push(manifest);
    }
    let scope = TreatyScope {
        schema: CHIO_FEDERATION_TREATY_SCOPE_SCHEMA.into(),
        treaty_id: "analysis-treaty".into(),
        participant_kernel_ids: manifests.iter().map(|m| m.kernel_id.clone()).collect(),
        participant_public_keys: keys.iter().map(Keypair::public_key).collect(),
        ladder_manifest_sha256s: manifests
            .iter()
            .map(governance_ladder_manifest_sha256)
            .collect::<Result<_, _>>()?,
        allowed_action_classes: vec!["analysis.read".into()],
        issued_at_unix_ms: now - 1000,
        expires_at_unix_ms: now + 600_000,
        revocation_epoch_sha256: sha256_hex(b"local revocation snapshot"),
        trust_bundle_sha256: sha256_hex(b"local two-operator trust configuration"),
    };
    let intersection = compute_ladder_intersection(&scope, &manifests, now)?;
    let report = evaluate_cross_boundary_admission(CrossBoundaryAdmissionInput {
        treaty_scope: &scope,
        ladder_intersection: &intersection,
        expected_ladder_intersection_sha256: Some(ladder_intersection_sha256(&intersection)?),
        action_class_id: "analysis.read",
        present_evidence: vec![],
        verified_evidence: vec![],
        now_unix_ms: now,
    })?;
    println!(
        "analysis.read: mode {}, accepted {}",
        report.mode, report.accepted
    );
    assert!(report.accepted);
    std::fs::write(
        "treaty-inputs/scope.json",
        serde_json::to_vec_pretty(&scope)?,
    )?;
    std::fs::write(
        "treaty-inputs/intersection.json",
        serde_json::to_vec_pretty(&intersection)?,
    )?;
    std::fs::write(
        "treaty-inputs/context.json",
        serde_json::to_vec_pretty(
            &serde_json::json!({"nowUnixMs":now,"intersectionSha256":ladder_intersection_sha256(&intersection)?}),
        )?,
    )?;
    manifests[0].action_classes[0].mode = "maintenance".into();
    println!(
        "changed pinned manifest: {}",
        compute_ladder_intersection(&scope, &manifests, now)
            .expect_err("changed manifest must not match treaty pin")
    );
    println!("wrote complete scope, signed manifests, intersection, and verification context");
    Ok(())
}

Open the source file. Each program asserts its expected refusals; keys, timestamps, and digests change between runs.

TREATY_TIME=$(jq -r .nowUnixMs treaty-inputs/context.json)
TREATY_DIGEST=$(jq -r .intersectionSha256 treaty-inputs/context.json)
chio federation treaty intersect --treaty-scope treaty-inputs/scope.json \
  --manifest treaty-inputs/operator-0.json --manifest treaty-inputs/operator-1.json \
  --now-unix-ms "$TREATY_TIME" --report treaty-inputs/cli-intersection.json
chio federation treaty admit --treaty-scope treaty-inputs/scope.json \
  --ladder-intersection treaty-inputs/cli-intersection.json \
  --expected-ladder-intersection-sha256 "$TREATY_DIGEST" \
  --action-class-id analysis.read --now-unix-ms "$TREATY_TIME" \
  --report treaty-inputs/cli-admission.json
cat treaty-inputs/cli-admission.json

{
  "schema": "chio.federation.cross-boundary-admission-report.v1",
  "treatyId": "analysis-treaty",
  "actionClassId": "analysis.read",
  "accepted": true,
  "mode": "guarded",
  "consistencyModel": "single-kernel",
  "coSign": "none",
  "requiredEvidence": [],
  "presentEvidence": [],
  "verifiedEvidence": [],
  "treatyScopeSha256": "dd8e24469bd89e97820e8ae1196a394f94d60e11021bc69a3c805e380a7ec9ae",
  "ladderIntersectionSha256": "c0f39c8af4b8856c8d942ec3c1aa15bac131b24c358512d1903a1fe52c0cfc68",
  "expectedLadderIntersectionSha256": "c0f39c8af4b8856c8d942ec3c1aa15bac131b24c358512d1903a1fe52c0cfc68",
  "checks": [
    "chio_federation.treaty.scope_valid",
    "chio_federation.treaty.intersection_valid",
    "chio_federation.treaty.required_evidence_present",
    "chio_federation.treaty.required_evidence_verified"
  ]
}

You should see analysis.read: mode guarded, accepted true, then the changed manifest refused with chio_federation_ladder_manifest_hash_mismatch. The CLI's admission report repeats both digests and lists the four checks the action passed.

A changed pin makes a new scope, and revoking the treaty ends its grants

A scope is usable within issuedAtUnixMs <= now < expiresAtUnixMs. Intersection checks the scope and every manifest against the caller's time, admission checks the scope and intersection again, and the intersection expires at the earliest expiry among its inputs.

Changing revocationEpochSha256 or trustBundleSha256 changes treatyScopeSha256. The intersection omits those two pins, so unchanged ladders at the same generation time can yield the same ladderIntersectionSha256. An artifact bound to an old scope stays consistent with that scope, and a revocation epoch published elsewhere leaves it unchanged. It is rejected when compared against the current trusted inputs: refresh the verifier's scope, recompute the bindings, and apply current revocation and trust policy at the receiving door.

Revoking the treaty ends every grant issued under it, including the grants the partner's agents delegated to each other, and their next call is refused:

chio federation treaty revoke --treaty trt-01aa…4c19

revoked    trt-01aa…4c19, signed by your kernel 4f1c…a2e9
grants     cap-01a9…7e40 and 4 delegated descendants revoked
feed       revocation root sent to partner over iroh

Read more in Revoke, and the work stops.

Next: declare the ladder your kernel contributes