@jarenjs/db 0.84.3 → 0.86.0

package/ARCHITECTURE.md

@@ -1167,8 +1167,10 @@ calls with different bound values.
 `physical.js` compiles column codecs and verifies declarations against that
 inventory. The existing entity core, tracker and graph row merger execute both
 hybrid and column layouts; there is no separate relational store. The query
-planner reports decoded evaluation for physical codecs, and refuses physical
-keyset continuation until its identity semantics are qualified.
+planner preserves codec semantics through qualified native plans and explicit
+residuals, and refuses physical keyset continuation until its identity semantics
+are qualified. Present-null scalar predicates and safe fluent projection
+flattening join this native subset; strict binding failures stop before a scan.
 
 `sql.js` binds trusted statements to `store.js` transaction views. It reuses the
 read classifier's tokenizer and the driver's scope owner. Writes invalidate all
@@ -1176,6 +1178,28 @@ clean tracked entities; pending edits and incomplete capture populations refuse.
 `invariants.js` uses the shared Query compiler for store rules; the dialect lowers
 a bounded database subset into ordered trigger bodies. `migrate.js` reuses its
 existing rebuild/receipt transaction and verifies preservation before publication.
-The backup publisher remains shared by Node online and Bun serialized snapshots.
+The backup publisher uses Node online backup and Bun disk-backed VACUUM INTO.
+The standalone snapshot helper shares destination reservation and cleanup across
+both hosts, including transaction failures.
 
 `src/search.js` composes core lexical mechanics and the JSON predicate compiler over complete bounded entity snapshots. Committed capture and data-version checks invalidate derived state; SHA-256 source content validates persisted caches across reopen. Snapshot storage uses existing collection transactions. See [search execution](docs/SEARCH.md); native full-text dialects remain unqualified.
+
+`dialects/sqlite-relational.js` owns the explicit SQLite expression and statement
+compiler; `dialects/sqlite-schema.js` reuses it for ordered tables, indexes and
+triggers. `table-migration.js` owns reviewed source/target guards, native copying
+and preservation checks, with catalog/pragma spellings in the SQLite dialect.
+The supplied driver owns transactions and cursors. These programs are explicitly
+SQLite-semantic and never enter the JSON residual evaluator. See
+[the native SQLite contract](docs/SQLITE-RELATIONAL.md).
+
+`engine-metadata.js` holds inert version/table constants so schema inspection
+does not import runtime owners. `/query`, `/model` and `/entity` expose those
+mechanisms without the root store import. `compileEntityModel` performs one model
+normalization for both entities and mapping; openStore reuses that result.
+
+`drivers/worker-client.js` and `drivers/sqlite-endpoint.js` own the shared bounded
+RPC contract. Thread and process entries supply their transports. The process
+driver retains owner credits until OS exit, fences lost generations, and combines
+observed native transaction state with pending statement metadata to distinguish
+rollback from an unknown commit. Supervision never serializes callbacks or replays
+transactions; Store ownership remains in the existing driver/Store gates.

package/README.md

@@ -888,7 +888,8 @@ oracle run on both. What differs is declared rather than discovered:
 | `ALTER TABLE` | additive only | full, so a rebuild is never needed |
 
 Neither backend has a **statement timeout** (`capabilities.statementTimeout`
-is `false` on both) or **row estimates**. There is no replication.
+is `false` on both) or **row estimates**. Portable replication uses SQLite
+change capture; PostgreSQL capture and replication remain unqualified.
 Cross-process concurrency on SQLite is its own story — WAL plus a busy
 timeout, both set and visible on `store.capabilities`; on PostgreSQL it
 is the server's, and a serialization failure or a deadlock arrives as
@@ -1211,16 +1212,18 @@ same report rows — with the one difference the PostgreSQL mapping
 states: `numeric` carries both JSON number types, so an `integer`
 member reads back as `number`.
 
-## Sync-readiness — what exists and what does not
+## Replication and external-write boundaries
 
-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.
+The portable replication engine supplies replica identities, causal frontiers,
+bounded logical envelopes, durable replay receipts, conflict evidence and snapshot
+resets. Data and acknowledgements commit together; hosts supply transport and any
+conflict resolver. The default preserves both contenders and rejects the write.
+See [REPLICATION-FORMAT](docs/REPLICATION-FORMAT.md) for the current contract.
+
+Capture observes participating Store writes on supported SQLite hosts. Arbitrary
+writes from another connection are not fine-grained capture events; `dataVersion()`
+provides coarse invalidation. Adopted triggers, unsupported layouts and PostgreSQL
+retain the explicit capture and replication qualification limits.
 
 ## Operating a store — configuration, maintenance, backup, cancellation, the queue
 
@@ -1311,10 +1314,11 @@ its side-effect-free status read are in
 
 ## 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.
+- **SQLite and PostgreSQL have different capabilities.** Both backends ship;
+  PostgreSQL does not provide the SQLite capture, replication, job queue or pragma
+  maintenance capabilities. See the dialect table and normative host contracts.
+- **Replication transport is supplied by the host.** Portable logical replication
+  ships; arbitrary external writes are not captured as local row events.
 - **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
@@ -1359,6 +1363,7 @@ Every subpath a consumer can import, derived from the manifest by
 <!--fact:exports.db-->
 | Import | Kind | Declarations |
 |---|---|---|
+| `@jarenjs/db/node-process` | JavaScript | declared |
 | `@jarenjs/db/search` | JavaScript | declared |
 | `@jarenjs/db` | JavaScript | declared |
 | `@jarenjs/db/node` | JavaScript | declared |
@@ -1379,6 +1384,10 @@ Every subpath a consumer can import, derived from the manifest by
 | `@jarenjs/db/package.json` | metadata | — |
 | `@jarenjs/db/node-worker` | JavaScript | declared |
 | `@jarenjs/db/node-pool` | JavaScript | declared |
+| `@jarenjs/db/relational` | JavaScript | declared |
+| `@jarenjs/db/query` | JavaScript | declared |
+| `@jarenjs/db/model` | JavaScript | declared |
+| `@jarenjs/db/entity` | JavaScript | declared |
 <!--/fact-->
 
 
@@ -1431,3 +1440,15 @@ SQLite constraint/audit triggers for installation through that migration boundar
 Native column reads and bounded mutation documents are specified in [NATIVE-PLANS](docs/NATIVE-PLANS.md), including SQL census coverage, resource accounting and refusals.
 
 `@jarenjs/db/search` composes the resident ranker with bounded authoritative entity reads and optional atomic snapshot storage. See [persisted search](docs/SEARCH.md).
+
+Column-first table definitions, guarded same-connection rebuilds, exact matched writes,
+partial conflicts, raw-text JSON queries and byte-valued operations use
+[`@jarenjs/db/relational`](docs/SQLITE-RELATIONAL.md). Both host entries export
+`snapshotDatabase(connection, newPath)` for a disk-backed committed-WAL copy.
+Existing-connection consumers can import `/query`, `/model` and `/entity`;
+`compileEntityModel` shares one normalization between queries and mapping.
+
+`@jarenjs/db/node-process` adds supervised native execution with finite owner
+admission, caller deadlines, generation fencing and separate process-exit and
+transaction-fate observations. See [execution hosts](docs/HOSTS.md#supervised-node-processes)
+for Store composition, receipt reconciliation and operating-system limits.

package/docs/HOSTS.md

@@ -77,6 +77,132 @@ run on the caller. Synchronous Store methods and live queries are unavailable on
 these asynchronous connections. Bun can import both subpaths; opening a Node
 SQLite worker there reports the named unavailable-binding failure (`JD0003`).
 
+## Supervised Node processes
+
+`nodeProcessDriver` from `@jarenjs/db/node-process` implements the same asynchronous
+Driver and Connection contracts using one Node child process per connection. It
+shares the worker protocol, cursor credits, transaction scopes and error handling
+with the thread driver. SQLite and its native calls execute in the child; callbacks
+and decoded query residuals still execute in the parent. No function is serialized.
+Node.js 24 or newer is required. Bun can import the entry but `open` refuses with
+`JD0003`. The native-call and process-lifecycle fixtures qualify Node 24.20.0 on
+Linux; other supported operating systems require their own timing qualification.
+
+```js
+import { nodeProcessDriver } from '@jarenjs/db/node-process';
+
+const driver = nodeProcessDriver({ maxOwners: 2, timeoutMs: 250 });
+const owner = await driver.open('application.sqlite', { timeout: 50, queueTimeout: 100 });
+try {
+  const result = await owner.supervise(async (connection) => {
+    return connection.transaction(async (scope) => {
+      const statement = await scope.prepare('SELECT value FROM settings WHERE key = ?');
+      return statement.get(['theme']);
+    });
+  }, { signal: requestSignal, timeoutMs: 250 });
+  useResult(result);
+} catch (error) {
+  if (error.code === 'JD2097' || error.code === 'JD2090') {
+    const observation = owner.settlement();
+    // This snapshot can still say quarantined / safeToReplace:false.
+    recordOwnerObservation(observation);
+    const exited = await owner.settled();
+    // Before repeating an uncertain write, inspect its durable receipt.
+    reconcileBeforeRetry(exited);
+  } else throw error;
+} finally {
+  // Preserve the original operation outcome if closing a fenced generation fails.
+  await owner.close().catch(recordCleanupFailure);
+}
+```
+
+`supervise(body,{signal,timeoutMs})` admits one supervised callback per connection.
+An overlapping callback refuses with `JD2091`; an already-aborted call runs no
+callback and leaves the owner healthy. A deadline or abort rejects with `JD2097`,
+fences all pending calls and signals process termination. Later operations on the
+old generation fail with `JD2090`. A normal callback failure propagates unchanged
+and does not terminate a healthy owner. `cancel(reason)` explicitly fences the
+whole connection and returns its cancellation error. It affects every call sharing
+that owner, so independent request lifetimes should use separate owners.
+
+This is response cancellation and owner termination, not a SQLite statement
+interrupt. `capabilities.process` and `ownerTermination` are true, while
+`capabilities.cancellation.midStatement` remains false. The supervision timer cannot
+preempt synchronous parent JavaScript or bound operating-system scheduling. Keep
+callbacks/residuals bounded and await all admitted work. Native fixtures use a
+short deadline and independently enforce a one-second caller-response ceiling;
+that tested ceiling is not a universal scheduling guarantee.
+
+`settlement()` reports the generation, PID, health, transaction fate and
+`safeToReplace`. `settled()` resolves only after the child's OS exit event. An
+owner awaiting termination is quarantined and still consumes its credit. If the
+OS cannot settle a process promptly, the response can finish while the owner
+remains quarantined; neither capacity nor writer ownership is recycled. `restart()`
+waits for confirmed exit and returns a new generation; old Store handles remain
+invalid. No statement, transaction or callback is automatically replayed.
+
+The transaction observation is conservative:
+
+- A live, acknowledged native transaction is `active`.
+- An acknowledged single-statement completion is `committed`, or `rolled-back`
+  after rollback. A multi-statement program with no open transaction remains
+  `unknown`: an acknowledgement alone cannot distinguish its internal boundaries.
+- Confirmed process death rolls back an observed open transaction only when no
+  pending operation could have committed it.
+- A lost commit reply, multi-statement program or uncertain autocommit mutation
+  is `unknown`. Native transaction-state support is observed, never inferred from
+  a close promise. Reopen, verify integrity and reconcile a durable receipt before
+  retrying a write with an unknown outcome.
+
+Autocommit mutation cursors remain `unknown` until their final native frame is
+acknowledged. Creating an iterator or receiving an intermediate `RETURNING` row
+does not acknowledge completion; early cursor return still requires reconciliation.
+
+Driver `metrics()` reports capacity, owners, healthy owners and quarantine. A
+file path already owned by the same driver cannot be opened again until exit;
+this reservation uses its resolved path spelling, not filesystem inode identity.
+Different driver instances, aliases and external processes remain the host's
+coordination responsibility. Use one supervisor per ownership domain and retain
+finite SQLite busy and transaction-queue timeouts. The host's service manager must
+also own its process group: an uncatchable parent-process death is not a promise
+that JavaScript can reap every descendant. Child crashes and restart are covered
+by the file/receipt fixtures; power loss and service-manager policy are separate.
+
+The ordinary Store composition uses `openStore(model,{driver,path})`. To supervise
+Store calls, retain the connection in a small driver wrapper's `open` method, then
+call `owner.supervise(() => store.transaction(body), options)`. This uses the same
+Store and transaction APIs. After owner loss, close the invalid Store, await owner
+exit and explicitly reopen/reconcile. A failed-generation `close()` may reject;
+its rejection never substitutes for the separate exit observation.
+
+All options below are positive safe integers. Row/byte/statement/cursor limits
+retain the thread worker meanings. `maxOwners` includes startup and quarantine;
+`timeoutMs` is the default supervised response deadline. `maxRequestBytes` bounds
+each outgoing request before IPC; parameters must be SQLite scalars or byte arrays.
+The process close deadline
+and startup deadline can reject while termination is still pending. The reserved
+owner credit remains until exit. Direct calls without `supervise`
+retain the ordinary row, queue and step cancellation boundaries.
+
+<!--fact:db.execution-options-->
+
+| Option | Thread worker | Process owner |
+|---|---:|---:|
+| `windowRows` | 64 | 64 |
+| `windowBytes` | 1048576 | 1048576 |
+| `maxPending` | 64 | 64 |
+| `maxStatements` | 1024 | 1024 |
+| `maxCursors` | 64 | 64 |
+| `allMaxRows` | 100000 | 100000 |
+| `allMaxBytes` | 16777216 | 16777216 |
+| `closeTimeoutMs` | 5000 | 1000 |
+| `startupTimeoutMs` | 10000 | 10000 |
+| `maxOwners` | — | 4 |
+| `timeoutMs` | — | 250 |
+| `maxRequestBytes` | — | 1048576 |
+
+<!--/fact-->
+
 ## WAL pool policy
 
 A file pool opens exactly one writer and `readers` read-only workers, verifies WAL,
@@ -283,9 +409,10 @@ sync twin. Physical adoption on PostgreSQL refuses pending a separate mapping
 and codec qualification. Unknown application-trigger effects do not qualify
 capture or replication; those combinations refuse before an adoption claim.
 
-Node backups use the built-in online snapshot. Bun uses `Database.serialize()`
-under the store gate, writes and flushes a sibling temporary, then uses the shared
-atomic publisher. Both include committed WAL. Bun's snapshot holds the whole
-image in memory and cancellation takes effect between phases. Process-kill tests
+Node backups use the built-in online snapshot. Bun uses disk-backed `VACUUM INTO`
+under the store gate, flushes a sibling temporary, then uses the shared atomic
+publisher. Both include committed WAL. Bun allocates no whole-database JavaScript
+image; native SQLite caches and temporary storage govern working memory, and
+cancellation takes effect between phases. Process-kill tests
 cover rebuild copy, table drop, commit and backup publication on both hosts;
 these tests do not establish power-loss durability or native executable packaging.

package/docs/MODEL-FORMAT.md

@@ -1101,6 +1101,7 @@ error.
 | `JD2094` | invalid or uncommitted durable snapshot; reopen the last committed version |
 | `JD2095` | trusted SQL or synchronous callback authority refused |
 | `JD2096` | persistence invariant rejected the mutation; constraint class |
+| `JD2097` | supervised native operation cancelled or past its response deadline; owner exit and transaction fate are reported separately |
 | `JD0060` | a replication envelope or snapshot is invalid |
 | `JD2100` | a replica sequence or causal dependency has a gap |
 | `JD2101` | an envelope identity names different content or an unknown local origin |
@@ -2352,7 +2353,9 @@ relation navigation across physical layouts is not qualified.
 | `decimal` | exact decimal string, including trailing zeros | TEXT |
 | `blob-hex` | lowercase hexadecimal string | BLOB |
 
-Unsafe narrowing refuses `JD2003`. A byte handle never enters the public entity.
+Unsafe narrowing refuses `JD2003`. A byte handle never enters the JSON-facing entity;
+[the native SQLite channel](SQLITE-RELATIONAL.md#exact-writes-and-bytes) preserves
+Uint8Array/Buffer values on the same synchronous connection.
 `null: "null"` maps SQL NULL to present JSON null; `"absent"` omits the property;
 `"reject"` refuses it. With the JSON codec, JSON null is stored as the text `null`,
 so SQL NULL can independently mean absence. `default: "database"` omits an absent
@@ -2361,9 +2364,10 @@ writes to the database. A generated integer identity uses the existing
 `x-entity.default: "auto"` declaration. Direct updates with identical values and
 identical tracked saves produce no effective writes.
 
-Mapped query documents execute through the existing decoded-row evaluator;
-explanations report this residual and strict pushdown refuses it. Scalar graph
-loads use mapped names; complex codec predicates require query documents.
+Mapped query documents use the qualified native subset in [NATIVE-PLANS](NATIVE-PLANS.md).
+Present-null scalar equality/ranges preserve Jaren semantics. Unsupported codecs
+and shapes retain explicit residuals; strict mode also rejects unsupported bound
+externals before fetching rows. Scalar graph loads use mapped names.
 Physical `page` and `after` continuation refuse until codec-aware keysets are
 qualified; an explicit `take`/`skip` load remains available.
 Capture/live/replication for adopted application triggers is not qualified and
@@ -2414,3 +2418,10 @@ must stay in the safe-number range.
 ## Native column mutation documents
 
 Asynchronous entity sets expose `mutate(document)` for conditional updates, conflict-aware upserts and bounded same-entity insert-select. The closed grammar, no-op/revision behavior, output bounds and transactional qualifications are specified in [NATIVE-PLANS](NATIVE-PLANS.md).
+
+Explicit physical DDL metadata and live-schema migration planning are specified
+in [SQLITE-RELATIONAL](SQLITE-RELATIONAL.md#physical-schema-ownership). Opening a
+physical entity retains adoption-only behavior. Public plans create complete
+ordered declarations; an incomplete generated/default definition or view remains
+adoption metadata. SQLite expressions preserve a separate, explicit semantic
+contract for raw text, bytes, nulls, collations and floating totals.

package/docs/NATIVE-PLANS.md

@@ -49,6 +49,13 @@ Floating sums/averages and date/datetime grouping remain residual. Physical text
 comparisons explicitly use codepoint collation, independent of a column's declared
 collation; an incompatible index may therefore stop helping that query.
 
+Safe identity/object projection chains, including a projected join followed by
+filtering and ordering, flatten without crossing windows, grouping or inner
+ordering. Standalone min/max over supported scalar columns and sum/avg over safe
+integer columns now lower natively, preserving empty-sequence and present-null
+errors. Missing or unbindable external values refuse strict execution and both
+cursor APIs before any decoded fetch; a nullable slot accepts explicit null.
+
 `explain` reports the emitted SQL, scan narrative, profile bounds and last
 execution's admitted statement/returned-row/serialized-wire-byte counts. These
 are application admission costs. SQLite does not expose visited-row counts or
@@ -73,12 +80,13 @@ const result = await store.entity('Inventory').mutate({
 });
 ```
 
-The three operations are:
+The operations are:
 
 | Operation | Required document members | Meaning |
 |---|---|---|
-| `update` | `key`, `set`; `expectedRevision` for a versioned entity | Complete primary key and revision predicate; writes only changed columns and increments the revision once. Missing/stale/identical rows yield zero affected rows. |
-| `upsert` | `values`, `conflict`, `update` | Insert or update the named supplied members only if their stored values differ. `conflict` is the complete ordered primary key. |
+| `update` | `key` and/or `where`, `set` and/or `expressions`; `expectedRevision` for a versioned entity | Exact assignments with an atomic predicate. Default changed reporting suppresses identical writes; `reporting: 'matched'` executes them. A declared version increments once on a write. |
+| `upsert` | `values`, `conflict`; `update` or `onConflict: 'nothing'` | Ordered logical conflict columns may name a non-primary UNIQUE identity; `conflictWhere` matches a partial index. Default changed reporting suppresses identical updates. |
+| `delete` | `key` and/or `where`; `expectedRevision` for a versioned entity | One conditional or bulk delete, with the same transactional output bounds. |
 | `insert-select` | `source`, `where`, `select`, `conflict`, `onConflict: 'nothing'` | Same-entity scalar/literal projection, bounded source rows, conflict-ignore insertion. Source and target path codecs and NULL policies must match. |
 
 `returning` is a nonempty list of logical stored members (default: all). `maxRows`
@@ -92,14 +100,23 @@ before insertion, even if all rows would conflict. Output bounds and codec/schem
 validation run inside the transaction; failure rolls back rows and trigger effects.
 The byte bound checks decoded output, not a database allocation interrupt.
 The statement's `RETURNING` view follows SQLite timing; later AFTER-trigger
-modifications are not an extra readback. Same-input replay yields no effective
-write, no revision increment and no additional trigger effects.
+modifications are not an extra readback. Changed-reporting same-input literal replay yields no effective write, revision
+increment or additional trigger effects. Matched reporting and arithmetic
+expressions intentionally may write on repeat.
 
 Mutations are untracked. Re-read affected rows before subsequent tracked editing;
 a previously tracked revision remains stale and retains normal conflict checks.
 Use `tx.entity(name).mutate(document)` to compose writes, receipts and jobs in one
-transaction. An outer failure rolls everything back. No synchronous `mutate`
-facade or generic bulk mutation expression language is declared.
+transaction. An outer failure rolls everything back. `entityCore` on a synchronous
+connection also settles these mutations synchronously. `where` accepts a native
+Jaren predicate or structural `sql` expression; `expressions` maps exact logical
+assignment names to `sql` expressions, with logical columns resolved to physical
+names. A member cannot appear in both `set` and `expressions`.
+
+For cross-table insert-select, expression conflict updates, raw JSON text, bytes
+and complete SQLite null/collation semantics use the explicit
+[native SQLite surface](SQLITE-RELATIONAL.md). It shares expression emission with
+entity mutations while retaining its own native SQL result contract.
 
 ## Bounded ranges and live qualification
 

package/docs/SQLITE-RELATIONAL.md

@@ -0,0 +1,190 @@
+# Native SQLite programs on an existing connection
+
+`@jarenjs/db/relational` provides structural SQL authoring, physical table DDL,
+and guarded migrations. `relational(connection)` requires an available
+synchronous SQLite connection from `@jarenjs/db/node` or `@jarenjs/db/bun`.
+It opens no store and uses the supplied connection and transaction. Expressions
+are closed `$sql` nodes built by `sql`; strings are bound values, never SQL
+fragments. Identifiers are quoted as single names. `planRelational` returns
+`{ sql, params, access }` for review without reading the database.
+
+## Choose the expression semantics
+
+| Surface | Null, text and numeric semantics | Execution |
+|---|---|---|
+| LINQ / JSON query over mapped entities | Jaren equality, codepoint text comparison, declared codecs; present null remains null | Qualified native plan; `strict: true` refuses any required residual, including unsupported external bindings |
+| `sql` expressions and `relational` | SQLite three-valued logic, native affinities, explicit BINARY/NOCASE/RTRIM, native aggregates | One native statement; no decoded-row fallback |
+
+For example, Jaren equality regards two present nulls as equal, while SQLite
+`=` yields SQL NULL and `IS` supplies a null-safe comparison. Jaren sum over an
+empty sequence is zero and a present null is a type error. SQLite `sum` skips
+null and returns null without inputs; `total` returns floating zero. SQLite
+floating accumulation and ASCII NOCASE are deliberate choices on this surface.
+No mapping must omit a null member to use native SQL.
+
+```js
+import { relational, sql } from '@jarenjs/db/relational';
+const r = relational(connection);
+const c = sql.column;
+const query = {
+  from: { table: 'staging', as: 's' },
+  columns: {
+    id: c('id', 's'), raw: c('body', 's'),
+    price: sql.cast(sql.call('json_extract', [c('body', 's'), '$.price']), 'REAL'),
+  },
+  where: sql.binary('IS', c('supplier', 's'), sql.param('supplier')),
+  orderBy: [{ by: sql.collate(c('sku', 's'), 'NOCASE'), nulls: 'first' }],
+};
+for (const row of r.iterate(query, { externals: { supplier: null } })) {
+  consume(row); // original raw text and native byte values are preserved
+}
+```
+
+`all`, `get`, `iterate` and `execute` settle synchronously. `iterate` uses the
+shared cursor lifecycle, releases its statement on early return or failure,
+and reports `streaming`/`barrier` from the driver. `all` intentionally collects
+the result. SQLite may itself sort or build temporary query structures.
+
+Selections support table and subquery sources, inner/left/cross joins, correlated
+`sql.scalar`/`sql.exists`, CASE, IN/NOT IN, DISTINCT, grouped and distinct
+aggregates, HAVING, UNION/UNION ALL and ordered windows. The declaration file
+lists the closed operators and functions, including trim/coalesce, LIKE, JSON
+extraction, casts and SQLite date functions. Neither arbitrary function names
+nor a raw-expression escape hatch is accepted.
+
+## Exact writes and bytes
+
+```js
+const result = r.execute({
+  op: 'update', table: 'claims',
+  set: { revision: sql.binary('+', c('revision'), 1), status: 'done' },
+  where: sql.binary('AND',
+    sql.binary('=', c('revision'), sql.param('expected')),
+    sql.binary('=', c('owner'), sql.param('owner'))),
+}, { externals: { expected: 3, owner: 'worker-1' } });
+// result.affected is SQLite's direct statement count, excluding trigger writes.
+```
+
+UPDATE emits exactly the supplied assignments. `reporting: 'matched'` is the
+native surface's default and executes identical assignments, so UPDATE OF and
+immutability triggers run. `reporting: 'changed'` adds a BINARY, null-safe
+comparison to suppress unchanged rows. UPDATE and DELETE require an explicit
+`where`; literal `1` authorizes every row. Predicates and arithmetic belong to
+one statement. The existing entity updater retains changed-row behavior;
+`entity.mutate` adds explicit matched reporting and expression assignments.
+
+INSERT accepts `values` or a `source` selection with ordered target `columns`.
+A source may read another table or an intermediate legacy shape. `ignore: true`
+uses INSERT OR IGNORE. `conflict` accepts ordered column/expression targets, an
+optional partial-index `where`, and `action: 'nothing'` or `'update'` with an
+exact `set` and optional `updateWhere`. Use `sql.column(name, 'excluded')` for
+incoming values. Conflict-target expressions contain literal schema values so
+SQLite can match its index. No read-then-write emulation occurs.
+
+`Uint8Array` and Node `Buffer` values bind as bytes; returned binary values stay
+bytes. Subarray offsets and zero bytes survive without hex strings or JSON
+arrays. Combine metadata, image, conflict and history writes inside the existing
+synchronous transaction; failure rolls back all of them. Optional `returning`
+collects rows using SQLite RETURNING timing, before subsequent AFTER-trigger
+changes. Unlike bounded entity mutation documents, this explicit native surface
+has no automatic result row/byte limit; use a bounded selection or streaming read
+when handling large results.
+
+## Physical schema ownership
+
+```js
+import { defineTable, planTable, planTableMigration, applyTableMigration } from '@jarenjs/db/relational';
+const history = defineTable({
+  name: 'history', primaryKey: ['id'],
+  columns: [
+    { name: 'id', type: 'INTEGER', identity: 'autoincrement', nullable: false },
+    { name: 'body', type: 'TEXT', nullable: false },
+    { name: 'revision', type: 'INTEGER', default: 1, nullable: false },
+  ],
+  indexes: [{ name: 'history_revision', terms: [{ by: c('revision'), direction: 'desc' }] }],
+  triggers: [{ name: 'history_immutable', timing: 'before', event: 'update',
+    steps: [{ raise: { action: 'abort', message: 'immutable history' } }] }],
+});
+const ddl = planTable(history).createSql;
+const migration = planTableMigration(connection, history, { id: 'history-v2', allowRebuild: true });
+// Inspect migration.statements and migration.finish before applying the plan.
+applyTableMigration(connection, migration);
+```
+
+Columns retain declaration order and exact INTEGER/REAL/TEXT/BLOB/NUMERIC/ANY
+types. Definitions support ordered primary keys, rowid or AUTOINCREMENT identity,
+nullability, database defaults, generated columns, STRICT/WITHOUT ROWID, named
+UNIQUE/CHECK/foreign-key constraints and delete/update actions. Index terms
+support expressions, direction and collation, with an optional partial predicate.
+Triggers support BEFORE/AFTER, INSERT/UPDATE/DELETE, UPDATE OF, OLD/NEW conditions,
+mutation steps and RAISE. Schema expressions use the same structural emitter,
+with quoted inline literals because SQLite disallows schema parameters.
+
+Entity `.physical(...)` metadata can also supply column `type`, `defaultValue`,
+`collation`, `identity`, `check`, `generatedExpression` and `stored`, plus table
+`constraints`, `indexes`, `triggers`, `strict` and `withoutRowid`.
+`planEntity(...).createSql` now emits explicit table DDL for complete writable
+declarations; views and incomplete generated/default definitions remain adoption
+metadata. `openStore` still verifies physical tables without creating them.
+Identical physical models produce an empty `planModelMigration`; changed
+physical tables use the live-schema `planTableMigration` API.
+
+## Guarded upgrades
+
+Planning inspects the existing schema without modifying it. A differing existing
+table requires `allowRebuild: true`; additions currently use the same guarded
+rebuild. Every removed column needs `dropColumns`; removing an existing explicit
+index/trigger requires `dropObjects`. Unmentioned indexes and triggers survive.
+An optional `copy` maps writable non-key target columns to structural expressions;
+new columns otherwise use their defaults. The plan retains the source schema and
+an exact canonical checksum. Applying an edited plan or a stale source refuses.
+A target already matching the reviewed plan is a no-op on repeat.
+
+Execution creates a replacement, copies natively, verifies row counts and
+unchanged values/storage classes, drops/renames atomically, restores indexes and
+triggers, and checks foreign keys and the target schema. Primary-key columns,
+unshadowed hidden rowids, raw text, bytes and AUTOINCREMENT high-water marks are
+preserved. A key change, rowid-ownership change or ambiguous rowid alias refuses.
+No migration history table or model adoption is needed.
+
+Rebuilds require SQLite's foreign-key transition outside a transaction. For a
+nested upgrade use `withForeignKeysSuspended(connection, () => { ... })` as the
+outer scope, then nested `connection.transaction`/migration calls share savepoints.
+The helper owns an IMMEDIATE transaction, checks references, and restores
+`foreign_keys` and `legacy_alter_table` after success or failure. Its callback must
+settle synchronously. A rebuild inside an already open FK-enabled transaction
+refuses before DDL. Node/Bun regressions cover populated history and references,
+failed copies, repeat reopening, nested rollback, and process death after DROP
+with WAL recovery. These tests do not establish power-loss durability.
+
+## Read-only inspection and disk snapshots
+
+`readSchema` from `@jarenjs/db/model` inventories tables without adopting them,
+but excludes engine bookkeeping. For a scanner that must include framework tables,
+select table names directly from `sqlite_schema` with `relational`, or use the
+public `connection.dialect.introspect.tables()` statement. A native selection can use `sql.call('typeof', [sql.column(name)])` and
+`sql.column('rowid')` to inspect actual text storage in otherwise unknown shapes.
+Declared affinity does not determine a value's storage class. WITHOUT ROWID tables
+and shadowed rowid aliases require an explicit different identity selection.
+
+Both host driver entries export `snapshotDatabase(connection, newPath)`. It
+reserves a new destination, refuses any existing file (even empty), includes
+committed WAL data through VACUUM INTO, syncs the output and cleans up a failed
+copy. It allocates no database-sized JavaScript image. SQLite page caches and
+its temporary storage govern native working memory. The copy runs synchronously
+inside the asynchronous filesystem operation; it is not an incremental-progress
+or interruption API. A snapshot inside an active transaction fails and cleans up.
+Explicit keys, retained histories and bytes survive; [SQLite VACUUM](https://www.sqlite.org/lang_vacuum.html)
+may renumber unaliased rowids, so this is not a page-identical archival copy. Bun store backups
+use the same disk-backed path; Node store backup keeps its online-backup binding.
+
+## Lightweight engines
+
+Use `@jarenjs/db/query`, `/model` and `/entity` for existing-connection consumers;
+`/relational` needs neither entity normalization nor a query plan cache.
+`compileEntityModel(model)` returns `{ entities, mapping }` from one normalization,
+avoiding the duplicated work of separate `normalizeEntities` and `explainMapping`
+calls. No global strong model cache is introduced. Keep connection/query caches
+bounded and reuse compiled metadata. Smaller import graphs alone do not prove
+the complete application meets its RSS budget; measure application memory with
+representative workloads.

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@jarenjs/db",
   "private": false,
-  "version": "0.84.3",
+  "version": "0.86.0",
   "type": "module",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
   "sideEffects": false,
   "exports": {
+    "./node-process": {
+      "types": "./types/node-process.d.ts",
+      "default": "./src/drivers/node-process.js"
+    },
     "./search": {
       "types": "./types/search.d.ts",
       "default": "./src/search.js"
@@ -48,6 +52,22 @@
     "./node-pool": {
       "types": "./types/node-pool.d.ts",
       "default": "./src/drivers/node-pool.js"
+    },
+    "./relational": {
+      "types": "./types/relational.d.ts",
+      "default": "./src/relational-api.js"
+    },
+    "./query": {
+      "types": "./types/query.d.ts",
+      "default": "./src/query-api.js"
+    },
+    "./model": {
+      "types": "./types/model.d.ts",
+      "default": "./src/model-api.js"
+    },
+    "./entity": {
+      "types": "./types/entity.d.ts",
+      "default": "./src/entity.js"
     }
   },
   "files": [
@@ -88,9 +108,9 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.84.3",
-    "@jarenjs/json": "^0.84.3",
-    "@jarenjs/validate": "^0.84.3"
+    "@jarenjs/core": "^0.86.0",
+    "@jarenjs/json": "^0.86.0",
+    "@jarenjs/validate": "^0.86.0"
   },
   "bin": {
     "jaren-db": "./src/cli.js"