[quality-runtime]

Adds packages/db — the Drizzle schema, client, and migration history — with authentication and tenancy owned by Better Auth rather than reimplemented. Organizations are the tenant boundary (TENANT-01), so they exist from the first migration instead of being retrofitted around later.

Decisions are recorded in ADR 0001 (why Drizzle + Better Auth, which plugins, what the tests do and do not prove) and ADR 0002 (identifier format). docs/data-model.md describes the resulting model; docs/security.md gains the tenant-authorization guardrail.

Schema

Eight tables from Better Auth's organization, admin, and twoFactor plugins. Teams and dynamic access control are off — both add tables and neither has a requirement yet.

The Drizzle schema is maintained by hand rather than generated into the tree, because generated files stop being reviewed. Four deviations deliberately strengthen what Better Auth generates:

Deviation	Why
timestamptz throughout	Audit history must be unambiguous across zones
UNIQUE (organization_id, user_id)	Better Auth checks before inserting, which races
UNIQUE (provider_id, account_id)	Better Auth throws when this pair matches two rows, so a duplicate breaks sign-in
FK on session.active_organization_id	A session must not outlive the tenant it points at

Identifiers

Prefixed, application-generated, lowercase base36 — usr_v1stgxr8z5jdhi6b. packages/db/id.ts is the only place they are generated, and each table enforces its own format in the database:

CONSTRAINT "user_id_format" CHECK ("id" ~ '^usr_[0-9a-z]{16}$')

That makes the convention an invariant rather than a habit: a writer not wired to id.ts — most importantly a Better Auth config that forgets generateId — fails on its first insert instead of quietly storing a second format.

Boundaries

createDatabase takes a pg Client or Pool, not a connection string, so connection lifecycle stays with the deployment (ARCH-01) — a long-lived pool on a server, a per-request client behind Hyperdrive on Workers:

const db = createDatabase(new Pool({ connectionString: env.DATABASE_URL }));

No Drizzle relations() are declared. They serve Better Auth's opt-in join mode and Drizzle's relational queries; neither is in use, so they are not maintained unused.

Verification

bun run check, bun run test (72 passing), and reuse lint all pass. CI now runs check and test — previously tests were not a gate, so a Better Auth upgrade could go green without executing the drift guard.

• schema/auth.test.ts — structural check against getAuthTables(), so an upgrade that adds or renames a field fails in CI.
• schema/migrations.test.ts — applies the checked-in SQL to real PostgreSQL via PGlite (no service container) and asserts the constraints actually reject: wrong-prefix and uppercase IDs, duplicate memberships, duplicate account identities.

Not verified: no application consumes this yet, and nothing automatically compares column types, uniqueness, indexes, or references against Better Auth's definitions — ADR 0001 records that gap and the upgrade procedure that covers it.