# Evolution 18 — architecture

```
 approver key                enforcer key                          sensor keys (one per process)
      |                           |                                         |
 issue_authorization()     ExecutionTruthBridge.execute()            observer_proc.py  x2
  effect digest      --->   1 verify signatures against PINNED        TREE_DIFF: lstat+SHA-256 before/after
  + object identity           approver public keys                    INOTIFY  : kernel events in between
    (dev, ino, size,        2 re-adapt the call: same effect digest,
     sha256, parent)          same tool, same passport version
                            3 pin every path component (no links),
                              compare with the signed identity
                            4 lock resources, journal INTENT,
                              consume the authorization (once)
                            5 arm sensors  ----------------------------->  arm(root, nonce, bind)
                            6 execute THROUGH the pins; commit guard
                              re-checks revocation/expiry before the
                              mutating call
                            7 collect  <---------------------------------  signed observation
                            8 grade each declared effect, check
                              postconditions, build the graph
                            9 sign receipt, journal OUTCOME
                                         |
                                         v
                 cain-execution-truth-verify/verify.py  (no CAIN imports; reader supplies the keys it trusts)
                 re-derives level and verdict; rejects a receipt that claims more than its records show
```

| File | Role | Lines |
|---|---|---|
| `cain/reality/observer_proc.py` | sensor process; imports nothing from CAIN | ~260 |
| `cain/reality/sensor_trust.py` | sensor client, statement check, per-effect grading, verdict | ~250 |
| `cain/reality/toctou_guard.py` | pinning, descriptor executor, locks, once-ledger | ~240 |
| `cain/reality/causal_graph.py` | typed evidence graph | ~150 |
| `cain/reality/reality_bridge.py` | `issue_authorization` (decision) and `ExecutionTruthBridge` (enforcement) | ~430 |
| `cain-execution-truth-verify/verify.py` | clean-room verifier and CLI | ~400 |
| `tests/evolution18/harness.py`, `corpus.py` | fixtures and the 82-scenario corpus | ~900 |
| `tests/test_evolution18_execution_truth.py` | 100 tests | ~330 |
| `scripts/evolution18/run_evidence.py`, `mutation_run.py` | evidence and mutation runs | ~330 |

## How this sits in CAIN

- It extends Moat 4 (execution provenance) and uses Moat 1/2 objects from Evolution 17 (`cain.interop`: effects,
  adapters, passports, the authorization record format). No new moat, no second runtime.
- `cain/reality/` already held the REALITY package (observers of *external* systems: HTTP, git, Kubernetes, Postgres;
  trust classes R0–R6; a ground-truth certificate). Evolution 18 adds observation of the *local* effects of one
  executed action. The level names map onto the existing classes (`SELF_REPORTED`=R0, `INSTRUMENTED`=R1,
  `EXTERNALLY_OBSERVED`=R3, `INDEPENDENTLY_CORROBORATED`=R5). The package `__init__` is unchanged; the new modules
  are imported by path (`cain.reality.reality_bridge`).
- Invariants: the agent proposes (a tool call); the approver decides (`issue_authorization`); the enforcer enforces
  and holds no approver private key (test `test_enforcer_holds_no_approver_private_key`, corpus AB-04); the system
  executes through pins; the evidence is the receipt. No authorization, no execution (corpus AD-02).

## What it is not wired to

Nothing in the hosted gateway, MCPGate proxy or TALOS gate calls this code. It is a library with tests. The live
MCP stdio path is being connected to the TALOS gate in Sovereign Evolution 8 by another session; connecting this
observation layer behind that gate is the next integration step, not something this evolution did.