How does Zanith prove correctness, not just speed?

A 53/53 production proof suite across 7 files under test/proof/ runs against dedicated PostgreSQL 17.8 databases. It stress-tests a 1,000-model schema with 3,967 directed relation edges, asserts relation correctness against real returned rows, verifies type inference under tsc with positive expectTypeOf and negative @ts-expect-error cases, exercises preflight + shadow verification + batched-backfill crash-resume + recovery checksum integrity, and adversarially proves flagship migrate claims in 06-flagship-claims.test.ts.

What benchmarks does Zanith publish?

1,000-model schema compile in 22.9ms (engine bench) / 4.56ms mean on the proof bench (M4 Pro), 1,000 model lookups in 0.73ms, 3.4MB graph memory at 1k models, 2.4µs SELECT compile overhead, 17.2µs JOIN compile, 88.97KB ESM bundle, 765/765 unit tests, 53/53 proof suite tests.

Are the benchmark numbers reproducible?

Yes. Three commands re-run the proof suite end-to-end: create the dedicated test database (one psql command), `npx vitest run test/proof/`, then `npx tsc --noEmit` to confirm type assertions hold. Machine specs, Node version, Postgres version, and the deterministic schema generator are all published on this page.

Does Zanith catch real schema-migration bugs before they hit production?

Yes. Preflight blocks addUnique when duplicates exist, addForeignKey when orphan rows exist, and SET NOT NULL when NULLs exist — with sample offending rows in the finding. Shadow-DB verification applies the plan to a parallel database, introspects the result, and diffs against the declared schema. The proof suite demonstrates each case against live data.

Can a Zanith backfill resume after a crash?

Yes. The proof suite simulates a crash after 4 of 20 batches (2,000 of 10,000 rows committed) and shows the runner reads _zanith_migration_checkpoints, resumes from the last cursor, and completes the remaining 8,000 rows with no duplicates. Final state: every row updated, checkpoint marked done.

What happens if a recovery archive is tampered with?

The restore refuses with an explicit error: `Refusing to restore: archive checksum changed since archive time`. archiveColumn records an MD5 checksum at archive time; restoreArchiveColumn re-computes it against the archive table and rejects mismatches by default.

Proof · 01 — The receipts

Real numbers. Sourced. Re-run on every commit.

Every figure on this page comes from a benchmark or proof file in the engine repo, with the source named below it. The disclosures at the bottom are part of the page, not buried.

765/765: unit tests passing
53/53: proof suite · real Postgres
22.9ms: schema compile · 1k models
88.97KB: ESM bundle

v0.2 · earlynumbers reflect engine compilation overhead — not end-to-end query timelast run · CI · main

proof suite · last run

$ npx vitest run test/proof/
 
 Test Files  7 passed (7)
      Tests  53 passed (53)
   Duration  8.54s

02 — Schema-scale benchmarks

Compile cost scales sub-linearly at 1,000 models.

Three measurements from the engine bench — compile time, lookup latency, and graph memory at 1k models.

22.9ms

schema compile · 1000 models

Lex + parse + validate the .zanith source into a runtime graph. Sub-linear at scale because validation reuses tokenization state.

engine/test/benchmark/scale.test.ts

0.73ms

1000 model lookups

Indexed lookup against the in-memory model registry. Sub-microsecond per call — well below any human-perceptible threshold.

engine/test/benchmark/scale.test.ts

3.4MB

graph memory · 1000 models

Total memory footprint of the runtime graph at 1k models. Order of magnitude smaller than a comparably-sized generated client on disk.

engine/test/benchmark/scale.test.ts

03 — Per-operation cost

Microseconds on the engine. Not milliseconds on the wire.

Compile overhead per operation — sourced from engine/test/benchmark/execution.test.ts.

operation	shape	cost	group
Expression · simple eq	{ field: value }	1.2µs	expression
Expression · AND/OR	{ AND: [a, b], OR: [c, d] }	2.4µs	expression
SELECT · with WHERE	where + projection	2.4µs	compile
findMany · build + compile	args validate + AST + emit	2.1µs	compile
JOIN · projection · WHERE	1 included relation	17.2µs	compile
GROUP BY + COUNT + SUM	aggregate compile	5.5µs	compile
INSERT · single row	RETURNING *	2.8µs	write
UPSERT · ON CONFLICT DO UPDATE	deduped by unique field	2.7µs	write
Bulk INSERT · 10 rows	values list	7.6µs	write

compile cost distribution · µs

expressioncompilewriteread

engine/test/benchmark/execution.test.ts

04 — Unit test suite

765 of 765 passing. Fully green.

The full engine test battery — compiler, expression, integration, types, schema, benchmarks, and proof files.

765 / 765 · fully green

$ pnpm test
 
vitest run · zanith engine
 
✓ test/compiler/select.test.ts (8)
✓ test/compiler/insert.test.ts (5)
✓ test/benchmark/scale.test.ts (6) 427ms
✓ test/benchmark/execution.test.ts (1) 466ms
✓ test/proof/06-flagship-claims.test.ts (16)
 
  Test Files  74 passed (74)
       Tests  765 passed (765)
    Duration  2.14s

05 — Production-grade proof suite

Tests that prove correctness under ugly cases.

7 files · 53 / 53 passing · real Postgres (17.8). Type assertions verified under tsc --noEmit. Every claim below is backed by a test you can re-run.

53/53tests passing

7test files

8.5sfull suite

real Postgres · real rows

tests per file53 / 53 passing

environment

CPU: Apple M4 Pro
RAM: 48 GB
OS: Darwin arm64 (25.3.0)
Node: v20.20.0
Postgres: 17.8 (Homebrew)
Engine: v0.2
pg driver: 8.20.0
vitest: 0.34.6
Test database: zanith_proof_tests (separate, schema-owned)

per-suite resultstest/proof/

00System + repro report
postgres9/9
test/proof/00-system-report.test.ts
Machine metadata, cold/warm compile distribution, SQL snapshots for relation-heavy queries.
01Large-schema stress
5/5
test/proof/01-large-schema.test.ts
1,000 models · 3,967 directed relation edges · self-relations · m2m · 5-hop chain · duplicate FKs.
02Relation correctness
postgres7/7
test/proof/02-relation-correctness.test.ts
Compile → execute → assert rows. One-hop, multi-hop, self-relation, duplicate joins, m2m, LEFT/INNER.
03Type-inference proof
8/8
test/proof/03-type-inference.test.ts
expectTypeOf positives + // @ts-expect-error negatives. Gate is tsc --noEmit, not vitest alone.
04Preflight + shadow verify
postgres6/6
test/proof/04-preflight-shadow.test.ts
addUnique / addForeignKey / NOT NULL blocks with sample rows. Shadow apply + drift detection.
05Backfill + recovery
postgres2/2
test/proof/05-backfill-recovery.test.ts
10k-row crash-resume from checkpoint. archiveColumn round-trip + checksum tamper rejection.
06Flagship claims
postgres16/16
test/proof/06-flagship-claims.test.ts
Destructive gate, soft-drop, archive round-trips, reseed — adversarial proofs of migrate safety claims.

compileSchema · warm ×201,000 models · 3,967 edges

mean: 4.56ms
p50: 4.57ms
p95: 5.6ms
p99: 5.78ms
max: 5.82ms

relation density · 1k models3,967 directed edges

3,967edges

Domain refA / refB / refC75%
3 belongsTo per Domain model (989 × 3)
Audit FKs → User25%
createdBy / updatedBy / approvedBy on every 3rd Domain
Chain · m2m · self · fixtures0%
5-hop Chain · PostTag · User.manager · Post.author · m2m

generated SQL snapshots · 00-system-report

Simple SELECT WHERE

SELECT "domain_0"."id", "domain_0"."slug"
FROM "domain_0" AS "domain_0"
WHERE "domain_0"."active" = TRUE
LIMIT $1
-- params: [10]

5-hop relation chain

SELECT "chain0"."id" AS "topId",
       "next_5"."label" AS "deepestLabel"
FROM "chain0" AS "chain0"
LEFT JOIN "chain1" AS "next"   ON "chain0"."next_id"  = "next"."id"
LEFT JOIN "chain2" AS "next_2" ON "next"."next_id"    = "next_2"."id"
LEFT JOIN "chain3" AS "next_3" ON "next_2"."next_id"  = "next_3"."id"
LEFT JOIN "chain4" AS "next_4" ON "next_3"."next_id"  = "next_4"."id"
LEFT JOIN "chain5" AS "next_5" ON "next_4"."next_id"  = "next_5"."id"

Triple-join · same target

SELECT "domain_0"."id",
       "createdBy"."email" AS "creator",
       "updatedBy"."email" AS "updater",
       "approvedBy"."email" AS "approver"
FROM "domain_0" AS "domain_0"
LEFT JOIN "users" AS "createdBy"  ON "domain_0"."created_by_id"  = "createdBy"."id"
LEFT JOIN "users" AS "updatedBy"  ON "domain_0"."updated_by_id"  = "updatedBy"."id"
LEFT JOIN "users" AS "approvedBy" ON "domain_0"."approved_by_id" = "approvedBy"."id"
LIMIT $1

backfill crash-resume · 10,000 rows · batch 500

Phase 1 commits 4 batches (2,000 rows) then throws. Phase 2 resumes from _zanith_migration_checkpoints — no duplicates.

findings the suite surfaced

m2m junction column-name bug

The m2m emit hard-codes junction.fromField / junction.toField as the literal column name in the join's ON clause — it does not route through the junction model's columnName mapping. Workaround documented in 02-relation-correctness.test.ts.

Shadow-verify representation gap

Even matching plans report residual createTable + dropTable drift. Real drift IS still caught — the rawSql case proves the gate works — but verifyOnShadowOrThrow is currently over-strict on matching plans.

06 — What this page doesn't measure

Honest disclosures. Part of the design.

Every benchmark page should say what it does not measure. These gaps are explicit — not buried in a footnote.

measurement boundarygreen = on this page · gray = explicit gap

compileSchema: 22.9ms; @ 1k models
per-op compile: 2.4µs; SELECT WHERE
graph footprint: 3.4MB; steady-state
proof suite: 53/53; real Postgres

4 explicit gaps · 2 tracked · 0 hidden

01scope · by design
End-to-end query time against a live database
Every µs on this page is engine overhead. Network latency, connection setup, and the database's actual execution time are excluded.
on this page · Per-op compile in µs — engine time only, not round-trip
02in progress
Comparable benchmarks against Prisma, Drizzle, TypeORM
We don't have sourced competitor figures yet. Specific µs comparisons will land when we can run a matched workload on each.
on this page · Our numbers are pinned from vitest — competitors need matched workloads first
03planned
Long-running memory churn
The 3.4MB figure is the steady-state graph footprint. We haven't yet measured memory under continuous schema reloads or sustained query throughput.
on this page · Single compile heap delta @ 1k models — not sustained churn
04downstream concern
Performance on hot-paths inside the DB
We measure what we emit, not how the planner reacts. The /examples page shows the SQL we generate; production tuning lives downstream.
on this page · Generated SQL specimens — planner behavior is yours to tune

Generated SQL and compile costs live on /examples. Competitor benches will ship when we can run matched workloads — tracked openly above.

07 — Reproduce

Three commands. Full receipts.

Run the proof suite end-to-end on your machine. Type assertions require a separate tsc pass — vitest strips types at runtime.

engine/ · reproduce

# 1. create the dedicated test database (idempotent)
$ psql -h localhost -d postgres \
$   -c "DROP DATABASE IF EXISTS zanith_proof_tests" \
$   -c "CREATE DATABASE zanith_proof_tests"

# 2. run all seven proof files
$ npx vitest run test/proof/

# 3. confirm type assertions under tsc — vitest strips types
$ npx tsc --noEmit

Override the connection string with ZANITH_PROOF_DB_URL if the default doesn't match your local Postgres.

Per-operation compile costs also live on /examples#compile-cost.

08 — Go deeper

elsewhere

Compile costs

per-operation µs figures from the same engine bench

Real numbers. Sourced. Re-run on every commit.

Compile cost scales sub-linearly at 1,000 models.

Microseconds on the engine. Not milliseconds on the wire.

765 of 765 passing. Fully green.

Tests that prove correctness under ugly cases.

Honest disclosures. Part of the design.

End-to-end query time against a live database

Comparable benchmarks against Prisma, Drizzle, TypeORM

Long-running memory churn

Performance on hot-paths inside the DB

Three commands. Full receipts.

The numbers are the start. Not the finish.

How it works

Examples

Roadmap

Docs

Compile costs