State Migration Playbook¶
Operational playbook — instantiates Encapsulated Substitutability
Moves or maps the durable state, configuration, credentials, and history a substitute needs to perform the role — with a verified, reversible transfer plan.
A substitute can be behaviorally perfect and still fail on day one because it does not hold what the role requires. State Migration Playbook addresses the data dimension of substitutability: it inventories the durable state, configuration, secrets, and history the incumbent accumulated, and prescribes exactly how each is moved, remapped, recreated, or retired so the substitute can actually take over. Its defining move is treating state — not behavior — as the thing to transfer, verify, and be able to un-transfer: the playbook is only trustworthy if the migration is reconciled against the source and reversible until it is. Where the validation mechanisms ask "does the substitute behave the same?", this one answers "does the substitute have everything it needs to do the job at all?"
Example¶
A company is replacing its identity provider — the system that authenticates every employee and application. The new provider may be behaviorally equivalent, but it cannot log anyone in until it holds the state the old one did: every user account and group membership, every credential (password hashes, API keys), MFA enrollments, and the consent and session history that downstream apps rely on.
The playbook sequences it. Accounts and groups are exported, their schema mapped to the new provider's model, and imported; password hashes are migrated where the formats are compatible and a forced reset is planned where they are not; MFA is re-enrolled; counts and a sample of live logins are reconciled between old and new. Crucially, the old provider stays authoritative and reversible until that reconciliation passes — so a botched import produces a rollback, not a company-wide lockout. The substitute only becomes real once it provably holds the state the role needs.
How it works¶
- Inventory the state. Catalogue what the role depends on: durable data, configuration, credentials and secrets, accumulated history, and any in-flight or transient state.
- Write the transfer rules. For each item decide what moves as-is, what is transformed or remapped across schema and format differences, what is recreated, and what is deliberately dropped.
- Execute the transfer. Migrate — often behind a freeze or a dual-write window — preserving integrity and idempotency so a re-run does not corrupt or double-count.
- Verify against the source. Reconcile counts, checksums, and live samples between source and target before the substitute is trusted.
- Hold a backout open. Keep the source authoritative and recoverable until verification passes, so a failed transfer can be reversed.
Tuning parameters¶
- Transfer scope — move everything, or only the state the role strictly needs. Full fidelity is safer but slower and heavier; a lean transfer is faster but risks leaving behind state something quietly depends on.
- Cutover style — big-bang copy-then-switch versus dual-write or trickle migration. Dual-write shortens the freeze and eases rollback but adds real complexity.
- Transformation depth — lift-and-shift versus remap and clean during transfer. Remapping fixes format mismatches but is where corruption is introduced.
- Verification rigor — count checks versus full checksum and sample reconciliation. Higher rigor catches silent corruption at the cost of time.
- Reversibility horizon — how long the source stays authoritative and recoverable. Longer is safer but delays decommissioning and doubles storage.
When it helps, and when it misleads¶
Its strength is closing the gap that behavior tests never see: the substitute that works in a lab but cannot assume the role because it lacks the state. The playbook makes the transfer explicit, verifiable, and — critically — reversible, which is what lets a team attempt a risky migration without betting the business on a single irreversible copy.
Its failure modes are quiet ones. Silent data corruption or unmigrated edge state — the orphaned records, the one-off configuration nobody documented — often surfaces weeks later, far from the cutover. One-way migrations with no backout trap a team the moment the substitute misbehaves. And the migration is easily run backwards: declaring it "done" on a fixed date without reconciling, because the calendar, not the checksum, drove the call. The discipline that guards against all three is to reconcile source against target before trusting the substitute[1], and to keep the source recoverable until you have.
How it implements the components¶
State Migration Playbook fills the state-transfer side of the archetype — the components a migration procedure produces:
state_and_context_transfer_rule— its core output: the per-item rules for what durable state, configuration, credentials, and history move, are remapped, are recreated, or are retired so the substitute can perform the role.fallback_or_rollback_path— the state backout: keeping the source authoritative and recoverable so a failed or corrupt transfer can be reversed.
It does not validate behavior — conformance_evidence_harness and observable_behavior_specification belong to Golden Master or Trace Comparison and the live comparison to Parallel Run Reconciliation — and the fallback_or_rollback_path it owns is the data backout, distinct from the instant traffic revert that Fallback Switch or Kill Switch provides.
Related¶
- Instantiates: Encapsulated Substitutability — transfers and verifies the durable state a substitute must hold to take over the role.
- Sibling mechanisms: Parallel Run Reconciliation · Golden Master or Trace Comparison · Fallback Switch or Kill Switch · Blue-Green or Canary Replacement · Service-Level Regression Monitor · Supplier or Model Homologation · Contract Test Suite · Capability Equivalence Matrix · Adapter or Facade Layer · Dependency Injection or Plugin Slot
Editorial Notes¶
Form Classification¶
Form family: Protocol, Workflow & Routine
Rationale: State Migration Playbook operates as a repeatable ordered procedure or handoff sequence that coordinates action because it moves or maps the durable state, configuration, credentials, and history a substitute needs to perform the role — with a verified, reversible transfer plan.
Independent corroboration: The frozen evidence defines State Migration Playbook as 'Moves or maps the durable state, configuration, credentials, and history a substitute needs to perform the role — with a verified, reversible transfer plan', so its operative form is Protocol, Workflow & Routine.
Nearest alternative: Intervention, Treatment & Transformation — State Migration Playbook includes features of a direct treatment or transformation applied to a target to change its state or condition, but its defining operation is a repeatable ordered procedure or handoff sequence that coordinates action.
Review outcome: Independent reviewer agreement; medium confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Convergent development
Present-day reach: Multi-domain
Rationale: Verified reversible transfer of durable state is system migration practice.
Related originating lineages:
- Accounting & Auditing — Reconciliation verifies completeness.
- Engineering & Design — Engineering design, reliability, and systems-safety practice supplies a parallel or contributing lineage for the mechanism's defining operation: moves or maps the durable state, configuration, credentials, and history a substitute needs to perform the role — with a verified, reversible transfer plan.
- Organizational & Management Science — Owners coordinate cutover.
Review resolution: The blind reviewers agree that computer_science is the primary origin and differ only on alternate origin disagreement, origin mode disagreement, domain reach disagreement, encyclopedia synthesis disagreement. I preserve every independently explained alternate from both records rather than imposing a numeric cap. I retain convergent because the combined evidence shows independent disciplinary development. The broader reach of multi_domain records portability separately from historical provenance; encyclopedia_synthesis=true preserves the affirmative synthesis judgment where either reviewer identified one.
Encyclopedia synthesis: The exact catalogued form synthesizes established practice rather than reproducing a single standard historical label.
Review outcome: Reconciled after independent review; high confidence.
Notes¶
There are two different rollbacks in a substitution and you usually need both: the state backout this playbook owns (restore the prior data) and the traffic revert a Fallback Switch or Kill Switch or Blue-Green rollout provides (send work back to the incumbent). A traffic revert to a substitute whose state has already diverged can be worse than no revert at all, so the two must be planned together. This playbook is also the prerequisite for Parallel Run Reconciliation, which cannot stand up its twin until the state is transferred.
References¶
[1] Sato, D. "Parallel Change". martinfowler.com (2014). Supports delaying exclusive reliance on a replacement until it has been incrementally migrated and tested. registry ↩