CASAN/docs/migration/CASAN_ASSURANCE_KERNEL_MIGRATION.md

CASAN Assurance Kernel Migration

Scope

This migration preserves existing native and Agentic Bridge protocols while adding canonical kernel envelopes and changing unsafe defaults. It is designed for incremental adoption; no big-bang H1–H7 rewrite is required.

Behavior changes

1. H2 registry enforcement defaults on in enforce mode.
2. A missing or failed H2 dependency denies in enforce mode.
3. High-impact action classes use deterministic risk floors and require actor, approval and evidence.
4. Failed side-effecting single-step execution defaults to halt in enforce or production mode.
5. Enforce/production sandbox execution refuses timeout/static-only fallback.
6. Networked/production Control Plane startup requires verified JWT identity; CASAN_CP_TRUST_AUTH_PROXY no longer authorizes header trust.
7. Production certification requires an external signing provider and external immutable anchor.
8. Canonical schema 1.0.0 is dual-emitted with legacy runtime records.

Development migration

Existing loopback development works with:

CASAN_PROFILE=development
CASAN_CP_AUTH_MODE=local
CP_BIND=127.0.0.1

For short-lived compatibility testing only, H2 can be bypassed explicitly:

CASAN_H2_REGISTRY=0
CASAN_AGENTIC_H2_REGISTRY=0

The bypass is high-severity, observe-only/non-certifiable and rejected in production. Prefer registering the tool instead of retaining this setting.

Failure handling can be selected with CASAN_SINGLE_STEP_FAILURE_POLICY=halt|quarantine|require_approval|record_only. Production side effects reject record_only and fail closed to halt.

Production Control Plane migration

1. Export the enterprise IdP's RS256 public key.
2. Configure issuer, audience, claim names and bounded clock skew in runtime.env using infra/production/runtime.env.example.
3. Configure oauth2-proxy to pass access tokens and authorization headers.
4. Set CASAN_CP_IDP_PUBLIC_KEY in casan-prod.env for the read-only mount.
5. Add a digest-pinned CASAN_CP_OAUTH2_PROXY_IMAGE.
6. Remove CASAN_CP_TRUST_AUTH_PROXY from every environment.
7. Configure Vault/KMS and Object Lock provider variables.
8. Run production-preflight.sh before starting Compose.
9. Run managed endpoint smoke with an authenticated enterprise session.

The current API loads a static public key at startup. Coordinate IdP rotation by installing the next public key and restarting the API after token overlap has been handled operationally. Automated JWKS rollover is not yet implemented.

Adapter migration

The native harness and Agentic Bridge already dual-emit to CASAN_STATE_ROOT/logs/kernel/. Existing consumers can keep reading legacy records. New consumers should:

1. Require schema_version=1.0.0.
2. Run the common verifier.
3. Respect the four separate outcome fields.
4. Reject observed-only certification.
5. Treat runtime extensions as optional namespaced data.
6. Avoid certifying legacy runs that have no canonical evidence.

For a new runtime, implement an adapter and pass the complete 10-invariant conformance matrix before advertising kernel conformance.

Audit compatibility

New H5 audit records use v2 hashing with action class and risk factors. The audit verifier and head signer support v1 and v2 records. This is compatibility, not claim upgrading: v1 records do not gain v2 risk evidence retroactively.

Verification commands

python3 packages/casan-harness/tests/assurance-kernel-tests.py
python3 packages/casan-harness/tests/assurance-upgrade-integration-tests.py
bash packages/casan-harness/tests/phase-assurance-upgrade-tests.sh
bash packages/casan-harness/tests/phase-agentic-bridge-tests.sh
npm --workspace packages/casan-control-panel/backend test
npm --workspace packages/casan-control-panel/backend run build
npm --workspace packages/casan-control-panel/frontend run build
bash packages/casan-harness/tests/phase-production-preflight-tests.sh

Redirect CASAN_STATE_ROOT to a temporary directory for legacy suites that write runtime evidence.

Rollback

Code rollback can restore the previous adapters because legacy emission remains present. Before rollback:

1. Stop new runs and preserve canonical/audit evidence.
2. Record the last v2 audit head and external anchor.
3. Roll back API, UI, Nginx and oauth2-proxy as one deployment unit.
4. Do not restore trusted-header identity on a networked deployment.
5. Do not disable production registry, isolation or trust-root requirements.
6. If operational continuity requires emergency local trust, use the explicit break-glass override, retain the critical evidence and do not certify runs.

A rollback that reintroduces production header trust, missing-gate allow, or silent sandbox/trust fallback is not a safe compatibility rollback.

Expected warnings

• Development registry bypass: high severity and non-certifiable.
• Missing H2 in observe mode: degraded assurance.
• Local signer/local ledger: permitted locally, untrusted for production.
• Unsupported runtime intervention: explicit unsupported.
• Legacy evidence without kernel envelope: compatibility-readable but not kernel-validated.