suaveplan/openspec/archive/2026-05-18-add-api-migrations/tasks.md

Tasks — add-api-migrations

1. Scaffold

• 1.1 Create packages/api/api-migrations/ with src/{runner,adapters/{surrealql,postgres,sqlite},otel,error-codes,types}/ + tests/setup/ + tests/integration/
• 1.2 package.json v0.1.0. Deps: @suaveplan/error @suaveplan/types tslib, @opentelemetry/api. PeerDeps (optional, dialect-specific): surrealdb postgres @sqlite.org/sqlite-wasm — each listed as peerDependenciesMeta.<x>.optional: true. Dev: standard + the actual clients for integration tests.
• 1.3 Subpath exports: ., ./runner/runner, ./adapters/surrealql/surrealql, ./adapters/postgres/postgres, ./adapters/sqlite/sqlite, ./otel/instruments, ./error-codes/error-codes, ./types/migration
• 1.4 tsconfigs + vite + vitest (100/100/100/100, testTimeout 60000 for integration)
• 1.5 tests/setup/polyfills.ts

2. Implementation

• 2.1 src/error-codes.ts + .md + test — 6 MIGRATION.* codes + MigrationError
• 2.2 src/types/migration.{ts,md,index.ts} — MigrationFile, MigrationRecord, MigrationResult, MigrationAdapter, MigrationDialect, MigrationRunnerOptions
• 2.3 src/otel/instruments.{ts,test.ts,md,index.ts} — counter + histogram
• 2.4 src/adapters/surrealql/surrealql.{ts,test.ts,md,index.ts} — createSurrealqlAdapter(client), SurrealQL DDL
• 2.5 src/adapters/postgres/postgres.{ts,test.ts,md,index.ts} — createPostgresAdapter(client), standard SQL DDL
• 2.6 src/adapters/sqlite/sqlite.{ts,test.ts,md,index.ts} — createSqliteAdapter(db), SQLite DDL
• 2.7 src/runner/runner.{ts,test.ts,md,index.ts} — MigrationRunner class; checksum validation; dry-run; AbortSignal; rollback
• 2.8 src/index.ts — named re-exports

3. Tests

• 3.1 Co-located *.test.ts per spec scenario (use stub MigrationAdapter for unit tests)
• 3.2 src/api-migrations.spec-conformance.test.ts — every MIGRATION.* thrown
• 3.3 tests/integration/surrealql-roundtrip.test.ts — real @suaveplan/testing-integration-surrealdb testcontainer; apply 3 migrations, query the tracking table, assert records + checksums
• 3.4 tests/integration/postgres-roundtrip.test.ts — real @suaveplan/testing-integration-postgres testcontainer
• 3.5 tests/integration/sqlite-roundtrip.test.ts — in-memory @sqlite.org/sqlite-wasm
• 3.6 tests/property.test.ts — fast-check checksum stability: identical content produces identical SHA-256
• 3.7 tests/dep-graph.test.ts — every adapter has its own subpath; sibling .md present
• 3.8 Runner imports + timeouts

4. Documentation

• 4.1 Sibling .md per impl (≥200 words)
• 4.2 README.md — quick-start for each dialect, AbortSignal pattern, checksum-drift recovery procedure

5. Gates

• 5.1 bunx turbo lint typecheck test --filter=@suaveplan/api-migrations --force
• 5.2 Coverage 100/100/100/100
• 5.3 bun scripts/openspec-conformance.ts @suaveplan/api-migrations exit 0
• 5.4 Build green
• 5.5 Banned patterns + no export * + no direct runner imports

6. Archive

• 6.1 Fold spec → openspec/specs/api-migrations/spec.md
• 6.2 mv → archive
• 6.3 MANIFEST + STATUS refresh