suaveplan/openspec/archive/2026-05-18-add-better-auth-surrealdb/tasks.md

Tasks — add-better-auth-surrealdb

1. Scaffold

• 1.1 Create packages/auth/better-auth-surrealdb/ with src/{adapter,compile,id-strategy,link-fields,schema,schemas,otel,error-codes,types,testing}/ + tests/{setup,integration}/
• 1.2 Add better-auth ^1.4.0 to root package.json new catalogs.auth block. Re-run bun install from repo root.
• 1.3 package.json v0.1.0. Deps: @suaveplan/error @suaveplan/surrealdb @suaveplan/types tslib, zod (catalog:forms), @opentelemetry/api. PeerDeps: better-auth: ^1.4.0.
• 1.4 12 subpath exports: ., ./adapter, ./compile, ./id-strategy, ./link-fields, ./schema, ./schemas/options, ./schemas/link-fields, ./testing, ./error-codes, ./otel, ./types
• 1.5 tsconfigs + vite (rollup assetFileNames config so the .surql schema string is bundled into dist/) + vitest (100/100/100/100, testTimeout 60000 for integration)
• 1.6 tests/setup/polyfills.ts

2. Implementation

• 2.1 src/error-codes.ts + .md + test — 7 BETTER_AUTH_SURREALDB.* codes + BetterAuthSurrealError
• 2.2 src/types/adapter.{ts,md,index.ts} — IdStrategy, LinkFieldMap, BetterAuthSurrealAdapterOptions; re-exports of Better-Auth Adapter + Where types
• 2.3 src/schemas/options.{ts,test.ts,md,index.ts} — BetterAuthSurrealAdapterOptionsSchema (Zod)
• 2.4 src/schemas/link-fields.{ts,test.ts,md,index.ts} — LinkFieldMapSchema
• 2.5 src/link-fields/link-fields.{ts,test.ts,md,index.ts} — DEFAULT_BETTER_AUTH_LINK_FIELDS constant + applyLinkPrefix(model, field, value, map) + stripLinkPrefix(model, field, value, map) helpers
• 2.6 src/compile/compile-where.{ts,test.ts,md,index.ts} — operator + connector mapping; placeholder generator; link-field value pre-resolution via link-fields helpers
• 2.7 src/compile/compile-select.{ts,test.ts,md}
• 2.8 src/compile/compile-sort.{ts,test.ts,md}
• 2.9 src/id-strategy/id-strategy.{ts,test.ts,md,index.ts} — 3 strategies; record-id prefix manipulation; ULID generator
• 2.10 src/otel/instruments.{ts,test.ts,md,index.ts} — counter + histogram
• 2.11 src/schema/schema.{ts,test.ts,md,index.ts} — exports BETTER_AUTH_SURREAL_SCHEMA (frozen string copied verbatim from /mnt/f/surrealdb/surql/features/02-auth/02-better-auth.surql) + applyBetterAuthSchema(adapter) helper
• 2.12 src/adapter/adapter.{ts,test.ts,md,index.ts} — createBetterAuthSurrealAdapter factory + all 8 methods; integrates link-fields helpers in every read/write path
• 2.13 src/adapter/model-to-table.{ts,test.ts,md} — validation + caching
• 2.14 src/testing/index.ts + .md — runAdapterConformance(factory) that applies BETTER_AUTH_SURREAL_SCHEMA before exercising scenarios
• 2.15 src/index.ts — named re-exports only (no export *)

3. Tests

• 3.1 Co-located *.test.ts per spec scenario (unit tests use a stub SurrealAdapter for shape; integration tests use real testcontainer)
• 3.2 src/better-auth-surrealdb.spec-conformance.test.ts — every BETTER_AUTH_SURREALDB.* code thrown from a production path
• 3.3 tests/integration/conformance.test.ts — real @suaveplan/testing-integration-surrealdb testcontainer; calls applyBetterAuthSchema(adapter) then runs runAdapterConformance(...)
• 3.4 tests/integration/schema-write-compatibility.test.ts — applies BETTER_AUTH_SURREAL_SCHEMA, then writes representative rows on session (record-link userId), account (string userId), member (record-link userId AND organizationId), oauth_access_token (string userId). All four writes succeed.
• 3.5 tests/property.test.ts — fast-check (200 runs) on compileWhere invariants: placeholder names unique; vars match clause refs; link-field values always pre-resolved to record-link form when configured
• 3.6 tests/dep-graph.test.ts
• 3.7 All tests import runner from @suaveplan/testing/runner
• 3.8 Every it() has { timeout: 5000 } (60000 for integration)

4. Documentation

• 4.1 Sibling .md per impl (≥200 words)
• 4.2 README.md — quick-start (applyBetterAuthSchema + createBetterAuthSurrealAdapter), full table of 17 schema tables + which use record<user> vs string, linkFields override examples, idStrategy choice table, conformance harness usage, peer-dep notes
• 4.3 Note in README that schema content is mirrored from canonical /mnt/f/surrealdb/surql/features/02-auth/02-better-auth.surql; changes upstream require a coordinated package version bump

5. Gates

• 5.1 bunx turbo lint typecheck test --filter=@suaveplan/better-auth-surrealdb --force
• 5.2 Coverage 100/100/100/100
• 5.3 bun scripts/openspec-conformance.ts @suaveplan/better-auth-surrealdb exit 0
• 5.4 Build green
• 5.5 Banned-pattern grep + no export * + no direct vitest/bun:test imports

6. Archive

• 6.1 Fold spec → openspec/specs/better-auth-surrealdb/spec.md
• 6.2 mv change → openspec/archive/<date>-add-better-auth-surrealdb/
• 6.3 DO NOT refresh MANIFEST or STATUS (orchestrator consolidates after 4-package batch)