orbyn-data-migration · diff
git:20261026.5ac9638 to git:20261101.8be107b
23 added, 60 removed. Audit A to A.
---
name: orbyn-data-migration
description: "Plan and implement stored-data, schema and writer migrations with compatibility, cutover, retry and recovery evidence. Use for durable format changes; not a routine in-memory type refactor or permission to run production migrations."
---
# Migrate data with an explicit writer boundary
- Read the consuming project's migration conventions, current schema and every
- active reader/writer, including jobs, released clients and cached payloads. Define
- the old/new representation, invariant, migration identity and cutover condition.
- Use [architect](../architect/SKILL.md) for an unsettled model.
-
- For a durable transition, the final design or implementation handoff must identify
- **active writers and versions, allowed writes per phase, the actual enforcement
- point, old-writer rejection/current-writer control evidence, and compatible recovery**.
- Use the [writer cutover method](references/writer-cutover.md). An API flag or lock
- that an old/direct writer bypasses is insufficient. Unknown writer state blocks
- unsafe conversion or retirement, not safe discovery or compatibility work. For a
- pure in-memory refactor, explain why this durable cutover contract is inapplicable.
-
- For incident recovery, the final plan must separately gate reopening and closure
- on reconciled data, user-visible success, and queued/replayed work health. Name
- the operational owner, observation window and stop conditions; missing targets or
- telemetry remain unresolved. Use the [recovery method](../orbyn-ci-design/references/rollout-recovery.md).
- A successful writer control alone does not prove the service has recovered.
+ Read the consuming project's migration conventions and current schema. Use
+ [architect](../architect/SKILL.md) for an unsettled model.
- Choose expansion, backfill, reader/writer transition and retirement only as the
- system needs them. Name what can run concurrently with each phase. A lock helps
- only when all writers honor it; an older deployed service may require fencing or
- shutdown before data conversion. Do not infer deployed writer state from a local
- branch. Retain compatibility for external clients that cannot move atomically.
+ Production execution, backups, operator cutover and irreversible retirement remain
+ within the user's explicit effect scope.
- Make backfills bounded and resumable at a durable cursor or operation key. Account
- for deleted records, partial batches, transactions, unique constraints and evolving
- data while the migration runs. Keep original values or a defined recovery route
- when conversion loses information. Avoid “rollback” instructions that restart old
- writers against an incompatible format.
+ ## Method
- For example, replacing one task time range with multiple sessions changes stored
- records, API shapes, background work and calendar rendering. Define the translation
- and ownership once; several UI adapters cannot establish storage compatibility.
+ 1. **Find every active reader and writer,** including jobs, released clients and cached payloads. Do not infer deployed writer state from a local branch.
+ 2. **Define the change:** old/new representation, invariant, migration identity and cutover condition.
+ 3. **Write the cutover contract.** The final design or implementation handoff for a durable transition must identify **active writers and versions, allowed writes per phase, the actual enforcement point, old-writer rejection/current-writer control evidence, and compatible recovery**. Use the [writer cutover method](references/writer-cutover.md). An API flag or lock that an old/direct writer bypasses is insufficient. Unknown writer state blocks unsafe conversion or retirement, not safe discovery or compatibility work. For a pure in-memory refactor, explain why this durable cutover contract is inapplicable.
+ 4. **Choose phases:** expansion, backfill, reader/writer transition and retirement, only as the system needs them. Name what can run concurrently with each phase. A lock helps only when all writers honor it; an older deployed service may require fencing or shutdown before data conversion. Retain compatibility for external clients that cannot move atomically.
+ 5. **Make backfills bounded and resumable** at a durable cursor or operation key. Account for deleted records, partial batches, transactions, unique constraints and evolving data while the migration runs.
+ 6. **Define recovery.** Keep original values or a defined recovery route when conversion loses information. Avoid “rollback” instructions that restart old writers against an incompatible format.
+ 7. **Exercise it, when authorized,** in a disposable environment: representative old data, a partial/retried migration, legitimate concurrent behavior and recovery. Capture the exact schema/candidate and counts without exposing user payloads. A dry-run query is not a completed data conversion.
+ 8. **Deliver** the migration and caller changes, phase/order, actual evidence and remaining operator steps. Keep the owning product guide current rather than creating a second backlog.
- When authorized, exercise representative old data, a partial/retried migration,
- legitimate concurrent behavior and recovery in a disposable environment. Capture
- the exact schema/candidate and counts without exposing user payloads. A dry-run
- query is not a completed data conversion. Production execution, backups, operator
- cutover and irreversible retirement remain within the user's explicit effect scope.
+ For example, replacing one task time range with multiple sessions changes stored records, API shapes, background work and calendar rendering. Define the translation and ownership once; several UI adapters cannot establish storage compatibility. [Cutting over session writers](examples/session-cutover.md) shows why a backfill is insufficient while a legacy writer remains active, with staged recovery.
- Deliver the migration and caller changes, phase/order, actual evidence and remaining
- operator steps. Use [backend design](../orbyn-backend-design/SKILL.md) for effect
- boundaries and [CI design](../orbyn-ci-design/SKILL.md) for a repeatable qualification
- lane. Keep the owning product guide current rather than creating a second backlog.
+ ## Incident recovery
- ## Worked example
+ The final plan must separately gate reopening and closure on reconciled data, user-visible success, and queued/replayed work health. Name the operational owner, observation window and stop conditions; missing targets or telemetry remain unresolved. Use the [recovery method](../orbyn-ci-design/references/rollout-recovery.md). Confirm recovery through these gates; a successful writer control alone is insufficient.
- For a costly concurrent cutover, use [property verification](../tdd/references/formal-verification.md)
- to model writer admission, durable fencing, in-flight writes, retries and phase
- transitions at their actual atomic boundaries. A useful rule is that an old-epoch
- writer cannot commit after the cutover fence. Replay a counterexample against
- the real storage boundary and assert unchanged effects on rejection. A bounded
- model pass cannot establish that old deployed processes have stopped.
+ ## Independently released consumers
- [Cutting over session writers](examples/session-cutover.md) shows why a backfill
- is insufficient while a legacy writer remains active, with staged recovery.
+ Use the task's [impact map](../how/references/impact-map.md) to identify stored, event, generated and external readers/writers, their owners and supported versions. Pilot representative old/new coexistence and a failed/retried batch before wider backfill. Track durable progress, counts, rejected records and drift without exposing payloads. Reconcile intervening writes and deployment changes before resuming. Fence or drain incompatible writers using the system's actual mechanism, and retire compatibility only after explicit adoption and integrity evidence. A source search or local schema migration cannot establish that old deployed writers stopped.
- ## Independently released consumers
+ ## Read when needed
- Use the task's [impact map](../how/references/impact-map.md) to identify stored,
- event, generated and external readers/writers, their owners and supported versions.
- Pilot representative old/new coexistence and a failed/retried batch before wider
- backfill. Track durable progress, counts, rejected records and drift without
- exposing payloads. Reconcile intervening writes and deployment changes before
- resuming. Fence or drain incompatible writers using the system's actual mechanism;
- retire compatibility only after explicit adoption and integrity evidence. A source
- search or local schema migration cannot establish that old deployed writers stopped.
- Internal APIs without durable/wire changes use the architect's
- [staged change method](../architect/references/large-changes.md).
+ - A costly concurrent cutover: [property verification](../tdd/references/formal-verification.md) to model writer admission, durable fencing, in-flight writes, retries and phase transitions at their actual atomic boundaries. A useful rule is that an old-epoch writer cannot commit after the cutover fence. Replay a counterexample against the real storage boundary and assert unchanged effects on rejection. A bounded model pass cannot establish that old deployed processes have stopped.
+ - Effect boundaries: [backend design](../orbyn-backend-design/SKILL.md).
+ - A repeatable qualification lane: [CI design](../orbyn-ci-design/SKILL.md).
+ - Internal APIs without durable/wire changes: the architect's [staged change method](../architect/references/large-changes.md).