Testing & benchmarks
Test commands, SQL checks, browser coverage, and benchmark workloads.
One set of focused runners covers fast correctness checks, real-browser behavior, performance regressions, and the benchmark harness behind the live benchmarks page. This page is the source of truth for running and maintaining them.
Treat a failure as a defect to explain. Expected answers come from SQL semantics, independent engines, or an independently authored model; never record Minnow's failing output as its new expected answer. An oracle correction needs evidence from that independent contract. Preserve failing inputs and reduce them into regressions. Do not loosen assertions, deadlines, coverage floors, or resource budgets to hide a failure, and do not treat a successful retry as a clean run. Storage and browser-runtime regressions must run against real browser APIs and durable stores; Node models and injected faults are useful additional checks, not substitutes for that gate.
The typecheck, build, and browser prerequisites force a fresh TypeScript project-reference build.
They do not trust an existing .tsbuildinfo, so a release gate proves the current sources even
after generated declarations or asynchronous signatures change.
Choose the smallest runner that proves the change
| Command | What it runs | Use it for |
|---|---|---|
npm test | Vitest plus the committed fast SQLLogicTest profile | Normal implementation work |
npm run test:unit | Vitest unit, generated, simulator, comparison, and harness tests | A focused inner loop |
npm run test:sql:standard | 6,345 result-checked upstream queries; committed, offline, about fifteen seconds | Every SQL or optimizer change |
npm run test:sql:full | The full supported profile, including exhaustive multi-way join permutations | Before a release |
npm run test:coverage | Vitest with the coverage floors enforced | Before pushing |
npm run soak | The generative suites on fresh random seeds, to find new failures | Hunting bugs rather than pinning |
npm run simulate | One replayable deterministic concurrency, fault, and storage simulation | Storage and transaction changes |
npm run test:simulator:full | 4,000 concurrent mutations plus deterministic fault and maintenance checkpoints, then three long interaction plans over the memory, IndexedDB, and OPFS stores | Before a release |
npm run simulate:interactions | One replayable interaction plan: DDL, DML, transactions, concurrent rounds, faults, reopens, and maintenance against a shadow model | Engine, index, and transaction changes |
npm run test:packed | Differential, conformance, and SQLLogicTest suites with every segment packed that can be; :full adds the simulators | Packed-segment and block-read changes |
npm run fixture:format | Freezes a database this build wrote, as a compatibility fixture | Before changing a format version |
npm run test:browser:library | Core IndexedDB, OPFS, transaction, SQLLogicTest, and multi-tab interaction-plan tests in Chromium, Firefox, and WebKit | Storage, engine, or browser-runtime changes |
npm run test:browser:conformance | Full core browser suite, full SQLLogicTest, and 800-step interactions over native IndexedDB and OPFS in all three browsers | Release and nightly storage correctness |
npm run test:browser:site | Public-site examples in Chromium, Firefox, and WebKit | Docs, examples, and site changes |
npm run test:browser | Both browser runners, in sequence | Cross-browser regression checks |
npm run test:consumer | Packed libraries installed, typed, bundled, and run outside the workspace | Package and public-entry changes |
npm run benchmark:gate | Seeded Node performance ratios against the checked-in baseline | Query-executor and write-path changes |
npm run benchmark:browser | Minnow against SQLite-Wasm and DuckDB-Wasm in real Chromium on a real disk, judged against the checked-in browser baseline | Storage, executor, and worker changes |
npm run benchmark:storage | The rebuild core's storage in real Chromium on a real disk, OPFS and IndexedDB: cache hits, a cold slab read, publish and commit latency (recorded, not judged) | Storage changes in packages/core/src/next |
npm run benchmark:sizes | Download size of Minnow, SQLite Wasm, and PGlite, from the installed packages | Dependency or public-entry changes |
npm run benchmark:live-wide | Allocation per thread, deliveries, and time to rows for one wide live query from subscribe and from a Suspense load | Live-query, projection, and result-wire changes |
npm run api:check | The public API surface against the committed contract snapshot | Public-entry or declaration changes |
npm run check | Format, types, lint, build, API contract, coverage, fast SQLLogicTest, and test:packed | The local merge gate |
npm run check:release | The local gate, full SQL/simulator (also forced-packed), performance, and browser runners | Release candidates |
Install the browser binaries once before using a browser runner:
npx playwright install chromium firefox webkitWebKit on a Linux host Playwright does not support
Playwright's Linux WebKit build is made for Ubuntu 24.04. On a distribution with newer system
libraries (an Arch-based host with ICU 78, for one), every WebKit case fails before it runs:
Host system is missing dependencies to run browsers, then
libicudata.so.74: cannot open shared object file. npx playwright install-deps needs apt and
root, and you do not need either. WebKit needs three libraries that are older than the system's:
ICU 74, libxml2 2.9 (libxml2.so.2) and flite 2.2. Take them from Ubuntu 24.04's packages, keep
them out of the system's library folders, and give Playwright a private browsers folder whose
MiniBrowser wrapper puts them on the library path:
WK="${WK:-$HOME/.cache/minnow-webkit}" # scratch for the libraries and the browser mirror
BUILD=webkit-2336 # the build the repo's Playwright looks for (ls ~/.cache/ms-playwright)
SOURCE="${SOURCE:-$BUILD}" # the build to run under that name (webkit-2359 for OPFS, below)
mkdir -p "$WK/debs" "$WK/x" "$WK/lib"
cd "$WK/debs"
for deb in main/i/icu/libicu74_74.2-1ubuntu3_amd64.deb \
main/libx/libxml2/libxml2_2.9.14+dfsg-1.3ubuntu3_amd64.deb \
universe/f/flite/libflite1_2.2-6build3_amd64.deb; do
curl -fsSLO "http://archive.ubuntu.com/ubuntu/pool/$deb"
done
for deb in *.deb; do bsdtar -xOf "$deb" 'data.tar*' | bsdtar -xf - -C "$WK/x"; done
cp -a "$WK"/x/usr/lib/x86_64-linux-gnu/*.so.* "$WK/lib/"
# A private browsers folder: links to the installed build, with a MiniBrowser wrapper that keeps
# these libraries on the path (the installed wrapper replaces LD_LIBRARY_PATH).
SRC="$HOME/.cache/ms-playwright/$SOURCE"
DST="$WK/browsers/$BUILD"
rm -rf "$DST" && mkdir -p "$DST/minibrowser-wpe"
for f in "$SRC"/*; do [ "$(basename "$f")" = minibrowser-wpe ] || ln -s "$f" "$DST/"; done
for f in "$SRC"/minibrowser-wpe/*; do [ "$(basename "$f")" = MiniBrowser ] || ln -s "$f" "$DST/minibrowser-wpe/"; done
sed -e 's|readlink -f $0|echo $0|' \
-e "s|^export LD_LIBRARY_PATH=\"\(.*\)\"|export LD_LIBRARY_PATH=\"\1:$WK/lib\"|" \
"$SRC/minibrowser-wpe/MiniBrowser" > "$DST/minibrowser-wpe/MiniBrowser"
chmod +x "$DST/minibrowser-wpe/MiniBrowser"Then run any browser runner with WebKit through that folder:
export PLAYWRIGHT_SKIP_VALIDATE_HOST_REQUIREMENTS=1
export PLAYWRIGHT_BROWSERS_PATH="$HOME/.cache/minnow-webkit/browsers"
npx playwright test --config playwright.next-owner.config.ts --project=webkitPLAYWRIGHT_BROWSERS_PATH here holds only WebKit, so set it only for WebKit runs. A Playwright
upgrade installs a new WebKit build: set BUILD to it and run the block again. Check with
ldd that nothing else is missing (LD_LIBRARY_PATH=<build>/minibrowser-wpe/lib:<build>/minibrowser-wpe/sys/lib:$WK/lib ldd <build>/minibrowser-wpe/bin/MiniBrowser | grep "not found").
What a local WebKit run covers depends on the build:
- Build 2336 (WebKit 26.5, the one Playwright 1.62 pins) has no
navigator.storageat all, in pages or in workers. It covers WebKit's IndexedDB path only, and its OPFS cases skip. - Build 2359 (WebKit 26.6, from Playwright 1.63:
npx playwright@1.63.0 install webkit) has OPFS in dedicated workers, with sync access handles:navigator.storage.getDirectory()resolves, andcreateSyncAccessHandle()opens a handle that writes, flushes and reads back. That holds in a persistent profile, which the repo's runners use. In a throwaway browser contextgetDirectory()rejects withUnknownError, as in Safari's private browsing.
To run the repo's lanes on 2359 while keeping the repo's Playwright, run the block with
SOURCE=webkit-2359. It mirrors 2359 under the folder name Playwright 1.62 looks for. That pairs
Playwright with a newer WebKit than it was released with. The library's OPFS cases
(opfs.spec.ts, audit-correctness.spec.ts) pass on it with OPFS really in use, but a failure
there is unconfirmed until it reproduces on macOS. Either way this is Linux WebKit, not Safari;
CI runs WebKit on macOS.
One more 2359 behaviour matters to the owner lanes: on a cross-origin isolated page, closing the tab that created a SharedWorker makes 2359 start a fresh instance of it, move the other tabs' ports to the new one and drop messages sent in the gap (roughly 80–300 ms). Build 2336, Chromium and Firefox keep the same instance, isolated or not, and 2359 keeps it on a page that is not isolated. A multi-tab owner case that hangs only on 2359 is likely this, not OPFS. The rebuild core's owner protocol survives it: every broker request is bounded and retried, and each broker instance announces an id so clients resend and owners register again; the SharedWorker restart note has the measurements and the repro.
The merge gate and fast SQLLogicTest profile run in .github/workflows/ci.yml on every push and pull
request, spread across parallel jobs. One job runs the format, type, lint, build, API contract,
SQLLogicTest, and heap-plateau checks. The unit suite runs under coverage in seven Vitest parts; a
final job merges their results and coverage and enforces the coverage floors on the whole suite,
exactly as npm run test:coverage does. The Format, types, lint, build, unit tests check requires
all of them, and the Unit tests on the oldest supported Node check requires all four of that
suite's parts on Node 22. The first of those also runs the full npm run build on Node 22.
The parts are balanced by measured duration, not by file count. Every test file runs in exactly one
part, and each part starts its longest files first. scripts/test-shards.ts does this for Vitest's
--shard, using the per-file times in scripts/test-durations.json; the maintenance workload still
runs alone, after the rest of whichever part holds it. The weights only steer the split: a stale or
missing weight makes a part slower, but it cannot skip a file or run one twice. That holds only if
every part computes the same split, so after the parts finish, each gate reads what every part
reported running and fails unless together they ran exactly what one unsplit run lists, each test
once (scripts/check-parts.mts). Each CI part uploads
its timings as a durations-* artifact; refresh the weights from a run with
gh run download <run id> --pattern 'durations-*' --dir .cache/durations and
npm run test:durations -- .cache/durations. A file's time varies by about half from run to run
with what shares its runner, so a refresh averages each measurement with the committed weight.
More than two hundred test files start PGlite, and a fresh instance runs initdb first: about three
seconds each. Under Vitest, a new PGlite() or PGlite.create() with no arguments instead loads a
data directory dumped once per run, by the run's global setup, from the installed PGlite right
after its own initdb (scripts/pglite-snapshot.ts). It is never committed. A call with any
argument runs initdb as usual. scripts/pglite-snapshot.test.ts checks that the two starts are
indistinguishable: the whole catalog, every setting, and the transaction and OID counters.
MINNOW_PGLITE_SNAPSHOT=off turns the snapshot off for a run.
Browser jobs run independently: Chromium and Firefox on Linux, and WebKit on macOS. Each engine's
library suite is split into parts the same way, by the per-spec times in
scripts/browser-durations.json (MINNOW_BROWSER_PART=1/3 MINNOW_BROWSER=webkit selects a part
locally). The rebuild-owner and site suites run once per engine: on the first Chromium and Firefox
parts, which take correspondingly less of the library, and in a WebKit job of their own. Chromium
also runs the packed consumer. Every engine there has OPFS in workers, so a missing OPFS API fails these jobs rather than
skipping their OPFS cases. The Real browsers check requires every engine to pass. Splitting the
jobs preserves their 45-minute deadlines and leaves time to save failure artifacts. A test that passes only on retry still fails the gate. Workflow dependency installation
retries network failures up to three times, with short delays; other installation failures stop
immediately. These retries do not rerun tests or bypass release gates. The merge gate restores
node_modules from a cache keyed on the lockfile, every package.json, the platform, and the Node
version, and runs the real npm ci whenever any of them differs.
.github/workflows/sql-conformance.yml runs the full SQL profile and long simulator
nightly and on demand. Both it and the release workflow also run
test:browser:conformance: the entire core browser suite, including the full pinned SQL corpus
and longer multi-tab plans over native IndexedDB and OPFS, split into Playwright shards (two each for
Chromium and Firefox, three for WebKit) that must all pass. WebKit runs on macOS so worker OPFS is available; a missing worker OPFS API
fails this profile instead of skipping its tests. Publishing requires the exact commit's successful
CI, SQL, simulator, and browser conformance gates. Retry a failed release through GitHub's rerun
control; there is no manual trigger that can bypass CI. .github/workflows/performance.yml runs the performance gate
nightly. The performance gate is deliberately kept off the merge path — it measures a machine as
much as it measures the code, and a merge gate that fails on a noisy runner is one people learn to
re-run rather than read. When a completed run crosses a ratio threshold, the gate starts a fresh
process and fails only if that same workload and comparison engine cross it again. Setup errors,
missing profiles, and incomplete runs still fail immediately. The SQL gate records the CPU model,
Node/V8 versions and host load before timing. Threshold profiles group machines by OS, architecture
and Node major version; CPU context is diagnostic and does not automatically select a looser threshold.
.github/workflows/browser-performance.yml runs the browser performance lane
nightly, also off the merge path, and uploads its JSON lines and summary as an artifact.
Each browser runner owns its test directory, server, port, and build prerequisites. Shared browser
defaults live in playwright.shared.mjs; runner-specific configuration stays in its named
playwright.*.config.ts file. This keeps every runner independently callable without hiding which
application it starts. The library server disables file watching and hot reload, so editing a
shared checkout cannot navigate a page in the middle of a conformance test. Finish edits before
starting a release run so its workers and pages all load the same build.
The tarball-shape test packs an isolated copy: its prepack hook cannot rewrite the compiler
output while concurrent bundle and declaration tests read it.
Browser runs save an HTML report in playwright-report/, including attached seed plans and
result summaries. CI, release, and nightly jobs retain reports for passing and failing browser
runs for 14 days; failed tests also retain traces. Each engine's library report is saved before
the site runner can replace it. Successful attempts delete their persistent browser profiles;
failed attempts retain and upload the profile with the trace, including a failed first attempt
whose retry passes. Because macOS WebKit otherwise stores OPFS outside Playwright's profile
directory, its storage fixture redirects that browser-owned data into the per-test profile. The
failure fixture also copies every file from the isolated test origin through the browser File
System API. Its manifest records each original path, size, captured byte count, hash, and capture
error, so incomplete evidence is explicit. Evidence collection has a separate 20-second,
20,000-file, and 512 MiB cap and marks the manifest incomplete if any limit is reached. Library
traces retain action timing, errors, sources, and attachments;
the static runner pages omit continuous screenshots and DOM snapshots. A console log alone is not
a replay artifact.
Focused native recovery tests force real checkpoint and WAL boundaries, terminate the worker, and compare the reopened manifest list with the list acknowledged before termination. IndexedDB cleanup tests check integrity between bounded pages and after reopening, including a legacy cleanup marker, concurrent pruning, and deliberately unrelated gaps. Worker lifecycle tests check slow disposal, its absolute timeout cap, and cleanup after an already-reported fatal error. These reductions run in all three engines alongside the longer seeded plans.
The Node worker-client lost-reply regression waits for the committed write's reply, drops it, then advances a controlled clock to expire the client request. It checks the stored row before and after the timeout and requires exactly one mutation request, independently of runner speed.
The native SQL comparison runner initializes PGlite, SQLite Wasm, and Minnow sequentially to reduce overlapping startup allocations. Its trace records each engine's start and readiness, so a page-process failure can be distinguished from a SQL comparison failure. Every oracle, query, and result check still runs, and a test that passes only on retry still fails CI.
Site tests distinguish editor text from executed output. TypeScript errors must appear in the compiler diagnostics alert, and the guarded-upsert example must log exactly zero updated rows and one skipped row in the results panel. A matching word in the source editor cannot satisfy either check.
Unit files are capped at four concurrent workers (or the available CPU count, if lower). Each file can start complete databases and comparison engines, so unrestricted file concurrency can produce heap pressure and scheduling timeouts unrelated to the engine. The maintenance stress file runs alone after the other unit files, so the growing simulator seed corpus cannot consume its CPU time. Its own writer and background-maintenance concurrency remains intact, and coverage from both execution groups is combined. Test workloads, deadlines, assertions, and coverage floors remain unchanged. Browser runners likewise cap independent scenarios at two workers (one on a two-CPU runner); each concurrency scenario still creates its full set of tabs.
What each layer proves
- Unit and language tests stay beside the source they exercise. They cover predictable
behavior, supported SQL and mutations, comparisons with other engines, fault injection, and the
benchmark generator and answer-checking rules. Reads and writes are both checked
differentially: the read conformance suite diffs a generated query corpus against SQLite and
PGlite, and the mutation conformance suite replays a seeded script of inserts, updates,
deletes, upserts, and atomic write scopes against the same two oracles — comparing statement
outcomes, affected-row counts,
RETURNINGrows, trigger-written audit rows, and the full table state after every step. The fixture's triggers are declared in each oracle's own dialect (plpgsql trigger functions for PGlite) with identical bodies, andMERGE— which SQLite lacks — runs verbatim on PGlite and as an equivalent statement pair on SQLite.npm testpicks upapps/site/benchalongsidepackages/**, so the dataset generator, the oracles, and the suite definitions are checked on every unit run. Four seeded oracle suites then check the paths where stored state can diverge from what a query returns: random mutations, rekeys, compaction, reopens, and column and index DDL, with every indexed query shape compared against the same query forced to scan and against a JavaScript model (index-oracle), every live query's deliveries and the rows a second subscriber rebuilds from its patches compared with a fresh run of its SQL after every commit (live-oracle), stepped folds interleaved with writes and DDL from a second connection (compaction-interleave), andMATCHqueries through updates, folds, and reopens (fts-oracle);npm run soakexplores all four under new seeds. A PostgreSQL-diffed constraint suite pins CHECK, NOT NULL, DEFAULT, generated, FK, and UNIQUE semantics and tags each documented divergence, and a fault sweep injects an abort or quota refusal at every IndexedDB write of every write shape and expects the logical state unchanged, integrity clean, and the retried write to succeed. - Library browser tests exercise IndexedDB, OPFS, and transaction behavior that a Node substitute cannot prove, and drive a database through a real module worker: the package entry booting, transferred buffers arriving intact, and a second worker reopening what the first one wrote. Storage fixtures use persistent browser profiles in every engine so durable adapters reach their disk-backed browser implementations. They also run the SQL engine itself where it ships: the committed SQLLogicTest profile executes through the published worker against real IndexedDB and OPFS in all three browsers, and a seeded interaction plan runs with each plan connection being a real tab, so the same properties the Node simulator checks are judged against real workers, real storage, and real crashes.
- The packed-consumer test builds every public package, installs the resulting tarballs in an OS-temporary Vite application outside the npm workspace, and resolves every exported entry with both Bundler and NodeNext TypeScript resolution. Chromium then runs the emitted worker against IndexedDB, migrates and queries through Kysely, observes a live update, streams exports, mounts the React and devtools adapters, exports a snapshot, restores it into OPFS, and reopens it. The Minnow archives and direct tool and peer versions are pinned to the build; npm resolves their ordinary transitive dependencies into a private temporary cache as it would for a new project.
- The public API contract assigns every package subpath a stable audience and snapshots the
declaration syntax exported by every typed entry point, including whether each name is
type-only or available at runtime.
npm run api:checkfails on an unclassified subpath or an added, removed, or changed public declaration;npm run api:reportprints the surface for review. After classifying compatibility and documenting the release impact,npm run api:updaterecords an intentional surface. Coverage has a separate non-regression floor for every published package, so the core suite cannot hide a drop in devtools or an adapter. The v1 support policy defines the audiences and guarantee. - Site browser tests execute the public examples and drive the benchmarks page itself: one
case runs a suite end to end in each browser and asserts it verified against the oracles,
another asserts the
/benchmarksroute is cross-origin isolated. Documentation cannot drift into non-running sample code, and the harness cannot drift from the page that runs it. Comparison suites require one result per declared engine/workload and report expected, attempted, supported, verified and failed counts. A missing live driver on an engine that declares subscriptions fails; the SQLite and PGlite comparison drivers' absent subscription support is declared explicitly rather than inferred from a missing driver method. Timings show medians. The exportedp95Msis an empirical percentile of five or seven timed windows, which is their maximum, rather than an estimate of production tail latency. - Semantic path equivalence generates NULLs, signed zero, exact decimals, invalid text, casts and empty/nonempty membership. It compares optimized and unoptimized row execution, vector execution, literal and parameter input, memoized results and worker RPC. Values and result domains agree exactly; refusals retain their error class. PostgreSQL independently checks acceptance and values without converting NUMERIC text through Float64. The same corpus runs over native IndexedDB and OPFS workers. Interaction runs also check that the bounded background history agrees with observer evidence.
- The performance gate detects regressions on stable seeded query shapes, reads and writes alike. Read-only engines calibrate their repeat counts independently so every fast path gets a measurable sample. A regression is reported only when the full ratio range observed across both engines' samples crosses the checked-in threshold, then repeats in a fresh process. Every stateful mutation window executes the same fixed 12-operation sequence on all three engines and finishes with a cross-engine state check. The suite includes exact-NUMERIC arithmetic, composite-key lookup, and the Kysely compilation/driver path as well as direct SQL. It is a guardrail, not a published cross-engine benchmark: the comparison engines run without indexes, which is fine for noticing that Minnow got slower and useless as a fair cross-engine claim.
Plain COUNT(*) reads use the snapshot's surviving row count without preparing column schemas
or index scans. The regression suite checks this path after deletes, updates, upserts, and
compaction, including old snapshots, concurrent connections, memory budgets, and cancellation.
Native-browser SQL comparisons
The library runner executes every SQL feature-matrix entry through Minnow's built module worker over both native IndexedDB and OPFS in Chromium, Firefox, and WebKit. SQLite Wasm and PGlite run in those same real browsers as independent comparison engines. Background maintenance stays enabled, and unexpected worker or page errors fail the campaign even when query answers match.
The 370 matrix entries are accounted for explicitly: 306 supported entries execute, and 64
unsupported entries must reject with their recorded error while leaving the fixture unchanged.
Portable reads compare columns and values with PostgreSQL. Compatible mutations compare affected
counts, RETURNING, and their actual target table's state, with domain checks for volatile values.
The report separately counts cross-engine comparisons and features with fixed behavior probes.
Every supported entry must have one of those semantic checks; acceptance alone cannot pass the
matrix. The category totals must cover the entire matrix.
An additional 137 independently authored behavior steps cover 74 matrix features, with two more
PostgreSQL state comparisons. They check TRUNCATE and UPSERT post-images, stored defaults and runtime
values, trigger effects and removal, constraint enforcement, generated columns, views, sequences,
identities, ALTER backfill, and transactions. Minnow's documented minimum-value ANY_VALUE result
has a fixed assertion even though PostgreSQL may choose another value. Runtime defaults must be a
valid timestamp, a finite random value in range, and a version-4 UUID. Negative probes require the
specific error type and message. The remaining DDL forms have observable schema checks, and all
28 nonportable reads have fixed answers or documented value-domain assertions. A new entry in a
category without cross-engine result comparison must provide a behavior probe, or the suite fails.
Single-argument AGE must agree with its documented two-argument form using the same statement's
CURRENT_DATE, including NULL propagation. BM25 checks matching rows and finite positive scores;
it does not invent an exact public scoring formula. Index probes check catalog behavior and query
results, while the separate performance suites cover execution cost.
Each seed also runs fixed edge cases, 42 generated queries, and four mutations with immediate post-state checks against SQLite and PostgreSQL: 117 independent comparisons per storage adapter and browser. Cases include NULL logic, joins, aggregates, windows, correlated subqueries, Unicode, JSON, numeric boundaries, and a literal question mark alongside a bound parameter. Numeric values compare exactly unless a particular aggregate or cross-runtime math expression declares a floating-point precision. JSON and numeric normalization follows result-domain metadata; ordinary text is never parsed as JSON.
The campaign replays the committed sql-conformance seeds and accepts MINNOW_SEED for new or
reproduced inputs. Its report records the seed and each coverage category.
SQLLogicTest: broad, strict SQL correctness
Minnow ships a native runner for SQLite's database-neutral
SQLLogicTest format. The parser and
answer checker live in @minnowdb/core/testing; the command-line runner streams one record at a
time and creates one empty database per file. A large corpus therefore does not become an equally
large in-memory syntax tree.
The runner implements the original format's statement ok/error, typed query, nosort,
rowsort, valuesort, result labels, MD5 result hashes, hash-threshold, skipif, onlyif
(with the trailing # comment the upstream corpus writes after an engine name), and halt
directives. Malformed records, wrong value counts, wrong types, duplicate labels with
different answers, and unknown directives are failures with exact source lines. Conditions are
reported as skips; they are never silently discarded.
The ordinary local profile is committed and needs no network:
npm run test:sql:standard
# Iterate on one source file or its first 200 records.
npm run test:sql:logic -- --file packages/core/testdata/sqllogictest/standard-select3.test
npm run test:sql:logic -- --file packages/core/testdata/sqllogictest/standard-select4.test --stop-after 200
# Show broad-suite progress, or trace every record from an isolated boundary.
npm run test:sql:logic -- --file packages/core/testdata/sqllogictest/full-select5.test --progress-every 100
npm run test:sql:logic -- --file packages/core/testdata/sqllogictest/full-select5.test --trace --trace-from 800It runs 1,822 statements and 6,345 queries, checking 385,389 scalar results across 8,169 source
records. The same committed files also run inside Chromium, Firefox, and WebKit
(sqllogictest.spec.ts), through the published module worker against real IndexedDB and OPFS with
automatic maintenance left on, so a browser engine's Date, regular-expression, or number-formatting
difference, a result that does not survive the worker boundary, or a durable store's commit path
under thousands of statements is checked against the corpus's recorded answers rather than
against Node's. Each run attaches its per-file timings to the report. Every thirty seconds,
native runs also log and attach their phase, completed statement and query counts, accumulated
timings, and a bounded prefix of the active SQL. This preserves progress when the unchanged
ten-minute per-file deadline expires. The fast set includes representative five-table and seventeen-table join-order families
that guard against pathological Cartesian work. On the development machine used to measure it,
the whole profile took about fifteen seconds. That makes the broad suite part of
npm test, npm run check, and every pull request, instead of a suite agents discover only after
they finish a change.
The supported full profile adds the exhaustive multi-way join families:
npm run test:sql:fullIt is fully runnable locally, reports progress every 500 records, and contains all 10,708 records
from the five selected upstream files: 1,822 statements, 8,884 queries, and 5,093,664 checked
scalar results. There are no all-profile exclusions. standard-exclusions.json still records the
2,539 supported exhaustive-join records that move from the fast profile to the full one solely
because of runtime.
The corpus is pinned to immutable revision
572273bf5076176e17f47aea75115a225e70fef8. upstream.json records its URL, date, 115,244,234-byte
archive size, archive SHA-256, five source hashes, and expected 622 test files. Regeneration first
verifies all of those inputs:
npm run test:sql:fetch
npm run test:sql:prepare-standardThe raw 622-file corpus remains locally runnable for boundary discovery. It is expected to expose
unsupported SQL; use --keep-going when auditing rather than treating it as a release profile:
npm run test:sql:upstream -- --stop-after 500
npm run test:sql:upstream -- --keep-going --max-failures 25Adding support means removing its exact exclusion, regenerating the committed files, and adding a focused regression test. Adding an exclusion without a concrete reason makes the ledger diff visible in review; there is no wildcard skip list.
When adding a runner, give it one responsibility and make it independently runnable. When adding a suite case, derive smoke-test counts from the suite itself instead of copying totals into tests or HTML.
Seeds, and how a soak failure becomes a permanent test
The generated suites — SQL support, write support, the deterministic simulator, the
columnar-versus-row comparison, and the compaction and multi-tab soaks — build their corpora from
a seeded generator. A committed run is deterministic: it uses the checked-in seeds plus every seed
that has ever failed, listed in packages/core/regression-seeds.json. Each recorded seed runs as
its own test case next to the suite's default, so a seed in that file is executed on every
commit, not merely listed. That makes the suite a reliable regression net, and on its own it
would be nothing else, because the questions it asks never change.
npm run soak is the other half. It runs the same suites on seeds nobody has tried and stops at
the first failure, printing the seed:
npm run soak -- --rounds 200A failing seed is the whole artifact. Replay it directly:
MINNOW_SEED=1476318588 npx vitest run packages/core/src/engine/sql-conformance.test.tsThen add it to regression-seeds.json under the suite that failed, where every future run picks
it up. Never remove one: a seed in that file is a bug that used to exist, and the entry is what
stops it coming back. The explored space only grows, and it grows by exactly what the soak found.
Every fast-check property follows the same rule. It takes its seed from a seedsFor case rather
than letting fast-check draw a fresh one, so a CI failure replays and the soak runner explores
the property. seeds.test.ts fails on any fc.assert without a seed, on a registry key that no
suite runs, and on a seeded suite the soak runner does not list.
Declared reach
A passing seed shows that no law was broken, not that any law was tested. A plan can update rows that do not exist, inject every fault into a write that changes nothing, or deliver every live result by re-running the query. Seed 1349451771 in the registry is the case where all of its faults hit missing rows, so no storage write hook fired.
So each generated campaign declares the states its laws depend on, and fails when too few of its
histories reached one. testing/reach.ts counts each history once per state, after the
campaign; the counting is TanStack DB's createOracleReach. The interaction campaigns report the
states each plan entered in InteractionRunResult.reached: an UPDATE or DELETE that matched
rows, a refused write, a LIMIT that cut rows off, a rollback that discarded changes, reads
during a concurrent round, a fault after which the write had or had not landed, a reopen of a
database with rows, and, in their own campaigns, rekeys, retired-key reads, refused unique
values, ALTER TABLE on populated tables, and index lookups that returned rows. The live oracles
declare patched, moved, replaced, shrunk, re-run, and rekeyed deliveries. A MINNOW_SEED replay
checks one history, so reach stands aside then.
A campaign can be split across several test files so parallel runners share its histories. The
directory publication compatibility campaign runs in four files, one slot of its seeds each. Then
no single file sees every history, so no file asserts reach on its own subset. Each file records
what its histories reached in the run's reach directory, and a *.reach.test.ts file asserts the
union against the declared states (testing/reach-union.ts). The test sequencer keeps those files
in the same CI part and runs the union check after them. The union fails if any declared file left
no record or ran no histories, so a file that silently stopped running cannot pass.
Format compatibility
A browser database's data lives in the user's browser, so it outlives every deploy. There is no migration window and no way to reach back and rewrite it: if a format change makes yesterday's blocks unreadable, the first anyone hears is a user whose application will not open.
The following corpus describes compatibility within the existing 0.x engine. The planned 1.0
rebuild starts a fresh chain; its first released writer begins a new fixture obligation.
next/storage/legacy-data.test.ts uses the old artifacts as refusal inputs instead: next open
must report MINNOW_LEGACY_DATA, preserve every old byte/schema/record, and create no replacement.
It covers frozen OPFS trees with and without sync-handle capability and actual I8 databases
loaded from every frozen snapshot. Synthetic native I1–I8 shapes and O5/O11 markers extend
refusal coverage; they are not claimed to be frozen older-writer images.
packages/core/format-fixtures/ holds one frozen database per released block/snapshot pair — a
framed snapshot, which carries the raw block bytes verbatim, plus the answers that build gave to a
fixed set of queries. Each manifest records the exact @minnowdb/core version that wrote it.
format-compatibility.test.ts rejects a fixture that claims a future writer, reproduces the
current writer byte for byte, opens every fixture, checks the answers still hold, and checks that
writes into a restored database still work. Frozen raw vectors independently cover every
block-format-2 physical type.
The directory also holds one native fixture for every locked OPFS layout. The test requires a
fixture for the current writer and checks its recorded package version, then reopens each fixture's
format marker, checkpoint, WAL tail, acknowledgement file, and packed extent through the current
adapter before committing and recovering another write. Every supported older fixture must
upgrade automatically through ordinary open; an older-layout refusal cannot pass this test.
The ordered OPFS upgrade registry must cover every version between the first locked layout and
the current one. upgrades.test.ts injects failure at every preparation/publication I/O boundary,
models both tab death and power loss, exercises partial transfers and concurrent openers, and
keeps concurrent openers waiting through a slow live conversion. A resurrected ready record
cannot roll back later acknowledged writes, even with a missing/torn marker and missing/corrupt
completion receipt. Damaged native proof after resetting a nonempty old WAL is refused rather
than repaired from stale staging. The native browser
worker suite discovers the same frozen fixtures and checks automatic upgrade and new writes
across restart. A pinned test-only alias of the released core 0.10.0 package proves that the actual
layout-6 reader opens the old fixture and refuses the upgraded tree before mutation, in Node
and native workers. A second alias, of core 0.12.1, is the last IndexedDB schema-2 and OPFS
layout-7 writer: marker-upgrade.test.ts and indexeddb-schema3.test.ts have it leave a
merge-v1 fold in flight, then upgrade, finish that fold, write, reopen, and check that 0.12.1
refuses the result without a byte changing. A third alias, of core 0.13.1, is the last IndexedDB
schema-3 and OPFS layout-8 writer: marker-upgrade.test.ts upgrades its database to layout 9,
logs a commit whose frame spans continuation frames and whose index changes exceed one layout-8
chunk, reopens from the log and from a checkpoint, and checks that 0.13.1 then refuses the
database; indexeddb-schema4.test.ts does the same for schema 4 with every older writer. A fourth
alias, of core 0.14.1, is the last IndexedDB schema-4 and OPFS layout-9 writer:
marker-upgrade.test.ts upgrades layouts 7, 8, and 9 to the current layout, rekeys a row through the
ordinary API, reopens, and checks that the retired key still resolves and that every released
reader then refuses the database; indexeddb-schema5.test.ts does the same for schema 5 from
every released IndexedDB writer, and snapshot-format2.test.ts checks that only a snapshot
holding the key-forwards table is written as format 2. A fifth alias, of core 0.15.0, is the last
IndexedDB schema-5 and OPFS layout-10 writer, the last build that could not fold a table across
ALTER TABLE, and the last without delta merges: schema-change-fold-upgrade.test.ts uses a
frozen native OPFS database written by 0.15.0 at the real 4,096-segment ceiling. It retains every
row and segment from the original live-writer history; no case size is reduced. The fixture is
a gzip-compressed binary container: one JSON header line maps paths to byte ranges in the
following payload; identical native files share a range. This reduces repository bytes without
changing any restored file, row or segment. The released writer hardcodes the 4,096-segment
admission ceiling; its compaction batch options cannot lower that limit. Its manual generator is
scripts/write-fold-ceiling-fixture.mts. The test first checks that the released reader reads
all rows but refuses another write and cannot fold them, then upgrades through the ordinary API.
IndexedDB cases still build their released history live. The suite
upgrades the database to the current schema or layout through the ordinary open API, checks that
the first write folds the table and succeeds, interrupts and retries the IndexedDB upgrade, races
current and released openers, and checks that 0.15.0 then refuses the database.
The first upgraded OPFS write and background-fold settlement have a progress-aware watchdog:
30 seconds without an advancing native cursor/state/row or output-byte count fails with the
last observation; even continuing progress cannot exceed a 120-second phase cap. Repeated
polls and lease-renewal timestamps do not extend it. Active folds are observed without
launching competing full-table scans; an idle fragmented table still gets a read to schedule
its next fold. All existing data, reopen, integrity, interruption/retry and corruption checks remain.
The watchdog is a .test-support.ts helper; the package file list excludes that test-only output
from the published tarball, while the normal build still type-checks it.
delta-merge-upgrade.test.ts leaves single-row updates and deletes over its folded partitions,
upgrades the database to the current schema or layout, merges those deltas, writes, reopens,
interrupts and retries the IndexedDB upgrade, races current and released openers, refuses a
damaged merge record as corruption, and checks that 0.15.0 then refuses the database. Schema 6
and layout 11 were never released, so no alias writes them: marker-upgrade.test.ts upgrades
layouts 7 to 10, and a layout-11 marker over the layout-10 fixture, to the current layout, folds a
table across ADD and DROP COLUMN there, merges a table's deltas there, and writes packed
segments there. A sixth alias, of core 0.16.0, is the last IndexedDB schema-7 and OPFS layout-12
writer, the last that stored every datetime column as TIMESTAMPTZ and the last without packed
segments: timestamp-kind-upgrade.test.ts has it declare TIMESTAMP and TIMESTAMPTZ columns,
upgrades the database to schema 8 or layout 13 through the ordinary open API, checks that those
columns stay TIMESTAMPTZ, declares new TIMESTAMP columns that render without a zone,
reopens, interrupts and retries the IndexedDB upgrade, races current and released openers,
refuses a damaged time-zone mark as corruption, and checks that 0.16.0 then refuses the
database; marker-upgrade.test.ts takes the frozen layout-12 fixture to layout 13 the same way,
and snapshot-format3.test.ts checks that only a snapshot with a TIMESTAMP column is written as
format 3, that 0.16.0 refuses it into every store, and that 0.16.0's own snapshots import with
their columns as instants. packed-segment-upgrade.test.ts writes a wide table's history with
the same alias, upgrades the database, reads the history, writes single-row commits that pack,
folds them with the released segments, reopens, interrupts and retries the IndexedDB upgrade,
races current and released openers, refuses a damaged packed block and a record naming a member
its block lacks, and checks that 0.16.0 then refuses the database; packed-segments.test.ts
exports a database holding packed segments and imports the snapshot into this build and into
0.16.0. format-compatibility.test.ts restores the forward the frozen format-2 fixture stored,
checks it resolves until it expires, rekeys data an older writer exported, and restores the
column kinds the frozen format-3 fixture stored. The marker upgrade is cut at each of its eight
I/O boundaries by tab death and by power loss, from every older layout.
marker-race.test.ts pauses one opener inside a marker write — while creating a database, and
while upgrading one — lets a second opener read the marker in that window, and checks that the
second waits instead of refusing the database or writing the marker again beside a live WAL.
Unsupported pre-contract prototypes are refused without changing their bytes.
The layout-7 tests also zero or truncate acknowledged WAL bytes and
damage either acknowledgement slot; recovery must report corruption rather than roll back.
It also fails when the current BLOCK_FORMAT_VERSION or SNAPSHOT_FORMAT_VERSION has no fixture
behind it. That failure is the useful one, because it fires before the damage:
npm run fixture:formatThe native OPFS fixture has its own writer:
npm run fixture:opfs-formatRun the relevant writer on the build that still writes the old format, commit the fixture, and only then change the version. A fixture can only be produced by the build that writes it — once that code is gone, the format it wrote cannot be regenerated. For the same reason, never delete a released, locked fixture. Block format 2 is the first such lock; the unsupported experimental block-1 fixture was replaced before v1.
Internal orchestration and adapter transitions
Catalog mutations, per-connection writer admission, and query preparation/execution have separate internal owners. The public database API delegates to them; SQL kernels and adapter atomic publication remain shared with the ordinary paths. Refactoring these owners must preserve cancellation, reader leases, compaction turn lending, shutdown draining, and original failure reporting. The lifecycle, admission, semantic equivalence, and native interaction suites exercise those boundaries. Caller-provided clock and ID callbacks retain their original database receiver through the extracted catalog and query paths, with a lifecycle regression on all three adapters.
storage/commit-admission.test.ts runs the same multi-table commit refusals on memory, IndexedDB,
and OPFS. Invalid coverage, duplicate limits, invalid limits, and segment backpressure must leave
the manifest, transaction journal, and staged bytes unchanged. A corrected retry on that same
transaction must publish every changed table.
Record-core hardening tests verify bulk unique-key removal without per-key ordered-index work, canonical snapshot export and restore after mixed mutations, and exact batched block lengths and checksums after refusal, retry, and placement-only adapter replay. Snapshot ordering is lazy; constraint membership stays immediate. IndexedDB hardening also verifies that independent commit reads are queued together and a refused commit leaves the journal and staged bytes unchanged for a corrected retry. The controller extraction and storage changes add about 4 KiB to the raw OPFS bundle allowance while keeping the compressed download budgets unchanged.
Matched-index performance comparisons
npm run benchmark:compare runs the Node suite with primary-key indexes on every engine's
ordinary, mutation, and settled tables. It verifies query and final-state results before timing.
Use this command and the live browser comparison for competitive speed claims.
The existing benchmark:gate preserves its historical schema and runtime-specific thresholds,
including unindexed ordinary-key comparator tables. Its purpose is detecting changes against
that same workload. Its ordinary key ratios cannot support competitive speed claims. A comparison
run cannot update those thresholds; changing that gate's schema requires fresh calibration on
every recorded runtime, including Linux.
Running out of quota
quota.test.ts covers what happens when the browser refuses a write because the origin is out of
space — the characteristic way a browser database fails, and the one an application most needs to
handle deliberately. It pins four things: the write fails rather than half-landing, the error
keeps its QuotaExceededError identity so an application can branch on it, everything committed
earlier stays readable, and the same write succeeds once there is room, with no repair step.
Property-based tests
block-format/properties.test.ts describes the format as properties and checks them
against generated inputs rather than chosen ones: a value written and read back is the same value,
both codecs agree, a zone map contains everything it summarizes, and a flipped byte is detected
rather than decoded into plausible rows. The generators reach for what breaks encoders — negative
zero, the extremes of the double range, subnormals, empty and astral-plane strings, all-null and
empty columns. A failure shrinks to a minimal case and prints the seed and shrinking path. The same property
campaign runs in dedicated workers in Chromium, Firefox, and WebKit, using each engine's native
CompressionStream, DecompressionStream, UTF-8 conversion, dates, and typed arrays. Every
browser replays the same committed seeds; set MINNOW_SEED to reproduce a reported failure.
The block-format-properties entry in regression-seeds.json and the soak runner keep discovered
failures in the permanent regression set.
Soaks and deterministic simulation
Four suites cover accumulation rather than a single operation, which is where a fold that loses a row, a scheduler interleaving, or a compactor that stops folding actually shows up:
compaction-soak.test.tsruns 1,500 interleaved mutations against a referenceMap, compacting at checkpoints, and compares the whole table to the reference each time. Compaction is bounded and incremental — one call folds a limited number of blocks — so the test expects steady progress, not a finished table after one call.concurrency-simulation.test.tsruns twelve independent databases over one shared store, the shape of twelve browser tabs on one origin, issuing a seeded random schedule. It checks that the outcome is explicable: every visible row was written by some tab, acknowledged writes are present, no key appears twice, the write the store acknowledged last is the one visible, and every tab sees the same database afterwards.auto-compaction-soak.test.tsis the same kind of history with the background maintenance left on, as it ships: 1,800 seeded mutations and reads while folds and collection passes land underneath them, the table checked against the reference at every checkpoint, then settled and held to convergence bounds — a scan reads the bounded folded partitions and only a level-zero tail below both background fold thresholds, and the store holds the data rather than the history.simulator.test.tscontrols the completion order of every asynchronousBlockStorecall across independent database clients. A referenceMapchecks commuting concurrent mutations at each checkpoint; scheduled crash points must reopen to exactly the state before or after the write; compaction and garbage collection run throughout. The final quiescent store is bounded by the key space rather than the number of rounds across blocks, segment records, transaction records, and manifests, and must have no leaked leases. The diagnostic trace is a fixed-size tail, so the simulator itself does not grow with the run.
Run or save an exact plan directly:
npm run simulate -- --seed 24301 --rounds 500 --clients 8 --key-space 128
npm run simulate -- --seed 24301 --write-plan /tmp/minnow-plan.json
npm run simulate -- --plan /tmp/minnow-plan.jsonThe seed fixes both workload generation and storage completion choices. A failure prints its
replay command. npm run soak -- --suite deterministic-simulator explores fresh seeds, and a
failure joins packages/core/regression-seeds.json so every future unit run replays it.
Interaction plans
The storage simulator above drives one table with keyed upserts and deletes. The interaction-plan
simulator (interaction-simulator.ts, exported from @minnowdb/core/testing) drives the SQL
surface an application uses, in the spirit of Turso's simulator: a seeded plan of interactions
over several connections that share one database — CREATE TABLE with random column types and
nullability, multi-row inserts by literal and by parameter, predicate UPDATE and DELETE,
selects with three-valued predicates, LIMIT and ORDER BY, secondary indexes, DROP TABLE,
SQL transactions that commit or roll back, rounds of concurrent keyed writes with readers in
flight, storage faults and worker crashes, reopens, compaction and collection, and checkpoints.
The plan is JSON, so a failing seed replays exactly and can be checked in.
Generated plans preserve the randomized sequence and add a fresh-row insert for each configured fault point before the final checkpoint. These keys lie outside the random key range, so each probe can change the database and reach its write hook. An update or delete of a missing row can otherwise make a random fault step do no work. The fresh probes supplement those random cases; unsupported fault points are still reported as skipped by drivers that cannot inject them.
Every interaction is executed through the real SQL entry points and judged against a shadow model
that evaluates the predicates with SQL's three-valued logic. Beyond "the rows match", the runner
checks properties a database must honour whatever its internals do: a rejected insert leaves none
of its rows behind; reported row counts equal the model's; nothing matching a delete survives it;
LIMIT returns exactly the first rows in order; COUNT(p) + COUNT(NOT p) + COUNT(p IS NULL)
equals COUNT(*); a UNION ALL has the sum of its members' cardinalities; uncommitted rows are
visible on their own connection and invisible to another; a read taken during a round of
commuting writes shows every untouched key exactly and every touched key at its old or new
value; a mutation interrupted by a fault lands entirely or not at all and a reported success is
durable; and at every checkpoint every connection reads the same database as the model. After
each compaction and collection, the IndexedDB and OPFS stores must also pass a full
checkIntegrity().
With rekeying: true (--rekeying true on the command line) a plan also changes primary keys:
UPDATE … SET id = … to a constant, shifted by a step, negated, or swapped between two rows,
alone or inside a transaction, and some tables get a self-referencing
REFERENCES … NOT ENFORCED column. The model keeps every retired key's forward, so it checks the
rekeying rules too: a rekey onto a live, repeated, or retired key fails
as a duplicate and writes nothing; references follow the moved rows; a retired key reads, updates,
upserts, and is compared through its forward on every connection; and inserting a retired key is
refused. These steps come from a second random stream, so a plan generated without the option is
exactly what it always was and every recorded seed still replays the plan that failed. The Vitest
suite runs rekeying plans over every store under the interaction-simulator-rekeying seeds.
Four more options widen the schema a plan works against, each from a random stream of its own, so turning any of them on leaves the others' steps where they were:
constraints(--constraints true) gives tables an inlineUNIQUEcolumn, a wide-domain column that may later get aUNIQUEindex (whose build the model refuses when the rows already hold a duplicate), composite unique indexes, and child tables with an enforced foreign key that isON DELETE CASCADE,SET NULL, orRESTRICT. The model predicts which statement each constraint refuses, and with which error: a duplicate isUniqueConstraintError, a missing parent or a restricting child is the foreign key's own refusal, and a statement that breaks one changes nothing. Uniqueness is judged per statement, so a swap is allowed. Deletes cascade down the tree of children, dropping a referenced table is refused, and withrekeyinga parent's rekey moves its children's references. Plans also addINSERT … ON CONFLICT (unique column) DO UPDATE | DO NOTHING(the row holding the value is updated under its own key; any other collision is an error), a targetlessON CONFLICT DO NOTHING, and selects shaped for the secondary-index path — equality,IN, and ranges on an indexed column, ordered by it — whose plans the Node driver explains to count the reads an index served. A concurrent round whose writes contend for one unique value runs concurrently all the same, and its outcomes must be those of some serial order: of two writes claiming one free value, exactly one lands.schemaChanges(--schema-changes true) interleavesALTER TABLEwith the writes:ADD COLUMNwith a constantDEFAULT(sometimes reusing a dropped column's name),DROP COLUMN,RENAME COLUMN, andCREATE/DROP INDEX, including drops and renames the engine must refuse because an index or foreign key uses the column. Some inserts then leave the defaulted columns out. Columns are added to and dropped from tables that already hold rows, so folds meet segments written before a column existed and updates whose only changed column was dropped, and reads meet them through every path, the secondary-index selections among them.fullText(--full-text true) addsMATCH … AGAINSTqueries, with prefixes, several columns, and an extra predicate, over keyed tables and over append-only tables a full-text index can cover. The model tokenizes as the engine documents: NFKC, lowercased, runs of letters and digits. The append-only tables are folded and collected now and then too, so searches meet an index that survived a fold.burstCommits(--burst-commits N) adds bursts of up toNsingle-row commits to one table from every connection, each judged as it lands. Every plan with the option holds at least one. After a burst of 640 commits or more the table must hold at most 640 visible segments: automatic folds have to keep up, which is how a table that can never compact shows up long before its writes are refused.
The Vitest suite runs plans with all four over every store under the
interaction-simulator-schema seeds.
Two refusals inside a transaction are engine behaviour rather than defects, so the runner counts
them and continues: a COMMIT that lost the race to another connection's data commit, and a
transaction the engine rolled back after transactionIdleTimeoutMs of idleness. Both discard the
whole transaction, and an expired one is acknowledged with a ROLLBACK before the plan goes on.
See transactions for the rules themselves.
The runner also validates result shape: projected columns must match in order, each row must
have exactly its declared fields, and a missing field cannot stand in for NULL. Its expected-error
paths check the engine's specific error identity or exact documented refusal. An unrelated error
does not become acceptable just because a statement was meant to fail or a crash was injected.
Custom drivers must preserve error names and causes across their transport, including
DatabaseWorkerOutcomeUnknownError for a mutation interrupted by a worker crash.
The runner is driver-agnostic. In Vitest (interaction-simulator.test.ts, with the rekeying and
schema suites in interaction-simulator-rekeying.test.ts and interaction-simulator-schema.test.ts,
whose IndexedDB seeds alternate with interaction-simulator-schema-indexeddb.test.ts)
each connection is a
MinnowDatabase over one shared memory, IndexedDB, or OPFS store with the storage fault points
armed. In Playwright (interaction.spec.ts) each connection is a real tab holding the published
worker over a real IndexedDB or OPFS database, and the plan's faults terminate a worker with a
statement in flight — the tab then reports the loss to its client at once, so the in-flight call
fails as an unknown outcome instead of waiting out the client's silence deadline. The same seed
produces the same plan in both.
The browser driver recovers a crash by reloading the document. A new worker in the same document
is enough on Chromium and Firefox, but WebKit can keep a transaction the dead worker still had
queued — behind another of its own, or behind another tab's write that waited on it — registered,
and blocks every transaction that overlaps it, in every tab, until the tab that ran the worker
closes; a reload does not always release it. The engine bounds that wait with
StorageUnresponsiveError, raised by the reopen itself when the stuck transaction blocks the
open's first read. A deliberate
WebKit/IndexedDB crash campaign that meets an unresponsive store records it in
transientsAccepted and stops, with interactions counting the steps it judged; background
maintenance in other tabs that was waiting on the same database reports the same
StorageUnresponsiveError, and that report is accepted with it. This exception is limited to that
browser, store, and deliberate crash campaign. The resilience spec's crash-recovery test makes
the same exception, and only for the reopen right after its injected worker crash on WebKit's
IndexedDB.
Every browser/store pair also runs a separate campaign without fault steps that must complete
the entire plan; a crash exception cannot replace that coverage. Other early stops fail.
The standard browser campaigns generate 220 steps with three connections. The conformance profile
generates 800 with four connections. Each run attaches its exact generated plan before executing
it. The nightly workflow varies a logged MINNOW_BROWSER_INTERACTION_SEED_BASE input; reproduce that frontier with:
MINNOW_SEED=123456 MINNOW_BROWSER_INTERACTION_SEED_BASE=123456 npm run test:browser:conformanceThis fixes the generated plan, while actual browser scheduling remains uncontrolled. Node's IndexedDB and OPFS simulations are additional diagnostic checks, not proof of native durability.
npm run simulate:interactions -- --seed 24301 --length 300 --connections 4 --store indexeddb
npm run simulate:interactions -- --seed 24301 --write-plan /tmp/minnow-interactions.json
npm run simulate:interactions -- --plan /tmp/minnow-interactions.json --store opfs
npm run soak -- --suite interaction-simulator
npm run simulate:interactions -- --seed 1 --length 1500 --connections 6 --tables 3 --key-space 48 \
--constraints true --schema-changes true --full-text true --burst-commits 1500 --store opfs
npm run soak -- --suite interaction-simulator-schemaA failure names the interaction, the property, the model's rows, and the SQL leading up to it.
The first soaks of this simulator found seven defects the existing suites had missed — an
index-pruned scan that resurrected deleted rows, a composite index that skipped rows with a NULL
trailing column, a stale intermediate value served by block-level pruning, a fold that refused
any transaction writing two segments to one table, a zone-pruned delete that made a reinserted
key fail every keyed range read, a compaction refused by a background index build, and an
IndexedDB key cache that let two tabs write one primary key twice — each now pinned in
simulator-regressions.test.ts. The last one only shows with a separate adapter instance per
connection, which is why the Node driver opens one per connection for IndexedDB and OPFS. Its
first real-browser runs then added two more: WebKit keeping a terminated worker's unfinished
IndexedDB transaction alive, which wedged every tab (now bounded by StorageUnresponsiveError,
which an open reports too rather than calling the silent database corrupt), and a crashed tab's
pending call waiting out the client's silence deadline long enough for another tab's idle
transaction rollback to fire. The
nightly Firefox OPFS crash campaign later found an OPFS database that would not reopen after a
crash, because its checkpoint held a staged index build for an index a stale writer had just
marked invalid; a fold that reported a failure when another tab dropped its table just before
the fold began; and background collection reporting a crashed leader tab's lost step, which its
own retry reconciles. Each is pinned in Node: checkpoint-interruption.test.ts,
simulator-regressions.test.ts, and the collection and compaction controller tests. Longer Node
soaks (1,500 steps over six connections) later found cursors, DELETE, spilling queries, and
reads inside a transaction seeing rows outside an exact index selection at stale values, so a
DELETE removed a row its WHERE did not match. The first rekeying soaks found a connection losing a key forward once another tab
collected the manifest that wrote it, retired keys not followed under OR and NOT, and a
self-referencing table's references moved twice by a shift or swap. The first constraint and
schema-change soaks found a statement giving two rows one UNIQUE value refused with the error a
failed index build raises instead of UniqueConstraintError, a negative constant DEFAULT that
neither filled the rows an ADD COLUMN found nor allowed NOT NULL, DROP COLUMN refused on any
table another table references, and two OPFS databases that would not reopen: one after
DROP INDEX of a UNIQUE index, whose finished build record outlived it, and one after a commit
invalidated a UNIQUE index's postings, which the checkpoint loader wrongly required to be
ready.
live-differential.test.ts holds live queries to a fresh execution. A fast-check property runs
keyed and predicate writes, upserts, rekeys, transactions that commit or roll back, writes from a
second connection, compaction, collection, and an index build. It runs in process with
incremental maintenance on and off, and across a worker boundary. Set MINNOW_SEED and
MINNOW_LIVE_RUNS to explore further. It found a self-join patched as if only its base rows
changed, and a live query on a retired key that missed a row written at the key it forwards to.
Comparing only the latest result misses a delivery that is wrong and then repaired by the next
one, and it never sees the patch stream a worker-hosted subscriber rebuilds its rows from. So
each statement has two subscribers, checked by testing/live-publication.ts. One records every
onChange in a ledger. The ledger holds each delivery to the LiveQueryDelivery contract: only
the first is initial, the manifest version never goes back, and every retained entry is -1
or points at a distinct row of the previous delivery with the same values. The other subscriber rebuilds
its rows from subscribePatches alone. It refuses a patch before any reset, and changed rows
that do not fill exactly the -1 positions. After each write, the ledger's rows, the rebuilt
rows, and the fresh query must agree. live-oracle.test.ts applies the same two checks to its
wider shapes. Before these checks existed, a retained map that kept a changed row passed both
oracles, and so did a worker that dropped the changed row at position 0. Both are now caught.
live-publication.test.ts gives each law a wrong delivery it must reject.
Correct rows do not prove the work was incremental. live-work-bounds.test.ts runs the same
five commits against each maintained shape at 1,000 and at 50,000 rows. Each run must report the
same work: delta queries, aggregate groups evaluated, groups put back in order, and patched
deliveries. Wall time is never measured. Before this check existed, every commit to a grouped
query evaluated and sorted all of its groups. So a maintained GROUP BY over 100,000 groups cost
as much as running the statement again, about 100 ms, while every row stayed correct.
live-differential also includes grouped shapes with one group per key, so its commits reach the
path that moves a few groups' rows. It declares reach for both moving and rebuilding.
These checks have limits. The fresh query is Minnow's own engine. The SQLite and PGlite diffs are what hold that engine to an outside answer. The React and Kysely bindings consume deliveries above this layer and are not driven by these generated histories.
Background maintenance, size, and memory
auto-maintenance.test.ts pins what autoCompact and autoCollect guarantee, as bounds rather
than timings: a burst of writes folds back down and, a quiet minute later, collects to a store no
bigger than twice the data; repeated bursts settle to the same place instead of each leaving a
residue; versions from a moment ago stay readable and old ones are pruned; the switches off do
nothing; the buffer pool stays inside its budget under many distinct queries.
The immediate post-burst history bound includes both the collector's 64-version retention window
and up to 63 commits before its next scheduled pass. collection-controller.test.ts controls the
clock to prove that shorter tails are collected after the idle minute. The post-minute space and
history bounds remain separate from that scheduling allowance.
Background-fold waits require both the expected segment layout and no active job, because
planning starts before a durable job record exists.
The idle-fold fixture stays below the idle threshold until its final atomic write, so a pause
between earlier commits cannot fold the burst early and leave a legitimate small tail.
automatic-compaction-fit.test.ts holds automatic folds to the same standard on tables whose
folds do not fit the default memory budget as planned: a wide table refreshed wholesale keeps
folding inside the budget, a fold whose distinct keys outgrow it is cut, the smallest fold gets
the memory it needs, and a refresh written in an unrelated order folds with a job record a few
kilobytes long. A fold resumed by another engine recomputes its replay, and one whose replay no
longer matches its plan is abandoned unwritten. A single delta as large as its table folds with
no further write, including a lone one over already-folded partitions. Each case fails with its
part of the fix removed.
delta-merge.test.ts checks delta merges against a shadow model on memory, IndexedDB, and OPFS:
the resolver against a row-by-row replay over two hundred random runs, the partitions left
untouched and the merged deltas under the run's order, a fault injected at every storage call
the merge step makes (each recovered by another connection), two connections stepping the same
merge, a plan whose sources do not reproduce its checksum refused unwritten, a merge at the
level-zero ceiling it relieves, a quiet table folded after a burst but not after a trickle, and a
live query whose window spans a merge answered without a query. compaction-controller.test.ts
carries a quiet table's fold through a busy run, a failure, and a decline.
large-delta-reads.test.ts refreshes 400,000- and 1,000,000-row tables with one full-table
upsert under default settings, on memory, OPFS, and IndexedDB stores, and checks exact results
at once — while the fold runs — and after it; it also folds such a table with a compactTable
that names no budget. overlay-fallback.test.ts forces the replay's two bounded paths — patches
replayed per range of rows, and touched keys replayed in hash partitions — through projections,
aggregates, ordering, index-selected rows, layered partial updates, deletes, and reads of older
versions, and requires the in-memory replay's exact rows in its exact order; one case reaches
both paths through a real small budget. delta-scan.test.ts runs its SQLite-checked mutation
script through both paths as well.
executor-agg-handoff.test.ts forces its first aggregate's variable-state growth to
contend with a pinned native holder. It pins at the actual hash-growth boundary,
after reader/sizing credit can retire, and starts the other executions at the
first handoff before its restore resumes. A fitting query is allowed to finish
without a handoff; this campaign deliberately establishes pressure before requiring one.
The resident follower still must finish without requesting a restore phase.
The generator keeps its scalar, skewed and many-group shapes, two or three executions, parameter sizes, filters, resident followers and both cancellation points. An additional schedule releases an 8 MiB sizing reservation when the scan opens. Both that schedule and the original schedule must reach the same pressure, restoration, PostgreSQL-result and zero-credit checks. All original examples, seeds, six generated histories per seed, 8,192 source rows, memory caps and deadlines remain. Fast-check includes examples in its run budget, so the budget increases from 14 to 17 to add three examples while preserving all six generated histories. The growth observer is restored and checked alongside the existing suspension/restore observers, including abandoned histories.
event-loop-stalls.test.ts runs a 1 ms watchdog through the workloads that once held every
other query for hundreds of milliseconds or minutes — a fold of reordered wide upserts, live
aggregates patched after large commits, scans over upsert-heavy tables, secondary-index builds
and their first lookups, a full-text index build, and a 600,000-row write and upsert on OPFS —
and fails if any stretch the watchdog
cannot run exceeds 250 ms (750 ms in CI). Each case fails against the code before 0.13.0.
checkpoint-slicing.test.ts pins that a multi-slice OPFS checkpoint gives the event loop turns
between its slot writes, publishes exactly the bytes a one-step checkpoint would, and survives
power loss or a refused write at every one of its file operations, with the refused checkpoint
retried by later writes; wire.test.ts checks the sliced encoder against the one-step encoder
byte for byte, and the sliced checkpoint parser against JSON.parse, each with a property test
over arbitrary JSON-shaped states and, for the parser, malformed input it must refuse.
large-commit.test.ts pins on the memory and OPFS stores that a commit large enough to check its
keys in slices still refuses a conflicting key without changing anything, that its
ahead-encoded log frame replays after a crash, and that an index change of 70,000 postings —
more than one stored chunk — commits, replays from the OPFS log, and loads from a checkpoint.
wal.test.ts writes payloads that span continuation frames and checks that replay joins them,
treats pieces with nothing after them as an unwritten tail wherever the log stops, takes pieces
back when an append fails, and refuses a corrupt piece inside the acknowledged log.
follower-large-commit.test.ts commits 400,000 indexed rows from an OPFS follower — past the
message's structural limit — and checks that a re-sent large commit runs once under its first
delivery's identity. index-reads.test.ts pins that an OPFS index lookup answers while a large
commit holds the leader's queue, and that a chunk read failing partway runs again on the queue.
lease-lane.test.ts pins that OPFS reader leases run between the slices of a large commit and a
checkpoint, with every power-loss and torn-write boundary of such a checkpoint recovered.
unique-index-staged-build.test.ts pins, on the memory, IndexedDB, and OPFS stores, that
creating a UNIQUE index stages its keys in ordered chunks of at most 4,096 and never sends
them in one catalog update, enforces the index across a reopen, handles an empty table, and
releases staged keys when publication fails. index-capacity.test.ts builds a secondary index
over 600,000 distinct values and a full-text index over 450,000 documents, both of which the
chunk limit once refused, and pins that at most one chunk per block of rows covers a term, so a
lookup reads no more chunks than before.
npm run benchmark:stalls measures the real numbers for those shapes and a few more, during the
writes and during the maintenance that follows; -- --store opfs runs them over the native
OPFS store.
The heap itself is checked by the memory soak, which the unit suites cannot do honestly:
npm run soak:memory # node --expose-gc; four workloads, eight rounds each
npm run soak:memory -- --rounds 12 --workload writesEach workload — queries, writes with background maintenance, live query sets opened and closed, databases opened and closed over one store — runs in rounds with a forced collection and a heap reading after each. The assertion is a plateau: the last rounds may not sit more than a bounded margin above the early ones. The database runs with a small buffer pool so the pool fills during the warm-up rounds, which are excluded; a climb that continues past a full pool is a leak.
A leak is memory kept; a burst is memory allocated and dropped, which a page still pays for in
heap growth and collection time. npm run benchmark:live-wide measures the burst of one large
live query: 15,933 rows over 13 joins, 63 columns, 12 of them JSON_OBJECT columns, decoded
through Kysely with json: "parse". The database runs in a worker thread on the stock worker
host, and each thread samples its own allocations, collected objects included. It reports bytes
allocated per thread, how many times the result was delivered, and the time until rows are ready,
for a plain subscribe and for a Suspense load (refresh(), then a subscriber). The React suite
counts the same deliveries under real Suspense and StrictMode.
Concurrent writes
write-coordinator.test.ts covers the writer queue itself against a controlled lock manager:
arrival order, one pending lock request per context, prompt cancellation of a queued or
lock-waiting writer, one stall report per unchanging holder with no bypass, silence while
holders keep changing, and separate queues for separate databases.
It also refuses to invent a stalled holder from an empty or unavailable lock snapshot and
proves that writers behind the local queue do not inspect remote locks. The browser corpus
retains every console error's structured arguments in its report while still failing on errors.
write-contention.test.ts covers writers that do and do not take turns. Coordinated writers all
land; a store marked uncoordinated through the test seam (markStoreUncoordinatedForTests, the
stand-in for an older build in another tab) accepts only maxCommitRetries + 1 of a synchronized
IndexedDB burst, and that budget does not grow with concurrency. Rejected writes publish nothing
and acknowledged writes remain fully present. The same seam is what every test of the defensive
compare-and-swap path uses — a commit landing under an open scope or transaction, a compaction
publishing without a turn, an index becoming ready under a stale writer — so those paths stay
covered without a public optimistic mode.
write-scope-admission.test.ts loads 45 tables at concurrency 1, 6, and 12 through direct
engines and worker clients over memory, IndexedDB, and OPFS. With commit retries disabled, every
scope must run once and retain every row, and a shared counter read and rewritten by every scope
must see every value exactly once. Mixed batch and SQL writes, rollback, shutdown, a scope
cancelled through its signal, and the stall report for a callback that awaits another write on
the same database have separate checks. The native-browser companion loads 39,015 rows across
45 tables with 12 writers and automatic maintenance enabled, then reopens the store and verifies
counts and sums; a second case opens three tabs over one database, bursts scopes, batch writes,
SQL statements, and BEGIN transactions from all three while one of them adds a column and an
index, requires zero conflicts with zero retries, and then holds a scope open in one tab to prove
that another tab's write waits rather than fails and that closing the waiting tab lets go
without waiting for the holder. storage-probe.spec.ts drives the queue against real Web Lock
holders: a progressing queue is waited out without a report, a holder that never lets go is
reported once and never bypassed, and a waiter that gives up leaves at once. The interaction
simulator asserts zero lost commit races in Node and, for complete campaigns, across real tabs.
index-create-concurrency.test.ts races CREATE [UNIQUE] INDEX IF NOT EXISTS against another
connection's build on memory, IndexedDB, and OPFS: it must wait while that build runs, succeed
only once the index enforces, fail when that build finds a duplicate (leaving no index), create
the index itself when that build fails, and stop waiting when its own connection closes. Its
second half parks a build mid-write and then marks its connection gone, as a closed tab would
leave it: the index — UNIQUE or not, staged key set or postings, CREATE, a query's rebuild, or
a full-text build — must be finished by another connection within seconds, and a live builder
must never lose its build to the queries and statements waiting on it.
index-takeover.spec.ts closes a real Chromium or WebKit tab in the middle of
CREATE UNIQUE INDEX over IndexedDB and OPFS, and requires the other tab's waiting
CREATE UNIQUE INDEX IF NOT EXISTS to finish within seconds with the index enforcing.
The fault sweep
packages/core/src/testing/fault-sweep.ts runs a fixed workload once without faults, then
interrupts every reached block-read, block-write, and transaction-commit boundary in turn.
fault-sweep.test.ts runs it in Node; fault-sweep.spec.ts runs the same campaign in dedicated
workers over native IndexedDB and OPFS in Chromium, Firefox, and WebKit.
Recovery must match an exact complete table state. Every acknowledged statement must survive; only the interrupted statement may be wholly present or wholly absent. Partial batches, lost acknowledged rows, duplicate keys, changed values, and an unreadable database all fail. A failed read cannot change the allowed durable state. The uninterrupted baseline must also survive a cold adapter reopen with every expected row.
The campaign records each injected error and rejects unrelated engine errors instead of swallowing them. Every fault point must be reached, and every scheduled injection must fire. Automatic maintenance is disabled here so the operation counts are deterministic; separate maintenance and crash suites test background work and abrupt worker termination. Each trial closes the engine and adapter, reopens the database, and removes its browser storage afterwards.
Benchmark workload model
The benchmarks page keeps four workload classes apart. They are never combined into one score:
| Workload | Read measurement | Write measurement |
|---|---|---|
| OLTP | Selective key, small-set, and bounded-range latency | Point and small-batch inserts, updates, and upserts (1–100 rows) |
| OLAP | Scan, join, window, and aggregate execution | Bulk ingestion and mutation throughput (10,000–100,000 rows) |
A read workload keeps every query visible rather than collapsing to one figure: each cell is the median of the timed windows for that query, after one untimed warm-up. Writes keep every operation and batch size visible the same way. Nothing is reported unless it was verified — every read must match an independent JavaScript oracle and every write is read back and compared row for row, and a query an engine got wrong or could not run prints a dash instead of a timing. Statement deallocation and session cleanup are awaited outside the timing windows. An unexpected cleanup failure invalidates the measurement or suite; a paired execution and cleanup failure retains both original errors.
Two further measurements cover what an application pays above the engine, so a regression in the worker client or the live-query layer shows on the page instead of hiding behind engine numbers:
- The cached columns (
Minnow (cached),Minnow (OPFS, cached)) repeat each statement with the default result memo enabled. They measure repeat-query caching separately from execution. The read table times engine calls directly inside the benchmark worker; it does not show separate client RPC columns. - The live-query suite registers 1 to 100 subscriptions through that client, commits one row,
and times the commit until the last affected subscription's
onChangehas fired with its rows in hand. One case keeps 99 of 100 subscriptions on a table the commit never touches, which measures the cost of ruling them out. Every affected subscription must fire exactly once per commit and end on the row count the commits imply, and no other may fire at all. The suite owns its tables and never writes the dataset's, so the read oracles stay true after it. Only Minnow takes part in this harness. PGlite has a live-query extension, but this harness has no driver for it; an unmeasured driver is reported as unsupported here, not as a missing engine capability.
There is nothing to publish or regenerate. The benchmarks page has no checked-in
numbers: it builds every engine and runs the suites in the visitor's browser, on the engines,
suites, and dataset size they pick, and explains the measurement methodology, storage differences,
caching, and memory caveats as it reports them. The suites themselves live in apps/site/bench
and the page that drives them in apps/site/app/benchmarks.
To iterate on the harness, run the unit tests (npm test) for the generator, answer checkers, and
suite rules, then npm run test:browser:site to run a suite in real browsers. To try a change by
hand, npm run site:dev and open /benchmarks.
Rebuild owner RETURNING settlement
Owner accounting tests distinguish receiving results from delivery settlement. Under R2/R11,
autocommit RETURNING waits for commit acknowledgement under its durability mode before rows
can flow; inside an explicit transaction rows can flow when the statement executes. The result grant stays charged
until every frame is released. A client query may resolve while its release message is still
batched or in transit. Execution.delivered is the settlement point: the stream has ended,
every frame is released, and the result grant is closed. Accounting assertions await this
completion, rather than an elapsed release-timer delay. The owner regression holds commit
acknowledgement and release at explicit barriers and varies microtask ordering around both.
Rebuild owner latency
The unexported rebuild core's owner protocol has a separate, cross-origin isolated runner. Run one engine at a time, with no other benchmark or build in flight:
MINNOW_R6_MODE=observe npm run test:browser:next-owner -- next-owner-latency.spec.ts --project=chromium --repeat-each=5 --workers=1Repeat for firefox and webkit, recording host load alongside the results. Shared Ubuntu
runners are an observation lane: they report, but do not judge, warm cross-tab point-read p50 targets of 250, 400 and 600 microseconds respectively, and a loaded
p95 target of 5 milliseconds. The fixture uses real lowering and the owner protocol, with a
synthetic executor and write path; it does not establish the real executor's lookup cost.
Warm prepared reads bypass plan-cache lookup. The report also includes bare broker round trips,
lock-call counts and a clone/transfer probe. The probe sends buffers to the broker, which replies
without echoing those buffers, so it measures one payload direction.
The Node component split in owner-point-read.bench.test.ts always checks finite measurements,
sample counts, synchronous execution, frame release and warm plan-cache reuse. The nightly owner
observation job runs it with MINNOW_R6_MODE=observe, then runs the browser observations. It
reports the server-alone 10-microsecond and owner-share 50-microsecond targets without judging
them. Browser correctness, finite-value, sample-count, isolation and lock invariants still fail
the job. Raw metrics and the unchanged absolute targets are uploaded together.
R6 is NOT ACCEPTED until a passing quiet-host record is committed. The scheduled
acceptance job runs only when the repository variable R6_QUIET_RUNNER names a qualified quiet
runner. Without that configuration it is skipped; it never fails just to report missing acceptance.
The observation job still enforces all its invariants and can pass independently. A green
observation or a skipped acceptance job never grants acceptance.
npm run version:check refuses any published package on major 1 or later, including prereleases,
unless packages/core/r6-acceptance.json is valid and its exact bytes are in Git HEAD.
An untracked, staged-only or edited record cannot unblock a release. The publisher makes the
same check before consulting npm. The record names the qualified runner, UTC date, measured
commit, host-load qualification, all three browsers and their p50 and loaded p95 values. It records
the worst of the five run-level quantiles for each browser; all must meet the unchanged targets.
The 0.x release line does not require this future acceptance record.
Absolute targets are judged only after independent host and CPU-load qualification, never qualification by the latency result or selection of a lucky run. Keep all histories. A missing, busy or unqualified runner refuses acceptance. Browser sample intervals are rounded to the nearest nanosecond before reporting microseconds, so an exact clock tick cannot cross a target through binary subtraction alone; the targets themselves are unchanged.
An isolated scheduling experiment helps distinguish browser task queues from SQL and wire costs:
MINNOW_OWNER_SCHEDULING_BENCH=1 npm run test:browser:next-owner -- next-owner-scheduling.spec.ts --project=chromium --workers=1It compares the fixture's fresh-channel yields with the production task scheduler, then compares 4, 1 and 0.5 millisecond slices using that scheduler. Five rounds rotate variant order. Each variant completes the same integer kernel and checksum; the attachment reports echo latency, work completion time and yield count, with host CPU count and load at the start and end. Slice elapsed time includes host preemption and is not OS CPU time. The echo client and worker belong to one page: this isolates task scheduling rather than measuring the cross-tab protocol. These experiments do not change the production quantum or replace the latency gate. Retain every round and inspect throughput cost as well as latency before choosing a scheduling change.
Quiet-host R6 gate and CPU components
Once a quiet runner is independently qualified and configured, run all engines with one command:
MINNOW_R6_QUIET_RUNNER_ID=<approved-runner-id> npm run benchmark:owner:r6 -- --out /path/to/fresh-outputThe command refuses an absent configured runner ID and checks load1 <= 1 before starting, builds the core, waits up to ten minutes for
build load to decay, judges the Node component targets, then runs Chromium, Firefox and WebKit sequentially. Each engine runs the
latency lane five times with qualified absolute judging, then the five-round fixed-work sweep over
4, 1 and 0.5 ms quanta (including the original fixture's 4 ms control). It samples host load every
second and at command boundaries. Any measured load above 1, invalid load evidence or incomplete
run produces refused.json and raw logs, never report.json. It waits for its own children;
it does not kill processes. A complete quiet run writes report.json; a passing run also writes
acceptance.json. The qualified job uploads both and the raw evidence as r6-acceptance.
Review that evidence, copy acceptance.json to packages/core/r6-acceptance.json and commit it;
do not hand-write passing numbers. Re-run npm run version:check. Unmet targets return exit
1, refusal returns exit 2. The gate requires OS load averages (Linux/macOS).
Temporary output uses os.tmpdir(); set TMPDIR to your scratch directory on a constrained host.
For a private Linux WebKit installation, MINNOW_R6_WEBKIT_BROWSERS_PATH overrides the browser
path for WebKit only. The ordinary Playwright browser path still serves Chromium and Firefox.
The quantum tradeoff remains a candidate: decide it from quiet loaded p95 and fixed-work
completion times, not from a shorter workload or these shared-host observations.
For CPU work without cross-process waits:
npm run benchmark:owner:cpu
npm run benchmark:owner:cpu -- --baseline /path/to/frozen-frame-buffers.tsThis requires Node with process.threadCpuUsage() (22.19+). Five fresh-process rounds rotate
baseline/candidate order. It reports the p50 of amortized thread CPU per operation over 30
batches: 1,000 prepared reads or 10,000 isolated frame validations. A 200-column case checks wide
frames as well. Setup and warmup are excluded; V8 sampled-stack attribution is a separate pass.
The profile identifies composition binding, compiled-plan-cache hits, write probes, frame work,
owner dispatch and fixture execution. Zero samples mean below sampling resolution, not zero CPU.
Stable-catalog prepared reads bypass the SQL-text plan cache. Native port serialization, client
work, real executor binding and real indexed lookups are outside this component bench.
Reports and the CPU profile are retained under os.tmpdir(). Neither CPU p50 nor sampled stacks
are a substitute for cross-tab R6 acceptance.
Performance after repeated writes
Most gate shapes read a table as it was loaded. The settled-* shapes read it as it is after a
day of use: the same rows with a thousand point updates applied and the background maintenance
allowed to finish, timed against SQLite and PGlite with the same updates. Their costs do not move
with history, so the ratio is the engine's own cost of having been written to — a read that
slows down as a table is used, or maintenance that stops keeping up, moves one of these numbers.
settle-after-updates times the updates and the settle itself, once, so a fold or a collection
pass that grows expensive shows up too. Its waiter checks active jobs first, reads segment
visibility only between jobs, and measures the full storage footprint only after the table is no
longer due for a fold. This keeps the observer from competing with the maintenance it times; the
sample ends only after ten consecutive 50ms observations see no job and the same footprint.
The report separates the time to the first confirmed-stable observation from the following
confirmation delay. Observation resolution is 50ms. The gate and comparison row keep the full
elapsed time, including confirmation; SQLite and PGlite time their updates without this window.
Wide-table writes
The wide-* shapes write the way an app syncing server data does: a 101-column table of text,
numbers, booleans, and timestamps, keyed by a number, with a _synced flag. wide-guarded-upsert
lands 2,000-row sync batches, half new rows, through upsertBatch with
conflictWhere: _synced = true, and some rows it meets are local edits the guard must leave
alone. wide-insert-row, wide-upsert-row, wide-update-row (a keyed SQL UPDATE of three
columns), and wide-delete-row are the app's own single-row edits. Unlike the historical shapes,
SQLite and PGlite hold this table with a real primary key, and SQLite runs prepared statements
over arguments built before timing, so these ratios compare like with like. The table lives in a
database of its own, so its writes do not change what the other shapes read. Every engine runs the
same sequence, and a summary of the table is compared with SQLite's after each shape.
Update the performance-gate baseline
After an intentional executor change, inspect the performance-gate output before updating its thresholds:
npm run benchmark:gate -- --updateTreat that update as a code change: explain it in review and run the gate again without --update.
Browser performance lane
npm run benchmark:browser measures Minnow in real Chromium against the engines an application
would otherwise ship: SQLite-Wasm for point reads and writes, and single-thread DuckDB-Wasm for
wide and large analytics. Like the Node gate, it judges ratios against a competitor measured in the
same run, never wall-clock budgets. These numbers are not published anywhere; the
benchmarks page is the only place results are shown, and it runs in the visitor's
browser.
npx playwright install chromium # once
npm run benchmark:browser # point suite, then W1M, W500 and S1
npm run benchmark:browser -- --suite=point
npm run benchmark:browser -- --suite=analytics --scale=W1M --only=scan_proj3_agg,agg_numeric_sum
npm run benchmark:browser -- --suite=analytics --scale=large # W5M and S5, hours| Option | Effect |
|---|---|
--suite=point|analytics|all | Which suite to run; default all |
--scale=default|large|<ids> | Analytics datasets: default is W1M, W500 and S1; large is W5M and S5 |
--only=<cells> | Comma-separated cell ids (W1M/scan_proj3_agg), query ids (scan_proj3_agg), or point cells |
--with-sqlite | Adds SQLite-Wasm to the analytics suite, on W1M and S1 only |
--warm=<n> | Warm runs per cell; at least 5 for a baseline update |
--timeout-ms=<ms> | Per-run deadline in the page; the engine's worker is terminated when it passes |
--reload | Loads every dataset again instead of reusing the cached copy |
--update | Recalibrates this runtime profile in packages/core/browser-perf-baseline.json |
--out=<dir> | Where cells.jsonl, summary.txt and lane.log go |
--no-confirm | Skips the confirmation re-run of flagged cells |
The suites.
- Point, against SQLite-Wasm on the OPFS SAH-pool VFS: a 1M-row keyed load; strict single inserts; strict concurrent inserts from 8, 32 and 64 callers (Minnow spreads them over up to eight worker connections in one page, so they meet one leader; SQLite's pool allows one worker, which runs them in turn); relaxed parameterized inserts; warm primary-key reads on an INTEGER key (bound and literal) and a UUID text key; the first read after a reopen at 1M rows; a read from a second tab; and reads on a compacted table before and after 2,000 uncompacted updates. Reads are timed in batches of 200, because a page without cross-origin isolation has a coarse clock.
- Analytics, against DuckDB-Wasm 1.32.0: the wide table (200 columns at 1M rows, 500 columns
at 250k rows) and the commerce star schema from
apps/site/bench, at the query families of scans, wide aggregation, joins, windows and sorts, plus three spill shapes under a 64 MiB and a 256 MiB cap. W5M and S5 (5M rows) are opt-in.
Storage microbench. The nightly run also records npm run benchmark:storage: the rebuild
core's storage layer (packages/core/src/next/storage, not yet shipped) on OPFS and on IndexedDB in
the same profile. It times a cached peek and a leased cache hit, a cold read of 32 pages after
reopening (it must be one coalesced store read on both backends, and one file read on OPFS; on
IndexedDB it also counts the get requests), a small write plus publish, and a log append
with and without a flush. The run prints one STORAGE_MICROBENCH JSON line, which the nightly
workflow saves as browser-perf-results/storage-microbench.json next to the lane's results. Nothing judges them yet, and the page is not cross-origin isolated, so
sub-millisecond numbers on Firefox are rounded to the millisecond.
Export diagnostics (rebuild, not yet shipped). npm run benchmark:export records the
page-stream half on Linux/Chromium OPFS: a wide 1,048,576-row, 200-column table read into reused
column buffers. MINNOW_EXPORT_SCAN_COMPARE=1 adds the production executor and result path:
createExecutor → ResultSink → ResultChannel → the owner transfer policy → real MessagePort
credits. This mode:"scan" number is the Gate A export result. Preparation and fixture snapshot
and group descriptors replace SQL lowering, catalog and group-root loading; the receiver consumes
typed frames rather than JS row objects. The executor owns admission, scan options and result
framing without bench overrides. Its current compiled scan uses the default per-batch read policy;
the diagnostic 64 MiB scan window is not forced onto it. The timed region includes execution
admission, scanning, framing, transfers and complete credit drain, and excludes fixture preparation.
Page-stream and real-executor results must be reported separately.
Historical ownership, batch, IO, range, shape-transport and frame-copy comparison flags use the
explicit mode:"scan-adapter" diagnostic and its old stand-in frame assembler. Those numbers
are excluded from Gate A. They remain available to reproduce earlier component experiments.
next-executor-export generated histories verify production executor preparation, source-value
equality through real transfers, task-delayed cumulative credits, storage survival and zero
remaining execution charges across multiple groups, sparse NULLs and >64 KiB values.
The optional page-stream hot-set audit selects the actual PageCache even when the extent space also registers retained metadata caches. It requires the protected hot set to survive and the probationary scanned pages to be evicted; the scan comparison disables this separate audit.
Both export modes record rows/s, worker CPU and sampled renderer RSS. The scan comparison brackets
CPU after setup, checks frame delivery and release charges, and defaults to five interleaved
cold/warm attempts per mode. MINNOW_EXPORT_SCAN_COLD_ONLY=1 keeps five cold attempts of each.
MINNOW_EXPORT_ROWS requests a size, rounded up to whole groups of 65,536 rows; the report
records the actual exported rows. MINNOW_EXPORT_DISTINCT selects how many groups are
generated independently, with the rest copied to distinct file offsets. Warm means at least 98%
file residency at the start, not a promise it stays resident. MINNOW_EXPORT_VARIANCE=1 records
nine cold/warm pairs with per-pass phases, GC pauses, read shapes, residency, and host pressure.
The nightly workflow keeps the page diagnostic in export-bench.json and the cold comparison in
export-scan-bench.json, under browser-perf-results/. Neither enforces a performance threshold.
On Ubuntu 24.04, these diagnostics require util-linux-extra for fincore; the nightly workflow
installs it explicitly before running the lane.
scripts/executor-export-bench.mts isolates the production executor/result path against the
historical adapter over the same memory-backed page cache, with per-batch reads for both and
real in-process MessagePort transfers. It records five interleaved fresh-process CPU/wall rounds,
excluding fixture construction, preparation, warmup and GC. It measures worker work, not OPFS
latency or renderer RSS; the adapter comparison is diagnostic, not an alternative Gate A result.
MINNOW_EXPORT_SCAN_PROFILE=1 profiles only the dedicated scan worker, cold and warm, after
setup. Its export-cpu-N attachments can be summarized with scripts/scan-profile.mts:
top self-time functions and exclusive buckets for scan, descriptors, vectors, production frame
assembly, result accounting and transport. ColumnStore helpers inherit their nearest classified
caller, so ResultSink copies are counted as production framing rather than pipeline overhead;
stores used by other operators are not automatically called frames. Executor entry/admission,
memory accounting and benchmark delivery/instrumentation have separate buckets. CDP sample durations include native waits and descheduling;
active sample shares estimate hotspots, not exact CPU seconds per bucket. The report keeps
native reads, GC and idle samples separate and records the worker's actual thread CPU bracket.
MINNOW_EXPORT_SCAN_CORE_PROFILE=1 profiles the scan side alone over the same OPFS table.
It drives the real table scan and pipeline into a synchronous borrowed-batch consumer,
without the frame adapter, result channel, ownership copies, or client transport. The consumer
records batch/column counts, dictionary/validity/offset shapes, and an endpoint fingerprint;
it does not decode text or check every value. Its rows/s is a scan diagnostic, not export
throughput or a Gate A result. Cold/warm residency and setup-excluded CPU rules stay the same.
scripts/scan-shape-bench.mts --planning isolates descriptor sizing and reservation over
real loaded pages; without --planning it runs the whole memory-backed scan. Both compare
with 74c79c9b in five interleaved fresh-process rounds, excluding setup and one warmup,
and record CPU, wall time and host load. The comparison requires that Git object.
MINNOW_EXPORT_SCAN_SHAPE_COMPARE=1 npm run benchmark:export compares the same change
in five cold, interleaved OPFS scan-only pairs. It uses explicit 64 MiB windows and the
same borrowed-batch consumer; it measures neither frame assembly nor export transport.
Add MINNOW_EXPORT_SCAN_SHAPE_TRANSPORT=1 to compare the whole stand-in adapter and
real owner transfer path instead. Both modes assert which three module versions reached
the worker. This historical transport comparison uses the old adapter, not the production
ResultSink, and is explicitly excluded from Gate A.
Ordinary executor scans reuse the write-path owner's governor-registered group-root cache.
A cold miss validates the complete immutable root, including every unselected column and all
canonical checks. The optional compact entry owns its encoded bytes and navigation indexes;
subsequent queries select metadata directly from those validated offsets. Complete-root APIs
still expose every column. Validation authority is scoped to the exact owner and full blob
identity, including both containing-extent fields, blob offset, length and checksum.
Both construction and active borrowing are charged before allocation. Idle entries are charged
and evictable; selected facts use the existing query-local cache through sizing and execution.
Pressure can evict either cache or decline compact construction/borrowing, falling back to the
ordinary complete decoder. Optional preparation scratch does not increase execution's native
minimum. Explicit non-retaining export bypasses owner admission and promotion. Query cleanup
drains pending readers before releasing its facts; owner close clears roots and removes the
cache binding. Visibility, deletion masks and snapshot-specific hints are never shared there.
next/page/directory-native-budget.test.ts measures a fresh reader's complete page-load peak,
then repeats the load through a parsed-directory hit at that same fixed budget. Generated wide
floats and sparse NULLs check that optional metadata does not consume the admitted page
workspace. Set MINNOW_NATIVE_DIRECTORY_RUNTIME_URL to a frozen runtime's root file URL
(with a trailing slash) to replay the same law against a historical implementation. Every
history runs against its parsed cache; versions with query-local preparation use that cache.
next/testing/validated-root.test.ts checks selective and complete equality, unselected corruption,
full identity, byte ownership, concurrent and cancelled borrowers, refusal and zero charges.
next/testing/root-reuse.test.ts checks real executor source equality and validation reuse across
queries; next/testing/query-root-ownership.test.ts covers query facts, eviction and cancellation.
scripts/query-root-component.mts isolates a two-pass sizing/scan root handoff over synthetic
wide metadata. scripts/query-root-bench.mts --baseline <frozen-root> --candidate <frozen-root>
compares the real three-column executor scan from complete, separately built cores. Both use
B7's shared independent-process runner: every arm in every one of nine AB/BA pairs starts a
fresh process, and build start order alternates too. One process closes before the next starts.
The whole scan restores the same immutable native file image before opening the ordinary core;
file hashes, lengths and retained allocation capacities are checked. Image creation, restore,
verification and IPC are outside CPU timing. Each sample warms ten complete queries, then
measures ten complete lifetimes under one all-thread process CPU clock, including natural GC.
Raw totals and exact completed-query/row volumes are recorded before per-query normalization.
Run an identical-build --aa control first. It must show neither a gain nor a regression by
the paired rule; A/B requires its matching --aa-report <results.json>. The control must match
the candidate revision, source hashes, row count, warmup/repeat policy and native image hash.
Use the capture run's input.json with --bundle in both whole-scan campaigns. Component runs
use the same protocol without a native image. --smoke is for small lifecycle tests only;
its timing cannot qualify an A/B campaign. Earlier persistent-worker results are superseded
because alternating execution order did not balance worker identity. These native loaded-host
diagnostics are separate from quiet-host Gate A and the owner/MessagePort export transport.
A campaign can explicitly use --aa-bias-ms <ms> in both controls and comparisons when a
recorded control bias must be carried into the decision. The raw A/A decision remains visible;
A/B then requires a paired CPU gain greater than the larger of that floor and its matching
A/A median magnitude, plus paired IQR, with the usual favourable-pair count. The report's
biasAdjusted decision is authoritative for that mode. A zero floor keeps the strict neutral
control policy. Linux reports bind the current CPU affinity; use the same taskset -c mask
for A/A and A/B. These constrained native comparisons are separate from quiet-host acceptance.
For parser changes, add --decode-only to the component command in both A/A and A/B.
Both arms then parse complete roots without query or parsed-descriptor caches; every synthetic
group uses distinct extent addresses. The default component mode still measures query-cache handoff.
For cross-query validated-root changes use --validated-roots instead in both A/A and A/B:
both builds receive the same owner cache and use their query-local handoff; each observation
spans fresh query lifetimes while the owner remains open. The parent may ignore the newer
optional owner binding. This mode includes selected metadata materialization, not only cache lookup.
scripts/query-root-profile.mts --runtime <frozen-root> --bundle <input.json> captures a
setup-excluded V8 profile of the same three-column scan, followed by a separate counter pass
that records complete-root columns, chunk opens and decoded rows by column. Its sample shares
are diagnostic: they are not an exact allocation of all-thread CPU, and sampled wall time can
include host scheduling. GC remains a separate bucket. The extent-pair codec generator checks
full safe-integer offsets and lengths, including shared offsets with distinct lengths and
duplicate refusal after several such lengths; canonical byte and charge contracts stay unchanged.
Use --summarize <scan.cpuprofile> to reclassify a saved profile without running the query again.
The scan reuses verified header facts while the endpoint pages stay the same. Loading,
releasing or materializing a page invalidates those facts. Exact-range varlen byte sizes
are memoized separately; sparse selections are sized from their selected rows.
The reader charges its bounded scalar memo separately from the shared directory cache.
Generated source-value equality and residency histories cover this reuse in
next/exec/column-shape.test.ts and next/exec/shape-reuse.test.ts. Reference sizing sums
immutable source values independently of the reader's range and gather byte memos.
next/testing/column-shape-differential.test.ts checks real page-cache eviction and backend
reload while the extent space also registers retained metadata caches. It also checks three
same-layout groups through one target, all-valid/sparse/all-null masks, empty selections,
values larger than 64 KiB stored out of line, gzip, and actual dictionary code widths 0/1/2.
Declared reach requires these states. Four-byte dictionary codes are outside this generated
writer campaign: the writer limits groups to 65,536 rows. A restored stale-range-length mutant
must fail the independent size comparison, even if its oversized buffer preserves decoded values.
The shape histories include 512-byte and 2 KiB raw pages. The generated
next/page/small-pages.test.ts also checks adaptive flushes for intervals, UUIDs
and 128-bit decimals when the raw buffer holds fewer than 64 rows. The density-based
row preference is capped by that buffer's capacity. The independent
next/page/small-page-representations.test.ts checks safe and wide int64 inputs,
safe/wide intervals, and safe/int64/int128 decimal coefficients with all-valid and sparse
null masks, in both flat and dictionary source form. It checks source equality after a
successful write/read before page-size assertions, so silent data loss cannot be hidden by
another column's throwing copy. The old rebuild writer could persist undetectably wrong
values at these small capacities; the internal rebuild README records the impact and thresholds.
This unreleased-format defect does not affect the shipped format or default raw page sizes.
scripts/frame-copy-bench.mts isolates frame ownership copies in five interleaved CPU/wall
rounds; MINNOW_EXPORT_FRAME_COPY_COMPARE=1 compares those policies through the whole cold scan.
scripts/scan-range-bench.mts isolates the scan's contiguous-prefix dispatch over real encoded
columns in memory. MINNOW_EXPORT_SCAN_RANGE_COMPARE=1 compares it against the parent gather
policy in five cold scan/transport rounds, with the frame adapter and owner policy held fixed.
Contiguous compact batches can use range APIs while the scan's gatherBatches diagnostic still
counts the compact-selection branch; selections with gaps continue to gather.
The scan export requests a charged, coalesced row window from the core scan (64 MiB by default).
MINNOW_EXPORT_SCAN_IO_COMPARE=1 compares this one-pass policy with cached per-batch reads;
scripts/scan-io-bench.mts isolates both over a fresh memory-backed page cache. Setup and warmup
GC are outside its CPU/wall timings. Direct TableScan callers opt in with
readWindowBytes; absent/zero keeps ordinary cached batch reads. The historical adapter bench
requests 64 MiB explicitly; the real executor uses its terminal full-scan default. Resident shared loads remain synchronous until a task yield is due. Filters and
deletions retain selective reads, and a refused window is released and reduced before falling
back to bounded batch loading. For an explicit terminal full-column exportStream(),
admission sizing and this fallback keep non-retaining reads even when the optional window is
disabled. Existing cached hits remain usable; misses are verified exact private copies charged
until lease release, without cache admission or pooling. Successful one-pass window reads keep
their coalesced slab geometry. Other plans retain their existing cache policy. This exception
belongs to the unreleased executor export, not the shipped exportSnapshotStream() format.
The window read loops, including dictionary/gzip loads and immediately resolved storage
continuations, check the scan/driver's shared R23.5 clock. Sorting and cached installation also
check that clock; only a genuine task yield restarts it. Missing pages are reserved before
those yields so a concurrent reader waits for the same work. The generated lifecycle campaign
is next/testing/scan-windows.test.ts; its virtual work ticks are scheduling evidence, not a
throughput measurement. A scan-owned abort signal reaches both readers and storage; cancel
stops new backend calls while already-started buffers remain charged until drained. Shared
loads omit closed readers' remaining jobs while finishing live readers. Different cancellation
signals load independently. Started rejections are observed immediately while preparation is
yielded, and still propagate after drain. Generated blocked-read histories verify those rules, fresh-signal
retry and zero final charges.
MINNOW_EXPORT_SCAN_BATCH_COMPARE=1 npm run benchmark:export compares 1, 2 and 3 MiB
decoded-byte targets in five interleaved cold rounds. This is a bench experiment: the core's
default target remains 1 MiB. Every variant keeps the 2,048-row maximum, borrowed vectors,
64 MiB read windows and real owner 4 MiB credits. Reports include the actual batch target,
frame count, largest batch/frame and peak outstanding credit bytes, and assert the requested
target reached the worker. scripts/scan-batch-bench.mts isolates the same target choices over
a memory-backed cache with real query/result grants and in-process structured-clone transfers;
it excludes MessagePort IPC. Setup and warmup GC are outside CPU/wall timings. Both experiments
keep the labelled bench frame builder and current owner wire policy. If a foreground command
hits its time limit, MINNOW_EXPORT_SCAN_BATCH_COMPLETED accepts only an exact comma-separated
prefix of completed round:targetMiB cases (for example 0:1,0:2,0:3). The next command runs
only the remaining cases and records the prefix. Combine both logs and keep all five rounds;
a continuation's report alone is a partial campaign, not a five-round comparison.
The rebuild's opt-in MINNOW_EXPORT_SCAN_OWNED_COMPARE=1 npm run benchmark:export compares
borrowed scan output copied into frames with dedicated output decoded into transferable
buffers while retaining dictionary codes. It uses the same labelled bench adapter, real result credits and owner transfer policy.
Dedicated buffers are allocated in the result grant and stay charged until client credit.
The component benchmark is npx vite-node scripts/scan-owned-bench.mts: it includes allocations,
the real governor, frame accounting and real in-process transfers with four frames held, excluding MessagePort IPC.
--profile runs one diagnostic pass per variant, not a performance comparison. Both record CPU and wall
time; the browser also records absolute renderer RSS and charged-memory snapshots. Charged
memory is not physical RSS, and independent category peaks must not be added. Dictionary deltas
and capped text fallback still need ownership copies. The component benchmark also records
an all-flat diagnostic, which changes text policy and may change wire bytes and frame counts.
Storage kill campaign. The nightly run also runs npm run test:storage-kills: the rebuild
core's storage in Chromium, on OPFS and on IndexedDB, killed 1,000 times each at seeded
storage-request checkpoints while a worker builds and publishes extents, retires and reclaims them, appends, flushes,
truncates and resets its log, and spills. After every kill a new worker reopens the store and
checks that the root is the last acknowledged one (or the one a publish in flight was writing,
every blob's coordinates and checksum included), that every acknowledged log byte reads back,
and that the free-space audit is exact, then carries on. Any other outcome fails the run, and so
does any failure the workload reports while it runs. Each kill is classed by what the worker
posted before it died: before a step's storage work began, inside it (a platform request, such as
an IndexedDB transaction, was open), in its window (begun, but no request open), or after it
returned. The worker numbers its messages and atomically claims each number in shared memory
before posting; the page reads that counter just before the kill; the page then waits for every message up to that count, so no
acknowledgement or failure posted before that read is missed (the test page is cross-origin
isolated for this). If a kill interrupts a claim before the post, the barrier deadline fails
the campaign rather than passing with a missing message; the operation has an unknown outcome.
The campaigns avoid that interruption window: a shared-memory gate parks the worker only after
its request marker is fully posted. The page waits for the parked flag, drains the entire claimed prefix while the worker cannot
post or resume JavaScript, then terminates it without resuming it. It never treats a missing claim as an acknowledgement.
Messages claimed after the read are an unobserved tail: recovery accepts their operations as
pending, whether they completed or not. The
same campaign runs 50 kills per store in every browser lane. It declares reach: on IndexedDB,
kills must land inside writes, publishes, reclaims, log flushes, truncations and spills; OPFS's
storage calls are synchronous, so a kill never stops one halfway: there kills must land at each
step's edges, and the simulated power-loss sweeps cover what happens inside a call. A concurrent mode runs the workload as lanes that operate
at once (two writers, a reader holding a pin, the log, spill, reclaim). A seeded delay arms its
next native-request gate; successive kills target publish, log, spill and data requests, with
at least two operation windows open on IndexedDB. There those kills must land with a transaction of each kind open while
several operations are under way, and a Node sweep (chaos-crash.test.ts) loses power under the
same interleaved workload over the simulated stores, counting the storage calls that had run and
not yet returned. It
prints one STORAGE_KILLS JSON line per store with the kill and phase table, which the nightly
workflow saves as browser-perf-results/storage-kills.jsonl. A failure names its seed: set
MINNOW_SEED to replay the same plan of kills. Serial terminate kills park at a real request in
the selected step, rather than racing a short request against a page timer. A buffered IDB write
in that selected step stays pending until its scheduled native batch issues; batching remains
enabled. No-op occurrences get no credit and the gate advances to the next matching step under
the original deadline. Page-close kills retain their separately observed boundary. That boundary
includes every acknowledgement received through its observation barrier, including those received
after the kill was armed. The controller regression holds new intents and waits for the active
publish's completion markers before taking its boundary. It compares the whole acknowledged
state, allowing more than one root since recovery; elapsed time does not determine the count.
The IDB gate runs in a microtask after the transaction body has issued its initial requests,
before the transaction-end callback. OPFS parks before the synchronous call and reaches an edge;
it does not interrupt the call. These gates do not establish a particular physical disk-write
interruption point; the simulated power-loss sweeps supply that coverage. Neither reach minima,
state lists nor kill counts are reduced. MINNOW_STORAGE_CPU_THROTTLE=4 applies Chromium CDP
Emulation.setCPUThrottlingRate to the controller page, including replacement pages, and records
the rate in each report. It exercises delayed controller scheduling, not a calibrated 4× disk or
worker slowdown. The controller and gate regressions also exercise short requests and delayed
message delivery directly.
The worker gate uses 100 ms futex sleeps so the VM can process worker termination between wakes. Every wake keeps the worker parked; it does not advance the storage call or change the kill point. This avoids an indefinite wait retaining WebKit's owner during teardown.
What each cell records (one JSON line per engine per cell): the warm median and p95 over at
least five runs; the cold first run in a fresh worker after reopening the database; renderer RSS
after open; peak renderer RSS (/proc/<pid>/status VmHWM, reset with clear_refs before the
cell); renderer CPU time across all threads (/proc/<pid>/stat); the result hash; and, when the
cell fails, its failure class and message. Memory and CPU need Linux and are marked unavailable
elsewhere.
Rules the lane enforces. Each of these was once a wrong measurement:
- The browser profile is a persistent one (
launchPersistentContext); an ephemeral context keeps OPFS in memory. The lane refuses a profile on tmpfs or ramfs, and proves OPFS is on disk by writing a probe file and watching the profile grow. The profile lives inminnow-browser-perfunder the OS temporary directory (os.tmpdir(), which honoursTMPDIR); setMINNOW_BROWSER_PERF_DIRto choose a persistent directory on disk. - One fixed origin,
http://127.0.0.1:8791(MINNOW_BROWSER_PERF_PORT), so a database loaded in one run is the one later runs read. A port in use is an error. - Every write cell names its durability. SQLite's pragmas are read back after they are set and
recorded as they were: WAL only takes effect on the SAH pool with
locking_mode=EXCLUSIVE, so the strict set is EXCLUSIVE + WAL +synchronous=FULLand the relaxed set usessynchronous=NORMAL. - DuckDB-Wasm is pinned to exactly 1.32.0, the EH single-thread bundle, on an
opfs://database. The 1.33 development builds keepopfs://databases in memory without an error, and the threaded build cannot open OPFS at all, so neither is used. - Every result is canonicalized and hashed, order-sensitively when the ORDER BY is total, and
Minnow's hash is compared with the reference engine's. Results of up to 2,000 rows are kept, so a
hash difference is rechecked with a 1e-9 relative tolerance and reported as
toleranceorties(only near-equal float keys changed places) rather than as a wrong answer. - A failure is recorded, never fatal to the run. After any failed Minnow cell the lane reopens the store in a fresh page and counts the table; a store that will not reopen fails the run at once.
A whole default run takes about an hour on an 8-thread laptop, most of it the first loads.
Cached datasets. Loading W1M takes minutes per engine, so loaded databases stay in the
profile between runs. datasets.json in the lane directory keys each copy by the generator
version (GENERATOR_VERSION in scripts/browser-perf/catalogue.ts) and the engine's package
version, and every reuse first reopens the copy and checks its row count. Bump the generator version
when a generator, schema or load path changes. Delete the lane directory to reclaim the disk
space; the default scales take several gigabytes, the large ones tens.
The baseline. packages/core/browser-perf-baseline.json holds, per runtime profile (OS,
architecture, Chromium major, and a -ci suffix on a CI runner, so a shared runner and a
developer machine never judge each other), what each cell does today: completes with its ratio and a
regression threshold, or fails with its failure class. Many analytics cells fail at default
options today, and the baseline says so. The lane fails when:
- a Minnow store does not reopen after a failed cell;
- Minnow's result differs from the reference engine's;
- a cell that used to complete now fails, and fails again in a fresh browser;
- a ratio's whole sampled range (Minnow's fastest run against the reference's slowest) is past its threshold, and is again in a fresh browser;
- a cell has no baseline entry on this profile.
A cell that starts completing, or fails differently, is reported as a note. Thresholds pin the
current ratio with 1.5× to 3× headroom, sized from the spread of both engines' samples. The same
file carries the design targets for the 1.0 reset (Gates A–D and the point targets); the summary
prints each cell's progress toward its target and never fails on one. --update rewrites the
current profile's cells it ran and keeps every other profile and the targets. A profile marked
provisional was calibrated on a noisy or unrepresentative host; recalibrate it on the machine
that runs the lane, and treat that update as a code change. A new CI profile starts empty, so its
nightly run fails as uncalibrated until the hosted workflow is run with recalibrate=all and the
uploaded baseline file is committed. Use recalibrate=S_q7 for the approved NUMERIC ROUND
correction from 4e7b6a0c; its new measurements must come from the hosted runner. That cell's
calibration records the authority and workflow run URL.
Every browser baseline entry has a SHA-256 workload identity over the exact SQL (including reference dialects), dataset ID and scale, generator version and memory cap. Point cells include the executed SQL family, table definitions and row counts. A changed identity fails closed with “changed workload — recalibrate”, before loading data; it never receives a ratio verdict. The old S_q7 entries retain the identity of their original FLOAT query until hosted calibration; no local numbers or guessed thresholds replace them.
Refresh the download-size comparison
The benchmarks page opens with what a browser downloads to run each engine. It is measured from the installed packages rather than quoted, so refresh it whenever a dependency version or the public entry point changes:
npx tsc -b packages/core --force
npm run benchmark:sizesEach measured engine's browser entry is bundled and minified with identical esbuild settings, and
the WebAssembly and data files it fetches at run time are added at their shipped size. The script
measures Minnow, SQLite Wasm, and PGlite. The result lands in
apps/site/components/bench/library-sizes.json, which is a scratch output — nothing imports it.
The figure each measured engine shows on the page is the download field in
apps/site/components/bench/config.ts, updated by hand from that run.
The unit suite also compares fresh bundles against the installed SQLite Wasm loader plus its
Wasm file. The engine with OPFS must stay smaller after gzip. The generic worker with all
stores plus its separately bundled client has a tight 547 KiB combined budget; those two
downloads repeat some code and exceed SQLite's single loader-plus-Wasm measurement. The report
and test share the same measurement code. Per-entry budgets in
packages/core/src/tree-shaking.test.ts separately bound the main engine, the IndexedDB worker,
the schema DSL, and what a page that runs the engine in a worker ships on its main thread (the
client, the DSL and error classes, the Kysely dialect, and the React hooks); probes there also
check that the last two carry none of the SQL parser, optimizer, or executor. Each budget is its
current measurement plus a little headroom, so growth is a deliberate edit beside the number.
This guards compressed download size; it does not claim a smaller uncompressed bundle or prove
that every possible behavior is regression-free.
OPFS browser cases check for the storage API inside a dedicated worker before running
(requireWorkerOpfs: does navigator.storage.getDirectory exist). The Linux WebKit build
pinned with Playwright 1.62 (build 2336) has no navigator.storage at all, so a local run on
Linux skips its OPFS cases for that missing capability, while IndexedDB cases still run. Build
2359 has worker OPFS, so the cases run there (see
WebKit on a Linux host Playwright does not support).
The check sees only whether the API exists. The rebuild's backend choice (next/storage/select.ts)
goes further: it calls getDirectory(), requires createSyncAccessHandle, and treats the
private-mode refusals (SecurityError, UnknownError, NotSupportedError) as no OPFS, falling
back to IndexedDB. So in a context where the API exists but refuses (WebKit 2359 outside a
persistent profile, Safari private browsing), the check runs an OPFS case that cannot get OPFS,
while the rebuild's backend uses IndexedDB. Runs that claim OPFS coverage do not skip: under CI (the merge gate, where WebKit runs
on macOS) and in the conformance profile, a missing worker OPFS API fails the test. The site's
benchmark test follows the same rule. Worker startup errors and probe timeouts are always
failures. Contention correctness tests allow queued durable writes a 30-second RPC deadline;
the separate timeout and sustained-latency tests retain their own limits.
Browser interaction campaigns retain every worker diagnostic in their attached evidence. A typed ownership or revision refusal from an unpublished index build or compaction job can occur when another tab wins the same maintenance work. Those specific maintenance events are classified by their operation, error type, and identity/revision fields. Generic errors, I/O failures, corruption, changed posting chunks, and window or unhandled errors still fail the campaign; message text never suppresses a failure.
Rebuild differential harness
npm run test:differential runs the serial rebuild harness in the normal unit suite.
It replays the same workloads against the current engine on memory, fake IndexedDB and
the in-memory OPFS shim, then checks committed canonical answers. These are Node models;
the browser suites above remain necessary for native storage and process failures.
npm run test:differential:nightly selects the larger profile.
A candidate engine implements EngineFactory and EngineUnderTest in
packages/core/src/testing/differential-harness.ts. Pass its factory to runWorkload,
then pass both outcome arrays to assertIdentical. For large profiles, use compareEngines
to compare open engines in lockstep while retaining only one statement’s answers; the caller
closes those engines in a finally block. Each factory call owns a fresh database.
The interface accepts SQL and parameters, including transaction control and RETURNING,
the create-table schema objects used by these workloads, batch insert/upsert/delete,
and reopen. The current adapter is differential-current.ts. These are repository
test helpers, not new exports from the published testing entry point.
Identity includes projected column names and SQL domain metadata, statement kind, affected counts, RETURNING, duplicate rows, exact strings and typed values. NUMERIC scale and DATE text are preserved. Numbers compare IEEE-754 bytes, including signed zero; NaN payloads are not compared because JavaScript does not promise them. Arrays preserve order; blobs preserve bytes; object keys are sorted; JSON text stays exact text. No floating-point tolerance is enabled. Rows compare as multisets unless the source supplies proof of a total SQL order. Error constructor names and optional codes compare; messages, stacks, physical IDs, storage metrics and timings do not. The contract comment in the harness is the authority for this comparison.
The shared sources are the SQLite/PGlite seeded templates and fixture
(conformance-source.ts), the existing fast-check simple-write arbitrary
(live-write-source.ts), serial traces from the interaction-plan simulator, and
the committed SQLLogicTest files. The original conformance and live suites import
the extracted generators too. This harness does not replace their independent
oracles. It does not replay every property, conformance combination, simulator
interaction, or live delivery.
The fast profile uses seed 24301, one round of all 115 conformance templates,
30 fast-check writes with reads after each, a 40-interaction plan filtered to
serial SQL operations, the first 50 SQLLogicTest operations, and a batch/transaction
contract workload. It currently has five workloads and 348 operations per store (340 SQL statements).
The longer profile uses seeds 24301–24304, five template rounds, 300 writes and
400-interaction plans per seed, and all five standard SQLLogicTest files: 18 workloads and 17,125 operations per store (17,061 SQL statements).
All generated seeds come from seedsFor("differential-harness", ...);
MINNOW_SEED=123 npm run test:differential replays one seed.
The soak runner also varies this suite’s seeds. The campaign's declared reach lives in testing/reach.ts.
npm run fixture:differential records the fast workloads and canonical memory-engine
answers in packages/core/testdata/differential-corpus.json. It refuses a seed override.
The file contains the actual inputs, including tagged datetime parameters, so replay
does not depend on keeping an old generator or engine. The frozen test executes those
inputs through the ordinary API. Keep the file compact (currently about 1.23 MB).
These answers pin current behaviour as evidence, never as SQL authority. Changing
them requires a cited PostgreSQL behaviour or a documented Minnow contract, with the
reason recorded in the change. Do not regenerate them just to silence a mismatch.
Mutant adapters prove that dropping a row, changing NUMERIC scale, swapping an error class or introducing negative zero fails at the intended operation. Reversing an unordered result passes. Live subscriptions, concurrent openers, crash schedules, native browser storage and order-dependent floating aggregates remain outside this serial harness; their existing suites still own those checks.
Rebuild-core write CPU comparisons
scripts/write-insert-bench.mts compares two built core dist directories in fresh Node
workers. Save the parent build before rebuilding the candidate, then run:
node scripts/write-insert-bench.mts --baseline /path/to/parent/dist --mode load --durability strict --rounds 9 --require-gain
node scripts/write-insert-bench.mts --baseline /path/to/parent/dist --mode hash --hash-bytes 5 --iterations 20000000 --rounds 9 --require-gainThe load prepares its input outside the clock, writes one million rows in a transaction,
waits for its durable receipt and maintenance, and verifies the row count. Its memory backend
checks the strict write protocol; it does not measure disk flushes or worker transport.
The hash component walks a buffer and checks equality with the parent outside the clock.
Change --hash-bytes and --hash-offset to measure other sizes and alignments.
Write-key hash reuse is checked against the canonical xxHash32 implementation for both stored Bloom seeds. Generated cases cover collisions, shifted ranges, growth, rollback and release; the resulting run bytes must match the uncached path. Cached hashes never replace byte equality checks. Hash metadata is charged with the key delta and is not added to the stored format. Disk merges compute the pair for keys read from storage, then reuse it across block boundaries. Structural write optimizations require a paired whole-load gain; component gains alone do not qualify.
run-direct.test.ts compares borrowed single-entry batches with the ordinary owned encoder.
It checks complete native run bytes across block and Bloom boundaries, mixed chains, filtered
rows and wide row IDs. The key delta stays pinned until the final block is encoded or the
builder aborts; releasing its owner early must not release those bytes. Mixed chains fall
back to the ordinary serializer without changing a partially filled block.
run-accounting.test.ts observes native allocation before it happens, including hash-array
resize overlap. Generated ordinary and bulk runs keep their output charged after finish()
until the consumer releases it. Bounded streaming histories encode more bytes than their
256 KiB output budget; parts stay charged until the extent writer's append() resolves.
Flush, staging and merge encoders charge the owner's account before allocation. Larger
resident metadata waits through the cancellable publication retry after unwinding. Boundary keys
remain charged through publication. Budget denial, native allocation failure, cancellation
and retry must return provisional charges before waiting for memory. This checks managed
buffer ownership, not the JavaScript runtime's eventual garbage collection or native RSS.
merge-finish-budget.test.ts reaches the default 896 KiB split boundary with compact,
long-key inputs. Several independent encoder contexts share the real merge allowance,
with input leases and writer staging still charged. Finish transfers the prepaid metadata
backings instead of allocating second index and fence buffers. The generator checks stored
fence bytes, header counts, continued charging until consumption, abort cleanup and progress
while another execution holds its minimum. The review's two-reader, repeated nine-byte-key
probe separately covers the large balanced index/fence case.
merge-summary.test.ts accumulates hundreds or thousands of completed pieces with
fan-in from 1 to 32 and encoded keys up to exactly 2 KiB. Completed boundary keys and
run descriptors belong to the publication metadata account, which grows with the output;
the fixed merge grant funds reusable work only. The new account pays before the encoder's
charge is refunded. Temporary pressure aborts provisional work and releases input leases
and output allocations before the cancellable metadata retry waits. Charges remain until
publication takes ownership or the output is abandoned.
The unpublished rebuild's inline run encoding still refuses encoded keys over 2 KiB
with IndexKeyTooLongError (MINNOW_INDEX_KEY_TOO_LONG, a RangeError subclass).
The write path now selects overflow encoding for longer admitted keys. Its semantic limit
comes from the catalog path: a single TEXT primary key permits 16,384 UTF-16 units
(up to 49,155 encoded bytes), while secondary tuple terms share a 65,536-character
budget. A text component spends five term characters per UTF-16 unit plus five terminator
characters, so a one-text secondary supports 13,106 units. Composite primary keys also
obey the shipped hidden scalar locator's 16,384-character whole-term ceiling.
A unique path refuses excess values with IndexKeyLimitError (the same stable code).
A nonunique path keeps its catalog identity, becomes invalid atomically, and queries scan.
Imported scalar secondary provenance has a separate catalog policy. These limits apply to
mutation keys; they do not impose a blanket length cap on query parameters.
key-order-proof.test.ts checks retained key order and ascending batch admission against an
independent byte-order model. A normalized prefix proves order only when it differs; ties use
full byte comparison. A batch must be strictly beyond every retained key before it can skip
lookups. Generated bulk-encoder cases exercise both implicit order and explicit permutations,
and partial-failure tests cut the same completed key prefix in either ingress path.
Each worker runs one excluded warmup before its measured pass. Nine or more pairs alternate
AB/BA order. CPU includes all Node threads; wall time is separate. The acceptance rule uses
paired CPU deltas: their median gain must exceed their interquartile range (IQR), and at least
seven of nine pairs must favour the candidate. The output retains every delta, the IQR, full range, and MAD. The same rule in the reverse direction
identifies a regression; --require-no-regression fails on that result.
--samples 3 averages three complete timed passes per worker and retains each timing;
the default is one. Report the sample count and CPU affinity with every comparison.
--gc-before requires node --expose-gc and collects setup garbage outside both clocks;
report this choice with the result. Use --worker candidate --profile /path/to/load.cpuprofile
for a separate profile of only the measured phase; profiling runs are not acceptance runs.
A governor cap bounds managed allocations, not renderer RSS. For native memory work, align input backing-buffer bytes and governor usage with V8 heap and OS resident-memory readings at explicit batch barriers. Compare before and after garbage collection, and use allocator dumps to distinguish live bytes from retained pages. A heap snapshot taken after a peak cannot by itself explain that peak.
Rebuild-core low-cap write ownership
The low-cap campaign observes idle row credit transferred into an active merge while global capacity is insufficient. The merge already has prepaid credit: this reach state checks the ownership exchange, not a claim that the transfer is required for progress. The separate protected-reader minimum campaign checks merge progress while real reader bytes remain held.
Rebuild-core catalog checkpoints
The staged-ALTER campaign places ADD both before and after staging, checkpoints the newer catalog while the older claim remains unfolded, and reopens before allowing the fold. Fixed and varlen columns, NULL and frozen defaults, each native column position, and plain/FTS publications are generated. Bounded SQL reads, native/portable reads, and a second reopen after folding must preserve the same values. Published-memory membership comes from validated group metadata, read lazily; open still does not walk group roots. Every controlled fold gate is released and drained, including on failure.
The executor list-cardinality campaign varies parameter, expression and aggregate lists from empty inputs through more than 131,072 elements. Sizing uses loops rather than JavaScript call argument spreads, so long lists keep the same maxima and sums without a native stack error. A source check covers every rebuild layer, including support files. It permits argument spreads only for documented small bounds or fixed-tuple adapters. Separate layer bodies bound its work under coverage. Generated lowering, flush-queue and release-inventory cases also exercise lists above the native argument limit, preserving collation bindings, order and copied range metadata.
A separate replay-work generator interleaves many one-row commits over wide tables and one or two physical schemas. Mapping builds are bounded by the distinct table/schema pairs; unrelated DDL must not rebuild them. Identity metadata is charged before allocation, invalidated when its table descriptor changes, and released when replay ends, including failed replay. Under pressure inactive mappings are discarded before retrying the ordinary cancellable metadata policy. Descriptor arrays retained by memtables have independent row-owner charges until their final reader fence. Generated ownership cases force eviction, ID permutations and high column IDs, then assert that cache retirement cannot release a still-retained memtable's charge.
The DDL row-schema campaign runs DROP, ADD and RENAME at each column position over resident and published rows. Unrelated ordinary and FTS writes publish roots; each history reopens at publication, after later writes, after another ALTER, and after checkpoint/maintenance. It compares every value by its current column identity, including frozen ADD missing values. Row WAL names physical columns and tombstone indexes by stable IDs. A newer catalog checkpoint must preserve surviving values from older row frames without positional decoding or expanding missing values into every row. Generated histories cover DROP, ADD and RENAME at each position, DELETE marks, atomic CREATE/rows/ALTER (including replacing all old columns), and an ALTER sharing an LSN with another table's index build. They check exact rows after ordinary and FTS publications, writes, checkpoints, maintenance and reopen. Malformed identities and incompatible root/catalog replay versions refuse with typed errors; repaired roots can retry without leaked admission. A separate generated campaign forces merge and staging publications immediately after ALTER, before a later row flush could hide a stale copied replay version.
Dropping an index does not erase a build still needed by an older catalog checkpoint. The write path retains that obligation until a published root carries the build or covers its DROP. A flush whose selected catalog still requires the old index writes its backfill runs; quiet builds get an empty root. The catalog/index invariant remains enforced.
The generated checkpoint campaign uses seeds 702 and 704, with 24 histories per seed on memory, simulated disk and fake IndexedDB at a 32 MiB owner cap. It varies empty and nonempty builds, multiple cancellations, drop order and table creation after a cancelled build. A held flush and two later builds force the catalog prefix between CREATE and DROP. Every published catalog is checked against the committed DDL history, and historical index runs are read independently to check their keys and row IDs.
The campaign also interrupts publication after preparation, reopens the old root and log, and verifies continued durable writes, later index replacement, log recycling and another reopen. It checks the surviving indexes through point and range reads. Pending records are charged before allocation and returned when no checkpoint prefix needs them, or when the owner closes. The campaign observes those native allocations independently and checks that all credit returns. This is finite Node regression evidence, not a native-browser or exhaustive power-loss proof.
Rebuild-core staged rollback
The generated staged-residual campaign commits a deletion, then stages and rolls back new rows that shared its memtable. The committed tombstone must survive until its rowless flush publishes it. The campaign also keeps an earlier pending deletion across statement and savepoint rollback; a flush cannot wait for a pending sequence as though it were a committed LSN.
Seeds 702 and 704 run 80 histories per backend over memory, the simulated disk and fake IndexedDB. Histories vary memtable capacity, primary and secondary indexes, rollback kind, retained snapshots, held publication, merges and deterministic task-clock yields. Row scans, index probes and ranges agree before and after publication and reopen. Deleted keys can be inserted again, real duplicates still fail, and rolled-back staged keys remain absent. This is a write-path visibility and recovery check; it does not measure native browser memory or cover every DDL interleaving. A dedicated memory/simulated-disk regression deletes a stored key, reopens, stages and rolls back another transaction, then inserts that key again. A point lookup and prefix range must identify the same single live row before and after another reopen.
Rebuild-core log queue accounting
The generated storage log-queue check holds a transaction open and independently counts retained input snapshots from copy creation through transaction settlement. It compares that live-byte count and peak with the real governor, checks the 4 MiB backend-owned queue bound, and checks that pressured appends wait. Refused copy admission borrows the still-charged caller buffer. Separate cases cover replaced tails, failed transactions, truncation order and close-time drain. This checks managed buffer accounting; native IndexedDB clones and browser RSS still need the Gate D browser measurement.
Extent-list startup at scale (rebuild core, opt-in)
On Linux with Chromium, the R25 lane builds 100k and 1M zero-column groups on OPFS and IndexedDB, one extent per group, using the real manifest and group-directory codecs and incremental extent lists. Each dataset is reopened in three fresh workers. The report separates backend setup, fence acquisition, session/index loading and extent-space startup, against the 500 ms reopen target. It also reports owner-worker and whole-browser CPU ticks, coalesced list-data bytes read, and root payload bytes. CPU samples exclude build, module boot and cleanup; OS caches remain warm. IndexedDB opens data/log byte spaces with last-record boundary lookups and loads persisted record entries lazily for the requested ranges. Whole-store orphan/missing/key/order checks run in audit and test-build open, issuing three bulk requests together per 4,096-entry page. Their O(records) scan is outside ordinary open. Native metadata/range lookup time is included, but its physical bytes are opaque. This is a synthetic metadata stress measurement. Gate A acceptance uses actual S5/W5M loads and owner-ready reopening, including write-path recovery and composition.
npm run test:prepare
MINNOW_NEXT_STORAGE_REOPEN=1 npx playwright test --config playwright.library.config.ts packages/core/browser-tests/next-storage.spec.ts --project=chromium --workers=1 -g 'R25 list reopen'The keeper admission regressions use finite governor grants. They require refusal before any write, bounded page-at-a-time preparation, charges held across suspended readers, and complete scratch cleanup after failed reads, failed writes and aborted publication attempts.
Storage task-slicing regressions queue timers before large preparation and cached-list reads, then require service before completion. They also cancel at task turns and immediate read resumptions, exercise union and free-map construction independently, and verify that two preparations share the worker's task clock rather than starting fresh slices.
The unexported rebuild core also has an opt-in owner-ready measurement:
MINNOW_OWNER_REOPEN=1 with next-storage-owner-reopen.spec.ts in Chromium. It loads the
actual S5 commerce and W5M wide datasets through the real write path, then measures backend
open, extent-space open, write-path recovery and owner host ready separately. CPU samples use
separate bracketed runs; wall samples have no sampling barriers. The executor stand-in is unused
during startup. Its first SELECT count(*) is explicitly statistics-only and measures the owner
protocol around the recovered row count, not an integrated scan. Native IndexedDB disk bytes
are unavailable; the report counts returned byte payloads and numeric index/meta reads.
The factory acquires handles in openFence and recovers in open, following the host contract.
The default fence deadline is unchanged; the ready timer includes acquisition and recovery.
The simulated disk reuses spare capacity for appends. It keeps the logical file length exact and retains copy-on-write for overwrites and truncation, so old views and flushed prefixes stay unchanged. Recovery starts a new append lineage; it cannot overwrite an old view's unflushed suffix. Seeded tests compare reused buffers with fresh-image writes under honest and lying flushes, planned crashes, recovery, overwrite, truncate and gaps. They check every physical step and retained image, plus a buffer-growth bound that rejects a full-prefix copy on every append. This removes quadratic WAL copying from the IndexedDB histories without changing their cases, seeds, publication rounds, reads, reopen checks or deadlines. Simulator spare buffers are test-fixture memory, outside the engine's managed-memory accounting.
The extent-space crash sweep registers each backend, placement and seed as a separate test. Every seed still checks every physical crash boundary, using the normal local test deadline.
The bounded-storage histories hold every remaining ordinary byte in the caller, sometimes with a live progress loan, while publication and abort finish without admission. Final-phase histories enumerate actual native I/O and task suspensions, then interleave tracked-hole/EOF reservations with queued abort, discard and seal transitions at every checkpoint. A free outside the barrier must fail these checks. Audit histories also require another publication to finish while the audit's external producer is blocked, and verify a restarted generation.
The free-map pressure regression replays seed 598's generated durable-load shapes over memory and the IndexedDB adapter. It holds all but one ordinary byte during each native allocator release, including trim and abort, with startup credit retained or returned and with or without a caller loan. Releases must add no charge. The histories require real merges, exact rows, recovery, audit and complete charge cleanup. Pressure is scoped to allocator mutation; the separate write-path metadata and merge admission policy has its own tests. The full review workload can expose that separate policy after storage succeeds.
Native-open histories require ordinary listed-root open to write no payload pair chains. They close the startup grant, hold the remaining ordinary capacity (sometimes with a loan), and require the first publication or audit to complete with descriptor credit still charged. Refusal, transfer failure, cancellation during decoding/handoff, native write failure and unused close return every charge. A large-page-directory case allows sorting only physical page coordinates; payload coordinates may not appear in private writes. Timer checks cover immediately resolved reads. The first publication or audit pays the deferred chain-copy cost; recovery that publishes pays it before ready. Generic callbacks keep their existing path.
The rebuild's native extent-list cursor tests also interleave two roots over two prepaid 192 KiB windows. A cursor reuses bytes still held by its peer, while checking its own root's checksum and descriptor. The shared cache has two slots regardless of the extent count; evicted ranges are read again. It adds no payload buffer to the charged read slab.
Disk-derived retirement tests keep the before/after list pages protected through complete worklist construction, then release at most 256 ranges per batch. They independently check fragmentation debt and recovery when the gaps coalesce within the arena capacity. Private metadata faults, cancellation, native root copies and snapshot charges have separate checks. These are managed-buffer bounds; opaque native IndexedDB memory still needs Gate D browser measurement.
Native compatibility histories vary minimum reader and minimum writer independently in both root slots. Concurrent openers must refuse an unsupported requirement before stealing the live owner's lock, writing an epoch or creating missing files. They compare every OPFS file and the IndexedDB root, log, data and epoch records afterward. Stale preflight snapshots still require an owned recheck. These tests use the native adapters over their test shims, not two browser binaries from different released versions. The first supported format chain starts at1.0.
Native ownership histories also suspend stealing openers before and after lock grants and native fencing. A runnable publisher must escape a frozen compatibility gate on its own bounded clock, by advancing a durable owner generation. Delayed lock-loss notifications cannot revoke the replacement identity. The resumed stale attempt must leave every native byte unchanged; a fresh compatible takeover must work even while the obsolete opener remains frozen. A cut after native fencing but before lease exposure must preserve roots and WAL, and a timed-out waiter must never steal later. These use real adapter code with modeled locks and native test shims; they do not claim browser background-tab freeze or mixed-binary coverage.
The rebuild's portable-load histories replace targets holding real FTS checkpoint journals, committed staged preparations, document pages, terms and postings. They interrupt every physical publication step, reopen to either intact old rows and FTS payloads or a complete replacement with empty native FTS state, then retry. Old FTS extents must retire exactly once and all governor charges must return. These tests use the simulated honest-flush disk; they do not replace browser power-loss or quota testing.
The owner-ready campaign accepts MINNOW_OWNER_REOPEN_SAMPLES=6 for six wall and six
separate CPU samples per dataset/backend. It retains each sample and its before/after host
load and CPU-pressure snapshot, including slow observations. Private metadata read bytes are
included. A statistics-only first count remains labelled separately from startup.
Bounded-arena histories independently track live cells and reusable runs under fragmentation, overflow, splitting and coalescing. They require forgotten holes to remain unavailable, check the single prepaid backing allocation, and recover all free space on rebuild where coalescing brings fragmentation within capacity. Unchanged extreme fragmentation may retain debt across reopen. Integrated histories also check root-list provenance: unknown space never authorizes a root reference or retirement.
Memory-transfer histories fill ordinary capacity, queue another admission and move an existing allocation into a cache owner without adding or releasing a charge. They also move ordinary allocations beside an active loan, refuse loan capture, and require both owners to return every byte on close. Foreign and closed grants cannot transfer into another owner's accounting.
Private-metadata histories run over memory, both simulated fences, OPFS handles and IndexedDB. Random page rewrites must survive the operator-spill sweep; resetting metadata must preserve roots, log, data and operator spill. Every read, write and reset from a replaced owner must fail. This backing holds reconstructible disk-derived retirement tickets and is discarded at open; durable roots remain recovery authority.
The metadata-journal generator inventories frames independently at construction, requires admission first, and keeps the frame count constant as its disk queue grows. It tests multi-page inputs, empty chains, cursor references and page reuse; mutants that omit admission or cursor retention fail their respective invariants. Serial list reads also generate thousands of tiny physical records and require index selections of at most128 entries per page, independently of the byte target. Native-read response capacity is measured separately in its scripted store. Cancellation and failed-write tests require cleanup without a new memory request. These primitive tests do not yet establish live publication's bound.
Private pair-stream histories sort shuffled extents above 2^40 through several
disk passes, including an unmatched final run. Independent expected pairs check
union, difference and duplicate policy. Cancellation interrupts the 100,000-entry
producer during copying, selected sort/merge task turns and the final descriptor
write. Each case retries and checks input references. A scripted two-run trace
fails every native write boundary in turn, preserving the original error and
returning the workspace charge. Mutants that truncate offsets, reclaim shared
extents or copy the whole producer before slicing must fail.
Pair-progress histories count microtask continuations while merging and validating immutable extent streams, and count output-frame view allocations. They vary input size and ownership overlap, compare every output with independent expected pairs, cross native page boundaries, and require exact workspace cleanup. In-frame scalar operations stay synchronous and reuse admitted frame views; actual native I/O and shared-clock pauses still suspend. The continuation check freezes its clocks to isolate scheduling overhead. Separate clock, cancellation, corruption and physical-failure suites exercise those boundaries.
The rebuild's directory-append campaign counts encoded references rather than asserting wall clock timings. It generates singleton appends, variable transaction batches and mixed edits. The writer retains a canonical prefix: full pages followed by descending power-of-two partial pages. This bounds both encoding work and the page index. Each history audits extent ownership, reopens, verifies every expected value and returns every governor charge. The original full-page boundary workload retains its groups, operations, assertions and deadline.
The directory page grammar stays unchanged. The rebuild's root format is now version 3;
no older next/ writer is supported because no published package includes the rebuild.
Archived development roots and the 4133d25a writer are kept only for explicit refusal tests.
Packing tests seed fresh version-3 roots over the unchanged packed group/page payloads;
this test bootstrap discards the archived root slots and runs no migration. A separately
bundled current writer supplies an independent module graph for continuing-writer and
competing-opener checks. This does not prove older-writer compatibility.
The ordinary-open campaign still covers every tail total from 0 through 4,095 in 32 independent ranges of 128 states. Every state reads all values in both current module graphs, makes durable writes, and reopens. It also covers the full-page carry, packed-tail normalization, and an edited page whose extent still holds unchanged partial pages. Seeds, states and physical fault edges are retained. Both current writers must preserve the same unchanged directory prefix.
The exhaustive ranges use the ordinary startup policy, without repeating test-only physical
audits at every open. Each range reopens its final peer write and audits its boundary carry.
Transition histories explicitly audit current and previous ownership.
They interrupt both writers after directory page/index writes and each native publication step: data flush,
root write, root truncate and root flush. Strictly acknowledged values must survive recovery;
both writers continue writing and reopen. Each transition also refuses damaged page/index
bytes and queues two competing openers in both build orders. Declared reach covers all tail
states, transition types and publication edges. The physical crash model uses honest flushes
with seeded lost/torn pending writes; this is Node fixture evidence, not a real-browser crash
campaign. To reproduce the archived development payload fixtures from the pinned writer, run
npx vite-node scripts/write-next-directory-fixtures.mts; scratch uses os.tmpdir().
Ordered-root startup regressions require a streaming union without the unordered free-map sort, validate scattered list-page allocations, and refuse overlapping, descending or inconsistent extents before reclaim. Full audit and test-build semantic checks remain enabled separately. The lifetime free-run arena is admitted before allocation, including its overlap with the prepaid reconstruction view. Its charge transfers from startup to the space and remains until close. Previous-only retirement streams through disk tickets; it has no resident per-extent index. Immutable native-list descriptors retain their transferred codec charge until handoff or close. Deleting entries does not assume JavaScript containers release capacity. Finite-budget regressions cover refusal, transfer refusal, cancellation, fragmentation, previous-root retirement and cleanup. Audits restart when their mutation epoch changes, including a raced failure, so publication, reservation and writer transitions cannot make their captured accounting view stale. They hold no publication lock during enumeration.
Ownership-boundary histories hold native publication and interleave synchronous reservations with abort, discard and seal in generated orders. They drive the memory backend's task turn explicitly, require queued owners to retain their records, then release publication and audit the result. Close must retain its memory until an accepted publication settles, including a native failure. These tests cover the barrier; disk-derived R8 tickets are a separate integration.
The real owner-ready composition holds initial flush, merge and recycle work until the page
acknowledges receiving ready, then resumes it. Native file/range and logical call-site tracing
(MINNOW_OWNER_TRACE=1) includes in-flight maintenance state; it is diagnostic, not a timing run.
The first statistics-only count can overlap the resumed maintenance. Standalone write-path opens
still schedule their maintenance automatically; owner composition supplies the ready lifecycle.
Bounded-storage I/O histories independently count pending IndexedDB record gets, callback response bytes and output-copy lengths in eager and lazy index modes. Random two-boundary trims must retain all outside bytes, survive reopen and roll back an already trimmed first boundary if the second is corrupt. Raw reads must have one pending data-record request; boundary copies stay at most 60 KiB. A constructor probe requires fixed-slab admission before allocation, and a held borrowed view must serialize ordinary cache reads. Borrowed metadata frames share the paid slab and cannot become native write buffers. These checks cover managed/native callback lifetimes, not browser allocator or garbage-collector retention after a callback returns.
Slab-backed list-cursor histories verify high coordinates, page coalescing and scalar results against an independent sequence. Malformed headers, checksums, first offsets, overlaps and past-end coordinates fail. An injected shared clock services a real timer and cancels within the first 512 entries even when reads resolve immediately. Arena-copy tests count typed-array elements at the yield, cancel partway through copying and retry with the same reservation. A full ordinary governor must transfer the arena's existing charge without a second admission; source and lifetime owners return exactly their own bytes.
Disk-ticket histories keep eight generations pinned while their source snapshot owners close. They fill ordinary governor capacity, sometimes hold a caller progress loan, and reject any new publication admission. Reclaim checks the next-durable-generation guard and pin guard separately. An independent native buffer-constructor probe permits only two owned frames in the slab-backed composition; every release batch must contain at most 256 ranges. Each seeded backlog mixes validated worklists retained from publication with startup-style differences derived at reclaim. Cursor counts require validated tickets to avoid rescanning either root, even after the caller releases its proof reference. Abort must return that reference. A generated publication-merge suite checks exact rounded retirements and sealed-writer ownership against an independent coordinate partition, including missing/extra/duplicate claims, changed shared lengths and incoming overlaps on either side. Each immutable root opens once for both proofs; this cost guard counts cursors rather than elapsed time. Both campaigns declare their reach. The pair-progress seeds also bound clock probes by slices instead of scalar output, and cancel inside a merge within 512 consumed pairs before retrying it. All original cancellation stops (1, 200, 8,000, 16,000 and 22,000 yielded tasks) remain. Their three larger input histories extend to 160,000 or 320,000 extents so the late stops stay reachable after redundant scalar clock probes are removed; none of their retries or assertions is removed. The directory coverage workload keeps its rows, assertions, coverage settings and 300-second deadline. Separate histories keep fragmentation debt across rebuilds, recover it when gaps coalesce, and fail each reconstruction native-write boundary, including cursor cleanup after the arena was allocated. These component histories precede the full extent-space and write-path integration campaign.
Rebuild storage step-down regression
The storage campaign stops its workload inside the worker, drains admitted operations, closes the session, releases the lease, then terminates. Withholding page-side messages alone cannot stop a worker timer or a message already in transit. The regression checks paused lanes, admitted writes and delayed messages.
Run ten Chromium repetitions with 4× CPU throttling and a deliberate post-close scheduling pause to exercise dormant workload timers:
MINNOW_STEP_DOWN_CPU_RATE=4 MINNOW_STEP_DOWN_WAKE_AFTER_CLOSE=1 \
npx playwright test --config playwright.library.config.ts next-storage.spec.ts \
--project=chromium --workers=1 --repeat-each=10 \
-g 'stop, drain, close, release, then terminate'The pause is a test probe; its timings are not release-performance measurements. Each repetition keeps the ordinary 40 stop/reopen cycles and checks every acknowledged state.
The owner idle-timeout regression keeps MessagePort delivery native and advances a fake timeout clock. It holds a cursor window open for 100 ms with a 20 ms idle limit, then separately checks the 19/20 ms boundary after the terminal reply and final frame release. Sleeping after the last frame tests an idle gap between requests, not whether a running request is protected.
The owner hidden-flush test disables automatic lifecycle relays only in its fixture and uses an explicit hidden event in the positive case. A same-worker FIFO checkpoint observes existing saves without starting one. The control confirms zero saves and zero durable LSN, then both cases terminate the worker before closing the tab. Loss is required only for this fixture's unsaved JavaScript state; relaxed durability does not require data loss. Ordinary tab teardown can process hidden/pagehide or graceful close and flush, with browser-dependent scheduling.
The internal expression-helper cancellation test holds a sort or join key's precise replay at explicit consumer backpressure. It fixes source batching so a valid row and a later error reach the same batch; an elapsed source slice can otherwise flush single rows and never suspend that replay. Cancellation awaits the compiler's request for the helper's real close fence, checks that its grant is still held, and releases the consumer before awaiting helper and execution settlement. No row may be delivered after cancellation, and cleanup must return all charges. Both committed seeds, shallow stack settings, examples and generated histories run without stack-name hooks or timer-based settlement windows. The test timeout is only a hang backstop; this check does not measure cancellation latency.
The rebuild's staging-retirement campaign holds an index flush at its publication barrier, rolls back staged rows, and drops their table while the catalog checkpoint still retains it. Generated memtable sizes, staging lengths, and memory/simulated backends check that the retained root's reachable extents match its deltas. Releasing the barrier must finish the drop and allow reopening. This covers the held-build rollback schedule; it is not an exhaustive check of every publication schedule.
The write row-plan generator compares inserted values and index visibility across physical ranges, sparse selections, nullable and encoded vectors, partial memtables, and admission boundaries. It checks returned row selections, producer-buffer reuse, NOT NULL refusal and reopen. Its work check ensures contiguous input reaches the existing copier without a materialized row selection.
The row-plan accounting generator holds admission open and observes the live owner account. The owner allocates one fixed 64-byte allowance for the single active plan, retained through success, failure and cancellation and released on close. The plan borrows its row selection without another copy. The check covers one and several admission chunks and proves the allowance is allocated during the wait, rather than inferring it from a zero balance after close.
The rebuild's durable-format registry is swept through real decoder entry points by
next/testing/durable-format.test.ts. Generated cases cover unknown versions and tags,
every reserved bit, strict boolean selectors and alignment padding. The checks require typed
refusal, unchanged bytes and returned allocation charges. A future minimum-reader or manifest
format in either root slot must refuse before any native write: IndexedDB's epoch and records
and OPFS's file tree remain unchanged. Checksum-invalid torn slots retain their ordinary
recovery behavior. Snapshot registry entries remain design-only until export/load is implemented.
Deletion-bitmap cases cover exact word lengths, every unused tail bit, aligned and unaligned input, and both cache-hit and asynchronous reads through the production write path. They require typed refusal, unchanged inputs and returned resources. Registry completeness also scans production persistence calls and durable reference fields independently of the registry and its decoder adapters, so omitting a format from both lists cannot hide its writer.
Rebuild long-key codec stages
The unpublished rebuild manifest is version 3. Every stored run has an explicit inline or
overflow encoding discriminator. Unsupported versions raise UnsupportedEncodingError;
old development roots are refused without rewriting them. No published package contains
next/, so this is not an upgrade of a supported stored format. The 1.0 rebuild starts a new chain: it refuses 0.x data without mutation. No 0.x converter
is implied; the existing 0.x compatibility suites remain specific to the 0.x engine.
format/run-key.test.ts generates canonical inline and overflow descriptors, including the
49,155-byte encoded single-text primary-key maximum. It checks bounded prefixes, complete
chunk coverage, checksum fields, overlap, extent bounds, truncation and unknown tags.
encoding-version.test.ts checks typed refusal and returned parse charges for unsupported
root versions. The writer, readers, Bloom filters, summaries and catalog-limit admission now use this
encoding together. Short-key block bytes remain unchanged.
write/overflow-writer.test.ts exercises an opt-in overflow writer. It
keeps data blocks within 4 KiB, puts payload chunks and their checksummed directory in the
same extent, and keeps summary storage charged through consumption. Generated cases check
precharge before native allocation, delayed acknowledgement, detached buffers, cancellation
before admission, injected allocation/append failures and retry, bulk input, wide row IDs,
and two interleaved encoders. Short-key runs retain inline encoding; admitted longer keys
select overflow encoding and publish through the current root.
write/overflow-readers.test.ts checks point reads, both range directions, exact fence seeks
and mixed-run merges against complete key bytes. Generated shared prefixes must not collapse
distinct keys, and an inline key that prefixes a longer key is still an exact point lookup.
Keys may span payload chunks; hot keys span blocks. Readers prepay a reusable full-key head
and parsing workspace, release a block lease before resolving its key, and pass tests that
poison every returned lease. The campaign includes fan-in 32, output splits, interleaved
readers, read failures, close/cancel during I/O, retry and typed structural refusals. These
codec tests do not certify the later catalog-limit policy or the shipped-format cutover.
write/overflow-summary.test.ts checks complete-key Bloom membership across real filter
partitions, conservative prefix summaries, and ordered pending heads in both range directions.
write/overflow-root.test.ts checks ordinary point/range reads, old snapshots, continued writes
and reopen with an opt-in overflow writer. write/overflow-integrity.test.ts refuses
contradictory endpoints, impossible capacities, cross-extent descriptors, damaged payloads and
checksummed unknown directory versions. write/overflow-publication.test.ts retains hundreds
of funded output summaries under 32/64 MiB caps, faults every native root-publication step,
retries after recovery, and opens an overflow root from an independent current module graph.
These are new-encoding tests, not evidence for the separate shipped-format cutover.
testing/long-key-limits.test.ts compares flat, constant and dictionary-vector admission
with the shipped scalar and tuple term helpers. It checks canonical domain component costs,
unique refusal, nonunique invalidation, statement/savepoint rollback, backfill and WAL replay.
Ordinary storage APIs exercise writes and point reads. Real owner SQL scans and a prepared
query verify that invalidation changes the catalog version and replans away from incomplete
indexes. This base's executor still refuses SQL modify and bounded index operators; these
tests do not claim to implement them. SQL's zero-byte refusal remains separate from raw
physical-key tests.
write/long-key-actions.test.ts checks the maximum TEXT width and embedded NULs, including
an old range plan admitted after a larger invisible key was published. It admits full heads
without growing the planned grant. Invalid FK-support indexes use an exact scan of only the
reference columns; rekey, CASCADE, SET NULL and RESTRICT remain correct after reopen.
Faults at allocation boundaries check cleanup, including a partially constructed key batch.
Wide flushes drain by bytes and reserve encoder credit from catalog bounds before starting.
The generated cap cases include 32 and 64 MiB. Input admission prepays old/new column and
key-arena overlap, then recomputes that need after relief. A wide memtable can freeze before
its row limit; pending rows stage through the existing publication protocol. Commit, rollback
and rollback to a savepoint all retain the correct prefix after such a freeze. A retained
allocation from another execution forces this relief before the memtable is full.
scripts/write-hot-key-cpu.test.ts checks hot-key ordering work structurally. It counts
row/sequence input reads on the delta's arrays, requires a linear bound, and compares that
work with the legacy traversal. It preserves the generated keys and exact row order. CPU
samples are diagnostic evidence only: JIT, GC and shared runners must not decide this law.
An unnecessary hot-chain heapsort is rejected by the work bound without a timing threshold.
The long-key range, poisoned-reader, retained-summary and byte-bounded flush campaigns put
each original history in a separate test body. Every body regenerates the original fast-check stream with the same
seed, run count and examples; only its assigned history performs storage work. Together the
bodies execute every original history exactly once. The route opens for all shrink candidates
after a failure, so smaller counterexamples remain visible. This bounds work per body under
V8 coverage without shortening keys, reducing fan-in or removing prefix ties, either scan
direction, skip checks or publication pieces. Reach still counts the original histories.
Local coverage timings guide this split; ordinary CI keeps its generous hang backstops and
has no 40-second performance assertion. testing/history-body.test.ts checks exact routing,
examples and shrinking. The shared helper uses the excluded .test-support naming pattern.
Known-size memtable flushes give the page writer an estimate-only row-count hint. This avoids
reserving space for 65,536 wide rows when the group contains only a few. The hint changes no
codec decision or page boundary. page/known-rows.test.ts compares native page and tail bytes
with the ordinary estimator; the integration campaign refuses exaggerated reservations
before a memory store could allocate a multi-gigabyte buffer.
testing/wide-row-recycle.test.ts also exercises the ordinary native flush with 1, 4, 6 or 8 JSONB
columns, values on both sides of the 64 KiB large-value boundary, and explicit validity
bitmaps. It checks complete append progress, bounded reservations before storage allocation,
charged encoder scratch and cleanup, then compares every native value before and after
reopen. Initial extent requests must total at most four times the actual JSON row bytes plus
64 KiB for narrow columns, roots and directories. This structural assertion catches the old
full-group extrapolation before storage allocates gigabytes. There is no elapsed-time
correctness assertion; a generous 120-second campaign timeout is only a hang backstop.
The separate shipped-format cutover and quiet-host performance acceptance remain outside
these correctness campaigns.
Catalog-dependent run capacities are checked after WAL replay has restored the catalog. A table's
durable checkpoint can lead the global catalog checkpoint; physical runs for a dropped index can
also remain until retirement. Structural extent and descriptor checks still run independently.
write/catalog-run-limits.test.ts rewrites a native checksummed root to give an otherwise valid
run a capacity beyond its recovered catalog path, checks typed refusal and cleanup, and reopens
intact controls. Refused opens release state pins and native owners before grants, without
publishing; repairing the root then permits an ordinary retry. The exhaustive crash sweep and
catalog/drop campaign enforce the replay order.
write/wide-key-batches.test.ts checks complete borrowed batches whose encoded keys exceed
the 1 MiB key work target. Insert admission splits wide key-bearing input by bytes; index puts, FK checks,
updates, deletes, conflict probes and replay consume every completed key batch. A publication
barrier keeps the new index out of the root until close, so ordinary reopen must replay the
entire backfill. Checks cover both the live build and the replayed tail.
The one-index ingress campaign keeps its 160-row, 32/64 MiB histories, now including borrowed batches of 80 or 160 maximum-width keys, rollback and savepoints. The two-index lifecycle campaign uses 32 MiB for 32 rows and 64/128 MiB for 48/80 rows. Larger pre-flush snapshots retain old key deltas, and their complete peak plus private commit credit can exceed 32 MiB; the tests do not promise that an execution whose whole minimum exceeds the cap can run there. No production budget or stored encoding changes for this batching fix. Existing statement row, conflict and undo scratch copies remain outside the codec's native-allocation proof.
Byte slicing is restricted to key-bearing input. A large unindexed payload keeps its ordinary admission and publication boundaries; the bounded memory-read campaign checks its original logical prefixes without changing its fixture or expectations.
The long-key registry integration first introduced reader version 2 in the outer root-slot
header and manifest version 3; later native features advance those selectors together with
the closed vocabulary registry. It registers inline/overflow runs, pointer and chunk descriptors,
the checksummed key directory, raw payload references and the extended-block bit. The
independent persistence inventory includes these references. durable-long-keys.test.ts
checks WAL-only nonunique invalidation at 13,107 UTF-16 units and an independently bundled
reader with capability 1: OPFS and IndexedDB must refuse before native writes. That synthetic
build has a profile for its own codec vocabulary, accepts its own root header, and uses the
same manifest version as the current build, isolating reader-capability refusal. A separate
incoherent bundle must fail module initialization; production profile validation stays strict.
Both native root slots and unchanged IDB root/epoch bytes are checked. This is a gate test,
not a historical predecessor or upgrade fixture. The strict catalog-operation registry admits
invalidateIndex while still rejecting unknown operations.
Archived development directory roots are refused by the outer durable-format gate with
MINNOW_FORMAT_UNSUPPORTED, before the inner manifest decoder runs. The directory-refusal
campaign checks the exact code, zero writable OPFS handles and writes, and the complete
unchanged native file image for all three frozen directory shapes. The pre-registry archived
writer still refuses the current root with MINNOW_MANIFEST_CORRUPT; its separate check
preserves root/data payloads, without claiming that obsolete writer has a pre-fence gate.