@jarenjs/db 0.66.1 → 0.72.0

package/src/dag-job.js

@@ -48,7 +48,7 @@ const fingerprint = (value) => hashContent(canonicalizeJson(value ?? null));
  * @param {any} store - an open store with `{ jobs: true }`
  * @param {{ compileDag: Function,
  *   documents: Record<string, any>,
- *   tasks?: Record<string, Function>,
+ *   tasks?: Record<string, Function | { run: Function, version?: string, taskVersions?: Record<string, string> }>,
  *   concurrency?: number, pollInterval?: number, leaseMs?: number,
  *   owner?: string, renew?: boolean, onOutcome?: (event: any) => void,
  *   backoffBase?: number, backoffCap?: number,
@@ -130,14 +130,20 @@ export function createDagJobRunner(store, options) {
    * just as surely as an edited document does.
    */
   const requireSameRun = async (context, jobId, revision, inputHash, taskVersions) => {
-    const loaded = await context.checkpoints.load(jobId);
-    const stored = loaded?.values?.[RUN_IDENTITY_NODE];
+    const loaded = await context.checkpoints.inspect(jobId, RUN_IDENTITY_NODE);
+    const stored = loaded.value;
     const taskVersionsHash = fingerprint(taskVersions);
     const identity = { revision, inputHash, taskVersionsHash, taskVersions };
     if (stored === undefined) {
+      if (loaded.hasValues) throw new DbRuntimeError('JD2069',
+        `run '${jobId}' cannot resume: checkpoint values have no recorded workflow, input or task identity`,
+        { docPath: '/jobs', collection: jobId });
       await context.checkpoints.save(jobId, RUN_IDENTITY_NODE, identity);
       return;
     }
+    if (stored === null || typeof stored !== 'object' || Array.isArray(stored))
+      throw new DbRuntimeError('JD2069', `run '${jobId}' has invalid checkpoint identity metadata`,
+        { docPath: '/jobs', collection: jobId });
     const differs = [];
     if (stored.revision !== revision) {
       differs.push(`the workflow (checkpointed under revision ${stored.revision}, `
@@ -152,13 +158,8 @@ export function createDagJobRunner(store, options) {
       // equal: the upgrade is allowed only where nothing can be replayed
       // wrongly — when no node value has been recorded yet, so the run has
       // nothing to inherit from an implementation nobody can name.
-      const recorded = Object.keys(loaded?.values ?? {})
-        .filter((nodeId) => nodeId !== RUN_IDENTITY_NODE);
-      if (recorded.length === 0) {
-        await context.checkpoints.save(jobId, RUN_IDENTITY_NODE, identity);
-      }
-      else {
-        differs.push(`the task versions (this run recorded ${recorded.length} node value(s) `
+      if (loaded.hasValues) {
+        differs.push(`the task versions (this run recorded node value(s) `
           + 'before task identity was persisted, so the implementation that produced them '
           + 'cannot be confirmed)');
       }
@@ -169,10 +170,14 @@ export function createDagJobRunner(store, options) {
         : `checkpointed under ${stored.taskVersionsHash}, this runner compiles `
           + `${taskVersionsHash}`})`);
     }
-    if (differs.length === 0) return;
+    if (differs.length === 0) {
+      if (stored.taskVersionsHash === undefined)
+        await context.checkpoints.save(jobId, RUN_IDENTITY_NODE, identity);
+      return;
+    }
     throw new DbRuntimeError('JD2069',
       `run '${jobId}' cannot resume: ${differs.join(' and ')} changed since its `
-      + 'checkpoints were written. Enqueue it under a new id, or drop the run — '
+      + 'checkpoints were written. Enqueue it under a new id, or explicitly reset this inactive run with its observed generation — '
       + 'reusing them would answer for a computation nobody asked for',
       { docPath: '/jobs', collection: jobId });
   };

package/src/dialect.js

@@ -171,7 +171,7 @@ function normalizeCapabilities(declared) {
  *   usesIndex: (line: string, index: string) => boolean,
  *   excludedRef: (columnSql: string) => string,
  *   tx: { begin: string, beginImmediate: string, commit: string,
- *     rollback: string,
+ *     rollback: string, deferForeignKeys?: string,
  *     savepoint: (n: string) => string, release: (n: string) => string,
  *     rollbackTo: (n: string) => string },
  *   pragma?: { set: (name: string, value: number | string) => string,

package/src/dialects/sqlite.js

@@ -401,6 +401,7 @@ export const sqliteDialect = createDialect({
   tx: {
     begin: 'BEGIN',
     beginImmediate: 'BEGIN IMMEDIATE',
+    deferForeignKeys: 'PRAGMA defer_foreign_keys = ON',
     commit: 'COMMIT',
     rollback: 'ROLLBACK',
     savepoint: (n) => `SAVEPOINT ${quoteIdentifier(n)}`,

package/src/document-files.js

@@ -208,6 +208,65 @@ export function readDocuments(source, format) {
   throw refuse(`unknown document format '${format}' — one of ${DOCUMENT_FORMATS.join(', ')}`);
 }
 
+/**
+ * Read an explicitly materialized collection-map bundle under a byte ceiling.
+ * JSON/JSONL collection readers remain streaming; a bundle holds named arrays.
+ * @param {string | AsyncIterable<any>} source
+ * @param {{ maxBytes: number | null, maxRows: number | null }} bounds
+ */
+export async function readCollectionBundle(source, bounds) {
+  let text = '', bytes = 0;
+  for await (const chunk of textChunks(source)) {
+    bytes += Buffer.byteLength(chunk);
+    if (bounds.maxBytes !== null && bytes > bounds.maxBytes)
+      throw refuse(`the collection bundle exceeds its maxBytes bound of ${bounds.maxBytes}`);
+    text += chunk;
+  }
+  const value = parseDocument(text, 'collection bundle');
+  if (value === null || typeof value !== 'object' || Array.isArray(value)
+    || Object.values(value).some((documents) => !Array.isArray(documents)))
+    throw refuse('a collection bundle is an object mapping collection names to document arrays');
+  for (const [name, documents] of Object.entries(value))
+    if (bounds.maxRows !== null && documents.length > bounds.maxRows)
+      throw refuse(`collection '${name}' exceeds its maxRows bound of ${bounds.maxRows}`);
+  return value;
+}
+
+/** One encoder for file and stream output, including atomic collection bundles. */
+function documentEncoder(format, collections = []) {
+  if (!['json', 'jsonl', 'collections'].includes(format)) throw refuse(`unknown document format '${format}'`);
+  if (format === 'collections' && (new Set(collections).size !== collections.length
+    || collections.some((name) => typeof name !== 'string')))
+    throw refuse('collection bundle names must be unique strings');
+  let documents = 0, index = -1, members = 0;
+  const advance = (next) => {
+    let text = '';
+    while (index < next) {
+      text += index < 0 ? '{\n' : '\n],\n';
+      index++;
+      text += `${JSON.stringify(collections[index])}: [`;
+      members = 0;
+    }
+    return text;
+  };
+  return {
+    write: (document, collection) => {
+      const value = JSON.stringify(document);
+      if (value === undefined) throw refuse('a document must be JSON serializable');
+      if (format === 'jsonl') { documents++; return `${value}\n`; }
+      if (format === 'json') return documents++ === 0 ? `[\n${value}` : `,\n${value}`;
+      const next = collections.indexOf(collection);
+      if (next < index || next < 0) throw refuse('collection bundle writes must follow the declared collection order');
+      const prefix = advance(next);
+      documents++;
+      return prefix + (members++ === 0 ? '\n' : ',\n') + value;
+    },
+    finish: () => format === 'jsonl' ? '' : format === 'json' ? documents === 0 ? '[]\n' : '\n]\n'
+      : collections.length === 0 ? '{}\n' : advance(collections.length - 1) + '\n]\n}\n',
+    count: () => documents,
+  };
+}
+
 /**
  * A sink that publishes whole or not at all.
  *
@@ -217,17 +276,18 @@ export function readDocuments(source, format) {
  * a target that never changed.
  *
  * @param {string} target - the file to replace
- * @param {'json' | 'jsonl'} format
- * @returns {Promise<{ write: (document: any) => Promise<void>,
+ * @param {'json' | 'jsonl' | 'collections'} format
+ * @param {{ collections?: string[] }} [options]
+ * @returns {Promise<{ write: (document: any, collection?: string) => Promise<void>,
  *   commit: () => Promise<{ bytes: number, documents: number }>,
  *   abort: () => Promise<void>, temporary: string }>}
  */
-export async function openAtomicTarget(target, format) {
+export async function openAtomicTarget(target, format, options = {}) {
+  const encoder = documentEncoder(format, options.collections);
   const directory = path.dirname(path.resolve(target));
   const temporary = path.join(directory,
     `.${path.basename(target)}.${process.pid}.${Date.now()}.tmp`);
   const handle = await fsp.open(temporary, 'wx');
-  let documents = 0;
   let bytes = 0;
   let settled = false;
 
@@ -243,21 +303,20 @@ export async function openAtomicTarget(target, format) {
 
   return {
     temporary,
-    write: async (document) => {
-      const text = JSON.stringify(document);
-      if (format === 'jsonl') { documents++; return put(`${text}\n`); }
-      return put(documents++ === 0 ? `[\n${text}` : `,\n${text}`);
+    write: async (document, collection) => {
+      if (settled) throw refuse('this target was already settled');
+      await put(encoder.write(document, collection));
     },
     commit: async () => {
       if (settled) throw refuse('this target was already settled');
       settled = true;
       try {
-        if (format === 'json') await put(documents === 0 ? '[]\n' : '\n]\n');
+        await put(encoder.finish());
         // Publish only after the temporary has been durably flushed.
         await handle.sync();
         await handle.close();
         await fsp.rename(temporary, target);
-        return { bytes, documents };
+        return { bytes, documents: encoder.count() };
       }
       catch (error) {
         try { await discard(); }
@@ -277,23 +336,20 @@ export async function openAtomicTarget(target, format) {
  * A sink that writes to an open stream (standard output) and can never
  * be taken back — `abort` is honest that what left has left.
  * @param {{ write: (chunk: string, callback: (error?: any) => void) => any }} stream
- * @param {'json' | 'jsonl'} format
+ * @param {'json' | 'jsonl' | 'collections'} format
+ * @param {{ collections?: string[] }} [options]
  */
-export function openStreamTarget(stream, format) {
-  let documents = 0;
+export function openStreamTarget(stream, format, options = {}) {
+  const encoder = documentEncoder(format, options.collections);
   const put = (text) => new Promise((resolve, reject) => {
     stream.write(text, (error) => (error ? reject(error) : resolve(undefined)));
   });
   return {
     temporary: null,
-    write: async (document) => {
-      const text = JSON.stringify(document);
-      if (format === 'jsonl') { documents++; return put(`${text}\n`); }
-      return put(documents++ === 0 ? `[\n${text}` : `,\n${text}`);
-    },
+    write: async (document, collection) => put(encoder.write(document, collection)),
     commit: async () => {
-      if (format === 'json') await put(documents === 0 ? '[]\n' : '\n]\n');
-      return { bytes: 0, documents };
+      await put(encoder.finish());
+      return { bytes: 0, documents: encoder.count() };
     },
     abort: async () => undefined,
   };

package/src/document-steps.js

@@ -16,6 +16,7 @@
  * differing in answer.
  */
 
+import { analyzeQuery, createQueryAccumulator } from '@jarenjs/json/query';
 import { DbCompileError, DbRuntimeError } from './errors.js';
 import { utf8Length } from './cursor.js';
 
@@ -54,115 +55,73 @@ export function stepFailure(migrationId, index, kind, reason, cause) {
     undefined, cause);
 }
 
-/**
- * Whether an assertion is a PER-DOCUMENT predicate — a FLWOR over the
- * collection's documents whose `$where` and `$return` read only the
- * binding — so evaluating it over each batch of documents answers
- * exactly what evaluating it over the whole collection would. Anything
- * that reads the root (`$count: '$[*]'`, a `$let`, a `$distinct`, a
- * nested `$for`) is cross-document and keeps its whole-collection read.
- * @param {any} query
- * @returns {boolean}
- */
-export function isPerDocumentAssertion(query) {
-  if (query === null || typeof query !== 'object' || Array.isArray(query)) return false;
-  const keys = Object.keys(query);
-  if (!keys.includes('$for') || !keys.includes('$return')
-    || keys.some((key) => !['$for', '$where', '$return'].includes(key))) return false;
-  const bindings = query.$for;
-  if (bindings === null || typeof bindings !== 'object' || Array.isArray(bindings)) return false;
-  const names = Object.keys(bindings);
-  if (names.length !== 1 || bindings[names[0]] !== '$[*]') return false;
-  // a root reference anywhere in the body is a cross-document read
-  const body = JSON.stringify({ $where: query.$where ?? null, $return: query.$return });
-  return !/"\$(?:[[.]|")/.test(body.replace(/"\$[A-Za-z_][A-Za-z0-9_]*/g, '"'));
+/** A path with no filter capable of reading the collection root. */
+function localPath(path) {
+  return path.segments.every((segment) => !segment.descendant
+    && segment.selectors.every((selector) => ['name', 'index', 'wildcard'].includes(selector.kind)));
 }
 
-/**
- * The aggregate shapes whose answer over a whole collection is the
- * COMBINATION of its answers over any partition of that collection —
- * which is what lets a host compute them one batch at a time and never
- * hold the collection.
- *
- * Each entry says only how two partial answers combine. What the
- * operator MEANS over a batch — its null handling, its empty-sequence
- * answer, its type coercions — is the engine's, because every batch is
- * answered by the engine's own compiled query. Nothing here reimplements
- * an operator; a fold that disagreed with the engine on any input would
- * be caught by the parity suite, which runs every shape both ways.
- *
- * `$distinct` is here only under an explicit cardinality bound: its
- * partial answer grows with the data, so without one it is not a fold
- * at all.
- * @type {Record<string, { start: any, combine: (accumulated: any, partial: any) => any,
- *   growing?: boolean }>}
- */
-const ASSOCIATIVE_AGGREGATES = {
-  // fn:count of a partition sums; the empty collection answers 0
-  $count: { start: 0, combine: (accumulated, partial) => accumulated + (partial ?? 0) },
-  // fn:sum of the empty sequence is 0, so the identity is 0
-  $sum: { start: 0, combine: (accumulated, partial) => accumulated + (partial ?? 0) },
-  // fn:min/fn:max of the empty sequence is the empty sequence, so the
-  // identity is `undefined` and a partial that is empty contributes
-  // nothing
-  $max: {
-    start: undefined,
-    combine: (accumulated, partial) => (partial === undefined ? accumulated
-      : (accumulated === undefined || partial > accumulated ? partial : accumulated)),
-  },
-  $min: {
-    start: undefined,
-    combine: (accumulated, partial) => (partial === undefined ? accumulated
-      : (accumulated === undefined || partial < accumulated ? partial : accumulated)),
-  },
-};
+/** Every item of this root scan belongs to exactly one input document. */
+function rootScan(node) {
+  return node?.kind === 'path' && node.rootSlot === 0 && localPath(node)
+    && node.segments[0]?.selectors.length === 1
+    && node.segments[0].selectors[0].kind === 'wildcard';
+}
+
+/** Expressions local to one binding; global/root and positional reads refuse. */
+function bindingLocal(node, slot) {
+  if (node === null || typeof node !== 'object') return true;
+  if (node.kind === 'literal' || node.kind === 'raw') return true;
+  if (node.kind === 'var') return node.slot === slot && !node.external;
+  if (node.kind === 'path') return node.rootSlot === slot && localPath(node);
+  if (node.kind === 'flwor' || node.kind === 'call') return false;
+  return Object.values(node).every((value) => Array.isArray(value)
+    ? value.every((item) => bindingLocal(item, slot)) : bindingLocal(value, slot));
+}
+
+/** A single unwindowed root binding whose body cannot observe other rows. */
+function independentPhrase(node) {
+  if (node?.kind !== 'flwor' || node.forBindings.length !== 1
+    || node.letBindings.length > 0 || node.groupby || node.orderby || node.count
+    || node.fold || node.limits || node.asChecks) return false;
+  const binding = node.forBindings[0];
+  return rootScan(binding.expr) && binding.atSlot < 0 && !binding.allowingEmpty
+    && !binding.window && bindingLocal(node.where, binding.slot) && bindingLocal(node.ret, binding.slot);
+}
+
+/** Invalid/unknown documents conservatively retain their materializing classification. */
+function assertionAst(query) {
+  try { return analyzeQuery(query).root; }
+  catch { return null; }
+}
 
-/** An assertion that is exactly one aggregate over the root. */
-function aggregateShapeOf(query) {
-  if (query === null || typeof query !== 'object' || Array.isArray(query)) return null;
-  const keys = Object.keys(query);
-  if (keys.length !== 1) return null;
-  const operator = keys[0];
-  return Object.hasOwn(ASSOCIATIVE_AGGREGATES, operator) ? operator : null;
+/** Whether a query's result is a concatenation of independent per-row results. */
+export function isPerDocumentAssertion(query) {
+  return independentPhrase(assertionAst(query));
 }
 
 /**
- * How a host must run an assertion, and why.
- *
- * - `perDocument` — its answer over each batch is its answer over the
- *   whole, so it walks in batches and fails at the first that violates.
- * - `fold` — it is one associative aggregate over the root, so each
- *   batch is answered by the engine and the partial answers combine.
- * - `materialize` — nothing above holds: it needs every document at
- *   once, which is a cost the host must be told about and bound.
- *
- * The one classifier every host shares, so the Store and a file cannot
- * disagree about what an assertion costs.
+ * Classify before execution. Folds consume operand ITEMS in their original
+ * order; addition is never regrouped into partition totals. Distinct folds
+ * require an explicit cardinality bound. EBV applies to the complete sequence.
  * @param {any} query
- * @returns {{ strategy: 'perDocument' | 'fold' | 'materialize', shape: string | null, reason: string }}
+ * @param {{ expect?: string, maxDistinct?: number }} [options]
+ * @returns {{ strategy: 'perDocument'|'fold'|'materialize', shape: string|null, reason: string }}
  */
-export function classifyAssertion(query) {
-  if (isPerDocumentAssertion(query)) {
-    return {
-      strategy: 'perDocument',
-      shape: null,
-      reason: 'a predicate over each document, whose answer per batch is its answer over the whole',
-    };
+export function classifyAssertion(query, options = {}) {
+  const ast = assertionAst(query);
+  if (independentPhrase(ast)) return options.expect === 'ebv'
+    ? { strategy: 'fold', shape: '$ebv', reason: 'sequence EBV retains at most two items across all batches' }
+    : { strategy: 'perDocument', shape: null, reason: 'an independent predicate over each document' };
+  if (ast?.kind === 'op' && Object.keys(query).length === 1 && Object.hasOwn(query, ast.name) && ['$count', '$sum', '$avg', '$min', '$max', '$distinct'].includes(ast.name)
+    && (rootScan(ast.args[0]) || independentPhrase(ast.args[0]))
+    && (ast.name !== '$distinct' || Number.isSafeInteger(options.maxDistinct) && options.maxDistinct > 0)) {
+    return { strategy: 'fold', shape: ast.name,
+      reason: ast.name === '$distinct' ? 'distinct items are retained under an explicit cardinality bound'
+        : 'the operand is partition-independent and items accumulate in original order' };
   }
-  const aggregate = aggregateShapeOf(query);
-  if (aggregate !== null) {
-    return {
-      strategy: 'fold',
-      shape: aggregate,
-      reason: `${aggregate} over the root is associative, so batch answers combine`,
-    };
-  }
-  return {
-    strategy: 'materialize',
-    shape: null,
-    reason: 'the assertion reads the whole root in a way that does not decompose '
-      + 'into independent batches, so every document must be held at once',
-  };
+  return { strategy: 'materialize', shape: null,
+    reason: 'the assertion may observe the whole root or position, so every document must be held under declared bounds' };
 }
 
 /**
@@ -181,6 +140,7 @@ export function classifyAssertion(query) {
  *   compileJslt: (stylesheet: any) => (document: any) => any,
  *   compileQuery: (query: any) => any,
  *   keys?: string[],
+ *   assertionBounds?: { maxRows: number | null, maxBytes: number | null, maxDistinct?: number },
  * }} context - the host's compilers and the key members a document of
  *   this collection carries, which a transform may not move
  * @returns {any} the compiled operation
@@ -244,17 +204,12 @@ export function compileDocumentStep(step, index, context) {
     fail(`the assertion does not compile: ${/** @type {Error} */ (cause).message}`,
       /** @type {Error} */ (cause));
   }
-  const classification = classifyAssertion(step.assert);
-  // the engine's own effective-boolean-value, reached through a query
-  // that answers its input unchanged: a fold checks the value it
-  // computed with exactly the rule the whole-collection path uses
-  const identity = compileQuery('$');
-  // and the engine's verdict on the EMPTY SEQUENCE, which `$max`/`$min`
-  // answer over a collection that offered them nothing. It cannot be
-  // asked of `identity` — a query's input may not be `undefined` — so it
-  // is evaluated once, by the engine, over a wildcard that selects
-  // nothing. The fold never decides this itself.
-  const emptySequenceEbv = compileQuery('$[*]').ebv([]);
+  const classification = classifyAssertion(step.assert, { expect: step.expect,
+    maxDistinct: context.assertionBounds?.maxDistinct });
+  const operand = classification.shape === '$ebv' ? step.assert
+    : classification.shape === null ? null : step.assert[classification.shape];
+  const items = classification.strategy === 'fold' ? compileQuery(operand) : null;
+  const scalar = compileQuery('$');
 
   /** The verdict on a computed result, whichever way it was computed. */
   const check = (result, ebvOf) => {
@@ -272,6 +227,10 @@ export function compileDocumentStep(step, index, context) {
   return {
     kind: 'query',
     collection: step.collection,
+    plan: { migration: migrationId, step: index, collection: step.collection, ...classification,
+      bounds: classification.strategy === 'materialize' || classification.shape === '$distinct'
+        ? context.assertionBounds ?? ASSERTION_BOUNDS_DEFAULT : null },
+    accept: (value) => check(value, () => scalar.ebv(value)),
     perDocument: classification.strategy === 'perDocument',
     strategy: classification.strategy,
     shape: classification.shape,
@@ -286,17 +245,28 @@ export function compileDocumentStep(step, index, context) {
     assert: (documents) => check(compiled(documents), () => compiled.ebv(documents)),
     /**
      * The same answer, one batch at a time. `start` is the aggregate's
-     * identity, `combine` folds the engine's answer for a batch into
-     * what earlier batches answered, and `finish` applies the step's own
+     * initial state, `combine` adds the operand's items in row order,
+     * and `finish` applies the step's own
      * verdict to the total — the same verdict `assert` applies.
      * Null when this assertion does not fold.
      */
     fold: classification.strategy !== 'fold' ? null : {
-      start: () => ASSOCIATIVE_AGGREGATES[/** @type {string} */ (classification.shape)].start,
-      combine: (accumulated, documents) => ASSOCIATIVE_AGGREGATES[
-        /** @type {string} */ (classification.shape)].combine(accumulated, compiled(documents)),
-      finish: (accumulated) => check(accumulated,
-        () => (accumulated === undefined ? emptySequenceEbv : identity.ebv(accumulated))),
+      start: () => {
+        const bounds = context.assertionBounds;
+        const guard = classification.shape === '$distinct' ? createAssertionBoundGuard({
+          maxRows: bounds.maxDistinct, maxBytes: bounds.maxBytes,
+        }, step.collection, `distinct items of migration '${migrationId}' step ${index}`) : null;
+        return createQueryAccumulator(classification.shape, {
+          docPath: `/${classification.shape}`,
+          ...(guard === null ? {} : { admit: (item) => guard.admit(item) }),
+        });
+      },
+      combine: (state, documents) => {
+        for (const item of items.items(documents)) state.add(item);
+        return state;
+      },
+      value: (state) => state.value(),
+      finish: (state) => check(state.value(), state.ebv),
     },
   };
 }
@@ -351,7 +321,7 @@ export function checkMigrationDocument(migration) {
 
 /**
  * What a MATERIALIZING assertion — one that is neither a per-document
- * predicate nor a single associative aggregate — is allowed to hold.
+ * predicate nor a supported ordered fold — is allowed to hold.
  *
  * The defaults are deliberately generous and deliberately finite: a
  * migration that used to read a large collection whole now refuses
@@ -377,7 +347,11 @@ export function normalizeAssertionBounds(declared) {
       throw new TypeError(`assertionBounds.${name} must be a positive integer, or null for no bound`);
     return value;
   };
-  return Object.freeze({ maxRows: read('maxRows'), maxBytes: read('maxBytes') });
+  if (declared.maxDistinct !== undefined
+    && (!Number.isSafeInteger(declared.maxDistinct) || declared.maxDistinct < 1))
+    throw new TypeError('assertionBounds.maxDistinct must be a positive integer');
+  return Object.freeze({ maxRows: read('maxRows'), maxBytes: read('maxBytes'),
+    ...(declared.maxDistinct === undefined ? {} : { maxDistinct: declared.maxDistinct }) });
 }
 
 /**

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';