@jarenjs/db 0.84.3 → 0.86.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
@@ -120,6 +121,8 @@ export function nodeDriver() {
   });
 }
 
+export { snapshotDatabase } from './snapshot.js';
+
 export {
   readDocuments, readJsonDocuments, readJsonlDocuments, readCollectionBundle,
   openAtomicTarget, openStreamTarget, openNullTarget,

package/src/drivers/snapshot.js

@@ -0,0 +1,49 @@
+//@ts-check
+/** Disk-backed SQLite snapshots shared by the Node and Bun bindings. */
+import { DbCompileError } from '../errors.js';
+
+/** Reserve a new destination and fill it through SQLite, never a JS image.
+ * @param {string} target @param {() => any} write
+ * @param {{progress?:Function}} [options] @returns {Promise<number>} */
+export async function writeSqliteSnapshot(target, write, options) {
+  if (typeof target !== 'string' || !target || target.includes('\0')) throw new TypeError('snapshot target must be a nonempty path');
+  const fs = await import('node:fs/promises');
+  const file = await fs.open(target, 'wx');
+  let complete = false;
+  try {
+    await write();
+    await file.sync();
+    const header = new Uint8Array(100);
+    const reader = await fs.open(target, 'r');
+    try { await reader.read(header, 0, header.length, 0); }
+    finally { await reader.close(); }
+    const encoded = (header[16] << 8) | header[17];
+    const pageSize = encoded === 1 ? 65536 : encoded;
+    const size = (await file.stat()).size;
+    const pages = size / pageSize;
+    options?.progress?.({ totalPages: pages, remainingPages: 0 });
+    complete = true;
+    return pages;
+  }
+  finally {
+    await file.close();
+    if (!complete) await fs.rm(target, { force: true });
+  }
+}
+
+/** Create a consistent, bounded-memory snapshot on a new path, including
+ * committed WAL data. Does not open a model store or replace a target.
+ * SQLite's page caches bound working memory; no serialize/hex image is built.
+ * @param {any} connection @param {string} target
+ * @returns {Promise<{path:string,pages:number}>} */
+export async function snapshotDatabase(connection, target) {
+  if (connection.dialect.name !== 'sqlite' || !connection.synchronous)
+    throw new DbCompileError('JD0038', 'snapshotDatabase requires a synchronous SQLite connection');
+  const write = () => connection.prepare('VACUUM INTO ?').run([target]);
+  // Acquire ownership before asynchronous filesystem work. Acquiring it
+  // afterwards would queue behind an outer transaction awaiting this call.
+  const snapshot = () => writeSqliteSnapshot(target, write);
+  const pages = await (typeof connection.exclusively === 'function'
+    ? connection.exclusively(snapshot, 'a database snapshot') : snapshot());
+  return { path: target, pages };
+}