Plan: Migration Gate + Verify-Only Boot

Pure classify(applied: &[AppliedRecord], embedded: &[EmbeddedMigration]) → SchemaState (records in, not sets — success is part of the input); async wrappers verify_schema(&self, migrator, floor_check, gate_hint) and the gate-side apply_by_verdict(&self, migrator) implementing the two-consumer table.

Read-only proof obligations (tests): verify creates NOTHING on a missing table; succeeds under a SELECT-only role; acquires no advisory lock; non-42P01 errors preserved.

Proptests (mandatory — universally-quantified comparator): precedence totality (every (applied, embedded) pair yields exactly one state), Ahead ⇒ extras > max(embedded), round-trip Behind→apply→Exact.

Scratch-DB matrix legs (harness precedent crates/craig-db/tests/migration_session.rs): exact / absent table / strict subset (Behind) / strict future suffix (Ahead) / incomparable (Diverged both ways) / interleaved unknown (Diverged) / dirty+mismatch precedence / query-failure passthrough / down-migration filtering.

Migrations ×8: schema_compat_floor create+seed (same timestamp per service; after each service’s current max version).

Bootstrap split (v1 verified schema too late — JWKS + MQ init preceded it and could mask the refusal): bootstrap() splits into bootstrap_data_plane(prefix) → {settings, telemetry, db} and bootstrap_control_plane(…​) → {auth, MQ, …}. Services call: data_plane → verify_schema → control_plane. (Mechanical — the fn already does DB at step 4, auth at 7, MQ at 8; bootstrap.rs:148-197.)

Migrate mode: pub async fn run_migrate_mode_if_requested(env_var: &str, service: &str, migrator: &Migrator) → Result<bool, MigrateModeError> — typed thiserror (no anyhow at a library pub boundary; PrintOpenapiError precedent, lib.rs:266-276), variants for argv / env / telemetry-init / connect / migrate errors. Semantics:

Floor lint: extend validate-migration-constraints — a destructive statement (DROP TABLE/COLUMN, ALTER … DROP) without a same-file schema_compat_floor bump = error.

×8 boot orchestrators: the migrate-mode first line + boot swaps raw run_migrations → apply_by_verdict (boot still applies when Behind — the no-op fallback; this alone already un-bricks rollback fleet-wide via Ahead-tolerance). As built: the two non-serving process modes are dispatched through ONE craig-api helper, run_process_modes_if_requested(service, &migrator, &openapi) — the ordering contract (migrate first, openapi second) and the CRAIG_<SVC>__DATABASE_URL derivation live in one place instead of 8 main-copies (also what keeps the fattest boot orchestrators under the B2 function-LOC budget — clippy’s 40-line lint is file-allowed for these bootstrap fns; B2’s 100-line counter is the one that binds).

Compose gates ×8 in root docker-compose.yml, YAML anchors sharing image: + build: with the app service (image-only gates could run a STALE :local image and exit 0 silently — anchors + the xtask --build path close that; production uses immutable tags/digests, documented). restart: "no"; depends_on: postgres: service_healthy; env = the one DATABASE_URL var. App services gain service_completed_successfully edges. Note: compose gates are NOT keyless as a class — cases/seed still mount field-key.env in the same compose model; the devstack always has the key via xtask provisioning.

cargo xtask migrate apply [--service <name>]: registry-driven; validates names before starting anything; up -d --build locally; bounded polling with container logs on timeout + a kill of the timed-out one-shot (never silently left running); partial-success contract: report per-service, exit ≠ 0 if any failed (additive migrations make partial application safe to retry — recorded in ADR-063 + runbook).

Structural compose invariant test (xtask test over docker-compose.yml; as built: yaml-rust2, not serde_yaml — serde_yaml is archived upstream and yaml-rust2 is already in-tree transitively via the config crate; rationale recorded in xtask/Cargo.toml): every registry service has exactly ONE gate with matching image anchor + DB URL + a service_completed_successfully edge on the app; plus a validate lint: run_migrations callable only from craig-db + the migrate-mode helper (so that post-M3b no serving path applies DDL).

deployment-guide first pass: gate section + budget arithmetic (gates ×8 + old + surge replica worst case replaces the "boot pool is cold" row at :716/:738-741).

×8 boot: apply_by_verdict → verify_schema (+ floor check). Serving binaries now never apply DDL. CHANGELOG (pre-1.0 breaking): external deployments MUST run the gate (the compose graph carries it automatically; k8s = parallelism-1 Job or deploy hook — an init container is NOT equivalent: per-pod, recreates the convoy; ADR-063 says so). As built: the composition lives in ONE craig-api fn, bootstrap_verified(prefix, service_name, &migrator) — data plane → verify_schema (FloorCheck::Enforce, gate hint derived from the service name) → control plane, so the verify-precedes-JWKS/MQ ordering is structural rather than an 8-copy convention; mains are ONE call. BootstrapError gains the SchemaVerify variant. The isolation lint now also forbids .apply_by_verdict( outside craig-db + the migrate-mode helper (no speculative bootstrap allowance — bootstrap verifies, never applies). The poisoned-gate pin asserts compose’s actual diagnostic (didn’t complete successfully, with the older dependency failed to start wording also accepted).

Rollback boundary test (a verifier-tolerance test alone is insufficient): via RUNTIME migrators (Migrator::new(dir), already used in-repo at template_db.rs:291) — apply the FULL set to a scratch DB, then run the N−1 gate (runtime migrator over a truncated dir copy = the old image’s set) → must no-op exit-0 (Ahead), then the N−1 verify → must boot-verdict. Old gate + old app against the newer DB, executable in-battery.

Upgrade-in-place test: an existing seeded volume upgraded THROUGH the gates (no wipe/reseed) with data preserved — the real operator path; reseed is not the upgrade story.

Postgres-only proof ×8: every service binary’s migrate run with Keycloak/RabbitMQ/ field-key/unrelated settings ABSENT (compose run --no-deps or env-stripped exec): covers missing/invalid URL, exact argv, Ahead no-op, Diverged refusal, concurrent double invocation (advisory-lock serialized, both exit 0).

Automated poisoned-gate test (dependent gets "dependency failed to start") — a regression test, not manual MR evidence.

Explicit registry (no grep heuristics — a grep matches docs/definitions/negative tests). The 8 warmable bases: craig_cases_enctest, craig_security_authztest, craig_security_archtest, craig_security_dlqdedup, craig_security_bkfill, craig_security_conflict, craig_financial_1179, craig_rules_archtest — mapped to the 4 unique migration dirs (cases, security, financial, rules); a registry-completeness check fails on an unregistered ensure_template call site. As built, completeness is RUNTIME-ENFORCED (stronger than the unit-test sketch): ensure_template itself refuses a base not in the exported WARMABLE_BASES registry with the registration instruction, so a new call site fails its own first run — grep-free by construction.

Wire into the REAL entrypoints: cargo xtask test (cmd/test.rs:14 — the nextest path) and validate’s phase_devstack_and_tests before the nextest stage. (NOT e2e — that runs Playwright and reseeds AFTER any warm.)

Lifecycle semantics: runs under the existing xtask devstack lifecycle lock (no nested locking when called from validate); requires ports reconciled; no down-stack mutation.

Bounds: cold total + per-base timeout with diagnostics (the observed failure IS cold creation under contention — warm-state ≤2 s is the secondary bar); the 5 security bases share one migration set — warm once, template-copy where the mechanics allow, else document the 5× cost. As built: 3 min total bound + 1 min per-base warn with per-base timings printed; the security siblings DO template-copy (CREATE … TEMPLATE from the group leader, then ensure’s fast verify) — each unique set applies exactly once.

Parity test per unique dir (runtime vs embedded fingerprint ×4, template_db.rs:66-85) + a concurrent post-warm ensure_template + clone-latency leg.