supaschema 0.1.0-rc.1

package/LICENSE-COMMERCIAL.md

@@ -0,0 +1,35 @@
+# Commercial License
+
+supaschema is dual-licensed: **AGPL-3.0-only** (`LICENSE`) for open-source use, or a **commercial license** for proprietary and hosted use.
+
+## Which license applies to you
+
+You can use supaschema for free under the AGPL-3.0 — including inside your company — as long as you comply with the AGPL. The AGPL's copyleft reaches across a network: if you modify supaschema and let others interact with the modified version over a network, you must offer them the corresponding source under the AGPL.
+
+**You do not need a commercial license to:**
+
+- Use supaschema as a dev dependency to generate and check your own migrations and types.
+- Run it in your own CI against your own repositories.
+- Modify it for internal use, where the modified version is not offered to third parties over a network.
+
+**You need a commercial license to:**
+
+- Embed supaschema (modified or not) in a proprietary product, CLI, or SDK you distribute without releasing your source under the AGPL.
+- Offer supaschema's functionality as part of a **hosted or SaaS service** to third parties without releasing the service's corresponding source under the AGPL.
+- Otherwise use supaschema in a way the AGPL-3.0 would require you to release source you do not wish to release.
+
+If you are unsure whether your use is covered, ask — the goal is for ordinary adoption to stay free and frictionless.
+
+## What the commercial license grants
+
+A commercial license grants the right to use, modify, and distribute supaschema **without** the AGPL's source-disclosure obligations, under terms set in a signed agreement. Scope (per-product, per-seat, per-org, OEM/redistribution) and support level are defined per engagement.
+
+## How to obtain one
+
+Open an issue titled "Commercial license inquiry" on the [project repository](https://github.com/jmclaughlin724/supaschema/issues), or contact the copyright holder listed in `package.json`. Include:
+
+- Your company and the product or service supaschema would be part of.
+- Whether it is distributed software, a hosted service, or both.
+- Approximate scale (repositories, seats, or end customers).
+
+Pricing is quoted per engagement. No rights beyond the AGPL-3.0 are granted without a signed commercial agreement.

package/README.md

@@ -0,0 +1,249 @@
+# supaschema
+
+[![CI](https://github.com/jmclaughlin724/supaschema/actions/workflows/ci.yml/badge.svg)](https://github.com/jmclaughlin724/supaschema/actions/workflows/ci.yml) [![npm version](https://img.shields.io/npm/v/supaschema)](https://www.npmjs.com/package/supaschema) [![npm downloads](https://img.shields.io/npm/dm/supaschema)](https://www.npmjs.com/package/supaschema) [![node](https://img.shields.io/node/v/supaschema)](https://github.com/jmclaughlin724/supaschema/blob/main/package.json) [![license](https://img.shields.io/npm/l/supaschema)](https://github.com/jmclaughlin724/supaschema/blob/main/LICENSE) [![codecov](https://codecov.io/gh/jmclaughlin724/supaschema/branch/main/graph/badge.svg)](https://codecov.io/gh/jmclaughlin724/supaschema) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/jmclaughlin724/supaschema/badge)](https://scorecard.dev/viewer/?uri=github.com/jmclaughlin724/supaschema) [![install size](https://packagephobia.com/badge?p=supaschema)](https://packagephobia.com/result?p=supaschema)
+
+**Declarative Postgres and Supabase migrations in milliseconds — no Docker, no shadow database, no ORM.** supaschema reads your SQL with PostgreSQL's own parser, shipped as WASM inside the package, so it diffs your schema, writes a replay-safe migration, and regenerates your TypeScript + Zod types in a single command — without standing up a database to do it.
+
+- **Fast at any scale.** It parses instead of replaying: a full diff of an 8,300-object production schema runs in under two seconds, where the Supabase CLI's shadow-database engines take minutes. The gap widens from ~20× to ~70× as your schema grows.
+- **Catches the tenant-isolation regression other tools ship.** An RLS policy's `USING` predicate _is_ the tenant boundary. Every Supabase CLI engine diffs policies by name and silently drops a tightened predicate; supaschema compares policy bodies structurally and catches it before it merges.
+- **Replay-safe by construction.** Every statement is guarded (`IF NOT EXISTS`, catalog-checked `DO` blocks), so a crashed or retried deploy just re-runs the file — where the CLI's unguarded `CREATE TABLE` / `CREATE INDEX` fail on the second apply.
+
+```bash
+npx supaschema diff   # writes the migration AND refreshes database.types.ts + database.zod.ts
+```
+
+![Diff latency vs schema size — supaschema stays in seconds where shadow-database engines climb into minutes](docs/benchmarks/scaling-latency.svg)
+
+The promise of declarative schema management sounds great: keep your schema in SQL files, edit them in your editor, diff against your database to produce a type-safe, idempotent migration, and get regenerated types back in your repo.
+
+In practice, the existing tooling needs a running database at every step. Diff engines replay your schema into a throwaway Docker database just to read it, and type generators introspect only what your database has already applied — so an unapplied change sitting in your editor can't produce a migration or its types until the database catches up. That's a backlog, a time sink, and a constant drain on CPU.
+
+supaschema knows every table, column, type, and enum without a database because it's built on PostgreSQL's own parser. The same system that would normally interpret your SQL inside a Docker container ships inside the package, embedded in your repo.
+
+Migrations diff without an ORM, without Docker, without a shadow database, and without introspection — reading your live catalog directly and read-only, or your schema files and git refs with no database at all. Zod-validated types generate with no database whatsoever. Nothing is applied to your local or remote database. All within milliseconds.
+
+Measured head-to-head against the Supabase CLI's diff engines on identical fixtures ([benchmarks](#benchmarks)):
+
+|  | supaschema | Supabase CLI engines (all five) |
+| --- | --- | --- |
+| Diff latency, 1 → 2,500 tables (~17,500 objects) | 0.2s → 3.2s | 3.6–4.6s → ~3.5 minutes |
+| Generated SQL survives a second apply | every fixture | fails on column/index changes |
+| Diff content vs intended change (F1) | 1.000 on every scored fixture | 0.982–0.999 (every engine missed the same policy change) |
+| Infrastructure per diff | none — pure TypeScript + WASM | Docker shadow database |
+| Ambiguous change (rename, drop, type change) | blocked until explicitly hinted | inferred or dropped silently |
+
+## Install
+
+```bash
+npm install --save-dev supaschema
+```
+
+Requires Node 22+ and PostgreSQL 15+. Run `npx supaschema init` to scaffold `supaschema.config.json`. In a Supabase project the database URL is discovered from `supabase/config.toml` automatically; anywhere else, set `SUPASCHEMA_DATABASE_URL` or define named `environments` in the config. If setup misbehaves, `npx supaschema doctor` prints a one-page diagnosis.
+
+## Quick Start
+
+Edit your schema files (`supabase/schemas/` by default), then generate the migration:
+
+```bash
+npx supaschema diff
+```
+
+supaschema compares the schema you declared with the schema your database has, and writes the difference to `supabase/migrations/<timestamp>_<name>.sql`:
+
+```sql
+-- Generated by supaschema 0.1.0.
+-- Operations: 1 create constraint, 1 create table, 1 drop function, ...
+-- supaschema: lineage from=a145201bcaa397f6... to=4db806bc9b786ea2...
+SET lock_timeout = '5s';
+
+DROP FUNCTION IF EXISTS "app"."legacy_ping"();
+
+CREATE TABLE IF NOT EXISTS app.audit_events (
+  id bigint GENERATED BY DEFAULT AS IDENTITY NOT NULL,
+  account_id bigint NOT NULL
+);
+
+DO $supaschema$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_catalog.pg_constraint c ...) THEN
+    ALTER TABLE app.audit_events ADD CONSTRAINT audit_events_pkey PRIMARY KEY (id);
+  END IF;
+END
+$supaschema$;
+```
+
+Prove the migration, then apply it with your normal runner:
+
+```bash
+npx supaschema check    # static replay-safety and lock-hazard gate
+npx supaschema verify   # applies it twice in throwaway databases, compares catalogs
+supabase db push        # your runner applies it — supaschema never touches your real databases
+```
+
+Types come from the same tree, in the same step. Run `npx supaschema types` once to create `database.types.ts` and `database.zod.ts` (runtime Zod validators); from then on every `diff` refreshes them with the migration. You never wait for a deploy to get correct types.
+
+No flags are needed day to day: sources, output paths, and names all have sensible defaults, every applied default is printed, and every flag overrides ([commands](#commands)).
+
+## Features
+
+- **Replay-safe by construction.** Every statement is guarded (`IF NOT EXISTS`, `DROP ... IF EXISTS`, catalog-checked `DO` blocks). A crashed deploy can simply run the file again.
+- **Fails closed on ambiguity.** Drops, renames, and type changes stay blocked until you approve the exact object in `hints`. Nothing is inferred from name similarity.
+- **Normalized output.** Migrations are written in one canonical SQL style, so formatting never shows up as a change. An object the deparser can't faithfully reproduce keeps your original spelling and says so with a warning.
+- **Types and validators without a database.** `supaschema types` writes Supabase-compatible TypeScript types plus runtime Zod validators straight from your schema files, and `diff` refreshes both automatically with every migration. No introspection, no running database, no applying migrations first — the parser already knows your schema, so you never stop mid-workflow to deploy before types can regenerate.
+- **No git ceremony.** Schema files are diffed straight from disk — no staging or committing before you can generate.
+- **Everything stays in sync.** Your editor validates the config via JSON Schema and `--watch` re-diffs on save; named `environments` point commands at local, staging, or production; `migrations` reconciles files against each database's applied history; `--fail-on-diff` gates drift in CI.
+- **Accuracy is measured, not assumed.** Diff output is scored against ground-truth change manifests ([benchmarks](#accuracy)).
+- **AI agents are governed.** A bundled Claude Code + Codex rule, skill, and hook set blocks hand-edits to generated migrations ([AI agents](#ai-agents)).
+- **Usable as a library.** Every CLI capability is an exported, typed function ([library](#library)).
+
+## Benchmarks
+
+All numbers are reproducible from this repo (`npm run benchmark`; harness in [benchmarks/README.md](benchmarks/README.md)) and verified, not just timed: every generated migration is applied in one transaction, applied a second time, and the resulting catalog is compared against the target. Reference run 2026-06-12: Apple Silicon, Node 24, PostgreSQL 17.6, Supabase CLI 2.106.0.
+
+### Speed
+
+**The diff alone** (charted at the top): supaschema's cost is parsing and planning, so it stays in seconds at every scale — **0.2s** at one table, **1.4s** at 1,000 tables, **3.2s** at 2,500 tables (~17,500 objects). Every shadow-database engine pays for a full schema replay into a fresh Docker database on every diff: **~4 seconds at a single table**, **~39 seconds** at 1,000 tables, and **~3.5 minutes** at 2,500 — a gap that widens from ~20x to ~70x as your schema grows.
+
+**The full real-world step — migration plus regenerated types:**
+
+![Full workflow: migration + regenerated types](docs/benchmarks/workflow-latency.svg)
+
+In the real workflow you don't stop at the diff: you need the migration _and_ your regenerated types. For supaschema that's still one command — `diff` writes the migration and refreshes `database.types.ts` and `database.zod.ts` in the same invocation — so the full step costs **0.23s** at one table and **5.2s** at 2,500. The engines can't regenerate types from unapplied SQL, so their full step is `db diff`, then apply the migration, then `supabase gen types`: **~6 seconds** at a single table, **~45 seconds** at 1,000 tables, **~3.7 minutes** at 2,500 — and what comes back is TypeScript only, with no runtime validators.
+
+| Median, full workflow | 1 table | 50 tables | 1,000 tables | 2,500 tables |
+| --- | --- | --- | --- | --- |
+| supaschema (migration + TS types + Zod) | 0.24s | 0.26s | 2.25s | 5.22s |
+| supabase engines (diff + apply + gen types) | 5.7–8.1s | 6.4–7.6s | 44.8–50.4s | 212.6–229.7s |
+
+![Realistic fixture latency](docs/benchmarks/realistic-latency.svg)
+
+| Median diff time     | 1 table | 50 tables | 1,000 tables | 2,500 tables |
+| -------------------- | ------- | --------- | ------------ | ------------ |
+| supaschema (files)   | 0.19s   | 0.19s     | 1.38s        | 3.23s        |
+| supaschema (live db) | 0.21s   | 0.23s     | 1.25s        | 2.78s        |
+| supabase default     | 3.86s   | 4.11s     | 39.12s       | 208.48s      |
+| supabase migra       | 3.81s   | 4.43s     | 38.74s       | 204.54s      |
+| supabase pg-delta    | 3.58s   | 4.15s     | 38.52s       | 207.47s      |
+| supabase pg-schema   | 4.61s   | 3.98s     | 38.57s       | 205.59s      |
+| supabase pgadmin     | 3.73s   | 4.01s     | 38.74s       | 209.98s      |
+
+Per-fixture latency charts: [additive](docs/benchmarks/additive-latency.svg) · [functions-policies](docs/benchmarks/functions-policies-latency.svg) · [xl](docs/benchmarks/xl-latency.svg) · [xxl](docs/benchmarks/xxl-latency.svg).
+
+### Accuracy
+
+Two independent measures back every run. **F1** scores the emitted statements against a ground-truth change manifest by object identity — recall is "did you touch every object that changed", precision penalizes operations beyond the intent and destructive drop+create of data-bearing objects. The **catalog fingerprint** is the objective oracle that needs no manifest: the generated migration is applied to a throwaway database and the resulting catalog is compared to the target. F1 says you named the right objects; the fingerprint says the SQL is actually correct.
+
+Every fixture is scored — the generated `realistic`/`xl`/`xxl` set and the hand-authored `additive`/`functions-policies` fixtures all carry manifests. supaschema scores **F1 1.000** on each, in both file and live-database modes. Every Supabase engine scores **0.982–0.999, and the gap is always the same miss: each silently dropped an RLS policy change** — and on that fixture each engine's migration also fails the fingerprint check, so the miss is confirmed objectively, not just by the rubric.
+
+That miss matters more than speed. A slow diff costs seconds and an unreplayable diff costs a deploy, but a silently dropped policy change ships a tenant-isolation hole that review, CI, and the migration runner all wave through. The same comparison run against a real ~8,300-object production Supabase tree is written up in the [anilize case study](docs/case-study-anilize.md).
+
+### Replay safety
+
+![XL fixture correctness](docs/benchmarks/xl-correctness.svg)
+
+Every engine's migration applies once and reaches the target catalog. Only supaschema's also applies **twice**: the others emit unguarded `ADD COLUMN` and `CREATE INDEX`, which fail on re-run for every fixture containing column or index changes. Per-fixture charts: [additive](docs/benchmarks/additive-correctness.svg) · [functions-policies](docs/benchmarks/functions-policies-correctness.svg) · [realistic](docs/benchmarks/realistic-correctness.svg) · [xxl](docs/benchmarks/xxl-correctness.svg).
+
+## How It Works
+
+supaschema reads SQL with PostgreSQL's own parser, shipped inside the package. The part of Postgres that understands SQL runs in the library itself — that's why no Docker and no shadow database are needed, and why the engine never touches SQL with regex.
+
+1. **Parse** — every statement, from your files or a live database, becomes a parse tree.
+2. **Compare** — two definitions are equal when their parse trees are equal. Formatting, keyword case, and type spellings can never show up as fake changes.
+3. **Plan** — changes are ordered by dependency. Anything destructive waits for your explicit approval in `hints`.
+4. **Render** — the migration is written as guarded SQL that is safe to run twice, stamped with a lineage marker that chains it to the next one.
+5. **Gate** — existing migrations are never overwritten, and a migration that doesn't continue the chain is refused.
+6. **Verify** — the migration runs twice in throwaway databases, applied exactly the way `supabase db push` applies it, and the result must match your schema files.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `diff` | Generate the migration (`--fail-on-diff` CI drift gate, `--watch` editor loop, `--out stdout`, `--write-hints`) |
+| `check` | Static replay-safety gate for the migrations directory or named files — including other tools' migrations (`--reporter github\|sarif\|json`) |
+| `verify` | Apply-twice proof for the newest pending migration in disposable databases |
+| `types` | Generate Supabase-compatible TypeScript types and Zod validators from the schema tree — no database needed (`--out stdout` to print) |
+| `plan` / `inspect` / `fingerprint` | JSON diff plan · extracted schema model · one-line schema-equality hash |
+| `migrations` | Files on disk vs a database's applied history: applied, pending, ghosts, out-of-order |
+| `sync` | Gate pending migrations, then optionally drive the Supabase CLI (`--local` / `--remote`) |
+| `audit` | Coverage report for adopting an existing schema |
+| `corpus` / `selfcheck` | The engine's own correctness oracles ([docs/corpus.md](docs/corpus.md)) |
+| `doctor` / `init` / `completion` / `explain` | Setup diagnosis · config scaffold · shell completions · offline diagnostic decoder |
+
+Defaults: `--from` is the database (falling back to `git:HEAD`), `--to` is the schema tree, and output lands in the migrations directory — paths set by `schemaPaths` and `migrationsDir` in the config. Full flags: [docs/commands.md](docs/commands.md). Exit codes: `0` ok · `1` runtime error · `2` diagnostic errors · `3` drift found.
+
+## Sources
+
+Either side of a diff can be any of these — generating a diff never creates a database or runs Docker:
+
+| Source | Reads |
+| --- | --- |
+| `dir:supabase/schemas` | SQL files exactly as they sit on disk |
+| `git:HEAD` (any ref) | the schema tree at a committed ref |
+| `database:$DATABASE_URL` | a live catalog, read-only |
+| `dump:path.sql` / `dump:-` | one SQL file, or stdin |
+| `catalog:path.json` | a saved `inspect` snapshot, for air-gapped or point-in-time comparison |
+
+## Safety
+
+- Destructive changes require the exact object key in `hints.destructive`; column changes then render as per-column `ALTER`s instead of dropping and recreating the table, and type changes that would rewrite the whole table are flagged (`SUPA_CHECK_ALTER_COLUMN_TYPE_REWRITE`).
+- Renames come only from `hints.renames`. `CASCADE` is never emitted. Idempotency is required, not optional.
+- Data statements (`INSERT`/`UPDATE`/`DELETE`/`DO`) are never treated as schema changes, and unsupported DDL produces a blocking diagnostic instead of passing through.
+- Diagnostics redact credentials (URL passwords, JWTs, secrets).
+- Recovery steps for blocked plans: [docs/hints.md](docs/hints.md) · config reference: [docs/config.md](docs/config.md).
+
+## AI Agents
+
+The package ships a governance bundle so coding agents generate migrations through the diff instead of hand-writing SQL:
+
+- `AGENTS.md` — operator brief: invariants, commands, recovery codes.
+- `.claude/rules/` and `.codex/rules/` — the migration policy for Claude Code and Codex.
+- `.claude/skills/supaschema/` — the step-by-step workflow skill, with recovery steps for every blocking `SUPA_*` code.
+- `.claude/hooks/` and `.codex/hooks/` — wired PreToolUse hooks that **block any edit to a generated migration** (identified by its lineage marker) in both runtimes.
+
+Copy the surfaces into your repo root to get the write-time enforcement — the hooks only run where `.claude/settings.json` and `.codex/hooks.json` are wired. Pointing agents at `node_modules/supaschema/` gives them the guidance without the hooks. `supaschema explain <SUPA_CODE>` decodes every diagnostic offline.
+
+## Library
+
+Every CLI capability is an exported, typed function:
+
+```ts
+import {
+  extractSourceModel, // any source prefix -> SchemaModel
+  extractCatalogModel, // live pg_catalog -> SchemaModel
+  planSchemaDiff, // two models -> MigrationPlan
+  renderMigrationSplit, // plan -> { sql, concurrentSql? }
+  checkMigrationSql, // SQL -> replay-safety diagnostics
+  verifyMigration, // apply-twice + reconvergence proof
+  migrationsStatus, // disk files vs applied history
+  syncMigrations, // gate + orchestrate the migration runner
+  runCorpus, // the corpus oracle
+  resolveDatabaseUrl,
+  parseLineage,
+  loadConfig,
+} from "supaschema";
+```
+
+## Scope and Stability
+
+Modeled: schemas, extensions, types/enums/domains, tables, constraints, indexes, sequences, functions/procedures, views/materialized views, triggers, RLS, policies, grants/default privileges, foreign data wrappers, comments. Deliberate non-goals (partitioning, publications, event triggers, collations) fail closed with diagnostics ([support matrix](docs/support-matrix.md)). Pre-1.0: pin an exact version in CI. Worked Supabase and plain-PostgreSQL setups live in `examples/`.
+
+## Documentation
+
+[commands](docs/commands.md) · [config](docs/config.md) · [hints & recovery](docs/hints.md) · [CI recipes](docs/ci.md) · [CI gate & paid tier](docs/ci-gate.md) · [diagnostics](docs/diagnostics.md) · [support matrix](docs/support-matrix.md) · [corpus oracle](docs/corpus.md) · [case study](docs/case-study-anilize.md) · [benchmark harness](benchmarks/README.md)
+
+## Development
+
+```bash
+npm run check           # lint + typecheck + tests + build
+npm run fixture:verify  # render a fixture migration, apply twice, compare catalogs
+npm run corpus:check    # replay a dirty-real corpus and require reconvergence to zero
+npm run benchmark       # threshold-enforced benchmarks
+```
+
+## Contributing and License
+
+Bug reports and feature requests: [GitHub issues](https://github.com/jmclaughlin724/supaschema/issues). Run `npm run check` before opening a pull request.
+
+supaschema is an independent open-source project and is not affiliated with or endorsed by Supabase.
+
+Dual-licensed: **AGPL-3.0-only** ([LICENSE](LICENSE)) for open-source use, **commercial** ([LICENSE-COMMERCIAL.md](LICENSE-COMMERCIAL.md)) for embedding in proprietary products or hosted services.

package/benchmarks/README.md

@@ -0,0 +1,104 @@
+# Comparison Benchmarks
+
+This harness compares `supaschema` against Supabase CLI schema diff engines. It writes machine-readable JSON and SVG charts.
+
+## Run
+
+```bash
+SUPASCHEMA_COMPARE_DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres \
+  npm run bench:compare
+
+npm run bench:plot
+```
+
+`bench:plot` accepts any number of result JSON files plus an optional output directory and emits one artifact set per fixture (sample size), so each scale is saved and read separately:
+
+```bash
+node benchmarks/plot.js benchmarks/results/comparison.json benchmarks/results/comparison-xl.json
+```
+
+Outputs:
+
+- `benchmarks/results/comparison.json` — raw rows from `bench:compare` (use `SUPASCHEMA_COMPARE_OUT` to direct separate runs to separate files, e.g. `comparison-xl.json`)
+- per fixture: `<fixture>-latency.svg`, `<fixture>-correctness.svg`, and `<fixture>-results.json` (that fixture's rows plus source-run metadata)
+- `summary.md` — per-fixture result tables plus a cross-fixture scaling table (each tool's median and its ratio vs its own smallest fixture)
+
+## Tool Selection
+
+By default the harness attempts `supaschema` plus every Supabase `db diff` engine available in the installed CLI. Limit the run with comma-separated filters:
+
+```bash
+SUPASCHEMA_COMPARE_TOOLS=supaschema-file,supaschema-db,supabase-pg-delta \
+SUPASCHEMA_COMPARE_FIXTURES=additive \
+SUPASCHEMA_COMPARE_ITERATIONS=10 \
+SUPASCHEMA_COMPARE_TIMEOUT_MS=30000 \
+SUPASCHEMA_COMPARE_DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres \
+  npm run bench:compare
+```
+
+The harness refuses non-local database hosts by default because it creates and drops temporary databases. Set `SUPASCHEMA_COMPARE_ALLOW_REMOTE=1` only for disposable remote benchmark clusters. Use `SUPASCHEMA_COMPARE_PORT_BASE` to move the per-run Supabase temp project ports away from local conflicts.
+
+Real-project fixtures: `node benchmarks/tools/build-project-fixture.mjs --tree <schemas dir> --out <fixture dir>` turns an actual declarative tree into a fixture (fixpoint statement ordering, Supabase auth stubs, support-surface filtering with a `dropped.log`, and a `fixture.json` carrying the schema list + supaschema adapter). Point the harness at it with `SUPASCHEMA_COMPARE_FIXTURE_DIRS=<fixture dir>` so private schemas never enter the package tree.
+
+When the compare admin URL is `supabase_admin` (required to install most extensions on a local Supabase stack), also set `SUPASCHEMA_COMPARE_SEED_ROLE=postgres`: after seeding, the harness transfers ownership of every user-schema object to that role. This works around two Supabase CLI behaviors found while benchmarking real schemas (CLI 2.105, verified by direct bisection 2026-06-11):
+
+1. **Silent empty diffs for supabase_admin-owned objects.** `supabase db diff --from <db1> --to <db2>` returns an empty diff with exit 0 — no warning — when the differing objects are owned by `supabase_admin`, regardless of the connecting user. The same databases diff correctly after `ALTER ... OWNER TO postgres`. A diff tool reporting "no changes" against databases that differ by a whole table is the failure mode supaschema's `SUPA_PLAN_EMPTY_WITH_DRIFT` invariant exists to make impossible.
+2. **`&sslmode=` URL corruption.** The CLI appends `&sslmode=...` to a bare `--to` URL with no query string, corrupting the database name (`FATAL: database "...&sslmode=" does not exist`) — visible only under `--debug`. Work around it by always passing URLs with an existing query string (e.g. `?sslmode=disable`).
+
+The default is 10 measured iterations plus 1 warmup per adapter/fixture pair. A full default run across all adapters and fixtures takes tens of minutes because Supabase engines and realistic-fixture seeding dominate; use the filters above for quick local passes.
+
+Fixtures: the on-disk pairs under `benchmarks/fixtures/` (`additive`, `functions-policies`) plus a generated `realistic` fixture — a deterministic 50-table Supabase-shaped schema (FKs, RLS policies, triggers, views, materialized views, functions, grants, comments) with a mixed change set, materialized at run time from the shared `dist/benchmark-fixtures.js` generator. Set `SUPASCHEMA_COMPARE_XL_TABLES` (for example `1000` for ~7000 objects) to add an `xl` fixture at that table count; it is opt-in because shadow-database engines take minutes per run at that scale — raise `SUPASCHEMA_COMPARE_TIMEOUT_MS` accordingly.
+
+Adapters:
+
+- `supaschema-file` — `diff` between two SQL dumps (diff only)
+- `supaschema-db` — `diff` between two live catalogs (diff only)
+- `supabase-default` / `supabase-migra` / `supabase-pg-delta` / `supabase-pg-schema` / `supabase-pgadmin` — `supabase db diff` per engine (diff only)
+- `supaschema-workflow` — the full real-world step measured as one command: `diff` writes the migration and refreshes seeded `database.types.ts` + `database.zod.ts` (TypeScript types **and** runtime Zod validators) in the same invocation
+- `supabase-*-workflow` — the same real-world step for each Supabase engine: `db diff`, apply the generated migration to the database (types cannot regenerate from unapplied SQL), then `supabase gen types --lang=typescript --db-url` (TypeScript only; no validators)
+
+Both workflow lanes are spawned through the same `tools/run-workflow.mjs` wrapper, so per-process overhead is identical on both sides. Workflow rows are charted separately (`workflow-latency.svg`) and excluded from the diff-only charts; never average the two lanes together. The captured output of a workflow run is still the generated migration, so verification and accuracy scoring apply to workflow rows unchanged.
+
+## Reading Results
+
+Use latency charts for speed and correctness charts for whether generated output:
+
+- applied once,
+- applied twice,
+- matched the target catalog fingerprint after the first and second apply.
+
+`matchesTargetAfterFirstApply` and `matchesTargetAfterSecondApply` are recorded separately in the JSON. `matchesTargetFingerprint` is true only when first apply matches, second apply succeeds, and second apply still matches. Command failures, skips, and unsupported adapters remain visible in the correctness chart.
+
+Timing fields: `elapsedMs` is the final command attempt only and is what the latency chart plots; `totalElapsedMs` additionally includes retry sleeps and failed environmental attempts (for example Supabase shadow-port conflicts), with `attempts` recording how many runs happened.
+
+Accuracy fields (generated fixtures only, which carry a ground-truth change manifest): `outputRecall`, `outputPrecision`, and `outputF1` score the generated SQL's content against the manifest, with `outputMissedSample`/`outputExcessSample` naming up to 8 missed or spurious object keys. Every emitted statement is classified through the PostgreSQL parser (supaschema guard `DO` blocks are unwrapped and classified too). Precision penalizes operations beyond the manifest and destructive drop+create of data-bearing objects (tables, materialized views, sequences, schemas, types/domains); drop+create of recreateable metadata (policies, triggers, views, indexes, functions) is the standard PostgreSQL change lane and is not penalized. `summary.md` reports the per-tool mean as the Output F1 column.
+
+Verification applies the fixture `from` state per statement, then applies the generated migration in one transaction per apply — mirroring runners like `supabase db push` — so transactional failures are not masked by autocommit.
+
+Do not average all modes together. Source-file diff, live-catalog diff, and replay verification measure different work.
+
+## Measured Results (as of 2026-06-12)
+
+Single sequential reference run, 2026-06-12 (`BENCH_ALL_SEQUENTIAL=1 bash benchmarks/tools/bench-all.sh`), with diff-output accuracy scoring active: Apple Silicon (darwin arm64), Node 24, PostgreSQL 17.6 (Supabase local), Supabase CLI 2.106.0, supaschema 0.1.0 with deparse normalization and type generation in the default diff path. Fixture scale: `additive`/`functions-policies` ≈ 1 table; `realistic` = 50 tables (~350 objects); `xl` = 1,000 tables (~7,000 objects); `xxl` = 2,500 tables (~17,500 objects). 3 iterations per cell, single-iteration at `xxl`. Regenerate with `benchmarks/tools/bench-all.sh` (parallel by default; `BENCH_ALL_SEQUENTIAL=1` for publication-grade latency medians free of cross-fixture CPU contention); per-fixture rows live in `<fixture>-results.json` and the generated `summary.md`. All durations are seconds.
+
+| Fixture | supaschema (file / live-db) | Supabase engines | Replay-safe (applies twice) | Output F1 (supaschema / engines) |
+| --- | --- | --- | --- | --- |
+| `additive` | 0.19s / 0.21s | 3.6–4.6s | supaschema only | — (no manifest) |
+| `functions-policies` | 0.18s / 0.21s | 3.3–3.7s | all tools | — (no manifest) |
+| `realistic` | 0.19s / 0.23s | 4.0–4.4s | supaschema only | 1.000 / 0.982 |
+| `xl` | 1.38s / 1.25s | 38.5–39.1s | supaschema only | 1.000 / 0.999 |
+| `xxl` | 3.2s / 2.8s | 204.5–210.0s | supaschema only | 1.000 / 0.999 |
+
+The full-workflow lanes (same run) measure the real-world step of producing the migration **and** regenerated types:
+
+| Fixture | `supaschema-workflow` (migration + TS types + Zod) | `supabase-*-workflow` (db diff + apply + gen types) |
+| --- | --- | --- |
+| `additive` | 0.24s | 5.8–8.1s |
+| `functions-policies` | 0.23s | 5.7–6.2s |
+| `realistic` | 0.26s | 6.4–7.6s |
+| `xl` | 2.25s | 44.8–50.4s |
+| `xxl` | 5.22s | 212.6–229.7s |
+
+Regression with schema size: supaschema stays near three seconds through 2,500 tables because its cost is parse/plan/catalog-read bound. All five Supabase shadow-database engines cluster near ~3.5–4.5s even at one table and grow with schema replay cost to ~39s at 1,000 tables and ~3.4–3.5 minutes at 2,500 — the gap grows from ~20× to ~70×. Verification outcomes are scale-independent: Supabase engines emit unguarded DDL, so apply-twice fails on every fixture whose diff contains `ADD COLUMN`/`CREATE INDEX` statements (`additive`, `realistic`, `xl`, `xxl`); `functions-policies` passes everywhere because its diff is entirely `CREATE OR REPLACE`. Accuracy outcomes: supaschema scores F1 1.000 in both modes on every manifest-scored fixture; every Supabase engine misses the policy-predicate change (recall loss → 0.982 at 50 tables, 0.999 at 1,000/2,500 where the larger manifest dilutes the same miss).
+
+The internal threshold suite (`npm run benchmark`) enforces these as regression gates in CI on PostgreSQL 15/16/17 — every lane fails the build past its `SUPASCHEMA_*_MS` threshold. Reference warm-max values from the same machine: `realisticTreeDiff` 15ms, `noDriftDiff` 15ms, `largeInMemoryDiff` 74ms (250 tables), `liveCatalogDiff` 39ms, `liveCatalogDiffXl` 426ms, `endToEndMigration` 11ms, `endToEndMigrationLarge` 185ms, `endToEndMigrationXl` 692ms, `shadowRoundTripDiff` 1019ms, `replayVerification` 132ms.