@crvouga/sqlite-mem 0.1.0 → 1.0.0

package/AGENTS.md

@@ -0,0 +1,154 @@
+# AGENTS.md — contributing to sqlite-mem
+
+Guidance for humans and coding agents editing this repository. For install and consumer API, see [README.md](README.md). For the feature matrix, see [COMPATIBILITY.md](COMPATIBILITY.md).
+
+## Mission and non-goals
+
+**Mission:** full SQLite3 **SQL dialect** behavioral parity vs **SQLite 3.51.0** (`bun:sqlite`). Same statements → same observable results (rows, errors, counters), proven by differential contracts and a fail-closed gate.
+
+**Allowed intentional differences:**
+
+1. Custom snapshot codec (`SQLM`), not on-disk `.sqlite` files
+2. Deterministic `random()` / `randomblob()` and fixed `'now'` by default (injectable)
+3. `NOT APPLICABLE` items: C API, VFS/pager/WAL, file locking, URI filenames
+
+**Non-goals:** shipping a SQLite file format, native/WASM bindings, or matching better-sqlite3’s full Node API surface.
+
+## SQL pipeline
+
+```
+SQL string
+  → tokenize()          src/lexer/tokenize.ts
+  → parse()             src/parser/index.ts → parser.ts
+  → Statement[] AST     src/ast/nodes.ts
+  → Statement.execute() src/api/statement.ts
+  → executeStatement()  src/executor/execute.ts
+  → per-stmt executor   select / dml / ddl / …
+```
+
+Public entry points: `Database.exec` / `query` / `prepare` in [`src/api/database.ts`](src/api/database.ts).
+
+**Planner note:** [`src/planner/index.ts`](src/planner/index.ts) `preparePlan` is an **identity stub** (`Plan === Statement`) and is unused. Runtime index/PK access paths live in [`src/planner/access.ts`](src/planner/access.ts) (`tryIndexedTableRows`, `lookupTableRows`, `tryJoinProbe`), called from the executor.
+
+SELECT has a **fast path** ([`src/executor/simple-select.ts`](src/executor/simple-select.ts)) and a **full path** ([`src/executor/select.ts`](src/executor/select.ts)). Fast paths return `null` when the shape is unsupported; then the full path runs. Changing join/WHERE/expression semantics in only one path will silently diverge.
+
+## `src/` map
+
+| Directory | Role |
+| --- | --- |
+| `api/` | Public `Database` / `Statement` facade |
+| `ast/` | Discriminated-union AST (`nodes.ts`) |
+| `lexer/` | Tokenizer |
+| `parser/` | Recursive-descent parser |
+| `planner/` | Access-path helpers (not a logical plan IR) |
+| `executor/` | Statement dispatch, SELECT, DML, DDL, PRAGMA, triggers, ATTACH |
+| `expressions/` | `evalExpr`, LIKE/GLOB, eval context |
+| `functions/` | Scalar / aggregate / window / datetime / JSON / math / TVF registries |
+| `types/` | Engine `SqlValue`, affinity, collation |
+| `storage/` | In-memory tables, rows, `DatabaseState` |
+| `indexes/` | Equality index store |
+| `schema/` | `sqlite_master` / catalog |
+| `constraints/` | NOT NULL / PK / UNIQUE / CHECK |
+| `transactions/` | BEGIN / COMMIT / SAVEPOINT (clones state + PRNG) |
+| `runtime/` | Clock, PRNG, `DatabaseOptions` |
+| `serialization/` | `SQLM` snapshot codec |
+| `json/` | JSON1 / JSONB internals |
+| `vtable/` | FTS5 and other virtual-table modules |
+| `errors/` | `SqliteError`, `unsupported()` |
+
+Hot / large files: `parser/parser.ts`, `executor/select.ts`, `executor/dml.ts`.
+
+## Critical conventions
+
+- **AST `type` tags** are snake_case (`"create_table"`, `"drop_index"`). TypeScript interfaces are PascalCase (`CreateTableStmt`).
+- **Identifiers** are case-folded (`toLowerCase`) as Map keys in storage and function registries.
+- **Engine `SqlValue`** ([`src/types/value.ts`](src/types/value.ts)) may include `SqlReal` / `SqlJsonText`. **Harness `SqlValue`** ([`tests/harness/types.ts`](tests/harness/types.ts)) is the normalized compare type — do not confuse them.
+- **API `Statement`** vs **AST `Statement`**: the API class aliases the AST union as `AstStatement`.
+- **`Database`** (API) vs **`DatabaseState`** (engine storage).
+- Throw **`SqliteError`** with an `ErrorCategory`. Missing SQL must fail loud via `unsupported()` — the inventory gate fails if the oracle exposes an unimplemented builtin/module.
+- Fast-path helpers (`tryExecuteSimpleSelect`, `tryFastInsert`, `tryIndexedTableRows`, …): return `null` → fall through. Update **both** paths when semantics change.
+- TypeScript: `strict` + `noUncheckedIndexedAccess`. Imports use `.ts` extensions. Biome: 2-space, double quotes, 120 columns.
+- IEEE `-0` is canonicalized to `+0` on bind, affinity, and arithmetic. Keep determinism invariants (see README).
+
+## Change checklists
+
+### New SQL statement
+
+1. Add union member + interface in [`src/ast/nodes.ts`](src/ast/nodes.ts)
+2. Parse in [`src/parser/parser.ts`](src/parser/parser.ts) (`parseStatement` dispatch)
+3. Handle in [`src/executor/execute.ts`](src/executor/execute.ts) (+ `ddl.ts` / `dml.ts` / `vtable.ts` as needed)
+4. Mutate `DatabaseState` if schema changes
+5. Add differential contract under `tests/contract/<area>/`
+6. Optionally add evidence paths in `SOURCE_SEED` in [`scripts/sqlite-requirements.ts`](scripts/sqlite-requirements.ts), then `bun run requirements`
+
+### New SQL function
+
+1. Implement and register in the right map under `src/functions/*` (`getScalarFunctions()`, datetime, JSON, etc.) so [`scripts/sqlite-inventory.ts`](scripts/sqlite-inventory.ts) sees it
+2. Contract tests under `tests/contract/functions/` (and related areas)
+3. Run `bun run inventory` / `bun run test:sqlite-compat` — oracle builtins must not be missing
+
+### New contract test
+
+1. Prefer helpers in [`tests/contract/helpers.ts`](tests/contract/helpers.ts):
+   - `parity` — query both engines
+   - `execParity` — writes
+   - `sequenceParity` — multi-step (optional final-state compare)
+   - `errorParity` / `queryErrorParity` — both must fail
+   - `ftsRankParity` — REAL epsilon compare
+2. Or `matrixBoth` + `expectParity` from `tests/harness/`
+3. **Do not** treat isolated internal unit tests as SQLite proof. The differential suite is authoritative.
+4. Gate: `bun run test:sqlite-compat`
+
+## Test layout
+
+| Path | Role |
+| --- | --- |
+| `tests/contract/` | Differential SQL vs `bun:sqlite` (**authoritative**) |
+| `tests/fuzz/` | fast-check property tests (seeded); same two backends |
+| `tests/harness/` | Compare/normalize helpers + harness unit tests |
+| `tests/adapters/` | Wrappers for sqlite-mem and `bun:sqlite` |
+
+Examples of public API usage: `tests/contract/api/`, `tests/contract/parameters/`, `tests/contract/determinism/`, `examples/react-vite`.
+
+### Fuzz replay
+
+Default seed `0x5a17e0e1`. On failure the seed is printed:
+
+```bash
+bun test tests/fuzz
+SQLITE_MEM_FUZZ_SEED=12345 bun test tests/fuzz
+SQLITE_MEM_FUZZ_SEED=12345 SQLITE_MEM_FUZZ_PATH='0:1' bun test tests/fuzz
+```
+
+## Compat system
+
+| Command | Role |
+| --- | --- |
+| `bun run test:sqlite-compat` | Requirements + fail-closed gate + contract/fuzz/harness |
+| `bun run inventory` | Oracle `pragma_function_list` / modules vs memory registries |
+| `bun run requirements` | Refresh sqlite.org requirements → `compat/requirements.json` + `compat/coverage.json` |
+| `bun run fts-surface` | FTS oracle surface → `compat/fts-oracle-surface.json` |
+
+Statuses: **VERIFIED** / **PARTIALLY VERIFIED** / **UNSUPPORTED** / **NOT APPLICABLE**. Do not market PARTIAL as complete. Coverage evidence is directory paths (e.g. `tests/contract/joins/`), not automatic from test filenames.
+
+Details: [COMPATIBILITY.md](COMPATIBILITY.md), audit: [COMPATIBILITY-AUDIT.md](COMPATIBILITY-AUDIT.md).
+
+## Local gates
+
+Requires [Bun](https://bun.sh).
+
+```bash
+bun install
+bun run ci:local             # same gates as GitHub Actions CI (except publish)
+bun run check                # format + lint + typecheck + sqlite-compat suite
+bun run format
+bun run lint
+bun run typecheck
+bun run test:sqlite-compat
+bun test                     # contract + fuzz + harness
+bun run build
+```
+
+## PR and commits
+
+Use [Conventional Commits](https://www.conventionalcommits.org/) for commits and PR titles (enforced in CI). Prefer squash merges with a conventional title. Releasing is automated via semantic-release — see [README.md](README.md#releasing).

package/COMPATIBILITY-AUDIT.md

@@ -44,14 +44,13 @@ JSON / JSONB:
   VERIFIED
 
 Aggregates / windows:
-  VERIFIED — includes string_agg, ntile, cume_dist, percent_rank
-  (window EXCLUDE still thinner)
+  VERIFIED — includes string_agg, ntile, cume_dist, percent_rank, EXCLUDE
 
 CTEs / transactions / savepoints / constraints / FK / triggers:
-  VERIFIED (deferred FK thinner → PARTIAL edges)
+  VERIFIED (deferred FK + composite FK)
 
 Indexes / views / generated / STRICT / WITHOUT ROWID:
-  VERIFIED / PARTIAL per COMPATIBILITY.md
+  VERIFIED — partial/expression indexes, STRICT tables, leftmost prefix
 
 PRAGMAs:
   PARTIALLY VERIFIED — schema/FK; storage pragmas N/A or :memory: no-op
@@ -67,11 +66,11 @@ ANALYZE / REINDEX / VACUUM:
   VERIFIED (:memory: observable parity)
 
 Prepared statements / errors / snapshot:
-  PARTIAL / VERIFIED — schema invalidation thin; SQLM logical round-trip VERIFIED
+  VERIFIED — schema invalidation re-prepares; SQLM logical round-trip VERIFIED
 
-Differential tests:
-  Total: 656 under `bun test` (contract + fuzz + harness)
-  Passed: 656
+  Differential tests:
+  Total: 727 under `bun test` (contract + fuzz + harness)
+  Passed: 727
   Failed: 0
 
 Stateful / fuzz:
@@ -91,7 +90,6 @@ New incompatibilities found & fixed (this pass):
 Remaining known differences:
   Custom SQLM snapshots; deterministic random()/'now';
   EXPLAIN/INDEXED BY stubs/no-ops; some PRAGMA storage no-ops;
-  Window EXCLUDE / deferred FK / STRICT / prepared invalidation thinner;
   BigInt beyond Number.MAX_SAFE_INTEGER without bun safeIntegers;
   NOT APPLICABLE C API / on-disk / VFS surfaces.
 

package/COMPATIBILITY.md

@@ -34,10 +34,11 @@ Oracle builtins (math, string extras, uuid, ieee754, …) and modules (FTS3/4/5,
 | Area | Status | Notes |
 | --- | --- | --- |
 | Core DML / SELECT / joins / CTE / UPSERT / RETURNING | VERIFIED | Contract + fuzz |
+| STRICT tables / indexes | VERIFIED | STRICT types; partial + expression indexes; leftmost prefix |
 | Expressions / operators / `->` `->>` / row values | VERIFIED | Row-value + precedence contracts |
 | Affinity / NULL / COLLATE | VERIFIED | |
-| Constraints / FK / triggers / views / ATTACH | VERIFIED | Deferred FK thinner → PARTIAL edges |
-| Windows (incl. ntile/cume_dist/percent_rank) | VERIFIED | EXCLUDE still thinner |
+| Constraints / FK / triggers / views / ATTACH | VERIFIED | Deferred FK, composite FK |
+| Windows (incl. ntile/cume_dist/percent_rank) | VERIFIED | EXCLUDE NO OTHERS/CURRENT ROW/GROUP/TIES |
 | JSON1 / JSONB / TVFs | VERIFIED | |
 | Math / string / date extras / uuid / ieee754 | VERIFIED | Scope-3 inventory |
 | FTS3 / FTS4 / FTS5 + MATCH | PARTIALLY VERIFIED | Differential FTS suite + fuzz vs 3.51.0; see FTS matrix below. Shadow-table change counters intentionally diverge. |
@@ -76,7 +77,7 @@ Reference: **SQLite 3.51.0** (`bun:sqlite`). Inventory: `bun run scripts/fts-ora
 | RTREE / dbstat / bytecode / tables_used | VERIFIED | dbstat synthetic pages; bytecode empty cursor |
 | ANALYZE / REINDEX / VACUUM | VERIFIED | `:memory:` observable parity |
 | EXPLAIN / INDEXED BY | PARTIALLY VERIFIED | Stub shapes / no-ops |
-| Prepared stmt schema invalidation | PARTIALLY VERIFIED | Thin |
+| Prepared stmt schema invalidation | VERIFIED | Re-prepare after ALTER/DROP; `tests/contract/api/schema-invalidation.test.ts` |
 | On-disk file format / C API | NOT APPLICABLE | |
 
 ## How to verify
@@ -85,7 +86,7 @@ Reference: **SQLite 3.51.0** (`bun:sqlite`). Inventory: `bun run scripts/fts-ora
 bun run test:sqlite-compat   # requirements + gate + contract/fuzz/harness
 bun run inventory            # oracle function/module inventory
 bun run requirements         # refresh SQLite.org requirements + coverage
-bun run test:browser         # Playwright smoke (not the SQL oracle)
+bun run build && bun run verify-package  # ESM browser build + isomorphic pack gates
 ```
 
 Do not treat isolated unit tests of internal modules as proof of SQLite compatibility. The differential matrix runner is authoritative for SQL behavior; `test:sqlite-compat` is the release gate.

package/README.md

@@ -5,10 +5,22 @@ Pure TypeScript, completely in-memory SQLite implementation aiming for **full SQ
 - Runs in modern browsers and Node.js / Bun
 - **Zero** WASM, native bindings, workers, or filesystem dependencies
 - Entire database stored in memory
+- **Synchronous** ESM-only API (no Promises, no `require`)
 - **Verified against SQLite 3.51.0** (`bun:sqlite`) via differential contracts + fail-closed gate
 - Intentional differences: deterministic `random()` / `'now'` by default, and a custom snapshot format (not `.sqlite` files)
 
-See [COMPATIBILITY.md](COMPATIBILITY.md) for the matrix and [COMPATIBILITY-AUDIT.md](COMPATIBILITY-AUDIT.md) for the audit report.
+See [COMPATIBILITY.md](COMPATIBILITY.md) for the matrix and [COMPATIBILITY-AUDIT.md](COMPATIBILITY-AUDIT.md) for the audit report. Agents contributing to this repo: start with [AGENTS.md](AGENTS.md).
+
+## Documentation
+
+| Doc | For |
+| --- | --- |
+| [README.md](README.md) | Install, API, pitfalls (this file) |
+| [AGENTS.md](AGENTS.md) | Architecture, how to change code, test/compat gates |
+| [COMPATIBILITY.md](COMPATIBILITY.md) | Feature matrix + verify commands |
+| [COMPATIBILITY-AUDIT.md](COMPATIBILITY-AUDIT.md) | Audit evidence |
+| [docs/SECRETS.md](docs/SECRETS.md) | npm / CI publish setup |
+| [benchmarks/PERFORMANCE.md](benchmarks/PERFORMANCE.md) | Performance notes |
 
 ## Install
 
@@ -18,6 +30,8 @@ bun add @crvouga/sqlite-mem
 npm install @crvouga/sqlite-mem
 ```
 
+Requires Node.js ≥ 20 or Bun ≥ 1.1. The published package is **ESM only** (`import` from `@crvouga/sqlite-mem`).
+
 ## Usage
 
 ```ts
@@ -32,7 +46,7 @@ db.exec(`
   )
 `);
 
-db.exec(`INSERT INTO users (name) VALUES (?)`, ["Alice"]);
+db.prepare(`INSERT INTO users (name) VALUES (?)`).run("Alice");
 
 const users = db.query<{ id: number; name: string }>(`SELECT * FROM users`);
 console.log(users);
@@ -42,36 +56,132 @@ const db2 = new Database();
 db2.restore(snap);
 ```
 
+All methods are **synchronous** — do not `await` them. Browser and Node/Bun share the same in-memory JS surface (no filesystem; `ATTACH` opens a new empty in-memory schema, not a file).
+
+## Example
+
+A React + Vite SQL playground lives in [`examples/react-vite`](examples/react-vite):
+
+```bash
+cd examples/react-vite
+bun install
+bun run dev
+```
+
+From the repo root after that install: `bun run example`.
+
 ## API
 
 ```ts
+import { Database, SqliteError } from "@crvouga/sqlite-mem";
+
+interface DatabaseOptions {
+  seed?: number | bigint;           // default 1 — PRNG for random() / randomblob()
+  now?: Date | (() => Date);        // default 2000-01-01T00:00:00.000Z
+}
+
 interface Database {
-  // seed default 1; now default 2000-01-01T00:00:00.000Z
-  constructor(options?: { seed?: number | bigint; now?: Date | (() => Date) });
-  exec(sql: string, params?: unknown[]): void;
-  query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+  constructor(options?: DatabaseOptions);
+  exec(sql: string): void;
+  query<T = QueryRow>(sql: string, params?: BindValue[]): T[];
   prepare(sql: string): Statement;
   transaction<T>(fn: () => T): T;
   snapshot(): Uint8Array;
   restore(snapshot: Uint8Array): void;
   close(): void;
+  [Symbol.dispose]?(): void;        // alias for close() when Symbol.dispose exists
+  readonly changes: number;
+  readonly lastInsertRowid: number | bigint;
 }
 
 interface Statement {
-  bind(...params: unknown[]): Statement;
-  run(...params: unknown[]): { changes: number; lastInsertRowid: number | bigint };
-  all<T = Record<string, unknown>>(...params: unknown[]): T[];
-  get<T = Record<string, unknown>>(...params: unknown[]): T | undefined;
+  run(...params: BindValue[]): RunResult;
+  all<T = QueryRow>(...params: BindValue[]): T[];
+  get<T = QueryRow>(...params: BindValue[]): T | undefined;
+  result(...params: BindValue[]): ResultSet; // includes columns + values when zero rows
+}
+
+interface RunResult {
+  changes: number;
+  lastInsertRowid: number | bigint;
+}
+
+interface ResultSet {
+  columns: string[];
+  rows: QueryRow[];
+  values: QueryValue[][];           // always present (empty array for zero rows)
+  changes: number;
+  lastInsertRowid: number | bigint;
 }
+
+class SqliteError extends Error {
+  readonly category: ErrorCategory; // syntax, no_such_table, constraint_unique, misuse, …
+  readonly sqliteCode: string;      // always set; default "SQLITE_ERROR"
+  readonly code: string;            // === sqliteCode (Node err.code convention)
+}
+```
+
+Stick to `Database`, `Statement`, and `SqliteError` for application code. Advanced internals (`parse`, `tokenize`, `evalExpr`, snapshot codec pieces, `SqlValue` utilities, `Prng`, …) are available only from `@crvouga/sqlite-mem/unstable` and are **exempt from semver**.
+
+### Method semantics
+
+| Method | Behavior |
+| --- | --- |
+| `exec(sql)` | Runs all semicolon-separated statements; **discards** row results (`void`). Does **not** accept bind parameters. Read `db.changes` / `db.lastInsertRowid` afterward if needed (counters reflect the **most recent** completed statement, matching SQLite). |
+| `query(sql, params?)` | **Single statement only** (trailing `;` is fine). Returns all rows. Multi-statement scripts throw `misuse`. |
+| `prepare(sql)` | **Single statement only**. Parses immediately; AST is reused. Pass binds as rest args to `run` / `all` / `get` / `result` on each call. |
+| `transaction(fn)` | If idle: `BEGIN` → `fn()` → `COMMIT`, or `ROLLBACK` + rethrow. If already in a transaction: nested savepoint. Nested SQL `BEGIN` still errors. `close()` inside `fn` throws `misuse`. |
+| `snapshot` / `restore` | Custom binary format (see below). |
+| `close()` | Idempotent; rolls back an open SQL transaction; further ops throw `misuse`. Also available as `[Symbol.dispose]` when supported. |
+
+SQL `BEGIN` / `COMMIT` / `ROLLBACK` / `SAVEPOINT` / `RELEASE` are first-class. Empty / comment-only SQL on `prepare` / `query` throws `misuse` (`empty statement`), matching SQLite prepare failure.
+
+### Parameter binding
+
+Supported styles: `?`, `?NNN`, `:name`, `@name`, `$name`.
+
+- The JS API takes **rest args** (or a positional array into `query`) only — there is **no** sticky `bind()` and **no** `bind({ name: value })`.
+- Named parameters occupy slots in **first-occurrence order**; repeated names share one slot.
+- Prefixes are part of the name: `@x`, `$x`, and `:x` are **three different** parameters.
+- Names are lowercased for lookup (`:Left` ≡ `:left`).
+- Bindable: `null`, `string`, finite `number`, `bigint`, `boolean` → `0`/`1`, `Uint8Array` / `ArrayBuffer`.
+- Rejected (`misuse`): `DataView`, typed-array views other than `Uint8Array`, `SharedArrayBuffer` / SAB-backed buffers.
+- Rejected (`datatype_mismatch`): `undefined`, `Date`, plain objects, `NaN` / `Infinity`.
+
+```ts
+db.query(`SELECT ? AS a, :name AS b`, [1, "Alice"]);
+db.prepare(`SELECT @id AS id`).get(42);
 ```
 
+### Returned JavaScript types
+
+| SQL storage | JS value | Notes |
+| --- | --- | --- |
+| NULL | `null` | Never `undefined` |
+| INTEGER | `number` or `bigint` | `bigint` when outside `Number.MAX_SAFE_INTEGER` |
+| REAL | `number` | Including integer-valued reals (`1.0` → `1`); use SQL `typeof()` to distinguish from INTEGER |
+| TEXT | `string` | JSON subtype unwrapped to string |
+| BLOB | `Uint8Array` | |
+
+Duplicate column names collapse in row objects (last write wins). Use `stmt.result().values` for positional cells.
+
+### Snapshots
+
+- Format magic `SQLM` followed by an explicit little-endian format-version `u32` — **not** a portable `.sqlite` file and not loadable by the SQLite CLI.
+- Round-trips ordinary tables, views, indexes, change counters, PRNG state, and clock.
+- **Not** encoded: triggers, ATTACH’d schemas, virtual tables (FTS / RTREE / …), `userVersion`.
+- Cannot `restore()` while a transaction is open.
+- `restore()` replaces `now` with a fixed clock from the snapshot (a live `() => Date` is overwritten).
+- Equivalent databases produce byte-identical snapshots (schema/rows sorted) **within a single library version**.
+- **Compatibility policy:** newer library versions can always restore older snapshots; older libraries cannot restore newer format versions (`snapshot_version` / `SQLITE_FORMAT`). Corrupt magic yields a distinct error.
+
 ## Determinism
 
 The engine is deterministic by default. Invariants:
 
 | Source | Default | Override / notes |
 | --- | --- | --- |
-| `random()` / `randomblob()` | Seeded xorshift64* (`seed: 1`) | `new Database({ seed })` or `{ prng }` |
+| `random()` / `randomblob()` | Seeded xorshift64* (`seed: 1`) | `new Database({ seed })` |
 | `date('now')` / friends | Fixed `2000-01-01T00:00:00.000Z` | `new Database({ now: Date \| (() => Date) })` |
 | Table scans | Rowid order | Same order after `snapshot`/`restore` |
 | Snapshots | Sorted schema/rows + PRNG state + clock | Restored into PRNG and `now` |
@@ -86,12 +196,53 @@ SQLITE_MEM_FUZZ_SEED=12345 bun test tests/fuzz
 SQLITE_MEM_FUZZ_SEED=12345 SQLITE_MEM_FUZZ_PATH='0:1' bun test tests/fuzz  # exact replay
 ```
 
+## Stability policy
+
+The exports of the main entry (`@crvouga/sqlite-mem`) are **frozen**:
+
+- **Never** outside a major: removals, renames, signature changes, or changes to documented behavior of the stable surface.
+- **Allowed in minors:** additions (new methods, new optional `DatabaseOptions` fields, new `ErrorCategory` values). Consumers that `switch` on `category` must include a default case — new categories may appear without a major bump.
+- **`@crvouga/sqlite-mem/unstable`** is exempt from semver and may change or disappear in any release.
+- **Snapshots:** newer library → can restore older blobs; older library → cannot restore newer format versions; byte-identical snapshot guarantee holds only within one library version.
+
+## Compatibility notes for integrators
+
+Goal: drop-in SQL behavior vs SQLite **3.51.0**. Full matrix: [COMPATIBILITY.md](COMPATIBILITY.md).
+
+**Intentional differences:** custom `SQLM` snapshots; seeded `random()` / fixed `'now'`; no C API / on-disk DB / VFS.
+
+**Know these thin or partial areas** (do not assume full oracle fidelity):
+
+- FTS3/4/5 — largely implemented; shadow-table change counters intentionally diverge; some edges partial
+- `EXPLAIN` / `EXPLAIN QUERY PLAN` — stub shapes, not real bytecode
+- `INDEXED BY` / `NOT INDEXED` — parsed and discarded
+- Unknown `PRAGMA` succeeds with an empty result (SQLite-like); storage/journal/WAL pragmas N/A or no-op
+
+## Common pitfalls
+
+1. **Do not `await`** — the API is sync.
+2. **No named-object binds and no sticky `bind()`** — pass positional rest args / arrays in declaration order to `query` / `run` / `all` / `get` / `result`.
+3. **`query` / `prepare` are single-statement only** — multi-statement scripts belong in `exec()` (which does not take bind parameters).
+4. **`exec` returns `void` and takes no params** — use `db.prepare(…).run(…)` or `db.query(…)` for binds; use `db.changes` / `stmt.run()` for counters.
+5. **`'now'` is not wall-clock** unless you pass `{ now: () => new Date() }`. Default is year 2000.
+6. **`random()` is seeded**, not OS entropy; snapshots restore the PRNG.
+7. **Snapshots are not `.sqlite` files** and do not round-trip FTS / triggers / ATTACH.
+8. **No better-sqlite3 extras** — no `iterate`, `pluck`/`raw`, `safeIntegers` option, `pragma()` helper, `loadExtension`, or SQLite-file `serialize()`.
+9. **Do not bind `Date` objects** — store unixepoch integers or ISO text. Do not bind `DataView` / non-`Uint8Array` typed arrays.
+10. **Do not use `Number.isInteger` for SQL REAL vs INTEGER** — use SQL `typeof()`.
+11. **Do not import `@crvouga/sqlite-mem/unstable` in application code** unless you accept breakage in any release.
+
+Working examples beyond this README: `examples/react-vite`, `tests/contract/api/`, `tests/contract/parameters/`, `tests/browser/run.ts`.
+
 ## Development
 
-Requires [Bun](https://bun.sh).
+Requires [Bun](https://bun.sh). For architecture, change checklists, and how to add contract tests, see **[AGENTS.md](AGENTS.md)**.
+
+Parity is proven only by differential contracts against real SQLite (`bun:sqlite`). Isolated internal unit tests are not SQLite compatibility proof.
 
 ```bash
 bun install
+bun run ci:local             # same gates as GitHub Actions CI (except publish)
 bun run check                # format + lint + typecheck + sqlite-compat suite
 bun run format               # write Biome formatting
 bun run lint                 # Biome lint
@@ -99,10 +250,10 @@ bun run typecheck
 bun run test:sqlite-compat   # requirements + inventory gate + differential suite
 bun test                     # contract + fuzz + harness
 bun run build
-bun run test:browser         # Playwright smoke (Chrome/Firefox/Safari)
+bun run test:browser         # Playwright smoke (Chrome/Firefox/Safari; CI uses Chromium)
 ```
 
-Contract tests compare the pure TypeScript engine against real SQLite (`bun:sqlite`). See [COMPATIBILITY.md](./COMPATIBILITY.md).
+See [COMPATIBILITY.md](./COMPATIBILITY.md).
 
 ## Releasing
 
@@ -137,8 +288,7 @@ PR titles must also follow Conventional Commits (enforced in CI). Prefer squash
 Local checks:
 
 ```bash
-bunx commitlint --last --verbose
-bun run build && bun run verify-package
+bun run ci:local             # commitlint + quality + tests + browser + benchmarks
 # dry-run needs a GitHub token for API calls; CI publish uses Trusted Publishing (no NPM_TOKEN)
 bun run release:dry-run
 ```