@jarenjs/db 0.46.5 → 0.56.0

package/src/query.js

@@ -39,7 +39,7 @@ import { chain } from './driver.js';
 import {
   planQuery, planEntityQuery, entityShape, planEntityPredicate, entityPathRef,
 } from './plan.js';
-import { emitPlan, emitEntityPlan, createEntityPredicateEmitters } from './emit.js';
+import { emitPlan, emitEntityPlan, createEntityPredicateEmitters, UnrepresentablePath } from './emit.js';
 import { selectPlan } from './algebra.js';
 import { compileSetResidual, compileRowResidual, sequenceResult } from './residual.js';
 import { derivedSlotValue, probeBox, probeVector, columnScore } from './derive.js';
@@ -58,18 +58,52 @@ import {
  * residual.
  * @param {number} [bound]
  * @param {{ functions?: any, extensions?: any } | null} [operators]
+ * @param {any} [zoneProvider] - D7's injected clock, or absent
  * @returns {any}
  */
-export function createQueryState(bound = undefined, operators = null) {
+export function createQueryState(bound = undefined, operators = null,
+  zoneProvider = undefined) {
   return {
     cache: createSemanticCache(bound ?? 128),
     counters: { hits: 0, misses: 0, evictions: 0 },
     /** Fragment identity → the SQL function name registered for it. */
     registered: new Map(),
     operators: operators ?? null,
+    // D7's injected clock: a named zone is host code a database does
+    // not have, so a calendar ladder over one walks in the residual —
+    // and the residual is the caller's OWN document, so the frozen spec
+    // reaches the kernel unchanged rather than being rebuilt in UTC
+    zoneProvider: zoneProvider ?? null,
   };
 }
 
+/**
+ * The answer for a native selection's items: the engine's result shape
+ * (`undefined | item | items`), or — when the document is a chain's
+ * element WINDOW, `[<phrase>]` (plan.js, `wrapped`) — the items as the
+ * ONE array that constructor yields, never singleton-unwrapped: an empty
+ * selection is `[]`, one row is `[row]`. Exactly the engine's answer for
+ * the same document, which is what lets a chain's `toArray()` push.
+ * @param {any} entry
+ * @param {any[]} items
+ * @returns {any}
+ */
+function answerOf(entry, items) {
+  return entry.planned.wrapped === true ? items : sequenceResult(items);
+}
+
+/**
+ * The same for one aggregate value: `[value]` under the window, and `[]`
+ * for an aggregate that answers nothing.
+ * @param {any} entry
+ * @param {any} value
+ * @returns {any}
+ */
+function wrapValue(entry, value) {
+  if (entry.planned.wrapped !== true) return value;
+  return value === undefined ? [] : [value];
+}
+
 /** @param {any} value - a bindable native parameter? */
 function bindable(value) {
   return typeof value === 'string'
@@ -135,11 +169,16 @@ export function createQueryEngine(context) {
   // residual compilation here. `null` when the store opened with no
   // registry — the whole engine is then byte-identical to before.
   const operators = state.operators ?? null;
+  const zoneProvider = state.zoneProvider ?? null;
   const dialect = connection.dialect;
   const shape = {
     collection: collection.name,
     schema: collection.schema,
     columnByCanonical: physicalPlan.columnByCanonical,
+    // the DECLARED indexes, in their declared column order: a temporal
+    // plan is recognized by the index a model already has, so the
+    // planner needs to see the list rather than guess a column's role
+    indexes: physicalPlan.expected?.indexes ?? [],
     // the R*Tree virtual tables this collection's `bbox` column sets are
     // realized as, by stem — empty under `physical: 'columns'`, and
     // empty on a driver whose build carries no R*Tree module, because
@@ -163,6 +202,14 @@ export function createQueryEngine(context) {
    * a k-nearest query into a full scan that `explain()` still calls
    * `knn`, which is the one thing this mode may not do quietly. */
   const knnStats = { queries: 0, rows: 0, candidates: 0, fullFetches: 0, diverted: 0 };
+  /** The temporal counters `stats()` reports, and the ONLY place a
+   * candidate or a result count comes from: `explain()` reads the LAST
+   * ACTUAL run's numbers off the cache entry rather than estimating
+   * any of them. `statements` is what makes the as-of bound checkable —
+   * one narrowing fetch per call, whatever the probes number — and
+   * `diverted` counts the calls whose native bucket met a group with no
+   * instant and handed the whole question back to the engine. */
+  const seriesStats = { queries: 0, statements: 0, candidates: 0, results: 0, diverted: 0 };
   /** The by-identities fetch statements, one per batch size. */
   const identityFetch = new Map();
 
@@ -171,13 +218,15 @@ export function createQueryEngine(context) {
   const residualCompileOptions = (limits) => {
     const functions = operators?.functions;
     const extensions = operators?.extensions;
-    if (limits === undefined && functions === undefined && extensions === undefined)
+    if (limits === undefined && functions === undefined && extensions === undefined
+      && zoneProvider === null)
       return undefined;
     /** @type {any} */
     const options = {};
     if (limits !== undefined) options.limits = limits;
     if (functions !== undefined) options.functions = functions;
     if (extensions !== undefined) options.extensions = extensions;
+    if (zoneProvider !== null) options.zoneProvider = zoneProvider;
     return options;
   };
 
@@ -277,8 +326,26 @@ export function createQueryEngine(context) {
       return out;
     };
 
-    const plan = shapePlan(planned.plan ?? selectPlan(collection.name));
-    const emitted = emitPlan(plan, dialect, physical);
+    let plan = shapePlan(planned.plan ?? selectPlan(collection.name));
+    let emitted;
+    try {
+      emitted = emitPlan(plan, dialect, physical);
+    }
+    catch (error) {
+      if (!(error instanceof UnrepresentablePath)) throw error;
+      // a member name the dialect cannot spell: the whole document runs
+      // in the set residual, named — and strict mode refuses it by name
+      if (strict) {
+        throw new DbCompileError('JD0010',
+          `strict mode refused a residual: 'path' — ${error.message}`, collection.docPath);
+      }
+      planned = {
+        ...planned, plan: null, mode: 'set', rowReturn: null, udfs: [], prefilters: [],
+        series: null, reasons: [{ construct: 'path', reason: error.message }, ...planned.reasons],
+      };
+      plan = shapePlan(selectPlan(collection.name));
+      emitted = emitPlan(plan, dialect, physical);
+    }
     const externalNames = planned.analysis.externals.map((e) => e.name);
     const limits = profile === null ? undefined : profile.limits;
     const entry = {
@@ -302,10 +369,13 @@ export function createQueryEngine(context) {
       setResidual: null,
       packedResidual: null,
       rowResidual: planned.mode === 'row'
-        ? compileRowResidual(planned.rowReturn, limits, operators)
+        ? compileRowResidual(planned.rowReturn, limits, operators, zoneProvider)
         : null,
       fullScanSql: null,
       fullScanShape: () => shapePlan(selectPlan(collection.name)),
+      // the LAST actual execution's numbers, never an estimate: `null`
+      // until this document has run once
+      seriesCounts: null,
     };
 
     const sizeBefore = state.cache.size();
@@ -320,7 +390,8 @@ export function createQueryEngine(context) {
   };
   const setResidualOf = (entry, document) => {
     if (entry.setResidual === null)
-      entry.setResidual = compileSetResidual(document, entry.residualLimits, operators);
+      entry.setResidual = compileSetResidual(document, entry.residualLimits, operators,
+        zoneProvider);
     return entry.setResidual;
   };
   /** The item-packing variant for cursors: `[document]` packs the
@@ -397,6 +468,68 @@ export function createQueryEngine(context) {
 
   const rowsToDocs = (rows) => rows.map((row) => JSON.parse(row.doc));
 
+  /**
+   * The bucket records a native temporal group answers: the ladder's
+   * start under the name the document asked for it by, then one member
+   * per aggregate with the caller's own word for "no numbers".
+   *
+   * `null` when a group has no instant at all — a row whose instant
+   * member is missing or is not a number groups under SQL `NULL`, and
+   * the kernel REFUSES such a row (`JQ2001`). SQL cannot refuse, so the
+   * call diverts and the engine answers, exactly as it does everywhere.
+   * @param {any} entry
+   * @param {any[]} rows
+   * @returns {any[] | null}
+   */
+  const bucketItems = (entry, rows) => {
+    const bucket = entry.plan.bucket;
+    const items = [];
+    for (const row of rows) {
+      const start = row[bucket.as] ?? null;
+      if (start === null) return null;
+      /** @type {any} */
+      const item = { [bucket.as]: start };
+      for (const aggregate of bucket.aggregates) {
+        const value = row[aggregate.as] ?? null;
+        if (value === null && aggregate.empty === 'omit') continue;
+        item[aggregate.as] = value === null && aggregate.empty === 'zero' ? 0 : value;
+      }
+      items.push(item);
+    }
+    return items;
+  };
+
+  /** How many ITEMS an engine result carries (its own shape rule). */
+  const itemCount = (answer) => (answer === undefined ? 0
+    : Array.isArray(answer) ? answer.length : 1);
+
+  /**
+   * A native bucket met a group with no instant. The kernel refuses
+   * such a row, and SQL cannot, so the whole question goes back to the
+   * engine over the whole collection — the same diversion a k-nearest
+   * probe of the wrong width takes, and counted the same way.
+   */
+  const divertBucket = (entry, document, externals) => {
+    seriesStats.diverted++;
+    return chain(fullScanOf(entry), (statement) =>
+      chain(statement.all(fullScanParams(entry)), (rows) => {
+        const docs = rowsToDocs(checkRowBound(entry, rows));
+        const answer = setResidualOf(entry, document)(docs, externals);
+        countSeries(entry, 2, docs.length, itemCount(answer));
+        return answer;
+      }));
+  };
+
+  /** Record one actual execution against the entry and the store. */
+  const countSeries = (entry, statements, candidates, results) => {
+    if (entry.planned.series === null) return;
+    seriesStats.queries++;
+    seriesStats.statements += statements;
+    seriesStats.candidates += candidates;
+    seriesStats.results += results;
+    entry.seriesCounts = { statements, candidates, results };
+  };
+
   /**
    * The documents of the given row identities, in identity order,
    * through the dialect's by-identities statement — batched, and each
@@ -461,6 +594,12 @@ export function createQueryEngine(context) {
    */
   const candidatesOf = (entry, externals, diverted) => {
     if (diverted) {
+      // a diversion IS a full-table scan; the plan-shape check above
+      // only ever saw the native statement
+      if (entry.needsScanCheck) {
+        throw profileRefusal(`the profile refuses a full-table scan of '${collection.name}' `
+          + '(a bound external the database cannot take diverted the call to the whole collection)');
+      }
       if (entry.planned.mode === 'knn') knnStats.diverted++;
       return chain(fullScanOf(entry), (statement) =>
         chain(statement.all(fullScanParams(entry)), (rows) =>
@@ -512,8 +651,11 @@ export function createQueryEngine(context) {
         // the k-nearest cut — and the full document over them, which
         // re-applies its own predicates and ordering (idempotent
         // narrowing: the fetch decided nothing)
-        return chain(candidatesOf(entry, externals, diverted), (docs) =>
-          setResidualOf(entry, document)(docs, externals));
+        return chain(candidatesOf(entry, externals, diverted), (docs) => {
+          const answer = setResidualOf(entry, document)(docs, externals);
+          countSeries(entry, 1, docs.length, itemCount(answer));
+          return answer;
+        });
       }
       if (entry.planned.mode === 'row') {
         return chain(statementOf(entry), (statement) =>
@@ -521,16 +663,27 @@ export function createQueryEngine(context) {
             const items = [];
             for (const row of checkRowBound(entry, rows))
               items.push(...entry.rowResidual(JSON.parse(row.doc), externals));
-            return sequenceResult(items);
+            return answerOf(entry, items);
           }));
       }
       return chain(statementOf(entry), (statement) => {
         if (entry.plan.aggregate !== null) {
           return chain(statement.get(bindParams(entry, externals)),
-            (row) => aggregateResult(entry, row));
+            (row) => wrapValue(entry, aggregateResult(entry, row)));
+        }
+        if (entry.plan.bucket !== null) {
+          return chain(statement.all(bindParams(entry, externals)), (rows) => {
+            const items = bucketItems(entry, checkRowBound(entry, rows));
+            if (items === null) return divertBucket(entry, document, externals);
+            countSeries(entry, 1, rows.length, items.length);
+            return answerOf(entry, items);
+          });
         }
-        return chain(statement.all(bindParams(entry, externals)),
-          (rows) => sequenceResult(rowsToDocs(checkRowBound(entry, rows))));
+        return chain(statement.all(bindParams(entry, externals)), (rows) => {
+          const docs = rowsToDocs(checkRowBound(entry, rows));
+          countSeries(entry, 1, docs.length, docs.length);
+          return answerOf(entry, docs);
+        });
       });
     });
   };
@@ -562,6 +715,21 @@ export function createQueryEngine(context) {
       if (done) return Promise.resolve({ done: true, value: undefined });
       if (bufferedAt < buffered.length) return Promise.resolve(nextFromBuffer());
 
+      if (entry.planned.wrapped === true) {
+        // a chain's element window is ONE item — the array — whatever
+        // the plan mode; the cursor hands it over as `execute` answers it
+        if (materialized === null) {
+          materialized = Promise.resolve(chain(execute(document, options), (value) => {
+            buffered = [value];
+            bufferedAt = 0;
+          }));
+        }
+        return materialized.then(() => {
+          if (bufferedAt < buffered.length) return nextFromBuffer();
+          done = true;
+          return { done: true, value: undefined };
+        });
+      }
       if (entry.planned.mode === 'set' || entry.planned.mode === 'knn'
         || mustDivert(entry, externals)) {
         // the barrier: materialize candidates, pack the result items
@@ -571,6 +739,7 @@ export function createQueryEngine(context) {
             chain(candidatesOf(entry, externals, diverted), (docs) => {
               buffered = packedResidualOf(entry, document)(docs, externals);
               bufferedAt = 0;
+              countSeries(entry, 1, docs.length, buffered.length);
             })));
         }
         return materialized.then(() => {
@@ -579,6 +748,33 @@ export function createQueryEngine(context) {
           return { done: true, value: undefined };
         });
       }
+      if (entry.plan.bucket !== null) {
+        // a native bucket is a barrier: the groups are the answer
+        if (materialized === null) {
+          materialized = Promise.resolve(chain(guardScan(entry), () =>
+            chain(statementOf(entry), (statement) =>
+              chain(statement.all(bindParams(entry, externals)), (rows) => {
+                const items = bucketItems(entry, checkRowBound(entry, rows));
+                if (items === null) {
+                  const answer = divertBucket(entry, document, externals);
+                  return chain(answer, (value) => {
+                    buffered = value === undefined ? []
+                      : Array.isArray(value) ? value : [value];
+                    bufferedAt = 0;
+                  });
+                }
+                countSeries(entry, 1, rows.length, items.length);
+                buffered = items;
+                bufferedAt = 0;
+                return null;
+              }))));
+        }
+        return materialized.then(() => {
+          if (bufferedAt < buffered.length) return nextFromBuffer();
+          done = true;
+          return { done: true, value: undefined };
+        });
+      }
       if (entry.plan.aggregate !== null) {
         // a native aggregate yields exactly one item
         if (materialized === null) {
@@ -639,7 +835,9 @@ export function createQueryEngine(context) {
    * The explanation record: the engine explain shape plus the pushdown
    * facts. `estimatedRows` is deliberately ABSENT — the capability
    * slot is empty on SQLite and no number is fabricated; the
-   * database's own plan prose rides in `scanNarrative` instead.
+   * database's own plan prose rides in `scanNarrative` instead. So is
+   * every count in `series`: they are the LAST ACTUAL execution's, and
+   * `null` until this document has run once.
    * @param {any} document
    * @param {{ externals?: any, strict?: boolean }} [options]
    */
@@ -668,6 +866,12 @@ export function createQueryEngine(context) {
       if (term.ref.column !== null) touchedColumns.add(term.ref.column);
     }
     if (entry.plan.aggregate?.ref?.column) touchedColumns.add(entry.plan.aggregate.ref.column);
+    if (entry.plan.bucket !== null) {
+      if (entry.plan.bucket.ref.column) touchedColumns.add(entry.plan.bucket.ref.column);
+      for (const aggregate of entry.plan.bucket.aggregates) {
+        if (aggregate.ref?.column) touchedColumns.add(aggregate.ref.column);
+      }
+    }
     const indexes = [
       ...physicalPlan.expected.indexes
         .filter((index) => index.columns.some((column) => touchedColumns.has(column)))
@@ -689,11 +893,14 @@ export function createQueryEngine(context) {
     return chain(connection.prepare(dialect.explainQuery(entry.sql)), (statement) =>
       chain(statement.all(eqpParams), (rows) => ({
         mode: entry.planned.mode,
+        // a chain's element window (`[<phrase>]`): the phrase planned as
+        // if bare, its rows answered as the one array item
+        wrapped: entry.planned.wrapped === true,
         externals: [...entry.externalNames],
         operators: [...entry.dependencies.operators],
         functions: [...entry.dependencies.functions],
         collations: [...entry.dependencies.collations],
-        limits: entry.limits,
+        limits: entry.residualLimits ?? entry.limits,
         sql: entry.sql,
         params,
         indexes,
@@ -718,16 +925,27 @@ export function createQueryEngine(context) {
           ? entry.planned.reasons.map((r) => ({ operator: r.construct, reason: r.reason }))
           : [],
         udfs: [...entry.planned.udfs],
+        // the temporal record: what the document asked, which declared
+        // index the fetch seeks through, and which kernel finished it.
+        // The counts are the LAST ACTUAL execution's — `null` before
+        // this document has run — because an estimate mislabelled as a
+        // count is exactly the thing an honest explain may not print
+        series: entry.planned.series === null ? null : {
+          ...entry.planned.series,
+          counts: entry.seriesCounts === null ? null : { ...entry.seriesCounts },
+        },
         scanNarrative: rows.map((row) => String(row.detail)).join('; '),
       })));
   };
 
-  return { execute, query, explain, shape, stats: () => ({ knn: { ...knnStats } }) };
+  return { execute, query, explain, shape,
+    stats: () => ({ knn: { ...knnStats }, series: { ...seriesStats } }) };
 }
 
 // ————— The entity query surface (the second document kind) —————
 
 import { mergeEntityRow, parseGraphRow } from './graph.js';
+import { relationTables } from './model.js';
 
 /** The default include depth bound (D14: printed, never silent). */
 export const INCLUDE_DEPTH_DEFAULT = 3;
@@ -745,9 +963,14 @@ export const INCLUDE_DEPTH_DEFAULT = 3;
 export function createEntityQueryEngine(context) {
   const { connection, entities, mapping, state } = context;
   const operators = state.operators ?? null;
+  const zoneProvider = state.zoneProvider ?? null;
   const dialect = connection.dialect;
   const q = dialect.quoteIdentifier;
   const physicalOf = (name) => ({ table: mapping.entities[name].table });
+  // the relation tables of every root this engine serves (§10.1): the
+  // engine is the scope every entity set of the store shares, so a
+  // producer holding one set can follow a hop into another root
+  const relations = relationTables(entities);
 
   const entryFor = (document, pushdown) => {
     const key = ['E', document, dialect.name, pushdown];
@@ -758,6 +981,14 @@ export function createEntityQueryEngine(context) {
     }
     state.counters.misses++;
     let planned = planEntityQuery(document, entities, mapping, operators);
+    if (planned.referenced.length === 0) {
+      // `$[*]` over the entity MAP answered the rows of every entity,
+      // mixed, and explain() named no table read; the root is the map
+      // of entity arrays, and a query ranges over one of them by name
+      throw new DbCompileError('JD0033',
+        'an entity query ranges over a declared entity array ($.<Entity>[*]); this '
+        + 'document names none, so it has no rows to answer', '/entities');
+    }
     if (!pushdown) {
       planned = { ...planned, mode: 'set', plan: null,
         reasons: [{ construct: 'pushdown', reason: 'disabled by the harness switch' }] };
@@ -810,7 +1041,7 @@ export function createEntityQueryEngine(context) {
 
   const runResidual = (entry, document, externals) => {
     if (entry.setResidual === null)
-      entry.setResidual = compileSetResidual(document, undefined, operators);
+      entry.setResidual = compileSetResidual(document, undefined, operators, zoneProvider);
     return chain(fetchRoot(entry), (root) => entry.setResidual(root, externals));
   };
 
@@ -837,11 +1068,11 @@ export function createEntityQueryEngine(context) {
     if (entry.statement === null) entry.statement = connection.prepare(entry.sql);
     return chain(entry.statement, (statement) => {
       if (entry.planned.plan.aggregate === 'count')
-        return chain(statement.get(params), (row) => row?.value ?? 0);
+        return chain(statement.get(params), (row) => wrapValue(entry, row?.value ?? 0));
       return chain(statement.all(params), (rows) => {
         const retEntity = entry.planned.plan.bindings
           .find((binding) => binding.name === entry.planned.plan.ret).entity;
-        return sequenceResult(rows.map((row) =>
+        return answerOf(entry, rows.map((row) =>
           mergeEntityRow(mapping.entities[retEntity], row, '__doc')));
       });
     });
@@ -852,6 +1083,7 @@ export function createEntityQueryEngine(context) {
     const entry = entryFor(document, pushdown);
     const base = {
       mode: entry.planned.mode,
+      wrapped: entry.planned.wrapped === true,
       referenced: [...entry.planned.referenced],
       reasons: entry.planned.reasons,
       sql: entry.sql,
@@ -869,7 +1101,7 @@ export function createEntityQueryEngine(context) {
       })));
   };
 
-  return { execute, explain };
+  return { execute, explain, relations };
 }
 
 /**
@@ -899,6 +1131,11 @@ export function createLoadEngine(context, entityName) {
   const refuse = (reason, path) => new DbCompileError('JD0032',
     `${reason} (include path: ${path.join('.') || '<root>'})`,
     entities.get(entityName)?.docPath);
+  const isWindowBound = (value) => Number.isSafeInteger(value) && value >= 0;
+  /** An include's window inside its subquery: LIMIT, and OFFSET for a
+   * `skip` — per parent row, since the subquery is correlated (§10.4). */
+  const windowClause = (child) => (child.take !== undefined || (child.skip !== undefined && child.skip > 0)
+    ? ` ${dialect.limitClause(child.take ?? null, child.skip)}` : '');
 
   /** Compile a where EXPRESSION over `$it` against one entity. */
   const compileWhere = (expression, entity, path) => {
@@ -969,6 +1206,7 @@ export function createLoadEngine(context, entityName) {
       where: spec?.where !== undefined ? compileWhere(spec.where, entity, path) : null,
       order: spec?.orderBy !== undefined ? compileOrder(spec.orderBy, entity, path) : null,
       take: spec?.take,
+      skip: spec?.skip,
       includes: [],
     };
     const includeSpec = spec?.include;
@@ -984,6 +1222,26 @@ export function createLoadEngine(context, entityName) {
           [...path, relationName]);
       }
       const childSpec = includeSpec[relationName] === true ? {} : includeSpec[relationName];
+      if (childSpec.count === true) {
+        // a count counts EVERY related row; a where/take beside it was
+        // dropped without a word, and the number answered was the total
+        const dropped = ['where', 'orderBy', 'take', 'skip', 'include', 'after']
+          .filter((member) => childSpec[member] !== undefined);
+        if (dropped.length > 0) {
+          throw refuse(`count: true counts every related row and takes no ${dropped.join('/')} — `
+            + 'load the rows to count a subset', [...path, relationName]);
+        }
+      }
+      for (const member of ['take', 'skip']) {
+        if (childSpec[member] !== undefined && !isWindowBound(childSpec[member]))
+          throw refuse(`${member} must be a non-negative integer`, [...path, relationName]);
+      }
+      // a keyset cursor is one position in ONE ordered set; an include is
+      // a set per parent, so it windows with skip/take and never seeks
+      if (childSpec.after !== undefined) {
+        throw refuse("'after' (keyset pagination) paginates the root — an include windows with skip and take",
+          [...path, relationName]);
+      }
       const childName = relation.to;
       const include = {
         name: relationName,
@@ -1037,6 +1295,17 @@ export function createLoadEngine(context, entityName) {
     const parentKey = parentNode.entityMapping.keys[0];
     if (include.count === true) {
       const childTable = mapping.entities[relation.to].table;
+      if (relation.kind === 'manyToMany') {
+        const join = mapping.joinTables[relation.joinTable];
+        const own = join.left.entity === parentNode.entity.name ? join.left : join.right;
+        return `(SELECT COUNT(*) FROM ${q(relation.joinTable)} AS ${q(childAlias)} `
+          + `WHERE ${q(childAlias)}.${q(own.column)} = ${q(parentAlias)}.${q(parentKey)})`;
+      }
+      if (relation.kind === 'oneToOne') {
+        const childKey = mapping.entities[relation.to].keys[0];
+        return `(SELECT COUNT(*) FROM ${q(childTable)} AS ${q(childAlias)} `
+          + `WHERE ${q(childAlias)}.${q(childKey)} = ${q(parentAlias)}.${q(relation.via)})`;
+      }
       return `(SELECT COUNT(*) FROM ${q(childTable)} AS ${q(childAlias)} `
         + `WHERE ${q(childAlias)}.${q(relation.via)} = ${q(parentAlias)}.${q(parentKey)})`;
     }
@@ -1071,10 +1340,10 @@ export function createLoadEngine(context, entityName) {
         + (child.where !== null
           ? ` AND ${emitters.emitPred(rendered.aliasSql, rendered.docSql, child.where)}` : '')
         + ` ORDER BY ${orderSql.join(', ')}`
-        + (child.take !== undefined ? ` ${dialect.limitClause(child.take, undefined)}` : '')
+        + windowClause(child)
       : `SELECT ${rendered.aliasSql}.* FROM ${q(childTable)} AS ${q(childAlias)} `
         + `WHERE ${conditions.join(' AND ')} ORDER BY ${orderSql.join(', ')}`
-        + (child.take !== undefined ? ` ${dialect.limitClause(child.take, undefined)}` : '');
+        + windowClause(child);
     if (relation.kind === 'oneToOne') {
       return `(SELECT json_object(${rendered.projection()}) FROM `
         + `(${inner} ${dialect.limitClause(1, undefined)}) AS ${q(childAlias)})`;
@@ -1101,6 +1370,11 @@ export function createLoadEngine(context, entityName) {
     };
     const emitters = createEntityPredicateEmitters(dialect, param);
     const maxDepth = spec?.maxDepth ?? INCLUDE_DEPTH_DEFAULT;
+    for (const member of ['take', 'skip']) {
+      // interpolated into LIMIT/OFFSET as written: a string ran as SQL
+      if (spec?.[member] !== undefined && !isWindowBound(spec[member]))
+        throw refuse(`${member} must be a non-negative integer`, []);
+    }
     const tree = buildTree(entityName, spec ?? {}, 0, maxDepth, [], new Set());
     const rendered = render(tree, 'r', param, emitters);
 

package/src/residual.js

@@ -36,16 +36,22 @@ import { compileJsonQuery } from '@jarenjs/json/query';
  * @param {{ functions?: any, extensions?: any } | null} [operators]
  * @returns {any}
  */
-function residualOptions(limits, operators) {
+function residualOptions(limits, operators, zoneProvider) {
   const functions = operators?.functions;
   const extensions = operators?.extensions;
-  if (limits === undefined && functions === undefined && extensions === undefined)
+  const clock = zoneProvider ?? null;
+  if (limits === undefined && functions === undefined && extensions === undefined
+    && clock === null)
     return undefined;
   /** @type {any} */
   const options = {};
   if (limits !== undefined) options.limits = limits;
   if (functions !== undefined) options.functions = functions;
   if (extensions !== undefined) options.extensions = extensions;
+  // D7's injected clock: without it a named zone is a compile refusal,
+  // which is what the language wants — being right for eight months of
+  // the year is exactly what a silent UTC fallback would be
+  if (clock !== null) options.zoneProvider = clock;
   return options;
 }
 
@@ -57,10 +63,12 @@ function residualOptions(limits, operators) {
  * @param {any} [limits]
  * @param {{ functions?: any, extensions?: any } | null} [operators] -
  *   the store's registered operators, so the residual can evaluate them
+ * @param {any} [zoneProvider] - D7's injected clock, so a calendar
+ *   ladder on a named zone compiles rather than being refused
  * @returns {(candidates: any[], externals: any) => any}
  */
-export function compileSetResidual(document, limits, operators) {
-  const compiled = compileJsonQuery(document, residualOptions(limits, operators));
+export function compileSetResidual(document, limits, operators, zoneProvider) {
+  const compiled = compileJsonQuery(document, residualOptions(limits, operators, zoneProvider));
   return (candidates, externals) => compiled(candidates, externals);
 }
 
@@ -73,10 +81,11 @@ export function compileSetResidual(document, limits, operators) {
  *   the only place that knows the name.
  * @param {any} [limits]
  * @param {{ functions?: any, extensions?: any } | null} [operators]
+ * @param {any} [zoneProvider] - D7's injected clock
  * @returns {(row: any, externals: any) => any[]} the row's items
  */
-export function compileRowResidual(rowDocument, limits, operators) {
-  const compiled = compileJsonQuery(rowDocument, residualOptions(limits, operators));
+export function compileRowResidual(rowDocument, limits, operators, zoneProvider) {
+  const compiled = compileJsonQuery(rowDocument, residualOptions(limits, operators, zoneProvider));
   return (row, externals) => {
     const packed = compiled([row], externals);
     // one binding → exactly one packed array of that row's items