STTracker/docs/plans/001-phase1-sdd/reports/task-1-report.md

# Task 1 report: `packages/db`

**Status:** DONE_WITH_CONCERNS (concerns are minor; see the end)
**Branch:** `feat/phase1`, base fb4ff36

## Commits
- `6c5a9fb` chore: workspace package stubs with approved dependencies
- `8248a2a` feat(db): Bun.SQL Kysely dialect for sqlite and postgres
- `27ec24e` feat(core): shared domain error classes

## What was built
- **`packages/db/src/dialect.ts`**:
  - `type Dialect = "sqlite" | "postgres"` and `dialectOf(url)`, which throws on an unknown scheme.
  - `BunSqlDialect` is one Kysely `Dialect` over `new SQL(url)`. It picks the Sqlite or Postgres adapter, compiler and introspector by URL scheme.
  - `executeQuery` calls `runner.unsafe(sql, params)`. It sets `numAffectedRows` only for INSERT/UPDATE/DELETE/MERGE, and `insertId` only for SQLite INSERT.
  - Transactions are `begin`/`commit`/`rollback` on the held connection. On Postgres, `begin` can carry an isolation level and access mode.
- **Deviation from the brief (forced by Bun):** Bun's SQLite adapter throws `This adapter doesn't support connection reservation` on `reserve()`.
  - Postgres uses `sql.reserve()` as the brief says.
  - SQLite uses the single `SQL` instance as its connection, guarded by a mutex. The lock is held from `acquireConnection` to `releaseConnection`, so a transaction never interleaves with other queries.
  - This is recorded in DECISIONS.
- **`db.ts`:** `createDb(url): Promise<Db>`, with `Db { k: Kysely<Database>; dialect; close() }`.
  - SQLite: runs `PRAGMA foreign_keys = ON`, plus `PRAGMA journal_mode = WAL` unless the URL is `:memory:`.
  - Postgres: runs `select 1` to fail fast on a bad URL.
  - If init fails, the Kysely instance is destroyed before the error is rethrown.
- **`ids.ts`:** `newId()` returns `Bun.randomUUIDv7()`; `nowIso()` returns `new Date().toISOString()`.
- **`json.ts`:** `toJson` and `fromJson<T>(s, fallback)`. The fallback is returned for null, undefined or invalid JSON.
- **`migrate.ts`:** `migrateToLatest(db)` runs a Kysely `Migrator` (imported from `kysely/migration`, as Kysely 0.29 requires) with a static provider over `migrations/index.ts`. An empty set works. It throws with the name of the failing migration.
- **`migrations/index.ts`:** `export const migrations: Record<string, Migration> = {}`.
- **`schema.ts`:** placeholder `export interface Database {}`.
- **`testing.ts`:** `forEachDialect(name, fn)` registers `describe("<name> [sqlite]")`, plus `[postgres]` when `TEST_POSTGRES_URL` is set.
  - `beforeEach` builds a fresh migrated DB: SQLite uses `:memory:`; Postgres runs `create database "st_<uuid hex>"` through an admin connection and uses the derived URL.
  - `afterEach` closes the DB.
  - `afterAll` drops every created database `with (force)`.
- **`packages/core/src/errors.ts`:** `AuthError(code)`, `ValidationError(field, reason)` (code `validation`), `CryptoError(message)` (code `crypto`), `ImportError(code)` and `NotFoundError(what)` (code `not_found`).
  - All of them extend Error and have a readonly `code` and a `name` set.
- **Package stubs:** these get name, private, type module, `exports {"./*": "./src/*.ts"}`, and the dependencies from the ruling:
  - packages: db, core, plugin-sdk;
  - apps: server, web;
  - plugins: trakt, hardcover, mangabaka, csv, listenbrainz, lastfm.

  Versions are caret ranges of the npm latest on 2026-10-30:
  - kysely ^0.29.7, zod ^4.6.7, fflate ^0.8.3;
  - react and react-dom ^19.3.1, wouter ^3.13.0, @tanstack/react-query ^5.105.0;
  - @types/react and @types/react-dom ^19.3.0.

  `bun install` was run and `bun.lock` committed. `bun install --frozen-lockfile` reports no changes.
- **Docs:**
  - DECISIONS: three new entries, newest first (single Bun.SQL dialect; JSON as text; UUIDv7 instead of ULID).
  - ARCHITECTURE: the map row for `packages/db` is updated.

## Files changed
- `bun.lock`
- `docs/ARCHITECTURE.md`, `docs/DECISIONS.md`
- `apps/{server,web}/package.json`
- `packages/{core,db,plugin-sdk}/package.json`
- `plugins/{trakt,hardcover,mangabaka,csv,listenbrainz,lastfm}/package.json`
- `packages/db/src/{dialect,db,ids,json,migrate,schema,testing}.ts`, `packages/db/src/migrations/index.ts`
- `packages/db/test/db.test.ts`
- `packages/core/src/errors.ts`

## TDD evidence
**Tests:**
- Inside `forEachDialect`, per dialect:
  - "round-trips a row";
  - "transactions roll back";
  - "transactions commit" (extra);
  - "newId is time-sortable" (1000 ids, sorted and unique).
- Outside it, once: a `fromJson` fallback test.

RED, written before any source existed:
```
$ bun test packages/db
error: Cannot find module '../src/ids.ts' from '/home/user/STTracker/packages/db/test/db.test.ts'
 0 pass
 1 fail
 1 error
```
GREEN on SQLite:
```
$ bun test packages/db
 5 pass
 0 fail
 12 expect() calls
Ran 5 tests across 1 file. [371.00ms]
```
GREEN on SQLite and Postgres:
```
$ TEST_POSTGRES_URL=postgres://postgres:postgres@127.0.0.1:55432/postgres bun test packages/db
 9 pass
 0 fail
 20 expect() calls
Ran 9 tests across 1 file. [1.87s]
```
**Mutation check:** I temporarily changed `rollbackTransaction` to issue `commit`. "transactions roll back" then failed on both `[sqlite]` and `[postgres]`, and I restored the code. After the Postgres runs, no `st_%` databases were left over.

**Manual probe:**
- `createDb("sqlite://rel.db")` creates `./rel.db` with `journal_mode=wal` and `foreign_keys=1`.
- `createDb("mysql://x")` throws `Unsupported database URL scheme: mysql`.

## Typecheck
```
$ bun run typecheck
$ tsc --noEmit -p tsconfig.json
```
It exits clean with no output.

## Self-review findings
- The mutex is released through Kysely's `try/finally` in its connection provider, so a failing query cannot leave the SQLite lock held.
- `numAffectedRows` is not set for SELECTs, because Bun's `count` there is the row count.
- Postgres `count(*)` comes back as a string (bigint). The test uses `Number()`. Later tasks should do the same or cast in SQL.
- Not implemented, on purpose: savepoints (Kysely raises a clear error if they are used), and true streaming (`streamQuery` yields the whole result as one chunk). Both are recorded in DECISIONS.
- Fixed during review: one claim I could not verify, about how Bun.SQL returns `jsonb`, was removed from the DECISIONS text.

## Concerns
1. **SQLite has no `reserve()`.** That is why it uses a single connection behind a mutex, which deviates from the brief's "acquireConnection returns `sql.reserve()`". The public interface is unchanged.
2. **Postgres test cost.** `create database` takes about 100–300 ms per test, and once took about 1 s. One run of 4 PG tests took 11 s; reruns took 1.6–3.8 s. With many DB tests in later tasks, the Postgres suite may get slow. A faster option is one DB per `describe` with a schema reset per test. That would change the harness contract, so I did not do it.
3. **ULID wording.** `AGENTS.md` (Rules: "IDs are ULIDs") still says ULID. The DECISIONS entry says to read it as UUIDv7. Editing `AGENTS.md` was outside my ruling, so the maintainer or controller may want a one-word fix.
4. **Kysely 0.29 import path.** `Migrator`, `Migration` and `MigrationProvider` must be imported from `kysely/migration`; the root exports are deprecated type errors. Task 2's migration files should import `Migration` from `kysely/migration`.