@jarenjs/db 0.46.5 → 0.56.0

package/src/dialects/sqlite.js

@@ -33,7 +33,8 @@ function jsonPathText(segments) {
   let text = '$';
   for (const segment of segments) {
     if ('index' in segment) {
-      text += `[${segment.index}]`;
+      // SQLite counts from the end as `[#-1]`; a bare `[-1]` is a bad path
+      text += segment.index < 0 ? `[#${segment.index}]` : `[${segment.index}]`;
       continue;
     }
     // eslint-disable-next-line no-control-regex
@@ -82,6 +83,9 @@ export const sqliteDialect = createDialect({
     upsert: true,
     savepoints: true,
     alterTableFull: false,
+    // a GROUP BY / ORDER BY term may name a result alias, so a bucket
+    // ladder is written once rather than three times
+    groupByAlias: true,
   },
   tableSuffix: ' STRICT',
   // RFC 3339 text → epoch milliseconds, in SQL: the migration planner
@@ -152,6 +156,22 @@ export const sqliteDialect = createDialect({
     `(length(${patternA}) = 0 OR substr(${valueSql}, -length(${patternB})) = ${patternC})`,
   strContains: (valueSql, patternSql) => `instr(${valueSql}, ${patternSql}) > 0`,
   orderNulls: (nullsFirst) => (nullsFirst ? ' NULLS FIRST' : ' NULLS LAST'),
+  // the fixed bucket ladder, in integer arithmetic all the way down.
+  // `origin + floor((at - origin) / every) * every` is `at` less the
+  // NON-NEGATIVE remainder, and `((x % m) + m) % m` is how a language
+  // whose `%` truncates towards zero (C's, and SQLite's) spells one —
+  // which is the whole of why an instant before 1970 lands in its own
+  // bucket rather than the one after it. The column is declared
+  // INTEGER, so nothing here converts and nothing rounds.
+  timeBucket: (instantSql, originSql, everyA, everyB, everyC) =>
+    `(${instantSql} - (((${instantSql} - ${originSql}) % ${everyA} + ${everyB}) % ${everyC}))`,
+  // `rows` is COUNT(*) — the D5 count of SOURCE rows, which is not
+  // COUNT(value): a measured gap is a row that reported nothing, and
+  // the difference between "nobody reported" and "everybody reported a
+  // gap" is exactly what the count is for
+  groupAggregate: (fn, valueSql) => (valueSql === null
+    ? 'COUNT(*)'
+    : `${{ sum: 'SUM', avg: 'AVG', min: 'MIN', max: 'MAX' }[fn]}(${valueSql})`),
   rowIdentity: () => '"rowid"',
   // membership of the row identity in a bound list — the fetch of a
   // k-nearest plan's candidates. `IN` over the rowid is a primary-key

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;
   };
@@ -273,6 +280,17 @@ export function emitPlan(plan, dialect, physical) {
     }
   };
 
+  // The temporal bucket's ladder, written ONCE and named: the SELECT
+  // list carries it, and the grouping and the ordering name the alias.
+  // Writing it three times would triple its parameters, and a bucket
+  // start is exactly the kind of value the caller wants to read back.
+  const bucketSql = plan.bucket === null ? null
+    : dialect.timeBucket(valueOf(plan.bucket.ref),
+      param({ literal: plan.bucket.origin }),
+      param({ literal: plan.bucket.every }),
+      param({ literal: plan.bucket.every }),
+      param({ literal: plan.bucket.every }));
+
   const selection = plan.rank !== null
     // the k-nearest fetch: the row identity and the packed column
     // under the pushed WHERE, and nothing that orders or limits — the
@@ -280,15 +298,30 @@ export function emitPlan(plan, dialect, physical) {
     // the rank loses to fetching the column and ranking in the engine,
     // and none of them runs where no function can be registered)
     ? `${dialect.rowIdentity()} AS ${q('rid')}, ${q(plan.rank.column)} AS ${q('vec')}`
-    : plan.aggregate === null
-      ? `${dialect.jsonText(docColumn)} AS ${q('doc')}`
-      : plan.aggregate.fn === 'count'
-        ? `COUNT(*) AS ${q('value')}`
-        : `${plan.aggregate.fn.toUpperCase()}(${valueOf(plan.aggregate.ref)}) AS ${q('value')}`;
+    : plan.bucket !== null
+      ? [`${bucketSql} AS ${q(plan.bucket.as)}`,
+        ...plan.bucket.aggregates.map((entry) =>
+          `${dialect.groupAggregate(entry.fn,
+            entry.ref === null ? null : valueOf(entry.ref))} AS ${q(entry.as)}`)].join(', ')
+      : plan.aggregate === null
+        ? `${dialect.jsonText(docColumn)} AS ${q('doc')}`
+        : plan.aggregate.fn === 'count'
+          ? `COUNT(*) AS ${q('value')}`
+          : `${plan.aggregate.fn.toUpperCase()}(${valueOf(plan.aggregate.ref)}) AS ${q('value')}`;
 
   let sql = `SELECT ${selection} FROM ${q(physical.table)}`;
   if (plan.filter !== null) sql += ` WHERE ${emitPred(plan.filter)}`;
-  if (plan.aggregate === null && plan.rank === null) {
+  if (plan.bucket !== null) {
+    // `first-seen` is the engine's own group order (§6.5, first
+    // appearance), which over a collection is the group's earliest row
+    // identity — the same tiebreaker the ungrouped fetch appends
+    const alias = q(plan.bucket.as);
+    const order = plan.bucket.order === 'first-seen'
+      ? dialect.groupAggregate('min', dialect.rowIdentity())
+      : `${alias} ${plan.bucket.order === 'desc' ? 'DESC' : 'ASC'}`;
+    sql += ` GROUP BY ${alias} ORDER BY ${order}`;
+  }
+  if (plan.aggregate === null && plan.rank === null && plan.bucket === null) {
     const terms = (plan.order ?? []).map((term) => {
       // Jaren's default sorts an empty key least: NULLS FIRST when
       // ascending, NULLS LAST when descending — and mirrored for

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,10 +47,12 @@ 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',
   JD0052: 'the live-query bound was reached',
+  JD0053: 'the live event-time declaration is invalid',
   JD0020: "the migration's from-shape does not match the database",
   JD0021: 'the migration is missing a required data transform',
   JD0022: 'an applied migration disagrees with the history record',
@@ -51,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',
 });
 
 /**
@@ -82,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)
@@ -94,6 +117,8 @@ export const DB_CODES = Object.freeze({
  *    classifies as re-run; the reason names the forcing construct
  *  - `JD0052` — registering would exceed the store's `live.maxQueries`
  *    bound; the bound is printed, never silent
+ *  - `JD0053` — a live query's `eventTime` names a member it does not
+ *    admit, or a watermark/retention that is not a finite span
  *  - `JD0020` — a migration's `from` hash does not match the
  *    database's recorded shape; running it would corrupt
  *  - `JD0021` — a draft transform was not filled in, or a document no
@@ -149,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';