# CAIN-42 governance data plane

AGENT PROPOSES -> CAIN AUTHORIZES -> MCPGATE ENFORCES -> SYSTEM EXECUTES -> EVIDENCE REMEMBERS

## What changed

Before this evolution, every recorded decision on the hosted Fabric waited for its own PBFT round on
the live cluster `cain-mr-01` (production runs with `CAIN_FABRIC_CONSENSUS=1`). The measured cost is in
`baseline/hosted_fabric_baseline.json` and `governance/live_run.json#baseline_per_call_pbft`.

The quorum now commits authority once per window instead of once per call.

```
CONTROL PLANE (asynchronous, one leader worker via a sqlite lease)
  grant (admin API) -> AuthorizationSnapshot -> PBFT commit of its sha256 (never its contents)
    -> gateway verifies the commit QC itself (>= 2f+1 pinned Ed25519 signers, exact digest)
    -> prepare / validate / stage / hash / commit (sqlite) / publish (atomic reference swap)
  reconciler: desired grants vs published snapshots -> CONFIG_DRIFT_DETECTED / CONFIG_RECONCILED,
    renewals at half-window, stale authority withdrawn when it cannot be re-committed
  evidence: fast-path decision commitments -> RFC 6962 Merkle root -> PBFT commit of the root

EXECUTION DATA PLANE (synchronous, local)
  CONSENSUS stage, only when every earlier stage said ALLOWED:
    snapshot present -> hash recomputes -> quorum commit present -> clock sane -> not expired
    -> tenant/principal/agent match -> revocation epoch (shared DB) -> identity fingerprint (shared DB)
    -> exact capability (service, path; no wildcards; unclean paths refused)
    -> durable anchor enqueue (bounded; full queue = no fast path)
  any miss -> the unchanged per-call PBFT round, which fails closed on its own
```

## Safety properties (each has a test in tests/TEST_RESULTS.json)

- The fast path replaces only the CONSENSUS stage. Policy, tool rules, kill switch, authorization, trust
  and risk still run live on every call. It can never turn a deny, hold or degraded decision into an allow.
- A snapshot authorizes only what a quorum committed. Widening a grant needs a new commit; narrowing or
  revoking bumps the tenant revocation epoch in the shared database and bites on the next call in every
  worker process, with no quorum round.
- A restarted gateway re-verifies every persisted snapshot's commit certificate offline before using it.
- Cluster unreachable: no new snapshot is issued or renewed; the circuit breaker stops retry storms.
- Stated trade: a snapshot committed before an outage keeps authorizing its exact capabilities until it
  expires (default 120 s, maximum 900 s). The per-call path would have refused during that window.

## Feature flags

| flag | default | effect |
|---|---|---|
| `CAIN_AUTH_SNAPSHOT` | off | enables the fast path and starts the control loop (also needs `CAIN_FABRIC_CONSENSUS=1`) |
| `CAIN_AUTH_SNAPSHOT_MAX_PENDING` | 20000 | evidence backlog bound; at the bound the fast path is refused |

Rollback is unsetting `CAIN_AUTH_SNAPSHOT`: the CONSENSUS stage is then the per-call round, unchanged.

## Resource bounds

Event queue 1024 (put_nowait -> explicit rejection), anchor backlog 20000, anchor batch 2048, 256
capabilities per snapshot, TTL 5-900 s, commit timeout 15 s, circuit breaker 3 failures / 15 s cooldown,
exponential backoff capped at 8 s, latency rings 4096 samples.

## Observability

`GET /api/v1/governance/status` (admin): `cain_authorization_latency_ns` p50/p95/p99/p99.9,
`cain_governance_lag_s` (oldest unanchored decision), `cain_snapshot_age_s`, `cain_pbft_commit_latency_ms`,
fast-path hit/miss counts by reason, drift/reconcile/renewal/circuit counters, queue depth, pending anchors.
`GET /api/v1/governance/events` (admin): CONFIG_DRIFT_DETECTED, CONFIG_RECONCILED, REVOCATION_EPOCH_BUMPED,
CIRCUIT_OPENED, SNAPSHOT_PUBLISH_REFUSED, SNAPSHOT_REJECTED_ON_LOAD. `GET /api/v1/governance/anchor/{id}`
(public, hashes only): the RFC 6962 inclusion proof of a fast-path decision.

## PII span pipeline

`pii-redactor/pii_spans.py`: every pattern scans the original buffer once, matches become
(start, end, class) spans, overlapping spans are merged (never dropped), and the output is built in one
join. The verification re-scan is kept. Measured in `benchmarks/pii_span_bench.json` and
`mcpgate/pii_accuracy.json`. Built and tested, not wired into the pii-redactor service.

Fixed in the sequential redactor as well: a valid card followed by a phone number was one greedy
26-digit match, failed validation as a whole, and the card was left unredacted while the report said
fully redacted.

## Dependencies

New code imports the Python standard library, fastapi/pydantic (already gateway dependencies) and the
existing CAIN modules `cain_mr_client`, `cain_pbft_engine_33`, `cain_pbft_qc` and `fabric_control_plane`.
Nothing new is installed.
