# 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)