Migration harness: real Migrator (headless, isolated, Friction Log) #1537

Parent

#1540

Source of truth

ADR PR #1575 contains the Migration Harness ADR and context glossary. The ADR is the authoritative architecture, requirements and acceptance contract; #1540 is the tracking epic. The design in #1575 is merged and accepted; implementation completion is tracked separately. Implement against the accepted ADR revision. This ticket scopes the work and does not redefine shared contracts.

What to build

• Build the real headless Migrator adapter with configurable time/turn limits and the ADR's default model/settings.
• Use the host model broker, restricted Migrator Environment and runtime supervision contracts; no model credentials or model-service access enter the command environment.
• Reuse the concrete isolation backend selected and demonstrated in Migration harness: Run skeleton and behaviour checks on Legacy Data #1534; verify the same enforcement and supervision around every real Migrator invocation.
• Provide only the copied guide, Fixture App workspace with its prepared README, assigned credentials and the Friction Log schema/output path. Do not supply prior Friction Logs, identifiers, diagnoses, workarounds or a friction catalog in the prompt or workspace. Support alternate agent commands through the same contract.
• Write a structured Friction Log keyed by guide section slug plus a short issue slug, following the ADR's rules, and capture Run Reports for redacted evidence export.

Acceptance criteria

• One real guide-only Run for each store procedure (DynamoDB and Postgres v2-to-v3) completes with a Run Report identifying the procedure and a valid Friction Log, including the explicit empty-list case.
• Probe every Protected Resource and show denials/absence through trusted harness assertions and the required enforcement event stream; absence checks use harness-owned probes rather than fabricated access events.
• Explicitly deny the Migrator access to its own Oracle Stores, other Runs' Store Sets, forbidden hosts and the model service.
• Assigned loopback endpoints, npm installation and encryption succeed; unrelated host-loopback ports and Docker sockets remain inaccessible.
• Model credential canaries are absent from environment and mounted files; do not equate an absent-variable read with a violation.
• Real invocations run the startup probes and host-owned supervisor; broken monitoring fails setup and successful forbidden-access events stop execution.

Blocked by

• Migration harness: Run skeleton and behaviour checks on Legacy Data #1534

Completion dependencies and priority

Adapter development can start after #1534. Completion of the two-store acceptance additionally requires #1604 (DynamoDB guide), #1603 (Postgres guide) and #1605 (Postgres Run extension). These gate integration completion, not initial adapter development. Deliver the tested guide first; this agent adapter is not a prerequisite for that milestone. No v4 work is required.

Delivery status — 2026-11-12

The source guide is #1620 at a6d33c9e8f7acc65158553bbce5b7b6ff62165a2, SHA-256 6e730d48fdba975c55273f3c9d58f27c21928babe8607c862a6b0eca996bc242. It now generates the complete standalone PostgreSQL script from the executable module, verifies Protect source plaintexts independently against Stack, batches SDK operations, and resolves catalog identities without physical-column/search-path assumptions. The explicit credentials snippet and immutable links are corrected.

Current live E2E passed: 14 guide tests on each of PostgreSQL 17 and 18, including the actual pasted script, dropped-column fixture, both restricted search paths and missing-primary-key refusal. The combined PG17 suite passed 27 tests. Local verification passed 74 focused tests, strict example/snippet compilation against published packages, typechecking and the lint gate. The previous PG17 fixture failure reproduced once; the test-only follow-up explicitly targets public and checks setup before migration.

Customer documentation is synchronized in cipherstash/docs#118 at signed 5259b44995b09ab7d3cac62003e77d3b68c58c00, pinned to the byte-identical guide at e7d6a02d3. Source equivalence, types, content, links, scoped lint, production build and docs CI pass. Two pre-existing full-docs-lint formatting errors remain. Nothing is merged or deployed.

Historical guide-only evidence

One fresh sample per store passed at harness 5261d3a5c0ae6a4750a7a1102d08436a1d314725 against previous guide hash 46106cc0a71dbeb757bcb0b3889c6fc5741bac201afe807ed8cde0a035d3d649, using the existing Colima harness VM outside CI. These runs preceded the canonical-script repair and do not validate the current guide:

Runtime: Claude Code 2.1.322, resolved model claude-sonnet-5-5. Both retained complete private command/response artifacts. Independent review confirmed the actual guide-read response hash, use of the staged friction schema, no supplementary documentation supplied to the model, and no successful forbidden-access events. Filesystem README events remain conservatively marked possible; npm extraction produces those events, and command/response review is the evidence for the guide-only claim.

Report SHA-256 digests: DynamoDB 2c081ffc88daed4969d64907a87fe8fbad5f3a20f5efd7ea00d9232ca439587b; PostgreSQL 52fe3656562fda47c371e9a2a634e97de2733afa80dc7bac067f9ff0694e0ded. Raw artifacts remain private; secrets are not published.

Earlier attempts remain recorded with their original outcomes: PostgreSQL exposed the missing inline preflight, and a subsequent DynamoDB attempt passed behavior but produced an invalid section slug. The harness now supplies its exact section catalog/schema; no historical failure was relabelled.

Remaining work

These are one clean sample per store, not ADR convergence or customer staging proof. #1538/#1539 remain unimplemented. Customer schema/query inventory and actual AWS/PostgreSQL operational rehearsal, including cutover and rollback, remain required before customer-specific sign-off.

Harness integration remains pending required reviews and the acceptance-evidence follow-ups below. Deterministic CI at the schema-update heads reproduced an intermittent unmatched vfork observer continuation before behavior checks; signed repairs 62b09150f and 9ed2ff135 supply explicit PID tracing and identify the actor independently of strace's temporary capability-probe children. A red regression reproduced the helper-PID failure; independent review, 31 supervisor tests, 131 base tests and 220 combined tests pass locally (21 credentialed tests deferred to CI). The preceding heads repeatedly failed on missing actor-exit records, despite one passing retry. Current adapter head 7e12eaa0d09b8e0f28d7335e765109b975ab95cb passed current-head CI. All nine isolation and nine Test JS workflows across the five repair heads passed without retries. Both PostgreSQL branch logs show 224 passing harness tests, and both adapter logs show 241; all include the complete 21-case live matrix with no harness skips. The successful model evidence above belongs to its recorded harness revision and does not validate a later repair. No merge bypass, real-model CI workflow, paid host, VM restart or production data change was used.

Acceptance audit: four #1537 isolation criteria remain partially evidenced. Follow-up proof must cover each Protected Resource class, actual Oracle/foreign-Run/model-service targets, Docker socket absence or connection denial (the current probe only attempts a file read), and canary absence across actor-visible mounted files. These are evidence gaps, not demonstrated escapes. Startup supervision and active broken-monitoring/forbidden-access controls are evidenced at the recorded model-run revision; later tracing revisions require separate CI validation.