@crvouga/postgres-mem 0.1.0

package/AGENTS.md

@@ -0,0 +1,159 @@
+# AGENTS.md — contributing to postgres-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:** PostgreSQL 18 **SQL dialect** behavioral parity vs **PostgreSQL 18.3** (PGlite, `@electric-sql/pglite`). Same statements → same observable results (rows, errors, SQLSTATEs, row counts), proven by differential contracts and a fail-closed gate.
+
+**Allowed intentional differences:**
+
+1. Custom snapshot codec (`PGMM`), not `pg_dump` / on-disk clusters
+2. Deterministic `random()` / `gen_random_uuid()` and fixed `now()` by default (injectable)
+3. Single-session engine: no MVCC across connections, no wire protocol, no aborted-transaction (`25P02`) state
+4. `NOT APPLICABLE` items: roles/auth enforcement, replication, VACUUM internals, storage params, PL/pgSQL
+
+**Non-goals:** speaking the wire protocol, matching `pg`/`postgres.js` client APIs, PL/pgSQL, or multi-session concurrency.
+
+## 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 / session / triggers
+```
+
+Public entry points: `Database.exec` / `query` / `prepare` / `copyFrom` in [`src/api/database.ts`](src/api/database.ts).
+
+Everything is **typed values** (`TypedValue = { t: TypeId, v: Datum }` in [`src/types/value.ts`](src/types/value.ts)) — there is no SQLite-style affinity. Type resolution/casting lives in [`src/types/resolve.ts`](src/types/resolve.ts) and [`src/types/cast.ts`](src/types/cast.ts); `numeric` is an in-repo arbitrary-precision implementation ([`src/types/numeric.ts`](src/types/numeric.ts)).
+
+## `src/` map
+
+| Directory | Role |
+| --- | --- |
+| `api/` | Public `Database` / `Statement` facade, bind-value conversion |
+| `ast/` | Discriminated-union AST (`nodes.ts`) |
+| `lexer/` | Tokenizer (dollar quoting, E-strings, `::`, operators) |
+| `parser/` | Recursive-descent parser |
+| `executor/` | Statement dispatch, SELECT, DML, DDL, session (SET/SHOW/COPY/PREPARE), triggers, window functions |
+| `expressions/` | `evalExpr`, operators, pattern matching, `EngineCtx` |
+| `functions/` | Scalar / aggregate / window / datetime / JSON / array / SRF / tsearch registries |
+| `types/` | `TypedValue`, casts, comparison, numeric, datetime, jsonb, timezone |
+| `storage/` | In-memory schemas, tables, sequences, `DatabaseState` |
+| `schema/` | `pg_catalog` + `information_schema` virtual catalogs, `search_path` |
+| `constraints/` | NOT NULL / PK / UNIQUE / CHECK / FK with referential actions |
+| `transactions/` | BEGIN / COMMIT / SAVEPOINT (clones state + PRNG) |
+| `runtime/` | Clock, PRNG, `DatabaseOptions` |
+| `serialization/` | `PGMM` snapshot codec |
+| `tsearch/` | `tsvector` / `tsquery` text search |
+| `errors/` | `PostgresError` with SQLSTATE, `unsupported()` |
+
+Hot / large files: `parser/parser.ts`, `executor/select.ts`, `executor/dml.ts`, `types/numeric.ts`.
+
+## Critical conventions
+
+- **AST `type` tags** are snake_case (`"create_table"`, `"drop_index"`). TypeScript interfaces are PascalCase (`CreateTableStmt`).
+- **Identifiers** fold to **lowercase** unless double-quoted (PostgreSQL rule); quoted identifiers are case-sensitive.
+- **Engine values** are `TypedValue` with PG internal type names (`int4`, `float8`, `numeric`, `timestamptz`, `_int4` for arrays). **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 **`PostgresError`** with an `ErrorCategory` and a five-character **SQLSTATE**. Missing SQL must fail loud via `unsupported()` (`0A000`) — the inventory gate fails if the oracle exposes an unimplemented builtin/operator that isn't in `compat/unsupported-register.json`.
+- The public API is **sync**; the oracle (PGlite) is **async** — contract helpers `await` both sides through the `ContractDb` adapter interface.
+- TypeScript: `strict` + `noUncheckedIndexedAccess`. Imports use `.ts` extensions. Biome: 2-space, double quotes, 120 columns.
+- Determinism invariants (seeded PRNG, fixed clock, PRNG rollback with transactions, byte-identical snapshots) must hold — 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` / `session.ts` as needed)
+4. Mutate `DatabaseState` if schema changes; keep `pg_catalog` / `information_schema` views consistent
+5. Add differential contract under `tests/contract/<area>/`
+6. Add/extend a scenario row in `compat/sections/*.ts` and its catalog test in `tests/contract/catalog/`
+
+### New SQL function or operator
+
+1. Implement and register in the right map under `src/functions/*` (or `src/expressions/operators.ts`) so [`scripts/postgres-inventory.ts`](scripts/postgres-inventory.ts) sees it; remove any matching entry from `compat/unsupported-register.json`
+2. Contract tests under `tests/contract/functions/` (and related areas)
+3. Run `bun run inventory` / `bun run test:postgres-compat` — oracle builtins must not be silently missing
+
+### New contract test
+
+1. Prefer helpers in [`tests/contract/helpers.ts`](tests/contract/helpers.ts):
+ - `parity` — query both engines, compare rows
+ - `parityTyped` — also compare column type names
+ - `execParity` — writes (row counts + final state)
+ - `sequenceParity` — multi-step (optional final-state compare)
+ - `errorParity` / `queryErrorParity` — both must fail with the same SQLSTATE class
+ - `rankParity` — REAL epsilon compare (ts_rank etc.)
+ - `divergence` — engine-only assertion pinned to a `compat/divergences.json` entry
+2. Or `matrixBoth` + `expectParity` from `tests/harness/`
+3. **Do not** treat isolated internal unit tests as PostgreSQL proof. The differential suite is authoritative.
+4. Gate: `bun run test:postgres-compat`
+
+## Test layout
+
+| Path | Role |
+| --- | --- |
+| `tests/contract/` | Differential SQL vs PGlite (**authoritative**) |
+| `tests/fuzz/` | fast-check property tests (seeded); differential, NoREC/TLP metamorphic, stateful DST |
+| `tests/harness/` | Compare/normalize/classify helpers + harness unit tests |
+| `tests/adapters/` | Wrappers for postgres-mem and PGlite (`ContractDb`) |
+| `tests/corpus/` | Fuzz regression corpus |
+| `tests/meta/` | Canary definitions, skip register |
+
+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
+POSTGRES_MEM_FUZZ_SEED=12345 bun test tests/fuzz
+POSTGRES_MEM_FUZZ_SEED=12345 POSTGRES_MEM_FUZZ_PATH='0:1' bun test tests/fuzz
+```
+
+## Compat system
+
+| Command | Role |
+| --- | --- |
+| `bun run test:postgres-compat` | Requirements + fail-closed gate + construct catalog + smoke ratchet + contract/fuzz/harness |
+| `bun run inventory` | Oracle `pg_proc` / `pg_operator` vs engine registries (+ `--write-register`) |
+| `bun run scenarios` | Construct-level scenario catalog (`compat/scenarios.ts`) + smoke gate |
+| `bun run requirements` | Refresh PostgreSQL 18 SQL-commands docs → `compat/requirements.json` + `compat/coverage.json` |
+| `bun run canaries` | Apply deliberate sabotages, assert the suite catches them |
+
+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; trivial probes are tracked in `compat/smoke-baseline.json` (ratchet — no new smoke stubs). Documented divergences bind to `compat/divergences.json` (regenerate `DIVERGENCES.md` with `bun run divergences`). Generated operator/CAST matrices: `tests/contract/matrices/`. Stateful dump-after-each fuzz: `tests/fuzz/stateful.test.ts`. Oracle `server_version` must be on the allow-list in `tests/harness/oracle-versions.ts` (18.3).
+
+**PGlite quirk:** PGlite's WASM boot leaks `process.exitCode = 99` under Bun ([pglite#975](https://github.com/electric-sql/pglite/issues/975)); the adapter and scripts reset it — keep that workaround when touching `tests/adapters/pglite.ts`.
+
+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 + postgres-compat suite
+bun run format
+bun run lint
+bun run typecheck
+bun run test:postgres-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

@@ -0,0 +1,155 @@
+# PostgreSQL 18 Compatibility Audit
+
+```text
+PostgreSQL 18 Compatibility Audit
+=================================
+
+Reference PostgreSQL version:
+  PGlite (@electric-sql/pglite) — real PostgreSQL 18.3 compiled to WASM,
+  in-process, no Docker. server_version pinned in
+  tests/harness/oracle-versions.ts and asserted by the gate.
+
+postgres-mem version:
+  0.0.0-development (package.json; publish via semantic-release)
+
+Scope:
+  Every oracle-exposed SQL construct is in-scope except NOT APPLICABLE
+  (roles/auth enforcement, replication, wire protocol, storage internals,
+  PL/pgSQL, extensions). The gate fails closed on silence.
+
+PostgreSQL requirements reviewed:
+  183 SQL commands (from the PostgreSQL 18 SQL-commands documentation
+  index → compat/requirements.json)
+
+Requirements classification:
+  NOT APPLICABLE:  56
+  SQL_BEHAVIOR:    127
+  unknown:         0 (gate fails if non-zero)
+
+Coverage statuses (SQL_BEHAVIOR):
+  VERIFIED: 43 / PARTIALLY_VERIFIED: 26 / UNSUPPORTED: 58 (fail-loud,
+  registered) — see `bun run requirements` / compat/coverage.json
+
+Oracle builtin inventory:
+  pg_catalog functions exposed by oracle: 2787
+  implemented in engine registries:        301
+  registered unsupported (with reasons):  2486
+  silently missing:                          0 (gate fails otherwise)
+  pg_catalog operators exposed by oracle:   74
+  implemented:                              41
+  registered unsupported:                   33
+
+Construct catalog:
+  945 scenarios across 33 sections (compat/scenarios.ts), all promoted
+  to executing catalog tests; smoke baseline EMPTY (0 trivial stubs).
+
+SQL grammar / operators / expressions:
+  VERIFIED — contracts + generated operator matrices from pg_operator
+
+Types / casts / NULL:
+  VERIFIED — bool/int2/4/8, float4/8, numeric (in-repo arbitrary
+  precision), text/varchar/char, bytea, uuid, date/time/timestamp[tz],
+  interval, json/jsonb, arrays; cast matrices generated from pg_cast;
+  3VL through operators/aggregates/DISTINCT
+
+Functions (oracle surface):
+  VERIFIED for the implemented 301; every other oracle builtin is an
+  explicit register entry (never silent)
+
+JSON / JSONB:
+  VERIFIED — operator + function surface, jsonpath subset
+
+Aggregates / windows:
+  VERIFIED — FILTER, ORDER BY in aggregates, string_agg/array_agg/
+  jsonb_agg, full frame specs incl. GROUPS/RANGE + EXCLUDE
+
+CTEs / transactions / savepoints / constraints / FK:
+  VERIFIED — recursive + data-modifying CTEs; FK actions (CASCADE/SET
+  NULL/SET DEFAULT/RESTRICT/NO ACTION); DEFERRABLE parsed, checked at
+  statement end (commit-time deferral is a documented gap)
+
+Schemas / search_path / catalogs:
+  VERIFIED — pg_catalog + information_schema commonly-queried subset
+
+Sequences / serial / identity / enums / domains / generated columns:
+  VERIFIED
+
+Triggers / LANGUAGE sql functions:
+  PARTIALLY VERIFIED — row-level triggers fire in creation order
+  (PostgreSQL: name order), UPDATE OF ignored, INSTEAD OF unsupported —
+  all pinned divergences
+
+Text search:
+  PARTIALLY VERIFIED — tsvector/tsquery/@@/ts_rank with simple-style
+  config; no ispell/synonym dictionaries
+
+COPY / PREPARE / EXECUTE / SET / SHOW:
+  VERIFIED — text + csv COPY via copyFrom API hook; GUC subset
+
+Collation:
+  Pinned C semantics; locale/ICU out of scope (documented)
+
+Snapshots / determinism:
+  VERIFIED — PGMM logical round-trip, byte-identical snapshots, PRNG
+  rollback with transactions, fixed clock, post-restore lockstep
+
+Differential tests (2026-08-21 initial audit):
+  Total: 3400 under `bun test` / `bun run test:postgres-compat`
+    (contract + fuzz + harness; Bun 1.4.0, PGlite/PostgreSQL 18.3)
+  Passed: 3400
+  Failed: 0
+  expect() calls: 8968
+  Files: 273 (246 contract)
+
+Stateful / fuzz:
+  Seeds: 0x5a17e0e1 (+ POSTGRES_MEM_FUZZ_SEED override, PATH replay)
+  Differential grammar fuzz, per-area fuzz (17 areas), TLP + NoREC
+  metamorphic, stateful DST with minimizer/repro, mixed-stateful,
+  robustness (PostgresError-only), corpus regressions
+  Mismatches: 0
+
+Harness integrity:
+  PGlite adapter compares rows (canonical text), column names/types,
+  SQLSTATE class + normalized messages, rowCount/command tags, and
+  logical state dumps after write sequences. Comparator meta-tests:
+  tests/harness/*.test.ts. Canaries: 6 deliberate sabotages, each
+  caught by the suite (bun run canaries). Skip register: empty.
+
+Engine bugs found & fixed by the differential/fuzz process (this build):
+  1. sum() crashed on certain inputs surfaced by grammar fuzz
+  2. min()/max() returned unnormalized numeric cells
+  3. NULL IN (empty subquery) returned NULL instead of false
+  4. FULL JOIN did not enforce the join condition on one side
+  (regression tests added under tests/contract/*; area corpus scripts
+  replayed by tests/fuzz/corpus.test.ts)
+
+Remaining known differences / intentional:
+  Custom PGMM snapshots; deterministic random()/now() by default
+  ({ random: "os" } / { now: "system" } match PostgreSQL entropy and
+  wall clock); sync single-session API; COPY payloads via copyFrom;
+  no 25P02 aborted-transaction state; trigger creation-order firing;
+  UPDATE OF ignored; no INSTEAD OF triggers; round(float8) ties away
+  from zero; '1e400'::float8 saturates; DROP CASCADE retains dependent
+  views; COMMENT ON not stored; version() banner; pg_get_viewdef
+  missing; EXPLAIN stubs. Machine-readable: compat/divergences.json
+  (18 entries, each pinned).
+
+Final assessment:
+  Verified against PostgreSQL 18.3 (PGlite on Bun 1.4.0). Oracle
+  function/operator inventory is closed (0 silently missing).
+  Requirements matrix ingested with zero unknown statuses. Gate:
+  `bun run test:postgres-compat`. Triggers, text search, collation,
+  numeric extremes, and catalog long tail remain PARTIALLY VERIFIED
+  honestly — not “fully compatible because green.”
+```
+
+Verification commands:
+
+```bash
+bun run test:postgres-compat
+bun run inventory
+bun run requirements
+bun run scenarios
+bun run canaries
+bun run typecheck
+```

package/COMPATIBILITY.md

@@ -0,0 +1,87 @@
+# Compatibility
+
+Goal: **PostgreSQL 18 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:postgres-compat
+```
+
+See [COMPATIBILITY-AUDIT.md](COMPATIBILITY-AUDIT.md) for the latest evidence-based audit report.
+
+Reference oracle: **PostgreSQL 18.3** via PGlite (`@electric-sql/pglite`, real Postgres compiled to WASM, in-process). 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
+
+Differential tests compare a **tuple** per statement: rows (normalized to canonical PostgreSQL text where typed), column names and type names where requested, error SQLSTATE class + normalized message, command tag / `rowCount`, and transaction status, plus a **logical state dump** (catalog names, column definitions, row payloads, sequence values) after write sequences.
+
+A catalog ID appearing in a test file is **not** proof by itself. Trivial probes are tracked in [`compat/smoke-baseline.json`](compat/smoke-baseline.json) and ratcheted downward (currently **0 smoke stubs** across 945 catalog scenarios). Generated operator/cast matrices live under [`tests/contract/matrices/`](tests/contract/matrices/). Observed mem≠oracle diffs must bind to a `compat/divergences.json` entry or be a **FAILURE** — unexplained diffs are not allowed.
+
+Intentional differences are finite and machine-readable in `compat/divergences.json` (PGMM snapshots, seeded `random()`/`now()`, sync single-session API, no aborted-transaction state, EXPLAIN stubs, trigger-order/`UPDATE OF` edges, float8 rounding/overflow edges, …). Human-readable: [DIVERGENCES.md](DIVERGENCES.md).
+
+## 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 and unregistered) |
+| **NOT APPLICABLE** | Outside the in-memory single-session dialect surface (roles/auth, replication, storage, wire protocol) |
+
+## Scope bound
+
+Anything a PostgreSQL application can invoke through SQL against the PGlite **18.3** oracle must match observable behavior, except:
+
+1. **Snapshot format** — custom binary codec (`PGMM`), not `pg_dump` / on-disk clusters (logical state still round-trips).
+2. **Deterministic `random()` / `now()`** — seeded PRNG and fixed clock by default (injectable).
+3. **Single session** — no MVCC across connections, no isolation levels beyond one session, no `25P02` aborted-transaction state (documented divergence).
+4. **NOT APPLICABLE** rows in `compat/coverage.json` (roles, replication, VACUUM internals, LISTEN/NOTIFY, cursors, PL/pgSQL, extensions).
+
+The oracle exposes **2787 builtin functions** and **74 operators** in `pg_catalog`; postgres-mem implements **301 functions** and **41 operators**, and every remaining item is an explicit entry in [`compat/unsupported-register.json`](compat/unsupported-register.json) with a reason (trigger/internal plumbing, admin/monitoring, unsupported type families, …). The gate fails closed on silence.
+
+## Requirements coverage (PostgreSQL 18 SQL commands)
+
+`bun run requirements` ingests the PostgreSQL 18 SQL-commands documentation index: **183 commands** → 56 NOT APPLICABLE, 127 SQL-behavior. Of the SQL-behavior commands: **43 VERIFIED**, **26 PARTIALLY VERIFIED**, **58 UNSUPPORTED** (fail-loud, registered). Full detail: `compat/coverage.json`.
+
+## Feature matrix (summary)
+
+| Area | Status | Notes |
+| --- | --- | --- |
+| Core DML / SELECT / joins / CTE / ON CONFLICT / RETURNING | VERIFIED | Contract + fuzz |
+| Types: bool/int2/4/8, float4/8, numeric, text/varchar/char, bytea, uuid | VERIFIED | numeric is in-repo arbitrary precision |
+| Date/time: date, time, timestamp[tz], interval + arithmetic | VERIFIED | Timezone conversions for named zones; some interval corners partial |
+| Casts (implicit/assignment/explicit) | VERIFIED | Generated cast matrices from oracle |
+| Arrays + unnest + subscripts/slices | VERIFIED | |
+| JSON / JSONB operators + functions | VERIFIED | |
+| Window functions (frames, EXCLUDE) | VERIFIED | |
+| GROUPING SETS / ROLLUP / CUBE, DISTINCT ON, LATERAL, set ops | VERIFIED | |
+| Recursive + data-modifying CTEs | VERIFIED | |
+| Constraints: PK / UNIQUE / NOT NULL / CHECK / FK actions | VERIFIED | DEFERRABLE parsed, checked at statement end |
+| Sequences / serial / identity | VERIFIED | |
+| Schemas + search_path + pg_catalog / information_schema | VERIFIED | Catalog columns are the commonly-queried subset |
+| Enums, domains, generated columns | VERIFIED | |
+| Triggers (row-level, LANGUAGE sql-expressible) | PARTIALLY VERIFIED | Creation-order firing, `UPDATE OF` ignored, no INSTEAD OF (documented) |
+| CREATE FUNCTION LANGUAGE sql | PARTIALLY VERIFIED | Scalar + set-returning; no polymorphic/variadic edges |
+| Text search (tsvector / tsquery / @@ / ts_rank) | PARTIALLY VERIFIED | `simple`-style config; no ispell/synonym dictionaries |
+| COPY FROM/TO (text, csv) | VERIFIED | Via `copyFrom` API hook / rows out |
+| PREPARE / EXECUTE / DEALLOCATE, SET / SHOW / RESET | VERIFIED | GUC subset |
+| Transactions / savepoints | VERIFIED | No `25P02` aborted state (documented divergence) |
+| Collation / ordering | PARTIALLY VERIFIED | `C` semantics pinned; locale/ICU out of scope |
+| Regex (`~`, `~*`, POSIX functions) | PARTIALLY VERIFIED | JS regex flavor mapped to POSIX ERE; documented edges |
+| EXPLAIN | PARTIALLY VERIFIED | Stub plan shapes |
+| MERGE / CALL / cursors / LISTEN / PL/pgSQL | UNSUPPORTED | Fail loud `0A000`, registered |
+| Roles / GRANT / VACUUM / ANALYZE / LOCK | NOT APPLICABLE | Parsed no-ops where harmless |
+| Wire protocol / multi-session MVCC / on-disk format | NOT APPLICABLE | |
+
+## How to verify
+
+```bash
+bun run test:postgres-compat # requirements + gate + contract/fuzz/harness
+bun run inventory            # oracle pg_proc/pg_operator inventory
+bun run requirements         # refresh PostgreSQL 18 requirements + coverage
+bun run scenarios            # catalog + smoke ratchet
+bun run build                # ESM browser build
+```
+
+Do not treat isolated unit tests of internal modules as proof of PostgreSQL compatibility. The differential suite is authoritative for SQL behavior; `test:postgres-compat` is the release gate.
+
+**Parity claim:** Verified against **PostgreSQL 18.3** (PGlite). 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.