@jarenjs/db 0.49.2 → 0.56.0

package/src/tracker.js

@@ -8,8 +8,10 @@
  * snapshot against current with the suite's own diff engine and plans
  * the MINIMAL set of parameterised statements: scalar/epoch/foreign-
  * key column writes, `jsonb_set`/`jsonb_remove` chains for document
- * paths, join-table synchronisation for many-to-many members, and a
- * counted whole-row fallback for anything untranslatable.
+ * paths, join-table synchronisation for many-to-many members — by the
+ * key-set difference a `put` implies, or by an explicit `link`/`unlink`
+ * delta resolved against the join table at save time — and a counted
+ * whole-row fallback for anything untranslatable.
  *
  * Ordering never violates a foreign key mid-transaction: inserts run
  * parent-first, deletes child-first, updates in between, join rows
@@ -24,13 +26,37 @@ import { createJSONPatch } from '@jarenjs/json/patch';
 import { parseJSONPointer } from '@jarenjs/json/pointer';
 
 import { DbCompileError, DbRuntimeError } from './errors.js';
-import { chain } from './driver.js';
+import { chain, attempt } from './driver.js';
 import { translatePatch } from './patch-sql.js';
 
 /** Rows per batched INSERT: bounded by the portable parameter budget. */
 export const BATCH_PARAM_BUDGET = 900;
 export const BATCH_ROW_BOUND = 100;
 
+/**
+ * The target keys a many-to-many membership array names: a key, or a
+ * document carrying the target's key. One reading for the unit of work
+ * and for `create()`, so the two attach the same rows.
+ * @param {any} value - the member's value
+ * @param {string} targetKey - the target entity's key property
+ * @param {string} member
+ * @param {(reason: string) => Error} refuse
+ * @returns {(string | number)[]}
+ */
+export function membershipKeys(value, targetKey, member, refuse) {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) throw refuse(`'${member}' must be an array to synchronise its join table`);
+  return value.map((element) => {
+    const key = typeof element === 'string' || typeof element === 'number'
+      ? element
+      : element !== null && typeof element === 'object'
+        ? element[targetKey] : undefined;
+    if (typeof key !== 'string' && typeof key !== 'number')
+      throw refuse(`an element of '${member}' carries no usable '${targetKey}' key`);
+    return key;
+  });
+}
+
 const UNIT_SEPARATOR = '';
 
 /**
@@ -70,6 +96,11 @@ export function createTracker(context) {
   const records = new Map();
   /** @type {Map<string, any>} */
   const removals = new Map();
+  /** Pending membership deltas (§11.7), one per entity, own key and
+   * many-to-many member: the targets to link and the targets to unlink.
+   * @type {Map<string, { entity: string, member: string, ownKey: string | number,
+   *   links: Set<string | number>, unlinks: Set<string | number> }>} */
+  const memberships = new Map();
   let pendingSequence = 0;
 
   const keyOf = (entityName, parts) =>
@@ -89,6 +120,12 @@ export function createTracker(context) {
       collection: entityName,
     });
 
+  /** A membership write needs the entity's own key: an `auto` key is
+   * allocated by the save, so a pending insert has none to attach to. */
+  const needsOwnKey = (entityName, member, verb) => contractError(entityName,
+    `'${member}' membership needs the entity's own key at ${verb} time — `
+    + 'save the entity first, then attach');
+
   const register = (entityName, doc) => {
     deepFreeze(doc);
     const key = recordKeyFor(entityName, doc);
@@ -169,6 +206,60 @@ export function createTracker(context) {
     });
   };
 
+  /**
+   * The pending membership delta a `link`/`unlink` addresses (§11.7):
+   * the member must be a many-to-many relation of the entity; the own
+   * key is read from a key or a document (a pending insert whose key
+   * the save allocates has none to attach to); the target is a key or a
+   * document carrying the target's key — the reading a membership array
+   * gets, so the two attach the same rows.
+   */
+  const membershipOf = (entityName, own, member, target, verb) => {
+    const plan = coreFor(entityName).plan;
+    const relation = entities.get(entityName).properties.get(member)?.relation;
+    if (relation === undefined || relation.kind !== 'manyToMany') {
+      throw contractError(entityName, relation === undefined
+        ? `'${member}' is not a relation member of '${entityName}' — ${verb}() attaches a `
+          + 'many-to-many membership through its join table'
+        : `'${member}' is a ${relation.kind} relation — ${verb}() attaches many-to-many `
+          + "memberships only; write the related entity's foreign key instead");
+    }
+    let ownKey;
+    if (own !== null && typeof own === 'object' && !Array.isArray(own)) {
+      ownKey = own[plan.keys[0]];
+      if (typeof ownKey !== 'string' && typeof ownKey !== 'number')
+        throw needsOwnKey(entityName, member, `${verb}()`);
+    }
+    else {
+      ownKey = coreFor(entityName).normalizeKey(own)[0];
+    }
+    const targetKey = mapping.entities[relation.to].keys[0];
+    const [key] = membershipKeys([target], targetKey, member,
+      (reason) => contractError(entityName, reason));
+    const id = `${keyOf(entityName, [ownKey])}${UNIT_SEPARATOR}${member}`;
+    let pending = memberships.get(id);
+    if (pending === undefined) {
+      pending = { entity: entityName, member, ownKey, links: new Set(), unlinks: new Set() };
+      memberships.set(id, pending);
+    }
+    return { pending, key };
+  };
+
+  /** Attach one membership (local, synchronous); the last word on one
+   * target wins, so `unlink` after `link` means unlink. */
+  const link = (entityName, own, member, target) => {
+    const { pending, key } = membershipOf(entityName, own, member, target, 'link');
+    pending.unlinks.delete(key);
+    pending.links.add(key);
+  };
+
+  /** Detach one membership (local, synchronous). */
+  const unlink = (entityName, own, member, target) => {
+    const { pending, key } = membershipOf(entityName, own, member, target, 'unlink');
+    pending.links.delete(key);
+    pending.unlinks.add(key);
+  };
+
   const counts = () => {
     let pendingInserts = 0;
     for (const record of records.values()) {
@@ -178,6 +269,7 @@ export function createTracker(context) {
       tracked: records.size - pendingInserts,
       pendingInserts,
       pendingDeletes: removals.size,
+      pendingMemberships: memberships.size,
     };
   };
 
@@ -275,29 +367,31 @@ export function createTracker(context) {
     return { columnSets, docBuild, m2mMembers, fallback };
   };
 
+  /** The join-table endpoints a many-to-many member writes through. The
+   * endpoint columns come from the mapping, never from the join table's
+   * NAME: an entity name with an underscore, or a `through` name, does
+   * not split into its endpoints. */
+  const joinEndpoints = (entityName, member) => {
+    const relation = entities.get(entityName).properties.get(member).relation;
+    const join = mapping.joinTables[relation.joinTable];
+    const own = join.left.entity === entityName ? join.left : join.right;
+    const target = own === join.left ? join.right : join.left;
+    return {
+      entity: entityName,
+      member,
+      joinTable: relation.joinTable,
+      ownColumn: own.column,
+      targetColumn: target.column,
+      tableColumns: [join.left.column, join.right.column],
+      targetKey: mapping.entities[relation.to].keys[0],
+    };
+  };
+
   /** Compute a many-to-many member's join-row difference by key sets. */
   const joinDiff = (entityName, before, after, ownKey, member) => {
-    const entity = entities.get(entityName);
-    const relation = entity.properties.get(member).relation;
-    const targetKey = mapping.entities[relation.to].keys[0];
-    const extract = (value) => {
-      if (value === undefined || value === null) return [];
-      if (!Array.isArray(value)) {
-        throw contractError(entityName,
-          `'${member}' must be an array to synchronise its join table`);
-      }
-      return value.map((element) => {
-        const key = typeof element === 'string' || typeof element === 'number'
-          ? element
-          : element !== null && typeof element === 'object'
-            ? element[targetKey] : undefined;
-        if (typeof key !== 'string' && typeof key !== 'number') {
-          throw contractError(entityName,
-            `an element of '${member}' carries no usable '${targetKey}' key`);
-        }
-        return key;
-      });
-    };
+    const endpoints = joinEndpoints(entityName, member);
+    const extract = (value) => membershipKeys(value, endpoints.targetKey, member,
+      (reason) => contractError(entityName, reason));
     // a snapshot that never LOADED the member knows nothing about the
     // current membership — treating unknown as empty would re-insert
     // existing rows (a UNIQUE violation the seeded corpus found); the
@@ -307,15 +401,24 @@ export function createTracker(context) {
       ? null
       : [...new Set(extract(memberValue))];
     return {
-      joinTable: relation.joinTable,
-      ownColumn: `${entityName}_key`,
-      targetColumn: `${relation.to}_key`,
+      ...endpoints,
       ownKey,
       beforeKeys,
       afterKeys: [...new Set(extract(after[member]))],
     };
   };
 
+  /** A pending `link`/`unlink` delta as a join op. Its baseline is the
+   * join table as read at save time, so linking a member that exists
+   * and unlinking one that does not are no-ops — the two-run property. */
+  const membershipDelta = (pending) => ({
+    ...joinEndpoints(pending.entity, pending.member),
+    ownKey: pending.ownKey,
+    beforeKeys: null,
+    links: [...pending.links],
+    unlinks: [...pending.unlinks],
+  });
+
   /** Relation members riding a pending INSERT: many-to-many becomes
    * join rows; anything else refuses — projections are not state. */
   const insertRelationOps = (record) => {
@@ -334,11 +437,8 @@ export function createTracker(context) {
           + 'projection, not stored state; add the related entities themselves');
       }
       const ownKey = record.current[plan.keys[0]];
-      if (typeof ownKey !== 'string' && typeof ownKey !== 'number') {
-        throw contractError(record.entity,
-          `'${property.name}' membership needs the entity's own key at `
-          + 'add() time — save the entity first, then attach');
-      }
+      if (typeof ownKey !== 'string' && typeof ownKey !== 'number')
+        throw needsOwnKey(record.entity, property.name, 'add()');
       ops.push(joinDiff(record.entity, null, record.current, ownKey, property.name));
     }
     return ops;
@@ -368,6 +468,10 @@ export function createTracker(context) {
         continue;
       }
       if (record.current === record.snapshot) continue;
+      // a record with a pending removal is deleted, not updated: planning
+      // both bumped the version on the UPDATE and left the DELETE's
+      // snapshot guard matching nothing (JD2040), so the row survived
+      if (removals.has(recordKeyFor(record.entity, record.snapshot) ?? '')) continue;
       // probe before stamping: an update stamp must never turn a
       // deep-equal replacement into a phantom write
       if (createJSONPatch(record.snapshot, record.current).length === 0) continue;
@@ -397,6 +501,23 @@ export function createTracker(context) {
         unversioned.add(removal.entity);
     }
 
+    // a link/unlink beside a put-based synchronisation of the SAME member
+    // folds into that op's key set: one intent per entity, own key and
+    // member, never two statements racing for one row
+    const synced = new Map(joinOps.map((op) =>
+      [`${op.entity}${UNIT_SEPARATOR}${op.ownKey}${UNIT_SEPARATOR}${op.member}`, op]));
+    for (const [id, pending] of memberships) {
+      const diff = synced.get(id);
+      if (diff === undefined) {
+        joinOps.push(membershipDelta(pending));
+        continue;
+      }
+      const after = new Set(diff.afterKeys);
+      for (const key of pending.unlinks) after.delete(key);
+      for (const key of pending.links) after.add(key);
+      diff.afterKeys = [...after];
+    }
+
     // resolve unknown membership baselines, then finalize each op
     const resolveJoins = (i) => {
       if (i >= joinOps.length) return null;
@@ -413,6 +534,11 @@ export function createTracker(context) {
     const finalizeJoins = () => {
       for (const op of joinOps) {
         const before = new Set(op.beforeKeys);
+        if (op.links !== undefined) {
+          op.added = op.links.filter((key) => !before.has(key));
+          op.removed = op.unlinks.filter((key) => before.has(key));
+          continue;
+        }
         const after = new Set(op.afterKeys);
         op.added = op.afterKeys.filter((key) => !before.has(key));
         op.removed = op.beforeKeys.filter((key) => !after.has(key));
@@ -525,7 +651,7 @@ export function createTracker(context) {
             + `(${q(op.ownColumn)}, ${q(op.targetColumn)}) VALUES `
             + op.added.map((_, i) => `(${parameterAt(i * 2 + 1)}, ${parameterAt(i * 2 + 2)})`).join(', ');
           statements.push({
-            kind: 'join-insert', entity: op.joinTable, sql,
+            kind: 'join-insert', entity: op.joinTable, sql, tableColumns: op.tableColumns,
             params: op.added.flatMap((key) => [op.ownKey, key]),
             joinRows: op.added.map((key) => ({
               own: op.ownKey, target: key,
@@ -535,7 +661,7 @@ export function createTracker(context) {
         }
         for (const key of op.removed) {
           statements.push({
-            kind: 'join-delete', entity: op.joinTable,
+            kind: 'join-delete', entity: op.joinTable, tableColumns: op.tableColumns,
             sql: `DELETE FROM ${q(op.joinTable)} WHERE ${q(op.ownColumn)} = ${parameterAt(1)} `
               + `AND ${q(op.targetColumn)} = ${parameterAt(2)}`,
             params: [op.ownKey, key],
@@ -633,14 +759,8 @@ export function createTracker(context) {
             ? captureJoinDelete(statement.entity, statement.removal.parts)
             : null,
           () => {
-        let ran;
-        try {
-          ran = prepared.run(statement.params);
-        }
-        catch (error) {
-          throw wrapDb(error, statement);
-        }
-        return chain(ran, (outcome) => {
+        return chain(attempt(() => prepared.run(statement.params),
+          (error) => wrapDb(error, statement)), (outcome) => {
           const changed = Number(outcome?.changes ?? 0);
           report.statements.push({ sql: statement.sql, rows: changed });
           if (statement.kind === 'insert') report.inserted += statement.records.length;
@@ -709,12 +829,11 @@ export function createTracker(context) {
       else if (statement.kind === 'join-insert' || statement.kind === 'join-delete') {
         for (const row of statement.joinRows ?? []) {
           // the join-row "document" lists its columns in table order
-          // (the sorted pair) so both capture modes agree exactly
-          const pair = statement.entity.split('_');
+          // (the mapping's left, right) so both capture modes agree exactly
           const value = { [row.ownColumn]: row.own, [row.targetColumn]: row.target };
           const ordered = {};
-          for (const part of pair) ordered[part + '_key'] = value[part + '_key'];
-          const keyParts = pair.map((part) => ordered[part + '_key']);
+          for (const column of statement.tableColumns) ordered[column] = value[column];
+          const keyParts = statement.tableColumns.map((column) => ordered[column]);
           if (statement.kind === 'join-insert') {
             captureRecord?.(statement.entity, keyParts, null, ordered);
           }
@@ -734,6 +853,7 @@ export function createTracker(context) {
       }
     }
     removals.clear();
+    memberships.clear();
   };
 
   const saveChanges = () => {
@@ -767,10 +887,15 @@ export function createTracker(context) {
   /** Drop tracking for a key without scheduling anything. */
   const discard = (entityName, keyOrDoc) => {
     const parts = coreFor(entityName).normalizeKey(keyOrDoc);
-    records.delete(keyOf(entityName, parts));
+    const key = keyOf(entityName, parts);
+    records.delete(key);
+    // a pending membership change belongs to the key it attaches to
+    for (const id of memberships.keys()) {
+      if (id.startsWith(`${key}${UNIT_SEPARATOR}`)) memberships.delete(id);
+    }
   };
 
   return {
-    register, registerGraph, add, put, remove, discard, counts, saveChanges,
+    register, registerGraph, add, put, remove, discard, link, unlink, counts, saveChanges,
   };
 }

package/types/index.d.ts

@@ -84,7 +84,9 @@ export interface ExecuteOptions {
   pushdown?: boolean;
 }
 
-export interface LoadInclude extends LoadSpec {
+/** An include's clauses: the root's without `after` — a keyset cursor
+ * paginates the root alone; an include windows with `skip`/`take`. */
+export interface LoadInclude extends Omit<LoadSpec, 'after'> {
   /** Project the related-row COUNT instead of the rows. */
   count?: boolean;
 }
@@ -128,6 +130,8 @@ export interface StoreStats {
     tracked: number;
     pendingInserts: number;
     pendingDeletes: number;
+    /** Pending `link`/`unlink` records: one per entity, own key and member (§11.7). */
+    pendingMemberships: number;
   } | null;
   liveQueries: number;
 }
@@ -186,12 +190,44 @@ export interface SyncCollection<T = unknown> {
 
 // ————— entities (phase B) —————
 
+/** One row of an entity's relation table (MODEL-FORMAT §10.1): the
+ * declared relation as plain data a query producer can lower a hop
+ * from — never a document dialect. For a foreign-key relation `via`
+ * names the key property, `fkEntity` the entity holding it, `fkTargets`
+ * the entity it references and `targetKey` the key property it
+ * references there (the column a hop's equality compares `via` with);
+ * `kind` says which side holds the key (`oneToOne`: the declaring
+ * entity; `oneToMany`: the target). A many-to-many carries its
+ * `joinTable` and the target's `targetKey`. */
+export interface RelationEntry {
+  readonly to: string;
+  readonly kind: 'oneToOne' | 'oneToMany' | 'manyToMany';
+  readonly via?: string;
+  readonly fkEntity?: string;
+  readonly fkTargets?: string;
+  readonly joinTable?: string;
+  readonly targetKey: string;
+}
+
+/** An entity's relation table: one entry per declared relation member. */
+export type RelationTable = Readonly<Record<string, RelationEntry>>;
+
+/** The identity every entity set of one store shares — two sets with one
+ * `scope` may be joined in one document — carrying the relation tables
+ * of every root, keyed by entity name, so a hop can chain into another
+ * root of the same scope. */
+export interface EntityScope {
+  readonly relations: Readonly<Record<string, RelationTable>>;
+}
+
 export interface UntrackedReads<T = unknown> {
   get(key: EntityKeyArg): Promise<T | undefined>;
   load(spec?: LoadSpec): Promise<T[]>;
 }
 
 export interface EntitySet<T = unknown, I = unknown> {
+  /** The provider phantom: a chain over this set infers its item type. */
+  readonly __item?: T;
   create(doc: I): Promise<Readonly<T>>;
   get(key: EntityKeyArg): Promise<Readonly<T> | undefined>;
   update(key: EntityKeyArg, changes: Partial<T>): Promise<Readonly<T>>;
@@ -206,7 +242,27 @@ export interface EntitySet<T = unknown, I = unknown> {
   remove(key: EntityKeyArg | T): void;
   /** Drop tracking without scheduling anything — conflict recovery. */
   discard(key: EntityKeyArg | T): void;
+  /** Attach / detach one many-to-many membership through the unit of
+   * work (§11.7): local bookkeeping, written by `saveChanges()` as join
+   * rows against the join table as it stands then — idempotent. `own`
+   * and `target` are each a key or a document carrying the key. */
+  link(own: EntityKeyArg | T, member: string, target: EntityKeyArg | object): void;
+  unlink(own: EntityKeyArg | T, member: string, target: EntityKeyArg | object): void;
   asNoTracking(): UntrackedReads<T>;
+  /** The provider contract over this entity's root (MODEL-FORMAT §10.1):
+   * the document is over the multi-entity root and arrives whole; the
+   * answer is the engine's result shape, value-or-promise (D2). */
+  execute<R = unknown>(document: unknown, options?: ExecuteOptions): ValueOrPromise<SequenceResult<R>>;
+  explain(document: unknown, options?: ExecuteOptions): Promise<unknown>;
+  /** The root expression this set's rows are bound through (`$.<Name>[*]`). */
+  readonly root: string;
+  /** The identity every entity set of one store shares: two sets with one
+   * `scope` may be joined in one document; it carries every root's
+   * relation table. */
+  readonly scope: EntityScope;
+  /** This entity's relation table (MODEL-FORMAT §10.1) — what a query
+   * producer lowers a relation hop from. */
+  readonly relations: RelationTable;
 }
 
 export interface SyncUntrackedReads<T = unknown> {
@@ -215,6 +271,8 @@ export interface SyncUntrackedReads<T = unknown> {
 }
 
 export interface SyncEntitySet<T = unknown, I = unknown> {
+  /** The provider phantom: a chain over this set infers its item type. */
+  readonly __item?: T;
   create(doc: I): Readonly<T>;
   get(key: EntityKeyArg): Readonly<T> | undefined;
   update(key: EntityKeyArg, changes: Partial<T>): Readonly<T>;
@@ -225,7 +283,15 @@ export interface SyncEntitySet<T = unknown, I = unknown> {
   put(next: T): Readonly<T>;
   remove(key: EntityKeyArg | T): void;
   discard(key: EntityKeyArg | T): void;
+  link(own: EntityKeyArg | T, member: string, target: EntityKeyArg | object): void;
+  unlink(own: EntityKeyArg | T, member: string, target: EntityKeyArg | object): void;
   asNoTracking(): SyncUntrackedReads<T>;
+  /** The provider contract over this entity's root, answering values. */
+  execute<R = unknown>(document: unknown, options?: ExecuteOptions): SequenceResult<R>;
+  explain(document: unknown, options?: ExecuteOptions): unknown;
+  readonly root: string;
+  readonly scope: EntityScope;
+  readonly relations: RelationTable;
 }
 
 // ————— the store —————
@@ -237,6 +303,14 @@ export interface SyncStore {
   entity(name: string): SyncEntitySet;
   transaction<R>(fn: (store: Store) => R): R;
   execute?<R = unknown>(document: unknown, options?: ExecuteOptions): SequenceResult<R>;
+  explain?(document: unknown, options?: ExecuteOptions): unknown;
+  /** The entity roots this store-level provider serves (present with
+   * entities): it has no single root of its own, so a chain over it is
+   * refused by name — chain over `entity(name)` instead. */
+  readonly roots?: readonly string[];
+  /** The relation tables of every entity, keyed by entity name (present
+   * with entities; MODEL-FORMAT §10.1). */
+  readonly relations?: Readonly<Record<string, RelationTable>>;
   saveChanges?(): SaveReport;
 }
 
@@ -253,6 +327,13 @@ export interface Store {
    * in the engine's result shape. */
   execute?<R = unknown>(document: unknown, options?: ExecuteOptions): ValueOrPromise<SequenceResult<R>>;
   explain?(document: unknown, options?: ExecuteOptions): Promise<unknown>;
+  /** The entity roots this store-level provider serves (present with
+   * entities): it has no single root of its own, so a chain over it is
+   * refused by name — chain over `entity(name)` instead. */
+  readonly roots?: readonly string[];
+  /** The relation tables of every entity, keyed by entity name (present
+   * with entities; MODEL-FORMAT §10.1). */
+  readonly relations?: Readonly<Record<string, RelationTable>>;
   /** The unit of work (§11); present only with entities. */
   saveChanges?(): Promise<SaveReport>;
   transaction<R>(fn: (store: Store) => R | Promise<R>): Promise<Awaited<R>>;
@@ -409,10 +490,19 @@ export interface OpenStoreOptions {
    * than answered in UTC. No time-zone database is bundled. */
   zoneProvider?: unknown;
   busyTimeout?: number;
+  /** How long work waits for an open transaction to settle before
+   * `JD0012` (MODEL-FORMAT §5.1); reaches every driver. */
+  queueTimeout?: number;
   journalMode?: string;
   statementCacheBound?: number;
   profile?: unknown;
   readOnly?: boolean;
+  /** A `createJsltRegistry()` registry (Ring 2/3): the operators a
+   * query may use, and the pushable subset. */
+  operators?: unknown;
+  /** Raw registry-free operators; never pushed. */
+  functions?: Record<string, unknown>;
+  extensions?: Record<string, unknown>;
 }
 
 export declare function openStore(model: unknown, options: OpenStoreOptions): Promise<Store>;
@@ -433,7 +523,9 @@ export interface Dialect {
 export interface Driver {
   readonly name: string;
   readonly dialect: Dialect;
-  open(options?: unknown): unknown;
+  /** Open a connection (value-or-promise) at `path` (`':memory:'` for
+   * none) with the driver's own options. */
+  open(path: string, options?: unknown): unknown;
 }
 
 export declare const sqliteDialect: Dialect;
@@ -444,6 +536,12 @@ export declare const SQLITE_FLOOR: string;
 
 export declare function normalizeEntities(model: unknown): Map<string, unknown>;
 export declare function explainMapping(model: unknown): unknown;
+/** The relation tables of normalized entities, keyed by entity name
+ * then by relation member (MODEL-FORMAT §10.1) — what every entity set
+ * exposes as `relations` and every scope carries for all its roots. */
+export declare function relationTables(
+  entities: Map<string, unknown>,
+): Readonly<Record<string, RelationTable>>;
 
 /**
  * Build the EMIT-FORMAT model document for a model's entities.
@@ -527,7 +625,9 @@ export declare const HISTORY_TABLE: string;
 // are deliberately WIDE (unknown), never wrong.
 
 export declare function planCollection(name: string, collection: unknown, dialect: Dialect): unknown;
-export declare function compileIndexPath(path: string, schema: unknown): unknown;
+export declare function compileIndexPath(expression: string, docPath: string): unknown;
+export declare function normalizeDeclaredSql(sql: string): string;
+export declare function comparableDeclaredSql(sql: string): string;
 export declare function schemaTypeAt(schema: unknown, segments: unknown): unknown;
 export declare const KEY_COLUMN: string;
 export declare const DOC_COLUMN: string;
@@ -575,7 +675,7 @@ export declare function openConnection(raw: unknown, options: unknown): unknown;
 export declare function wrapStatement(statement: unknown): unknown;
 export declare function lazyOpen(spec: unknown, reason: string, use: unknown, args?: unknown): unknown;
 export declare function classifyLiveQuery(
-  document: unknown, queryShape: unknown, keyed: boolean): unknown;
+  document: unknown, queryShape: unknown, keyed: boolean, eventTime?: unknown): unknown;
 export declare function createLiveRegistry(
   bounds: { maxQueries: number; maxMaintained: number }): unknown;
 export declare function diffRows(oldRows: readonly unknown[], newRows: readonly unknown[]):
@@ -586,6 +686,38 @@ export declare function createSortedWindow(
 export declare function compareCodepoint(a: string, b: string): number;
 export declare function collectEntityRoots(
   document: unknown, entities: ReadonlyMap<string, unknown>): Set<string>;
+/** The root expression an entity's rows are bound through (`$.<Name>[*]`) —
+ * what an entity set exposes as `root` and what `collectEntityRoots` reads. */
+export declare function entityRoot(name: string): string;
+
+// ————— the derived-index and k-nearest machinery —————
+// Constants carry their real shapes; the functions take and answer the
+// planner's own records, which have no published type — WIDE, never
+// wrong (the line at the top of this file).
+
+export declare const DERIVE_KINDS: ReadonlySet<string>;
+export declare const DERIVE_MAPPING: Readonly<Record<string, string | null>>;
+export declare const PHYSICAL_KINDS: ReadonlySet<string>;
+export declare const BBOX_COMPONENTS: readonly ['w', 's', 'e', 'n'];
+export declare const BBOX_INDEX_ORDER: readonly ['w', 'e', 's', 'n'];
+export declare const PRECISION_MIN: number;
+export declare const PRECISION_MAX: number;
+export declare const DIMS_MIN: number;
+export declare const DIMS_MAX: number;
+export declare function derivedMappingFor(kind: string, driverMapping: unknown): unknown;
+export declare function deriveGeohash(value: unknown, precision: number): unknown;
+export declare function deriveBboxEdge(value: unknown, component: 'w' | 's' | 'e' | 'n'): unknown;
+export declare function deriveVector(member: unknown, dims: number): unknown;
+export declare function storedMemberForm(member: unknown): unknown;
+export declare function derivedValue(column: unknown, member: unknown): unknown;
+export declare function memberAt(doc: unknown, segments: unknown): unknown;
+export declare function registerDeriveFunctions(connection: unknown): unknown;
+export declare function probeVector(value: unknown, dims: number): unknown;
+export declare function columnScore(bytes: unknown, dims: number, probe: unknown): unknown;
+export declare const KNN_MARGIN: number;
+export declare const IDENTITY_CHUNK: number;
+export declare function cutCandidates(rows: unknown[], m: number, margin: number): unknown;
+export declare function identityBatches(identities: unknown[]): unknown;
 
 // ————— the job queue (JOBS-FORMAT) —————
 
@@ -617,21 +749,25 @@ export interface JobCounts {
 
 export interface JobWorker {
   start(): JobWorker;
-  /** Resolves after in-flight handlers settle. */
-  stop(): Promise<void>;
+  /** Stop claiming, signal in-flight handlers, and wait up to `graceMs`
+   * (JOBS-FORMAT §6): the record says whether every loop drained. */
+  stop(options?: { graceMs?: number }): Promise<{ drained: boolean; inFlight: number }>;
   stats(): { claims: number; completions: number; failures: number;
-    polls: number; wakes: number };
+    polls: number; wakes: number; claimErrors: number; inFlight: number };
 }
 
 export interface JobWorkerOptions {
-  handlers: Record<string,
-    (payload: unknown, context: { job: JobRecord, checkpointsFor: Function }) => unknown>;
+  handlers: Record<string, (payload: unknown, context: {
+    job: JobRecord; checkpointsFor: Function; signal: AbortSignal }) => unknown>;
+  /** A positive integer; the loops claiming concurrently. */
   concurrency?: number;
   pollInterval?: number;
   leaseMs?: number;
   owner?: string;
   backoffBase?: number;
   backoffCap?: number;
+  /** How long `stop()` waits for in-flight handlers by default. */
+  stopGraceMs?: number;
 }
 
 export interface JobsApi {
@@ -659,6 +795,7 @@ export interface JobsOptions {
   pollInterval?: number;
   backoffBase?: number;
   backoffCap?: number;
+  stopGraceMs?: number;
   /** Injectable clock and randomness — every test injects both. */
   now?: () => number;
   random?: () => number;
@@ -674,6 +811,7 @@ export declare function createDagJobRunner(store: Store, options: {
   owner?: string;
   backoffBase?: number;
   backoffCap?: number;
+  stopGraceMs?: number;
 }): JobWorker;
 
 export declare function createJobEngine(options: {
@@ -683,4 +821,8 @@ export declare const JOBS_TABLE: string;
 export declare const JOB_CHECKPOINTS_TABLE: string;
 export declare const JOB_DEFAULTS: Readonly<{
   maxAttempts: number; leaseMs: number; pollInterval: number;
-  backoffBase: number; backoffCap: number }>;
+  backoffBase: number; backoffCap: number; stopGraceMs: number }>;
+/** A total diagnostic string for any value, including ones that fight back. */
+export declare function describeValue(value: unknown): string;
+/** A job result as the queue stores it: JSON text, or the reason it could not be. */
+export declare function serializeResult(value: unknown): unknown;

package/types/node.d.ts

@@ -2,9 +2,11 @@
 import type { Driver } from '@jarenjs/db';
 
 export interface NodeOpenOptions {
-  path?: string;
+  /** The busy timeout in milliseconds. */
   timeout?: number;
   readOnly?: boolean;
+  /** How long work waits for an open transaction (`JD0012` after). */
+  queueTimeout?: number;
 }
 
 /** The `node:sqlite` binding; the builtin loads lazily inside open(). */