Treaties

What a Treaty Is

A treaty is a record, not a relationship. One chio.federation.treaty-scope.v1 pins three things at once: which kernels are party to it, which action classes they are willing to share, and the exact SHA-256 of the governance ladder manifest each of them published. Everything downstream, the intersection, the admission decision, the bilateral invocation, and the buyer packet, binds back to that record by digest.

A treaty is verifier-owned local evidence. The verifier supplies the scope and the manifests from its own store, computes the intersection itself, and re-computes the digest it will accept. Nothing in the treaty path fetches a peer document, resolves a registry, or promotes a counterparty's assertion into local trust. A treaty narrows what two ladders already independently declared; it never widens either one.

Three verbs consume the record, and they compose in exactly this order:

The Treaty Scope Record

The record is a closed object: the schema sets additionalProperties: false and the Rust type carries deny_unknown_fields, so an unrecognized key rejects rather than being ignored. All ten fields are required, and all of them are inside the canonical-JSON digest.

The three array lengths are cross-checked, not merely bounded. Fewer than two participants rejects with chio_federation_treaty_missing_participant; a participant count that does not equal the public-key count rejects with the same code; a participant count that does not equal the manifest-hash count rejects with chio_federation_ladder_manifest_hash_mismatch. Duplicate participants and duplicate keys have their own codes, treaty_scope_duplicate_participant and treaty_scope_duplicate_participant_key.

{
  "schema": "chio.federation.treaty-scope.v1",
  "treatyId": "treaty:buyer-vendor:billing",
  "participantKernelIds": ["did:chio:buyer", "did:chio:vendor"],
  "participantPublicKeys": [
    "bff663535a5cf58658cc38595d20dc4501f6dfc076ddf07e20571d413a3ceb5a",
    "c41d8e0a97b2653f10ce4a7d8b09f523a6d17c0e4b98f2a53d0c76e1b48a95f2"
  ],
  "ladderManifestSha256s": [
    "4f2c9a1b7d3e58c06a9f14bd2e7c830516ab4d9f2c6e18a3b57d0f4e29c6b81a",
    "9c7b3f0d5e2a184f6b0c93d7e415a28c0f6d3b92e7a51c48d0b6f2e93a75c104"
  ],
  "allowedActionClasses": ["billing.charge"],
  "issuedAtUnixMs": 1800000000000,
  "expiresAtUnixMs": 1800003600000,
  "revocationEpochSha256": "1a4c7e9052b8d3f60c7a1e5b93d048f2a6c0b7e1d9538f24a0c6b2e7d15f8039",
  "trustBundleSha256": "77e1b0d43a9c25f81e06b7d3c48a95f20d1e6b8a35c709d4f2a8b60e13c5d972"
}

treatyScopeSha256, the value the admission report and the buyer packet both carry, is the SHA-256 of this record serialized as RFC 8785 canonical JSON. It is not the hash of the file bytes. Reformatting the file changes nothing; changing any field, including the two pins at the bottom, produces a different digest and breaks every artifact that bound the old one.

Ladder Intersection and the Strict Shared Mode

A treaty scope names action classes; it does not say what governing them requires. That answer lives in each participant's chio.federation.governance-ladder-manifest.v1, and intersect folds those manifests into one chio.federation.ladder-intersection.v1 by walking every id in allowedActionClasses and resolving it against every participant in turn. A participant may satisfy the lookup either by declaring the id directly or by listing it in that class's aliases, which is how the same semantic class published under two domain-local names collapses to one intersected entry.

Each field folds by its own rule. Two of the rules climb, one demands agreement, one unions, and one intersects a numeric quorum:

Two floors are re-checked after the fold, because a class can become destructive in the intersection that neither side declared destructive at full strength. An intersected class that is destructive must land at receipt_backed or above (chio_federation_ladder_destructive_below_floor) and must not carry crdt-commutative consistency (chio_federation_ladder_destructive_crdt_not_allowed). The same two rules are enforced a second time when the intersection is validated for output, so a hand-edited intersection file cannot smuggle a destructive class in below the floor.

The intersection carries the treaty's participant list and manifest hashes forward unchanged, sets intersectionId to {treatyId}:{nowUnixMs}, and sets expiresAtUnixMs to the minimum of every contributing manifest expiry and the treaty expiry. The shortest-lived input governs; an intersection never outlives the weakest thing it was computed from.

Admitting an Action Class

admit evaluates one action class against one intersection and emits a chio.federation.cross-boundary-admission-report.v1. The checks run in a fixed order and the first failure produces the report:

1. Structure. The scope and the intersection both validate, seeding checks with chio_federation.treaty.scope_valid and chio_federation.treaty.intersection_valid. A structural failure here is an error, not a report.
2. Freshness. --now-unix-ms must sit inside the scope window and the intersection window, and must not precede generatedAtUnixMs.
3. Identity. The intersection's treatyId, ladderManifestSha256s, and participantKernelIds must equal the scope's, element for element.
4. Binding. --expected-ladder-intersection-sha256 must be supplied, and must equal the digest computed from the intersection actually handed in.
5. Scope membership. The action class must appear in the scope's allowedActionClasses and in the intersection's actionClasses. Both misses raise the same code.
6. Evidence presence, then evidence verification. Required labels must all be present, and each present label must carry a verified: true ref.

Required evidence is not simply the intersected evidenceRequired list. The co-sign requirement adds its own implied label: bilateral_required appends bilateral_invocation and n_of_m appends quorum_signature, each only when not already listed. A ladder author cannot forget to demand the artifact that proves the co-signature they demanded. Note which value carries the quorum: the co-sign mode is n_of_m, while quorum-required is a consistencyModel and appends nothing.

The CLI takes evidence as repeated --evidence evidence_class=artifact_sha256 pairs. A token without = is rejected before any report is written. Every accepted pair is recorded as both a present label and a verified: true ref, so the flag is an assertion that the verifier already checked that artifact; it is not the check itself.

The report is also validated on the way out, which closes the obvious forgery. An accepted report that fails to carry every required label as present and verified will not serialize; it raises chio_federation_treaty_missing_required_evidence or chio_federation_treaty_unverified_required_evidence at write time. A report with accepted: false and no failureCode, or accepted: true with one, is equally unwritable.

Fail-Closed Rules

Every rule below denies. None of them degrade, warn, or fall back to a default mode. The manifest-level guarantee that makes this hold is defaultUnknownMode, which the schema fixes to the constant deny: a governance ladder cannot declare a permissive default for classes it has not enumerated.

Those are the decision codes, the ones a report carries in failureCode. Three more sit one layer down, on the closed enums themselves, and they fire from intersect, admit, and manifest validation alike, because all three call the same validators: chio_federation_ladder_invalid_mode for a mode outside the five, chio_federation_ladder_invalid_consistency_model for a consistency value outside the four, and chio_federation_ladder_invalid_cosign_mode for a co-sign value outside the four. A hand-edited intersection file that misspells one of those enums dies here rather than producing a report. Below those again is a large shape-checking family, the treaty_scope_*, ladder_intersection_*, governance_ladder_manifest_*, cross_boundary_admission_* and unsupported_* codes, which report an empty field, a malformed digest, or an unrecognized schema tag rather than a governance decision.

Two behaviors of the intersection check are worth stating plainly. The manifest digest comparison is a set comparison, so supplying the right manifests in a different order is fine and supplying a manifest that was not pinned is not. And --expected-ladder-intersection-sha256 is documented as coming from verifier-owned computation for a reason: hashing the file you were handed and passing that value back satisfies the comparison while proving nothing. The check is only load-bearing when the verifier recomputed the intersection itself.

Evidence Classes and What a Treaty Does Not Prove

The phrase evidence class names two different vocabularies in this lane, and confusing them is the fastest way to misread a report.

• Grade. On chio.federation.receipt-lineage-statement.v1, evidenceClass is a closed enum answering how well the lineage was established: verified, observed, asserted, unverifiable, rejected. These stay distinct; nothing promotes one grade into another.
• Kind. On chio.federation.cross-boundary-admission-report.v1, verifiedEvidence[].evidenceClass is an open label matching ^[a-z0-9_]+$ that names which artifact, not how good it is: receipt_lineage, bilateral_invocation, workflow_receipt, quorum_signature. Its companion boolean verified carries the quality judgment.

The two meet at verify-packet. A buyer attestation packet is rejected when the lineage statement's grade is anything other than verified, with failure code chio_attest_buyer_packet_lineage_not_verified. An asserted lineage does not become verified by being carried inside an otherwise well-formed package.

verify-packet is the strictest of the three verbs because it re-derives instead of trusting. It recomputes the lineage, continuation, admission, and bilateral digests and compares each against the packet's claim; it requires the bilateral invocation's signerKernelIds to equal the continuation's source and target in that order; it requires localReceiptSha256 and remoteReceiptSha256 to equal the lineage's parent and child receipt hashes; and it requires the admission report to be accepted and to carry exactly one verified ref each for receipt_lineage and bilateral_invocation at the packet's digests. Identity failures raise chio_attest_buyer_packet_identity_mismatch and digest failures raise chio_attest_buyer_packet_hash_mismatch. A packet whose bilateral DSSE digest cannot be resolved is not accepted on the strength of the hash alone; it lands on chio_attest_buyer_packet_dsse_unresolved.

Issuance, Expiry, and Revocation

A treaty is fresh when issuedAtUnixMs <= now < expiresAtUnixMs. The lower bound is inclusive and the upper bound is exclusive, so a treaty is never valid at the instant it expires, and a record whoseissuedAtUnixMs is greater than or equal to its expiresAtUnixMs describes an empty window and rejects at validation rather than at use.

Freshness is evaluated twice against a clock the caller supplies. intersect takes --now-unix-ms and checks the scope window plus every manifest window; admit takes its own --now-unix-ms and re-checks the scope window and the intersection window. Nothing caches the earlier verdict. An intersection computed while everything was fresh is denied the moment it is admitted outside a window, which is what makes expiry a deny rather than a stale accept.

Expiry propagates downward, never upward. The intersection sets its own expiresAtUnixMs to the minimum of every contributing manifest expiry and the treaty expiry, so shortening one participant's ladder shortens the shared surface on the next recomputation.

Revocation works through the digest graph rather than through a mutation. The scope pins revocationEpochSha256 and trustBundleSha256, and both sit inside treatyScopeSha256. A new revocation epoch or a new trust bundle means a new scope record, a new scope digest, and therefore a new intersection digest, which invalidates every admission report, bilateral invocation, and buyer packet that pinned the old values. There is no in-place renewal and no amendment of a live scope: a changed treaty is a different treaty, and the whole chain is recomputed from intersect forward. Because the binding is a digest comparison, a stale artifact does not go unnoticed; it fails with chio_federation_treaty_intersection_mismatch.

Walkthrough

Two kernels, did:chio:buyer and did:chio:vendor, share one class, billing.charge. The buyer ladder declares it guarded, non-destructive, totally-ordered, coSign: none, requiring workflow_receipt. The vendor ladder declares the same class receipt_backed, destructive, totally-ordered, coSign: bilateral_required, requiring receipt_lineage.

Step one computes the shared surface. Pass one --manifest per participant; the count must match the participant list exactly. The fold climbs on three fields at once. The mode rises to the vendor's receipt_backed, the class becomes destructive because one side said so, and the co-sign requirement tightens to bilateral_required. The evidence lists union rather than intersect, and participantModes preserves what each side actually declared:

$ chio federation treaty intersect \
    --treaty-scope ./treaty-scope.json \
    --manifest ./buyer-ladder.json \
    --manifest ./vendor-ladder.json \
    --now-unix-ms 1800000001000 \
    --report ./ladder-intersection.json
$ cat ./ladder-intersection.json

{
  "schema": "chio.federation.ladder-intersection.v1",
  "intersectionId": "treaty:buyer-vendor:billing:1800000001000",
  "treatyId": "treaty:buyer-vendor:billing",
  "participantKernelIds": [
    "did:chio:buyer",
    "did:chio:vendor"
  ],
  "ladderManifestSha256s": [
    "557d14d63b73898662db51fa1f4981ba78298c8f0531f4fca6b400f2c928b610",
    "040f8fbeb0a133bfbf6c0dc534ba2d7d89c010b18e3c04be72da0c04bde8bc01"
  ],
  "generatedAtUnixMs": 1800000001000,
  "expiresAtUnixMs": 1800003600000,
  "actionClasses": [
    {
      "actionClassId": "billing.charge",
      "mode": "receipt_backed",
      "destructive": true,
      "consistencyModel": "totally-ordered",
      "coSign": "bilateral_required",
      "evidenceRequired": [
        "receipt_lineage",
        "workflow_receipt"
      ],
      "participantModes": {
        "did:chio:buyer": "guarded",
        "did:chio:vendor": "receipt_backed"
      }
    }
  ]
}

Step two admits one class. The digest passed to --expected-ladder-intersection-sha256 is the SHA-256 over the canonical JSON of the record above, computed by the verifier, not read off the file with sha256sum. Because the intersected co-sign is bilateral_required, three labels are required, not two: receipt_lineage and workflow_receipt from the ladders, plus the implied bilateral_invocation.

$ chio federation treaty admit \
    --treaty-scope ./treaty-scope.json \
    --ladder-intersection ./ladder-intersection.json \
    --expected-ladder-intersection-sha256 c2aa43202abf74965cf25d66e605b7e9bdb08741fabe1bf65c9a3ebc61f648a0 \
    --action-class-id billing.charge \
    --evidence receipt_lineage=1111111111111111111111111111111111111111111111111111111111111111 \
    --evidence workflow_receipt=2222222222222222222222222222222222222222222222222222222222222222 \
    --evidence bilateral_invocation=3333333333333333333333333333333333333333333333333333333333333333 \
    --now-unix-ms 1800000002000 \
    --report ./admission-report.json
$ cat ./admission-report.json

{
  "schema": "chio.federation.cross-boundary-admission-report.v1",
  "treatyId": "treaty:buyer-vendor:billing",
  "actionClassId": "billing.charge",
  "accepted": true,
  "mode": "receipt_backed",
  "consistencyModel": "totally-ordered",
  "coSign": "bilateral_required",
  "requiredEvidence": [
    "receipt_lineage",
    "workflow_receipt",
    "bilateral_invocation"
  ],
  "presentEvidence": [
    "receipt_lineage",
    "workflow_receipt",
    "bilateral_invocation"
  ],
  "verifiedEvidence": [
    {
      "evidenceClass": "receipt_lineage",
      "artifactSha256": "1111111111111111111111111111111111111111111111111111111111111111",
      "verified": true
    },
    {
      "evidenceClass": "workflow_receipt",
      "artifactSha256": "2222222222222222222222222222222222222222222222222222222222222222",
      "verified": true
    },
    {
      "evidenceClass": "bilateral_invocation",
      "artifactSha256": "3333333333333333333333333333333333333333333333333333333333333333",
      "verified": true
    }
  ],
  "treatyScopeSha256": "b1ee0d587038d7eef7e95b7ae6c2458ef62fcae96f53b3791847fadbd6f02c93",
  "ladderIntersectionSha256": "c2aa43202abf74965cf25d66e605b7e9bdb08741fabe1bf65c9a3ebc61f648a0",
  "expectedLadderIntersectionSha256": "c2aa43202abf74965cf25d66e605b7e9bdb08741fabe1bf65c9a3ebc61f648a0",
  "checks": [
    "chio_federation.treaty.scope_valid",
    "chio_federation.treaty.intersection_valid",
    "chio_federation.treaty.required_evidence_present",
    "chio_federation.treaty.required_evidence_verified"
  ]
}

checks gains two more entries on the accepted path, required_evidence_present and required_evidence_verified, so the array records how far the sequence got rather than only whether it finished. requiredEvidence is the intersected list in sorted order with the implied label appended, which is why bilateral_invocation lands last here and not in alphabetical position.

Drop any one of those three flags and the command still writes a report, but the report carries accepted: false with chio_federation_treaty_missing_required_evidence and the process exits with a policy error. The denial is durable evidence; the non-zero exit is the operator signal. The run below is a second treaty, whose two ladders both demand governance_receipt, bilateral_invocation and (on one side) receipt_lineage, and it supplies only the first:

$ chio federation treaty admit \
    --treaty-scope ./vendor-call-scope.json \
    --ladder-intersection ./intersection.json \
    --expected-ladder-intersection-sha256 5d96f1d312f046ba9ee42733ee013132b8c67c2b41fc7a0bfb551ce95ac7f51e \
    --action-class-id workflow.destructive.vendor_call \
    --evidence governance_receipt=dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd \
    --now-unix-ms 1800000010000 \
    --report ./admission-negative.json

error [urn:chio:error:policy:decision-denied]: Chio treaty admission rejected request: chio_federation_treaty_missing_required_evidence
context: {"domain":"policy","severity":"error","stability":"stable","string_code":"CHIO-CLI-POLICY"}
suggested fix: Inspect the policy rule path and update the request or policy inputs before retrying.

The exit code is 1 and the report was still written. It names what was required, what arrived, and where the check sequence stopped:

$ cat ./admission-negative.json

{
  "schema": "chio.federation.cross-boundary-admission-report.v1",
  "treatyId": "treaty-buyer-vendor",
  "actionClassId": "workflow.destructive.vendor_call",
  "accepted": false,
  "failureCode": "chio_federation_treaty_missing_required_evidence",
  "mode": "receipt_backed",
  "consistencyModel": "totally-ordered",
  "coSign": "bilateral_required",
  "requiredEvidence": [
    "bilateral_invocation",
    "governance_receipt",
    "receipt_lineage"
  ],
  "presentEvidence": [
    "governance_receipt"
  ],
  "verifiedEvidence": [
    {
      "evidenceClass": "governance_receipt",
      "artifactSha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
      "verified": true
    }
  ],
  "treatyScopeSha256": "d4ea3c7755508e23a866448f815d5b451c9e6a653b1059a058f2719642f08876",
  "ladderIntersectionSha256": "5d96f1d312f046ba9ee42733ee013132b8c67c2b41fc7a0bfb551ce95ac7f51e",
  "expectedLadderIntersectionSha256": "5d96f1d312f046ba9ee42733ee013132b8c67c2b41fc7a0bfb551ce95ac7f51e",
  "checks": [
    "chio_federation.treaty.scope_valid",
    "chio_federation.treaty.intersection_valid"
  ]
}

checks stops at two entries. Scope and intersection validated; the two evidence checks never ran because the required set was not present, so the report says which stage refused rather than reporting a bare failure. The one class that did arrive is still recorded as verified, so a retry knows what it already has. The same fixture and the same failureCode are asserted by the negative lane of scripts/check-chio-treaty-bound-provenance.sh, which fails the build if the admission is accepted. Note also that requiredEvidence here is plainly sorted: both ladders already listed bilateral_invocation, so nothing was appended to the union.

Step three verifies what the boundary actually produced. The admission report is one of five inputs; the other four are the buyer packet, the receipt lineage statement, the cross-kernel continuation, and the bilateral invocation. Every digest the packet claims is re-derived and compared.

$ chio federation treaty verify-packet \
    --packet ./buyer-attestation-packet.json \
    --lineage-statement ./receipt-lineage-statement.json \
    --continuation ./cross-kernel-continuation.json \
    --admission-report ./admission-report.json \
    --bilateral-invocation ./bilateral-invocation.json \
    --report ./buyer-verification-report.json

See also

• Governance Ladder for the per-kernel chio.federation.governance-ladder-manifest.v1 whose digest a treaty pins.
• Federation for where the treaty lane sits among the other cross-operator paths, and for the peer pinning a treaty presumes.
• Bilateral Co-Sign for the DSSE envelope behind the implied bilateral_invocation evidence label.
• FROST Quorum for the threshold signature behind the n_of_m co-sign mode and its implied quorum_signature label.
• Continuation Tokens for the cross-kernel continuation the lineage statement and the bilateral invocation both bind.
• Revocation Epochs and Revocation Oracle for the epoch a scope's revocationEpochSha256 pins.
• Swarm Denial Codes for the wider denial vocabulary the chio_federation_treaty_* codes belong to.