feat(casan): establish assurance kernel and harden control plane

2026-08-02 23:24:51 +07:00
parent 8b477f3800
commit 5745519126
51 changed files with 4076 additions and 180 deletions
@@ -0,0 +1,95 @@
+# CASAN Execution Adapters
+
+## Adapter contract
+
+An execution adapter translates runtime events into the canonical Assurance
+Kernel envelope without replacing H2, H4, H5 or other existing controls.
+
+```text
+runtime event
+  -> adapter mapping
+  -> ExecutionRun / ExecutionStep / Actor / Action
+  -> PolicyDecision / VerificationResult / EvidenceItem / Outcome
+  -> common verifier
+```
+
+Adapter code lives in `packages/casan-harness/kernel/adapters.py`. The canonical
+schema and policy code must not import a native runtime.
+
+## Native harness adapter
+
+`NativeHarnessAdapter` maps the Bash harness execution identity, action,
+command, actor, environment, policy decisions, evidence and final outcome. The
+native entrypoint in `scripts/bash/casan-harness.sh` continues to emit its
+existing metrics and completion protocol while atomically writing a canonical
+bundle to `CASAN_STATE_ROOT/logs/kernel/`.
+
+If a phase exits non-zero, the harness best-effort emits a canonical failed
+bundle before propagating the original exit code. This emission never masks
+the command failure. A successful run reports execution, assurance and
+certification separately.
+
+The adapter is compatibility code: existing H gates remain the enforcement
+implementation. The kernel does not duplicate them.
+
+## Agentic Bridge adapter
+
+`AgenticBridgeAdapter` maps lifecycle admission, pre-tool, post-tool, telemetry
+and finalize events. The bridge now:
+
+- Uses the shared action classifier and risk floors.
+- Defaults H2 registry enforcement on in enforce mode.
+- Converts missing, unreadable, timed-out, malformed or failed H2 dependencies
+  into structured policy decisions.
+- Distinguishes failed tool outcome from successful telemetry recording.
+- Applies the single-step failure policy.
+- Restricts certification using enforcement mode, assurance strength and trust
+  capability.
+- Dual-emits the canonical bundle alongside its v20 lifecycle records.
+
+The Agentic Bridge remains a single-model integration: it performs admission,
+policy, evidence and finalization but does not invoke a model itself.
+
+## Cross-runtime conformance
+
+`tests/assurance-kernel-tests.py` runs the same invariants through both
+adapters. It proves:
+
+1. Dangerous action classification is identical.
+2. Missing actor identity denies the same high-impact action.
+3. Missing H2 enforcement denies in enforce mode.
+4. Approval and evidence requirements are identical.
+5. Claim/evidence relationships use the same contract.
+6. Observed-only execution cannot be certified.
+7. Execution, assurance and certification outcomes remain distinct.
+8. Correlation and parent causation are preserved.
+9. The same verifier detects evidence tampering.
+10. Runtime details are namespaced extensions rather than kernel assumptions.
+
+The conformance suite currently covers two paths. A future adapter must pass
+the same suite before being described as kernel-conforming.
+
+## Capability negotiation
+
+Adapters declare `canCancel`, `canPause`, `canResume`, `canRollback`,
+`canReduceAuthority` and `canQuarantine`. These are conservative. The native
+harness currently declares no general asynchronous intervention capability;
+the Agentic Bridge declares quarantine support only where its lifecycle can
+represent it. Unsupported interventions return an explicit result.
+
+## Adding an adapter
+
+1. Preserve the runtime's existing security controls.
+2. Map stable run, step, actor, correlation and causation identities.
+3. Use the shared action policy; do not create a weaker parallel classifier.
+4. Emit policy decisions and evidence references, not boolean-only results.
+5. Put runtime-only fields in `casan.runtime.<adapter>` extensions.
+6. Validate with `validate_bundle` and the JSON Schema.
+7. Add the full cross-runtime invariant matrix.
+8. Do not mark legacy or observe-only records certified.
+
+## Residual migration scope
+
+Custom loop runners, graphs and every historical event producer have not been
+rewritten. They may continue using legacy formats, but they cannot inherit
+kernel-conformance claims until they receive an adapter and pass conformance.