@jarenjs/db 0.49.2 → 0.56.0

package/src/driver.js

@@ -32,7 +32,7 @@
 
 import { isThenable, chain, toPromise } from '@jarenjs/core/function';
 
-import { DbCompileError } from './errors.js';
+import { DbCompileError, DbRuntimeError } from './errors.js';
 
 /** The minimum SQLite the store accepts, asserted at open. */
 export const SQLITE_FLOOR = '3.45.0';
@@ -96,18 +96,43 @@ 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) {
+  const before = guard ?? (() => {});
   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 /** @type {Function} */ (statement.iterate)(params); }
+      : (params = []) => { before(); return chain(statement.all(params),
+        (rows) => 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;
+}
+
 /**
  * Finish a raw binding into the connection contract: probe the library
  * once, assert the version floor, freeze the capability table, and
@@ -223,6 +248,16 @@ 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;
+  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 = () => {
@@ -315,9 +350,9 @@ 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) => { requireOpen(); return chain(raw.prepare(sql), (s) => wrapStatement(s, requireOpen)); },
     /** A nested savepoint inside this transaction.
      * @param {(scope: any) => any} fn */
     transaction: (fn) => savepointAround(fn),
@@ -338,9 +373,14 @@ function finishConnection(raw, dialect, synchronous, capabilities, queueTimeout)
     // 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),
+    exec: (sql) => { requireOpen(); return raw.exec(sql); },
     /** @param {string} sql */
-    prepare: (sql) => chain(raw.prepare(sql), wrapStatement),
+    prepare: (sql) => { requireOpen(); return chain(raw.prepare(sql), (s) => wrapStatement(s, requireOpen)); },
+    /** 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.
@@ -363,6 +403,7 @@ function finishConnection(raw, dialect, synchronous, capabilities, queueTimeout)
      * @param {(scope: any) => any} fn
      */
     transaction(fn) {
+      requireOpen();
       if (onStack) return savepointAround(fn);
       return whenFree(() => {
         owned = true;
@@ -383,15 +424,21 @@ function finishConnection(raw, dialect, synchronous, capabilities, queueTimeout)
           (error) => { release(); throw error; });
       }, 'a transaction');
     },
-    close: () => raw.close(),
+    // 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 undefined;
+      closed = true;
+      return 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,
   });
 }

package/src/drivers/wasm.js

@@ -166,6 +166,7 @@ export function wasmDriver(handle) {
       openConnection(raw, {
         dialect: sqliteDialect,
         synchronous: handle.synchronous === true,
+        queueTimeout: options?.queueTimeout,
         declared: {
           sessions: handle.declares?.sessions === true,
           userFunctions: handle.declares?.userFunctions === true,

package/src/emit-model.js

@@ -32,6 +32,11 @@
  */
 
 import { normalizeEntities } from './model.js';
+import { DbCompileError } from './errors.js';
+
+/** The fixed declarations every artifact carries; an entity of one of
+ * these names would be emitted twice. */
+const FIXED_DECLARATIONS = new Set(['DateTime', 'Entities', 'EntityInputs', 'EntityMetaMap']);
 
 const primitive = (name) => ({ kind: 'primitive', primitive: name });
 const ref = (name) => ({ kind: 'ref', ref: name });
@@ -75,6 +80,15 @@ export function entityEmitModel(model, options) {
     throw new TypeError("entityEmitModel needs { compile: compileEmitModel } injected");
   const entities = normalizeEntities(model);
   const entityNames = [...entities.keys()];
+  for (const name of entityNames) {
+    if (FIXED_DECLARATIONS.has(name)
+      || (name.endsWith('Input') && entityNames.includes(name.slice(0, -'Input'.length)))) {
+      throw new DbCompileError('JD0005',
+        `entity '${name}' collides with a fixed declaration of the emitted artifact `
+        + `(${[...FIXED_DECLARATIONS].join(', ')}, and <Entity>Input for every entity)`,
+        `/entities/${name}`);
+    }
+  }
 
   // every entity name, input name and the brand are reserved up front
   // so nested-shape hints can never steal them

package/src/emit.js

@@ -18,6 +18,14 @@
 
 import { codePointPrefixSuccessor } from '@jarenjs/core/string';
 
+/**
+ * A promoted path the dialect's JSON path grammar cannot spell (a
+ * member name holding a double quote or a control character). The
+ * planner promotes by SCHEMA, not by grammar, so the query engine
+ * catches this and runs the document in the set residual instead.
+ */
+export class UnrepresentablePath extends Error {}
+
 /**
  * @typedef {{ external: string } | { literal: unknown } |
  *   { derived: { kind: 'bboxAxis', external: string,
@@ -117,9 +125,8 @@ export function emitPlan(plan, dialect, physical) {
   const pathTextOf = (ref) => {
     const text = dialect.jsonPathText(ref.segments);
     if (text === null) {
-      // the planner never promotes an unrepresentable path; reaching
-      // this is an internal inconsistency, not a user error
-      throw new Error('emit: a promoted path is not representable in the dialect JSON path grammar');
+      throw new UnrepresentablePath('a member name the dialect\'s JSON path grammar cannot '
+        + 'carry (a double quote or a control character) runs in the residual');
     }
     return text;
   };

package/src/entity.js

@@ -19,8 +19,8 @@ import {
   getEpochOfDateTimeRFC3339, getEpochOfDateOnlyRFC3339,
 } from '@jarenjs/core/dates/rfc3339';
 
-import { DbRuntimeError } from './errors.js';
-import { chain } from './driver.js';
+import { DbRuntimeError, isDuplicateKeyError } from './errors.js';
+import { chain, attempt } from './driver.js';
 
 /**
  * The write/read machinery for one entity, prepared once.
@@ -132,6 +132,28 @@ export function entityCore(connection, entity, entityMapping, validate) {
     return doc;
   };
 
+  /** The document as a read will answer it. For a column-mapped scalar,
+   * JSON `null` and absence both store as SQL NULL and read back ABSENT
+   * (§9.3) — so a value a write RETURNS drops it too, and the promise
+   * this file opens with holds: the value the application sees IS the
+   * value stored. A property that needs present-`null` declares
+   * `column: "json"` and stays in the document, where it survives; an
+   * epoch column keeps its string in the document for the same reason. */
+  const asStored = (doc) => {
+    let out = doc;
+    const drop = (name) => {
+      if (!(name in out) || (out[name] !== null && out[name] !== undefined)) return;
+      if (out === doc) out = { ...doc };
+      delete out[name];
+    };
+    for (const column of scalarColumns) {
+      if (column.epoch) continue; // the string is in the document, null and all
+      drop(column.name);
+    }
+    for (const fk of fkColumns) drop(fk);
+    return out;
+  };
+
   // defaults, compiled once
   const defaulters = [];
   const updateStamps = [];
@@ -139,9 +161,13 @@ export function entityCore(connection, entity, entityMapping, validate) {
     const declared = property.default;
     if (declared === undefined || property.relation !== undefined) continue;
     if (declared === 'now' || declared === 'updated') {
-      defaulters.push({ name: property.name, fill: () => new Date().toISOString() });
-      if (declared === 'updated')
-        updateStamps.push({ name: property.name, fill: () => new Date().toISOString() });
+      // a `date` property takes the calendar date; a date-time stamp on
+      // it was invalid under its own format and refused by an epoch column
+      const stamp = property.format === 'date'
+        ? () => new Date().toISOString().slice(0, 10)
+        : () => new Date().toISOString();
+      defaulters.push({ name: property.name, fill: stamp });
+      if (declared === 'updated') updateStamps.push({ name: property.name, fill: stamp });
       continue;
     }
     if (declared === 'uuid') {
@@ -162,12 +188,42 @@ export function entityCore(connection, entity, entityMapping, validate) {
     for (const { name, fill } of defaulters) {
       if (out[name] === undefined) out[name] = fill(out);
     }
+    // the version token starts at 0 on insert: a row written with SQL
+    // NULL never matched the tracker's `WHERE ver = 0` and could not be
+    // saved through the unit of work at all
+    if (!updating && entity.version !== null && entity.version !== undefined
+      && out[entity.version] === undefined) {
+      out[entity.version] = 0;
+    }
     if (updating) {
       for (const { name, fill } of updateStamps) out[name] = fill(out);
     }
     return out;
   };
 
+  /**
+   * Refuse relation members a write cannot store: every relation member
+   * is a projection (§10.1), except a many-to-many MEMBERSHIP array,
+   * which `create()`/`add()` attach through the join table.
+   * @param {any} doc
+   * @param {string} verb
+   * @param {boolean} memberships - whether membership arrays are taken
+   */
+  const refuseProjections = (doc, verb, memberships) => {
+    for (const name of relationNames) {
+      const value = doc?.[name];
+      if (value === undefined || (Array.isArray(value) && value.length === 0)) continue;
+      const relation = entity.properties.get(name).relation;
+      if (memberships && relation.kind === 'manyToMany' && Array.isArray(value)) continue;
+      throw new DbRuntimeError('JD2003',
+        `'${name}' is a relation member — ${verb}() stores no projections; `
+        + (relation.kind === 'manyToMany'
+          ? 'membership changes through the unit of work (put + saveChanges)'
+          : 'write the related entities themselves'),
+        { docPath, collection: entity.name });
+    }
+  };
+
   const checkValid = (doc) => {
     if (validate === null) return;
     const outcome = validate(doc);
@@ -233,7 +289,13 @@ export function entityCore(connection, entity, entityMapping, validate) {
   };
 
   const wrapWrite = (error, key) => {
-    if (/** @type {any} */ (error)?.code === 'JD2003') return error;
+    const code = /** @type {any} */ (error)?.code;
+    if (typeof code === 'string' && code.startsWith('JD')) return error;
+    if (keys.length === 1 && isDuplicateKeyError(error, table, keys[0])) {
+      return new DbRuntimeError('JD2001',
+        `a '${entity.name}' already exists under key ${JSON.stringify(key)}`,
+        { docPath, collection: entity.name, key, cause: error });
+    }
     return new DbRuntimeError('JD2005',
       `the database rejected the operation: ${/** @type {any} */ (error)?.message ?? String(error)}`,
       key === undefined
@@ -269,7 +331,7 @@ export function entityCore(connection, entity, entityMapping, validate) {
     complete: (doc, { updating }) => {
       const completed = applyDefaults(doc, { updating });
       checkValid(completed);
-      return completed;
+      return asStored(completed);
     },
     validateOnly: (doc) => checkValid(doc),
     stampUpdated: (doc) => {
@@ -280,15 +342,7 @@ export function entityCore(connection, entity, entityMapping, validate) {
     },
     normalizeKey: (key) => normalizeKeyArg(key),
     create(doc) {
-      for (const name of relationNames) {
-        const value = doc?.[name];
-        if (value !== undefined && (!Array.isArray(value) || value.length > 0)) {
-          throw new DbRuntimeError('JD2003',
-            `'${name}' is a relation member — create() stores no `
-            + 'projections; use the unit of work for membership',
-            { docPath, collection: entity.name });
-        }
-      }
+      refuseProjections(doc, 'create', true);
       const completed = applyDefaults(doc, { updating: false });
       checkValid(completed);
       const { values, rest } = split(completed);
@@ -296,17 +350,11 @@ export function entityCore(connection, entity, entityMapping, validate) {
       const sql = insertSqlFor(names);
       return chain(prepared(`insert:${names.join(',')}`, sql), (statement) => {
         const params = [...values.map((value) => value.value), JSON.stringify(rest)];
-        let out;
-        try {
-          out = autoKey !== null && !names.includes(autoKey)
-            ? statement.get(params)
-            : (statement.run(params), null);
-        }
-        catch (error) {
-          throw wrapWrite(error, completed[keys[0]]);
-        }
-        if (out !== null) return { ...completed, [autoKey]: out.key };
-        return completed;
+        const returning = autoKey !== null && !names.includes(autoKey);
+        return chain(
+          attempt(() => (returning ? statement.get(params) : statement.run(params)),
+            (error) => wrapWrite(error, completed[keys[0]])),
+          (out) => asStored(returning ? { ...completed, [autoKey]: out.key } : completed));
       });
     },
     get(key) {
@@ -317,12 +365,22 @@ export function entityCore(connection, entity, entityMapping, validate) {
     },
     update(key, changes) {
       const parts = normalizeKeyArg(key);
+      refuseProjections(changes, 'update', false);
       return chain(this.get(key), (current) => {
         if (current === undefined) {
           throw new DbRuntimeError('JD2006',
             `no '${entity.name}' to update under that key`,
             { docPath, collection: entity.name });
         }
+        for (const keyName of keys) {
+          // the key identifies the row the UPDATE addresses; rewriting it
+          // through `changes` moved rows out from under the tracker
+          if (changes?.[keyName] !== undefined && changes[keyName] !== current[keyName]) {
+            throw new DbRuntimeError('JD2003',
+              `'${keyName}' is the primary key — update() cannot rewrite it; delete and create`,
+              { docPath, collection: entity.name, key: parts[0] });
+          }
+        }
         const next = applyDefaults({ ...current, ...changes }, { updating: true });
         // an explicit update is last-write-wins by contract (§11.2),
         // but it still moves a declared version token so optimistic
@@ -337,31 +395,18 @@ export function entityCore(connection, entity, entityMapping, validate) {
         ].join(', ');
         const sql = `UPDATE ${q(table)} SET ${assignments} `
           + `WHERE ${keyWhere(values.length + 1)}`;
-        return chain(prepared(`update:${values.length}`, sql), (statement) => {
-          try {
-            statement.run([...values.map((value) => value.value),
-              JSON.stringify(rest), ...parts]);
-          }
-          catch (error) {
-            throw wrapWrite(error, parts[0]);
-          }
-          return next;
-        });
+        return chain(prepared(`update:${values.length}`, sql), (statement) =>
+          chain(attempt(() => statement.run([...values.map((value) => value.value),
+            JSON.stringify(rest), ...parts]), (error) => wrapWrite(error, parts[0])),
+          () => asStored(next)));
       });
     },
     delete(key) {
       const parts = normalizeKeyArg(key);
       const sql = `DELETE FROM ${q(table)} WHERE ${keyWhere(0)}`;
-      return chain(prepared('delete', sql), (statement) => {
-        let out;
-        try {
-          out = statement.run(parts);
-        }
-        catch (error) {
-          throw wrapWrite(error, parts[0]);
-        }
-        return chain(out, (result) => Number(result?.changes ?? 0) > 0);
-      });
+      return chain(prepared('delete', sql), (statement) =>
+        chain(attempt(() => statement.run(parts), (error) => wrapWrite(error, parts[0])),
+          (result) => Number(result?.changes ?? 0) > 0));
     },
   };
 }

package/src/errors.js

@@ -18,6 +18,23 @@ import { CodedError } from '@jarenjs/core/errors';
  * this package can raise, proven in sync with MODEL-FORMAT.md §7's
  * normative table by a test.
  */
+/**
+ * Whether a database error is the unique-key collision of `table.column`
+ * — the one failure every insert path reports as `JD2001` rather than
+ * the generic `JD2005`. One detector for the collection cores, the
+ * entity cores and the unit of work, so no path wraps it differently.
+ * @param {any} error
+ * @param {string} table
+ * @param {string} column
+ * @returns {boolean}
+ */
+export function isDuplicateKeyError(error, table, column) {
+  if (error?.errcode === 1555) return true;
+  return typeof error?.message === 'string'
+    && error.message.includes('UNIQUE constraint failed')
+    && error.message.includes(`${table}.${column}`);
+}
+
 export const DB_CODES = Object.freeze({
   JD0001: 'the SQLite library is below the supported floor',
   JD0002: 'the declared model disagrees with the existing database',
@@ -30,6 +47,7 @@ export const DB_CODES = Object.freeze({
   JD0030: 'an unknown x-entity member was declared',
   JD0031: 'relation declarations contradict each other',
   JD0032: 'the include specification is invalid',
+  JD0033: 'an entity query names no entity array',
   JD0040: 'the save spans a relation cycle',
   JD0050: 'live queries require change capture',
   JD0051: 'the demanded live mode is unavailable',
@@ -52,6 +70,7 @@ export const DB_CODES = Object.freeze({
   JD2060: 'the maintained live state exceeded its bound',
   JD2061: 'another context owns the database',
   JD2062: 'the store closed with job handlers still in flight',
+  JD2063: 'the store is closed',
 });
 
 /**
@@ -83,6 +102,9 @@ export const DB_CODES = Object.freeze({
  *    silently ignored mapping directive is a data-loss bug waiting
  *  - `JD0031` — two relation declarations whose inverses contradict
  *    (different `via`, impossible `many` pairings)
+ *  - `JD0033` — a document handed to `store.execute()` over entities
+ *    ranges over no declared entity array (`$.<Entity>[*]`); the root
+ *    is the map of entity arrays, so there are no rows to answer
  *  - `JD0032` — a graph-load include specification is invalid: an
  *    unknown relation, a cycle, an untranslatable filter, or the
  *    depth bound exceeded (the bound is printed, never silent)
@@ -152,6 +174,9 @@ export class DbCompileError extends CodedError {
  *  - `JD2061` — a second context tried to open a database whose
  *    storage grants one context exclusive access (the owner topology
  *    of LIVE-FORMAT §11); connect to the owner instead
+ *  - `JD2063` — a call after `close()`: every entry point of a closed
+ *    store refuses by name rather than leaking the driver's own error,
+ *    and a second `close()` is a no-op on every driver
  */
 export class DbRuntimeError extends CodedError {
   /**

package/src/index.js

@@ -21,7 +21,7 @@ export {
 } from './ddl.js';
 export {
   planQuery, assertDecidedKind, entityShape, entityPathRef,
-  planEntityPredicate, planEntityQuery,
+  planEntityPredicate, planEntityQuery, collectEntityRoots, entityRoot,
 } from './plan.js';
 export { emitPlan, createEntityPredicateEmitters, emitEntityPlan } from './emit.js';
 export { mergeEntityRow, parseGraphRow } from './graph.js';
@@ -45,7 +45,7 @@ export {
   applyMandatoryPredicate, applyRowBound,
 } from './profile.js';
 export { translatePatch } from './patch-sql.js';
-export { normalizeEntities, explainMapping } from './model.js';
+export { normalizeEntities, explainMapping, relationTables } from './model.js';
 export { planEntity, planJoinTable } from './ddl.js';
 export { entityCore } from './entity.js';
 export { entityEmitModel } from './emit-model.js';

package/src/jobs.js

@@ -32,7 +32,8 @@
  *    timer, and its abandoned job recovers by lease expiry (§5).
  */
 
-import { chain } from './driver.js';
+import { chain, attempt } from './driver.js';
+import { DbCompileError, DbRuntimeError } from './errors.js';
 
 export const JOBS_TABLE = '_jaren_jobs';
 export const JOB_CHECKPOINTS_TABLE = '_jaren_job_checkpoints';
@@ -147,12 +148,25 @@ export function createJobEngine(options) {
   const random = options.random ?? Math.random;
   const defaults = { ...JOB_DEFAULTS, ...options.defaults };
 
+  /** Every queue statement failure rides the store's own wrap (§9):
+   * a read-only file, a locked database, a constraint — never the
+   * driver's raw error. */
+  const wrapJobs = (error) => (typeof error?.code === 'string' && error.code.startsWith('JD')
+    ? error
+    : new DbRuntimeError('JD2005',
+      `the database rejected the operation: ${error?.message ?? String(error)}`,
+      { docPath: '/jobs', collection: JOBS_TABLE, cause: error }));
   /** @type {Map<string, any>} */
   const statements = new Map();
   const prepared = (key, sql) => {
     let statement = statements.get(key);
     if (statement === undefined) {
-      statement = connection.prepare(sql);
+      const raw = connection.prepare(sql);
+      statement = {
+        run: (params) => attempt(() => raw.run(params), wrapJobs),
+        get: (params) => attempt(() => raw.get(params), wrapJobs),
+        all: (params) => attempt(() => raw.all(params), wrapJobs),
+      };
       statements.set(key, statement);
     }
     return statement;
@@ -164,13 +178,27 @@ export function createJobEngine(options) {
     for (const wake of [...wakers]) wake();
   };
 
-  const ready = connection.exec(CREATE_JOBS);
+  // the tables are created here, or refused here: a read-only store
+  // leaked the driver's "attempt to write a readonly database"
+  const ready = attempt(() => connection.exec(CREATE_JOBS), (error) => new DbCompileError('JD0002',
+    `the job tables could not be created (${error?.message ?? String(error)}) — `
+    + 'a read-only store creates nothing; open it read-write once, or without jobs',
+    '/jobs', error));
 
   const enqueue = (kind, payload, enqueueOptions) => {
     if (typeof kind !== 'string' || kind === '') {
       throw new TypeError('enqueue: "kind" must be a non-empty string');
     }
     const id = enqueueOptions?.id ?? crypto.randomUUID();
+    // a `runAt` that is not a number stored as NaN and left the job
+    // pending forever; a Date could not even be bound
+    if (enqueueOptions?.runAt !== undefined && !Number.isFinite(enqueueOptions.runAt)) {
+      throw new TypeError('enqueue: "runAt" is an epoch in milliseconds (a finite number)');
+    }
+    if (enqueueOptions?.maxAttempts !== undefined
+      && !(Number.isInteger(enqueueOptions.maxAttempts) && enqueueOptions.maxAttempts >= 1)) {
+      throw new TypeError('enqueue: "maxAttempts" is a positive integer');
+    }
     const at = now();
     return chain(prepared('enqueue', `INSERT INTO "${JOBS_TABLE}"
       (id, kind, payload, state, run_at, max_attempts, created_at, updated_at)
@@ -341,8 +369,12 @@ export function createJobEngine(options) {
     const kinds = Object.keys(handlers);
     const owner = workerOptions.owner ?? crypto.randomUUID();
     const concurrency = workerOptions.concurrency ?? 1;
+    if (!(Number.isInteger(concurrency) && concurrency >= 1)) {
+      // `Array.from({ length: 0 })` started a worker that never claimed
+      throw new TypeError('createWorker: "concurrency" is a positive integer');
+    }
     const pollInterval = workerOptions.pollInterval ?? defaults.pollInterval;
-    const stats = { claims: 0, completions: 0, failures: 0, polls: 0, wakes: 0 };
+    const stats = { claims: 0, completions: 0, failures: 0, polls: 0, wakes: 0, claimErrors: 0 };
 
     let running = false;
     /** @type {Promise<void>[]} */
@@ -448,7 +480,10 @@ export function createJobEngine(options) {
             kinds, owner, leaseMs: workerOptions.leaseMs }));
         }
         catch {
-          job = undefined; // a transient storage failure: back off to the poll
+          // a storage failure backs off to the poll — COUNTED, so a
+          // worker on a read-only store is not silently idle forever
+          stats.claimErrors += 1;
+          job = undefined;
         }
         if (!running || loopSession.cancelled) return;
         if (job === undefined) {

package/src/live-time.js

@@ -77,7 +77,7 @@ export function normalizeEventTime(options, collection) {
   const declared = options?.eventTime;
   if (declared === undefined || declared === null) return null;
   const refuse = (reason) => {
-    throw new DbCompileError('JD0053', reason, { collection });
+    throw new DbCompileError('JD0053', reason, `/collections/${collection}`);
   };
   if (!isJsonObject(declared))
     refuse('live eventTime is an object with a path, a watermark and a retention');
@@ -178,6 +178,15 @@ export function classifyEventTime(inner, windowed, keyed, eventTime) {
     return rerun(`'${name}' — a named zone resolves through the injected provider, which `
       + 'maintenance would have to consult per boundary');
   }
+  // the kernel reads member NAMES (`at`, `value`); the document spells
+  // them as row selectors (`$.at`) — handed the document's spelling, the
+  // kernel read `row['$.at']` and every fold died on its first reading
+  const valueMember = spec.value === undefined ? null : singularSelector(spec.value);
+  if (spec.value !== undefined && valueMember === null) {
+    return rerun(`'${name}' — the spec reads a value selector this view cannot follow`);
+  }
+  const kernelSpec = { ...spec, at: eventTime.member,
+    ...(valueMember === null ? {} : { value: valueMember }) };
   const aggregate = spec.aggregate ?? 'mean';
   if (!MAINTAINED_AGGREGATES.includes(aggregate)) {
     return rerun(`'${name}' — '${aggregate}' names a row by its position in the series, `
@@ -215,7 +224,7 @@ export function classifyEventTime(inner, windowed, keyed, eventTime) {
     return {
       strategy: 'rolling',
       source: operand.source,
-      spec,
+      spec: kernelSpec,
       member: eventTime.member,
       width: span.width,
       eventTime,
@@ -236,7 +245,7 @@ export function classifyEventTime(inner, windowed, keyed, eventTime) {
   return {
     strategy: 'bucket',
     source: operand.source,
-    spec,
+    spec: kernelSpec,
     member: eventTime.member,
     ladder,
     fill,

package/src/live.js

@@ -79,12 +79,22 @@ function unwrapDocument(document) {
   return { inner: doc, whole, windowed, offset, limit, aggregate };
 }
 
+/** Whether a `$for` source is the whole collection: the bare `$[*]`, or
+ * its packed spelling `["$[*]"]` — one array item a `$for` unpacks back
+ * into the rows, which is how `@jarenjs/linq` binds every source so an
+ * array-valued row stays one item. Over a collection the two are the
+ * same rows (the planner reads through the packing the same way). */
+function isWholeCollection(source) {
+  return source === '$[*]'
+    || (Array.isArray(source) && source.length === 1 && source[0] === '$[*]');
+}
+
 /** The single for-binding name of a canonical flwor, or null. */
 function bindingNameOf(inner) {
   if (!isJsonObject(inner) || !isJsonObject(inner.$for)) return null;
   const names = Object.keys(inner.$for);
   if (names.length !== 1) return null;
-  return inner.$for[names[0]] === '$[*]' ? names[0] : null;
+  return isWholeCollection(inner.$for[names[0]]) ? names[0] : null;
 }
 
 /** The whole-documents read behind a flwor: same binding, same