# 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:

```text
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:

```text
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

```bash
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.