# Evolution 2 — Frontier Contract Enforcement: architecture

## Where the contract sits

```
agent (RIG Ed25519 key) ─┐
                         ▼
RIG authority (actions, scopes, delegation parent, runtime digest)      ← the ONLY source of authority
                         ▼
contract: draft → propose → validate → authorize (issuer sig) → activate (agent consent sig)
                         ▼
invoke(request, invocation{nonce, ts, PoP sig})
  1. one SQLite IMMEDIATE transaction: decide() (pure) → [quorum USE cert, optional] → spend use + nonce
     → signed DECISION receipt carrying the CAINContractExecutionBinding digest
  2. evidence policy scitt_required → the decision receipt is logged to SCITT BEFORE execution (no evidence, no run)
  3. E8 ActionCommitBoundary: a single-use token over the action hash and the binding digest. At commit the binding
     is RECOMPUTED from live state (RIG, policy, epoch, contract state, environment); any difference → REFUSED
  4. product adapter runs ONLY inside E8.execute (OpenShell exec, MemVault read/write, SCITT register)
  5. signed OUTCOME receipt (E8 status, result digest) → SCITT
```

The contract **binds** governance state. It never grants anything: issuing fails with `AUTHORITY_AMPLIFICATION` if
RIG does not already cover the action and scope for the agent and every delegation ancestor. RIG is re-checked at
every invocation and again at the E8 commit.

## CAINContractExecutionBinding

`contract_digest, identity_digest, authority_digest, capability_digest, policy_digest, risk_digest, action_digest,
resource_digest, execution_path_digest, environment_digest, model_runtime_digest, tenant_digest, governance_epoch,
nonce, expiration, revocation_state`

`binding_digest = SHA-256("CAIN/contract/v1/binding" ‖ 0x1F ‖ CJ1(binding))`. It is computed at the decision, signed
into the receipt and the E8 token, and recomputed at commit. Changing any field between decision and commit refuses
execution (`test_change_between_decision_and_e8_commit_refuses_execution`, `test_binding_digest_covers_every_field`).

## Modules

| Module | Role |
|---|---|
| `platform-gateway/cain_governance_contract.py` | CJ1 canonical form, validator/compiler, lifecycle (DRAFT … ABORTED), pure `decide()`, receipts (tenant-global chain plus per-contract chain), signed export head, revocation, epoch, diff intelligence (DIFF_TAGS), replay |
| `platform-gateway/cain_contract_keys.py` | root → authority-key certificates, rotation (5 s grace for in-flight signatures), revocation (`compromised=True` invalidates every signature) |
| `platform-gateway/cain_contract_quorum.py` | Byzantine quorum certificates for AUTHORIZE, USE and REVOKE (N = 3f+1 sizes; in-process replicas only; **not used by the gateway**) |
| `platform-gateway/cain_contract_graph.py` | forensic graph and time machine: `known_then` (recorded) vs `known_now` (live) |
| `platform-gateway/routers/contracts.py` | `/fabric/contracts/*`: tenant from `frontier20_gate`; exec invoke and epoch bump are operator-only; agents cannot create, revoke or abort; bodies run off the event loop |
| `sdk/python/src/cainstudio/contracts.py` | client: local canonicalization/fingerprint parity, consent and PoP signing, local root-pinned verify; cannot create authority |
| `scripts/contract_verify_offline.py` | clean-room verifier, zero CAIN imports |
| `scripts/contract_attack_engine.py` | generated mutants from legitimate calls and exports, with positive controls |

## Production topology (as deployed 2026-10-04 09:19Z)

Two gateway processes (blue :8088 and green :8098) behind Traefik on one host. Each tenant has its own directory under
the frontier tenant root, holding `contracts.db`, the E8 registry and the E8 key. Both processes open the same files, so
the use bound, nonces and E8 single-use spend are enforced by SQLite IMMEDIATE transactions across the two processes
(`test_blue_green_processes_share_use_bound_and_e8_registry`). There is no cross-host replication.

## Diff intelligence

`diff_contracts` gives a class (NON-MATERIAL … AUTHORITY-MATERIAL) and direction-aware tags: AUTHORITY_EXPANDING,
AUTHORITY_REDUCING, CAPABILITY_EXPANDING, RESOURCE_EXPANDING, POLICY_EXPANDING, ENVIRONMENT_CHANGING, MODEL_CHANGING,
RUNTIME_CHANGING, TENANT_CHANGING and SECURITY_CRITICAL. An unknown shape is tagged SECURITY_CRITICAL. Any expanding
tag requires fresh consent. Consent carries forward only for annotation-only changes.
