@jarenjs/db 0.49.2 → 0.66.1

package/src/driver.js

@@ -19,20 +19,28 @@
  * specifiers. `open()` is where "this driver does not exist here"
  * becomes the coded `JD0003` instead of a module-load crash.
  *
- * `capabilities` is read once at open — from the library's version
- * report, its compile options and the binding's declaration — and is
- * the single source of truth for feature gating; never a `typeof`
- * sniff at a call site. Two slots are deliberately EMPTY on every
- * SQLite driver: `statementTimeout` (no interrupt or progress handler
- * exists to build one on) and `rowEstimates` (the query plan is prose,
- * not numbers). They exist so a driver that has the facts can fill
+ * `capabilities` is read once at open by a PROBE — the SQLite one by
+ * default, another engine's through `options.probe` — and is the single
+ * source of truth for feature gating; never a `typeof` sniff at a call
+ * site. {@link baseCapabilities} gives every slot the conservative
+ * answer, so a probe that says nothing about a feature says `false`
+ * rather than `undefined`. Two slots are deliberately EMPTY on every
+ * driver this package ships: `statementTimeout` (SQLite has no
+ * interrupt or progress handler to build one on, and a PostgreSQL
+ * server-side timeout is not the same promise as the store's
+ * `AbortSignal`) and `rowEstimates` (SQLite's query plan is prose, not
+ * numbers). They exist so a driver that has the facts can fill
  * them without a contract change; pretending SQLite has them is the
- * silent degradation this suite refuses.
+ * silent degradation this suite refuses. A third, `lazyIteration`, is
+ * probed rather than declared: whether the binding's statements carry
+ * a native row iterator, which is what lets a cursor classify itself
+ * honestly — a binding without one gets `iterate` composed over `all()`
+ * here, and the cursor over it says it buffers.
  */
 
 import { isThenable, chain, toPromise } from '@jarenjs/core/function';
 
-import { DbCompileError } from './errors.js';
+import { DbCompileError, DbRuntimeError, TransactionFailure } from './errors.js';
 
 /** The minimum SQLite the store accepts, asserted at open. */
 export const SQLITE_FLOOR = '3.45.0';
@@ -46,6 +54,19 @@ export const SQLITE_FLOOR = '3.45.0';
  */
 export const DEFAULT_QUEUE_TIMEOUT = 5000;
 
+/**
+ * Why a queued caller gave up. It is always a coded refusal — a caller
+ * has to be able to tell "you were cancelled before you ran" from every
+ * other failure — and the host's own `reason` rides along as the cause,
+ * so a cancellation that meant something specific still says it.
+ * @param {AbortSignal} [signal]
+ */
+function abortReason(signal) {
+  return new DbRuntimeError('JD2064',
+    'the call was aborted while it waited for the open transaction to settle; '
+    + 'it ran no statement', { cause: signal?.reason });
+}
+
 // the sync-capable-async helpers are `@jarenjs/core/function`'s (one
 // implementation in the suite); re-exported here because every store
 // module and the public `@jarenjs/db` surface reach them through this seam
@@ -96,18 +117,103 @@ export function lazyOpen(specifier, reason, use, args) {
  * @returns {{ run: Function, get: Function, all: Function,
  *   iterate: Function }}
  */
-export function wrapStatement(statement) {
+export function wrapStatement(statement, guard = undefined, active = undefined) {
+  const before = guard ?? (() => {});
+  const track = (source) => {
+    if (active === undefined) return source;
+    let done = false;
+    const iterator = {
+      next: () => {
+        before();
+        if (done) return { done: true, value: undefined };
+        return chain(source.next(), (step) => {
+          if (step.done) { done = true; active.delete(iterator); }
+          return step;
+        });
+      },
+      return: (value) => {
+        if (done) return { done: true, value };
+        done = true;
+        active.delete(iterator);
+        return source.return?.(value) ?? { done: true, value };
+      },
+      [Symbol.iterator]: () => iterator,
+      [Symbol.asyncIterator]: () => iterator,
+    };
+    active.add(iterator);
+    return iterator;
+  };
   return {
-    run: (params = []) => statement.run(params),
-    get: (params = []) => statement.get(params),
-    all: (params = []) => statement.all(params),
+    run: (params = []) => { before(); return statement.run(params); },
+    get: (params = []) => { before(); return statement.get(params); },
+    all: (params = []) => { before(); return statement.all(params); },
     iterate: typeof statement.iterate === 'function'
-      ? (params = []) => /** @type {Function} */ (statement.iterate)(params)
-      : (params = []) => chain(statement.all(params),
-        (rows) => rows[Symbol.iterator]()),
+      ? (params = []) => { before(); return chain(/** @type {Function} */ (statement.iterate)(params), track); }
+      : (params = []) => { before(); return chain(statement.all(params),
+        (rows) => track(rows[Symbol.iterator]())); },
   };
 }
 
+/**
+ * Run a driver call and map its failure — thrown OR rejected — through
+ * `wrap`. A `try/catch` around a value-or-promise call saw only the
+ * synchronous throw: on an asynchronous driver the failure arrived as a
+ * rejection nothing handled, so a rejected write resolved as a success
+ * and surfaced later as an unhandled rejection.
+ * @template T
+ * @param {() => T | Promise<T>} call
+ * @param {(error: any) => Error} wrap
+ * @returns {T | Promise<T>}
+ */
+export function attempt(call, wrap) {
+  let out;
+  try {
+    out = call();
+  }
+  catch (error) {
+    throw wrap(error);
+  }
+  return isThenable(out)
+    ? /** @type {Promise<T>} */ (out).then(undefined, (error) => { throw wrap(error); })
+    : out;
+}
+
+/**
+ * Settle a transaction only after its commit succeeds. Deferred constraints
+ * can refuse COMMIT or RELEASE after the body returned successfully; that
+ * failure owes the same rollback as a failing body.
+ * @param {() => any} body
+ * @param {() => any} commit
+ * @param {() => any} rollback
+ * @returns {any}
+ */
+function settleTransaction(body, commit, rollback) {
+  const fail = (error) => chain(attempt(rollback, (cleanupError) =>
+    // Losing one remote generation also loses its rollback channel.
+    // That is one failure, not two independent transaction defects.
+    error === cleanupError || error?.code === 'JD2090' && cleanupError?.code === 'JD2090'
+      && error.generation === cleanupError.generation
+      ? error : new TransactionFailure(error, cleanupError)), () => { throw error; });
+  const succeed = (value) => {
+    let committed;
+    try {
+      committed = commit();
+    }
+    catch (error) {
+      return fail(error);
+    }
+    return isThenable(committed) ? committed.then(() => value, fail) : value;
+  };
+  let out;
+  try {
+    out = body();
+  }
+  catch (error) {
+    return fail(error);
+  }
+  return isThenable(out) ? out.then(succeed, fail) : succeed(out);
+}
+
 /**
  * Finish a raw binding into the connection contract: probe the library
  * once, assert the version floor, freeze the capability table, and
@@ -115,23 +221,118 @@ export function wrapStatement(statement) {
  *
  * The raw shape a binding supplies:
  * `{ exec(sql), prepare(sql) -> { run, get, all, iterate? }, close(),
- *   registerFunction?, registerAggregate?, session? }` — every method
- * value-or-promise.
+ *   registerFunction?, registerAggregate?, session?, backup? }` — every
+ * method value-or-promise. `backup` is the online-backup primitive
+ * triple `{ copy(path, { rate, progress }), rename(from, to),
+ * remove(path) }` a binding with a platform backup API and a file
+ * system supplies; the store's `backupTo` is built on it and never
+ * touches a builtin itself.
  *
  * @param {any} raw
  * @param {{ dialect: any, synchronous?: boolean, queueTimeout?: number,
+ *   probe?: (raw: any, dialect: any, declared: any) => any,
  *   declared?: { sessions?: boolean, userFunctions?: boolean,
  *     deterministicIndexableFunctions?: boolean,
- *     aggregateFunctions?: boolean } }} options
+ *     aggregateFunctions?: boolean,
+ *     pragmas?: readonly string[],
+ *     maintenance?: Record<string, boolean>,
+ *     backup?: boolean } }} options - `declared.pragmas`
+ *   names the configuration pragmas the binding can apply (the store's
+ *   closed set, by option name); the store refuses a request outside it
+ *   and reads every declared one back after open. `declared.maintenance`
+ *   narrows the maintenance operations (`checkpoint`, `integrityCheck`,
+ *   `foreignKeyCheck`, `optimize`): every SQLite library runs them, so
+ *   an operation is available unless the binding declares it `false`
  * @returns {any} a Connection, or a promise of one
  */
 export function openConnection(raw, options) {
   const { dialect } = options;
   const synchronous = options.synchronous === true;
-  const declared = options.declared ?? {};
+  const probe = options.probe ?? sqliteProbe;
+  // The binding has already acquired its handle. A failed probe must
+  // release it here, before a store can take ownership of the connection.
+  /** @param {any} failure */
+  const failClosed = (failure) => {
+    /** @param {any} closeError */
+    const both = (closeError) => new AggregateError([failure, closeError],
+      'the connection failed to open, and closing its handle failed too');
+    const closed = attempt(() => raw.close(), both);
+    return chain(closed, () => { throw failure; });
+  };
+  let opened;
+  try {
+    opened = chain(probe(raw, dialect, options.declared ?? {}), (capabilities) =>
+      finishConnection(raw, dialect, synchronous, capabilities,
+        options.queueTimeout ?? DEFAULT_QUEUE_TIMEOUT));
+  }
+  catch (failure) {
+    return failClosed(failure);
+  }
+  return isThenable(opened) ? opened.then(undefined, failClosed) : opened;
+}
+
+/**
+ * The capability answers every connection carries, each defaulted to
+ * the conservative one. A probe fills in what its engine and binding
+ * actually supply; a slot it says nothing about reads `false` rather
+ * than `undefined`, so a feature gate is never a `typeof` sniff at a
+ * call site.
+ * @returns {Record<string, any>}
+ */
+export function baseCapabilities() {
+  return {
+    version: '',
+    jsonb: false,
+    generatedColumns: false,
+    returning: false,
+    upsert: false,
+    savepoints: false,
+    rtree: false,
+    fts: false,
+    sessions: false,
+    sessionReason: null,
+    worker: false,
+    pooling: false,
+    poolReaders: 0,
+    poolWriters: 0,
+    userFunctions: false,
+    deterministicIndexableFunctions: false,
+    aggregateFunctions: false,
+    configurablePragmas: Object.freeze([]),
+    backup: false,
+    maintenance: Object.freeze({
+      checkpoint: false, integrityCheck: false, foreignKeyCheck: false, optimize: false,
+    }),
+    alterTableFull: false,
+    statementTimeout: false,
+    rowEstimates: false,
+    lazyIteration: false,
+    // the job queue, the change ledger and the live registry are built
+    // on SQLite's own spellings; a store on another engine reports them
+    // absent by name rather than failing at the first statement
+    jobs: false,
+    changeCapture: false,
+  };
+}
+
+/**
+ * The SQLite probe: the library's version report and compile options,
+ * plus what the binding declares it can do. It is the DEFAULT probe
+ * because every binding this package ships is a SQLite one; a driver
+ * for another engine passes its own through `options.probe`, and the
+ * version floor asserted here goes with it.
+ * @param {any} raw
+ * @param {any} dialect
+ * @param {Record<string, any>} declared
+ * @returns {any} value-or-promise of the frozen capability table
+ */
+export function sqliteProbe(raw, dialect, declared) {
   return chain(raw.prepare(dialect.introspect.version()), (versionStatement) =>
     chain(versionStatement.get([]), (versionRow) => {
       const version = String(versionRow.version);
+      // the binding's statements either carry a lazy iterator or they
+      // do not; the probe statement is one of them
+      const lazyIteration = typeof versionStatement.iterate === 'function';
       if (compareVersions(version, SQLITE_FLOOR) < 0) {
         throw new DbCompileError('JD0001',
           `the SQLite library is ${version}, below the supported floor ${SQLITE_FLOOR}`);
@@ -139,7 +340,8 @@ export function openConnection(raw, options) {
       return chain(raw.prepare(dialect.introspect.compileOptions()), (optionsStatement) =>
         chain(optionsStatement.all([]), (rows) => {
           const compiled = new Set(rows.map((row) => String(row.name)));
-          const capabilities = Object.freeze({
+          return Object.freeze({
+            ...baseCapabilities(),
             version,
             // guaranteed by the version floor
             jsonb: true,
@@ -155,6 +357,7 @@ export function openConnection(raw, options) {
             sessions: declared.sessions === true
               && typeof raw.session === 'function'
               && compiled.has('ENABLE_SESSION'),
+            sessionReason: raw.sessionReason ?? null,
             userFunctions: declared.userFunctions === true
               && typeof raw.registerFunction === 'function',
             deterministicIndexableFunctions:
@@ -166,15 +369,40 @@ export function openConnection(raw, options) {
             // method AND declare it.
             aggregateFunctions: declared.aggregateFunctions === true
               && typeof raw.registerAggregate === 'function',
+            // the configuration pragmas the binding applies, by the
+            // store's option name — a request outside this list is a
+            // coded refusal at open, never a silently skipped member
+            configurablePragmas: Object.freeze([...(declared.pragmas ?? [])]),
+            // the online backup: the binding must supply the primitive
+            // triple AND declare it — the platform API and the file
+            // system it needs are the binding's, not the library's
+            backup: declared.backup === true && raw.backup !== null && typeof raw.backup === 'object'
+              && typeof raw.backup.copy === 'function' && typeof raw.backup.rename === 'function'
+              && typeof raw.backup.remove === 'function',
+            // the maintenance pragmas are the library's, not the
+            // binding's: available unless declared absent, and the
+            // store's report says so per operation
+            maintenance: Object.freeze({
+              checkpoint: declared.maintenance?.checkpoint !== false,
+              integrityCheck: declared.maintenance?.integrityCheck !== false,
+              foreignKeyCheck: declared.maintenance?.foreignKeyCheck !== false,
+              optimize: declared.maintenance?.optimize !== false,
+            }),
             // structural SQLite limits — stated, not worked around
             alterTableFull: false,
             // the slots every SQLite driver leaves EMPTY (no
             // interrupt, no progress handler, no estimate API)
             statementTimeout: false,
             rowEstimates: false,
+            // whether a cursor can pull one row at a time, or the driver
+            // materialises the result on the first pull (declared, so
+            // the cursor's own report is honest about it)
+            lazyIteration,
+            // the job queue and the change ledger are SQLite spellings,
+            // and every SQLite binding runs them
+            jobs: true,
+            changeCapture: true,
           });
-          return finishConnection(raw, dialect, synchronous, capabilities,
-            options.queueTimeout ?? DEFAULT_QUEUE_TIMEOUT);
         }));
     }));
 }
@@ -203,14 +431,26 @@ export function openConnection(raw, options) {
  * @param {any} dialect
  * @param {boolean} synchronous
  * @param {Readonly<Record<string, any>>} capabilities
+ * @param {number} queueTimeout
  * @returns {any}
  */
-function finishConnection(raw, dialect, synchronous, capabilities, queueTimeout) {
+export function finishConnection(raw, dialect, synchronous, capabilities, queueTimeout) {
+  const activeIterators = new Set();
   /** Savepoint names are never reused, so a stale name can never be
    * mistaken for a live one in an error or a log. */
   let savepointSeq = 0;
   /** Whether a top-level transaction currently owns the connection. */
   let owned = false;
+  /**
+   * Whether a transaction BLOCK is open on this connection right now.
+   *
+   * Only an engine whose `SAVEPOINT` does not start a transaction needs
+   * the answer, and it needs it for one decision: a checkpoint asked
+   * for outside a block has to open the block first, because there is
+   * nothing for it to be a checkpoint OF. On SQLite a bare `SAVEPOINT`
+   * IS the block, and the flag is never read.
+   */
+  let inBlock = false;
   /**
    * Whether an owning callback is on the stack RIGHT NOW — set around the
    * synchronous extent of every transaction body, cleared the moment it
@@ -223,6 +463,17 @@ function finishConnection(raw, dialect, synchronous, capabilities, queueTimeout)
   let onStack = false;
   /** @type {Array<() => void>} FIFO of work waiting for the owner. */
   const waiting = [];
+  /** Set by `close()`: every later call is refused by name rather than
+   * leaking the binding's own error (or, on a build that tolerates it,
+   * running against a closed handle). */
+  let closed = false;
+  let closeResult;
+  const requireOpen = () => {
+    if (closed) {
+      throw new DbRuntimeError('JD2063',
+        'the store is closed — a call after close() has no connection to run on');
+    }
+  };
 
   /** Hand the connection to the next waiter, in arrival order. */
   const release = () => {
@@ -242,28 +493,46 @@ function finishConnection(raw, dialect, synchronous, capabilities, queueTimeout)
    * instead of the scope it was handed (never — it is waiting for itself).
    * The bound turns the second case from a silent hang into a coded error
    * that names the fix, the same trade SQLite's own busy timeout makes.
+   * A caller that gives up while queued — an aborted signal — is taken
+   * off the queue and rejected with its own reason, and `work` never
+   * runs at all. That is the difference between cancelling a request
+   * and cancelling its effect.
    * @param {() => any} work
    * @param {string} what - what is waiting, for the timeout message
+   * @param {AbortSignal} [signal] - abandons the wait when it aborts
    * @returns {any} value-or-promise
    */
-  const whenFree = (work, what) => {
+  const whenFree = (work, what, signal) => {
+    if (signal?.aborted === true) return Promise.reject(abortReason(signal));
     if (!owned) return work();
     return new Promise((resolve, reject) => {
       let done = false;
-      const timer = setTimeout(() => {
+      /** Leave the queue without running: the turn passes to the next
+       * waiter when the owner releases, exactly as a timeout's does. */
+      const abandon = (error) => {
         done = true;
         const index = waiting.indexOf(run);
         if (index >= 0) waiting.splice(index, 1);
-        reject(new DbCompileError('JD0012',
-          `${what} waited ${queueTimeout}ms for the open transaction to settle. `
-          + 'A transaction owns its connection until it commits; work that belongs '
-          + 'INSIDE it must go through the scope the callback received '
-          + '(scope.transaction / the store passed to your callback), not the '
-          + 'outer connection — that request waits for itself.'));
-      }, queueTimeout);
+        // a wait that ends by timeout owes the signal its listener back
+        signal?.removeEventListener('abort', cancelled);
+        reject(error);
+      };
+      const timer = setTimeout(() => abandon(new DbCompileError('JD0012',
+        `${what} waited ${queueTimeout}ms for the open transaction to settle. `
+        + 'A transaction owns its connection until it commits; work that belongs '
+        + 'INSIDE it must go through the store or client the callback received '
+        + '(tx.collection / tx.entity / tx.entities / tx.transaction), not the '
+        + 'outer one — that request waits for itself.')),
+      queueTimeout);
+      const cancelled = () => {
+        clearTimeout(timer);
+        abandon(abortReason(signal));
+      };
+      signal?.addEventListener('abort', cancelled, { once: true });
       const run = () => {
         if (done) { release(); return; } // already rejected: pass the turn on
         clearTimeout(timer);
+        signal?.removeEventListener('abort', cancelled);
         done = true;
         let out;
         try {
@@ -279,33 +548,136 @@ function finishConnection(raw, dialect, synchronous, capabilities, queueTimeout)
     });
   };
 
-  /** Open one savepoint around `fn`, at whatever depth we are. `fn`
-   * receives the scope so nested work can name itself.
+  /**
+   * Hold the connection for `fn`'s whole extent without opening a
+   * savepoint: what an UNRELATED caller needs so its statements cannot
+   * fall inside a transaction it is not part of. A store-level read or
+   * write is exactly that caller — it waits for the owner, owns the
+   * connection while it runs, and hands it on.
+   *
+   * `fn` receives a scope for the same reason a transaction callback
+   * does: work that must nest inside this one (a membership attach, a
+   * unit of work's own transaction) says so through the scope rather
+   * than queueing behind the caller it is part of.
    * @param {(scope: any) => any} fn
+   * @param {string} [what] - what is waiting, for the timeout message
+   * @param {AbortSignal} [signal]
    */
-  const savepointAround = (fn) => {
-    const name = `jaren_sp_${savepointSeq++}`;
-    const succeed = (result) => chain(raw.exec(dialect.tx.release(name)), () => result);
-    const fail = (error) => chain(raw.exec(dialect.tx.rollbackTo(name)), () =>
-      chain(raw.exec(dialect.tx.release(name)), () => {
-        throw error;
-      }));
-    return chain(raw.exec(dialect.tx.savepoint(name)), () => {
-      let out;
+  const exclusively = (fn, what, signal) => {
+    requireOpen();
+    // a synchronous extent inside an owning callback cannot interleave
+    // with anything, so there is nothing to wait for
+    if (onStack) return fn(scopeFor());
+    return whenFree(() => {
+      owned = true;
       const wasOnStack = onStack;
       onStack = true;
+      let out;
       try {
         out = fn(scopeFor());
       }
       catch (error) {
         onStack = wasOnStack;
-        return fail(error);
+        release();
+        throw error;
+      }
+      onStack = wasOnStack;
+      if (!isThenable(out)) {
+        release();
+        return out;
       }
-      onStack = wasOnStack; // the body has returned or awaited
-      return isThenable(out) ? out.then(succeed, fail) : succeed(out);
+      return out.then(
+        (value) => { release(); return value; },
+        (error) => { release(); throw error; });
+    }, what ?? 'a store-level call', signal);
+  };
+
+  /**
+   * The ONE checkpoint primitive both savepoint kinds are built on: a
+   * structured `transaction()` nesting opens one and settles it around
+   * its callback, and a scope's manual `savepoint()` opens one the
+   * caller settles by name. Every checkpoint wears a generated
+   * monotonic identifier from the same sequence, so the two kinds share
+   * one engine stack and no caller-supplied label ever reaches SQL.
+   * The handle is opaque: the store's label bookkeeping lives above it.
+   * @returns {any} value-or-promise of `{ name }`
+   */
+  const openCheckpoint = () => {
+    const name = `jaren_sp_${savepointSeq++}`;
+    return chain(raw.exec(dialect.tx.savepoint(name)),
+      () => Object.freeze({ name }));
+  };
+  /** `ROLLBACK TO` a checkpoint: the engine keeps the target active and
+   * discards every savepoint opened after it.
+   * @param {{ name: string }} checkpoint */
+  const rollbackToCheckpoint = (checkpoint) =>
+    raw.exec(dialect.tx.rollbackTo(checkpoint.name));
+  /** `RELEASE` a checkpoint: the engine removes the target and every
+   * savepoint opened after it, keeping their rows.
+   * @param {{ name: string }} checkpoint */
+  const releaseCheckpoint = (checkpoint) =>
+    raw.exec(dialect.tx.release(checkpoint.name));
+
+  /** Only the synchronous extent of the callback may implicitly nest. */
+  const callBody = (fn) => {
+    const wasOnStack = onStack;
+    onStack = true;
+    try {
+      return fn(scopeFor());
+    }
+    finally {
+      onStack = wasOnStack;
+    }
+  };
+
+  /**
+   * Own the connection inside a transaction BLOCK: `BEGIN` (or `BEGIN
+   * IMMEDIATE`) around `fn`, committed or rolled back as a whole.
+   *
+   * The `immediate` mode takes the write lock up front. A body
+   * that reads before it writes — a claim: read the record, decide,
+   * insert — otherwise meets the read→write upgrade `SQLITE_BUSY` the
+   * busy handler cannot retry when another connection commits in
+   * between; taking the lock first makes that wait an ordinary busy
+   * wait the timeout covers. Nesting inside it is savepoints, as always.
+   * @param {(scope: any) => any} fn
+   */
+  const blockAround = (fn, mode) => {
+    const begin = mode === 'immediate' ? dialect.tx.beginImmediate : dialect.tx.begin;
+    return chain(raw.exec(begin), () => {
+      let out;
+      const wasInBlock = inBlock;
+      inBlock = true;
+      const restore = (value) => { inBlock = wasInBlock; return value; };
+      try {
+        out = settleTransaction(() => callBody(fn),
+          () => raw.exec(dialect.tx.commit), () => raw.exec(dialect.tx.rollback));
+      }
+      catch (error) {
+        restore(undefined);
+        throw error;
+      }
+      return isThenable(out)
+        ? out.then(restore, (error) => { restore(undefined); throw error; })
+        : restore(out);
     });
   };
 
+  /** Open one savepoint around `fn`, at whatever depth we are. `fn`
+   * receives the scope so nested work can name itself.
+   * @param {(scope: any) => any} fn
+   */
+  const savepointAround = (fn) => {
+    // an engine that refuses a savepoint outside a transaction gets the
+    // block it needs; on every other one this is the same statement it
+    // always was
+    if (!inBlock && dialect.capabilities.savepointStartsTransaction !== true)
+      return blockAround(fn, 'deferred');
+    return chain(openCheckpoint(), (checkpoint) => settleTransaction(() => callBody(fn),
+      () => releaseCheckpoint(checkpoint),
+      () => chain(rollbackToCheckpoint(checkpoint), () => releaseCheckpoint(checkpoint))));
+  };
+
   /** The scope handed to a transaction callback: the owner's direct
    * access to the connection, plus nesting. Deliberately narrow —
    * registering a function or opening a change session belongs to store
@@ -315,12 +687,26 @@ function finishConnection(raw, dialect, synchronous, capabilities, queueTimeout)
     capabilities,
     dialect,
     /** @param {string} sql */
-    exec: (sql) => raw.exec(sql),
+    exec: (sql) => { requireOpen(); return raw.exec(sql); },
     /** @param {string} sql */
-    prepare: (sql) => chain(raw.prepare(sql), wrapStatement),
+    prepare: (sql, metadata) => { requireOpen(); return chain(raw.prepare(sql, metadata), (s) => wrapStatement(s, requireOpen, activeIterators)); },
     /** A nested savepoint inside this transaction.
      * @param {(scope: any) => any} fn */
     transaction: (fn) => savepointAround(fn),
+    /** A MANUAL checkpoint at the current depth, settled by the caller
+     * through {@link rollbackTo}/{@link release} rather than around a
+     * callback. It is the same primitive structured nesting uses — one
+     * generated-identifier stack — so the two kinds cannot cross-release
+     * each other by name, and no caller-supplied label reaches SQL. */
+    savepoint: () => { requireOpen(); return openCheckpoint(); },
+    /** `ROLLBACK TO` a manual checkpoint: the target stays active; every
+     * savepoint opened after it is discarded with its rows.
+     * @param {{ name: string }} checkpoint */
+    rollbackTo: (checkpoint) => { requireOpen(); return rollbackToCheckpoint(checkpoint); },
+    /** `RELEASE` a manual checkpoint: the target and every savepoint
+     * opened after it are removed; their rows remain.
+     * @param {{ name: string }} checkpoint */
+    release: (checkpoint) => { requireOpen(); return releaseCheckpoint(checkpoint); },
   });
 
   return Object.freeze({
@@ -328,22 +714,27 @@ function finishConnection(raw, dialect, synchronous, capabilities, queueTimeout)
     capabilities,
     dialect,
     /** @param {string} sql */
-    // NOT gated. A statement issued while a transaction is open joins it,
-    // because a SQLite connection has no per-statement transaction scope
-    // and every caller inside a transaction reaches the connection this
-    // way. Two consequences, both documented in MODEL-FORMAT §Transactions:
-    // work inside a callback runs immediately as the owner (right), and an
-    // UNRELATED caller's bare write on a shared store joins that
-    // transaction and shares its fate (a single connection cannot tell the
-    // two apart — give each concurrent writer its own store to separate
-    // them). What the gate below does guarantee is that two TRANSACTIONS
-    // never interleave, which is what made commits report failure.
-    exec: (sql) => raw.exec(sql),
+    // NOT gated, because a SQLite connection has no per-statement
+    // transaction scope: a statement issued here joins whatever is open.
+    // That is right for work INSIDE the transaction, which is why the
+    // scope exposes the same two methods. An unrelated caller must not
+    // reach them — it takes `exclusively` instead, which holds the
+    // connection for its own extent, and the store's handles do exactly
+    // that (MODEL-FORMAT §5.1). What the gate guarantees on top is that
+    // two TRANSACTIONS never interleave, which is what made commits
+    // report failure.
+    exec: (sql) => { requireOpen(); return raw.exec(sql); },
     /** @param {string} sql */
-    prepare: (sql) => chain(raw.prepare(sql), wrapStatement),
+    prepare: (sql, metadata) => { requireOpen(); return chain(raw.prepare(sql, metadata), (s) => wrapStatement(s, requireOpen, activeIterators)); },
+    /** Whether a transaction issued NOW would have to queue: an owner
+     * holds the connection and no owning callback is on the stack (a
+     * synchronous call from inside the callback nests instead). What a
+     * synchronous surface must know before it would hand back a Promise. */
+    get mustQueue() { return owned && !onStack; },
     /**
      * A transaction. `fn`'s value is returned; a throw rolls back exactly
-     * this level and rethrows. No implicit retry.
+     * this level and rethrows. A refused COMMIT or RELEASE also rolls
+     * back before the next owner runs. No implicit retry.
      *
      * Two shapes, decided here rather than by the caller:
      *
@@ -361,14 +752,26 @@ function finishConnection(raw, dialect, synchronous, capabilities, queueTimeout)
      * queues behind the transaction the caller is part of, and
      * {@link DEFAULT_QUEUE_TIMEOUT} turns that into `JD0012`.
      * @param {(scope: any) => any} fn
+     * @param {AbortSignal} [signal] - abandons a QUEUED transaction; a
+     *   transaction that has already taken the connection runs on
+     * @param {'deferred' | 'immediate'} [mode] - `'immediate'` takes the
+     *   write lock up front (a top-level transaction only; a nested call
+     *   is a savepoint whichever mode the root chose)
      */
-    transaction(fn) {
+    transaction(fn, signal, mode = 'deferred') {
+      requireOpen();
       if (onStack) return savepointAround(fn);
       return whenFree(() => {
         owned = true;
         let out;
         try {
-          out = savepointAround(fn);
+          // A top-level transaction is one CHECKPOINT where a savepoint
+          // opens a transaction of its own, and a BLOCK where it does
+          // not: an engine that refuses `SAVEPOINT` outside a
+          // transaction has to be told one is starting.
+          out = mode === 'immediate' || dialect.capabilities.savepointStartsTransaction !== true
+            ? blockAround(fn, mode)
+            : savepointAround(fn);
         }
         catch (error) {
           release();
@@ -381,17 +784,48 @@ function finishConnection(raw, dialect, synchronous, capabilities, queueTimeout)
         return out.then(
           (value) => { release(); return value; },
           (error) => { release(); throw error; });
-      }, 'a transaction');
+      }, 'a transaction', signal);
+    },
+    /** Hold the connection for one unrelated caller's whole extent,
+     * without a savepoint: what a store-level read or write takes so it
+     * cannot fall inside a transaction it is not part of. */
+    exclusively,
+    // idempotent: the second close is a no-op on every driver, not a
+    // raw error on one and a resolved promise on another
+    close: () => {
+      if (closed) return closeResult;
+      closed = true;
+      // Remote hosts own cursor cleanup within their bounded shutdown.
+      // Waiting for a row here would postpone that deadline indefinitely.
+      if (raw.closeDrainsIterators === true) {
+        activeIterators.clear();
+        return closeResult = raw.close();
+      }
+      const pending = [];
+      for (const iterator of activeIterators) {
+        try { pending.push(iterator.return()); }
+        catch (error) { pending.push(Promise.reject(error)); }
+      }
+      if (pending.some(isThenable)) return closeResult = Promise.allSettled(pending).then(() => raw.close());
+      return closeResult = raw.close();
     },
-    close: () => raw.close(),
     registerFunction: typeof raw.registerFunction === 'function'
-      ? (name, functionOptions, fn) => raw.registerFunction(name, functionOptions, fn)
+      ? (name, functionOptions, fn) => { requireOpen(); return raw.registerFunction(name, functionOptions, fn); }
       : null,
     registerAggregate: typeof raw.registerAggregate === 'function'
-      ? (name, spec) => raw.registerAggregate(name, spec)
+      ? (name, spec) => { requireOpen(); return raw.registerAggregate(name, spec); }
       : null,
     session: typeof raw.session === 'function'
-      ? (table) => raw.session(table)
+      ? (table) => { requireOpen(); return raw.session(table); }
+      : null,
+    // the backup primitives, each refused by name once the store is
+    // closed exactly as a statement is
+    backup: capabilities.backup === true
+      ? Object.freeze({
+        copy: (path, options) => { requireOpen(); return raw.backup.copy(path, options); },
+        rename: (from, to) => { requireOpen(); return raw.backup.rename(from, to); },
+        remove: (path) => { requireOpen(); return raw.backup.remove(path); },
+      })
       : null,
   });
 }