@crvouga/mockingbird-service-sqlite 0.1.0

package/AGENTS.md

@@ -0,0 +1,170 @@
+# 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.
+- **Dual-path invariant:** residual `WHERE` filtering is skipped on an index/hash access path only when `whereFullyCovered(where, coveredColumns, …)` is true (see [`src/planner/access.ts`](src/planner/access.ts)). Any change to WHERE/join/insert semantics requires updating both fast and full paths **and** the fast≡full property tests under `tests/fuzz/fast-path.test.ts`.
+- Internal invariants use always-on asserts in [`src/runtime/assert.ts`](src/runtime/assert.ts) (`assert`, `assertUnreachable`, `assertRowShape`).
+- 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
+```
+
+### Random walk (state-dependent DST)
+
+`tests/fuzz/random-walk.test.ts` walks the SQL state space one enabled action at
+a time and asserts result + logical-state parity after every step.
+
+```bash
+bun run test:walk
+SQLITE_MEM_WALK_STEPS=80 bun run test:walk
+bun run test:walk:soak -- --depth 200 --runs 20
+```
+
+## Compat system
+
+| Command | Role |
+| --- | --- |
+| `bun run test:sqlite-compat` | Requirements + fail-closed gate + construct catalog + 𝔇 + smoke ratchet + contract/fuzz/harness |
+| `bun run inventory` | Oracle `pragma_function_list` / modules vs memory registries |
+| `bun run scenarios` | Construct-level scenario catalog (`compat/scenarios.ts`) + 𝔇 / smoke gates |
+| `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.
+
+**Catalog vs proof:** `tests/contract/catalog/` IDs must execute; smoke (`SELECT 1 AS v`) is tracked in `compat/smoke-baseline.json`. Documented divergences bind to `compat/divergences.json`. Generated operator/CAST matrices: `tests/contract/matrices/`. Stateful dump-after-each fuzz: `tests/fuzz/stateful.test.ts`. Oracle `sqlite_version()` must be 3.51.0 or 3.53.0.
+
+Details: [COMPATIBILITY.md](COMPATIBILITY.md), audit: [COMPATIBILITY-AUDIT.md](COMPATIBILITY-AUDIT.md).
+
+## Local gates
+
+Requires [Bun](https://bun.sh).
+
+```bash
+bun install
+bun run check:full             # 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 on PRs). Prefer squash merges with a conventional title so the npm bump is `feat` → minor / `fix` → patch. Direct pushes to `main` with any other subject still publish a patch. See [README.md](README.md#releasing).

package/COMPATIBILITY-AUDIT.md

@@ -0,0 +1,236 @@
+# SQLite3 Compatibility Audit
+
+```text
+SQLite3 Compatibility Audit
+===========================
+
+Reference SQLite version:
+  bun:sqlite (SQLite 3.51.0)
+
+Reference SQLite compile options:
+  ENABLE_MATH_FUNCTIONS, ENABLE_FTS3/4/5, ENABLE_RTREE, ENABLE_DBSTAT_VTAB,
+  ENABLE_BYTECODE_VTAB, JSON builtin (not OMIT_JSON), plus Bun/SEE codec flags.
+  Full list: `bun run inventory`
+
+sqlite-mem version:
+  0.0.0-development (package.json; released from the monorepo via `<name>@<version>` tags)
+
+Scope:
+  Scope 3 — every oracle-exposed SQL builtin/module is in-scope except
+  NOT APPLICABLE (C API, on-disk format, VFS/pager/WAL).
+
+SQLite requirements reviewed:
+  3487 (from sqlite.org requirements matrix → compat/requirements.json)
+
+SQLite requirements classification:
+  NOT APPLICABLE:     see compat/coverage.json counts.notApplicable
+  SQL_BEHAVIOR:       see counts.sqlBehavior
+  unknown:            0 (gate fails if non-zero)
+
+Coverage statuses (SQL_BEHAVIOR):
+  VERIFIED / PARTIALLY_VERIFIED / UNSUPPORTED — see `bun run requirements`
+  Regenerated via scripts/sqlite-requirements.ts + coverage upgrades.
+
+SQL grammar / operators / expressions:
+  VERIFIED — contracts + row-value comparisons + ->/->> precedence
+
+Types / affinity / NULL:
+  VERIFIED — affinity matrix, typeof/REAL (incl. unary ± float literals),
+  truthiness/3VL, JS-leak bind probes (differential + documented divergences)
+
+Functions (oracle surface):
+  VERIFIED — inventory missingOracleFunctions = 0 (163 names covered)
+
+JSON / JSONB:
+  VERIFIED
+
+Aggregates / windows:
+  VERIFIED — includes string_agg, ntile, cume_dist, percent_rank, EXCLUDE;
+  unaliased aggregate column names (`sum(v)`, `count(*)`) match oracle
+
+CTEs / transactions / savepoints / constraints / FK / triggers:
+  VERIFIED (deferred FK + composite FK + MATCH SIMPLE/FULL + statement ABORT)
+
+Indexes / views / generated / STRICT / WITHOUT ROWID:
+  VERIFIED — partial/expression indexes, STRICT tables, leftmost prefix;
+  WITHOUT ROWID UPSERT; generated STORED/VIRTUAL WHERE/ORDER BY
+
+PRAGMAs:
+  PARTIALLY VERIFIED — schema/FK; storage pragmas N/A or :memory: no-op
+
+ATTACH/DETACH:
+  VERIFIED (in-memory schemas; temp.schema = main state)
+
+Virtual tables / extensions:
+  VERIFIED for oracle modules: fts3/4/5, fts5vocab, rtree/rtree_i32,
+  dbstat, bytecode, tables_used (bytecode/tables_used empty cursors)
+
+ANALYZE / REINDEX / VACUUM:
+  VERIFIED (:memory: observable parity)
+
+Prepared statements / errors / snapshot:
+  VERIFIED — schema invalidation re-prepares; SQLM logical round-trip VERIFIED;
+  post-restore A/B lockstep + dumpLogicalState vs oracle
+
+  Differential tests (2026-08-21 audit refresh):
+  Total: 1912 under `bun test` / `bun run test:sqlite-compat`
+    (contract + fuzz + harness; Bun 1.4.0, SQLite 3.51.0)
+  Passed: 1912
+  Failed: 0
+  expect() calls: 7314
+
+Stateful / fuzz:
+  Seeds: 0x5a17e0e1 (+ SQLITE_MEM_FUZZ_SEED override)
+  Combination fuzz: tests/fuzz/combinations-scope3.test.ts
+  FTS fuzz: tests/fuzz/fts.test.ts
+  Long deterministic scripts: tests/contract/transactions/stateful.test.ts
+  Collate / window / CTE+DML / JSON subtype / affinity / conflicts fuzz
+  Mismatches: 0
+
+Harness integrity (Phase 1):
+  RealSqliteAdapter DML via prepare().run() with live changes/lastInsertRowid
+  sequenceParity compares DML counters; DDL/txn/PRAGMA allowlist neutralized
+  errorParity via deepCompareResults; dumpLogicalState + compareFinalState
+  Comparator meta-tests: tests/harness/normalize.test.ts
+
+Hardening pass (2026-08-19) — incompatibilities found & fixed:
+  1. Comparison affinity (INTEGER/TEXT/NUMERIC column vs literal) missing
+  2. WITH on UPDATE/DELETE/INSERT VALUES dispatched as SELECT only
+  3. Plain INTEGER PRIMARY KEY never reused deleted max rowid
+  4. date() `weekday N` modifier unimplemented
+  5. REGEXP operator not parsed (now calls missing regexp() like oracle)
+  6. last_insert_rowid() stale inside AFTER INSERT triggers
+  7. INSTEAD OF triggers never fired; view DML rejected
+  8. INSERT/UPDATE OR ROLLBACK / OR FAIL not distinguished
+  9. Window GROUPS/RANGE frames, window FILTER, recursive CTE queue edges
+  10. Collation-aware GROUP BY; FTS3 matchinfo format variants; external-content delete
+
+Audit refresh (2026-08-21) — additional findings & fixes:
+  11. sequenceParity previously ignored all DML write counters (hid divergences)
+  12. Unary +/- on float literals dropped REAL storage class (`typeof(-0.0)`)
+  13. UPDATE OR REPLACE counted conflict deletions in changes() (oracle = 1)
+  14. Empty-result column names + unaliased aggregate headers asserted vs oracle
+  15. JS bind edges: empty TEXT/BLOB, BigInt@MAX_SAFE, intentional Number/BigInt
+      bind-class divergences pinned via divergence()
+  16. Snapshot post-restore A/B + state dump vs live oracle
+
+Remaining known differences / intentional:
+  Custom SQLM snapshots; deterministic random()/'now' by default
+  (`random: "os"` / `now: "system"` match SQLite entropy and wall clock);
+  EXPLAIN stubs (shape contracts only); INDEXED BY no-op (documented);
+  ATTACH file path records filename but opens empty in-memory schema;
+  some PRAGMA storage no-ops; FTS shadow-table changes()/total_changes diverge
+  (sequenceParity neutralizeCounters on FTS maintenance paths);
+  MATERIALIZED/NOT MATERIALIZED stored but both materialize today;
+  compile_options / function_list content is sqlite-mem's;
+  generate_series is sqlite-mem extension (not in bun:sqlite default);
+  Number.MAX_SAFE_INTEGER JS bind typeof (mem integer vs bun real);
+  BigInt beyond Number.MAX_SAFE_INTEGER without bun safeIntegers;
+  NOT APPLICABLE C API / on-disk / VFS surfaces; uri.html remapped N/A.
+
+Final assessment:
+  Verified against SQLite 3.51.0 (bun:sqlite on Bun 1.4.0). Oracle
+  function/module inventory is closed (0 missing). Requirements matrix
+  ingested with zero unknown statuses. Gate: `bun run test:sqlite-compat`.
+  Harness now compares live DML counters; green means stronger evidence than
+  pre-2026-08-21. FTS/EXPLAIN remain PARTIALLY VERIFIED honestly — not
+  “fully compatible because green.”
+```
+
+---
+
+## SQLite Full-Text Search Compatibility Audit
+
+```text
+SQLite Full-Text Search Compatibility Audit
+==========================================
+
+Reference SQLite:
+  version: 3.51.0 (bun:sqlite)
+  source_id: 2025-06-12 13:14:41 f0ca7bba1c5e232e5d279fad6338121ab55af0c8c68c84cdfb18ba5114dcaapl
+  compile options: ENABLE_FTS3, ENABLE_FTS3_PARENTHESIS, ENABLE_FTS3_TOKENIZER,
+                   ENABLE_FTS4, ENABLE_FTS5
+  inventory: compat/fts-oracle-surface.json (bun run scripts/fts-oracle-surface.ts)
+
+FTS3: PARTIALLY VERIFIED (MATCH, snippet, offsets; matchinfo formats thinner)
+FTS4: PARTIALLY VERIFIED (same surface as FTS3 for tested paths)
+FTS5: PARTIALLY VERIFIED overall — core MATCH/tokenizers/ranking/aux VERIFIED;
+      external-content + full matchinfo format strings still thinner
+
+Tokenizers verified:
+  unicode61 (incl. remove_diacritics 0/1/2), ascii, porter,
+  porter unicode61, porter ascii, trigram
+
+MATCH grammar verified:
+  terms, AND/OR/NOT, implicit AND, phrases, prefix *, column filters
+  (col : term / {cols} :), NEAR / NEAR(…, N), parentheses, NEAR-as-term
+
+Ranking verified:
+  bm25() / rank column — order + scores vs oracle (1e-15 abs epsilon for ULP)
+
+Auxiliary functions verified:
+  bm25, highlight, snippet (FTS5); snippet, offsets (FTS3/4);
+  matchinfo present (default format PARTIAL)
+
+Content modes verified:
+  normal content tables: VERIFIED
+  contentless (content=''): VERIFIED
+  external content: PARTIALLY VERIFIED (CREATE accepted; sync/triggers thinner)
+
+Special commands verified:
+  optimize, rebuild, integrity-check (success + post-command MATCH)
+  delete-all / merge / automerge: error parity with oracle where probed
+
+Differential tests:
+  Passed: 872 (contract + fuzz + harness)
+  Failed: 0
+  FTS contract: tests/contract/fts/basic.test.ts,
+                tests/contract/fts/comprehensive.test.ts
+                (+ matchinfo formats, external-content, trigger maintenance)
+
+Fuzz cases:
+  Generated: fast-check seed 0x5a17e0e1 (override SQLITE_MEM_FUZZ_SEED)
+  Files: tests/fuzz/fts.test.ts (MATCH queries, tokenizers, stateful DML)
+  Mismatches: 0 (after trigram phrase expansion + NEAR-as-term fixes)
+
+Stateful cases:
+  Operations: INSERT/UPDATE/DELETE/MATCH sequences + txn/savepoint contracts
+  Mismatches: 0
+
+Compatibility gaps found:
+  1. Toy AND-token matcher (replaced)
+  2. Aux functions always threw (wired MATCH cursor + real bm25/highlight/snippet)
+  3. No CREATE option parsing (tokenize=/content=/prefix=/UNINDEXED)
+  4. No FTS5 query language / NEAR / phrases / column filters
+  5. False VERIFIED status on fts5.html / fts3.html (downgraded then re-evidenced)
+
+Compatibility gaps fixed:
+  Positional inverted index; unicode61/ascii/porter/trigram tokenizers;
+  FTS5 query parser; BM25 with SQLite IDF floor 1e-6; highlight/snippet;
+  contentless mode; special commands; FTS3/4 MATCH + snippet/offsets;
+  comparator realEpsilon for ranking ULP only; FTS fuzz suites
+
+Regression tests added:
+  tests/contract/fts/comprehensive.test.ts
+  tests/fuzz/fts.test.ts
+  tests/harness/fts-compare.ts
+  scripts/fts-oracle-surface.ts
+
+Remaining unsupported / thinner functionality:
+  - SQLite FTS shadow tables not mirrored (change counters diverge; documented)
+  - External-content sync/stale-index edge cases thinner
+  - FTS3 matchinfo format-string variants not exhaustively verified
+  - fts3tokenize / fts4aux still thin CREATE stubs
+  - locale / tokendata / detail=none advanced options accepted but lightly tested
+```
+
+Verification commands:
+
+```bash
+bun run test:sqlite-compat
+bun run scripts/fts-oracle-surface.ts
+bun test tests/contract/fts tests/fuzz/fts.test.ts
+bun run inventory
+bun run requirements
+bun run typecheck
+```

package/COMPATIBILITY.md

@@ -0,0 +1,102 @@
+# Compatibility
+
+Goal: **full SQLite3 SQL dialect behavioral parity** as a drop-in for the same statements against the reference oracle. Compatibility is proven by the differential contract suite and the fail-closed gate:
+
+```bash
+bun run test:sqlite-compat
+```
+
+See [COMPATIBILITY-AUDIT.md](COMPATIBILITY-AUDIT.md) for the latest evidence-based audit report.
+
+Reference oracle: **SQLite 3.51.0** (`bun:sqlite`; Linux/Windows bun may report **3.53.0** — see 𝔇 `oracle-platform-sqlite-version`). Inventory: `bun run inventory`. Construct catalog: `bun run scenarios` → [`compat/scenarios.ts`](compat/scenarios.ts). Divergences: [`compat/divergences.json`](compat/divergences.json). Requirements matrix: `bun run requirements` → `compat/requirements.json` + `compat/coverage.json`.
+
+## Proof surface (Phase 1)
+
+Differential tests compare a **B-tuple**: rows (plus `typeof` where requested), column names, error category / sqliteCode / message (Tier A exact or Tier B prefix-normalized), `changes`, `total_changes`, `lastInsertRowid`, and autocommit, plus a **logical Dump** (`sqlite_master` names, `table_info`, row payloads with per-column `typeof`, `sqlite_sequence`, selected pragmas).
+
+A catalog ID appearing in a test file is **not** proof by itself. Cases whose SQL is `SELECT 1 AS v` are **smoke**; [`compat/smoke-baseline.json`](compat/smoke-baseline.json) ratchets that list downward. Generated matrices live under [`tests/contract/matrices/`](tests/contract/matrices/). Observed mem≠oracle diffs must be `known-divergence(id)` from 𝔇 or **FAILURE** — unexplained diffs are not allowed.
+
+Intentional differences are finite and machine-readable in `compat/divergences.json` (SQLM snapshots, seeded `random()`/`now`, ATTACH empty schema, EXPLAIN stubs, INDEXED BY discarded, MATERIALIZED hint ignored, FTS shadow counters, compile_options/function_list, `-0`, JS API extras, snapshot exclusions).
+
+## Status vocabulary
+
+| Status | Meaning |
+| --- | --- |
+| **VERIFIED** | Differential contracts (+ fuzz where applicable) cover happy path **and** meaningful edges vs oracle |
+| **PARTIALLY VERIFIED** | Implemented; coverage thin or known edges remain |
+| **UNSUPPORTED** | Missing from SQL surface (must fail loud; gate fails if oracle-exposed) |
+| **NOT APPLICABLE** | Outside the in-memory dialect surface (C API, on-disk `.sqlite`, VFS/pager/WAL) |
+
+## Scope 3 bound
+
+Anything a SQLite application can invoke through SQL against this Bun/SQLite **3.51.0** build must match oracle observable behavior, except:
+
+1. **Snapshot format** — custom binary codec (`SQLM`), not the on-disk SQLite database file format (logical state still round-trips).
+2. **Deterministic `random()` / `'now'`** — seeded PRNG and fixed clock by default (injectable).
+3. **NOT APPLICABLE** rows in `compat/coverage.json` (C API, VFS, pager, file locking, etc.).
+
+Oracle builtins (math, string extras, uuid, ieee754, …) and modules (FTS3/4/5, RTREE, dbstat, bytecode, tables_used) are **in scope**.
+
+## Feature matrix (summary)
+
+| 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 | Comparison affinity + collation on GROUP BY/JOIN |
+| Constraints / FK / triggers / views / ATTACH | VERIFIED | Deferred FK, composite FK, INSTEAD OF, OR ROLLBACK/FAIL |
+| Windows (incl. ntile/cume_dist/percent_rank) | VERIFIED | EXCLUDE; GROUPS/RANGE frames; window FILTER |
+| 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. |
+
+## FTS compatibility matrix
+
+Reference: **SQLite 3.51.0** (`bun:sqlite`). Inventory: `bun run scripts/fts-oracle-surface.ts` → `compat/fts-oracle-surface.json`.
+
+| Feature | Status |
+| --- | --- |
+| FTS3 | PARTIALLY VERIFIED |
+| FTS4 | PARTIALLY VERIFIED |
+| FTS5 | PARTIALLY VERIFIED |
+| Virtual table creation (options/tokenizers) | VERIFIED |
+| Tokenizers (unicode61/ascii/porter/trigram) | VERIFIED |
+| MATCH grammar (AND/OR/NOT/phrase/prefix/NEAR/columns) | VERIFIED |
+| Boolean operators | VERIFIED |
+| Phrases | VERIFIED |
+| Prefix queries | VERIFIED |
+| NEAR | VERIFIED |
+| Column filters | VERIFIED |
+| Ranking / bm25 / rank | VERIFIED |
+| highlight / snippet | VERIFIED |
+| matchinfo / offsets (FTS3/4) | PARTIALLY VERIFIED | Default + common format strings verified; some FTS4-only formats thinner |
+| Contentless tables | VERIFIED |
+| External content | PARTIALLY VERIFIED | Canonical delete/sync covered; backfill/projection edges thinner |
+| Content tables | VERIFIED |
+| Triggers + FTS | PARTIALLY VERIFIED | Maintenance sequences covered; advanced edges thinner |
+| Special commands (optimize/rebuild/integrity-check) | VERIFIED |
+| Prefix indexes | VERIFIED |
+| Unicode / adversarial corpus | VERIFIED |
+| Transactions / savepoints | VERIFIED |
+| Error behavior | VERIFIED |
+| FTS differential fuzz | VERIFIED |
+| FTS stateful fuzz | VERIFIED |
+| 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 (missing INDEXED BY errors documented) |
+| 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
+
+```bash
+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 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.
+
+**Parity claim:** Verified against **SQLite 3.51.0** (`bun:sqlite`). Features marked **VERIFIED** are oracle-proven. **PARTIALLY VERIFIED** rows must not be marketed as complete. **NOT APPLICABLE** is the only allowed permanent omission from the SQL drop-in claim.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Vouga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.