# 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