# CAIN-42 Evolution 14 — Reference Architecture
## Governed Capability, Skill & Tool Supply-Chain Fabric

Status: **TESTED library, PRE-PRODUCTION.** Implementation: `cain45/l5/capability.py`, with small additive changes
to `cain45/l5/kernel.py` (E8 token capability bindings) and `cain45/hypervisor.py` (restriction-only
`capability_gate` hook). Tests: `tests/test_cain42_e14_{capability,adversarial,end_to_end}.py`. Clean-room
verifier: `scripts/cain45/verify_e14.py`. Evidence: `clawx-site/evidence/e14-capability-governance-2026-09-28/`.

### Where E14 sits

```
E9  AGENT IDENTITY / PASSPORT
 ↓
E10 COLLECTIVE GOVERNANCE
 ↓
E11 INTENT / COMMUNICATION
 ↓
E12 PERCEPTION / EVIDENCE
 ↓
E13 GOVERNED COGNITION / DECISION        GovernedDecision (signed, state machine)
 ↓
E14 CAPABILITY / SKILL / TOOL GOVERNANCE  admission → passport → grant → lease → decision binding
 ↓
E7  CONSEQUENCE GOVERNANCE                CapabilityConsequenceVector → consequence_vector + gate
 ↓
E8  ACTION COMMIT BOUNDARY                CapabilityAwareCommitBoundary (18 checks) → ActionCommitBoundary
 ↓
GOVERNANCE AUTHORIZATION TOKEN            binds capability / manifest / lease / sandbox / credential / binding digests (strict)
 ↓
MCPGATE                                   hypervisor capability_gate → E7/E8 hooks → cain.mcp_proxy interceptor
 ↓
EXECUTION
 ↓
EVIDENCE                                  commit records, kernel evidence chain, supply-chain graph, replay record
```

### Components (all in `cain45/l5/capability.py`)

| Part | Object | What it does |
|---|---|---|
| 1 | `GovernedCapability` | Canonical manifest; `capability_id = "cap:" + H(type, name, version, publisher, artifact, implementation)`; `manifest_digest` over every material field; `integrity()` refuses a claimed id/manifest that does not match its own fields. |
| 2 | `CapabilityPassport` | Signed by the admitting fabric (never by the agent): identity, provenance, artifact, dependencies, permissions, trust state, policy bindings, authority requirements, execution conditions, version history, mutations, revocations, security metadata. |
| 3 | `GovernedSkill`, `SkillAdmissionController` | A skill must declare what it requests and name a sandbox before the fabric's admission pipeline runs. |
| 4 | `GovernedTool`, `ToolManifest` | Protocol, endpoint, provider, data classes, rate/resource limits — all covered by the manifest digest. |
| 5 | `GovernedPlugin`, `GovernedConnector` | Treated as hostile until admitted; a plugin that combines `CREDENTIAL_ACCESS` with `AUTHORITY_GRANT` is refused at admission. |
| 6 | `CapabilityGrant`, `effective_capability` | Signed; `scope ⊆ issuer_authority` and `scope ⊆ declared permissions`; effective capability = **intersection** of identity, delegated, policy, trust, trajectory, environment, risk, budget envelopes (missing envelope = empty). Reuses the E13 intersection. |
| 7 | `CapabilityLease` | ≤ 120 s, signed, binds agent, trajectory, decision, authority, policy, risk, evidence, sandbox, credential, scope, nonce, sequence. Expiry, revocation, renewal (new nonce), revalidation, emergency stop, trajectory invalidation, capability-mutation invalidation. |
| 8 | `CapabilityCompositionGraph`, `CompositionRiskEngine` | Evaluates the combined power surface (an agent's leases, or a collective's union — splitting a pair across agents does not hide it) and chains in a `feeds` graph. |
| 9 | `CapabilityConsequenceVector` | Maps capability metadata into the E7 `consequence_vector` and `gate`; unknown reversibility raises uncertainty; cross-tenant exposure is a denial. |
| 10 | `CapabilityDriftEngine` | UNCHANGED / EXPECTED_CHANGE / MATERIAL_CHANGE / SUSPICIOUS_CHANGE / REVOKED / UNKNOWN; every class except UNCHANGED invalidates leases. |
| 11 | `CapabilitySupplyChainGraph`, `audit_supply_chain` | PUBLISHER → SOURCE → REPOSITORY → BUILD → ARTIFACT → DEPENDENCIES → PACKAGE → CAPABILITY → AGENT → DECISION → EXECUTION → EVIDENCE; 12 finding codes. `VULNERABILITY_INTELLIGENCE = UNKNOWN`. |
| 12 | `AttestationProvider` | Software/configuration provider implemented; TPM / TEE / secure-boot / confidential-computing slots return NOT_IMPLEMENTED. |
| 13 | `CapabilitySandboxProfile` | Default DENY over 15 controls; normalized paths; exact hosts; `confinement_mapping()` says what `cain45.confine` enforces at OS level vs policy only. |
| 14 | `CapabilityCredentialBinding` | Reference only (`credref:`), raw secrets refused, TTL ≤ lease, bound to capability/agent/trajectory/purpose/scope. `authority_from_credential` always returns no authority. |
| 15 | `GovernedModel` | Model output is `CONTEXT_INPUT_TO_GOVERNANCE`, never authority. |
| 16 | `SubagentCapabilityBoundary` | child ⊆ parent (E8 `CapabilityRatchet` subset rule), TTL/budget/risk only shrink, depth ≤ 3. |
| 17 | `CapabilityRevocationRegistry` | Propagates to grants, child grants, leases, agents, subagents, collectives, pending decisions, queued actions, credential bindings and E8 tokens (via `AuthorizationRegistry.revoke`). |
| 18 | `CapabilityDecisionBinding` | decision + capability + manifest + authority + policy + risk + intent + evidence + lease + action; any change or missing value → `RE_ADJUDICATE`. |
| 19 | `CapabilityAwareCommitBoundary` | 18 checks, then E8 authorize + commit against live capability digests (TOCTOU re-check), then consume + execute. |
| 20 | lifecycle | DISCOVERED → IDENTIFIED → PROVENANCE_CHECKED → ATTESTED → EVALUATED → ADMITTED → GRANTED → LEASED → INVOKED → OBSERVED → REVALIDATED → RENEWED; failures REJECTED / SUSPENDED / EXPIRED / REVOKED / DRIFTED / COMPROMISED / UNKNOWN. |
| 23 | `authorization_record`, `replay_capability_authorization` | Signed canonical inputs + outputs; replay names the changed component. |
| 26 | `CapabilityAdapter`, `MCPProtocolAdapter` | Framework-neutral contract; MCP reference adapter. Other frameworks NOT_IMPLEMENTED. |

### Integration points (additive, restriction-only)

* **E8 kernel** (`kernel.py`): `GovernanceAuthorizationToken` gains `capability_digest`,
  `capability_manifest_digest`, `capability_lease_digest`, `sandbox_profile_digest`, `credential_binding_digest`,
  `capability_binding_digest`. They enter the signed body only when set (older tokens are byte-identical).
  `check_bindings` treats them **strictly**: absent live value → `*_UNVERIFIED`; different → `*_CHANGED`.
* **Hypervisor** (`hypervisor.py`): `AgentHypervisor(capability_gate=...)` is consulted after the hypervisor's own
  checks and before the E7/E8 hooks and MCPGate; an exception is a denial.
* **E13**: two bench scenarios that were forced true are now real tests (see the limitations register).

### Deployment reality

Nothing in E14 is deployed on the hosted gateway (`HOSTED_SERVICE = NOT_IMPLEMENTED`). It runs where the CAIN-45
hypervisor / L5 library runs, in-process. Performance numbers are single-host. See the threat model and the
capability-governance document for the trust/authority model and the classified limitations.