@jarenjs/db 0.67.0 → 0.72.2

package/src/documents.js

@@ -36,7 +36,7 @@ import {
  * document is read, anything this host cannot honour.
  * @param {any[]} migrations
  * @param {Set<string>} present - the collections the caller supplied
- * @param {{ compileJslt: Function, compileQuery: Function, keys: Record<string, string[]> }} context
+ * @param {{ compileJslt: Function, compileQuery: Function, keys: Record<string, string[]>, assertionBounds: { maxRows: number | null, maxBytes: number | null, maxDistinct?: number } }} context
  * @returns {{ id: string, to: string, from: string, operations: any[] }[]}
  */
 function planStorelessRun(migrations, present, context) {
@@ -74,6 +74,7 @@ function planStorelessRun(migrations, present, context) {
         migrationId: migration.id,
         compileJslt: context.compileJslt,
         compileQuery: context.compileQuery,
+        assertionBounds: context.assertionBounds,
         keys: Object.hasOwn(context.keys, step.collection) ? (context.keys[step.collection] ?? []) : [],
       })),
     });
@@ -84,9 +85,12 @@ function planStorelessRun(migrations, present, context) {
 /** The shared option surface both surfaces read. */
 function runContext(options) {
   const runtime = resolveRuntime(options.runtime);
+  if (!Number.isSafeInteger(options.batchSize ?? 500) || (options.batchSize ?? 500) < 1)
+    throw new TypeError('batchSize must be a positive safe integer');
   return {
     batchSize: options.batchSize ?? 500,
     onProgress: options.onProgress,
+    onAssertionPlan: options.onAssertionPlan,
     keys: options.keys ?? {},
     compileJslt: options.compileJslt ?? compileJsltStylesheet,
     compileQuery: options.compileQuery ?? compileJsonQuery,
@@ -100,6 +104,12 @@ function runContext(options) {
   };
 }
 
+/** Compile all steps before a file host reads any document or opens its sink. */
+export function prepareDocumentRun(names, migrations, options = {}) {
+  const context = runContext(options);
+  return planStorelessRun(migrations, new Set(names), context);
+}
+
 /** The report both surfaces answer with, before its counts are filled. */
 const emptyReport = (plans) => ({
   applied: plans.map((plan) => plan.id),
@@ -162,10 +172,12 @@ export async function migrateDocuments(collections, migrations, options = {}) {
   for (const plan of plans) {
     for (const operation of plan.operations) {
       context.check();
+      if (operation.kind === 'query') context.onAssertionPlan?.({ ...operation.plan });
       const documents = state[operation.collection];
       const counters = countersFor(report, operation.collection);
       if (operation.kind === 'jslt') {
         for (let i = 0; i < documents.length; i++) {
+          context.check();
           documents[i] = operation.apply(documents[i], i);
           counters.transformed++;
           if ((i + 1) % context.batchSize === 0) {
@@ -180,7 +192,7 @@ export async function migrateDocuments(collections, migrations, options = {}) {
         continue;
       }
       if (operation.fold !== null) {
-        // an associative aggregate: the same batches, combined
+        // Ordered aggregate state consumes the same batches item by item.
         let accumulated = operation.fold.start();
         for (let at = 0; at < documents.length; at += context.batchSize) {
           context.check();
@@ -198,7 +210,8 @@ export async function migrateDocuments(collections, migrations, options = {}) {
         // bound is what the caller was promised, so it is checked
         const guard = createAssertionBoundGuard(context.assertionBounds, operation.collection,
           `the assertion of migration '${plan.id}'`);
-        for (const document of documents) guard.admit(document);
+        for (const document of documents) { context.check(); guard.admit(document); }
+        counters.asserted += documents.length;
         operation.assert(documents);
         continue;
       }
@@ -260,10 +273,11 @@ export async function streamDocuments(sources, migrations, options) {
   const plans = planStorelessRun(migrations, new Set(Object.keys(sources)), context);
 
   // the second refusal a single pass owes before it reads anything: a
-  // MATERIALIZING assertion. An associative aggregate is not one — its
-  // batches combine, so a single pass answers it exactly.
+  // MATERIALIZING assertion. An ordered fold only retains its state,
+  // so a single pass answers it exactly.
   for (const plan of plans) {
     for (const operation of plan.operations) {
+      if (operation.kind === 'query') context.onAssertionPlan?.({ ...operation.plan });
       if (operation.kind === 'query' && operation.strategy === 'materialize') {
         operation.fail('a cross-document assertion needs every document of '
           + `'${operation.collection}' at once, which a single pass does not hold — `
@@ -296,8 +310,10 @@ export async function streamDocuments(sources, migrations, options) {
       if (batch.length === 0) return;
       context.check();
       for (const stage of stages) {
+        context.check();
         if (stage.operation.kind === 'jslt') {
           for (let i = 0; i < batch.length; i++) {
+            context.check();
             batch[i] = stage.operation.apply(batch[i], counters.read - batch.length + i);
             counters.transformed++;
           }
@@ -315,10 +331,12 @@ export async function streamDocuments(sources, migrations, options) {
         context.onProgress?.({ migration: stage.migration, collection: name,
           asserted: counters.asserted });
       }
-      for (const document of batch) await options.write(name, document);
+      for (const document of batch) { context.check(); await options.write(name, document); }
+      context.check();
       batch = [];
     };
     for await (const document of sources[name]) {
+      context.check();
       counters.read++;
       batch.push(document);
       if (batch.length >= context.batchSize) await flush();

package/src/drivers/node.js

@@ -121,7 +121,7 @@ export function nodeDriver() {
 }
 
 export {
-  readDocuments, readJsonDocuments, readJsonlDocuments,
+  readDocuments, readJsonDocuments, readJsonlDocuments, readCollectionBundle,
   openAtomicTarget, openStreamTarget, openNullTarget,
   formatOf, DOCUMENT_FORMATS,
 } from '../document-files.js';

package/src/drivers/postgres.js

@@ -20,8 +20,8 @@
  *
  *  - `int8` and `numeric` arrive as STRINGS, because they can exceed
  *    what a double holds. The store's contract is JavaScript numbers —
- *    the same ceiling SQLite's INTEGER has — so they are converted, and
- *    a value past 2^53 loses precision here exactly as it would there.
+ *    so they are converted. An `int8` outside the safe integer range
+ *    refuses rather than returning a rounded key or count.
  *  - `json`/`jsonb` arrive PARSED, because the client's type parsers
  *    are the host's configuration. Every document read is already
  *    `::text` (the dialect's `jsonText`), but a graph load's built
@@ -34,7 +34,7 @@
 
 import { chain, openConnection, baseCapabilities } from '../driver.js';
 import { postgresDialect } from '../dialects/postgres.js';
-import { DbCompileError } from '../errors.js';
+import { DbCompileError, DbRuntimeError } from '../errors.js';
 
 export { postgresDialect, IDENTIFIER_BYTES } from '../dialects/postgres.js';
 
@@ -45,7 +45,7 @@ export const POSTGRES_FLOOR = 160000;
 /** Types the wire hands back as text because they can exceed a double,
  * and the two it hands back as text for width alone. The store's
  * contract is JavaScript numbers throughout. */
-const NUMERIC_OIDS = new Set([20, 21, 23, 26, 700, 701, 1700]);
+const NUMERIC_OIDS = new Set([21, 23, 26, 700, 701, 1700]);
 /** `json` and `jsonb`: parsed by the client unless the host said
  * otherwise, and the row decoder reads text. */
 const JSON_OIDS = new Set([114, 3802]);
@@ -73,6 +73,17 @@ let statementSequence = 0;
  *   is already what the store reads
  */
 function converterFor(dataTypeID) {
+  if (dataTypeID === 20) {
+    return (value) => {
+      if (value === null || value === undefined) return value;
+      const number = Number(value);
+      if (!Number.isSafeInteger(number)) {
+        throw new DbRuntimeError('JD2005',
+          `PostgreSQL int8 value '${String(value)}' is outside the safe JavaScript integer range`);
+      }
+      return number;
+    };
+  }
   if (NUMERIC_OIDS.has(dataTypeID)) {
     return (value) => (value === null || value === undefined ? value : Number(value));
   }

package/src/emit.js

@@ -393,6 +393,10 @@ export function emitPlan(plan, dialect, physical) {
         // per row.
         const column = q(pred.column);
         const list = pred.cells.map((cell) => param({ literal: cell })).join(', ');
+        // An empty membership search item raises in the query engine. The
+        // candidate fetch must retain it for the original row predicate.
+        if (pred.keepEmpty === true) return pred.cells.length === 0 ? `${column} IS NULL`
+          : `(${column} IS NULL OR ${column} IN (${list}))`;
         return `(${column} IS NOT NULL AND ${column} IN (${list}))`;
       }
       case 'cellPrefix': {

package/src/jobs.js

@@ -557,6 +557,12 @@ export function createJobEngine(options) {
     const lease = job?.lease;
     const generation = isLease(lease) ? lease.generation : 0;
     return {
+      inspect: (runId, nodeId) => chain(
+        prepared('cpIdentity', `SELECT value FROM "${JOB_CHECKPOINTS_TABLE}"
+          WHERE run_id=? AND node_id=? AND generation <= ?`).get([runId, nodeId, generation]),
+        (row) => chain(prepared('cpHasValues', `SELECT 1 AS present FROM "${JOB_CHECKPOINTS_TABLE}"
+          WHERE run_id=? AND node_id<>? AND generation <= ? LIMIT 1`).get([runId, nodeId, generation]),
+        (other) => ({ value: row === undefined ? undefined : JSON.parse(row.value), hasValues: other !== undefined }))),
       load: (runId) => chain(
         prepared('cpLoad', `SELECT node_id, value FROM "${JOB_CHECKPOINTS_TABLE}"
           WHERE run_id = ? AND generation <= ?`).all([runId, generation]),
@@ -772,6 +778,39 @@ export function createJobEngine(options) {
     });
   };
 
+  /**
+   * Explicitly discard one inactive run's checkpoints and start a new attempt
+   * budget. The caller must name the observed generation; a concurrent claim
+   * or reset invalidates that authorization. External task effects are not undone.
+   * @param {string} id
+   * @param {{ expectedGeneration: number, signal?: AbortSignal, deadline?: number }} resetOptions
+   */
+  const reset = (id, resetOptions) => {
+    if (typeof id !== 'string' || id === '') throw new TypeError('reset: id is a non-empty string');
+    const expected = resetOptions?.expectedGeneration;
+    if (!Number.isSafeInteger(expected) || expected < 0)
+      throw new TypeError('reset: expectedGeneration is the observed non-negative lease generation');
+    refuseCancelled(resetOptions, now, { abortCode: 'JD2081', aborted: 'reset() ran', passed: 'reset() ran' });
+    const at = now();
+    return connection.transaction(() => chain(
+      prepared('resetJob', `UPDATE "${JOBS_TABLE}" SET state='pending', attempts=0,
+        result=NULL, last_error=NULL, run_at=?, updated_at=?, lease_until=NULL,
+        lease_owner=NULL, lease_token=NULL, lease_generation=lease_generation+1
+        WHERE id=? AND lease_generation=? AND state<>'done'
+          AND (state<>'leased' OR lease_until<=?)`).run([at, at, id, expected, at]),
+      (out) => {
+        if (Number(out.changes ?? 0) === 0) return chain(get(id), (job) => {
+          const code = job?.state === 'leased' && job.leaseUntil > at ? 'JD2068'
+            : job !== undefined && job.leaseGeneration !== expected ? 'JD2066' : 'JD2065';
+          throw new DbRuntimeError(code,
+            `reset() refused: job '${id}' is unknown, completed, actively leased, or its generation changed; read it again before resetting`,
+            { docPath: '/jobs', collection: JOBS_TABLE, key: id });
+        });
+        return chain(prepared('resetCheckpoints', `DELETE FROM "${JOB_CHECKPOINTS_TABLE}" WHERE run_id=?`).run([id]),
+          (removed) => { wakeAll(); return { reset: true, discarded: Number(removed.changes ?? 0), generation: expected + 1 }; });
+      }));
+  };
+
   /**
    * Delete settled jobs (done, dead, cancelled) whose last change is
    * older than `settledBefore`, oldest first, at most `limit` of them,
@@ -1014,6 +1053,8 @@ export function createJobEngine(options) {
       // so a checkpoint can neither join an unrelated application
       // transaction nor still be writing when stop() has resolved
       attempt.checkpoints = {
+        inspect: (runId, nodeId) => io(() =>
+          checkpointsFor({ ...job, lease: attempt.lease }).inspect(runId, nodeId), 'a checkpoint identity read'),
         load: (runId) => io(() =>
           checkpointsFor({ ...job, lease: attempt.lease }).load(runId), 'a checkpoint read'),
         save: (runId, nodeId, value) => io(() =>
@@ -1297,6 +1338,7 @@ export function createJobEngine(options) {
     cancel,
     settledLocally,
     requeue,
+    reset,
     sweep,
     /** Stop every worker, bounded. Resolves to the per-worker outcome so
      * `close()` can report a handler it could not wait out rather than

package/src/migrate.js

@@ -32,6 +32,8 @@ import { compileJsltStylesheet } from '@jarenjs/json/jslt';
 import { DbCompileError } from './errors.js';
 import { chain, toPromise } from './driver.js';
 import { normalizeModel } from './store.js';
+import { planQuery } from './plan.js';
+import { createQueryEngine, createQueryState } from './query.js';
 import { CHANGES_TABLE, CHANGES_STATE_TABLE } from './capture.js';
 import { JOBS_TABLE, JOB_CHECKPOINTS_TABLE } from './jobs.js';
 import { planCollection, verifyShape, planEntity, planJoinTable } from './ddl.js';
@@ -1012,6 +1014,21 @@ export function compareShapeToModel(driver, connection, model, registerFunctions
     }));
 }
 
+/**
+ * Count can use the existing provider planner without assuming an intermediate
+ * schema. A native plan proves both row selection and item cardinality. Typed
+ * aggregates keep ordered engine folds until their current shape is declared.
+ */
+function assertionProvider(query, collection, shape) {
+  if (shape !== '$count') return null;
+  const operand = query.$count;
+  const document = { $count: typeof operand === 'string' && operand.startsWith('$[*]')
+    ? { $for: { row: '$[*]' }, $return: `$row${operand.slice(4)}` } : operand };
+  const source = { collection, schema: { type: 'object' }, columnByCanonical: new Map(), indexes: [] };
+  const planned = planQuery(document, source);
+  return planned.mode === 'native' && planned.plan?.aggregate?.fn === 'count' ? document : null;
+}
+
 /**
  * The batched row walk shared by transforms and post-validation:
  * `SELECT rowid, json(doc) ... WHERE rowid > ? ORDER BY rowid LIMIT ?`
@@ -1247,17 +1264,28 @@ function runSteps(connection, migration, options) {
         migrationId: migration.id,
         compileJslt: compileJsltStylesheet,
         compileQuery: compileJsonQuery,
+        assertionBounds: options.assertionBounds,
       });
       const assertOver = operation.assert;
       const readDoc = (row) => (assertionMapping === null
         ? JSON.parse(row.doc)
         : mergeEntityRow(assertionMapping, row, 'doc'));
 
+      const provider = assertionMapping === null ? assertionProvider(current.assert, current.collection, operation.shape) : null;
+      options.onAssertionPlan?.({ ...operation.plan, ...(provider === null ? {} : {
+        strategy: 'provider', reason: 'the existing query planner proves a native count without assuming an intermediate schema',
+      }) });
+      if (provider !== null) {
+        const engine = createQueryEngine({ connection, state: createQueryState(),
+          collection: { name: current.collection, schema: { type: 'object' }, docPath: '' },
+          physicalPlan: { table: current.collection, keyColumn: 'key', docColumn: 'doc', columnByCanonical: new Map() },
+        });
+        return chain(engine.execute(provider, { strict: true }), operation.accept);
+      }
+
       if (operation.fold !== null) {
-        // an associative aggregate: each batch is answered by the engine
-        // and the partial answers combine, so the collection is never
-        // held. The whole-collection read this replaces is the one
-        // statement a cross-document assertion used to cost.
+        // Consume operand items in row order through the query engine's
+        // shared state: regrouping floating-point batch totals is unsound.
         let accumulated = operation.fold.start();
         let folded = 0;
         return chain(walkRows(connection, current.collection, options.batchSize, (rows) => {
@@ -1604,6 +1632,8 @@ export function migrate(target, migrations, options) {
       'migrate needs { baseline }: the model the store was first created with '
       + '(the chain anchor and the shadow starting shape)');
   const batchSize = options.batchSize ?? 500;
+  if (!Number.isSafeInteger(batchSize) || batchSize < 1)
+    throw new TypeError('batchSize must be a positive safe integer');
   const runtime = resolveRuntime(options.runtime);
   /**
    * The cancellation boundary: between migrations, between steps and
@@ -1621,6 +1651,7 @@ export function migrate(target, migrations, options) {
     batchSize,
     assertionBounds: normalizeAssertionBounds(options.assertionBounds),
     onProgress: options.onProgress,
+    onAssertionPlan: options.onAssertionPlan,
     registerFunctions: options.registerFunctions,
     // the host's declared index-expression functions ride to every
     // planner and every connection this run opens — the shadow's
@@ -1740,7 +1771,15 @@ export function migrate(target, migrations, options) {
                   }
                   else if (migrationStep.kind === 'jslt')
                     rendered.push(`-- jslt transform over '${migrationStep.collection}'`);
-                  else rendered.push(`-- assert over '${migrationStep.collection}'`);
+                  else {
+                    const operation = compileDocumentStep(migrationStep, migration.steps.indexOf(migrationStep), {
+                      migrationId: migration.id, compileJslt: compileJsltStylesheet, compileQuery: compileJsonQuery,
+                      assertionBounds: runOptions.assertionBounds,
+                    });
+                    const strategy = assertionProvider(migrationStep.assert, migrationStep.collection, operation.shape) === null
+                      ? operation.strategy : 'provider';
+                    rendered.push(`-- assert over '${migrationStep.collection}' (${strategy}; ${operation.reason})`);
+                  }
                 }
                 const jsltCollections = [...new Set(migration.steps
                   .filter((s) => s.kind === 'jslt').map((s) => s.collection))];

package/src/plan.js

@@ -505,6 +505,8 @@ const SPATIAL_REASONS = {
   distance: 'a geodesic-circle box pre-filter is pushed; the exact distance refines in the engine',
   prefix: "a cell-range pre-filter over the derived column's precision is pushed; "
     + 'the longer prefix refines in the engine',
+  membership: 'the cell pre-filter retains unbounded members; the engine preserves '
+    + 'the membership error when its search item is empty',
   noIndex: 'no derived spatial index on this member covers the predicate '
     + '(declare indexes[].derive on it)',
   notGeographic: 'spatial predicates translate only over a member the schema types as an '
@@ -856,10 +858,12 @@ function planCellPrefix(node, itSlot, shape) {
  * the cells inline, where the planner can see them.
  *
  * Recognized: `{$exists: {$index-of: [{$geohash-neighbours: "cell"},
- * {$geohash: [path, k]}]}}`. Exact only when the cell's length IS k —
+ * {$geohash: [path, k]}]}}`. Admitted only when the cell's length IS k —
  * the membership test compares whole strings, so any other length makes
  * the document's own predicate constantly false and the promotion would
- * be answering a different question.
+ * be answering a different question. Unbounded rows remain candidates:
+ * the engine's membership raises on an empty search item, so the original
+ * predicate must still run even when the column covers whole cell strings.
  * @param {any} node
  * @param {number} itSlot
  * @param {any} shape
@@ -878,9 +882,26 @@ function planCellNeighbourhood(node, itSlot, shape) {
   const cells = cellNeighbourhood(cell.value);
   if (cells.length === 0)
     return { refusal: refusal('$geohash-neighbours', SPATIAL_REASONS.operand) };
-  return promotion({ p: 'cellIn', column: derivation.column, cells },
+  return promotion({ p: 'cellIn', column: derivation.column, cells, keepEmpty: true },
     { construct: '$geohash-neighbours', via: 'columns', columns: [derivation.column],
-      exact: true });
+      exact: false }, [refusal('$geohash-neighbours', SPATIAL_REASONS.membership)]);
+}
+
+/** Error candidates cannot be discarded by a different pushed conjunct. */
+function neighbourhoodErrorColumns(node, itSlot, shape, columns = new Set()) {
+  if (node === null || typeof node !== 'object') return columns;
+  if (node.kind === 'op' && node.name === '$index-of'
+    && node.args[0]?.name === '$geohash-neighbours') {
+    const derivation = geohashDerivation(node.args[1], itSlot, shape, '$geohash-neighbours');
+    if (!('refusal' in derivation)) columns.add(derivation.column);
+  }
+  for (const value of Object.values(node)) {
+    if (Array.isArray(value)) {
+      for (const child of value) neighbourhoodErrorColumns(child, itSlot, shape, columns);
+    }
+    else if (value !== null && typeof value === 'object') neighbourhoodErrorColumns(value, itSlot, shape, columns);
+  }
+  return columns;
 }
 
 // ————— The k-nearest promotion: an ORDERING the column pre-filters —————
@@ -2365,6 +2386,21 @@ function planFlwor(node, shape, rawFlwor, udfHook) {
     }
   }
 
+  // A later conjunct must not hide an earlier membership error. Retain
+  // every potentially empty search row through the combined SQL filter;
+  // the original WHERE then decides whether short-circuiting reaches it.
+  const errorColumns = neighbourhoodErrorColumns(node.where, itSlot, shape);
+  if (errorColumns.size > 0 && plan.filter !== null) {
+    if (!(plan.filter.p === 'cellIn' && plan.filter.keepEmpty === true
+      && errorColumns.size === 1 && errorColumns.has(plan.filter.column))) {
+      plan.filter = { p: 'or', items: [plan.filter, ...[...errorColumns].map((column) =>
+        ({ p: 'cellIn', column, cells: [], keepEmpty: true }))] };
+    }
+    whereFullyPushed = false;
+    if (!reasons.some((entry) => entry.reason === SPATIAL_REASONS.membership))
+      reasons.push(refusal('$geohash-neighbours', SPATIAL_REASONS.membership));
+  }
+
   // ORDER BY: all terms or none — a partially pushed ordering is wrong.
   // A k-nearest ordering is the third outcome: not pushed, but
   // recognized for the column to pre-filter (the reason is the

package/src/store.js

@@ -450,12 +450,19 @@ function wrapWriteError(error, plan, collection, docPath, key) {
  * open nothing else holds the connection.
  * @param {any} connection
  * @param {() => any} fn - value-or-promise
+ * @param {boolean} [retry] - one retry for a concurrent catalog creation
  * @returns {any} value-or-promise
  */
-function immediately(connection, fn) {
+function immediately(connection, fn, retry = true) {
   const dialect = connection.dialect;
   const commit = (value) => chain(connection.exec(dialect.tx.commit), () => value);
-  const rollback = (error) => chain(connection.exec(dialect.tx.rollback), () => { throw error; });
+  const rollback = (error) => chain(connection.exec(dialect.tx.rollback), () => {
+    // The winner's CREATE has committed before a catalog collision returns.
+    // Re-read and verify that shape in a fresh transaction, once per bracket;
+    // collection and entity creation can race independently during one open.
+    if (retry && dialect.isCreateRace?.(error) === true) return immediately(connection, fn, false);
+    throw error;
+  });
   return chain(connection.exec(dialect.tx.beginImmediate), () => {
     let out;
     try {
@@ -673,6 +680,14 @@ function collectionCore(connection, collection, plan, validate, queryState, stor
         (error) => wrapWriteError(error, plan, collection.name, collection.docPath, key)));
   };
 
+  // RETURNING is decoded after the server has inserted the row. Keep
+  // decoding in the same transaction so an unrepresentable allocated
+  // key refuses without committing a document the caller cannot address.
+  const insertAllocated = (doc) => connection.transaction(() => chain(
+    runWrite('insertAllocated', dialect.dml.insertAllocated(shape),
+      [JSON.stringify(doc), ...derivedFor(doc)], undefined, true),
+    (row) => row.key));
+
   const core = {
     stats: () => ({ ...stats, ...engine.stats() }),
     model: collection,
@@ -694,12 +709,7 @@ function collectionCore(connection, collection, plan, validate, queryState, stor
     insert(doc) {
       checkValid(doc);
       const key = resolveWriteKey(doc, undefined);
-      if (key === null) {
-        return chain(
-          runWrite('insertAllocated', dialect.dml.insertAllocated(shape),
-            [JSON.stringify(doc), ...derivedFor(doc)], undefined, true),
-          (row) => row.key);
-      }
+      if (key === null) return insertAllocated(doc);
       return chain(
         runWrite('insert', dialect.dml.insert(shape),
           [key, JSON.stringify(doc), ...derivedFor(doc)], key, false),
@@ -708,12 +718,7 @@ function collectionCore(connection, collection, plan, validate, queryState, stor
     put(doc, explicitKey) {
       checkValid(doc);
       const key = resolveWriteKey(doc, explicitKey);
-      if (key === null) {
-        return chain(
-          runWrite('insertAllocated', dialect.dml.insertAllocated(shape),
-            [JSON.stringify(doc), ...derivedFor(doc)], undefined, true),
-          (row) => row.key);
-      }
+      if (key === null) return insertAllocated(doc);
       return chain(
         runWrite('upsert', dialect.dml.upsert(shape),
           [key, JSON.stringify(doc), ...derivedFor(doc)], key, false),
@@ -2439,6 +2444,7 @@ export function openStore(model, options) {
               checkpointsFor: (job) => {
                 const inner = jobsEngine.checkpointsFor(job);
                 return Object.freeze({
+                  inspect: (runId, nodeId) => gated(() => inner.inspect(runId, nodeId), 'a root checkpoint identity read'),
                   load: (runId) => gated(() => inner.load(runId), 'a root checkpoint read'),
                   save: (runId, nodeId, value) =>
                     gated(() => inner.save(runId, nodeId, value), 'a root checkpoint save'),
@@ -2459,6 +2465,7 @@ export function openStore(model, options) {
                 gated(() => jobsEngine.cancel(id, cancelOptions), 'a root job cancellation'),
                 (outcome) => chain(jobsEngine.settledLocally(id), () => outcome))),
               requeue: lift((...args) => gated(() => jobsEngine.requeue(...args), 'a root job requeue')),
+              reset: lift((...args) => gated(() => jobsEngine.reset(...args), 'a root job reset')),
               sweep: lift((...args) => gated(() => jobsEngine.sweep(...args), 'a root job sweep')),
             }),
             /**
@@ -2875,6 +2882,10 @@ export function openStore(model, options) {
                 checkpointsFor: (/** @type {any} */ job) => {
                   const inner = jobsEngine.checkpointsFor(job);
                   return Object.freeze({
+                    inspect: lift((/** @type {any} */ runId, /** @type {any} */ nodeId) => {
+                      requireScope(identity);
+                      return inner.inspect(runId, nodeId);
+                    }),
                     load: lift((/** @type {any} */ runId) => {
                       requireScope(identity);
                       return inner.load(runId);

package/types/index.d.ts

@@ -1274,6 +1274,23 @@ export declare function readSchema(connection: unknown, options?: {
   tables?: readonly string[];
 }): unknown;
 
+export interface AssertionBounds {
+  maxRows?: number | null;
+  maxBytes?: number | null;
+  /** Opt into a distinct fold with at most this many unique items. */
+  maxDistinct?: number;
+}
+
+export interface AssertionPlan {
+  migration: string;
+  step: number;
+  collection: string;
+  strategy: 'provider' | 'perDocument' | 'fold' | 'materialize';
+  shape: string | null;
+  reason: string;
+  bounds: AssertionBounds | null;
+}
+
 export interface MigrateOptions {
   baseline: unknown;
   model?: unknown;
@@ -1307,13 +1324,14 @@ export interface MigrateOptions {
   /** An epoch-millisecond deadline on `runtime`'s clock (`JD2075`). */
   deadline?: number;
   /** What a MATERIALIZING assertion may hold. A per-document predicate
-   * and a single associative aggregate over the root are answered in
+   * and a supported ordered aggregate over independent rows are answered in
    * batches and are never bounded by this; anything else must hold the
    * collection at once and crosses these bounds before the excess is
    * held (`JD2007` rows, `JD2076` bytes). Defaults to
    * {@link ASSERTION_BOUNDS_DEFAULT}; `null` on either member removes
    * that bound, deliberately. */
-  assertionBounds?: { maxRows?: number | null; maxBytes?: number | null };
+  assertionBounds?: AssertionBounds;
+  onAssertionPlan?: (plan: AssertionPlan) => void;
 }
 
 /** The finite defaults a materializing assertion runs under when the
@@ -1324,9 +1342,8 @@ export declare const ASSERTION_BOUNDS_DEFAULT: {
 };
 
 /** How a host must run an assertion, and why. `perDocument` walks in
- * batches; `fold` is one associative aggregate whose batch answers
- * combine; `materialize` needs every document at once and is bounded. */
-export declare function classifyAssertion(query: unknown): {
+ * batches; `fold` accumulates query items in order; `materialize` needs every document at once and is bounded. */
+export declare function classifyAssertion(query: unknown, options?: { expect?: string; maxDistinct?: number }): {
   strategy: 'perDocument' | 'fold' | 'materialize';
   shape: string | null;
   reason: string;
@@ -1402,7 +1419,8 @@ export interface DocumentMigrationOptions {
   /** What a MATERIALIZING assertion may hold; the same bounds, and the
    * same refusals, a Store applies. Defaults to
    * {@link ASSERTION_BOUNDS_DEFAULT}. */
-  assertionBounds?: { maxRows?: number | null; maxBytes?: number | null };
+  assertionBounds?: AssertionBounds;
+  onAssertionPlan?: (plan: AssertionPlan) => void;
   /** Documents per assertion batch and per progress event (default 500). */
   batchSize?: number;
   onProgress?: (progress: MigrationProgress) => void;
@@ -1457,6 +1475,7 @@ export declare function compileDocumentStep(
     compileJslt: (stylesheet: unknown) => (document: unknown) => unknown;
     compileQuery: (query: unknown) => unknown;
     keys?: readonly string[];
+    assertionBounds?: { maxRows: number | null; maxBytes: number | null; maxDistinct?: number };
   },
 ): unknown;
 /** Structural validation of one migration document (`JD0023`/`JD0021`). */
@@ -1815,6 +1834,7 @@ export interface JobsApi {
    * written up to it, and a settlement prunes no further, so a stale
    * attempt cannot erase a live one's work. */
   checkpointsFor(job: ClaimedJob): {
+    inspect(runId: string, nodeId: string): unknown;
     load(runId: string): unknown;
     save(runId: string, nodeId: string, value: unknown): unknown;
     complete(runId: string, result: unknown): unknown;
@@ -1840,6 +1860,11 @@ export interface JobPageOptions {
  * schedule: WHEN to sweep or cancel is the host's call.
  */
 export interface JobsAdminApi {
+  /** Discard an inactive run's checkpoints and restart its attempts, atomically.
+   * Requires its observed generation; refuses done jobs and live leases.
+   * External effects are not undone. */
+  reset(id: string, options: { expectedGeneration: number; signal?: AbortSignal; deadline?: number }):
+    Promise<{ reset: true; discarded: number; generation: number }>;
   /** A keyset cursor over the queue by id, admitted per pull under the
    * store gate; each item is the record `get` answers. */
   page(options?: JobPageOptions): QueryCursor<JobRecord>;
@@ -1876,7 +1901,7 @@ export interface JobsOptions {
 export declare function createDagJobRunner(store: Store, options: {
   compileDag: Function;
   documents: Record<string, unknown>;
-  tasks?: Record<string, Function>;
+  tasks?: Record<string, Function | { run: Function; version?: string; taskVersions?: Record<string, string> }>;
   concurrency?: number;
   pollInterval?: number;
   leaseMs?: number;

package/types/node.d.ts

@@ -61,7 +61,7 @@ export declare function readDocuments(
 export interface DocumentTarget {
   /** The sibling file being filled, or null for a sink with no file. */
   readonly temporary: string | null;
-  write(document: unknown): Promise<void>;
+  write(document: unknown, collection?: string): Promise<void>;
   /** Flush, rename over the target, and answer what was written. */
   commit(): Promise<{ bytes: number; documents: number }>;
   /** Remove the temporary; the target keeps the bytes it had. */
@@ -72,13 +72,19 @@ export interface DocumentTarget {
  * on `commit`, and removed on `abort`, so a failed run leaves the
  * original byte for byte. */
 export declare function openAtomicTarget(
-  target: string, format: 'json' | 'jsonl',
+  target: string, format: 'json' | 'jsonl' | 'collections',
+  options?: { collections?: string[] },
 ): Promise<DocumentTarget>;
 
 /** Write to an open stream; `abort` cannot take back what has left. */
 export declare function openStreamTarget(
-  stream: DocumentByteSink, format: 'json' | 'jsonl',
+  stream: DocumentByteSink, format: 'json' | 'jsonl' | 'collections',
+  options?: { collections?: string[] },
 ): DocumentTarget;
 
 /** Validate everything and write nothing. */
 export declare function openNullTarget(): DocumentTarget;
+
+/** Read an explicit collection bundle, materialized under the declared bounds. */
+export declare function readCollectionBundle(source: DocumentByteSource,
+  bounds: { maxBytes: number | null; maxRows: number | null }): Promise<Record<string, unknown[]>>;