@jarenjs/db 0.43.3 → 0.46.5

package/src/migrate.js

@@ -39,12 +39,15 @@ import { derivedValue, memberAt, registerDeriveFunctions } from './derive.js';
  * generates them; one that cannot has them written, which is why the
  * planner emits a backfill for the second and not the first.
  * @param {any} connection
- * @returns {{ derived: 'virtual' | 'stored' }}
+ * @returns {{ derived: 'virtual' | 'stored', rtree: boolean }}
  */
 function mappingFor(connection) {
   return {
     derived: connection.capabilities?.deterministicIndexableFunctions === true
       ? 'virtual' : 'stored',
+    // the same reasoning for the R*Tree mapping: a build without the
+    // module plans (and verifies) the B-tree shape
+    rtree: connection.capabilities?.rtree === true,
   };
 }
 
@@ -102,6 +105,7 @@ function deriveStep(collection, plan, columnNames, note) {
       const entry = { name: column.name, derive: column.derive, segments: column.segments };
       if (column.precision !== undefined) entry.precision = column.precision;
       if (column.component !== undefined) entry.component = column.component;
+      if (column.dims !== undefined) entry.dims = column.dims;
       return entry;
     });
   return { kind: 'derive', collection, columns, note };
@@ -121,7 +125,7 @@ function deriveStep(collection, plan, columnNames, note) {
  * @param {any} fromModel
  * @param {any} toModel
  * @param {{ id?: string, dialect?: any,
- *   derived?: 'virtual' | 'stored' }} [options]
+ *   derived?: 'virtual' | 'stored', rtree?: boolean }} [options]
  * @returns {{ migration: any, report: {
  *   renamed: { from: string, to: string }[],
  *   added: string[], removed: string[],
@@ -132,7 +136,7 @@ export function planMigration(fromModel, toModel, options = undefined) {
   const dialect = options?.dialect ?? null;
   if (dialect === null || typeof dialect !== 'object')
     throw new TypeError('planMigration needs { dialect } (the store dialect renders the DDL)');
-  const mapping = { derived: options?.derived ?? 'virtual' };
+  const mapping = { derived: options?.derived ?? 'virtual', rtree: options?.rtree !== false };
   const fromCollections = normalizeModel(fromModel);
   const toCollections = normalizeModel(toModel);
 
@@ -215,6 +219,33 @@ export function planMigration(fromModel, toModel, options = undefined) {
     // database refuses to drop a column under a live index) — then
     // everything runs in dependency order: drop indexes, drop columns,
     // add columns, create indexes
+    // the R*Tree half of the physical shape (MODEL-FORMAT §2.1,
+    // `physical`). Changing it in either direction is a physical change
+    // and needs a migration, not an open-time alteration: the virtual
+    // table and its three triggers leave BEFORE the columns they read
+    // are disturbed, and arrive AFTER them with a backfill — a
+    // generated column arrives populated, an R*Tree does not.
+    //
+    // A virtual table is compared by NAME and not by declared text,
+    // which is where a column and an index are different: the name is
+    // built from the column stem, the module and its column list are
+    // fixed, and the three triggers are built from that same stem — so
+    // under this dialect a table present on both sides cannot differ,
+    // and one whose stem moved has a different name. `verifyShape`
+    // compares the declared text at open, which is the backstop if that
+    // ever stops being true.
+    const fromVirtual = new Map(fromPlan.virtualTables.map((v) => [v.name, v]));
+    const toVirtual = new Map(toPlan.virtualTables.map((v) => [v.name, v]));
+    for (const [virtualName, from] of fromVirtual) {
+      if (toVirtual.has(virtualName)) continue;
+      for (const trigger of from.triggers) {
+        steps.push({ kind: 'ddl', sql: dialect.ddl.dropTrigger(trigger.name),
+          note: `drop sync trigger '${trigger.name}' on '${name}'` });
+      }
+      steps.push({ kind: 'ddl', sql: dialect.ddl.dropVirtualTable(virtualName),
+        note: `drop the R*Tree '${virtualName}' (and its shadow tables) on '${name}'` });
+    }
+
     const disturbedColumns = new Set();
     for (const [columnName, fromColumn] of fromColumns) {
       const target = toColumns.get(columnName);
@@ -271,6 +302,19 @@ export function planMigration(fromModel, toModel, options = undefined) {
         });
       }
     }
+    for (const [virtualName, target] of toVirtual) {
+      if (fromVirtual.has(virtualName)) continue;
+      steps.push({ kind: 'ddl', sql: target.createSql,
+        note: `create the R*Tree '${virtualName}' on '${name}'` });
+      for (const trigger of target.triggers) {
+        steps.push({ kind: 'ddl', sql: trigger.sql,
+          note: `create sync trigger '${trigger.name}' on '${name}'` });
+      }
+      // the triggers fire on WRITES; the rows already stored need the
+      // backfill, and without it a probe silently returns nothing
+      steps.push({ kind: 'sql', sql: target.fillSql,
+        note: `backfill the R*Tree '${virtualName}' from the stored documents` });
+    }
 
     if (canonicalizeJson(fromCollection.schema) !== canonicalizeJson(toCollection.schema)) {
       report.schemaChanged.push(name);
@@ -298,7 +342,7 @@ export function planMigration(fromModel, toModel, options = undefined) {
     }
   }
 
-  for (const [name] of fromCollections) {
+  for (const [name, fromCollection] of fromCollections) {
     if (toCollections.has(name) || consumedOldNames.has(name)) continue;
     report.removed.push(name);
     report.destructive = true;
@@ -309,6 +353,13 @@ export function planMigration(fromModel, toModel, options = undefined) {
         + 'A rename is declared with x-rename on the target collection; without '
         + 'one, this is a drop plus a create.',
     });
+    // DROP TABLE takes the collection's own triggers with it and leaves
+    // the R*Tree — and its three shadow tables — standing. A leftover
+    // virtual table is a stale index a recreated collection would probe
+    for (const virtual of planCollection(name, fromCollection, dialect, mapping).virtualTables) {
+      steps.push({ kind: 'ddl', sql: dialect.ddl.dropVirtualTable(virtual.name),
+        note: `drop the R*Tree '${virtual.name}' that belonged to '${name}'` });
+    }
   }
 
   planEntityChanges(fromModel, toModel, dialect, steps, report);

package/src/plan.js

@@ -11,7 +11,7 @@
  *
  * The outcome of planning one document:
  *
- *   { plan, mode: 'native' | 'row' | 'set', reasons, rowReturn,
+ *   { plan, mode: 'native' | 'row' | 'set' | 'knn', reasons, rowReturn,
  *     prefilters }
  *
  * - `native` — everything translated; the plan alone answers.
@@ -22,6 +22,11 @@
  *   wrapper built anywhere else would have to guess it.
  * - `set`    — the pushed conjuncts narrow candidates; the WHOLE
  *   compiled document runs over the materialized candidates.
+ * - `knn`    — the pushed conjuncts narrow, the vector column CUTS the
+ *   candidates of a k-nearest window (`plan.rank`), and the whole
+ *   compiled document runs over the cut — a set residual whose
+ *   candidate set an ordering, not a predicate, chose (see "The
+ *   k-nearest promotion" below).
  *
  * `reasons` names every construct that forced work off the database,
  * with reason text drawn from the deliberate-residual table.
@@ -42,8 +47,9 @@ import { typeOfPath, isNumericType } from './types.js';
 import { schemaNodeAt } from './ddl.js';
 import {
   BBOX_COMPONENTS, BBOX_INDEX_ORDER, PRECISION_MIN, PRECISION_MAX,
-  probeBox, probePosition, probeCircleBox, cellNeighbourhood,
+  probeBox, probePosition, probeCircleBox, cellNeighbourhood, probeVector,
 } from './derive.js';
+import { KNN_MARGIN } from './knn.js';
 
 /** Comparison operator names → plan ops. */
 const COMPARISONS = new Map([
@@ -368,6 +374,9 @@ const SPATIAL_REASONS = {
     + 'disjuncts this suite\'s box convention does not carry — '
     + 'pushing nothing is correct, pushing a wrong box is not',
   precision: "the cell length must match the derived column's precision",
+  rtreeBox: "the box is stored in an R*Tree, whose coordinates are 32-bit floats rounded "
+    + 'OUTWARD, so the stored box is a superset of the row\'s; the exact box test refines '
+    + 'in the engine',
 };
 
 /**
@@ -416,16 +425,77 @@ function constantOf(node) {
  * @param {number} [precision]
  * @returns {string | { w: string, s: string, e: string, n: string } | null}
  */
+/**
+ * The R\*Tree virtual table a `bbox` column set is realized as, or
+ * `null` when it is realized as four columns under a B-tree — which is
+ * also the answer on a driver whose build carries no R\*Tree module,
+ * because the physical plan already fell back there (MODEL-FORMAT §4).
+ * @param {any} shape
+ * @param {string} canonical
+ * @returns {{ name: string, columns: string[] } | null}
+ */
+function rtreeTableOf(shape, canonical) {
+  const stem = shape.columnByCanonical?.get(`${canonical}|bbox|`);
+  if (stem === undefined) return null;
+  return shape.virtualByStem?.get(stem) ?? null;
+}
+
+/**
+ * The pushed box conjunct for one column set, under whichever physical
+ * mapping the collection declares — the same box either way, because
+ * the implied-conjunct proof is a proof about BOXES and not about SQL.
+ *
+ * Under `'rtree'` it is a `rowid` subquery over the virtual table: a
+ * conjunct on the collection table, so the `FROM` clause, the residual
+ * machinery and `prefilters` are all untouched. A join would be 6 %
+ * faster and would need join support the emitter does not have; a
+ * correlated `EXISTS` defeats the virtual table's index entirely and is
+ * 85x worse than the subquery.
+ * @param {{ w: string, s: string, e: string, n: string }} columns
+ * @param {{ name: string, columns: string[] } | null} virtual
+ * @param {any} probe
+ * @returns {{ pred: any, via: 'columns' | 'rtree', columns: string[],
+ *   inexact: boolean }}
+ */
+function boxConjunct(columns, virtual, probe) {
+  if (virtual === null) {
+    return { pred: { p: 'bboxOverlap', columns, probe },
+      via: 'columns', columns: boxColumnList(columns), inexact: false };
+  }
+  return { pred: { p: 'bboxRtree', table: virtual.name, columns: virtual.columns, probe },
+    via: 'rtree', columns: [...virtual.columns], inexact: true };
+}
+
 function derivedColumnsOf(shape, canonical, derive, precision) {
+  // `precision` is the identity's third component: a geohash column's
+  // precision, a vector column's `dims`
   const stem = shape.columnByCanonical?.get(`${canonical}|${derive}|${precision ?? ''}`);
   if (stem === undefined) return null;
-  if (derive === 'geohash') return stem;
+  if (derive === 'geohash' || derive === 'vector') return stem;
   /** @type {any} */
   const columns = {};
   for (const component of BBOX_COMPONENTS) columns[`${component}`] = `${stem}_${component}`;
   return columns;
 }
 
+/**
+ * The vector columns declared over one canonical path, by width. The
+ * identity key is `<canonical>|vector|<dims>`, so one path may carry
+ * one column per declared width and a probe chooses by its own.
+ * @param {any} shape
+ * @param {string} canonical
+ * @returns {{ column: string, dims: number }[]}
+ */
+function vectorColumnsOf(shape, canonical) {
+  const prefix = `${canonical}|vector|`;
+  const found = [];
+  for (const [key, column] of shape.columnByCanonical ?? []) {
+    if (key.startsWith(prefix))
+      found.push({ column, dims: Number(key.slice(prefix.length)) });
+  }
+  return found;
+}
+
 /**
  * A spatial SUBJECT: a singular member path on the binding that the
  * schema types as geography. Answers the canonical path a derived
@@ -499,11 +569,19 @@ function planBoxPredicate(node, itSlot, shape) {
     if (box === null) return { refusal: refusal(construct, SPATIAL_REASONS.unbounded) };
     probe = { box };
   }
-  const pred = { p: 'bboxOverlap', columns, probe };
-  const exact = construct === '$bbox-intersects';
-  return promotion(pred,
-    { construct, columns: boxColumnList(columns), exact },
-    exact ? [] : [refusal('$within', SPATIAL_REASONS.within)]);
+  const conjunct = boxConjunct(columns, rtreeTableOf(shape, subject.canonical), probe);
+  // `$bbox-intersects` is EXACT over the four columns — they ARE
+  // `B(row)` — and only IMPLIED over an R*Tree, whose 32-bit float
+  // coordinates round outward: the stored box is a superset. No false
+  // negatives either way, which is what D8 needs; but a superset does
+  // not DECIDE, so the exact box test keeps its refinement and
+  // `strict: true` is JD0010 where the column mapping ran native
+  const exact = construct === '$bbox-intersects' && !conjunct.inexact;
+  const refinements = construct === '$bbox-intersects'
+    ? (conjunct.inexact ? [refusal(construct, SPATIAL_REASONS.rtreeBox)] : [])
+    : [refusal('$within', SPATIAL_REASONS.within)];
+  return promotion(conjunct.pred,
+    { construct, via: conjunct.via, columns: conjunct.columns, exact }, refinements);
 }
 
 /**
@@ -555,8 +633,9 @@ function planDistanceBound(node, itSlot, shape) {
   if (box[0] < -180 || box[2] > 180)
     return { refusal: refusal('$distance', SPATIAL_REASONS.wrapped) };
 
-  return promotion({ p: 'bboxOverlap', columns, probe: { box } },
-    { construct: '$distance', columns: boxColumnList(columns), exact: false },
+  const conjunct = boxConjunct(columns, rtreeTableOf(shape, subject.canonical), { box });
+  return promotion(conjunct.pred,
+    { construct: '$distance', via: conjunct.via, columns: conjunct.columns, exact: false },
     [refusal('$distance', SPATIAL_REASONS.distance)]);
 }
 
@@ -617,7 +696,7 @@ function planCellPrefix(node, itSlot, shape) {
     ? { p: 'cellIn', column: derivation.column, cells: [cell] }
     : { p: 'cellPrefix', column: derivation.column, prefix: cell };
   return promotion(pred,
-    { construct: '$starts-with', columns: [derivation.column], exact },
+    { construct: '$starts-with', via: 'columns', columns: [derivation.column], exact },
     exact ? [] : [refusal('$starts-with', SPATIAL_REASONS.prefix)]);
 }
 
@@ -652,7 +731,130 @@ function planCellNeighbourhood(node, itSlot, shape) {
   if (cells.length === 0)
     return { refusal: refusal('$geohash-neighbours', SPATIAL_REASONS.operand) };
   return promotion({ p: 'cellIn', column: derivation.column, cells },
-    { construct: '$geohash-neighbours', columns: [derivation.column], exact: true });
+    { construct: '$geohash-neighbours', via: 'columns', columns: [derivation.column],
+      exact: true });
+}
+
+// ————— The k-nearest promotion: an ORDERING the column pre-filters —————
+//
+// `$orderby` on a `$similarity` key, descending, `$empty: 'least'`,
+// under a `$subsequence` window with a finite limit, over a member a
+// `derive: 'vector'` column stores: the one ordering the planner
+// promotes. Not to SQL — no ORDER BY is emitted, no per-row similarity
+// call, no LIMIT: every SQL spelling of the rank measured slower than
+// fetching the packed column and ranking in the engine, and none of
+// them runs where no function can be registered — but to a CUT. The
+// statement projects (identity, column) under the pushed WHERE; the
+// engine scores every row's column against the probe; the rows whose
+// score is within `KNN_MARGIN` of the `offset + limit`-th best are the
+// candidates. Then the ENGINE decides: the original document — its
+// whole `$orderby` (the similarity key over the raw member, every
+// secondary key, `$empty`), its window, its `$return` — runs as the set
+// residual over exactly those documents.
+//
+// What makes that exact is the implied-conjunct argument, applied to an
+// ordering. The column's score (a dot product over binary32-normalized
+// forms) and the engine's key (the cosine of the raw doubles) differ by
+// at most ~1e-8, measured; with a margin two orders of magnitude wider
+// the engine's top `offset + limit` is a SUBSET of the candidates — a
+// row the engine ranks inside the window that the column left out would
+// need two true cosines to differ by more than the column can mis-order
+// them. Ties at the boundary are included by construction, and the
+// engine breaks them by the document's own secondary keys, which is why
+// no row-identity tie rule exists here: row identity serves the fetch,
+// never the order.
+//
+// Two shapes reach the window's tail that no cut can order: fewer than
+// `offset + limit` rows scored — a small collection, or NULL columns
+// (absent, wrong-width, non-finite members) — so the window reaches the
+// unrankable rows, which `$empty: 'least'` places LAST in the engine's
+// own secondary order. The candidate set is then every row, and the
+// collection is no larger than the window.
+//
+// Preconditions, each a named refusal. The selection must be pushed
+// WHOLE — every `$where` conjunct exact, nothing before it — because a
+// conjunct left to the residual could drop a candidate the cut counted,
+// and an implied one narrows to a superset the residual then shrinks;
+// either could leave the window short. The probe must be a literal
+// vector of the column's width, or an external: what an external
+// carries is the binder's to check at call time, and a bound value that
+// is not a vector of that width DIVERTS the call to the residual, where
+// the engine answers what it answers everywhere (empty keys for another
+// width, its own refusal of a non-array) — never a plan-side error the
+// engine would not raise.
+
+const KNN_REASONS = {
+  rank: 'k-nearest rank is engine work: the vector column cuts the candidates and the engine orders them',
+  direction: 'k-nearest is promoted only descending (higher similarity first)',
+  empties: "k-nearest is promoted only under $empty: 'least' (unrankable rows last, where the cut can reach them)",
+  collation: 'a collation on a similarity key is refused, not approximated',
+  subject: 'the similarity key must compare a singular member path on the binding with a probe',
+  probe: 'the probe must be a literal vector (an array of finite numbers) or an external',
+  selection: 'k-nearest ranks over the column only when the selection is pushed whole (every $where conjunct exact, no $let or $as before it)',
+  window: 'k-nearest needs a window with a finite limit; an unbounded ranking is a full sort in the engine',
+  /** @param {string} path @param {number | null} dims */
+  noColumn: (path, dims) =>
+    `no vector column over ${path}${dims === null ? '' : ` at width ${dims}`}`,
+  /** @param {string} path @param {number} want @param {number[]} have */
+  dims: (path, want, have) =>
+    `the literal probe has ${want} components but the vector column over ${path} is declared at ${have.join(', ')}`,
+  /** @param {string} path */
+  widths: (path) =>
+    `several vector widths are declared over ${path}; an external probe cannot choose one at plan time`,
+};
+
+/**
+ * Recognize the k-nearest ordering, or say why not. `null` when the
+ * first key is not a `$similarity` at all — an ordinary ordering the
+ * caller plans as before. Further key specs are the engine's business
+ * (they order the candidates), so nothing here reads them.
+ * @param {any} orderby - the flwor's orderby node
+ * @param {number} itSlot
+ * @param {any} shape
+ * @param {boolean} selectionPushed - the WHERE pushed whole and exact,
+ *   with nothing before it
+ * @returns {{ rank: { column: string, dims: number,
+ *   probe: { lit: number[] } | { ext: string } } }
+ *   | { refusal: { construct: string, reason: string } } | null}
+ */
+function planKnnOrder(orderby, itSlot, shape, selectionPushed) {
+  const first = orderby.specs[0];
+  const key = first.key;
+  if (key.kind !== 'op' || key.name !== '$similarity') return null;
+  const refuse = (reason) => ({ refusal: refusal('$similarity', reason) });
+  if (first.desc !== true) return refuse(KNN_REASONS.direction);
+  if (first.emptyGreatest === true) return refuse(KNN_REASONS.empties);
+  if (first.collation !== null || first.collationName !== null)
+    return refuse(KNN_REASONS.collation);
+  // the subject may be either operand; the other is the probe
+  let subjectAt = 0;
+  if (memberPath(key.args[0], itSlot) === null && memberPath(key.args[1], itSlot) !== null)
+    subjectAt = 1;
+  const subject = memberPath(key.args[subjectAt], itSlot);
+  if (subject === null) return refuse(KNN_REASONS.subject);
+  const path = `$${subject.canonical}`;
+  const probeNode = key.args[subjectAt === 0 ? 1 : 0];
+  const declared = vectorColumnsOf(shape, subject.canonical);
+
+  if (probeNode.kind === 'var' && probeNode.external === true) {
+    if (declared.length === 0) return refuse(KNN_REASONS.noColumn(path, null));
+    if (declared.length > 1) return refuse(KNN_REASONS.widths(path));
+    if (!selectionPushed) return refuse(KNN_REASONS.selection);
+    return { rank: { column: declared[0].column, dims: declared[0].dims,
+      probe: { ext: probeNode.name } } };
+  }
+  const constant = constantOf(probeNode);
+  if (constant === null || !Array.isArray(constant.value)) return refuse(KNN_REASONS.probe);
+  const dims = constant.value.length;
+  if (probeVector(constant.value, dims) === null) return refuse(KNN_REASONS.probe);
+  const column = derivedColumnsOf(shape, subject.canonical, 'vector', dims);
+  if (column === null) {
+    return refuse(declared.length === 0
+      ? KNN_REASONS.noColumn(path, dims)
+      : KNN_REASONS.dims(path, dims, declared.map((entry) => entry.dims)));
+  }
+  if (!selectionPushed) return refuse(KNN_REASONS.selection);
+  return { rank: { column: /** @type {string} */ (column), dims, probe: { lit: constant.value } } };
 }
 
 /**
@@ -823,7 +1025,10 @@ function planPredicate(node, itSlot, shape) {
  *   reasons: { construct: string, reason: string }[],
  *   whereFullyPushed: boolean, orderPushed: boolean,
  *   projectionNative: boolean, itSlot: number, itName: string | null,
- *   udfs: string[], prefilters: any[] }}
+ *   udfs: string[], prefilters: any[],
+ *   knn: { column: string, dims: number, probe: any } | null }}
+ *   `knn` is the recognized k-nearest ordering, pending the window
+ *   the caller peels; its ordering is then never pushed
  */
 function planFlwor(node, shape, rawFlwor, udfHook) {
   const reasons = [];
@@ -843,7 +1048,7 @@ function planFlwor(node, shape, rawFlwor, udfHook) {
     reasons.push(refusal('$for',
       'only a single plain binding over the whole collection is translated'));
     return { plan, reasons, whereFullyPushed: false, orderPushed: false,
-      projectionNative: false, itSlot: -1, itName: null, udfs: [], prefilters: [] };
+      projectionNative: false, itSlot: -1, itName: null, udfs: [], prefilters: [], knn: null };
   }
   const itSlot = binding.slot;
   // the document's own name for the collection binding. The residual and
@@ -905,9 +1110,19 @@ function planFlwor(node, shape, rawFlwor, udfHook) {
     }
   }
 
-  // ORDER BY: all terms or none — a partially pushed ordering is wrong
+  // ORDER BY: all terms or none — a partially pushed ordering is wrong.
+  // A k-nearest ordering is the third outcome: not pushed, but
+  // recognized for the column to pre-filter (the reason is the
+  // caller's to name once the window is known)
   let orderPushed = false;
-  if (node.orderby !== null) {
+  let knn = null;
+  const ranked = node.orderby === null ? null
+    : planKnnOrder(node.orderby, itSlot, shape, whereFullyPushed && structureClean);
+  if (ranked !== null) {
+    if ('rank' in ranked) knn = ranked.rank;
+    else reasons.push(ranked.refusal);
+  }
+  else if (node.orderby !== null) {
     const terms = [];
     let refused = null;
     for (const spec of node.orderby.specs) {
@@ -953,9 +1168,35 @@ function planFlwor(node, shape, rawFlwor, udfHook) {
     itName,
     udfs,
     prefilters,
+    knn,
   };
 }
 
+/**
+ * Compose peeled `$subsequence` windows into one: the innermost applies
+ * first, so offsets add and each outer limit is cut to what the inner
+ * one left. `null` when nothing was peeled.
+ * @param {{ offset: number, limit: number | null }[]} windows -
+ *   outermost first, as peeled
+ * @returns {{ offset: number, limit: number | null } | null}
+ */
+function composeWindows(windows) {
+  if (windows.length === 0) return null;
+  let offset = 0;
+  let limit = null;
+  for (let i = windows.length - 1; i >= 0; i--) {
+    const w = windows[i];
+    offset += w.offset;
+    if (w.limit !== null) {
+      limit = limit === null ? w.limit : Math.min(Math.max(limit - w.offset, 0), w.limit);
+    }
+    else if (limit !== null) {
+      limit = Math.max(limit - w.offset, 0);
+    }
+  }
+  return { offset, limit };
+}
+
 /**
  * Plan a whole document against one collection.
  * @param {any} document - The raw query document (kept beside the AST
@@ -965,11 +1206,12 @@ function planFlwor(node, shape, rawFlwor, udfHook) {
  * @returns {{
  *   analysis: any,
  *   plan: import('./algebra.js').Plan | null,
- *   mode: 'native' | 'row' | 'set',
+ *   mode: 'native' | 'row' | 'set' | 'knn',
  *   reasons: { construct: string, reason: string }[],
  *   rowReturn: any,
  *   udfs: string[],
- *   prefilters: { construct: string, columns: string[], exact: boolean }[],
+ *   prefilters: { construct: string, via: 'columns' | 'rtree',
+ *     columns: string[], exact: boolean }[],
  * }}
  */
 function planCollectionCore(document, shape, options = undefined) {
@@ -1026,6 +1268,22 @@ function planCollectionCore(document, shape, options = undefined) {
   const { plan } = flwor;
   const fullyPushed = flwor.whereFullyPushed && flwor.orderPushed;
 
+  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
+    // keeps no order and no window — both are the engine's over the
+    // cut — and the reason strict mode names is the rank itself
+    const window = aggregate === null ? composeWindows(windows) : null;
+    if (window !== null && window.limit !== null) {
+      plan.rank = { ...flwor.knn, offset: window.offset, limit: window.limit,
+        margin: KNN_MARGIN };
+      return { analysis, plan, mode: 'knn',
+        reasons: [refusal('$orderby', KNN_REASONS.rank), ...flwor.reasons],
+        rowReturn: null, udfs: flwor.udfs, prefilters: flwor.prefilters };
+    }
+    flwor.reasons.unshift(refusal('$subsequence', KNN_REASONS.window));
+  }
+
   if (aggregate !== null) {
     // aggregates need the WHOLE selection native (their input is the
     // full sequence, not a narrowed candidate set)
@@ -1064,22 +1322,7 @@ function planCollectionCore(document, shape, options = undefined) {
   }
 
   // windows push only onto a fully pushed selection
-  if (windows.length > 0 && fullyPushed) {
-    // innermost window applies first; compose offsets/limits
-    let offset = 0;
-    let limit = null;
-    for (let i = windows.length - 1; i >= 0; i--) {
-      const w = windows[i];
-      offset += w.offset;
-      if (w.limit !== null) {
-        limit = limit === null ? w.limit : Math.min(Math.max(limit - w.offset, 0), w.limit);
-      }
-      else if (limit !== null) {
-        limit = Math.max(limit - w.offset, 0);
-      }
-    }
-    plan.window = { offset, limit };
-  }
+  if (windows.length > 0 && fullyPushed) plan.window = composeWindows(windows);
 
   if (fullyPushed && flwor.projectionNative && (windows.length === 0 || plan.window !== null)) {
     return { analysis, plan, mode: 'native', reasons: [], rowReturn: null,
@@ -1127,11 +1370,12 @@ function planCollectionCore(document, shape, options = undefined) {
  * @returns {{
  *   analysis: any,
  *   plan: import('./algebra.js').Plan | null,
- *   mode: 'native' | 'row' | 'set',
+ *   mode: 'native' | 'row' | 'set' | 'knn',
  *   reasons: { construct: string, reason: string }[],
  *   rowReturn: any,
  *   udfs: string[],
- *   prefilters: { construct: string, columns: string[], exact: boolean }[],
+ *   prefilters: { construct: string, via: 'columns' | 'rtree',
+ *     columns: string[], exact: boolean }[],
  * }}
  */
 export function planQuery(document, shape, options = undefined) {