CASAN/docs/architecture/CASAN_EXECUTION_ADAPTERS.md

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.

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.