suaveplan/openspec/archive/2026-05-19-fix-api-migrations-surrealql-ledger/tasks.md

Tasks — Fix api-migrations SurrealQL ledger CREATE silent drop on SurrealDB v3

1. Spec authoring

• 1.1 Not a migration — no enterprise/<pkg>.md to read
• 1.2 Read openspec/specs/api-migrations/spec.md
• 1.3 Read openspec/AGENTS.md Sections 13 and 14
• 1.4 Draft proposal.md
• 1.5 Source mapping cites the genesis-internal reference (better-auth-surrealdb::prepareRecordId) and the SurrealDB v3 CREATE docs
• 1.6 Draft specs/api-migrations/spec.md with ## MODIFIED Requirements
• 1.7 Every requirement carries a **Verified by:** line naming concrete it(...) titles

2. Implementation

• 2.1 Replace CREATE ${table}:$name SET ... with backtick-quoted record-id literal in insertApplied
• 2.2 Replace DELETE ${table}:${id} with the matching backtick-quoted record-id literal in deleteApplied
• 2.3 Add bareId helper that strips ${table}: prefix and wrapping backticks from SurrealDB-returned ids in selectApplied
• 2.4 Update rowToRecord to thread table through and call bareId

3. Tests

• 3.1 Update unit tests in src/adapters/surrealql/surrealql.test.ts — regression not.toContain("$name SET"), positive toContain("CREATE _migrations:\001` SET"), backtick escape, selectApplied` strip + RecordId object form + fallback paths
• 3.2 Add live SurrealDB v3 integration suite at tests/integration/surrealql-ledger.integration.test.ts — three tests: silent-drop regression, second-run no-op, rollback round-trip
• 3.3 Add tests/integration/global-setup.ts + integration-setup.ts + vitest.integration.config.ts + test:integration script (mirroring @suaveplan/surrealdb)
• 3.4 Every it(...) carries { timeout: 5000 } or 60000 for the live-container tests

4. Documentation

• 4.1 Sibling .md for the implementation file already exists (surrealql.md) — refreshed to describe the v3-safe form
• 4.2 README links unchanged — module list still accurate
• 4.3 CLAUDE.md unchanged — no new package

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

• 5.1 bun run check — 1 unrelated warning (broken symlink in unrelated tree); 0 errors
• 5.2 bunx turbo lint typecheck test --filter=@suaveplan/api-migrations — green (76 unit tests)
• 5.3 bunx turbo test:coverage --filter=@suaveplan/api-migrations — 100/100/100/100 istanbul
• 5.4 bun scripts/openspec-conformance.ts @suaveplan/api-migrations — exit 0 (PASS, 0 errors / 0 warnings / 0 info)
• 5.5 bunx turbo build --filter=@suaveplan/api-migrations — green
• 5.6 Live SurrealDB v3 integration tests (bun run test:integration) — 3/3 pass; verified to fail with the pre-fix SQL form

6. Pre-archive 7-row checklist

• 6.1 Generics threaded — bareId returns string; rowToRecord typed; no any
• 6.2 Zod schemas — no boundary changes; existing schemas untouched
• 6.3 Every error code in error-codes.ts still thrown by at least one production path (unchanged surface)
• 6.4 Strict-mode behaviors — { rollback: false } path retested
• 6.5 OTel instruments — unchanged; existing assertions in runner.test.ts cover both outcomes
• 6.6 Lifecycle dedup — N/A for this change
• 6.7 No retroactive tick

7. Archive

• 7.1 Fold spec delta into openspec/specs/api-migrations/spec.md
• 7.2 Move openspec/changes/fix-api-migrations-surrealql-ledger/ → openspec/archive/2026-05-19-fix-api-migrations-surrealql-ledger/
• 7.3 MANIFEST.md unchanged (no package set/dep change at the manifest level)