@jarenjs/db 0.43.3 → 0.46.4

package/src/dialect.js

@@ -34,6 +34,7 @@
  *   capabilities: Record<string, any>,
  *   tableSuffix: string,
  *   docColumnType: string,
+ *   packedVectorType: string,
  *   quoteIdentifier: (s: string) => string,
  *   parameterRef: (i: number, name: string) => string,
  *   stringLiteral: (s: string) => string,
@@ -43,7 +44,7 @@
  *   jsonPathText: (segments: JsonPathSegment[]) => string | null,
  *   jsonExtract: (columnSql: string, pathText: string) => string,
  *   derivedExpression?: (memberSql: string, column: { derive: string,
- *     precision?: number, component?: string }) => string,
+ *     precision?: number, component?: string, dims?: number }) => string,
  *   jsonSet: (exprSql: string, pathText: string, valueSql: string) => string,
  *   jsonRemove: (exprSql: string, pathText: string) => string,
  *   jsonAppend: (exprSql: string, arrayPathText: string, valueSql: string) => string,
@@ -58,6 +59,8 @@
  *   strContains: (valueSql: string, patternSql: string) => string,
  *   orderNulls: (nullsFirst: boolean) => string,
  *   rowIdentity: () => string,
+ *   identityIn: (identitySql: string, paramSqls: string[]) => string,
+ *   rtree?: { module: string, columns: readonly string[] },
  *   explainQuery: (sql: string) => string,
  *   excludedRef: (columnSql: string) => string,
  *   tx: { begin: string, beginImmediate: string, commit: string,
@@ -85,7 +88,9 @@ export function createDialect(spec) {
    * generated column over the document; a DERIVED column is the same
    * shape over a registered deterministic function, except where the
    * driver cannot index one — there the store writes the value and the
-   * column is an ordinary one.
+   * column is an ordinary one. A packed vector column is ALWAYS that
+   * ordinary stored column (its type is `packedVectorType`), on every
+   * driver: it never has an expression to spell.
    * @param {string} docColumn
    * @param {{ name: string, type: string, pathText: string,
    *   expression?: string | null, stored?: boolean }} column
@@ -167,6 +172,104 @@ export function createDialect(spec) {
     dropIndex(name) {
       return `DROP INDEX ${q(name)}`;
     },
+    /**
+     * The second physical realization of a `derive: 'bbox'` column set
+     * (MODEL-FORMAT §2.1, `physical: 'rtree'`): an R\*Tree virtual
+     * table beside the collection, keyed by the collection's row id and
+     * carrying the four box edges as `(minx, maxx, miny, maxy)`.
+     *
+     * The coordinates are 32-bit floats rounded OUTWARD, so the stored
+     * box is a superset of the row's — no false negatives, which is
+     * what an implied conjunct needs, and the reason `$bbox-intersects`
+     * stops being exact under this mapping.
+     * @param {{ name: string }} shape
+     * @returns {string}
+     */
+    createVirtualTable({ name }) {
+      return `CREATE VIRTUAL TABLE ${q(name)} USING ${spec.rtree.module}(`
+        + `${spec.rtree.columns.map(q).join(', ')})`;
+    },
+    /**
+     * @param {string} name
+     * @returns {string}
+     */
+    dropVirtualTable(name) {
+      return `DROP TABLE ${q(name)}`;
+    },
+    /**
+     * @param {string} name
+     * @returns {string}
+     */
+    dropTrigger(name) {
+      return `DROP TRIGGER ${q(name)}`;
+    },
+    /**
+     * Fill an R\*Tree from the documents already stored — the migration
+     * step that turns a `columns` collection into an `rtree` one. The
+     * `IS NOT NULL` is §3.2's rule in SQL: a row with no bounded
+     * position is ABSENT from the index, not at `[0, 0]`.
+     * @param {{ table: string, virtualTable: string,
+     *   edges: { name: string }[] }} shape
+     * @returns {string}
+     */
+    fillVirtualTable({ table, virtualTable, edges }) {
+      const columns = spec.rtree.columns;
+      const sources = [spec.rowIdentity(), ...edges.map((edge) => q(edge.name))];
+      return `INSERT INTO ${q(virtualTable)} (${columns.map(q).join(', ')}) `
+        + `SELECT ${sources.join(', ')} FROM ${q(table)} `
+        + `WHERE ${q(edges[0].name)} IS NOT NULL`;
+    },
+    /**
+     * The three triggers that keep an R\*Tree in sync with its
+     * collection — insert, update, delete — as DECLARED objects of the
+     * collection table.
+     *
+     * Declared, and not a second write path in JavaScript: a trigger is
+     * inside the writing transaction by construction (SQLite cannot
+     * separate them), no write path can bypass it (`insert`,
+     * `insertAllocated`, `upsert`, a translated patch, the patch
+     * fallback, a delete and a migration backfill all fire it), and it
+     * belongs to the collection table, so the existing declared-text
+     * drift check sees it for free.
+     *
+     * The body reads the DERIVED COLUMNS through `NEW` rather than
+     * restating the box expression, so the columns stay the box's one
+     * definition — and that text works unchanged on the stored-column
+     * branch, where those columns are ordinary ones.
+     *
+     * The `IS NOT NULL` guard is load-bearing: an R\*Tree coerces a
+     * `NULL` coordinate to `0.0` without complaint, so without it every
+     * unbounded document would land on Null Island instead of being
+     * absent (MODEL-FORMAT §3.2).
+     * @param {{ table: string, virtualTable: string, prefix: string,
+     *   edges: { name: string }[] }} shape - `edges` are the four
+     *   derived columns in `(w, e, s, n)` order, which is the order the
+     *   virtual table's `(minx, maxx, miny, maxy)` carry
+     * @returns {{ name: string, sql: string }[]}
+     */
+    createSyncTriggers({ table, virtualTable, prefix, edges }) {
+      const rid = spec.rowIdentity();
+      const target = `${q(virtualTable)} (${spec.rtree.columns.map(q).join(', ')})`;
+      const guard = `${q(edges[0].name)} IS NOT NULL`;
+      const values = (row) => [`${row}.${rid}`,
+        ...edges.map((edge) => `${row}.${q(edge.name)}`)].join(', ');
+      return [
+        { name: `${prefix}_ai`,
+          sql: `CREATE TRIGGER ${q(`${prefix}_ai`)} AFTER INSERT ON ${q(table)} `
+            + `WHEN NEW.${guard} BEGIN `
+            + `INSERT INTO ${target} VALUES (${values('NEW')}); END` },
+        // one trigger, not two: the old id leaves and the new box
+        // arrives only when it exists, so a document that loses its
+        // geometry leaves the index rather than keeping a stale box
+        { name: `${prefix}_au`,
+          sql: `CREATE TRIGGER ${q(`${prefix}_au`)} AFTER UPDATE ON ${q(table)} BEGIN `
+            + `DELETE FROM ${q(virtualTable)} WHERE ${q(spec.rtree.columns[0])} = OLD.${rid}; `
+            + `INSERT INTO ${target} SELECT ${values('NEW')} WHERE NEW.${guard}; END` },
+        { name: `${prefix}_ad`,
+          sql: `CREATE TRIGGER ${q(`${prefix}_ad`)} AFTER DELETE ON ${q(table)} BEGIN `
+            + `DELETE FROM ${q(virtualTable)} WHERE ${q(spec.rtree.columns[0])} = OLD.${rid}; END` },
+      ];
+    },
     /**
      * @param {string} table
      * @returns {string}
@@ -286,6 +389,25 @@ export function createDialect(spec) {
     del({ table, keyColumn }) {
       return `DELETE FROM ${q(table)} WHERE ${q(keyColumn)} = ${p(1, 'key')}`;
     },
+    /**
+     * The documents of a list of row identities, in identity order —
+     * the fetch of a k-nearest plan's candidates after the engine's
+     * cut. `count` placeholders; a caller with fewer identities binds
+     * `null` for the rest, which the membership test matches to no row.
+     * Identity order is the collection's own order, so the engine's
+     * stable sort over the fetched documents sees what it would have
+     * seen over the whole collection.
+     * @param {{ table: string, docColumn: string }} s
+     * @param {number} count
+     * @returns {string}
+     */
+    selectByIdentities({ table, docColumn }, count) {
+      const rid = spec.rowIdentity();
+      const placeholders = [];
+      for (let i = 1; i <= count; i++) placeholders.push(p(i, 'rid'));
+      return `SELECT ${spec.jsonText(q(docColumn))} AS ${q('doc')} FROM ${q(table)} `
+        + `WHERE ${spec.identityIn(rid, placeholders)} ORDER BY ${rid}`;
+    },
     /**
      * Rewrite the document column through a JSON-set expression chain
      * (the translated-patch path) or a bound parameter (the fallback).
@@ -316,6 +438,9 @@ export function createDialect(spec) {
     name: spec.name,
     capabilities: Object.freeze({ ...spec.capabilities }),
     docColumnType: spec.docColumnType,
+    // the declared type of a `derive: 'vector'` column — the bytes of
+    // the packed form, spelled by the dialect like every other type
+    packedVectorType: spec.packedVectorType,
     quoteIdentifier: q,
     parameterRef: p,
     stringLiteral: spec.stringLiteral,
@@ -349,6 +474,13 @@ export function createDialect(spec) {
     strContains: spec.strContains,
     orderNulls: spec.orderNulls,
     rowIdentity: spec.rowIdentity,
+    /**
+     * The R\*Tree spelling: the module name and the virtual table's own
+     * column list, in `(id, minx, maxx, miny, maxy)` order. Read only
+     * where a `physical: 'rtree'` column set is planned, so a spelling
+     * spec that omits it simply cannot carry that mapping.
+     */
+    rtree: Object.freeze({ ...spec.rtree }),
     explainQuery: spec.explainQuery,
     excludedRef: spec.excludedRef,
     epochFromRfc3339: spec.epochFromRfc3339,

package/src/dialects/sqlite.js

@@ -90,6 +90,10 @@ export const sqliteDialect = createDialect({
   epochFromRfc3339: (valueSql) =>
     `CAST(round((julianday(${valueSql}) - 2440587.5) * 86400000.0) AS INTEGER)`,
   docColumnType: 'BLOB',
+  // a `derive: 'vector'` column holds the packed little-endian binary32
+  // form (`4·dims` bytes); it is a stored column on every driver, so
+  // this is the whole of its SQL
+  packedVectorType: 'BLOB',
   quoteIdentifier,
   parameterRef: () => '?',
   stringLiteral,
@@ -105,10 +109,24 @@ export const sqliteDialect = createDialect({
   // the deterministic function the store registers at open. The
   // precision is a LITERAL, not a parameter — a generated column's
   // expression takes none — which is also what makes two precisions
-  // over one path two different columns by declared text.
-  derivedExpression: (memberSql, column) => (column.derive === 'geohash'
-    ? `jaren_geohash(${memberSql}, ${Math.trunc(Number(column.precision))})`
-    : `jaren_bbox_${column.component}(${memberSql})`),
+  // over one path two different columns by declared text. Exhaustive
+  // over the kind: a vector column is stored, never generated, so
+  // asking for its expression is a planner defect, and an unknown kind
+  // is refused rather than spelled as `jaren_bbox_undefined(...)`
+  derivedExpression: (memberSql, column) => {
+    switch (column.derive) {
+      case 'geohash':
+        return `jaren_geohash(${memberSql}, ${Math.trunc(Number(column.precision))})`;
+      case 'bbox':
+        return `jaren_bbox_${column.component}(${memberSql})`;
+      case 'vector':
+        throw new TypeError(
+          "sqlite dialect: a derive: 'vector' column is stored on every driver and has no generated expression");
+      default:
+        throw new TypeError(
+          `sqlite dialect: no generated-column expression for derive kind '${column.derive}'`);
+    }
+  },
   jsonSet: (exprSql, pathText, valueSql) =>
     `jsonb_set(${exprSql}, ${stringLiteral(pathText)}, ${valueSql})`,
   jsonRemove: (exprSql, pathText) =>
@@ -135,6 +153,17 @@ export const sqliteDialect = createDialect({
   strContains: (valueSql, patternSql) => `instr(${valueSql}, ${patternSql}) > 0`,
   orderNulls: (nullsFirst) => (nullsFirst ? ' NULLS FIRST' : ' NULLS LAST'),
   rowIdentity: () => '"rowid"',
+  // membership of the row identity in a bound list — the fetch of a
+  // k-nearest plan's candidates. `IN` over the rowid is a primary-key
+  // lookup per value; a NULL in the list matches no row, which is what
+  // lets a caller pad a batch
+  identityIn: (identitySql, paramSqls) => `${identitySql} IN (${paramSqls.join(', ')})`,
+  // the R*Tree module and the shape this store gives it: the row id
+  // and the four box edges in (minx, maxx, miny, maxy) order, which is
+  // the (w, e, s, n) a bbox index covers its columns in. The three
+  // shadow tables SQLite creates beside a virtual table are its own
+  // storage — deterministic from the name, and dropped with it.
+  rtree: { module: 'rtree', columns: ['id', 'minx', 'maxx', 'miny', 'maxy'] },
   explainQuery: (sql) => `EXPLAIN QUERY PLAN ${sql}`,
   excludedRef: (columnSql) => `excluded.${columnSql}`,
   tx: {

package/src/emit.js

@@ -228,6 +228,23 @@ export function emitPlan(plan, dialect, physical) {
           + ` AND ${q(c.e)} >= ${edge('w')}`
           + ` AND ${q(c.s)} <= ${edge('n')} AND ${q(c.n)} >= ${edge('s')})`;
       }
+      case 'bboxRtree': {
+        // The same box test, over the same box, in the shape a
+        // `physical: 'rtree'` column set stores it: a LIST subquery over
+        // the virtual table, which is a conjunct on the collection table
+        // — so the FROM clause, the residual machinery and `prefilters`
+        // are all untouched, and only this one case knows the mapping.
+        //
+        // Total by construction: a row with no box was never inserted
+        // into the virtual table (the sync trigger's `IS NOT NULL`
+        // guard), so it is simply not in the list — the same answer the
+        // column mapping's leading `IS NOT NULL` produces.
+        const [id, minx, maxx, miny, maxy] = [dialect.rtree.columns[0], ...pred.columns];
+        const edge = (axis) => probeEdge(pred.probe, param, axis);
+        return `${dialect.rowIdentity()} IN (SELECT ${q(id)} FROM ${q(pred.table)}`
+          + ` WHERE ${q(minx)} <= ${edge('e')} AND ${q(maxx)} >= ${edge('w')}`
+          + ` AND ${q(miny)} <= ${edge('n')} AND ${q(maxy)} >= ${edge('s')})`;
+      }
       case 'cellIn': {
         // The cells are whole values of the column, so this is an
         // equality set — and `IN` is the spelling that keeps it one:
@@ -256,15 +273,22 @@ export function emitPlan(plan, dialect, physical) {
     }
   };
 
-  const selection = plan.aggregate === null
-    ? `${dialect.jsonText(docColumn)} AS ${q('doc')}`
-    : plan.aggregate.fn === 'count'
-      ? `COUNT(*) AS ${q('value')}`
-      : `${plan.aggregate.fn.toUpperCase()}(${valueOf(plan.aggregate.ref)}) AS ${q('value')}`;
+  const selection = plan.rank !== null
+    // the k-nearest fetch: the row identity and the packed column
+    // under the pushed WHERE, and nothing that orders or limits — the
+    // engine scores, cuts and ranks (measured: every SQL spelling of
+    // the rank loses to fetching the column and ranking in the engine,
+    // and none of them runs where no function can be registered)
+    ? `${dialect.rowIdentity()} AS ${q('rid')}, ${q(plan.rank.column)} AS ${q('vec')}`
+    : plan.aggregate === null
+      ? `${dialect.jsonText(docColumn)} AS ${q('doc')}`
+      : plan.aggregate.fn === 'count'
+        ? `COUNT(*) AS ${q('value')}`
+        : `${plan.aggregate.fn.toUpperCase()}(${valueOf(plan.aggregate.ref)}) AS ${q('value')}`;
 
   let sql = `SELECT ${selection} FROM ${q(physical.table)}`;
   if (plan.filter !== null) sql += ` WHERE ${emitPred(plan.filter)}`;
-  if (plan.aggregate === null) {
+  if (plan.aggregate === null && plan.rank === null) {
     const terms = (plan.order ?? []).map((term) => {
       // Jaren's default sorts an empty key least: NULLS FIRST when
       // ascending, NULLS LAST when descending — and mirrored for

package/src/index.js

@@ -30,10 +30,12 @@ export { typeOfPath, isNumericType } from './types.js';
 export { compileSetResidual, compileRowResidual, sequenceResult } from './residual.js';
 export { deterministicFragment, registerFragment } from './udf.js';
 export {
-  DERIVE_KINDS, BBOX_COMPONENTS, BBOX_INDEX_ORDER, PRECISION_MIN, PRECISION_MAX,
-  deriveGeohash, deriveBboxEdge, derivedValue, memberAt, storedMemberForm,
-  registerDeriveFunctions,
+  DERIVE_KINDS, DERIVE_MAPPING, PHYSICAL_KINDS, BBOX_COMPONENTS, BBOX_INDEX_ORDER,
+  PRECISION_MIN, PRECISION_MAX, DIMS_MIN, DIMS_MAX,
+  deriveGeohash, deriveBboxEdge, deriveVector, derivedValue, derivedMappingFor, memberAt,
+  storedMemberForm, registerDeriveFunctions, probeVector, columnScore,
 } from './derive.js';
+export { KNN_MARGIN, IDENTITY_CHUNK, cutCandidates, identityBatches } from './knn.js';
 export {
   createQueryEngine, createQueryState, createEntityQueryEngine,
   createLoadEngine, INCLUDE_DEPTH_DEFAULT,

package/src/knn.js

@@ -0,0 +1,96 @@
+//@ts-check
+/**
+ * @file The candidate cut of a k-nearest plan: the arithmetic between
+ * the scores a statement fetched and the row identities the engine
+ * will decide over. No vector arithmetic lives here — a score is
+ * `derive.js`'s, through `@jarenjs/core/vector` — and no SQL: the
+ * fetch of the winners is the dialect's. This is the one place the
+ * margin is applied and the one place candidate identities are
+ * batched for it.
+ */
+
+/**
+ * The inclusive score margin of the cut. The column's score is a dot
+ * product over binary32-normalized forms; the engine's key is the
+ * cosine of the raw doubles; measured, the two differ by at most
+ * ~1e-8. Any margin of at least twice that makes the engine's top
+ * `offset + limit` a SUBSET of the candidates: were a row the engine
+ * ranks inside the window cut, some candidate the engine ranks outside
+ * it would have to score higher by the column and lower by the engine,
+ * which two scores within half the margin of each other cannot do.
+ * This is a hundred times that bound — it admits, in practice, only
+ * true ties, and those the engine breaks by the document's own keys.
+ */
+export const KNN_MARGIN = 1e-6;
+
+/**
+ * The most identities one fetch statement binds: under the parameter
+ * cap of every SQLite build the store runs on. A guard, not a design —
+ * a k-nearest window is a handful of rows, and this only matters for a
+ * collection of many exact duplicates.
+ */
+export const IDENTITY_CHUNK = 512;
+
+/** @param {any} a @param {any} b */
+const byIdentity = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+
+/**
+ * The rows a k-nearest window can contain, from the scored fetch.
+ *
+ * `m = offset + limit` rows are needed. When at least `m` rows scored,
+ * the candidates are every scored row within `margin` of the m-th best
+ * score — ties at the boundary included by construction. When fewer
+ * did, the window reaches the unrankable tail (NULL columns, or a
+ * collection smaller than the window), which only the documents can
+ * order: every row is then a candidate, and the collection is no
+ * larger than the window.
+ * @param {{ identity: any, score: number | null }[]} rows - one per
+ *   fetched row; `score` is `null` where the column held no vector
+ * @param {number} m - `offset + limit`
+ * @param {number} margin
+ * @returns {{ identities: any[], scored: number, full: boolean }} the
+ *   candidate identities in ascending identity order — the
+ *   collection's own order, which a stable sort over the candidates
+ *   must see — with how many rows scored and whether every row was
+ *   taken
+ */
+export function cutCandidates(rows, m, margin) {
+  let scored = 0;
+  for (const row of rows) if (row.score !== null) scored++;
+  if (scored < m) {
+    return { identities: rows.map((row) => row.identity).sort(byIdentity), scored, full: true };
+  }
+  if (m <= 0) return { identities: [], scored, full: false };
+  const scores = new Float64Array(scored);
+  let at = 0;
+  for (const row of rows) if (row.score !== null) scores[at++] = row.score;
+  scores.sort();
+  const threshold = scores[scored - m] - margin;
+  const identities = [];
+  for (const row of rows) {
+    if (row.score !== null && row.score >= threshold) identities.push(row.identity);
+  }
+  identities.sort(byIdentity);
+  return { identities, scored, full: false };
+}
+
+/**
+ * The identities sliced into fetch batches: at most `IDENTITY_CHUNK`
+ * each, and each padded with `null` to the next power of two — a NULL
+ * in an IN list matches no row — so a handful of prepared statements
+ * serve every candidate count instead of one per count seen.
+ * @param {any[]} identities - in the order they should be fetched
+ * @returns {{ size: number, params: any[] }[]}
+ */
+export function identityBatches(identities) {
+  const batches = [];
+  for (let start = 0; start < identities.length; start += IDENTITY_CHUNK) {
+    const slice = identities.slice(start, start + IDENTITY_CHUNK);
+    let size = 1;
+    while (size < slice.length) size *= 2;
+    const params = [...slice];
+    while (params.length < size) params.push(null);
+    batches.push({ size, params });
+  }
+  return batches;
+}

package/src/live.js

@@ -46,7 +46,8 @@ const segmentsOf = (path) => path.split('/').slice(1).map(decodeJSONPointerSegme
  * @param {any} document
  */
 function unwrapDocument(document) {
-  let doc = Array.isArray(document) && document.length === 1 ? document[0] : document;
+  const whole = Array.isArray(document) && document.length === 1 ? document[0] : document;
+  let doc = whole;
   let offset = 0;
   let limit = null;
   let windowed = false;
@@ -74,7 +75,7 @@ function unwrapDocument(document) {
       }
     }
   }
-  return { inner: doc, windowed, offset, limit, aggregate };
+  return { inner: doc, whole, windowed, offset, limit, aggregate };
 }
 
 /** The single for-binding name of a canonical flwor, or null. */
@@ -179,6 +180,55 @@ function memberDeps(root) {
   return deps;
 }
 
+/**
+ * The residual reasons a plan carries once every spatial REFINEMENT is
+ * taken out. A refinement is a pushed, non-exact pre-filter (`$within`,
+ * a bounded `$distance`, an over-long cell prefix): the fetch is still
+ * SQL-narrowed and the exact predicate stays in the residual, which is
+ * the per-row evaluation maintenance runs anyway. One reason is removed
+ * per non-exact pre-filter, matched by construct, so a spatial
+ * predicate the planner REFUSED (no derived index on the member) still
+ * counts as a reason and still re-runs.
+ * @param {any} planned
+ * @returns {{ construct: string, reason: string }[]}
+ */
+function unrefinedReasons(planned) {
+  const remaining = [...planned.reasons];
+  for (const prefilter of planned.prefilters) {
+    if (prefilter.exact) continue;
+    const index = remaining.findIndex((reason) => reason.construct === prefilter.construct);
+    if (index !== -1) remaining.splice(index, 1);
+  }
+  return remaining;
+}
+
+/**
+ * Whether a plan fell to the set residual ONLY because a spatial
+ * pre-filter refines in the engine (§7's spatial rows). `allowReturn`
+ * admits the per-row projection reason beside the refinement — the
+ * rows strategy re-evaluates the whole document per row, so a
+ * projected return is exact there and nowhere else.
+ * @param {any} planned
+ * @param {boolean} allowReturn
+ */
+function refinedOnly(planned, allowReturn) {
+  if (planned.mode !== 'set' || !planned.prefilters.some((prefilter) => !prefilter.exact)) {
+    return false;
+  }
+  const remaining = unrefinedReasons(planned)
+    .filter((reason) => !(allowReturn && reason.construct === '$return'));
+  return remaining.length === 0;
+}
+
+const SPATIAL_RERUN = {
+  aggregate: 'a spatial aggregate re-runs: the accumulator needs a fully translated '
+    + 'selection, and a refined spatial predicate leaves the exact test to the engine',
+  group: 'a spatial group re-runs: the group filter needs a fully translated selection, '
+    + 'and a refined spatial predicate leaves the exact test to the engine',
+  order: "'$orderby' — an ordering over a refined spatial selection re-runs "
+    + '(no window is maintained beside a pre-filter that only narrows)',
+};
+
 /**
  * Classify a collection query document against §7's table. Pure —
  * given the document and the collection's planner shape, returns the
@@ -192,18 +242,20 @@ function memberDeps(root) {
  */
 export function classifyLiveQuery(document, queryShape, keyed) {
   const rerun = (reason) => ({ strategy: 'rerun', reason });
+  // the reason named is the first one that is NOT a spatial refinement:
+  // a refinement narrows and never forces a re-run by itself
   const plannerReason = (planned) => {
-    const forcing = planned.reasons[0]
+    const forcing = unrefinedReasons(planned)[0] ?? planned.reasons[0]
       ?? { construct: 'residual', reason: 'the document did not translate' };
     return `'${forcing.construct}' — ${forcing.reason}`;
   };
-  const { inner, windowed, offset, limit, aggregate } = unwrapDocument(document);
+  const { inner, whole, windowed, offset, limit, aggregate } = unwrapDocument(document);
 
   if (aggregate !== null) {
     if (windowed) return rerun('a windowed aggregate maintains no accumulator');
     const planned = planQuery({ [aggregate.name]: inner }, queryShape, {});
     if (planned.mode !== 'native' || planned.plan.aggregate === null) {
-      return rerun(plannerReason(planned));
+      return rerun(refinedOnly(planned, false) ? SPATIAL_RERUN.aggregate : plannerReason(planned));
     }
     if (!keyed) return rerun('rows without a document key cannot be tracked');
     return {
@@ -220,7 +272,9 @@ export function classifyLiveQuery(document, queryShape, keyed) {
     const carrier = documentsSource(group.binding, group.where);
     const planned = planQuery(carrier, queryShape, {});
     if (planned.mode !== 'native') {
-      return rerun(`the group filter did not translate: ${plannerReason(planned)}`);
+      return rerun(refinedOnly(planned, false)
+        ? SPATIAL_RERUN.group
+        : `the group filter did not translate: ${plannerReason(planned)}`);
     }
     if (!keyed) return rerun('rows without a document key cannot be tracked');
     const rowDocument = {
@@ -239,8 +293,34 @@ export function classifyLiveQuery(document, queryShape, keyed) {
     };
   }
 
+  // a k-nearest window is planned WITH its window (the cut needs the
+  // limit), so the whole document is asked before the inner one: the
+  // column cuts the candidates and the engine orders them, and no
+  // maintained window has that shape — a ranking re-runs, named
+  if (windowed && planQuery(whole, queryShape, {}).mode === 'knn')
+    return rerun('a k-nearest ranking re-runs (the vector column cuts the candidates and the engine orders them)');
+
   const planned = planQuery(inner, queryShape, {});
-  if (planned.mode === 'set') return rerun(plannerReason(planned));
+  if (planned.mode === 'set') {
+    // §7's spatial rows: the fetch is SQL-narrowed by the pushed box or
+    // cell range and the exact predicate is what per-row re-evaluation
+    // runs — so a `$where` that fell to the set residual ONLY for a
+    // refinement is maintained as rows. An ordering beside it is not
+    // (the set residual drops the planner's order terms), and neither
+    // is a window; both re-run, named.
+    if (!refinedOnly(planned, true)) return rerun(plannerReason(planned));
+    if (!keyed) return rerun('rows without a document key cannot be tracked');
+    // a translated ordering leaves no reason behind, but the set residual
+    // dropped its terms — the window is not maintainable here
+    if (isJsonObject(inner) && inner.$orderby !== undefined) return rerun(SPATIAL_RERUN.order);
+    if (windowed) return rerun('a limit without an order is not deterministic to maintain');
+    return {
+      strategy: 'rows',
+      inner,
+      projected: planned.reasons.some((reason) => reason.construct === '$return'),
+      deps: { whole: true, members: new Set() },
+    };
+  }
   if (!keyed) return rerun('rows without a document key cannot be tracked');
 
   if (planned.plan.order !== null) {