suaveplan/openspec/changes/migration-adapters-completion/tasks.md

Tasks — Migration adapters completion

Every checkbox MUST reflect work actually done in this change. Do not retroactively tick boxes for work that was already in main when this change opened. Do not tick a box for a test that doesn't exist or doesn't pin the requirement it claims to verify.

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

Audit Note (2026-05-02)

Status: DEFERRED. None of the proposed additive surfaces exist: no migrationEvents shared bus, no MigrationLockLike / MigrationStoreLike interfaces (existing MigrationLockAdapter / MigrationStoreAdapter shapes are untouched), no BatchTargetProgress / BatchTargetStatus / TargetConfigFactory types, no GetAllRecordsFn, no ValidationError alias, no registerMigrationErrorCodes() named export. Lifecycle event-key aliases (migration:started, migration:applied, migration:completed, migration:rolled-back) are absent — code only emits migration:before / migration:after / migration:failed / migration:plan. 0% of work is done.

1. Spec authoring

• 1.1 Read ../suaveplan/enterprise/migration.md end-to-end
• 1.2 Read openspec/specs/migration/spec.md (does not exist yet — confirm and start fresh)
• 1.3 Read openspec/AGENTS.md Sections 13 and 14
• 1.4 Draft proposal.md from openspec/templates/proposal.md
• 1.5 Fill in ## Source mapping table — every requirement cites a line range OR appears in the "no source line" table with justification
• 1.6 Draft specs/migration/spec.md from openspec/templates/spec-delta.md
• 1.7 Every requirement in the spec delta carries a **Verified by:** line naming concrete it(...) titles

2. Implementation — lock/migration-lock

• 2.1 Create packages/database/migration/src/lock/migration-lock/migration-lock.ts exporting the MigrationLockLike interface (acquire(lockId, ttlMs), release(lockId), extend(lockId, ttlMs))
• 2.2 Re-export the existing MigrationLockAdapter from this module under the same name for back-compat
• 2.3 Add a migration-lock.md sibling doc covering both interface contracts (≥200 words, basic + advanced examples)
• 2.4 Update MemoryMigrationLock to implement MigrationLockLike alongside the existing MigrationLockAdapter shape (additive methods only)
• 2.5 Update lock/index.ts to export MigrationLockLike from the package root via index.ts

3. Implementation — store/migration-store

• 3.1 Create packages/database/migration/src/store/migration-store/migration-store.ts exporting the MigrationStoreLike interface (list, append, markFailed, markApplied, getLatestVersion)
• 3.2 Re-export the existing MigrationStoreAdapter from this module under the same name for back-compat
• 3.3 Add a migration-store.md sibling doc (≥200 words, basic + advanced examples)
• 3.4 Update MemoryMigrationStore to implement MigrationStoreLike alongside the existing MigrationStoreAdapter shape (additive methods only)
• 3.5 Update store/index.ts to export MigrationStoreLike from the package root via index.ts

4. Implementation — migration-events

• 4.1 Create packages/database/migration/src/migration-events/migration-events.ts exporting migrationEvents: EventBus<MigrationEventMap> plus createMigrationEvents() factory
• 4.2 Extend MigrationEventMap in types/migration.types.ts with the lifecycle keys: "migration:started", "migration:applied", "migration:failed", "migration:completed", "migration:rolled-back" (additive — preserve migration:before / migration:after / migration:plan)
• 4.3 Update MigrationExecutor to emit both legacy AND canonical lifecycle keys for one release; add // genesis: legacy emit removed in follow-up change comment (no @deprecated per CLAUDE.md rule)
• 4.4 Add a migration-events.md sibling doc (≥200 words, basic + advanced examples) covering the event-bus subscription pattern
• 4.5 Wire migrationEvents into index.ts exports

5. Implementation — batch types

• 5.1 Add BatchTargetStatus = "pending" | "running" | "completed" | "failed" type alias to types/migration.types.ts
• 5.2 Add BatchTargetProgress interface (targetId, status, results, error?, startedAt?, completedAt?)
• 5.3 Add TargetConfigFactory = (targetId: string) => MigrationRunnerConfig | Promise<MigrationRunnerConfig> type alias
• 5.4 Update BatchMigratorConfig to accept either the existing targets array OR a configFactory + targetIds pair (additive)
• 5.5 Update BatchMigrator to emit BatchTargetProgress updates via an optional onProgress?: (progress: BatchTargetProgress) => void callback
• 5.6 Re-export the new types from index.ts
• 5.7 Update batch-migrator.md sibling doc to cover the new factory pattern

6. Implementation — status GetAllRecordsFn

• 6.1 Add GetAllRecordsFn = () => Promise<MigrationRecord[]> type alias to status/migration-status.ts
• 6.2 Update MigrationStatusDashboard constructor to accept an optional getAllRecords?: GetAllRecordsFn parameter; falls back to store.list() when absent
• 6.3 Re-export GetAllRecordsFn from index.ts
• 6.4 Update migration-status.md sibling doc to describe the injection point

7. Implementation — ValidationError re-export

• 7.1 Add export type { MigrationValidationError as ValidationError } to types/migration.types.ts
• 7.2 Update index.ts to export both MigrationValidationError and ValidationError

8. Implementation — MIGRATION_CODES registration

• 8.1 Confirm the side-effect import in index.ts already triggers defineCodes registration on load
• 8.2 Export an idempotent registerMigrationErrorCodes() function from errors/migration-error.ts for downstream consumers that bundle without side-effect imports
• 8.3 Re-running registerMigrationErrorCodes() MUST NOT throw — guard with the registry's existing dedup
• 8.4 Re-export registerMigrationErrorCodes from index.ts

9. Tests

• 9.1 lock/migration-lock/migration-lock.test.ts — acquire returns true on uncontested lockId, false when contested; release frees lockId; extend refreshes TTL; multiple lockIds isolated; expired locks auto-release
• 9.2 lock/migration-lock/migration-lock.spec-conformance.test.ts — pins MigrationLockAdapter back-compat alias; verifies MemoryMigrationLock satisfies BOTH interfaces
• 9.3 store/migration-store/migration-store.test.ts — empty list initial; append → list returns single; markApplied flips status; markFailed records error; getLatestVersion returns latest by id sort
• 9.4 store/migration-store/migration-store.spec-conformance.test.ts — pins MigrationStoreAdapter back-compat alias; verifies MemoryMigrationStore satisfies BOTH interfaces
• 9.5 migration-events/migration-events.test.ts — every lifecycle key emits with the correct payload shape; multiple subscribers receive in registration order
• 9.6 migration-events/migration-events.spec-conformance.test.ts — listener throwing does not abort emit loop; off() removes specific listener; clear() removes all
• 9.7 batch/batch-migrator/batch-migrator.test.ts — BatchTargetProgress transitions pending → running → completed; failure transitions to failed and isolates from siblings; onProgress called per transition
• 9.8 status/migration-status/migration-status.test.ts — GetAllRecordsFn injected source returned from getHistory(); absent factory falls back to store.list()
• 9.9 errors/migration-error.spec-conformance.test.ts — ErrorCodes.has("MIGRATION.LOCK_HELD") is true after package import; second registerMigrationErrorCodes() call does not throw
• 9.10 Every it(...) in 9.1–9.9 carries { timeout: 5000 } (or 30000 for genuinely async)

10. Documentation

• 10.1 Sibling .md for every new implementation .ts (migration-lock.md, migration-store.md, migration-events.md); each ≥200 words with basic + advanced examples
• 10.2 Update packages/database/migration/README.md — add Modules links for the three new files; add Quick-start snippet showing migrationEvents subscription
• 10.3 Update CLAUDE.md package listing line for @suaveplan/migration if the public-surface description has changed

11. Pre-archive verification (the 5-gate triple)

• 11.1 bun run check — Biome 0 errors / 0 warnings / 0 info across the whole monorepo
• 11.2 bunx turbo lint typecheck test --filter=@suaveplan/migration — green
• 11.3 bunx turbo test:coverage --filter=@suaveplan/migration — 100/100/100/100
• 11.4 bun scripts/openspec-conformance.ts @suaveplan/migration — exit 0, no error findings
• 11.5 bunx turbo build --filter=@suaveplan/migration — green

12. Pre-archive 7-row checklist (AGENTS.md Section 13)

• 12.1 Generics threaded; expectTypeOf assertions on every literal-type claim (lifecycle key strings, BatchTargetStatus union)
• 12.2 Zod schemas wired at every declared boundary (MigrationLockLike / MigrationStoreLike consumers do not need Zod — interfaces are TS-only; verify schemas are still wired in MigrationRunnerOptionsSchema etc.)
• 12.3 Every error code in errors/migration-error.ts thrown by at least one production path
• 12.4 Strict-mode behaviors tested both on and off (lock TTL expiry honoured under enableTtlEnforcement: true and bypassed when false)
• 12.5 OTel instruments emitted from production paths and asserted with a real in-memory MeterProvider
• 12.6 Lifecycle dedup tested where claimed (idempotent registerMigrationErrorCodes)
• 12.7 No retroactive tick — every box above reflects work done in this change

13. Archive

• 13.1 Fold spec delta into openspec/specs/migration/spec.md (will be the first time this canonical spec exists)
• 13.2 Move openspec/changes/migration-adapters-completion/ → openspec/archive/<yyyy-mm-dd>-migration-adapters-completion/
• 13.3 Refresh MANIFEST.md if package set or deps changed (no expected change here)