# CAIN ACP Evolution 03 — State Fabric Protocol Specification (v1)

Status: IMPLEMENTATION-TESTED in one process on one host (real ACP ledger, real production PBFT engine
code, in-process network). Not deployed to the live clusters. See `E03_STATE_FABRIC_REPORT.md`.

## 1. Governance state

The authoritative governance state is the `AuthorityLedger` of `cain/acp/ledger.py`: a pure, deterministic
state machine replicated by PBFT. `snapshot()` is its complete, canonical serialization. Every field is
committed by exactly one dimension (an uncovered field is an error, not ignored):

| # | Dimension | Snapshot fields |
|---|-----------|-----------------|
| 0 | governance | genesis, epoch, min_authority_epoch, clock_ms, applied |
| 1 | policy | policy_hash, compatible_policies |
| 2 | identity | principals, agents |
| 3 | authority | authorities (objects, lineage, status) |
| 4 | revocation | revoked (AUTHORITY/AGENT/KEY/CAPABILITY/TOOL/MODEL/ENVIRONMENT/POLICY), halted_tenants, global_halt |
| 5 | trust | trust (oracle-signed, versioned) |
| 6 | risk | risk (oracle-signed, versioned) |
| 7 | replay | consumed_requests, consumed_nonces, seen_transitions |
| 8 | execution | executions (authorized binding, boundary observation, agent report) |
| 9 | containment | contained (AGENT / AUTHORITY / KEY records with full history) |
| 10 | memory | memory (layered governed memory records with history) |

The order is part of schema `cain.acp.stateroot.v1`; new dimensions require a new schema id.

## 2. Encodings

```
canonical(x)     = JSON, sorted keys, separators (",",":"), UTF-8; floats rejected; ints within ±(2^53−1);
                   ASCII object keys
H(domain, x)     = SHA-256("CAIN-ACP-H/" || domain || 0x00 || canonical(x))
SIG(domain, d)   = Ed25519 over ("CAIN-ACP-SIG/" || domain || 0x00 || d[32 bytes])
dim_digest_i     = H("statedim.v1", {"dimension": name_i, "value": {field: snapshot[field] ...}})
leaf_i           = canonical({"dimension": name_i, "value_digest": dim_digest_i})
STATE_ROOT       = RFC 6962 MTH(leaf_0 .. leaf_10)          (0x00 leaf prefix, 0x01 node prefix)
```

## 3. Transition lifecycle and certification

```
PROPOSE   a party signs a Transition (kind, body, at_ms) with the key the ledger rules require
VALIDATE  ordered by PBFT; each replica re-validates at its position in the total order (consensus orders
          bytes, it does not make them valid)
PREPARE / QUORUM / COMMIT   PBFT (cain_pbft_engine_33): COMMIT_QC verified against the replica's pinned
          membership, chained to the previous decision hash, digest-bound to the applied payload
STATE_ROOT  replica applies, computes STATE_ROOT of the resulting ledger state
EVIDENCE  head_k = H("head.v1", {prev, seq, decision_hash, transition_hash, outcome, reason, result,
          state_root}); replica signs ApplyReceipt{cluster_id, replica, seq, decision_hash, transition_hash,
          outcome, reason, result_digest, head, state_root} under SIG("receipt.v1", ·)
```

A result (and the state root it produced) is **certified** when ≥ q distinct pinned replicas signed
receipts identical in every field except `replica`, after discarding any replica that signed two different
receipts for one seq (equivocation). q = ⌈(n+f+1)/2⌉ (N=4→3, N=5→4, N=7→5), so any two quorums share
≥ f+1 replicas. Honest replicas sign only the root they computed; the ledger is deterministic, so a
certified root at seq s is the root every honest replica computed at s.

A verifier learns: WHAT state (root; any dimension by inclusion proof), WHEN (seq, ledger clock), WHICH
epoch (governance dimension), WHO certified it (receipt signers; PBFT QC signers in the evidence log),
WHAT transition created it (transition_hash; the transition itself in the log hashes to it).

## 4. Rules added in Evolution 03

* **Single-use transitions.** An accepted transition hash is remembered for `MAX_TRANSITION_AGE_MS`
  (10 min) behind the ledger clock; replays are `TRANSITION_REPLAY`, older ones `TRANSITION_STALE`.
* **Behaviour consistency.** AUTHORIZED (EXECUTE binding) vs EXECUTED (boundary-signed OBSERVE) vs
  REPORTED (agent-signed REPORT, a claim). `EFFECT_MISMATCH` (executed params ≠ authorized, status ≠
  NOT_EXECUTED) or `REPORT_CONTRADICTS_OBSERVATION` (status/outcome/params differ, either arrival order)
  deterministically contains the agent, its key, and the authority, and sets the agent's trust to 0 at a new
  version. A report never raises trust.
* **Containment.** CONTAIN by one governor, the subject's tenant principal, or a boundary. Contained:
  `AGENT_CONTAINED`, `KEY_CONTAINED` (same key under a new id), `AUTHORITY_CONTAINED`,
  `ANCESTOR_AUTHORITY_CONTAINED`, `ANCESTOR_AGENT_CONTAINED`; a contained agent cannot DELEGATE or write
  memory; an oracle cannot raise its trust. RELEASE needs the governor threshold and enters probation:
  `REVERIFICATION_REQUIRED` until an oracle trust attestation with a version greater than the one at release.
  History is append-only.
* **Governed memory.** MEMORY_WRITE (agent, UNVERIFIED) → MEMORY_OBSERVE (boundary, OBSERVED) →
  MEMORY_VERIFY (oracle, VERIFIED) → MEMORY_ADOPT (governor threshold, AUTHORITATIVE). Strict order,
  tenant-bound, append-only (MEMORY_SUPERSEDE marks, never deletes). Two live VERIFIED+ records for one
  (tenant, key) with different content are a recorded conflict; ADOPT is refused until one is superseded.
  `evaluate()` never reads memory.

## 5. Verification

`verification/acp/verify_state_root.py BUNDLE.json` (zero CAIN imports) checks quorum intersection of the
pinned membership, certifies roots from receipts, rejects forks and seq rollback, discards equivocators,
recomputes the root from a published snapshot, checks dimension inclusion proofs, recomputes the evidence
log head chain, re-hashes every logged transition, and binds certified receipts to log entries. It does
not re-verify PBFT commit certificates and takes replica keys as pinned input.
