migrate-verify

Migrate Verify

This command implements cutover-strategies.md step 4, "Dual-write, shadow-read": it emits a working differential harness into the customer's own project, in their language, wired to both the source system and SpiceDB, so that a real cutover can run both systems side by side and know whether they agree before a single user's access starts depending on SpiceDB alone.

The distinction that governs everything below: tools/migration-harness/ is ours -- it proves the converter is correct against a corpus this project controls, is never shipped, and has no role here. What this command emits is the customer's -- it proves their migration is correct against traffic this project will never see, and it ships into their repository with no runtime dependency on this one. differential-harness.md's own framing states this exactly: "What ships is a specification, not a service this project operates... built once, by /spicedb-dev:migrate-verify, and then it is theirs to run, extend, and eventually retire." Do not reference tools/migration-harness/'s paths anywhere in what this command emits or tells the user, and do not let a reviewer of this command conflate the two -- they solve different problems for different owners.

This command's own risk shape is different from every phase before it. Phases 1, 2, and 5 produce artifacts a human reviews before anything downstream depends on them. Phase 3 writes to a live system, but only once, behind an explicit confirmation. What this command emits runs continuously, unattended, beside live production traffic, for as long as the shadow-read window lasts. Its failure modes must never surface as a decision that affects a real user -- differential-harness.md's "safety property" is not a nice-to-have here, it is the entire reason this command is safe to ship at all -- and its comparisons must never manufacture a disagreement that isn't real. Two known ways a harness does that anyway, both demonstrated live in the pack's own references, are why every step below cites rather than re-derives its rules:

• Name translation. source-adapter.md's "What getting it wrong looks like, live" section shows one field of one lookup -- reading a split relation's .relation instead of its .permission -- flip a record from AGREE to a candidate DISAGREE on a migration that converted correctly. A harness that reports this as a real regression sends a correctly converted resource type back for rework and repeats the false alarm on every future run.
• Consistency staleness. differential-harness.md's "Diff" section measured a minimize_latency check fired immediately after the write that made it true returning the stale (pre-write) answer in 95.3% of trials at a ~360µs write-to-check gap, collapsing to 0% by 5ms on serve-testing's own hardcoded quantization window -- and states plainly that a real deployment's window (--datastore-revision-quantization-interval, 5 seconds by default) can be far larger. A harness that reports every stale-window disagreement as a genuine defect drowns real ones in noise from the first hour it runs.

Both are handled structurally below, not merely documented: this harness's check/lookup path never reads a .relation field, and every candidate disagreement is reconciled against a captured zedtoken before it is ever finalized.

This is not one of the six pipeline phases (SKILL.md's phase table, phases 0-5). It is the tool cutover-strategies.md names for its own step 4, "Dual-write, shadow-read": that file's own "Where this sits in the pipeline" table lists step 4 as automated, and its step-4 section points here for the harness's mechanics rather than restating them. Do not add a Phase status row for it (step 8, below) -- it sits alongside the six phases, not inside them.

Outputs, written under [project-dir] (placement resolved in step 3) unless a step below says otherwise:

• migration/verify/source_adapter.<ext> -- the pack's observe()/ask() entry points, in the project's own language.
• migration/verify/harness.<ext> -- the Question/Outcome/DifferentialRecord record shape, Diff, reconciliation, and the safety wrapper.
• migration/verify/dual_run.<ext> -- the out-of-band dispatcher and sampling configuration.
• migration/verify/snapshot_to_assertions.<ext> -- turns a batch of confirmed agreements into validation YAML.
• migration-map.json -- updated only if step 3 resolves a call-site language the plan had not recorded, appended to decisions.additional (step 8); this command never writes a phase_status entry -- see step 8 for why.
• migration-plan.md -- updated in place with a coverage record under Deferred / manual, and its rendered sections regenerated from migration-map.json when (and only when) that file changed this run (step 8; this command does not add a Phase status row -- see step 8 for why).