@jarenjs/db 0.72.3 → 0.75.0

package/src/plan.js

@@ -99,7 +99,7 @@ const PREDICATE_REASONS = {
   negatedPrefilter: 'a negated predicate cannot ride an implied pre-filter '
     + '(negating a superset drops rows)',
   existence: 'existence tests translate only over a singular member path on the binding',
-  joinTerritory: 'comparisons where both sides are paths are join territory',
+  joinTerritory: 'path comparisons require the same non-null numeric or string family',
   operands: 'comparisons translate only between a singular member path and a literal or external',
   compoundLiteral: 'array and object literals have no guarded native comparison form',
   stringSubject: 'string operators translate only over schema-typed string paths '
@@ -130,8 +130,8 @@ const PLAN_REASONS = {
   countProjection: 'count translates only over the bare binding or one member path '
     + '(a projected return can change the item count)',
   groupedAggregate: 'an aggregate over a grouped phrase folds its groups, which the engine does',
-  windowedGroup: 'a window over the GROUPS is engine work: the plan groups whole, '
-    + 'and a LIMIT over the groups would cut a different set',
+  distinctProjection: 'distinct translates over one typed scalar member path, unordered or ordered by that same path',
+  windowedGroup: 'a window over groups whose return can omit an item needs the engine cardinality',
   aggregatePath: 'aggregates translate only over a singular schema-typed path '
     + '(the engine ERRORS on non-conforming operands)',
 };
@@ -756,7 +756,8 @@ function planDistanceBound(node, itSlot, shape) {
   const distanceNode = upperOnLeft ? node.args[0] : node.args[1];
   const radiusNode = upperOnLeft ? node.args[1] : node.args[0];
   const radius = constantOf(radiusNode);
-  if (radius === null || typeof radius.value !== 'number')
+  const radiusExternal = radiusNode.kind === 'var' && radiusNode.external === true;
+  if (!radiusExternal && (radius === null || typeof radius.value !== 'number'))
     return { refusal: refusal('$distance', SPATIAL_REASONS.operand) };
 
   let subjectAt = 0;
@@ -769,21 +770,33 @@ function planDistanceBound(node, itSlot, shape) {
 
   const probeNode = distanceNode.args[subjectAt === 0 ? 1 : 0];
   const constant = constantOf(probeNode);
-  // an EXTERNAL centre would need a slot that composes the bound value
-  // with the radius, and the derived slot kind is closed at one axis of
-  // one bound value; such a query diverts to the full scan as before
-  if (constant === null) return { refusal: refusal('$distance', SPATIAL_REASONS.operand) };
-  const at = probePosition(constant.value);
-  if (at === null) return { refusal: refusal('$distance', SPATIAL_REASONS.unbounded) };
-  if (!Number.isFinite(radius.value) || radius.value < 0) {
+  const centreExternal = probeNode.kind === 'var' && probeNode.external === true;
+  if (!centreExternal && constant === null)
+    return { refusal: refusal('$distance', SPATIAL_REASONS.operand) };
+  if (!radiusExternal && (!Number.isFinite(radius.value) || radius.value < 0)) {
     return { refusal: refusal('$distance', SPATIAL_REASONS.radius) };
   }
-  const box = probeCircleBox(at, radius.value);
-  if (box === null) return { refusal: refusal('$distance', SPATIAL_REASONS.pole) };
-  if (box[0] < -180 || box[2] > 180)
-    return { refusal: refusal('$distance', SPATIAL_REASONS.wrapped) };
+  let probe;
+  if (centreExternal || radiusExternal) {
+    // Both inputs belong to one closed derived slot. Bind-time failure
+    // diverts the whole query, preserving the engine's errors and the
+    // candidates on the far side of a pole or the antimeridian.
+    probe = { circle: {
+      centre: centreExternal ? { external: probeNode.name } : { literal: constant.value },
+      radius: radiusExternal ? { external: radiusNode.name } : { literal: radius.value },
+    } };
+  }
+  else {
+    const at = probePosition(constant.value);
+    if (at === null) return { refusal: refusal('$distance', SPATIAL_REASONS.unbounded) };
+    const box = probeCircleBox(at, radius.value);
+    if (box === null) return { refusal: refusal('$distance', SPATIAL_REASONS.pole) };
+    if (box[0] < -180 || box[2] > 180)
+      return { refusal: refusal('$distance', SPATIAL_REASONS.wrapped) };
+    probe = { box };
+  }
 
-  const conjunct = boxConjunct(columns, rtreeTableOf(shape, subject.canonical), { box });
+  const conjunct = boxConjunct(columns, rtreeTableOf(shape, subject.canonical), probe);
   return promotion(conjunct.pred,
     { construct: '$distance', via: conjunct.via, columns: conjunct.columns, exact: false },
     [refusal('$distance', SPATIAL_REASONS.distance)]);
@@ -1305,8 +1318,14 @@ function planPredicate(node, itSlot, shape) {
     const ref = pathRef(left, itSlot, shape);
     const operand = operandOf(right);
     if (ref === null || operand === null) {
-      if (pathRef(left, itSlot, shape) !== null && pathRef(right, itSlot, shape) !== null)
+      const other = pathRef(right, itSlot, shape);
+      if (ref !== null && other !== null) {
+        const family = (item) => isNumericType(item.type) ? 'number' : item.type;
+        if (orderable(ref, shape.schema) && orderable(other, shape.schema)
+          && family(ref) === family(other))
+          return exactly({ p: 'refCmp', op, left: ref, right: other });
         return { refusal: refusal(node.name, PREDICATE_REASONS.joinTerritory) };
+      }
       return { refusal: refusal(node.name, PREDICATE_REASONS.operands) };
     }
     if ('lit' in operand) {
@@ -2057,7 +2076,7 @@ function planSeriesOperator(root, shape) {
  * The rules that make it agree with the engine, each one a refusal
  * rather than an approximation:
  *
- * - a key is a singular schema-typed path that cannot hold `null`, so
+ * - a key is a singular schema-typed scalar path, so
  *   the group SQL forms is the group the engine forms. An ABSENT key is
  *   its own group, and its value comes back with its JSON type beside
  *   it, so the decoder can leave the member out exactly as the object
@@ -2080,7 +2099,7 @@ function planGeneralGrouping(node, itSlot, shape) {
   const keySlot = new Map();
   for (const key of node.groupby.keys) {
     const ref = pathRef(key.expr, itSlot, shape);
-    if (ref === null || ref.type === 'unknown' || admitsNull(shape.schema, ref.segments))
+    if (ref === null || ref.type === 'unknown')
       return null;
     keySlot.set(key.slot, keys.length);
     keys.push({ as: key.name, ref });
@@ -2129,8 +2148,12 @@ function planGeneralGrouping(node, itSlot, shape) {
   };
   const tree = build(node.ret);
   if (tree === null) return null;
-  const order = groupOrder(node.orderby, keySlot);
+  const order = groupOrder(node.orderby, keySlot, build);
   if (order === null) return null;
+  // Group equality accepts null and boolean keys; ordering them raises
+  // JQ2005. SQL ordering must not hide that engine error.
+  if (order !== 'first-seen' && order.some((term) =>
+    term.aggregate === undefined && !orderable(keys[term.index].ref, shape.schema))) return null;
   return { keys, aggregates, tree, order };
 }
 
@@ -2164,21 +2187,32 @@ function groupAggregate(node, itSlot, shape) {
 /**
  * How the groups come out: the engine's order of FIRST APPEARANCE
  * (§6.5) when nothing declares otherwise, else the group-key ordering
- * an `$orderby` asked for. `null` when the ordering names anything but
- * group keys — after a grouping there is nothing else a row can order
- * by that the plan could reproduce.
+ * an `$orderby` asked for. Proven aggregate expressions share the
+ * return's aggregate slots, including aggregates used only to order.
  * @param {any} orderby
  * @param {Map<number, number>} keySlot
- * @returns {'first-seen' | { index: number, desc: boolean, nullsFirst: boolean }[] | null}
+ * @param {(node: any) => any} build
+ * @returns {any}
  */
-function groupOrder(orderby, keySlot) {
+function groupOrder(orderby, keySlot, build) {
   if (orderby === null) return 'first-seen';
   const terms = [];
   for (const spec of orderby.specs) {
     if (spec.collation !== null || spec.collationName !== null) return null;
     const key = spec.key;
-    if (key.kind !== 'var' || key.external === true || !keySlot.has(key.slot)) return null;
-    terms.push({ index: keySlot.get(key.slot), desc: spec.desc === true,
+    let target;
+    if (key.kind === 'var' && key.external !== true && keySlot.has(key.slot))
+      target = { index: keySlot.get(key.slot) };
+    else {
+      // SQL SUM/AVG may accumulate in a different order (SQLite also
+      // compensates rounding). Such a value cannot safely decide group
+      // order. Counts and extrema have no accumulation-order ambiguity.
+      if (!['$count', '$min', '$max'].includes(key.name)) return null;
+      const aggregate = key.kind === 'op' ? build(key) : null;
+      if (aggregate?.p !== 'agg') return null;
+      target = { aggregate: aggregate.index };
+    }
+    terms.push({ ...target, desc: spec.desc === true,
       nullsFirst: (spec.emptyGreatest === true) === (spec.desc === true) });
   }
   return terms;
@@ -2187,16 +2221,14 @@ function groupOrder(orderby, keySlot) {
 /**
  * The projection TREE one `$return` compiles to, or `null` when the
  * shape is not one the plan can rebuild. Object and array constructors,
- * literals and singular member paths compose; anything else — a
- * function call, a conditional, a dynamic member, a reference to the
- * binding itself — refuses the WHOLE projection, because a projection
+ * literals, whole collection bindings and singular member paths compose;
+ * a function call, conditional or dynamic member refuses the WHOLE projection, because a projection
  * that dropped part of what the caller asked for would be a wrong
  * answer, not a partial one.
  *
  * Distinct paths are collected once: a path named twice is one fetched
- * column and two leaves pointing at it. A projection with NO path is
- * refused too — a statement needs a column to select, and a projection
- * of pure literals has nothing the database could contribute.
+ * column and two leaves pointing at it. A constant tree needs only a
+ * row marker from SQL: the selection contributes its cardinality.
  * @param {any} node - the `$return` AST node
  * @param {number} itSlot
  * @param {any} shape
@@ -2210,8 +2242,9 @@ function projectionTree(node, itSlot, shape) {
   const build = (child) => {
     assertDecidedKind(child);
     if (child.kind === 'literal') return { p: 'lit', value: child.value };
-    if (child.kind === 'path') {
-      const ref = pathRef(child, itSlot, shape);
+    if (child.kind === 'path' || isItVar(child, itSlot)) {
+      const ref = isItVar(child, itSlot)
+        ? { segments: [], type: 'unknown', column: null } : pathRef(child, itSlot, shape);
       if (ref === null) return null;
       const canonical = canonicalOf(ref.segments);
       let index = byCanonical.get(canonical);
@@ -2243,7 +2276,7 @@ function projectionTree(node, itSlot, shape) {
     return null;
   };
   const tree = build(node);
-  return tree === null || leaves.length === 0 ? null : { tree, leaves };
+  return tree === null ? null : { tree, leaves };
 }
 
 /**
@@ -2581,10 +2614,16 @@ function planCollectionCore(document, shape, options = undefined) {
   // pushable at all — a SQL fold over zero rows never sees a second
   // operand, and `aggregateSpec` refuses the declaration at open — so
   // the recognizer here reads the phrase and nothing else
+  const distinct = root.kind === 'op' && root.name === '$distinct';
+  if (distinct) {
+    root = root.args[0];
+    rawInner = rawInner?.$distinct;
+    assertDecidedKind(root);
+  }
   let aggregate = null;
   const registeredAggregate = root.kind === 'op' && !AGGREGATES.has(root.name)
     ? (options?.aggregate?.(root.name) ?? null) : null;
-  if (root.kind === 'op' && (AGGREGATES.has(root.name) || registeredAggregate !== null)) {
+  if (!distinct && root.kind === 'op' && (AGGREGATES.has(root.name) || registeredAggregate !== null)) {
     if (windows.length > 0) {
       return {
         analysis, plan: null, mode: 'set',
@@ -2603,7 +2642,7 @@ function planCollectionCore(document, shape, options = undefined) {
   // a document that IS a series operator over the collection: the
   // operand's own conjuncts (and what the frozen spec implies) narrow
   // through the index, and the kernel decides over what comes back
-  if (aggregate === null && root.kind === 'op' && SERIES_ROOT_OPS.includes(root.name)) {
+  if (!distinct && aggregate === null && root.kind === 'op' && SERIES_ROOT_OPS.includes(root.name)) {
     const temporal = planSeriesOperator(root, shape);
     if (temporal !== null) {
       // a peeled `$subsequence` composes as it does everywhere — over a
@@ -2637,6 +2676,29 @@ function planCollectionCore(document, shape, options = undefined) {
   const { plan } = flwor;
   const fullyPushed = flwor.whereFullyPushed && flwor.orderPushed;
 
+  if (distinct) {
+    const ref = flwor.projectedPath;
+    const sameOrder = root.orderby === null || (ref !== null && plan.order !== null
+      && plan.order.every((term) => canonicalOf(term.ref.segments) === canonicalOf(ref.segments)));
+    if (fullyPushed && sameOrder && ref !== null && ref.type !== 'unknown'
+      && flwor.group === null && flwor.bucket === null) {
+      // DISTINCT and GROUP BY share the query language's key relation.
+      // An absent path contributes no item, including under a window.
+      plan.filter = conjoin(plan.filter, { p: 'typeIs', ref, types: [], positive: true });
+      plan.group = { keys: [{ as: 'distinct', ref }], aggregates: [],
+        tree: { p: 'key', index: 0 }, order: root.orderby === null ? 'first-seen'
+          : plan.order.map((term) => ({ index: 0, desc: term.desc,
+            nullsFirst: (term.emptyGreatest === true) === (term.desc === true) })) };
+      plan.order = null;
+      plan.window = windows.length === 0 ? null : composeWindows(windows);
+      return { analysis, plan, mode: 'native', reasons: [], rowReturn: null,
+        udfs: flwor.udfs, prefilters: flwor.prefilters, series: null };
+    }
+    return { analysis, plan: null, mode: 'set',
+      reasons: [refusal('$distinct', PLAN_REASONS.distinctProjection)],
+      rowReturn: null, udfs: [], prefilters: [], series: null };
+  }
+
   if (flwor.knn !== null) {
     // the k-nearest mode: the recognized ordering under a window with
     // a finite limit, composed exactly as pushed windows are. The plan
@@ -2661,6 +2723,14 @@ function planCollectionCore(document, shape, options = undefined) {
         rowReturn: null, udfs: [], prefilters: flwor.prefilters, series: null };
     }
     if (flwor.bucket !== null || flwor.group !== null || flwor.bucketRefusal != null) {
+      if (aggregate.fn === 'count' && flwor.group !== null
+        && ['object', 'array', 'lit'].includes(flwor.group.tree.p)
+        && flwor.group.aggregates.every((entry) => entry.fn === 'rows')) {
+        plan.group = flwor.group;
+        plan.aggregate = { fn: 'count', ref: null };
+        return { analysis, plan, mode: 'native', reasons: [], rowReturn: null,
+          udfs: flwor.udfs, prefilters: flwor.prefilters, series: null };
+      }
       // the phrase's items are its GROUPS; a COUNT(*) over the rows
       // answered the row count for a `$count` of the groups
       return {
@@ -2722,7 +2792,10 @@ function planCollectionCore(document, shape, options = undefined) {
   // the temporal bucket: only over a WHOLE pushed selection, because a
   // conjunct the residual would still apply would arrive after the rows
   // were already summed
-  if (flwor.group !== null && fullyPushed && windows.length === 0 && aggregate === null) {
+  if (flwor.group !== null && fullyPushed && aggregate === null
+    && (windows.length === 0 || ['object', 'array', 'lit'].includes(flwor.group.tree.p)
+      || (flwor.group.tree.p === 'agg'
+        && flwor.group.aggregates[flwor.group.tree.index].empty === 'zero'))) {
     plan.group = flwor.group;
     return { analysis, plan, mode: 'native', reasons: [], rowReturn: null,
       udfs: flwor.udfs, prefilters: flwor.prefilters, series: null };
@@ -2759,7 +2832,13 @@ function planCollectionCore(document, shape, options = undefined) {
 
   if (!groupedResidual && fullyPushed && flwor.projectionNative
     && (windows.length === 0 || plan.window !== null)) {
-    if (flwor.projectedPath !== null) plan.project = { path: flwor.projectedPath };
+    if (flwor.projectedPath !== null) {
+      plan.project = { path: flwor.projectedPath };
+      // A path yields no item for an absent member. Windows count the
+      // projected items, so discard those rows before applying LIMIT.
+      if (windows.length > 0) plan.filter = conjoin(plan.filter,
+        { p: 'typeIs', ref: flwor.projectedPath, types: [], positive: true });
+    }
     else if (flwor.projectedTree !== null) plan.project = flwor.projectedTree;
     return { analysis, plan, mode: 'native', reasons: [], rowReturn: null,
       udfs: flwor.udfs, prefilters: flwor.prefilters,
@@ -2768,7 +2847,7 @@ function planCollectionCore(document, shape, options = undefined) {
 
   // the row residual: everything but the projection pushed
   if (!groupedResidual && fullyPushed && !flwor.projectionNative
-    && (windows.length === 0 || plan.window !== null)) {
+    && windows.length === 0) {
     const rawFlwor = rawInner;
     const name = flwor.itName ?? 'it';
     return {
@@ -2930,9 +3009,8 @@ export function entityPathRef(node, slot, shape) {
  * collection projection composes — objects, arrays, literals and
  * singular member paths — with each leaf carrying the BINDING it reads
  * from, so the statement extracts it from that binding's alias. `null`
- * when the shape is not one the plan can rebuild, and a projection with
- * no path at all is refused for the same reason a collection's is: a
- * statement needs a column to select.
+ * when the shape is not one the plan can rebuild. A constant tree
+ * fetches a row marker, preserving the selection's cardinality.
  * @param {any} node - the `$return` AST node
  * @param {Map<number, any>} byName - binding slot → binding
  * @returns {{ tree: any, leaves: { binding: string, ref: any }[] } | null}
@@ -2979,7 +3057,7 @@ function entityProjectionTree(node, byName) {
     return null;
   };
   const tree = build(node);
-  return tree === null || leaves.length === 0 ? null : { tree, leaves };
+  return tree === null ? null : { tree, leaves };
 }
 
 /**
@@ -3037,6 +3115,10 @@ export function planEntityPredicate(node, slot, shape) {
     if (pred.p === 'and' || pred.p === 'or')
       return { ...pred, items: pred.items.map(reflavor) };
     if (pred.p === 'not') return { ...pred, item: reflavor(pred.item) };
+    if (pred.p === 'refCmp') {
+      const flavor = (ref) => reflavor({ p: 'typeIs', ref, types: [], positive: true }).ref;
+      return { ...pred, left: flavor(pred.left), right: flavor(pred.right) };
+    }
     if (!('ref' in pred) || pred.ref === null) return pred;
     const canonical = canonicalOf(pred.ref.segments);
     const flavored = shape.entityFlavors.get(canonical);
@@ -3155,6 +3237,29 @@ function planEntityQueryCore(document, entities, mapping, operators) {
    * that turns a product into a join. */
   const refinements = [];
   const filters = new Map(bindings.map((binding) => [binding.slot, null]));
+  const scopedFilters = [];
+  // Boolean composition may span bindings once mandatory equijoin
+  // edges establish the candidate tuples. Each leaf still has exactly
+  // one owner and uses that binding's existing total predicate forms.
+  const scopedPredicate = (node) => {
+    if (node.kind === 'op' && (node.name === '$and' || node.name === '$or')) {
+      const items = node.args.map(scopedPredicate);
+      return items.some((item) => item === null) ? null
+        : { p: node.name === '$and' ? 'and' : 'or', items };
+    }
+    if (node.kind === 'op' && node.name === '$not') {
+      const item = scopedPredicate(node.args[0]);
+      return item === null ? null : { p: 'not', item };
+    }
+    const slots = new Set();
+    collectBindingSlots(node, byName, slots);
+    if (slots.size !== 1) return null;
+    const slot = [...slots][0];
+    const binding = byName.get(slot);
+    const outcome = planEntityPredicate(node, slot, binding.shape);
+    return 'refusal' in outcome ? null
+      : { p: 'binding', binding: binding.name, filter: outcome.pred };
+  };
   const reasons = [];
   let whereFullyPushed = true;
   for (const conjunct of conjuncts) {
@@ -3190,6 +3295,8 @@ function planEntityQueryCore(document, entities, mapping, operators) {
     const slots = new Set();
     collectBindingSlots(conjunct, byName, slots);
     if (slots.size !== 1) {
+      const scoped = scopedPredicate(conjunct);
+      if (scoped !== null) { scopedFilters.push(scoped); continue; }
       reasons.push(refusal('$where', ENTITY_REASONS.conjunctBinding));
       whereFullyPushed = false;
       continue;
@@ -3255,11 +3362,17 @@ function planEntityQueryCore(document, entities, mapping, operators) {
   // SHAPE the projection tree rebuilds from the bindings' members
   const retBinding = root.ret.kind === 'var' && root.ret.external !== true
     ? byName.get(root.ret.slot) : undefined;
-  const projection = retBinding === undefined && aggregate === null
+  const projection = retBinding === undefined
     ? entityProjectionTree(root.ret, byName) : null;
   if (retBinding === undefined && projection === null) {
     reasons.push(refusal('$return', ENTITY_REASONS.projection));
   }
+  if (projection?.tree.p === 'leaf' && (aggregate === 'count' || windows.length > 0)) {
+    const leaf = projection.leaves[projection.tree.index];
+    const binding = bindings.find((entry) => entry.name === leaf.binding);
+    filters.set(binding.slot, conjoin(filters.get(binding.slot),
+      { p: 'typeIs', ref: leaf.ref, types: [], positive: true }));
+  }
 
   // ordering over flavored refs of either binding
   let order = null;
@@ -3292,6 +3405,10 @@ function planEntityQueryCore(document, entities, mapping, operators) {
   if (!fullyPushed) {
     return { analysis, mode: 'set', plan: null, referenced, reasons };
   }
+  for (const filter of scopedFilters) {
+    const slot = bindings[0].slot;
+    filters.set(slot, conjoin(filters.get(slot), filter));
+  }
 
   let window = null;
   if (windows.length > 0) {

package/src/query.js

@@ -47,7 +47,7 @@ import {
 } from './residual.js';
 import { createCursor, createSyncCursor, drainPage, utf8Length, PAGE_LIMIT_DEFAULT, rowClassOf } from './cursor.js';
 import { deepFreeze } from '@jarenjs/core/object';
-import { derivedSlotValue, probeBox, probeVector, columnScore } from './derive.js';
+import { derivedSlotValue, probeVector, columnScore } from './derive.js';
 import { cutCandidates, identityBatches } from './knn.js';
 import {
   deterministicFragment, registerFragment, registerAggregateOperator,
@@ -149,7 +149,8 @@ function slotValue(slot, externals, anchors = null) {
     return value === undefined ? undefined : JSON.stringify(value);
   }
   if ('derived' in slot)
-    return derivedSlotValue(slot.derived, externals[slot.derived.external]);
+    return derivedSlotValue(slot.derived, slot.derived.kind === 'bboxAxis'
+      ? externals[slot.derived.external] : externals);
   if ('typed' in slot) {
     // a typed slot is only ever emitted beside the seek that fills it,
     // so a bind that never resolved the seeks is a defect in the
@@ -179,8 +180,14 @@ function externalSlotKinds(slots, rank) {
   const kinds = new Map();
   for (const slot of slots) {
     if ('external' in slot) kinds.set(slot.external, 'plain');
-    else if ('derived' in slot && !kinds.has(slot.derived.external))
-      kinds.set(slot.derived.external, 'derived');
+    else if ('derived' in slot) {
+      const inputs = slot.derived.kind === 'bboxAxis'
+        ? [slot.derived] : [slot.derived.centre, slot.derived.radius];
+      for (const input of inputs) {
+        if ('external' in input && !kinds.has(input.external))
+          kinds.set(input.external, 'derived');
+      }
+    }
   }
   if (rank !== null && 'ext' in rank.probe && !kinds.has(rank.probe.ext))
     kinds.set(rank.probe.ext, 'probe');
@@ -792,7 +799,15 @@ export function createQueryEngine(context) {
   const divertingExternal = (entry, externals) =>
     entry.externalNames.find((name) => {
       const kind = entry.externalSlotKinds.get(name);
-      if (kind === 'derived') return probeBox(externals[name]) === null;
+      const invalidDerived = entry.slots.some((slot) => {
+        if (!('derived' in slot)) return false;
+        const inputs = slot.derived.kind === 'bboxAxis'
+          ? [slot.derived] : [slot.derived.centre, slot.derived.radius];
+        return inputs.some((input) => 'external' in input && input.external === name)
+          && !bindable(slotValue(slot, externals));
+      });
+      if (invalidDerived) return true;
+      if (kind === 'derived') return false;
       // a probe binds when SOME declared width takes it; a width the
       // model does not declare is the diversion it always was
       if (kind === 'probe') return rankAlternativeFor(entry, externals[name]) === null;
@@ -1193,7 +1208,7 @@ export function createQueryEngine(context) {
             return items;
           })) });
     }
-    if (entry.plan.group !== null) {
+    if (entry.plan.group !== null && entry.plan.aggregate === null) {
       // a native grouping is a barrier: the groups are the answer
       return createCursor({ ...classified, signal, deadline, now: state.now, wrap: driverWrap,
         materialize: () => chain(guardScan(entry), () => chain(statementOf(entry), (statement) =>
@@ -1295,6 +1310,10 @@ export function createQueryEngine(context) {
       else if (pred.p === 'bboxRtree') touchedVirtual.add(pred.table);
       else if (pred.p === 'cellIn' || pred.p === 'cellPrefix')
         touchedColumns.add(pred.column);
+      else if (pred.p === 'refCmp') {
+        if (pred.left.column) touchedColumns.add(pred.left.column);
+        if (pred.right.column) touchedColumns.add(pred.right.column);
+      }
       else if ('ref' in pred && pred.ref?.column) touchedColumns.add(pred.ref.column);
     };
     collectColumns(entry.plan.filter);
@@ -1383,7 +1402,10 @@ export function createQueryEngine(context) {
             fn: entry2.fn, path: entry2.ref === null ? null : segmentsOf(entry2.ref) })),
           order: entry.plan.group.order === 'first-seen' ? 'first-seen'
             : entry.plan.group.order.map((term) => ({
-              key: entry.plan.group.keys[term.index].as, desc: term.desc })),
+              ...(term.aggregate === undefined ? { key: entry.plan.group.keys[term.index].as }
+                : { aggregate: entry.plan.group.aggregates[term.aggregate].fn,
+                  path: entry.plan.group.aggregates[term.aggregate].ref?.segments ?? null }),
+              desc: term.desc })),
         },
         // a chain's element window (`[<phrase>]`): the phrase planned as
         // if bare, its rows answered as the one array item
@@ -1856,7 +1878,8 @@ export function createEntityQueryEngine(context) {
     for (const slot of entry.slots) {
       if (bindable(slotValue(slot, externals))) continue;
       const name = 'external' in slot ? slot.external
-        : 'derived' in slot ? slot.derived.external : null;
+        : 'derived' in slot ? (slot.derived.kind === 'bboxAxis' ? slot.derived.external
+          : [slot.derived.centre, slot.derived.radius].find((input) => 'external' in input)?.external) : null;
       return { construct: 'external', reason: BIND_REASONS.external(name, 'root') };
     }
     return null;

package/types/index.d.ts

@@ -978,7 +978,7 @@ export interface LiveEventTime {
 }
 
 export interface LiveMode {
-  readonly strategy: 'rows' | 'window' | 'accumulator' | 'group'
+  readonly strategy: 'rows' | 'window' | 'accumulator' | 'group' | 'distinct'
     | 'bucket' | 'rolling' | 'join' | 'graph' | 'nested-group' | 'rerun';
   readonly mode: 'incremental' | 'rerun';
   /** Present exactly when the strategy is 'rerun': the named reason. */