@jarenjs/db 0.34.0 → 0.43.1

package/src/dialect.js

@@ -42,6 +42,8 @@
  *   limitClause: (limit: number, offset?: number) => string,
  *   jsonPathText: (segments: JsonPathSegment[]) => string | null,
  *   jsonExtract: (columnSql: string, pathText: string) => string,
+ *   derivedExpression?: (memberSql: string, column: { derive: string,
+ *     precision?: number, component?: string }) => string,
  *   jsonSet: (exprSql: string, pathText: string, valueSql: string) => string,
  *   jsonRemove: (exprSql: string, pathText: string) => string,
  *   jsonAppend: (exprSql: string, arrayPathText: string, valueSql: string) => string,
@@ -50,7 +52,8 @@
  *   jsonAgg: (exprSql: string) => string,
  *   jsonTypeOf: (columnSql: string, pathText: string) => string,
  *   valueTypeOf: (paramSql: string) => string,
- *   strStartsWith: (valueSql: string, patternA: string, patternB: string) => string,
+ *   strStartsWith: (valueSql: string, lowerParamSql: string, upperParamSql: string) => string,
+ *   strStartsWithExact: (valueSql: string, patternA: string, patternB: string) => string,
  *   strEndsWith: (valueSql: string, patternA: string, patternB: string, patternC: string) => string,
  *   strContains: (valueSql: string, patternSql: string) => string,
  *   orderNulls: (nullsFirst: boolean) => string,
@@ -77,6 +80,24 @@ export function createDialect(spec) {
   const q = spec.quoteIdentifier;
   const p = spec.parameterRef;
 
+  /**
+   * One planned column's definition. A path column is a VIRTUAL
+   * generated column over the document; a DERIVED column is the same
+   * shape over a registered deterministic function, except where the
+   * driver cannot index one — there the store writes the value and the
+   * column is an ordinary one.
+   * @param {string} docColumn
+   * @param {{ name: string, type: string, pathText: string,
+   *   expression?: string | null, stored?: boolean }} column
+   * @returns {string}
+   */
+  const generatedColumnSql = (docColumn, column) => {
+    if (column.stored === true) return `${q(column.name)} ${column.type}`;
+    const expression = column.expression
+      ?? spec.jsonExtract(q(docColumn), column.pathText);
+    return `${q(column.name)} ${column.type} GENERATED ALWAYS AS (${expression}) VIRTUAL`;
+  };
+
   const ddl = Object.freeze({
     /**
      * One collection's physical table: a key column, the JSON document
@@ -90,9 +111,7 @@ export function createDialect(spec) {
       const columns = [
         `${q(keyColumn)} ${keyType} PRIMARY KEY`,
         `${q(docColumn)} ${spec.docColumnType} NOT NULL`,
-        ...generated.map((g) =>
-          `${q(g.name)} ${g.type} GENERATED ALWAYS AS `
-          + `(${spec.jsonExtract(q(docColumn), g.pathText)}) VIRTUAL`),
+        ...generated.map((g) => generatedColumnSql(docColumn, g)),
       ];
       return `CREATE TABLE ${q(table)} (${columns.join(', ')})${spec.tableSuffix}`;
     },
@@ -113,8 +132,7 @@ export function createDialect(spec) {
      * @returns {string}
      */
     addGeneratedColumn({ table, docColumn, column }) {
-      return `ALTER TABLE ${q(table)} ADD COLUMN ${q(column.name)} ${column.type} `
-        + `GENERATED ALWAYS AS (${spec.jsonExtract(q(docColumn), column.pathText)}) VIRTUAL`;
+      return `ALTER TABLE ${q(table)} ADD COLUMN ${generatedColumnSql(docColumn, column)}`;
     },
     /**
      * @param {string} table
@@ -217,26 +235,47 @@ export function createDialect(spec) {
   });
 
   const dml = Object.freeze({
-    /** @param {{ table: string, keyColumn: string, docColumn: string }} s */
-    insert({ table, keyColumn, docColumn }) {
-      return `INSERT INTO ${q(table)} (${q(keyColumn)}, ${q(docColumn)}) `
-        + `VALUES (${p(1, 'key')}, ${spec.jsonEncode(p(2, 'doc'))})`;
+    /**
+     * A collection insert. `stored` names the derived columns the
+     * store computes itself — empty on every driver that can index a
+     * registered function, because there the column generates itself.
+     * @param {{ table: string, keyColumn: string, docColumn: string,
+     *   stored?: string[] }} s
+     */
+    insert({ table, keyColumn, docColumn, stored }) {
+      const extra = stored ?? [];
+      const names = [q(keyColumn), q(docColumn), ...extra.map(q)];
+      const values = [p(1, 'key'), spec.jsonEncode(p(2, 'doc')),
+        ...extra.map((name, i) => p(i + 3, name))];
+      return `INSERT INTO ${q(table)} (${names.join(', ')}) VALUES (${values.join(', ')})`;
     },
     /**
      * Insert with a database-allocated key, read back in the same
      * statement.
-     * @param {{ table: string, keyColumn: string, docColumn: string }} s
+     * @param {{ table: string, keyColumn: string, docColumn: string,
+     *   stored?: string[] }} s
      */
-    insertAllocated({ table, keyColumn, docColumn }) {
-      return `INSERT INTO ${q(table)} (${q(docColumn)}) `
-        + `VALUES (${spec.jsonEncode(p(1, 'doc'))}) RETURNING ${q(keyColumn)} AS ${q('key')}`;
+    insertAllocated({ table, keyColumn, docColumn, stored }) {
+      const extra = stored ?? [];
+      const names = [q(docColumn), ...extra.map(q)];
+      const values = [spec.jsonEncode(p(1, 'doc')),
+        ...extra.map((name, i) => p(i + 2, name))];
+      return `INSERT INTO ${q(table)} (${names.join(', ')}) VALUES (${values.join(', ')}) `
+        + `RETURNING ${q(keyColumn)} AS ${q('key')}`;
     },
-    /** @param {{ table: string, keyColumn: string, docColumn: string }} s */
-    upsert({ table, keyColumn, docColumn }) {
-      return `INSERT INTO ${q(table)} (${q(keyColumn)}, ${q(docColumn)}) `
-        + `VALUES (${p(1, 'key')}, ${spec.jsonEncode(p(2, 'doc'))}) `
-        + `ON CONFLICT (${q(keyColumn)}) DO UPDATE SET `
-        + `${q(docColumn)} = ${spec.excludedRef(q(docColumn))}`;
+    /**
+     * @param {{ table: string, keyColumn: string, docColumn: string,
+     *   stored?: string[] }} s
+     */
+    upsert({ table, keyColumn, docColumn, stored }) {
+      const extra = stored ?? [];
+      const names = [q(keyColumn), q(docColumn), ...extra.map(q)];
+      const values = [p(1, 'key'), spec.jsonEncode(p(2, 'doc')),
+        ...extra.map((name, i) => p(i + 3, name))];
+      const assignments = [q(docColumn), ...extra.map(q)]
+        .map((column) => `${column} = ${spec.excludedRef(column)}`);
+      return `INSERT INTO ${q(table)} (${names.join(', ')}) VALUES (${values.join(', ')}) `
+        + `ON CONFLICT (${q(keyColumn)}) DO UPDATE SET ${assignments.join(', ')}`;
     },
     /** @param {{ table: string, keyColumn: string, docColumn: string }} s */
     get({ table, keyColumn, docColumn }) {
@@ -250,13 +289,26 @@ export function createDialect(spec) {
     /**
      * Rewrite the document column through a JSON-set expression chain
      * (the translated-patch path) or a bound parameter (the fallback).
-     * @param {{ table: string, keyColumn: string, docColumn: string }} s
+     * Stored derived columns are rewritten with it — they are computed
+     * FROM the document, so leaving them behind would let a query read a
+     * value the document no longer carries.
+     *
+     * `nextParam` is the first FREE parameter slot after the
+     * expression's own: the derived values take it and the ones after
+     * it, and the key binds LAST. That order is the statement's TEXT
+     * order, which is what a positional dialect numbers by — and with
+     * no derived columns it degenerates to the key at `nextParam`.
+     * @param {{ table: string, keyColumn: string, docColumn: string,
+     *   stored?: string[] }} s
      * @param {string} expression - SQL over the document column
-     * @param {number} keyIndex - 1-based position of the key parameter
+     * @param {number} nextParam - 1-based first free parameter slot
      */
-    updateDoc({ table, keyColumn, docColumn }, expression, keyIndex) {
-      return `UPDATE ${q(table)} SET ${q(docColumn)} = ${expression} `
-        + `WHERE ${q(keyColumn)} = ${p(keyIndex, 'key')}`;
+    updateDoc({ table, keyColumn, docColumn, stored }, expression, nextParam) {
+      const extra = stored ?? [];
+      const assignments = [`${q(docColumn)} = ${expression}`,
+        ...extra.map((name, i) => `${q(name)} = ${p(nextParam + i, name)}`)];
+      return `UPDATE ${q(table)} SET ${assignments.join(', ')} `
+        + `WHERE ${q(keyColumn)} = ${p(nextParam + extra.length, 'key')}`;
     },
   });
 
@@ -272,6 +324,17 @@ export function createDialect(spec) {
     limitClause: spec.limitClause,
     jsonPathText: spec.jsonPathText,
     jsonExtract: spec.jsonExtract,
+    /**
+     * The expression a DERIVED column is generated from: the member at
+     * the index path, as JSON text, handed to the deterministic
+     * function that computes the cell or the box edge.
+     * @param {string} docColumnSql
+     * @param {string} pathText
+     * @param {{ derive: string, precision?: number, component?: string }} column
+     * @returns {string}
+     */
+    derivedColumn: (docColumnSql, pathText, column) => spec.derivedExpression(
+      spec.jsonText(spec.jsonExtract(docColumnSql, pathText)), column),
     jsonSet: spec.jsonSet,
     jsonRemove: spec.jsonRemove,
     jsonAppend: spec.jsonAppend,
@@ -281,6 +344,7 @@ export function createDialect(spec) {
     jsonTypeOf: spec.jsonTypeOf,
     valueTypeOf: spec.valueTypeOf,
     strStartsWith: spec.strStartsWith,
+    strStartsWithExact: spec.strStartsWithExact,
     strEndsWith: spec.strEndsWith,
     strContains: spec.strContains,
     orderNulls: spec.orderNulls,

package/src/dialects/sqlite.js

@@ -101,6 +101,14 @@ export const sqliteDialect = createDialect({
   jsonPathText,
   jsonExtract: (columnSql, pathText) =>
     `jsonb_extract(${columnSql}, ${stringLiteral(pathText)})`,
+  // a DERIVED column's expression: the member as JSON text handed to
+  // the deterministic function the store registers at open. The
+  // precision is a LITERAL, not a parameter — a generated column's
+  // expression takes none — which is also what makes two precisions
+  // over one path two different columns by declared text.
+  derivedExpression: (memberSql, column) => (column.derive === 'geohash'
+    ? `jaren_geohash(${memberSql}, ${Math.trunc(Number(column.precision))})`
+    : `jaren_bbox_${column.component}(${memberSql})`),
   jsonSet: (exprSql, pathText, valueSql) =>
     `jsonb_set(${exprSql}, ${stringLiteral(pathText)}, ${valueSql})`,
   jsonRemove: (exprSql, pathText) =>
@@ -113,7 +121,14 @@ export const sqliteDialect = createDialect({
   jsonTypeOf: (columnSql, pathText) =>
     `json_type(${columnSql}, ${stringLiteral(pathText)})`,
   valueTypeOf: (paramSql) => `typeof(${paramSql})`,
-  strStartsWith: (valueSql, patternA, patternB) =>
+  // the half-open range over the prefix, which an index on the value
+  // can seek; `substr(value, 1, n) = p` and `value LIKE 'p%'` both read
+  // every row. SQLite's default BINARY collation compares UTF-8 bytes,
+  // which orders code points, so the range holds exactly the values
+  // that begin with the prefix
+  strStartsWith: (valueSql, lowerParamSql, upperParamSql) =>
+    `(${valueSql} >= ${lowerParamSql} AND ${valueSql} < ${upperParamSql})`,
+  strStartsWithExact: (valueSql, patternA, patternB) =>
     `substr(${valueSql}, 1, length(${patternA})) = ${patternB}`,
   strEndsWith: (valueSql, patternA, patternB, patternC) =>
     `(length(${patternA}) = 0 OR substr(${valueSql}, -length(${patternB})) = ${patternC})`,

package/src/driver.js

@@ -30,6 +30,8 @@
  * silent degradation this suite refuses.
  */
 
+import { isThenable, chain, toPromise } from '@jarenjs/core/function';
+
 import { DbCompileError } from './errors.js';
 
 /** The minimum SQLite the store accepts, asserted at open. */
@@ -44,34 +46,10 @@ export const SQLITE_FLOOR = '3.45.0';
  */
 export const DEFAULT_QUEUE_TIMEOUT = 5000;
 
-/**
- * @param {any} value
- * @returns {boolean} true when the value is a thenable
- */
-export function isThenable(value) {
-  return value !== null && typeof value === 'object' && typeof value.then === 'function';
-}
-
-/**
- * Sync-capable-async composition: apply `next` to a driver result
- * without allocating a promise when the result is already a value.
- * @param {any} value - A driver return: a value or a promise
- * @param {(value: any) => any} next
- * @returns {any} `next`'s result, promise-wrapped only if the input was
- */
-export function chain(value, next) {
-  return isThenable(value) ? value.then(next) : next(value);
-}
-
-/**
- * Lift a driver result into a promise — the ONE allocation the public
- * asynchronous surface pays per call.
- * @param {any} value
- * @returns {Promise<any>}
- */
-export function toPromise(value) {
-  return isThenable(value) ? value : Promise.resolve(value);
-}
+// 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
+export { isThenable, chain, toPromise };
 
 /**
  * Compare two dotted version strings numerically.

package/src/emit.js

@@ -16,10 +16,84 @@
  * logic never decides a row.
  */
 
+import { codePointPrefixSuccessor } from '@jarenjs/core/string';
+
 /**
- * @typedef {{ external: string } | { literal: unknown }} ParamSlot
+ * @typedef {{ external: string } | { literal: unknown } |
+ *   { derived: { kind: 'bboxAxis', external: string,
+ *     axis: 'w' | 's' | 'e' | 'n' } }} ParamSlot
+ *   Three kinds, closed. A DERIVED slot is the escape for a value SQL
+ *   cannot bind at all: a GeoJSON region arrives as an external object,
+ *   and what the statement needs is one edge of its bounding box, so
+ *   the binder computes that edge from the bound value. It is the same
+ *   shape the prefix successor uses — compute in JavaScript what SQL
+ *   cannot, bind an ordinary parameter — and it stays closed on
+ *   purpose: a general expression slot would be a second query language
+ *   living in the emitter.
  */
 
+/**
+ * The SQL for one string predicate. The prefix case is the only one
+ * with an index-usable spelling: a function of the value (`substr`) or
+ * a pattern match (`LIKE`) can only be scanned, while the half-open
+ * range `value >= p AND value < successor(p)` is a seek, and holds
+ * exactly the values beginning with `p` under a code-point ordering.
+ * The planner reaches here only with a non-empty literal pattern, so
+ * the successor is computable at emit time and needs no slot kind of
+ * its own; the one pattern that has no successor keeps the scannable
+ * form, which is correct, merely slow.
+ * @param {any} dialect
+ * @param {(slot: ParamSlot) => string} param
+ * @param {string} valueSql
+ * @param {any} pred
+ * @returns {string}
+ */
+function stropForm(dialect, param, valueSql, pred) {
+  const pattern = pred.operand.lit;
+  const bind = () => param({ literal: pattern });
+  if (pred.kind === 'ends')
+    return dialect.strEndsWith(valueSql, bind(), bind(), bind());
+  if (pred.kind === 'contains')
+    return dialect.strContains(valueSql, bind());
+  const upper = codePointPrefixSuccessor(pattern);
+  return upper === null
+    ? dialect.strStartsWithExact(valueSql, bind(), bind())
+    : dialect.strStartsWith(valueSql, bind(), param({ literal: upper }));
+}
+
+/**
+ * The name a dialect uses for one slot's parameter reference.
+ * @param {ParamSlot} slot
+ * @returns {string}
+ */
+function slotName(slot) {
+  if ('external' in slot) return slot.external;
+  if ('derived' in slot) return slot.derived.external;
+  return 'value';
+}
+
+/** Where each edge sits in a `[west, south, east, north]` box. */
+const BOX_AT = { w: 0, s: 1, e: 2, n: 3 };
+
+/**
+ * Bind one edge of the probe box: a plan-time literal box binds its own
+ * number, an external one binds a derived slot the binder computes from
+ * the value at call time.
+ *
+ * A positional dialect numbers parameters by the statement's TEXT
+ * order, so this is called in the order the placeholders appear and
+ * never in the order the box carries its edges.
+ * @param {any} probe
+ * @param {(slot: ParamSlot) => string} param
+ * @param {'w' | 's' | 'e' | 'n'} axis
+ * @returns {string}
+ */
+function probeEdge(probe, param, axis) {
+  return 'box' in probe
+    ? param({ literal: probe.box[BOX_AT[axis]] })
+    : param({ derived: { kind: 'bboxAxis', external: probe.ext, axis } });
+}
+
 /**
  * Emit one plan as SQL plus its ordered parameter slots.
  * @param {import('./algebra.js').Plan} plan
@@ -34,7 +108,7 @@ export function emitPlan(plan, dialect, physical) {
   const slots = [];
   const param = (slot) => {
     slots.push(slot);
-    return dialect.parameterRef(slots.length, 'external' in slot ? slot.external : 'value');
+    return dialect.parameterRef(slots.length, slotName(slot));
   };
 
   /** SQL for a ref's VALUE: the generated column when one exists. */
@@ -132,15 +206,51 @@ export function emitPlan(plan, dialect, physical) {
         return `${pred.name}(${dialect.jsonText(docColumn)})`;
       case 'strop': {
         const jt = typeOf(pred.ref);
-        const value = valueOf(pred.ref);
-        const bind = () => param({ literal: /** @type {any} */ (pred.operand).lit });
-        const form = pred.kind === 'starts'
-          ? dialect.strStartsWith(value, bind(), bind())
-          : pred.kind === 'ends'
-            ? dialect.strEndsWith(value, bind(), bind(), bind())
-            : dialect.strContains(value, bind());
+        const form = stropForm(dialect, param, valueOf(pred.ref), pred);
         return `(${jt} IS NOT NULL AND ${jt} = ${sl('text')} AND ${form})`;
       }
+      case 'bboxOverlap': {
+        // Two boxes meet when neither is wholly past the other, and
+        // TOUCHING counts (`bboxIntersects`), so these are `<=`/`>=`:
+        // a strict comparison would disagree with the engine on every
+        // shared edge. Emitted in the index's covered column order —
+        // (w, e, s, n) — so the leading longitude bound sits in front.
+        // The leading `IS NOT NULL` keeps the form TOTAL — a row with no
+        // box answers FALSE, not NULL, so a negation over an exact box
+        // test still composes classically — and it is also what makes
+        // the term SEEKABLE: it bounds the leading column from below,
+        // and a one-sided range alone loses to a table scan in SQLite's
+        // cost model, which prices a virtual generated column as a free
+        // column read when it is a host function call per row.
+        const c = pred.columns;
+        const edge = (axis) => probeEdge(pred.probe, param, axis);
+        return `(${q(c.w)} IS NOT NULL AND ${q(c.w)} <= ${edge('e')}`
+          + ` AND ${q(c.e)} >= ${edge('w')}`
+          + ` AND ${q(c.s)} <= ${edge('n')} AND ${q(c.n)} >= ${edge('s')})`;
+      }
+      case 'cellIn': {
+        // The cells are whole values of the column, so this is an
+        // equality set — and `IN` is the spelling that keeps it one:
+        // nine OR-ed ranges defeat SQLite's multi-index OR optimization
+        // (it gives up past a handful of terms) and fall back to a scan,
+        // which for a virtual generated column is a host function call
+        // per row.
+        const column = q(pred.column);
+        const list = pred.cells.map((cell) => param({ literal: cell })).join(', ');
+        return `(${column} IS NOT NULL AND ${column} IN (${list}))`;
+      }
+      case 'cellPrefix': {
+        // A cell SHORTER than the column's own: the half-open range an
+        // index seeks. Every cell is base-32, so the code-point
+        // successor always exists.
+        const column = q(pred.column);
+        const upper = codePointPrefixSuccessor(pred.prefix);
+        if (upper === null)
+          throw new Error('emit: a geohash cell has no code-point successor');
+        const range = dialect.strStartsWith(column, param({ literal: pred.prefix }),
+          param({ literal: upper }));
+        return `(${column} IS NOT NULL AND ${range})`;
+      }
       default:
         throw new Error(`emit: unknown predicate node '${/** @type {any} */ (pred).p}'`);
     }
@@ -209,12 +319,7 @@ export function createEntityPredicateEmitters(dialect, param) {
         : `(${jt} IS NOT NULL AND ${jt} NOT IN (${list}))`;
     }
     if (pred.p === 'strop') {
-      const bind = () => param({ literal: pred.operand.lit });
-      const form = pred.kind === 'starts'
-        ? dialect.strStartsWith(value, bind(), bind())
-        : pred.kind === 'ends'
-          ? dialect.strEndsWith(value, bind(), bind(), bind())
-          : dialect.strContains(value, bind());
+      const form = stropForm(dialect, param, value, pred);
       return `(${jt} IS NOT NULL AND ${jt} = ${sl('text')} AND ${form})`;
     }
     const lit = pred.operand.lit;
@@ -243,12 +348,7 @@ export function createEntityPredicateEmitters(dialect, param) {
         : `(${column} IS NOT NULL AND ${column} <> ${param({ literal: wanted })})`;
     }
     if (pred.p === 'strop') {
-      const bind = () => param({ literal: pred.operand.lit });
-      const form = pred.kind === 'starts'
-        ? dialect.strStartsWith(column, bind(), bind())
-        : pred.kind === 'ends'
-          ? dialect.strEndsWith(column, bind(), bind(), bind())
-          : dialect.strContains(column, bind());
+      const form = stropForm(dialect, param, column, pred);
       return `(${column} IS NOT NULL AND ${form})`;
     }
     const symbol = { eq: '=', ne: '<>', lt: '<', le: '<=', gt: '>', ge: '>=' }[pred.op];
@@ -330,7 +430,7 @@ export function emitEntityPlan(plan, dialect, physicalOf) {
   const slots = [];
   const param = (slot) => {
     slots.push(slot);
-    return dialect.parameterRef(slots.length, 'external' in slot ? slot.external : 'value');
+    return dialect.parameterRef(slots.length, slotName(slot));
   };
 
   const aliases = new Map(plan.bindings.map((binding, i) => [

package/src/errors.js

@@ -22,7 +22,7 @@ export const DB_CODES = Object.freeze({
   JD0001: 'the SQLite library is below the supported floor',
   JD0002: 'the declared model disagrees with the existing database',
   JD0003: 'the driver binding is unavailable on this runtime',
-  JD0004: 'an index path is not a singular member selection',
+  JD0004: 'a declared index cannot be mapped to a column',
   JD0005: 'the model document is invalid',
   JD0010: 'strict mode refused a residual',
   JD0011: 'the profile refused the document',
@@ -66,9 +66,11 @@ export const DB_CODES = Object.freeze({
  *  - `JD0003` — the runtime builtin behind a driver could not be
  *    loaded here (Node cannot resolve `bun:`; Bun ships no
  *    `node:sqlite`), or an injected handle is missing
- *  - `JD0004` — an index path does not select exactly one member
- *    (wildcards, slices, filters and descendants are not indexable);
- *    the reason names the expression
+ *  - `JD0004` — a declared index cannot be mapped to a column: its
+ *    path does not select exactly one member (wildcards, slices,
+ *    filters and descendants are not indexable), or its `derive`
+ *    declaration is not one the storage vocabulary carries; the reason
+ *    names the expression or the member and `docPath` points at it
  *  - `JD0005` — the model document is invalid; `docPath` points at
  *    the offending member
  *  - `JD0010` — `strict: true` and part of the query would have run

package/src/index.js

@@ -29,6 +29,11 @@ export { selectPlan, conjoin, assertNoSqlText, PLAN_VERSION } from './algebra.js
 export { typeOfPath, isNumericType } from './types.js';
 export { compileSetResidual, compileRowResidual, sequenceResult } from './residual.js';
 export { deterministicFragment, registerFragment } from './udf.js';
+export {
+  DERIVE_KINDS, BBOX_COMPONENTS, BBOX_INDEX_ORDER, PRECISION_MIN, PRECISION_MAX,
+  deriveGeohash, deriveBboxEdge, derivedValue, memberAt, storedMemberForm,
+  registerDeriveFunctions,
+} from './derive.js';
 export {
   createQueryEngine, createQueryState, createEntityQueryEngine,
   createLoadEngine, INCLUDE_DEPTH_DEFAULT,

package/src/jobs.js

@@ -26,7 +26,10 @@
  *  - **Shutdown is bounded.** Handlers receive an `AbortSignal` and
  *    `stop()` takes a deadline, so a handler that never settles cannot
  *    hold `stop()` — and therefore `store.close()`, and therefore the
- *    database file — open forever.
+ *    database file — open forever. A loop the deadline could not drain
+ *    is CANCELLED, not merely left behind: when its handler finally
+ *    settles it exits without another claim, store write or poll
+ *    timer, and its abandoned job recovers by lease expiry (§5).
  */
 
 import { chain } from './driver.js';
@@ -370,6 +373,17 @@ export function createJobEngine(options) {
 
     /** Aborted when `stop()` is called: the handler's cue to wind up. */
     let shutdown = new AbortController();
+    /**
+     * The per-`start()` loop session. When a `stop()` grace deadline
+     * expires the session is cancelled: a loop that could not be
+     * drained must abandon its job — no completion or failure write,
+     * no further claim, no re-armed poll timer — because the store it
+     * would touch is the one the caller is about to close. The
+     * abandoned lease expires and the next claim re-runs the job (§5).
+     * A later `start()` opens a NEW session, so a cancelled loop can
+     * never be revived.
+     */
+    let session = { cancelled: false };
     /** In-flight handler count, so `stop()` can report what it left. */
     let inFlight = 0;
 
@@ -389,7 +403,8 @@ export function createJobEngine(options) {
       }
     };
 
-    const runOne = async (job) => {
+    /** @param {{ cancelled: boolean }} loopSession */
+    const runOne = async (job, loopSession) => {
       stats.claims += 1;
       inFlight += 1;
       try {
@@ -399,9 +414,13 @@ export function createJobEngine(options) {
             { job, checkpointsFor, signal: shutdown.signal });
         }
         catch (error) {
+          // past cancellation the store is closing: leave the leased
+          // row to expiry-based recovery (§5) instead of racing it
+          if (loopSession.cancelled) return;
           await recordFailure(job, error);
           return;
         }
+        if (loopSession.cancelled) return;
         try {
           // a §7 handler may have completed transactionally already; the
           // guarded update makes this a no-op then
@@ -420,8 +439,9 @@ export function createJobEngine(options) {
       }
     };
 
-    const loop = async () => {
-      while (running) {
+    /** @param {{ cancelled: boolean }} loopSession */
+    const loop = async (loopSession) => {
+      while (running && !loopSession.cancelled) {
         let job;
         try {
           job = await Promise.resolve(claim({
@@ -430,13 +450,13 @@ export function createJobEngine(options) {
         catch {
           job = undefined; // a transient storage failure: back off to the poll
         }
-        if (!running) return;
+        if (!running || loopSession.cancelled) return;
         if (job === undefined) {
           await sleep();
           continue;
         }
         try {
-          await runOne(job);
+          await runOne(job, loopSession);
         }
         catch {
           // `runOne` normalizes every handler outcome, so reaching here
@@ -453,7 +473,12 @@ export function createJobEngine(options) {
         if (running) throw new TypeError('the worker is already started');
         running = true;
         shutdown = new AbortController();
-        loops = Array.from({ length: concurrency }, () => loop());
+        session = { cancelled: false };
+        loops = Array.from({ length: concurrency }, () => loop(session));
+        // a restart re-registers what stop() removed: the
+        // wake-on-enqueue hook and the stopAll membership
+        wakers.add(onWake);
+        workers.add(worker);
         return worker;
       },
       /**
@@ -461,6 +486,9 @@ export function createJobEngine(options) {
        * the loops — but only up to `graceMs`. A handler that ignores its
        * signal cannot hold the process open; the resolved record says so
        * instead, and the lease expiry (§5) lets another worker re-claim.
+       * A loop the grace period could not drain is cancelled outright:
+       * when its handler finally settles it exits without another
+       * claim, store write or poll timer.
        * @param {{ graceMs?: number }} [stopOptions]
        * @returns {Promise<{ drained: boolean, inFlight: number }>}
        */
@@ -478,6 +506,7 @@ export function createJobEngine(options) {
         ]);
         clearTimeout(timer);
         if (drained) loops = [];
+        else session.cancelled = true; // cancel what could not be drained
         wakers.delete(onWake);
         workers.delete(worker);
         return { drained: drained === true, inFlight };