@jarenjs/db 0.85.0 → 0.86.0

package/ARCHITECTURE.md

@@ -1196,3 +1196,10 @@ SQLite-semantic and never enter the JSON residual evaluator. See
 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 |
@@ -1442,3 +1447,8 @@ partial conflicts, raw-text JSON queries and byte-valued operations use
 `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 |

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@jarenjs/db",
   "private": false,
-  "version": "0.85.0",
+  "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"
@@ -104,9 +108,9 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.85.0",
-    "@jarenjs/json": "^0.85.0",
-    "@jarenjs/validate": "^0.85.0"
+    "@jarenjs/core": "^0.86.0",
+    "@jarenjs/json": "^0.86.0",
+    "@jarenjs/validate": "^0.86.0"
   },
   "bin": {
     "jaren-db": "./src/cli.js"

package/src/driver.js

@@ -292,6 +292,8 @@ export function baseCapabilities() {
     sessions: false,
     sessionReason: null,
     worker: false,
+    process: false,
+    ownerTermination: false,
     pooling: false,
     poolReaders: 0,
     poolWriters: 0,
@@ -809,6 +811,7 @@ export function finishConnection(raw, dialect, synchronous, capabilities, queueT
       if (pending.some(isThenable)) return closeResult = Promise.allSettled(pending).then(() => raw.close());
       return closeResult = raw.close();
     },
+    transactionState: () => raw.transactionState?.() ?? null,
     registerFunction: typeof raw.registerFunction === 'function'
       ? (name, functionOptions, fn) => { requireOpen(); return raw.registerFunction(name, functionOptions, fn); }
       : null,

package/src/drivers/node-process-endpoint.js

@@ -0,0 +1,13 @@
+//@ts-check
+/** The child owns SQLite; only bounded protocol frames cross IPC. */
+import { serveSqliteEndpoint } from './sqlite-endpoint.js';
+
+process.once('message', (configuration) => {
+  const port = {
+    postMessage: (message) => { if (process.connected) process.send(message); },
+    on: (name, listener) => process.on(name, listener),
+    close: () => { if (process.connected) process.disconnect(); },
+  };
+  serveSqliteEndpoint(port, configuration);
+});
+process.once('disconnect', () => process.exit(0));

package/src/drivers/node-process.js

@@ -0,0 +1,177 @@
+//@ts-check
+/** Supervised process ownership; response cancellation never implies SQL rollback. */
+import { sqliteDialect } from '../dialects/sqlite.js';
+import { sqlTokens } from '../dialects/check-read.js';
+import { DbCompileError, DbRuntimeError } from '../errors.js';
+import { createWorkerConnection } from './worker-client.js';
+import { positiveOption, queueFailure, rowBytes, workerSettings, PROCESS_DEFAULTS } from './worker-protocol.js';
+
+/**
+ * Finite owned SQLite processes behind the ordinary Driver contract.
+ * A quarantined process retains its admission credit until its exit event.
+ * @param {import('../../types/node-process.js').NodeProcessOptions} [configuration]
+ * @returns {import('../../types/node-process.js').NodeProcessDriver}
+ */
+export function nodeProcessDriver(configuration = {}) {
+  const maxOwners = positiveOption('maxOwners', configuration.maxOwners, PROCESS_DEFAULTS.maxOwners);
+  const timeoutMs = positiveOption('timeoutMs', configuration.timeoutMs, PROCESS_DEFAULTS.timeoutMs);
+  const maxRequestBytes = positiveOption('maxRequestBytes', configuration.maxRequestBytes, PROCESS_DEFAULTS.maxRequestBytes);
+  const settings = workerSettings(configuration, PROCESS_DEFAULTS);
+  const { limits } = settings;
+  const owners = new Set();
+  let generation = 0;
+  const driver = {
+    name: 'node-process-sqlite', dialect: sqliteDialect,
+    metrics: () => Object.freeze({ capacity: maxOwners, owners: owners.size,
+      quarantined: [...owners].filter((owner) => owner.status === 'quarantined').length,
+      healthy: [...owners].filter((owner) => owner.status === 'healthy').length }),
+    async open(path = ':memory:', options = {}) {
+      if (globalThis.process?.versions?.bun || globalThis.process?.release?.name !== 'node'
+        || Number(process.versions.node.split('.')[0]) < 24)
+        throw new DbCompileError('JD0003', 'supervised SQLite processes require Node.js 24 or newer');
+      const [{ fork }, { resolve }] = await Promise.all([import('node:child_process'), import('node:path')]);
+      const identity = path === ':memory:' ? null : resolve(path);
+      if (owners.size >= maxOwners || identity && [...owners].some((owner) => owner.path === identity))
+        throw queueFailure('process owner capacity or database ownership is reserved', owners.size);
+      const epoch = ++generation;
+      const state = { path: identity, status: 'starting', transaction: 'none', generation: epoch, pid: null,
+        safeToReplace: false, exitCode: null, exitSignal: null };
+      owners.add(state);
+      let child;
+      try {
+        child = fork(new URL('./node-process-endpoint.js', import.meta.url), [], {
+          serialization: 'advanced', stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+          execArgv: ['--no-warnings=ExperimentalWarning'],
+        });
+      }
+      catch (error) { owners.delete(state); throw error; }
+      state.pid = child.pid ?? null;
+      let resolveExit, control, killPromise, active = false, closeAcknowledged = false;
+      let transactionOpen = false, ambiguous = false;
+      const prepared = new Map();
+      const cursors = new Map();
+      const report = () => Object.freeze({ ...state });
+      const exited = new Promise((resolve) => { resolveExit = resolve; });
+      child.once('exit', (code, signal) => {
+        state.status = 'exited'; state.safeToReplace = true;
+        state.exitCode = code; state.exitSignal = signal;
+        queueMicrotask(() => {
+          if (ambiguous) state.transaction = 'unknown';
+          else if (transactionOpen) state.transaction = 'rolled-back';
+          owners.delete(state); resolveExit(report());
+        });
+      });
+      // A failed spawn has no owner to quarantine and emits no exit event.
+      child.once('error', () => {
+        if (child.pid === undefined) {
+          state.status = 'exited'; state.safeToReplace = true;
+          owners.delete(state); resolveExit(report());
+        }
+      });
+      const terminate = () => {
+        if (!killPromise) {
+          if (state.status !== 'exited' && !closeAcknowledged) { state.status = 'quarantined'; child.kill('SIGKILL'); }
+          killPromise = exited;
+        }
+        return killPromise;
+      };
+      const transport = {
+        on: (name, fn) => child.on(name, fn),
+        postMessage: (message) => child.send(message, (error) => { if (error) control?.lose(error); }),
+        terminate, unref: () => {},
+      };
+      const info = (sql) => {
+        const tokens = sqlTokens(sql), words = tokens.filter((token) => token.kind === 'word').map((token) => token.value.toUpperCase());
+        const multiple = tokens.some((token, i) => token.kind === 'symbol' && token.value === ';' && i < tokens.length - 1);
+        return { multiple, end: multiple || ['COMMIT', 'END', 'RELEASE'].includes(words[0]),
+          rollback: words[0] === 'ROLLBACK' && !words.includes('TO'),
+          writes: multiple || !['SELECT', 'WITH'].includes(words[0]) || words.some((word) => ['INSERT', 'UPDATE', 'DELETE', 'REPLACE'].includes(word)) };
+      };
+      const unknownStatement = { multiple: true, writes: true, end: true };
+      const execution = (op, data) => op === 'exec' ? info(data.sql)
+        : ['next', 'return'].includes(op) ? cursors.get(data.cursor) ?? unknownStatement
+          : ['run', 'get', 'iterate'].includes(op) ? prepared.get(data.statement) ?? unknownStatement : null;
+      const observe = (op, data, open, failed = false, statement = execution(op, data)) => {
+        if (typeof open !== 'boolean') return;
+        const wasOpen = transactionOpen;
+        transactionOpen = open;
+        if (open) { ambiguous = false; state.transaction = 'active'; }
+        else if (statement?.multiple || [...cursors.values()].some((cursor) => cursor.writes)
+          || op === 'return' && statement?.writes) { ambiguous = true; state.transaction = 'unknown'; }
+        else if (failed && wasOpen || statement?.rollback) {
+          ambiguous = false; state.transaction = 'rolled-back';
+        }
+        else if (!failed && statement && (wasOpen || ambiguous && statement.writes)) { ambiguous = false; state.transaction = 'committed'; }
+      };
+      const hooks = {
+        control: (value) => { control = value; },
+        lost: (error, pending) => {
+          const live = pending.map(({ op, data }) => execution(op, data)).filter(Boolean);
+          ambiguous = live.some((statement) => statement.end || statement.writes && !transactionOpen)
+            || !transactionOpen && [...cursors.values()].some((statement) => statement.writes);
+          if (ambiguous) state.transaction = 'unknown';
+          if (ambiguous || transactionOpen) error.retryable = false;
+          if (state.status !== 'exited') { state.status = 'quarantined'; terminate(); }
+        },
+        request: (op, data) => {
+          if (data.params?.some((param) => param !== null && !['number', 'bigint', 'string'].includes(typeof param) && !(param instanceof Uint8Array)))
+            throw new DbRuntimeError('JD2093', 'process parameters must be SQLite scalars or byte arrays');
+          if (rowBytes(data) > maxRequestBytes) throw new DbRuntimeError('JD2092', 'process request exceeds its byte credit');
+          const statement = execution(op, data);
+          if (statement && (statement.end || statement.writes && !transactionOpen)) {
+            ambiguous = true; state.transaction = 'unknown';
+          }
+        },
+        failure: (op, data, open) => observe(op, data, open, true),
+        result: (op, data, value, open) => {
+          const statement = execution(op, data);
+          if (op === 'close') closeAcknowledged = true;
+          if (op === 'prepare') {
+            if (prepared.size >= limits.statements) prepared.delete(prepared.keys().next().value);
+            prepared.set(value, info(data.sql));
+          }
+          if (op === 'iterate') cursors.set(value, statement);
+          if (op === 'return' || op === 'next' && value.done) cursors.delete(data.cursor);
+          observe(op, data, open, false, statement);
+        },
+      };
+      const opening = createWorkerConnection(transport, { ...settings, epoch, options, hooks, awaitStartupExit: false,
+        reopen: () => driver.open(path, options) });
+      child.send({ generation: epoch, path, options: { timeout: options.timeout, readOnly: options.readOnly }, limits });
+      const connection = await opening;
+      state.status = 'healthy';
+      const cancel = (reason = 'caller cancelled') => {
+        const error = Object.assign(new DbRuntimeError('JD2097', String(reason)), {
+          generation: epoch, retryable: false, class: 'cancelled',
+        });
+        control.lose(error); terminate(); return error;
+      };
+      const result = Object.freeze({ ...connection,
+        get mustQueue() { return connection.mustQueue; },
+        capabilities: Object.freeze({ ...connection.capabilities, worker: false, process: true,
+          ownerTermination: true, cancellation: Object.freeze({ ...connection.capabilities.cancellation, midStatement: false }) }),
+        settlement: report, settled: () => exited, cancel,
+        metrics: () => Object.freeze({ ...connection.metrics(), owner: report(), supervised: active ? 1 : 0 }),
+        async supervise(body, request = {}) {
+          if (active) throw queueFailure('one supervised operation already owns this process', 1);
+          const bound = positiveOption('timeoutMs', request.timeoutMs, timeoutMs);
+          if (request.signal?.aborted) throw Object.assign(new DbRuntimeError('JD2097', 'cancelled before admission'), { generation: epoch, retryable: true, class: 'cancelled' });
+          if (state.status !== 'healthy') throw new DbRuntimeError('JD2090', 'process owner is not healthy');
+          active = true;
+          let timer, abort;
+          try {
+            return await new Promise((resolve, reject) => {
+              abort = () => { const error = cancel('supervised operation was cancelled'); reject(error); };
+              request.signal?.addEventListener('abort', abort, { once: true });
+              timer = setTimeout(() => { const error = cancel('supervised operation exceeded its response deadline'); reject(error); }, bound);
+              Promise.resolve().then(() => body(result)).then(resolve, reject);
+            });
+          }
+          finally { active = false; clearTimeout(timer); request.signal?.removeEventListener('abort', abort); }
+        },
+      });
+      return result;
+    },
+  };
+  return Object.freeze(driver);
+}

package/src/drivers/node-worker-endpoint.js

@@ -1,105 +1,5 @@
 //@ts-check
-/** One worker owns one SQLite handle. Only bounded credit frames carry rows. */
+/** A thread owns one SQLite endpoint and its bounded protocol frames. */
 import { parentPort, workerData } from 'node:worker_threads';
-import { nodeDriver } from './node.js';
-import { DbRuntimeError, cloneDriverError } from '../errors.js';
-import { validRequest, generationFailure, rowBytes } from './worker-protocol.js';
-
-const { generation, path, options, limits } = workerData;
-let connection;
-let sequence = 0;
-const statements = new Map();
-const cursors = new Map();
-const frame = (kind, id, value) => ({ v: 1, generation, kind, id, ...value });
-const bound = (reason) => new DbRuntimeError('JD2092', reason);
-const release = (id) => {
-  const cursor = cursors.get(id);
-  if (cursor === undefined) return;
-  cursors.delete(id);
-  cursor.iterator.return?.();
-  if (cursor.ephemeral) statements.delete(cursor.statement);
-};
-const statementOf = (id) => {
-  const statement = statements.get(id);
-  if (statement === undefined) throw generationFailure(generation);
-  return statement;
-};
-const dispatch = (request) => {
-  switch (request.op) {
-    case 'exec': return connection.exec(request.sql);
-    case 'prepare': {
-      if (statements.size >= limits.statements) throw bound(`worker statement capacity ${limits.statements} exceeded`);
-      const id = ++sequence;
-      statements.set(id, { statement: connection.prepare(request.sql), ephemeral: request.ephemeral === true });
-      return id;
-    }
-    case 'get': {
-      const row = statementOf(request.statement).statement.get(request.params);
-      if (rowBytes(row) > limits.bytes) throw bound(`one worker row exceeds ${limits.bytes} bytes`);
-      return row;
-    }
-    case 'run': return statementOf(request.statement).statement.run(request.params);
-    case 'iterate': {
-      if (cursors.size >= limits.cursors) throw bound(`worker cursor capacity ${limits.cursors} exceeded`);
-      const record = statementOf(request.statement);
-      const id = ++sequence;
-      cursors.set(id, { iterator: record.statement.iterate(request.params),
-        statement: request.statement, ephemeral: record.ephemeral, buffered: null });
-      return id;
-    }
-    case 'next': {
-      const cursor = cursors.get(request.cursor);
-      if (cursor === undefined) throw generationFailure(generation);
-      if (request.rows > limits.rows || request.bytes > limits.bytes) throw bound('worker cursor credit exceeds the negotiated window');
-      const rows = [];
-      let bytes = 0;
-      try {
-        while (rows.length < request.rows) {
-          const step = cursor.buffered ?? cursor.iterator.next();
-          cursor.buffered = null;
-          if (step.done) { release(request.cursor); return { rows, bytes, done: true }; }
-          const size = rowBytes(step.value);
-          if (size > request.bytes) throw bound(`one worker row of ${size} bytes exceeds the ${request.bytes} byte window`);
-          if (bytes + size > request.bytes) { cursor.buffered = step; break; }
-          rows.push(step.value);
-          bytes += size;
-        }
-        return { rows, bytes, done: false };
-      }
-      catch (error) { release(request.cursor); throw error; }
-    }
-    case 'return': release(request.cursor); return undefined;
-    case 'finalize': {
-      for (const [id, cursor] of cursors) if (cursor.statement === request.statement) release(id);
-      statements.delete(request.statement);
-      return undefined;
-    }
-    case 'close': {
-      for (const id of cursors.keys()) release(id);
-      statements.clear();
-      return connection.close();
-    }
-  }
-};
-try {
-  connection = await nodeDriver().open(path, options);
-  // Functions cannot cross structured clone. Capture uses the existing
-  // journal path; a live query requires a synchronous connection.
-  parentPort.postMessage(frame('ready', 0, { capabilities: { ...connection.capabilities,
-    sessions: false, userFunctions: false, deterministicIndexableFunctions: false,
-    aggregateFunctions: false, backup: false, worker: true, pooling: false } }));
-  parentPort.on('message', (request) => {
-    try {
-      if (!validRequest(request)) throw new DbRuntimeError('JD2093', 'invalid worker protocol request');
-      if (request.generation !== generation) throw generationFailure(request.generation);
-      const value = dispatch(request);
-      parentPort.postMessage(frame('result', request.id, { value }));
-      if (request.op === 'close') parentPort.close();
-    }
-    catch (error) { parentPort.postMessage(frame('failure', request?.id ?? 0, { error: cloneDriverError(error) })); }
-  });
-}
-catch (error) {
-  parentPort.postMessage(frame('failure', 0, { error: cloneDriverError(error) }));
-  parentPort.close();
-}
+import { serveSqliteEndpoint } from './sqlite-endpoint.js';
+await serveSqliteEndpoint(parentPort, workerData);

package/src/drivers/node-worker.js

@@ -1,9 +1,9 @@
 //@ts-check
 /** A worker transport behind the ordinary Connection contract. */
-import { finishConnection, lazyOpen } from '../driver.js';
+import { lazyOpen } from '../driver.js';
 import { sqliteDialect } from '../dialects/sqlite.js';
-import { DbRuntimeError } from '../errors.js';
-import { generationFailure, positiveOption, queueFailure, rowBytes, validResponse, validResult } from './worker-protocol.js';
+import { createWorkerConnection } from './worker-client.js';
+import { workerSettings } from './worker-protocol.js';
 
 /** Dedicated SQLite worker per connection. No function serialization or write replay.
  * @param {{ windowRows?: number, windowBytes?: number, maxPending?: number,
@@ -12,17 +12,7 @@ import { generationFailure, positiveOption, queueFailure, rowBytes, validRespons
  * @returns {any} a Driver
  */
 export function nodeWorkerDriver(configuration = {}) {
-  const limits = {
-    rows: positiveOption('windowRows', configuration.windowRows, 64),
-    bytes: positiveOption('windowBytes', configuration.windowBytes, 1024 * 1024),
-    statements: positiveOption('maxStatements', configuration.maxStatements, 1024),
-    cursors: positiveOption('maxCursors', configuration.maxCursors, 64),
-  };
-  const maxPending = positiveOption('maxPending', configuration.maxPending, 64);
-  const allRows = positiveOption('allMaxRows', configuration.allMaxRows, 100000);
-  const allBytes = positiveOption('allMaxBytes', configuration.allMaxBytes, 16 * 1024 * 1024);
-  const closeMs = positiveOption('closeTimeoutMs', configuration.closeTimeoutMs, 5000);
-  const startupMs = positiveOption('startupTimeoutMs', configuration.startupTimeoutMs, 10000);
+  const { limits, maxPending, allRows, allBytes, closeMs, startupMs } = workerSettings(configuration);
   let generation = 0;
   const driver = {
     name: 'node-worker-sqlite', dialect: sqliteDialect,
@@ -34,170 +24,8 @@ export function nodeWorkerDriver(configuration = {}) {
           // Parent --test/--input-type/preloads do not describe the endpoint.
           execArgv: ['--no-warnings=ExperimentalWarning'],
         });
-        const pending = new Map();
-        let sequence = 0;
-        let failed = null;
-        let closing = false;
-        let closed = false;
-        let transactionDepth = 0;
-        let closePromise;
-        const metrics = { frames: 0, rows: 0, maxFrameRows: 0, maxFrameBytes: 0, maxPending: 0 };
-        let readyResolve;
-        let readyReject;
-        const ready = new Promise((resolve, reject) => { readyResolve = resolve; readyReject = reject; });
-        const lose = (cause) => {
-          if (failed !== null || closed) return;
-          failed = generationFailure(epoch, transactionDepth > 0, cause);
-          readyReject(failed);
-          for (const request of pending.values()) request.reject(failed);
-          pending.clear();
-        };
-        worker.on('error', lose);
-        worker.on('exit', (code) => { if (!closed) lose(new Error(`worker exited (${code})`)); });
-        worker.on('message', (message) => {
-          if (!validResponse(message, epoch)) { lose(new Error('invalid worker response')); return; }
-          if (message.kind === 'ready') { readyResolve(message.capabilities); return; }
-          if (message.kind === 'failure' && message.id === 0) {
-            readyReject(Object.assign(new Error(message.error.message), message.error)); return;
-          }
-          const request = pending.get(message.id);
-          if (request === undefined) return;
-          pending.delete(message.id);
-          if (message.kind === 'failure') {
-            const error = message.error;
-            request.reject(Object.assign(error.code?.startsWith('JD')
-              ? new DbRuntimeError(error.code, error.message) : new Error(error.message), error));
-          }
-          else if (message.kind === 'result' && validResult(request.op, message.value, limits)) request.resolve(message.value);
-          else { request.reject(generationFailure(epoch, transactionDepth > 0)); lose(new Error('invalid worker response')); }
-        });
-        const timer = setTimeout(() => { lose(new Error('worker startup timed out')); worker.terminate(); }, startupMs);
-        let capabilities;
-        try { capabilities = await ready; }
-        catch (error) { await worker.terminate(); throw error; }
-        finally { clearTimeout(timer); }
-        const request = (op, data = {}, cleanup = false) => {
-          if (failed !== null) return Promise.reject(failed);
-          if (closed || (closing && !cleanup)) return Promise.reject(new DbRuntimeError('JD2063', 'the worker connection is closing or closed'));
-          if (!cleanup && pending.size >= maxPending)
-            return Promise.reject(queueFailure(`worker request capacity ${maxPending} exceeded`, pending.size));
-          // One return per live cursor and one close have reserved capacity.
-          if (cleanup && pending.size >= maxPending + limits.cursors + 1)
-            return Promise.reject(queueFailure('worker cleanup capacity exceeded', pending.size));
-          const id = ++sequence;
-          return new Promise((resolve, reject) => {
-            pending.set(id, { resolve, reject, op });
-            metrics.maxPending = Math.max(metrics.maxPending, pending.size);
-            try { worker.postMessage({ v: 1, generation: epoch, kind: 'request', id, op, ...data }); }
-            catch (error) { pending.delete(id); reject(error); }
-          });
-        };
-        const raw = {
-          closeDrainsIterators: true,
-          exec: (sql) => {
-            if (/^(?:SAVEPOINT|BEGIN)\b/.test(sql)) transactionDepth++;
-            return request('exec', { sql }).then((value) => {
-              if (/^RELEASE\b/.test(sql)) transactionDepth = Math.max(0, transactionDepth - 1);
-              if (/^(?:COMMIT|ROLLBACK(?! TO))\b/.test(sql)) transactionDepth = 0;
-              return value;
-            });
-          },
-          prepare: async (sql, metadata = {}) => {
-            const id = await request('prepare', { sql, ephemeral: metadata.ephemeral === true });
-            const iterate = async (params = []) => {
-              const cursor = await request('iterate', { statement: id, params });
-              let rows = [];
-              let at = 0;
-              let done = false;
-              let returned = false;
-              let pulling = Promise.resolve();
-              const next = async () => {
-                if (failed !== null) throw failed;
-                if (returned) return { done: true, value: undefined };
-                if (at < rows.length) return { done: false, value: rows[at++] };
-                if (done) return { done: true, value: undefined };
-                const batch = await request('next', { cursor, rows: limits.rows, bytes: limits.bytes });
-                metrics.frames++;
-                metrics.rows += batch.rows.length;
-                metrics.maxFrameRows = Math.max(metrics.maxFrameRows, batch.rows.length);
-                metrics.maxFrameBytes = Math.max(metrics.maxFrameBytes, batch.bytes);
-                if (returned) return { done: true, value: undefined };
-                rows = batch.rows;
-                at = 0;
-                done = batch.done;
-                return at < rows.length ? { done: false, value: rows[at++] } : { done: true, value: undefined };
-              };
-              return {
-                next: () => {
-                  const result = pulling.then(next);
-                  pulling = result.then(() => undefined, () => undefined);
-                  return result;
-                },
-                return: async () => {
-                  if (returned) return { done: true, value: undefined };
-                  returned = true;
-                  rows = [];
-                  if (!done) await request('return', { cursor }, true);
-                  return { done: true, value: undefined };
-                },
-              };
-            };
-            return {
-              run: (params = []) => request('run', { statement: id, params }),
-              get: (params = []) => request('get', { statement: id, params }),
-              iterate,
-              all: async (params = []) => {
-                const iterator = await iterate(params);
-                const rows = [];
-                let bytes = 0;
-                try {
-                  for (;;) {
-                    const step = await iterator.next();
-                    if (step.done) return rows;
-                    bytes += rowBytes(step.value);
-                    if (rows.length >= allRows || bytes > allBytes)
-                      throw new DbRuntimeError('JD2092', `worker all() exceeds its ${allRows} row / ${allBytes} byte bound; use a cursor`);
-                    rows.push(step.value);
-                  }
-                }
-                finally { await iterator.return(); }
-              },
-            };
-          },
-          close: () => {
-            if (closePromise !== undefined) return closePromise;
-            closing = true;
-            closePromise = new Promise((resolve, reject) => {
-              const timeout = setTimeout(() => {
-                lose(new Error('worker close timed out'));
-                // V8 termination cannot preempt a synchronous native SQLite
-                // call. Fence and detach now; never hold the caller's deadline
-                // hostage to that native call or claim it was rolled back.
-                worker.unref();
-                worker.terminate().catch(() => {});
-                reject(failed);
-              }, closeMs);
-              request('close', {}, true).then(() => {
-                closed = true;
-                clearTimeout(timeout);
-                worker.terminate().then(() => resolve(undefined), reject);
-              }, (error) => {
-                clearTimeout(timeout);
-                worker.unref();
-                worker.terminate().catch(() => {});
-                reject(error);
-              });
-            });
-            return closePromise;
-          },
-        };
-        const connection = finishConnection(raw, sqliteDialect, false, Object.freeze(capabilities), options.queueTimeout);
-        return Object.freeze({ ...connection,
-          get mustQueue() { return connection.mustQueue; },
-          generation: epoch,
-          metrics: () => Object.freeze({ ...metrics, pending: pending.size, generation: epoch, healthy: failed === null && !closed }),
-          restart: async () => { lose(new Error('worker restarted')); await worker.terminate(); return driver.open(path, options); },
-        });
+        return createWorkerConnection(worker, { epoch, options, limits, maxPending, allRows, allBytes,
+          closeMs, startupMs, reopen: () => driver.open(path, options) });
       }, []),
   };
   return Object.freeze(driver);

package/src/drivers/node.js

@@ -38,6 +38,7 @@ export function adaptNodeDatabase(db, options) {
       };
     },
     close: () => db.close(),
+    transactionState: () => typeof db.isTransaction === 'boolean' ? db.isTransaction : null,
     // each optional primitive is exposed only when the HANDLE has it, so
     // a substitute that carries less than `node:sqlite` reports less —
     // a declared capability the handle cannot honour is a TypeError at

package/src/drivers/sqlite-endpoint.js

@@ -0,0 +1,113 @@
+//@ts-check
+/** One worker owns one SQLite handle. Only bounded credit frames carry rows. */
+import { nodeDriver } from './node.js';
+import { DbRuntimeError, cloneDriverError } from '../errors.js';
+import { validRequest, generationFailure, rowBytes } from './worker-protocol.js';
+
+/** @param {any} parentPort @param {any} configuration */
+export async function serveSqliteEndpoint(parentPort, configuration) {
+  const { generation, path, options, limits } = configuration;
+  let connection;
+  let sequence = 0;
+  const statements = new Map();
+  const cursors = new Map();
+  const frame = (kind, id, value) => ({ v: 1, generation, kind, id, ...value });
+  const transaction = () => {
+    try { return connection.transactionState(); }
+    catch { return null; }
+  };
+  const bound = (reason) => new DbRuntimeError('JD2092', reason);
+  const release = (id) => {
+    const cursor = cursors.get(id);
+    if (cursor === undefined) return;
+    cursors.delete(id);
+    cursor.iterator.return?.();
+    if (cursor.ephemeral) statements.delete(cursor.statement);
+  };
+  const statementOf = (id) => {
+    const statement = statements.get(id);
+    if (statement === undefined) throw generationFailure(generation);
+    return statement;
+  };
+  const dispatch = (request) => {
+    switch (request.op) {
+      case 'exec': return connection.exec(request.sql);
+      case 'prepare': {
+        if (statements.size >= limits.statements) throw bound(`worker statement capacity ${limits.statements} exceeded`);
+        const id = ++sequence;
+        statements.set(id, { statement: connection.prepare(request.sql), ephemeral: request.ephemeral === true });
+        return id;
+      }
+      case 'get': {
+        const row = statementOf(request.statement).statement.get(request.params);
+        if (rowBytes(row) > limits.bytes) throw bound(`one worker row exceeds ${limits.bytes} bytes`);
+        return row;
+      }
+      case 'run': return statementOf(request.statement).statement.run(request.params);
+      case 'iterate': {
+        if (cursors.size >= limits.cursors) throw bound(`worker cursor capacity ${limits.cursors} exceeded`);
+        const record = statementOf(request.statement);
+        const id = ++sequence;
+        cursors.set(id, { iterator: record.statement.iterate(request.params),
+          statement: request.statement, ephemeral: record.ephemeral, buffered: null });
+        return id;
+      }
+      case 'next': {
+        const cursor = cursors.get(request.cursor);
+        if (cursor === undefined) throw generationFailure(generation);
+        if (request.rows > limits.rows || request.bytes > limits.bytes) throw bound('worker cursor credit exceeds the negotiated window');
+        const rows = [];
+        let bytes = 0;
+        try {
+          while (rows.length < request.rows) {
+            const step = cursor.buffered ?? cursor.iterator.next();
+            cursor.buffered = null;
+            if (step.done) { release(request.cursor); return { rows, bytes, done: true }; }
+            const size = rowBytes(step.value);
+            if (size > request.bytes) throw bound(`one worker row of ${size} bytes exceeds the ${request.bytes} byte window`);
+            if (bytes + size > request.bytes) { cursor.buffered = step; break; }
+            rows.push(step.value);
+            bytes += size;
+          }
+          return { rows, bytes, done: false };
+        }
+        catch (error) { release(request.cursor); throw error; }
+      }
+      case 'return': release(request.cursor); return undefined;
+      case 'finalize': {
+        for (const [id, cursor] of cursors) if (cursor.statement === request.statement) release(id);
+        statements.delete(request.statement);
+        return undefined;
+      }
+      case 'close': {
+        for (const id of cursors.keys()) release(id);
+        statements.clear();
+        return connection.close();
+      }
+    }
+  };
+  try {
+    connection = await nodeDriver().open(path, options);
+    // Functions cannot cross structured clone. Capture uses the existing
+    // journal path; a live query requires a synchronous connection.
+    parentPort.postMessage(frame('ready', 0, { capabilities: { ...connection.capabilities,
+      sessions: false, userFunctions: false, deterministicIndexableFunctions: false,
+      aggregateFunctions: false, backup: false, worker: true, pooling: false } }));
+    parentPort.on('message', (request) => {
+      try {
+        if (!validRequest(request)) throw new DbRuntimeError('JD2093', 'invalid worker protocol request');
+        if (request.generation !== generation) throw generationFailure(request.generation);
+        const value = dispatch(request);
+        parentPort.postMessage(frame('result', request.id, { value,
+          transaction: request.op === 'close' ? null : transaction() }));
+        if (request.op === 'close') parentPort.close();
+      }
+      catch (error) { parentPort.postMessage(frame('failure', request?.id ?? 0, {
+        error: cloneDriverError(error), transaction: transaction() })); }
+    });
+  }
+  catch (error) {
+    parentPort.postMessage(frame('failure', 0, { error: cloneDriverError(error) }));
+    parentPort.close();
+  }
+}

package/src/drivers/worker-client.js

@@ -0,0 +1,185 @@
+//@ts-check
+/** Shared bounded RPC Connection client for owned SQLite execution hosts. */
+import { finishConnection } from '../driver.js';
+import { sqliteDialect } from '../dialects/sqlite.js';
+import { DbRuntimeError } from '../errors.js';
+import { generationFailure, queueFailure, rowBytes, validResponse, validResult } from './worker-protocol.js';
+
+/** @param {any} worker @param {any} settings @returns {Promise<any>} */
+export async function createWorkerConnection(worker, settings) {
+  const { epoch, options, limits, maxPending, allRows, allBytes, closeMs, startupMs, reopen, hooks = {} } = settings;
+  const pending = new Map();
+  let sequence = 0;
+  let failed = null;
+  let closing = false;
+  let closed = false;
+  let transactionDepth = 0;
+  let closePromise;
+  const metrics = { frames: 0, rows: 0, maxFrameRows: 0, maxFrameBytes: 0, maxPending: 0 };
+  let readyResolve;
+  let readyReject;
+  const ready = new Promise((resolve, reject) => { readyResolve = resolve; readyReject = reject; });
+  const lose = (cause) => {
+    if (failed !== null || closed) return;
+    failed = generationFailure(epoch, transactionDepth > 0, cause);
+    hooks.lost?.(failed, [...pending.values()]);
+    readyReject(failed);
+    for (const request of pending.values()) request.reject(failed);
+    pending.clear();
+  };
+  hooks.control?.({ lose });
+  worker.on('error', lose);
+  worker.on('exit', (code) => { if (!closed) lose(new Error(`worker exited (${code})`)); });
+  worker.on('message', (message) => {
+    if (!validResponse(message, epoch)) { lose(new Error('invalid worker response')); return; }
+    if (message.kind === 'ready') { readyResolve(message.capabilities); return; }
+    if (message.kind === 'failure' && message.id === 0) {
+      readyReject(Object.assign(new Error(message.error.message), message.error)); return;
+    }
+    const request = pending.get(message.id);
+    if (request === undefined) return;
+    pending.delete(message.id);
+    if (message.kind === 'failure') {
+      hooks.failure?.(request.op, request.data, message.transaction);
+      const error = message.error;
+      request.reject(Object.assign(error.code?.startsWith('JD')
+        ? new DbRuntimeError(error.code, error.message) : new Error(error.message), error));
+    }
+    else if (message.kind === 'result' && validResult(request.op, message.value, limits)) {
+      hooks.result?.(request.op, request.data, message.value, message.transaction); request.resolve(message.value);
+    }
+    else { request.reject(generationFailure(epoch, transactionDepth > 0)); lose(new Error('invalid worker response')); }
+  });
+  const timer = setTimeout(() => { lose(new Error('worker startup timed out')); worker.terminate(); }, startupMs);
+  let capabilities;
+  try { capabilities = await ready; }
+  catch (error) {
+    const termination = worker.terminate();
+    if (settings.awaitStartupExit !== false) await termination;
+    else termination.catch(() => {});
+    throw error;
+  }
+  finally { clearTimeout(timer); }
+  const request = (op, data = {}, cleanup = false) => {
+    if (failed !== null) return Promise.reject(failed);
+    if (closed || (closing && !cleanup)) return Promise.reject(new DbRuntimeError('JD2063', 'the worker connection is closing or closed'));
+    if (!cleanup && pending.size >= maxPending)
+      return Promise.reject(queueFailure(`worker request capacity ${maxPending} exceeded`, pending.size));
+    // One return per live cursor and one close have reserved capacity.
+    if (cleanup && pending.size >= maxPending + limits.cursors + 1)
+      return Promise.reject(queueFailure('worker cleanup capacity exceeded', pending.size));
+    const id = ++sequence;
+    return new Promise((resolve, reject) => {
+      pending.set(id, { resolve, reject, op, data });
+      metrics.maxPending = Math.max(metrics.maxPending, pending.size);
+      try { hooks.request?.(op, data); worker.postMessage({ v: 1, generation: epoch, kind: 'request', id, op, ...data }); }
+      catch (error) { pending.delete(id); reject(error); }
+    });
+  };
+  const raw = {
+    closeDrainsIterators: true,
+    exec: (sql) => {
+      if (/^(?:SAVEPOINT|BEGIN)\b/.test(sql)) transactionDepth++;
+      return request('exec', { sql }).then((value) => {
+        if (/^RELEASE\b/.test(sql)) transactionDepth = Math.max(0, transactionDepth - 1);
+        if (/^(?:COMMIT|ROLLBACK(?! TO))\b/.test(sql)) transactionDepth = 0;
+        return value;
+      });
+    },
+    prepare: async (sql, metadata = {}) => {
+      const id = await request('prepare', { sql, ephemeral: metadata.ephemeral === true });
+      const iterate = async (params = []) => {
+        const cursor = await request('iterate', { statement: id, params });
+        let rows = [];
+        let at = 0;
+        let done = false;
+        let returned = false;
+        let pulling = Promise.resolve();
+        const next = async () => {
+          if (failed !== null) throw failed;
+          if (returned) return { done: true, value: undefined };
+          if (at < rows.length) return { done: false, value: rows[at++] };
+          if (done) return { done: true, value: undefined };
+          const batch = await request('next', { cursor, rows: limits.rows, bytes: limits.bytes });
+          metrics.frames++;
+          metrics.rows += batch.rows.length;
+          metrics.maxFrameRows = Math.max(metrics.maxFrameRows, batch.rows.length);
+          metrics.maxFrameBytes = Math.max(metrics.maxFrameBytes, batch.bytes);
+          if (returned) return { done: true, value: undefined };
+          rows = batch.rows;
+          at = 0;
+          done = batch.done;
+          return at < rows.length ? { done: false, value: rows[at++] } : { done: true, value: undefined };
+        };
+        return {
+          next: () => {
+            const result = pulling.then(next);
+            pulling = result.then(() => undefined, () => undefined);
+            return result;
+          },
+          return: async () => {
+            if (returned) return { done: true, value: undefined };
+            returned = true;
+            rows = [];
+            if (!done) await request('return', { cursor }, true);
+            return { done: true, value: undefined };
+          },
+        };
+      };
+      return {
+        run: (params = []) => request('run', { statement: id, params }),
+        get: (params = []) => request('get', { statement: id, params }),
+        iterate,
+        all: async (params = []) => {
+          const iterator = await iterate(params);
+          const rows = [];
+          let bytes = 0;
+          try {
+            for (;;) {
+              const step = await iterator.next();
+              if (step.done) return rows;
+              bytes += rowBytes(step.value);
+              if (rows.length >= allRows || bytes > allBytes)
+                throw new DbRuntimeError('JD2092', `worker all() exceeds its ${allRows} row / ${allBytes} byte bound; use a cursor`);
+              rows.push(step.value);
+            }
+          }
+          finally { await iterator.return(); }
+        },
+      };
+    },
+    close: () => {
+      if (closePromise !== undefined) return closePromise;
+      closing = true;
+      closePromise = new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          lose(new Error('worker close timed out'));
+          // V8 termination cannot preempt a synchronous native SQLite
+          // call. Fence and detach now; never hold the caller's deadline
+          // hostage to that native call or claim it was rolled back.
+          worker.unref();
+          worker.terminate().catch(() => {});
+          reject(failed);
+        }, closeMs);
+        request('close', {}, true).then(() => {
+          closed = true;
+          clearTimeout(timeout);
+          worker.terminate().then(() => resolve(undefined), reject);
+        }, (error) => {
+          clearTimeout(timeout);
+          worker.unref();
+          worker.terminate().catch(() => {});
+          reject(error);
+        });
+      });
+      return closePromise;
+    },
+  };
+  const connection = finishConnection(raw, sqliteDialect, false, Object.freeze(capabilities), options.queueTimeout);
+  return Object.freeze({ ...connection,
+    get mustQueue() { return connection.mustQueue; },
+    generation: epoch,
+    metrics: () => Object.freeze({ ...metrics, pending: pending.size, generation: epoch, healthy: failed === null && !closed }),
+    restart: async () => { lose(new Error('worker restarted')); await worker.terminate(); return reopen(); },
+  });
+}

package/src/drivers/worker-protocol.js

@@ -4,6 +4,11 @@ import { DbRuntimeError } from '../errors.js';
 import { jsonStringBytes } from '../json-bytes.js';
 
 export const WORKER_PROTOCOL_VERSION = 1;
+export const WORKER_DEFAULTS = Object.freeze({ windowRows: 64, windowBytes: 1048576,
+  maxPending: 64, maxStatements: 1024, maxCursors: 64, allMaxRows: 100000,
+  allMaxBytes: 16777216, closeTimeoutMs: 5000, startupTimeoutMs: 10000 });
+export const PROCESS_DEFAULTS = Object.freeze({ ...WORKER_DEFAULTS, closeTimeoutMs: 1000,
+  maxOwners: 4, timeoutMs: 250, maxRequestBytes: 1048576 });
 const operations = new Set(['exec', 'prepare', 'run', 'get', 'iterate', 'next', 'return', 'finalize', 'close']);
 
 /** @param {number} generation @param {boolean} [transaction] @param {unknown} [cause] */
@@ -73,6 +78,16 @@ export function positiveOption(name, value, fallback) {
   return value;
 }
 
+/** One validation and spelling of shared transport credits.
+ * @param {any} configuration @param {typeof WORKER_DEFAULTS} [defaults] */
+export function workerSettings(configuration, defaults = WORKER_DEFAULTS) {
+  const values = Object.fromEntries(Object.keys(WORKER_DEFAULTS).map((name) =>
+    [name, positiveOption(name, configuration[name], defaults[name])]));
+  return { limits: { rows: values.windowRows, bytes: values.windowBytes, statements: values.maxStatements, cursors: values.maxCursors },
+    maxPending: values.maxPending, allRows: values.allMaxRows, allBytes: values.allMaxBytes,
+    closeMs: values.closeTimeoutMs, startupMs: values.startupTimeoutMs };
+}
+
 /** @param {string} reason @param {number} depth */
 export function queueFailure(reason, depth) {
   return Object.assign(new DbRuntimeError('JD2091', reason), { class: 'queue', retryable: true, depth });

package/src/errors.js

@@ -112,6 +112,7 @@ export const DB_CODES = Object.freeze({
   JD2094: 'the durable snapshot failed and the connection is invalid',
   JD2095: 'the trusted SQL or synchronous transaction authority was refused',
   JD2096: 'a persistence invariant rejected the mutation',
+  JD2097: 'the supervised operation was cancelled or exceeded its response deadline',
 });
 
 /**

package/types/index.d.ts

@@ -514,6 +514,8 @@ export interface StoreCapabilities {
   readonly sessions: boolean;
   readonly sessionReason: string | null;
   readonly worker: boolean;
+  readonly process: boolean;
+  readonly ownerTermination: boolean;
   readonly pooling: boolean;
   readonly poolReaders: number;
   readonly poolWriters: number;

package/types/node-process.d.ts

@@ -0,0 +1,33 @@
+import type { NodeOpenOptions } from './node.js';
+import type { CancellationCapabilities, Driver } from './index.js';
+import type { NodeWorkerConnection, NodeWorkerOptions, WorkerMetrics } from './node-worker.js';
+
+export interface NodeProcessOptions extends NodeWorkerOptions { maxOwners?: number; timeoutMs?: number; maxRequestBytes?: number }
+export interface ProcessSettlement {
+  readonly path: string | null;
+  readonly generation: number;
+  readonly pid: number | null;
+  readonly status: 'starting' | 'healthy' | 'quarantined' | 'exited';
+  readonly transaction: 'none' | 'active' | 'committed' | 'rolled-back' | 'unknown';
+  readonly safeToReplace: boolean;
+  readonly exitCode: number | null;
+  readonly exitSignal: string | null;
+}
+export interface NodeProcessConnection extends NodeWorkerConnection {
+  readonly capabilities: Readonly<Record<string, unknown>> & {
+    readonly process: true; readonly ownerTermination: true;
+    readonly cancellation: CancellationCapabilities & {readonly midStatement: false};
+  };
+  supervise<T>(body: (connection: NodeProcessConnection) => T | Promise<T>, options?: {signal?: AbortSignal; timeoutMs?: number}): Promise<T>;
+  cancel(reason?: string): Error;
+  settlement(): ProcessSettlement;
+  /** Resolves only after the OS reports owner exit, never from a caller deadline. */
+  settled(): Promise<ProcessSettlement>;
+  metrics(): WorkerMetrics & {readonly owner: ProcessSettlement; readonly supervised: number};
+  restart(): Promise<NodeProcessConnection>;
+}
+export interface NodeProcessDriver extends Driver {
+  open(path?: string, options?: NodeOpenOptions): Promise<NodeProcessConnection>;
+  metrics(): Readonly<{capacity: number; owners: number; quarantined: number; healthy: number}>;
+}
+export declare function nodeProcessDriver(options?: NodeProcessOptions): NodeProcessDriver;