Cross-Org Swarms

Inside one kernel, a delegated task is authorized by chio-swarm-authority: a signed task graph, a continuation token per hop, an attenuation witness chain, and a budget allocation. None of that binds the organization on the other side of a boundary. What binds both is a treaty: chio-federation’s treaty module folds the participants’ signed governance ladders into one intersection and admits a named action class against it, and its bilateral_verifier and frost modules supply the signature the admitted class requires.

The three layers do not subsume one another. A graph can be perfectly signed and still name an action class no treaty admits; an admitted class can still lack the co-signature its row demands. What follows is where they join, from the economy side.

Three verifiers, three refusals

Each entry point below is a separate function with its own error type. A caller that runs one and skips another has checked one thing.

The graph layer is fail-closed at both ends of its argument list. verify_swarm_authority_bundle refuses an empty set of trusted witness issuer keys before it reads the bundle, and refuses a bundle carrying no continuation tokens or no witness chains before it reads a hop. The named refusals are exercised as whole bundles under fixtures/proof-room/swarm-authority/:

• budget-allocations-exceed-pool
• egress-constraint-unsupported
• graph-cycle
• join-parent-set-mismatch
• max-depth-exceeded
• replayed-continuation-nonce
• revoked-task
• route-plan-mismatch
• stale-continuation
• stale-route-plan
• witness-child-scope-mismatch

Swarm Authority walks the bundle and the order of checks; Task Graphs covers the graph object itself.

What the graph carries out of the kernel

A task that reaches anything outside the kernel does so through a signed SwarmRoutePlanReceipt. Four of its fields describe the exit: selectedRoute, bridgeId, protocolTarget, and egressContractId. The verifier takes the prefix of each of the other three and requires all of them to equal bridgeId: the segment before the first colon of the selected route, the scheme of the protocol target, and the segment before the first colon of the egress contract. Three separate error strings distinguish which one disagreed.

egressConstraints must be non-empty and unique, and the accepted vocabulary has exactly one member: deny-private-network. Any other string is refused by name. The receipt is also refused when its attenuationDecision is anything other than accepted, when it has expired against the bundle’s clock, and when its issuer is not one of the pinned witness keys.

Route Plans covers the receipt field by field and what the shipped edges send.

The financial ladder, class by class

A treaty admits action classes, not calls. Each participant publishes a signed governance ladder naming the classes it will take part in and the governance each one carries. The financial domain ladder of spec/CHIO_LADDER.md is the economy’s own set, and it is where the settlement, clearing, and credit classes get their co-signature requirement.

Every class the ladder marks destructive: true sits at receipt_backed or above, which is the manifest’s declared destructive_floor, and none of them uses crdt-commutative. Both are enforced, not conventional: a manifest declaring a destructive class below its own floor is rejected with chio_federation_ladder_destructive_below_floor, and one pairing destructive with commutative consistency with chio_federation_ladder_destructive_crdt_not_allowed. A destructive class with an empty evidenceRequired list is rejected too.

All three quorum classes here are 2-of-3 at scope: treaty. The compliance ladder in the same document raises governance.case_enforce_sanction and governance.roster_rotate to 3-of-5. Those numbers are not free text: the crate’s FROST registry hard-codes a quorum per class, and a roster whose threshold and participant count disagree with a class it lists is refused.

{
  "id": "settle.commitment",
  "title": "SettlementCommitment dispatch",
  "mode": "receipt_backed",
  "destructive": true,
  "cross_org_visibility": "federated",
  "evidence_required": [
    "trust_activation",
    "workflow_receipt",
    "anchor_epoch"
  ],
  "co_sign": "n_of_m",
  "co_sign_quorum": { "n": 2, "m": 3, "scope": "treaty" },
  "consistency_model": "quorum-required",
  "consistency_anchor": "frost-quorum"
}

Governance Ladder covers the five modes and the per-class fields in full.

Two shapes of one ladder entry

The entry above is not the shape a peer sends over the wire. The wire-frozen manifest, published as spec/schemas/chio-federation/v1/governance-ladder-manifest.schema.json and deserialized into GovernanceLadderManifest, is camelCase, forbids unknown fields, and carries a smaller action-class object: actionClassId, mode, destructive, consistencyModel, coSign, evidenceRequired, and the optional coSignQuorum and aliases. There is no crossOrgVisibility, no consistencyAnchor, and no title on it. The schema pins defaultUnknownMode to the constant deny, and the crate checks the same thing again on the deserialized value.

The richer snake_case entry is still load-bearing, in a different place. Each of the seven registered FROST classes hard-codes its own ladder entry in that shape and takes the SHA-256 of the canonical encoding as ladderContractDigest. Every authorization body carries that digest, and validation recomputes it from the registration rather than trusting the body, so a deployment that words one of those rows differently fails with ContractMismatch("ladder_contract_digest").

coSignQuorum is required when coSign is n_of_m and forbidden otherwise, in the JSON Schema and again in the crate. Visibility does survive onto the wire elsewhere: chio.bilateral-signature-slice.v1 requires cross_org_visibility over private, treaty_only, federated, and public, and admits only bilateral_required or bilateral_if_cross_org in its own co_sign enum.

Where the co-signature comes from

The intersection decides which co-sign mode governs a class, and the admission report converts that into a piece of evidence the caller must actually hold. required_evidence_for_action appends bilateral_invocation to the required list when the intersected mode is bilateral_required, and quorum_signature when it is n_of_m. Neither is added for bilateral_if_cross_org, which is what makes that mode conditional rather than mandatory.

The bilateral verifier will not stand in for a quorum. A predicate declaring co_sign: n_of_m through the ordinary path is rejected with co_sign n_of_m requires the strict verifier API with VerifiedFrostAuthorization, and the strict path refuses in the other direction too: supplying a verified authorization alongside a bilateral_required predicate is itself an error.

When an authorization is supplied, bind_frost_authorization_to_predicate binds it to the predicate on five separate axes rather than accepting it as a token:

• The predicate must name a treaty_binding_ref. Without one there is nothing to bind against.
• Its consistency_model must be quorum-required and its consistency_anchor frost-quorum.
• The authorization’s ladder action class must equal the treaty binding’s action_class_id.
• Its scope id must equal the treaty id, and its resource id the predicate’s invocation_id.
• It must be current at the verifier’s pinned epoch, not at the local clock.

TreatyBindingRef is what closes the loop back to the treaty layer. Alongside the action class and consistency model, it carries the SHA-256 of the treaty scope, of the ladder intersection, and of the admission report, so a co-signed invocation names the exact fold and the exact decision it was admitted under.

Bilateral Co-Sign covers the co-signed receipt body and the offline walk; FROST Quorum covers the roster, the one-shot slot, and what verify_for_execution confirms.

The treaty artifacts

Four signed objects carry a cross-boundary decision, each with a published JSON Schema under spec/schemas/chio-federation/v1/.

A treaty scope binds at least two participant kernels, one manifest digest and one public key each, and refuses duplicates in any of the three lists. The fold is strictest-wins on mode and on co-sign, a union on required evidence, and an equality check on consistency model: two participants that disagree there are refused with chio_federation_ladder_consistency_mismatch rather than reconciled. The intersection expires at the earliest of the treaty scope’s expiry and every participant manifest’s.

Three commands drive the same functions from outside the crate: chio federation treaty intersect takes a treaty scope and one --manifest per participant and writes the intersection; chio federation treaty admit takes the scope, the intersection, an expected intersection digest, an action class id, and one --evidence pair per verified evidence class, and writes the admission report; chio federation treaty verify-packet checks a buyer packet against the admission report and the bilateral invocation together. Treaties runs that sequence end to end.

Next steps

• Treaties · the fold, the admission rules, and the worked sequence
• FROST Quorum · the roster, slot, and rotation behind a quorum-required class
• Bilateral Co-Sign · the two-party path and the predicate the verifier reads
• Swarm Authority · the bundle and the order its checks run in
• Bilateral Federation · the per-pair handshake that pins a peer’s ladder manifest
• Bilateral Receipts · the dual-signed record two kernels jointly produce
• Clearing Rounds · Payment Channels · two of the quorum-required classes, with their producers