# Sovereign Evolution 2 of 42 — engineering specification

Input: the open items of Evolution 1 (`release_gate.json`, `threat_register.json`). Every item below names its acceptance
test. An item counts as done only when that test fails on the Evolution-1 revision and passes after the change, and
the change is reviewed and deployed to **both** gateway instances.

## Owner decisions needed first (blocking)

1. **D-S46-11 — allowlist precedence on the capability-token path.** Choose one:
   (a) the operator allowlist and `REQUIRE_APPROVAL` always apply, so a token adds a requirement (recommended;
   restriction-only, satisfies I11/I12; changes 9 assertions in `test_mcp_proxy_self_issued_capability.py`,
   `test_mcp_proxy_capability_forgery.py`, `test_mcp_proxy_model_continuity.py`, `test_mcp_proxy_parameter_binding.py`,
   `test_identity_trust_decay.py`, which must then add the tool to their allowlist); or
   (b) a registered identity grant is a deliberate operator delegation, documented as such, and the strict xfails
   become ordinary tests of that rule.
   Acceptance: `test_d11_*` flips from xfail to pass (a), or is rewritten to assert the documented rule (b).
2. ~~T-S17-03 — guard offline fallback~~ — decided and fixed by -17 (9672bdc1, deployed 2026-10-12). Remaining: ship the next SDK wheel so installed SDKs get it.
3. **T-S17-05 — kernel enforcement on the hosted path / eBPF overclaim in IP recalc V38** (owner decision; see s17).

## Engineering work

| # | Item | Invariant | Acceptance |
|---|---|---|---|
| E2-1 | Bind the hosted pipeline's agent/tenant to the **authenticated** API-key principal rather than `_cain_agent` / `_cain_tenant` arguments (T-S46-05). | I6 | Test: a proof for agent A presented on agent B's API key → DENY, even when `_cain_agent=A`. |
| E2-2 | Shared, durable single-use store for proof and capability nonces across blue/green and restarts: SQLite with `INSERT ... ON CONFLICT` under WAL, re-read on every consume, and a failed write = DENY (T-S46-06). | I10, I14 | Two-process test: the same proof sent to two interceptor processes → exactly one ALLOW; disk-full simulation → DENY. |
| E2-3 | Hosted proof stage checks the policy: `policy_epoch` equals the registry's current epoch and `policy_ir_digest` equals the active policy digest. | I7 | Test: proof minted under epoch 1, registry at epoch 2 → DENY `EPOCH_MISMATCH`. |
| E2-4 | Make the signer pin mandatory in `z3_solver_gate.verify_proof_action`, `attestation_bound_pca.py`, `swarm_protocol.py`, and `ProofCarryingActionVerifier` (`trusted_issuer_keys` required) (D-S46-12). | I3 | Each: unpinned call → refusal; existing callers updated to pass the pin. |
| E2-5 | Re-verify PROVED at the boundary or bind it: either re-run `PolicyIRSMTVerifier.prove_action_authorization` against the active policy (timeout → DENY), or require the proof's `formula_digest` to match a digest recomputed from the active policy. | I8 | Test: signed PROVED claim whose formula does not match the active policy → DENY. |
| E2-6 | Durable, request-bound decision record at MCPGate: `request_id` → decision → permit consumption → downstream outcome, hash-chained with an append that fails closed (T-S17-06). | I14, evidence | Tamper test: delete, reorder or duplicate a record → `verify_chain` reports it; conflicting terminal outcome → refused. |
| E2-7 | Wire the authorization suites into CI (`.github/workflows/ci.yml`), including the four `test_sovereign_e1_*.py` files. | I15 | CI job fails when any E1 regression test fails. |
| E2-8 | Test hygiene: a session-wide conftest guard that refuses writes under `/root/.cain` and `/app/data` during pytest. | evidence | Running the suite leaves those directories' mtimes unchanged. |
| E2-9 | Implement the action-request / decision schemas (`schemas/`) on one live path: MCPGate emits `cain.sovereign.decision/1` and validates it before forwarding. | I1, I5 | Schema-validation failure → DENY; a golden-file test. |
| E2-10 | Model–code correspondence: generate `formal/authorization_model.py` predicates from a table that the tests also consume, so a code change that is not mirrored in the model fails a test. | method | A mutation of one stage check that is not mirrored in the model fails CI. |

## Out of scope for Evolution 2 (recorded so it is not lost)

Kernel-level enforcement on the hosted path (T-S17-05: requires seccomp-unotify / LSM / microVM work and an owner
decision on infrastructure), third-party audit, and hardware attestation.
