# CAIN HERMES — Architecture

**HERMES = Governance Compilation, Coverage Proof & Enforcement Integrity Fabric.**

CAIN-42 compiles organizational intent into enforceable autonomous-system governance and continuously proves the
deployed enforcement preserves that intent.

## Position in CAIN-42

HERMES is a layer **above and across** existing CAIN capabilities. It adds no new moat and builds no second CAIN.

```
AGENT → IDENTITY → INTENT
      → HERMES GOVERNANCE COMPILER
      → GOVERNANCE SPEC → AUTHORITY GRAPH
      → ARGUS ASSURANCE → IRONCLAD EFFECT CONTRACT
      → CAIN DECISION → MCPGATE ENFORCEMENT → EXTERNAL SYSTEM
      → OBSERVED EFFECT → VERIFIED EFFECT → EVIDENCE
      → HERMES COVERAGE PROOF → DRIFT DETECTION → RECERTIFICATION
      → ATLAS FEDERATED ASSURANCE
```

## Core invariants

- NO GOVERNANCE COVERAGE → NO TRUSTED AUTONOMOUS EXECUTION
- NO SEMANTIC PRESERVATION → NO GOVERNANCE CERTIFICATION
- NO VERIFIED ENFORCEMENT → NO GOVERNANCE CERTIFICATION
- GOVERNANCE DRIFT → RECERTIFICATION OR RESTRICTION
- UNKNOWN GOVERNANCE PATH → FAIL CLOSED

## What already existed (not duplicated)

| Existing | Where | HERMES reuses |
|---|---|---|
| Governance source language + IR + package compiler (`govc`) | `platform-gateway/cain_governance_compiler.py` | conceptually; HERMES adds coverage/proof |
| Policy compiler (non-broadening intersection) | `cain/authority/policy_compiler.py` | conceptual reuse |
| Policy differential verification | `cain/authority/policy_diff.py` | conceptual reuse |
| Deployment enforcement modes | `cain/authority/deployment.py` | conceptual reuse |
| Within-fabric semantic diff + route coverage scan | `platform-gateway/cain_governance_assurance.py` | distinguished from HERMES cross-target proof |
| Component/agent BOM | `platform-gateway/cain_governance_attestation.py` | distinguished from HERMES governance SBOM |
| Last-mile in-flight mutation / network path validator | `cain/substrate/cain_last_mile_enforcement.py`, `scripts/cluster13/` | distinguished from HERMES enforcement integrity |

## What HERMES adds

1. **GovernanceSpec** — a canonical *intent* representation with an order-independent semantic hash and a
   broadening change-set classifier (`cain/hermes/spec.py`).
2. **Governance Compiler** — lowers a spec into per-target controls and a coverage graph (`compiler.py`).
3. **Cross-target Semantic Preservation** — proves a heterogeneous set of controls preserves the intent (`semantic.py`).
4. **Governance Coverage Proof** — requirement→effect chain, consequence-weighted, critical gaps exposed (`coverage.py`).
5. **Governance SBOM** — dependency graph + authority/governance/coverage/evidence/effect impact sets (`sbom.py`).
6. **Governance Drift Engine** — 5 layers, monotonic response ladder (`drift.py`).
7. **Enforcement Integrity Engine** — bypass/stale/dead/shadow/drift detection (`integrity.py`).
8. **Live path** — 3 restriction-only stages in the hosted MCP pipeline + `/fabric/hermes` HTTP surface.

## Enforcement adapters (honest boundaries)

| Target | Enforcement point | Boundary |
|---|---|---|
| MCP | `cain.mcp_proxy / MCPGate` | governs hosted MCP tool calls; not out-of-band process execution |
| A2A | a2a delegation verifier | governs declared A2A delegations; a peer ignoring its own card is not covered |
| HTTP | gateway route policy | governs gateway routes; direct network paths not covered |
| CAIN_AUTHORITY | authority budget + prover | governs authority budgets; not a network control |
| EFFECT_CONTRACT | IRONCLAD EffectContractStage | binds declared effects; an undeclared effect escapes |
| APPROVAL | hosted threshold/quorum stage | governs thresholds; not review quality |

Kubernetes/cloud-IAM/OpenShell/database adapters are **DESIGN / NOT IMPLEMENTED** — no fake integration is claimed.

## Status

See `HERMES_PUBLIC_TRUTH.md`. Same-project tests only; no third-party enforcement target certified.
