@jarenjs/db 0.34.0

package/ARCHITECTURE.md

@@ -0,0 +1,397 @@
+# @jarenjs/db — architecture
+
+The public documentation promises SQLite and nothing else. This file
+documents the two seams that make that promise cheap to keep and cheap
+to outgrow — an undocumented seam decays into an accident.
+
+## The driver seam (`src/driver.js`, `src/drivers/*`)
+
+A driver is `{ name, dialect, open(path, options) }` returning a
+`Connection` (see `docs/MODEL-FORMAT.md` §4). Three bindings exist,
+one per subpath — `./node` (`node:sqlite`), `./bun` (`bun:sqlite`),
+`./wasm` (an injected handle) — and each imports its runtime builtin
+**lazily inside `open()`**, never at module scope. The release gate
+imports every export subpath under Node *and* Bun; Bun ships no
+`node:sqlite` and Node cannot resolve `bun:` specifiers, so a
+top-level builtin import would turn the gate red in both directions.
+`open()` is where "this binding does not exist here" becomes the coded
+`JD0003`.
+
+Every connection and statement method may return a value or a promise.
+The store composes through the sync-capable `chain` helper, which
+applies a continuation without allocating a promise when the driver
+answered with a value — the public asynchronous surface then lifts
+exactly once per call. Where the connection is synchronous the same
+operation cores are exposed promise-free under `store.sync`; where it
+is not, `store.sync` is absent rather than stubbed.
+
+Capabilities are probed once at open (version, compile options,
+binding declaration) and frozen. Two slots — `statementTimeout` and
+`rowEstimates` — are `false` on every SQLite driver because the
+underlying facts do not exist there (no interrupt, no progress
+handler, no estimate API). They are part of the contract so a driver
+that has the facts can fill them without a contract change.
+
+## The dialect seam (`src/dialect.js`, `src/dialects/sqlite.js`)
+
+A dialect is data plus a small emitter, and it is the only place SQL
+text is produced. `createDialect(spec)` composes a spelling spec —
+identifier quoting, parameter references, string literals, JSON
+extract/set/remove/append, transaction phrases, PRAGMA phrases,
+introspection queries, the table suffix and document column type —
+into the DDL and DML builders the store consumes. Nothing outside a
+dialect concatenates SQL; a reviewer can point at every emitted
+statement and find it behind the seam. The suite pins this with a
+test-double dialect whose quoting, parameter style and type names all
+differ: the same model produces correspondingly different SQL.
+
+Deliberately *not* dialect concerns, because they are behavioural
+rather than syntactic, and live in the capability table instead:
+whether functions register per connection, whether change capture
+exists and in what form, and whether tables can be restructured in
+place.
+
+The SQLite dialect stores documents as JSONB in a `BLOB` column of a
+`STRICT` table, projects each indexed path into a virtual generated
+column over `jsonb_extract`, and renders reads back to text through
+`json()`. Parameters are positional because every shipped binding
+binds arrays.
+
+## What sits on top
+
+- `src/ddl.js` — a normalized collection to its physical plan. Index
+  paths are analyzed through the query engine's **published AST**
+  (`analyzeQuery`): singularity decides indexability (`JD0004`
+  otherwise), and the collection's schema is the type source for
+  generated columns. The plan carries both the CREATE statements and
+  the structural facts an existing table must match (`JD0002` when it
+  does not — nothing is ever altered).
+- `src/patch-sql.js` — RFC 6902 to JSON-set primitives, discriminated
+  against the live document (a pointer cannot say array-or-object on
+  its own). Untranslatable operations fall back to a whole-document
+  write; the store counts and exposes the fallback.
+- `src/store.js` — model normalization (`JD0005`), shape
+  create-or-verify, the validated write path (injected
+  `compileSchema` hook; `capabilities.validated` says whether it is
+  in force), identity strategies, savepoint-nested transactions, and
+  the sync surface.
+
+Dependency arrows: `core → json → db`, plus `validate → db` for
+exactly ONE reason: the entity walk resolves `$ref` and merges `allOf`
+through the schema resolvers `@jarenjs/validate/normalize` exports for
+other packages to walk schemas with (emit already does). Validation
+itself still arrives only through the injected `compileSchema` hook —
+this package never calls the validator. No linq, no app, no view, no
+flow. The linq package couples by contract (`execute(document,
+options)`), never by import.
+
+## The decisions that cost something
+
+- **D3 — the normalized AST is a compatibility surface.** The planner
+  walks the engine's PUBLISHED AST, which promoted an internal shape
+  to a versioned contract the engine must now keep. Paid for: a
+  load-time exhaustiveness pact means a new language construct breaks
+  the build instead of silently becoming a residual.
+- **D6 — the store API is asynchronous** even though every shipped
+  driver is synchronous. Measured cost: ~0.17 µs per point read
+  (~6 %) over the `store.sync` twin. Paid for: the browser's OPFS
+  story and any future non-embedded driver need no API change, and
+  the sync-capable `chain` keeps the internal composition
+  allocation-free so the surface pays exactly one promise per call.
+- **D21 — the dialect indirection is paid for a second backend that
+  does not exist.** Every byte of SQL routes through a spelling spec;
+  the test double proves the seam by rendering the same plans and the
+  same DDL differently. The cost is one indirection and a larger
+  contract; the alternative was a rewrite on the day a second dialect
+  matters — and the capability slots (`statementTimeout`,
+  `rowEstimates`) already model what a server would fill in.
+
+## The pushdown contract (`src/plan.js`, `src/emit.js`, `src/query.js`)
+
+This is an implementation contract, not a format: it binds the planner,
+the emitter and their tests, and `explain()` is its runtime witness.
+
+**Three stages, and the middle one is dialect-neutral.** A query
+document is analyzed to the engine's published AST, the AST becomes a
+`Plan` — a relational algebra value carrying **no SQL text** (a test
+scans plan output for dialect tokens) — and the plan renders to SQL
+through a dialect. What cannot be proven equivalent runs as a
+**residual**: a real compiled Jaren query, never a reimplementation.
+`explain()` always says which is which.
+
+**Dispatch is exhaustive.** The planner switches on the AST's node
+kinds with no default branch that degrades silently: an unrecognised
+kind is an internal error naming the kind and the `AST_VERSION`. A
+construct that is *deliberately* not translated is a row in the table
+below, and that table's reasons are what `explain()` reports.
+
+### The translated set
+
+A single-binding FLWOR over the collection (`$for: { it: '$[*]' }`)
+with: comparison predicates (`$eq $ne $lt $le $gt $ge`) between a
+singular member path and a literal or external; `$and`/`$or`/`$not`
+composition; `$exists`/`$empty`; `$starts-with`/`$ends-with`/
+`$contains` on schema-typed string paths with literal patterns;
+`$orderby` over singular schema-typed paths (`$dir`, `$empty`, no
+collation); a top-level `$subsequence` window with literal bounds; the
+top-level aggregates `$count` (bare-binding return only) and
+`$sum`/`$avg`/`$min`/`$max` over a singular schema-typed path; and the
+whole-document projection `$return: '$it'`.
+
+### The deliberate-residual table
+
+| construct | reason |
+|---|---|
+| `$let` bindings, `$fold`, `$groupby`, positional/window bindings | no equivalence proof exists yet; residual by default |
+| a second `$for` binding, joins, non-singular path expansion | one relation per plan in this version |
+| `$match` and other unlisted operators, `$call` | no native spelling proven equivalent |
+| `$orderby` with a `$collation` | a collation the dialect cannot reproduce is refused, not approximated |
+| projections other than `'$it'` | run per row (the row residual) — pushed, ordered and windowed rows, projected by the engine |
+| string operators with an external pattern | the pattern's type is unknowable at plan time and the engine ERRORS on non-string patterns |
+| comparisons where both sides are paths | join territory |
+| array/object literals in comparisons | deep-equality has no guarded native form |
+| spatial predicates | no spatial index vocabulary in the model format |
+
+### The type truth table
+
+Jaren compares by JSON type; SQL engines by storage class and
+affinity. `jsonb_extract` returns SQL `NULL` for a missing member AND
+for a stored JSON `null` — only `json_type` tells them apart, so every
+translated predicate is guarded by it and is therefore **total
+(two-valued)**: `NOT`, `AND` and `OR` compose classically and SQL's
+three-valued `NULL` logic never reaches a result row. Probed engine
+facts the table encodes: a comparison against a missing member is
+`false` (even `$ne`); a cross-type `$eq` is `false` and a cross-type
+`$ne` against a PRESENT value is `true`; booleans do not order;
+string order is codepoint order (which is exactly SQLite's BINARY
+order over UTF-8);
+`$exists` is true for a stored `null`, `$empty` is true for a missing
+member.
+
+With `jt` = `json_type(doc, path)`, `v` = the compared value (the
+generated column where one exists), `?` = the bound operand:
+
+| Jaren predicate | emitted form |
+|---|---|
+| `$eq` path, number | `jt IN ('integer','real') AND v = ?` |
+| `$ne` path, number | `jt IS NOT NULL AND (jt NOT IN ('integer','real') OR v <> ?)` |
+| `$lt/$le/$gt/$ge` path, number | `jt IN ('integer','real') AND v op ?` |
+| `$eq` path, string | `jt = 'text' AND v = ?` |
+| `$ne` path, string | `jt IS NOT NULL AND (jt <> 'text' OR v <> ?)` |
+| `$lt/$le/$gt/$ge` path, string | `jt = 'text' AND v op ?` |
+| `$eq` path, `true`/`false` | `jt = 'true'` / `jt = 'false'` (no value bind) |
+| `$ne` path, `true`/`false` | `jt IS NOT NULL AND jt <> 'true'/'false'` |
+| `$eq` path, `null` | `jt = 'null'` |
+| `$ne` path, `null` | `jt IS NOT NULL AND jt <> 'null'` |
+| ordering vs `true/false/null` literal | constant `FALSE` (booleans and nulls do not order) |
+| `$exists` path | `jt IS NOT NULL` |
+| `$empty` path | `jt IS NULL` |
+| `$eq` path, external | `(jt = 'text' AND typeof(?) = 'text' AND v = ?) OR (jt IN ('integer','real') AND typeof(?) IN ('integer','real') AND v = ?)` |
+| `$ne` path, external | `jt IS NOT NULL AND NOT (…the $eq form…)` |
+| ordering vs external | the same two-branch form with `op` |
+| `$starts-with` path, string | `jt = 'text' AND substr(v, 1, length(?)) = ?` |
+| `$ends-with` path, string | `jt = 'text' AND (length(?) = 0 OR substr(v, -length(?)) = ?)` |
+| `$contains` path, string | `jt = 'text' AND instr(v, ?) > 0` |
+
+The guards make the forms sound for typed AND untyped paths alike —
+the schema type's job is choosing the generated COLUMN (the index),
+never weakening the guard. Two documented preconditions: string
+operators, aggregates AND ordering are only promoted on schema-typed
+paths because the engine ERRORS on non-conforming operands where SQL
+would coerce or sort — a stored `null` under an ordered key, a
+non-string under a string operator — so on an unvalidated store, rows
+violating the collection schema can make the engine throw where the
+database answers; keep `compileSchema` injected if that distinction
+matters to you.
+
+**Bind-time diversion.** SQLite cannot bind a boolean, and a
+`null`-valued external needs Jaren's null semantics, not SQL's. At
+execute time, if any referenced external is missing or not a string or
+finite number, the call runs the always-compiled set residual instead
+of the native statement — same answer, one branch, no wrong-typed SQL.
+
+### The two residual modes
+
+- **Row residual** — only the projection is untranslated: predicates,
+  ordering and the window are fully pushed; each fetched row runs
+  `{ $for: { it: '$[*]' }, $return: [ <the document's $return> ] }`
+  (the array wrapper keeps array-valued items unambiguous) and the
+  items concatenate in row order. Streams.
+- **Set residual** — anything else: the pushed predicate conjuncts
+  narrow candidates (`$and` splits; a partially translatable `$or`
+  does not), and the WHOLE original compiled document runs over the
+  materialized candidate array. Re-applying pushed conjuncts is
+  idempotent, so pushdown is pure narrowing. Reported as a barrier.
+
+### `explain()`
+
+Extends `compileJsonQuery(...).explain()`'s shape — `{ externals,
+operators, functions, collations, limits }` — with `{ sql, params,
+indexes, residual, barriers, scanNarrative }`. `params` lists the
+bound slots in order (external names and literal markers — values are
+ALWAYS bound, never interpolated). `indexes` names the declared
+indexes whose generated columns the pushed predicates and ordering
+touch, and the `scanNarrative` is the database's own `EXPLAIN QUERY
+PLAN` prose so the claim is checkable against the engine that will run
+it. `estimatedRows` is ABSENT on SQLite drivers — the capability slot
+is empty and no number is fabricated. `residual` is `null` or
+`{ mode: 'row' | 'set', reasons: [{ construct, reason }] }` with
+reasons drawn from the deliberate-residual table. With
+`strict: true`, any residual is instead the compile error `JD0010`
+naming the forcing construct.
+
+### The UDF escape hatch (capability-gated)
+
+Between native SQL and pulling rows sits registering a compiled
+predicate conjunct as a deterministic function used in the `WHERE`
+clause. Gated on `capabilities.userFunctions` (absent on Bun by
+construction) and applied only to fragments with no externals, no
+functions and no collations — deterministic and side-effect-free by
+analysis, not by hope. Registration is keyed by `contentKey(fragment)`
+so identical fragments share one registration, and the planner MUST
+produce a correct plan with the capability disabled (tested that way).
+Preference order: native SQL → deterministic function → residual, and
+`explain()` names the choice. **Index-form UDFs are deliberately not
+part of this**: an index over a registered function makes the database
+unwritable from any connection that has not registered the identical
+function — a WHERE-clause UDF carries no such schema dependency, and
+that operational hazard is why the model format declares no
+UDF-expression indexes.
+
+### The statement cache
+
+A caller of the core primitives, not an eighth implementation:
+`createBoundedCache` keyed by `contentKey(document)` plus collection,
+dialect and strictness. `contentKey` is the memo-grade key
+(`hashContent(stableStringify(x) ?? '')` — drops `undefined` members,
+no cycle guard; both properties acceptable for a cache key), never
+`canonicalizeJson` (signature-grade, throws on `undefined`).
+`store.stats()` exposes hits, misses and evictions, so the cache is
+proven rather than assumed.
+
+## The relational half (`src/model.js`, `src/plan.js` §entities, `src/query.js`)
+
+The same planner, a second document kind: entity query documents
+address the multi-entity root (`$.User[*]`), the ONLY shape a
+differential oracle can prove (the engine has no embedded relation
+members to walk — which is why relation-name sugar is deliberately
+absent from the query surface and lives on `load`). Three reference
+flavors decide emission: entity COLUMNS get total forms with no
+`json_type` guard (a mapped property has no present-null), entity
+EPOCH columns get a ±1 s index range plus the exact document-string
+recheck (mixed stored precisions can never diverge from the engine's
+codepoint order), and everything else rides the phase-A guarded truth
+table aliased per binding. Two-binding equijoins emit INNER JOIN with
+binding-order row-identity tiebreakers — exactly the engine's
+nested-loop order. The graph loader compiles include trees to
+correlated `json_group_array`/`json_object` subqueries: one statement
+per load, proven by a counting driver, never promised.
+
+## The unit of work (`src/tracker.js`)
+
+Materialised entities are deep-frozen plain JSON and the frozen
+document IS the snapshot — one retained reference, structural sharing
+made safe by the freeze. `saveChanges()` diffs with the suite's own
+diff engine and maps operations to minimal statements (column writes,
+`jsonb_set` chains, join-table key-set sync, a counted whole-row
+fallback); inserts batch parent-first, deletes run child-first,
+foreign-key cycles among the changed set are `JD0040`, and a declared
+`version` property turns every update into an optimistic
+`WHERE version = ?` with `JD2040` on conflict. The tracker mutates
+ONLY after commit: a failed save retries.
+
+## The migration engine, relationally (`src/migrate.js`, `src/cli.js`)
+
+The strategy-table diff renders SELF-CONTAINED steps — additive
+columns, data steps, and one rebuild implementation following
+SQLite's documented twelve-step procedure with `foreign_key_check`
+inside the transaction. Shape EQUALITY (schemaShapeOf versus a fresh
+createModelShape build) is the acceptance criterion, asserted on the
+shadow before the real database is touched and again after. Probed
+and designed around: node:sqlite enables foreign keys BY DEFAULT (the
+pragma bracket is load-bearing), `jsonb()` PARSES its argument
+(column folds pass plain SQL values), and a table rename does not
+rename columns (join tables rename their endpoint keys explicitly).
+
+## One cross-runtime seam worth remembering
+
+`bun:sqlite` answers **null** for a missing row where `node:sqlite`
+answers undefined; the bun adapter normalizes at the seam (and the
+bun-shaped test double mimics the null so the packed run pins it).
+Found by the ORM benchmark's first real-Bun file-store open — the
+in-memory tests never reopen a database, so create-or-verify had
+never seen bun's null.
+
+## Change capture (`src/capture.js`)
+
+Every committed write becomes an ordered stream of RFC 6902 patches.
+Two sources behind one contract: SQLite's **session changeset** where
+the binding exposes `createSession` (node:sqlite), parsed from its
+binary format by a hand-written decoder; a **write-path journal**
+where it does not (bun:sqlite, the wasm build), buffering before/after
+documents as the store writes them. Both net ONE op per row — insert+
+update coalesces, insert+delete vanishes, an update back to the
+original emits nothing — so the two modes agree as SETS (a differential
+test pins it). The journal's netting was added when the wasm parity
+suite ran a same-row multi-op transaction the original differential
+script never wrote. Op order within a record is UNSPECIFIED; every op targets
+a distinct pointer. The persisted `_jaren_changes` log rides the same
+transaction as the writes it describes; a caught inner-savepoint
+rollback truncates the journal buffer to its checkpoint. Overhead is
+measured and published: capture off ~6µs, journal ~17µs, session ~69µs
+per single-op commit, amortizing across a transaction.
+
+## Live queries (`src/live.js`, `src/window.js`)
+
+A live query classifies its document against the normative maintenance
+table by reading the COMPILED PLAN — translated filters, order terms
+and aggregates are exactly the planner's, never re-derived. Five
+strategies: incremental **rows** (per-key items, arrival order), the
+maintained **window** (all matching rows sorted, ties by key token, a
+delete inside the visible slice answered without re-query), running
+**accumulators** (per-row contributions retained so a capture `remove`
+— which carries no old value — is still answerable; min/max recompute
+over contributions when the extremum's holder leaves), per-group
+**deltas** (the accumulator machinery once per group), and **re-run**
+for everything else — declared, reported through `live.mode`, never
+silent. Invalidation matches a record by table plus pointer prefix,
+over-approximating toward re-evaluation (a missed update would be a
+correctness bug; an extra one is only slower). Emissions preserve
+reference identity for untouched rows — the O(k) renderer's contract —
+proven by a seeded oracle that holds the maintained result equal to a
+fresh re-query after every mutation. Incremental beats re-run 13× at
+1k rows, 51× at 10k.
+
+## Durable runs and the job queue (`src/jobs.js`, `src/dag-job.js`)
+
+The queue's whole correctness story is one guarded statement: the
+claim UPDATE selects the earliest eligible row (pending, failed, or an
+expired lease — so recovery IS the next claim, not a sweeper) whose
+kind the worker registered, sets it leased with a deadline, and
+RETURNs it. One statement is one transaction, so no two workers claim
+the same job without any distributed lock; every later transition
+wears `state='leased' AND lease_owner=?`, making execution
+at-least-once and completion exactly-once (proven by four workers on
+four connections over one WAL file). The `@jarenjs/flow` composition
+injects `compileDag` (db never imports flow — an import-graph test
+enforces it) and binds a per-job checkpoint store; a DAG run's
+completion records the result, marks the job done and prunes the
+checkpoint rows in ONE transaction, so a crash resumes from its
+checkpointed nodes rather than restarting. Non-goals stated plainly: a
+shared SQLite file over a network filesystem is not a safe
+coordination substrate.
+
+## The wasm driver (`src/drivers/wasm.js`)
+
+An injected handle, never an import: the host loads the official
+SQLite wasm build and this driver adapts its `oo1` object API — which
+is SYNCHRONOUS in a dedicated worker over the SAH-pool OPFS VFS, which
+is exactly what keeps journal capture, live queries and the job queue
+working unchanged in a browser. The engine parity is proven in Node
+against the real wasm bytes (the full pushdown oracle, entities, live
+queries, jobs, a shadow-verified migration); the browser suite proves
+the ENVIRONMENT — OPFS persistence across reloads, the owner topology
+(one context holds the sole connection, tabs are clients over a
+BroadcastChannel), and the second-writer refusal — across Chromium,
+Firefox and WebKit, with the memory fallback stated where OPFS is
+absent.

package/README.md

@@ -0,0 +1,218 @@
+# @jarenjs/db
+
+Documents AND entities in SQLite. A **model document** declares
+collections (a JSON Schema, a key, indexes) and — since phase B —
+**entities**: keys, typed columns, relations, defaults and an
+optimistic-concurrency token, all inside the schema through the
+`x-entity` vocabulary. `openStore` applies the physical mapping
+through a dialect and gives transactional, schema-validated reads and
+writes; queries arrive as plain Jaren query documents (usually
+written through `@jarenjs/linq`) and are **pushed down to SQL** where
+equivalence is proven, with everything else running honestly in the
+engine. The same code runs on Node, on Bun, and in a browser against
+an injected wasm handle, with zero dependencies outside `@jarenjs/*`.
+
+**The honest framing, first**: Prisma, Drizzle and Kysely are mature,
+support several databases, and are faster on some benchmark rows —
+those losses are published on the suite page with their reasons. What
+none of them has is a query that is one serializable JSON document,
+executable by two independent engines proven to agree by a
+differential oracle, running unchanged in Node, Bun and the browser,
+with schema-validated writes from the fastest validator in the
+ecosystem. The composition is the product; the individual numbers are
+what they are.
+
+```js
+import { openStore } from '@jarenjs/db';
+import { nodeDriver } from '@jarenjs/db/node';
+
+const store = await openStore({
+  $model: '0.1',
+  collections: {
+    users: {
+      schema: {
+        type: 'object',
+        required: ['id', 'email'],
+        properties: {
+          id: { type: 'string' },
+          email: { type: 'string', format: 'email' },
+          age: { type: 'integer' },
+        },
+      },
+      key: '/id',
+      indexes: [{ name: 'by_age', path: '$.age' }],
+    },
+  },
+}, { driver: nodeDriver(), path: 'app.db' });
+
+const users = store.collection('users');
+await users.insert({ id: 'u1', email: 'ada@example.test', age: 36 });
+
+// a query document — here written by hand; linq writes the same thing
+const adults = await users.execute({
+  $for: { it: '$[*]' },
+  $where: { $ge: ['$it.age', 21] },
+  $return: '$it',
+});
+```
+
+- **The pushdown planner with `explain()`.** A query compiles through
+  the engine's published AST into a dialect-neutral plan and renders
+  to guarded, parameter-bound SQL; whatever cannot be proven
+  equivalent runs as a real compiled Jaren query (the residual), and
+  `explain()` always says which is which — the SQL, the bound
+  parameters, the indexes used (verified against the database's own
+  plan output), and the residual's named reasons. A 418-run
+  differential oracle keeps both paths agreeing. `strict: true` turns
+  any residual into a compile error.
+- **Registered operators, correct in the residual, pushed where it
+  pays.** Open with a registry (`operators:
+  createJsltRegistry().use(mathPack).use(financePack)`) and a query may
+  use `$npv`, `$mean`, `$sqrt`, … over stored documents. Each runs
+  correctly in the residual — identical to the in-memory engine,
+  `explain()` names it. The `pushable:'scalar'` subset (the math ops) is
+  additionally accelerated into SQLite as **deterministic UDFs** where
+  the driver allows (node:sqlite yes; bun:sqlite has no UDF API and stays
+  the residual — reported by `capabilities.pushableOperators`). Pushdown
+  is a large win beside a selective native predicate or a `LIMIT` (3.9×,
+  615× measured) and a wash on a solo full-table computed predicate —
+  published honestly in MODEL-FORMAT §8.2, not gated behind a cost model
+  SQLite gives no row estimates to build. A first-class operator is
+  allowed under a profile by default (which also blocks host-side UDF
+  registration for untrusted documents); the profile's `functions`
+  allow-list still governs a `$call`-reached `fn`; the row bound still
+  fires. Without a registry the store is unchanged — `$npv` is `JQ0002`.
+- **Storage is declarative.** Indexed paths become generated columns
+  plus real indexes, typed from the collection's schema. Opening an
+  existing database verifies the declared shape and refuses to alter
+  it — reshaping is the migration story.
+- **Migrations are documents.** `planMigration` diffs two models into
+  rendered-DDL + JSLT-transform + assertion steps; a shadow database
+  replays the whole chain before the real store is touched; a
+  checksummed history refuses edited or reordered migrations; a
+  narrowing without an adequate transform is refused against the REAL
+  data, inside the transaction.
+- **The safe profile.** Untrusted query documents run under composed
+  bounds: engine limits on the residual, a mandatory row bound that
+  refuses rather than truncates, reference allow-lists, optional
+  full-scan refusal, and per-collection mandatory predicates no
+  document shape can shed. Read-only stores refuse writes at the
+  driver.
+- **Writes validate** through an injected hook; without one,
+  `store.capabilities.validated` is `false` and the docs say what that
+  costs. The public API is asynchronous (the browser's OPFS story
+  forces it) with a promise-free `store.sync` twin where the driver is
+  synchronous.
+
+## What SQLite-only means, frankly
+
+SQLite is the supported backend — 3.45 or newer, on `node:sqlite`,
+`bun:sqlite`, or your injected wasm build — and nothing else is
+promised. The dialect seam exists and is tested against a double, but
+no second dialect ships. Concretely: there is **no statement timeout**
+(the drivers expose no interrupt; the capability slot is honestly
+`false`), no server, no replication, and cross-process concurrency is
+SQLite's own story (WAL plus a busy timeout, both set and visible on
+`store.capabilities`).
+
+## The relational half (phase B)
+
+- **Entities and relations** (`x-entity`, MODEL-FORMAT §9): hybrid
+  rows — key and mapped scalar columns beside one JSONB document —
+  with real foreign keys (`PRAGMA foreign_keys` set AND verified),
+  all three relation kinds, and derived epoch columns for indexed
+  instant ranges.
+- **One-statement graph loads** (§10): `entity('User').load({ include:
+  { posts: { include: { comments: true } } } })` runs in exactly ONE
+  statement regardless of depth or parent count — asserted by a
+  counting driver in the tests, and published with statement counts
+  beside the timings on the benchmark page. Keyset pagination when
+  the ordering allows it, reported, never silent.
+- **The unit of work** (§11): reads are plain deep-frozen JSON (no
+  proxies, asserted); mutation is replacement; `saveChanges()` diffs
+  snapshots into minimal parameterised statements in one transaction,
+  with insert batching, `JD0040` cycle refusal, `JD2040` optimistic
+  conflicts, and a report of every statement, fallback and count.
+- **Generated types**: `entityEmitModel` + `@jarenjs/emit` render the
+  model into entity interfaces, input variants and an `EntityMetaMap`;
+  `typedStore` (from `@jarenjs/db/typed`) types every read, checks
+  every write, and widens `load` results by their include
+  specification.
+- **Relational migrations and the `jaren-db` CLI** (MIGRATION-FORMAT
+  §§9–12): the strategy-table diff, the documented twelve-step table
+  rebuild with `foreign_key_check` inside the transaction, shape
+  EQUALITY against a fresh build as the acceptance criterion, drift
+  detection, and `jaren-db check` for CI.
+
+## The reactive and durable half (phase C)
+
+- **Change capture** (LIVE-FORMAT §§1–6): every committed write
+  becomes an observable stream of RFC 6902 patches — from SQLite's
+  own session changesets where the binding has them, from a write-path
+  journal where it does not (`bun:sqlite`, the wasm build). One diff
+  format runs store → patch → live query → O(k) render. Capture is
+  opt-in; the overhead is published, not waved away.
+- **Live queries** (LIVE-FORMAT §§7–12): `collection.live(document)`
+  maintains a result as writes arrive and emits patches — incremental
+  for `where`/`select`/`orderBy`+`limit`/aggregates/single-level
+  `groupBy` (the normative maintenance table), re-run for everything
+  else, **declared, never silent** (`live.mode` names the reason).
+  Unaffected rows stay reference-identical; a seeded oracle holds the
+  maintained result equal to a fresh re-query after every mutation.
+- **Durable runs and the job queue** (JOBS-FORMAT, FLOW-FORMAT §7.6):
+  a `@jarenjs/flow` DAG run checkpoints declared nodes and RESUMES
+  after a crash; `store.jobs` leases work in one guarded statement
+  (exactly-once completion, no distributed lock), retries with
+  backoff, dead-letters, and reclaims expired leases as recovery.
+- **The browser** (`@jarenjs/db/wasm`): the same store, the same
+  queries, the same live updates run on the official SQLite wasm build
+  over the header-free OPFS SAH-pool VFS — one tab owns the
+  connection, others are clients. Proven in the `#/data` studio across
+  Chromium, Firefox and WebKit.
+
+## Sync-readiness — what exists and what does not
+
+The change stream is an ordered log of RFC 6902 patches with a
+monotonic sequence, and SQLite's own changeset/conflict primitives are
+available — which is what a replication protocol would be *built
+from*. **No replication is shipped.** There is no conflict resolution,
+no site identity, no causal ordering across writers, and no capture of
+writes made by another connection (the coarse `dataVersion()` signal
+is the honest mitigation, not a pretend fine-grained one). Building
+replication on these primitives is a roadmap item, not a hint.
+
+## What this is not — every non-claim in one place
+
+- **SQLite only.** One backend (3.45+); the dialect seam is tested
+  against a double but no second dialect ships. No server.
+- **No replication or sync engine** (see above). No cross-connection
+  change capture — another connection's writes are invisible locally.
+- **No statement timeout** on SQLite (the drivers expose no interrupt;
+  the capability slot is honestly `false`), no row estimates.
+- **Not safe for mutually hostile tenants** without the profile's
+  mandatory predicate — SECURITY states the claims and non-claims.
+- **The job queue is one database, one machine.** A shared SQLite file
+  over a NETWORK FILESYSTEM (NFS, SMB, many container volume mounts) is
+  NOT a safe coordination substrate — SQLite's locking is unreliable
+  there. Same-host processes over WAL are the supported topology. No
+  priority classes, no cron, no workflow compensation.
+- **Live-query maintenance is limited to the declared table** (§7);
+  joins, entity queries and non-canonical shapes re-run, reported.
+- **The wasm build journals** (its session extension is not yet
+  adapted); OPFS needs a secure context, and where it is absent the
+  store runs in memory with the durability difference stated.
+- **Named future work, not silent gaps**: `$groupby` pushdown,
+  relation-name query sugar, a many-to-many membership API, incremental
+  joins, other SQL dialects, replication, database introspection
+  (MODEL-FORMAT §10.6, the roadmap).
+
+The normative formats are
+[docs/MODEL-FORMAT.md](docs/MODEL-FORMAT.md) (storage §§1–7, safe
+profile §8, entities §9, relational translation §10, the unit of work
+§11), [docs/MIGRATION-FORMAT.md](docs/MIGRATION-FORMAT.md) (documents
+§§1–8, relational changes §§9–12),
+[docs/LIVE-FORMAT.md](docs/LIVE-FORMAT.md) (capture §§1–6, live queries
+§§7–12) and [docs/JOBS-FORMAT.md](docs/JOBS-FORMAT.md) (the durable
+queue §§1–9); the seams, the pushdown contract and every engine are in
+[ARCHITECTURE.md](ARCHITECTURE.md); the benchmark methodology is in
+[benchmark/README.md](../../benchmark/README.md).