Initial Commit

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

@@ -0,0 +1,56 @@
+# Tasks — Fix api-migrations SurrealQL ledger CREATE silent drop on SurrealDB v3
+
+## 1. Spec authoring
+
+- [x] 1.1 Not a migration — no `enterprise/<pkg>.md` to read
+- [x] 1.2 Read `openspec/specs/api-migrations/spec.md`
+- [x] 1.3 Read `openspec/AGENTS.md` Sections 13 and 14
+- [x] 1.4 Draft `proposal.md`
+- [x] 1.5 Source mapping cites the genesis-internal reference (`better-auth-surrealdb::prepareRecordId`) and the SurrealDB v3 CREATE docs
+- [x] 1.6 Draft `specs/api-migrations/spec.md` with `## MODIFIED Requirements`
+- [x] 1.7 Every requirement carries a `**Verified by:**` line naming concrete `it(...)` titles
+
+## 2. Implementation
+
+- [x] 2.1 Replace `CREATE ${table}:$name SET ...` with backtick-quoted record-id literal in `insertApplied`
+- [x] 2.2 Replace `DELETE ${table}:${id}` with the matching backtick-quoted record-id literal in `deleteApplied`
+- [x] 2.3 Add `bareId` helper that strips `${table}:` prefix and wrapping backticks from SurrealDB-returned ids in `selectApplied`
+- [x] 2.4 Update `rowToRecord` to thread `table` through and call `bareId`
+
+## 3. Tests
+
+- [x] 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
+- [x] 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
+- [x] 3.3 Add `tests/integration/global-setup.ts` + `integration-setup.ts` + `vitest.integration.config.ts` + `test:integration` script (mirroring `@suaveplan/surrealdb`)
+- [x] 3.4 Every `it(...)` carries `{ timeout: 5000 }` or 60000 for the live-container tests
+
+## 4. Documentation
+
+- [x] 4.1 Sibling `.md` for the implementation file already exists (`surrealql.md`) — refreshed to describe the v3-safe form
+- [x] 4.2 README links unchanged — module list still accurate
+- [x] 4.3 CLAUDE.md unchanged — no new package
+
+## 5. Pre-archive verification (the 5-gate triple)
+
+- [x] 5.1 `bun run check` — 1 unrelated warning (broken symlink in unrelated tree); 0 errors
+- [x] 5.2 `bunx turbo lint typecheck test --filter=@suaveplan/api-migrations` — green (76 unit tests)
+- [x] 5.3 `bunx turbo test:coverage --filter=@suaveplan/api-migrations` — 100/100/100/100 istanbul
+- [x] 5.4 `bun scripts/openspec-conformance.ts @suaveplan/api-migrations` — exit 0 (PASS, 0 errors / 0 warnings / 0 info)
+- [x] 5.5 `bunx turbo build --filter=@suaveplan/api-migrations` — green
+- [x] 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
+
+- [x] 6.1 Generics threaded — `bareId` returns string; `rowToRecord` typed; no `any`
+- [x] 6.2 Zod schemas — no boundary changes; existing schemas untouched
+- [x] 6.3 Every error code in `error-codes.ts` still thrown by at least one production path (unchanged surface)
+- [x] 6.4 Strict-mode behaviors — `{ rollback: false }` path retested
+- [x] 6.5 OTel instruments — unchanged; existing assertions in `runner.test.ts` cover both outcomes
+- [x] 6.6 Lifecycle dedup — N/A for this change
+- [x] 6.7 No retroactive tick
+
+## 7. Archive
+
+- [x] 7.1 Fold spec delta into `openspec/specs/api-migrations/spec.md`
+- [x] 7.2 Move `openspec/changes/fix-api-migrations-surrealql-ledger/` → `openspec/archive/2026-05-19-fix-api-migrations-surrealql-ledger/`
+- [x] 7.3 MANIFEST.md unchanged (no package set/dep change at the manifest level)