@jarenjs/db 0.67.0 → 0.72.0

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

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/store.js

@@ -2439,6 +2439,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 +2460,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 +2877,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);