Skip to content

Rolling State-Migration Workflow

Process / workflow — instantiates Mobile-Defect Reconfiguration

Carries a whole substrate from its current arrangement to a target one in overlapping local increments, keeping old and new interoperable throughout and logging every move, so the system migrates without a big-bang cutover.

This is the end-to-end campaign that moves an entire substrate from where it is to a named target — one overlapping increment at a time, never taking the whole system down. It states the target configuration explicitly, orchestrates the many local moves (each performed by the glide and handoff primitives) so that old and new representations coexist and interoperate during the transition, and keeps a durable lineage record of every step for resumability and rollback. Its defining contribution among its siblings is ownership of the whole route and its ledger — the target and the audit trail — rather than any single move. The shape it runs in is the expand–contract (parallel-change) pattern: add the new alongside the old, migrate across, then retire the old.

Example

A service must change its users table primary key from a 32-bit to a 64-bit id — a change that, done as one ALTER, would lock the table for hours. The workflow runs it as expand → migrate → contract instead. Expand: add the new 64-bit column and dual-write both. Migrate: backfill existing rows in the background and shift reads to the new column, batch by batch, while the lineage log records each batch as verified. Contract: once every reader and writer uses the new key and the log shows 100% backfilled, drop the old column. Throughout, both representations stay valid so the application never sees a break, and because each increment is logged, a mid-run failure resumes from the ledger rather than restarting. A structural change lands with zero downtime and a complete trail of what happened when.

How it works

  • Specify the target. Pin down the exact end arrangement — the schema or configuration the substrate is migrating to.
  • Keep old and new interoperable. Run the expand→migrate→contract shape so both representations are simultaneously valid; that overlap window is precisely what lets the front advance without a cutover.
  • Drive in resumable increments. Move the substrate through in idempotent batches, delegating each local move to the glide/handoff primitives.
  • Record lineage. Log every increment — what changed, when, verified — so the process can pause, resume, or roll back from any point.

It owns the orchestration and the bookkeeping, not the physics of an individual move.

Tuning parameters

  • Batch size — units per increment. Larger finishes faster but widens blast radius and lock time.
  • Interoperability span — how long old and new coexist before contracting. Longer is safer but doubles maintenance and courts a permanent straddle.
  • Cutover point — when reads shift to the new representation. Early surfaces new-side bugs sooner; late delays the payoff.
  • Lineage granularity — how finely progress is logged. Finer resumes cleanly but adds overhead.
  • Pacing / throttle — how fast increments run against a live system. Faster completes sooner but competes with production load.

When it helps, and when it misleads

Its strength is turning a change too large for one cutover into a paced, resumable, auditable process that never interrupts service, with failures resuming from the ledger instead of restarting from zero. Its signature failure is the migration that expands but never contracts — reads and writes straddle old and new indefinitely because nobody does the cleanup, leaving permanent doubled surface and complexity; an abandoned run likewise strands the substrate half-converted.[1] The discipline is to treat the contract phase as part of the plan rather than an optional epilogue: gate "done" on the lineage record showing the old representation fully retired, and put a deadline on the interoperability window so the straddle cannot become the permanent state.

How it implements the components

  • target_configuration_specification — the explicit end-state the workflow drives the whole substrate toward.
  • history_and_lineage_record — the durable move-by-move ledger (what changed, when, verified) that makes the migration resumable, roll-back-able, and provably complete.

It does not perform the individual local move (local_move_legality_rule, propagation_corridor_map — Localized Defect Glide Method), render live progress (progress_and_damage_metrics, substrate_state_map — Mobile-Defect Progress Dashboard), or verify the residue behind the front (behind_front_state_verification — Residual-Defect Scan).

Notes

The lineage record is not bookkeeping garnish — it is what separates a rolling migration from a risky string of manual changes. Without a durable, per-increment ledger you cannot safely resume a failed run or roll back a bad one, so the value of the workflow lives as much in its audit trail as in the increments themselves.

References

[1] The expand–contract pattern (also known as parallel change): introduce the new representation alongside the old, migrate readers and writers across, then retire the old. Its documented failure mode is stopping after "expand" — leaving both representations live indefinitely — which is why the contract phase is treated as mandatory rather than optional. ↩