@jarenjs/db 0.43.3 → 0.46.5

package/src/query.js

@@ -18,6 +18,17 @@
  * residual over the full collection instead of the native statement —
  * SQLite cannot bind a boolean, a `null` needs Jaren's semantics, and
  * a missing external must raise the ENGINE's error, not a driver's.
+ * Two externals never bind at all and divert by their own rule: a
+ * region reaching the statement through derived slots diverts when it
+ * has no box, and a k-nearest probe — which the plan scores in the
+ * engine, never in SQL — diverts when it is not a vector of the
+ * column's width, so the engine answers what it answers everywhere.
+ *
+ * The k-nearest mode (`plan.rank`) is a set residual whose candidates
+ * an ordering chose: the statement fetches (identity, column) under
+ * the pushed WHERE, the engine scores and cuts (`knn.js`), the
+ * winners' documents are fetched by identity through the dialect, and
+ * the whole document runs over them.
  */
 
 import { createSemanticCache } from '@jarenjs/core/cache';
@@ -31,7 +42,8 @@ import {
 import { emitPlan, emitEntityPlan, createEntityPredicateEmitters } from './emit.js';
 import { selectPlan } from './algebra.js';
 import { compileSetResidual, compileRowResidual, sequenceResult } from './residual.js';
-import { derivedSlotValue, probeBox } from './derive.js';
+import { derivedSlotValue, probeBox, probeVector, columnScore } from './derive.js';
+import { cutCandidates, identityBatches } from './knn.js';
 import { deterministicFragment, registerFragment } from './udf.js';
 import {
   normalizeProfile, translateProfilePredicate,
@@ -84,20 +96,25 @@ function slotValue(slot, externals) {
  * How one external reaches the statement. An external reached ONLY
  * through derived slots is bindable when its bound value HAS a box —
  * the object itself never had to be bindable. One reached directly
- * must be a string or a finite number, as before; and an external in
- * the document that reaches no slot at all still forces the diversion,
+ * must be a string or a finite number, as before; a k-nearest PROBE
+ * reaches no slot (it is scored in the engine) and is bindable when
+ * its value is a vector of the column's width; and an external in the
+ * document that reaches nothing at all still forces the diversion,
  * because the residual needs the engine's own semantics for it.
  * @param {import('./emit.js').ParamSlot[]} slots
- * @returns {Map<string, 'plain' | 'derived'>}
+ * @param {import('./algebra.js').PlanRank | null} rank
+ * @returns {Map<string, 'plain' | 'derived' | 'probe'>}
  */
-function externalSlotKinds(slots) {
-  /** @type {Map<string, 'plain' | 'derived'>} */
+function externalSlotKinds(slots, rank) {
+  /** @type {Map<string, 'plain' | 'derived' | 'probe'>} */
   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');
   }
+  if (rank !== null && 'ext' in rank.probe && !kinds.has(rank.probe.ext))
+    kinds.set(rank.probe.ext, 'probe');
   return kinds;
 }
 
@@ -123,6 +140,12 @@ export function createQueryEngine(context) {
     collection: collection.name,
     schema: collection.schema,
     columnByCanonical: physicalPlan.columnByCanonical,
+    // 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
+    // the physical plan already fell back there
+    virtualByStem: new Map((physicalPlan.virtualTables ?? [])
+      .map((virtual) => [virtual.stem, { name: virtual.name, columns: virtual.columns }])),
     operators,
   };
   const physical = {
@@ -130,6 +153,18 @@ export function createQueryEngine(context) {
     keyColumn: physicalPlan.keyColumn,
     docColumn: physicalPlan.docColumn,
   };
+  /** The k-nearest counters `stats()` reports: how many rows the
+   * fetch scored and how many candidates the cut kept, so a
+   * duplicate-heavy collection is visible rather than merely slow —
+   * plus `diverted`, the calls whose plan WAS the cut and whose bound
+   * probe was not a vector of the column's width, so the whole
+   * collection was read instead. A plan is recognized once and bound
+   * many times; without that counter a probe of the wrong width turns
+   * 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 by-identities fetch statements, one per batch size. */
+  const identityFetch = new Map();
 
   /** The `compileJsonQuery` options for an inline residual: the
    * profile's engine limits plus the store's registered operators. */
@@ -252,7 +287,11 @@ export function createQueryEngine(context) {
       sql: emitted.sql,
       slots: emitted.slots,
       externalNames,
-      externalSlotKinds: externalSlotKinds(emitted.slots),
+      externalSlotKinds: externalSlotKinds(emitted.slots, plan.rank),
+      // a literal probe is normalized once, here; an external one per
+      // call, from the bound value
+      probe: plan.rank !== null && 'lit' in plan.rank.probe
+        ? probeVector(plan.rank.probe.lit, plan.rank.dims) : null,
       dependencies: planned.analysis.dependencies,
       limits: planned.analysis.limits,
       residualLimits: limits,
@@ -349,12 +388,90 @@ export function createQueryEngine(context) {
 
   /** Must this call divert to the residual? */
   const mustDivert = (entry, externals) =>
-    entry.externalNames.some((name) => (entry.externalSlotKinds.get(name) === 'derived'
-      ? probeBox(externals[name]) === null
-      : !bindable(externals[name])));
+    entry.externalNames.some((name) => {
+      const kind = entry.externalSlotKinds.get(name);
+      if (kind === 'derived') return probeBox(externals[name]) === null;
+      if (kind === 'probe') return probeVector(externals[name], entry.plan.rank.dims) === null;
+      return !bindable(externals[name]);
+    });
 
   const rowsToDocs = (rows) => rows.map((row) => JSON.parse(row.doc));
 
+  /**
+   * The documents of the given row identities, in identity order,
+   * through the dialect's by-identities statement — batched, and each
+   * batch padded to a prepared size (`identityBatches`).
+   * @param {any[]} identities
+   * @returns {any} value-or-promise of the documents
+   */
+  const fetchByIdentities = (identities) => {
+    const batches = identityBatches(identities);
+    /** @type {any[]} */
+    const docs = [];
+    const next = (i) => {
+      if (i >= batches.length) return docs;
+      const batch = batches[i];
+      let statement = identityFetch.get(batch.size);
+      if (statement === undefined) {
+        statement = connection.prepare(dialect.dml.selectByIdentities(physical, batch.size));
+        identityFetch.set(batch.size, statement);
+      }
+      return chain(statement, (prepared) => chain(prepared.all(batch.params), (rows) => {
+        for (const row of rows) docs.push(JSON.parse(row.doc));
+        return next(i + 1);
+      }));
+    };
+    return next(0);
+  };
+
+  /**
+   * The k-nearest candidates: every fetched row's column scored
+   * against the probe, the cut applied at `offset + limit` with the
+   * plan's margin, and the winners' documents fetched by identity.
+   * The engine then decides over them (the set residual).
+   * @param {any} entry
+   * @param {any} externals
+   * @returns {any} value-or-promise of the candidate documents
+   */
+  const knnCandidates = (entry, externals) => {
+    const rank = entry.plan.rank;
+    const probe = entry.probe ?? probeVector(externals[rank.probe.ext], rank.dims);
+    return chain(statementOf(entry), (statement) =>
+      chain(statement.all(bindParams(entry, externals)), (rows) => {
+        checkRowBound(entry, rows);
+        const scored = rows.map((row) =>
+          ({ identity: row.rid, score: columnScore(row.vec, rank.dims, probe) }));
+        const cut = cutCandidates(scored, rank.offset + rank.limit, rank.margin);
+        knnStats.queries++;
+        knnStats.rows += rows.length;
+        knnStats.candidates += cut.identities.length;
+        if (cut.full) knnStats.fullFetches++;
+        return fetchByIdentities(cut.identities);
+      }));
+  };
+
+  /**
+   * The documents a residual runs over: the whole collection when the
+   * call diverts (still wearing the profile's mandatory predicate and
+   * row bound), the narrowed fetch in set mode, the cut in knn mode.
+   * @param {any} entry
+   * @param {any} externals
+   * @param {boolean} diverted
+   * @returns {any} value-or-promise of the documents
+   */
+  const candidatesOf = (entry, externals, diverted) => {
+    if (diverted) {
+      if (entry.planned.mode === 'knn') knnStats.diverted++;
+      return chain(fullScanOf(entry), (statement) =>
+        chain(statement.all(fullScanParams(entry)), (rows) =>
+          rowsToDocs(checkRowBound(entry, rows))));
+    }
+    if (entry.planned.mode === 'knn') return knnCandidates(entry, externals);
+    return chain(statementOf(entry), (statement) =>
+      chain(statement.all(bindParams(entry, externals)), (rows) =>
+        rowsToDocs(checkRowBound(entry, rows))));
+  };
+
   const aggregateResult = (entry, row) => {
     const fn = entry.plan.aggregate.fn;
     const value = row?.value ?? null;
@@ -389,17 +506,14 @@ export function createQueryEngine(context) {
     const entry = entryFor(document, strict, profile, pushdown);
 
     return chain(guardScan(entry), () => {
-      if (mustDivert(entry, externals)) {
-        return chain(fullScanOf(entry), (statement) =>
-          chain(statement.all(fullScanParams(entry)), (rows) =>
-            setResidualOf(entry, document)(rowsToDocs(checkRowBound(entry, rows)), externals)));
-      }
-      if (entry.planned.mode === 'set') {
-        // the narrowed statement fetches candidates; the full document
-        // then re-applies its own predicates (idempotent narrowing)
-        return chain(statementOf(entry), (statement) =>
-          chain(statement.all(bindParams(entry, externals)), (rows) =>
-            setResidualOf(entry, document)(rowsToDocs(checkRowBound(entry, rows)), externals)));
+      const diverted = mustDivert(entry, externals);
+      if (diverted || entry.planned.mode === 'set' || entry.planned.mode === 'knn') {
+        // the candidates — the whole collection, the narrowed fetch, or
+        // 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));
       }
       if (entry.planned.mode === 'row') {
         return chain(statementOf(entry), (statement) =>
@@ -448,19 +562,16 @@ export function createQueryEngine(context) {
       if (done) return Promise.resolve({ done: true, value: undefined });
       if (bufferedAt < buffered.length) return Promise.resolve(nextFromBuffer());
 
-      if (entry.planned.mode === 'set' || mustDivert(entry, externals)) {
+      if (entry.planned.mode === 'set' || entry.planned.mode === 'knn'
+        || mustDivert(entry, externals)) {
         // the barrier: materialize candidates, pack the result items
         if (materialized === null) {
           const diverted = mustDivert(entry, externals);
-          materialized = Promise.resolve(chain(guardScan(entry), () => chain(
-            diverted ? fullScanOf(entry) : statementOf(entry),
-            (statement) => chain(
-              statement.all(diverted ? fullScanParams(entry) : bindParams(entry, externals)),
-              (rows) => {
-                buffered = packedResidualOf(entry, document)(
-                  rowsToDocs(checkRowBound(entry, rows)), externals);
-                bufferedAt = 0;
-              }))));
+          materialized = Promise.resolve(chain(guardScan(entry), () =>
+            chain(candidatesOf(entry, externals, diverted), (docs) => {
+              buffered = packedResidualOf(entry, document)(docs, externals);
+              bufferedAt = 0;
+            })));
         }
         return materialized.then(() => {
           if (bufferedAt < buffered.length) return nextFromBuffer();
@@ -537,12 +648,17 @@ export function createQueryEngine(context) {
     const entry = entryFor(document, strict, profile, pushdown);
 
     const touchedColumns = new Set();
+    // an R*Tree probe touches no generated column at all — the index it
+    // reads IS a table — so the virtual tables are collected beside the
+    // declared indexes and named in the same `indexes` list
+    const touchedVirtual = new Set();
     const collectColumns = (pred) => {
       if (pred === null) return;
       if (pred.p === 'and' || pred.p === 'or') pred.items.forEach(collectColumns);
       else if (pred.p === 'not') collectColumns(pred.item);
       else if (pred.p === 'bboxOverlap')
         for (const column of Object.values(pred.columns)) touchedColumns.add(column);
+      else if (pred.p === 'bboxRtree') touchedVirtual.add(pred.table);
       else if (pred.p === 'cellIn' || pred.p === 'cellPrefix')
         touchedColumns.add(pred.column);
       else if ('ref' in pred && pred.ref?.column) touchedColumns.add(pred.ref.column);
@@ -552,9 +668,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);
-    const indexes = physicalPlan.expected.indexes
-      .filter((index) => index.columns.some((column) => touchedColumns.has(column)))
-      .map((index) => index.name);
+    const indexes = [
+      ...physicalPlan.expected.indexes
+        .filter((index) => index.columns.some((column) => touchedColumns.has(column)))
+        .map((index) => index.name),
+      ...[...touchedVirtual].sort(),
+    ];
 
     const params = entry.slots.map((slot) => {
       if ('external' in slot) return { external: slot.external };
@@ -566,8 +685,10 @@ export function createQueryEngine(context) {
       return bindable(value) ? value : null;
     });
 
+    const rank = entry.plan.rank;
     return chain(connection.prepare(dialect.explainQuery(entry.sql)), (statement) =>
       chain(statement.all(eqpParams), (rows) => ({
+        mode: entry.planned.mode,
         externals: [...entry.externalNames],
         operators: [...entry.dependencies.operators],
         functions: [...entry.dependencies.functions],
@@ -578,10 +699,22 @@ export function createQueryEngine(context) {
         indexes,
         prefilters: entry.planned.prefilters.map((prefilter) => ({ ...prefilter,
           columns: [...prefilter.columns] })),
+        // the k-nearest stage, when the plan has one: what the fetch
+        // reads, the window the cut serves, the margin it keeps, and
+        // who decides the order — always the engine
+        rank: rank === null ? null : {
+          column: rank.column,
+          dims: rank.dims,
+          probe: 'lit' in rank.probe ? { literal: [...rank.probe.lit] } : { external: rank.probe.ext },
+          limit: rank.limit,
+          offset: rank.offset,
+          margin: rank.margin,
+          decides: 'engine',
+        },
         residual: entry.planned.mode === 'native'
           ? null
           : { mode: entry.planned.mode, reasons: entry.planned.reasons },
-        barriers: entry.planned.mode === 'set'
+        barriers: entry.planned.mode === 'set' || entry.planned.mode === 'knn'
           ? entry.planned.reasons.map((r) => ({ operator: r.construct, reason: r.reason }))
           : [],
         udfs: [...entry.planned.udfs],
@@ -589,7 +722,7 @@ export function createQueryEngine(context) {
       })));
   };
 
-  return { execute, query, explain, shape };
+  return { execute, query, explain, shape, stats: () => ({ knn: { ...knnStats } }) };
 }
 
 // ————— The entity query surface (the second document kind) —————
@@ -693,15 +826,15 @@ export function createEntityQueryEngine(context) {
       }
       return runResidual(entry, document, externals);
     }
-    // bind-time diversion, exactly phase A's: a missing external must
-    // raise the ENGINE's error, a boolean or null cannot bind natively
-    for (const slot of entry.slots) {
-      if ('external' in slot && !bindable(externals[slot.external]))
-        return runResidual(entry, document, externals);
-    }
+    // bind-time diversion, exactly the collection engine's: every slot
+    // binds through `slotValue` — a derived slot included — and a value
+    // the database cannot take (a missing external, a boolean, a null,
+    // a region with no box) sends the call to the residual, where the
+    // ENGINE raises its own error or answers with its own semantics
+    const params = entry.slots.map((slot) => slotValue(slot, externals));
+    if (params.some((value) => !bindable(value)))
+      return runResidual(entry, document, externals);
     if (entry.statement === null) entry.statement = connection.prepare(entry.sql);
-    const params = entry.slots.map((slot) =>
-      ('literal' in slot ? slot.literal : externals[slot.external]));
     return chain(entry.statement, (statement) => {
       if (entry.planned.plan.aggregate === 'count')
         return chain(statement.get(params), (row) => row?.value ?? 0);

package/src/store.js

@@ -37,8 +37,8 @@ import { createLiveRegistry, classifyLiveQuery, LIVE_DEFAULTS } from './live.js'
 import { createJobEngine } from './jobs.js';
 import { collectEntityRoots } from './plan.js';
 import {
-  DERIVE_KINDS, PRECISION_MIN, PRECISION_MAX, derivedValue, memberAt,
-  storedMemberForm, registerDeriveFunctions,
+  DERIVE_KINDS, PHYSICAL_KINDS, PRECISION_MIN, PRECISION_MAX, DIMS_MIN, DIMS_MAX,
+  derivedValue, memberAt, storedMemberForm, registerDeriveFunctions,
 } from './derive.js';
 
 /** The model format version this store implements. */
@@ -58,51 +58,119 @@ function modelError(code, reason, docPath) {
 }
 
 /**
- * Normalize one index's `derive` declaration — the spatial storage
- * vocabulary. `derive` says what is COMPUTED from the selected member,
- * never how the member is selected, so the singular-path rule and its
- * `JD0004` are untouched; these are the refusals a derived index adds.
+ * Normalize one index's `derive` declaration — the spatial and vector
+ * storage vocabulary. `derive` says what is COMPUTED from the selected
+ * member, never how the member is selected, so the singular-path rule
+ * and its `JD0004` are untouched; these are the refusals a derived
+ * index adds.
  *
  * Every one of them is a mistake worth catching at open rather than at
  * the first query that quietly returns nothing.
  * @param {any} index - the declared index member
  * @param {string[]} paths
  * @param {string} docPath
- * @returns {{ kind: string | null, precision: number | undefined }}
+ * @returns {{ kind: string | null, precision: number | undefined,
+ *   physical: string | undefined, dims: number | undefined }}
  */
 function normalizeDerive(index, paths, docPath) {
   const declared = index.derive;
+  const none = { precision: undefined, physical: undefined, dims: undefined };
   if (declared === undefined) {
     if (index.precision !== undefined) {
       throw modelError('JD0004',
         "precision belongs to a derived index — declare derive: 'geohash' beside it",
         `${docPath}/precision`);
     }
-    return { kind: null, precision: undefined };
+    if (index.physical !== undefined) {
+      throw modelError('JD0004',
+        "physical names the shape a derive: 'bbox' index takes on disk; an undecorated "
+        + 'index has only one shape',
+        `${docPath}/physical`);
+    }
+    if (index.dims !== undefined) {
+      throw modelError('JD0004',
+        `index '${index.name}': dims is the width of a derive: 'vector' column — declare `
+        + 'derive beside it; an undecorated index has no width',
+        `${docPath}/dims`);
+    }
+    return { ...none, kind: null };
   }
   if (typeof declared !== 'string' || !DERIVE_KINDS.has(declared)) {
     throw modelError('JD0004',
-      `derive is a closed set ('geohash' or 'bbox'), got ${JSON.stringify(declared)} — `
+      `index '${index.name}': derive is a closed set ('geohash', 'bbox' or 'vector'), got `
+      + `${JSON.stringify(declared)} — `
       + 'an open expression member would be a second query language inside the model',
       `${docPath}/derive`);
   }
   if (paths.length !== 1) {
     throw modelError('JD0004',
-      `a ${declared} index derives its columns from ONE member; a composite path declares several`,
+      `index '${index.name}': a ${declared} index derives its columns from ONE member; a composite `
+      + 'path declares several',
       `${docPath}/path`);
   }
   if (index.unique === true) {
     throw modelError('JD0004',
-      `a ${declared} index is never unique: distinct positions share a cell (and a box edge) by construction`,
+      declared === 'vector'
+        ? `index '${index.name}': a vector index is never unique — it is a column nothing seeks, `
+          + 'and two documents may carry one embedding'
+        : `index '${index.name}': a ${declared} index is never unique: distinct positions share a `
+          + 'cell (and a box edge) by construction',
       `${docPath}/unique`);
   }
+  if (declared === 'vector') {
+    if (index.precision !== undefined) {
+      throw modelError('JD0004',
+        `index '${index.name}': precision applies to a geohash index; a vector column has a `
+        + 'width (dims), not a cell size',
+        `${docPath}/precision`);
+    }
+    if (index.physical !== undefined) {
+      throw modelError('JD0004',
+        `index '${index.name}': physical applies to a bbox index; a vector column has one `
+        + 'shape on disk — a stored packed column, on every driver',
+        `${docPath}/physical`);
+    }
+    const dims = index.dims;
+    if (dims === undefined) {
+      throw modelError('JD0004',
+        `index '${index.name}': a vector index must declare dims (${DIMS_MIN}..${DIMS_MAX}) — `
+        + 'the width is the identity of the column, and a column that accepted any width '
+        + 'would rank vectors from different models against each other',
+        `${docPath}/dims`);
+    }
+    if (typeof dims !== 'number' || !Number.isInteger(dims) || dims < DIMS_MIN || dims > DIMS_MAX) {
+      throw modelError('JD0004',
+        `index '${index.name}': dims must be an integer ${DIMS_MIN}..${DIMS_MAX}, got ${JSON.stringify(dims)}`,
+        `${docPath}/dims`);
+    }
+    return { ...none, kind: 'vector', dims };
+  }
+  if (index.dims !== undefined) {
+    throw modelError('JD0004',
+      `index '${index.name}': dims is the width of a derive: 'vector' column; a ${declared} `
+      + 'index has no width',
+      `${docPath}/dims`);
+  }
   if (declared === 'bbox') {
     if (index.precision !== undefined) {
       throw modelError('JD0004',
         'precision applies to a geohash index; a bbox index has no cell size',
         `${docPath}/precision`);
     }
-    return { kind: 'bbox', precision: undefined };
+    const physical = index.physical;
+    if (physical !== undefined
+      && (typeof physical !== 'string' || !PHYSICAL_KINDS.has(physical))) {
+      throw modelError('JD0004',
+        `physical is a closed set ('columns' or 'rtree'), got ${JSON.stringify(physical)}`,
+        `${docPath}/physical`);
+    }
+    return { ...none, kind: 'bbox', physical };
+  }
+  if (index.physical !== undefined) {
+    throw modelError('JD0004',
+      "physical applies to a bbox index; an R*Tree carries numbers, and a geohash cell "
+      + 'is text',
+      `${docPath}/physical`);
   }
   const precision = index.precision;
   if (precision === undefined) {
@@ -118,7 +186,7 @@ function normalizeDerive(index, paths, docPath) {
       `precision must be an integer ${PRECISION_MIN}..${PRECISION_MAX}, got ${JSON.stringify(precision)}`,
       `${docPath}/precision`);
   }
-  return { kind: 'geohash', precision };
+  return { ...none, kind: 'geohash', precision };
 }
 
 /**
@@ -230,6 +298,8 @@ export function normalizeModel(model) {
         unique: index.unique === true,
         derive: derive.kind,
         precision: derive.precision,
+        physical: derive.physical,
+        dims: derive.dims,
         docPath: indexDocPath,
       });
     }
@@ -536,7 +606,7 @@ function collectionCore(connection, collection, plan, validate, queryState, stor
   };
 
   const core = {
-    stats: () => ({ ...stats }),
+    stats: () => ({ ...stats, ...engine.stats() }),
     model: collection,
     queryShape: engine.shape,
     // the D2 provider: value-or-promise, deliberately NOT lifted — a
@@ -846,6 +916,39 @@ export function openStore(model, options) {
        */
       let topLevelTransaction = (fn) => withScope(opened.transaction, fn);
 
+      // ————— the rejection boundary around an ACQUIRED connection —————
+      // Initialization continues for a long way past `driver.open`:
+      // pragmas, shape verification, capture, jobs, readiness. Every one
+      // of those can refuse, and a refusal that walks away from the open
+      // handle leaks it — on Windows the database file simply stays
+      // locked, which is how three of these showed up as `EPERM` while
+      // a temporary directory was being removed. So: close exactly once
+      // on any failure after acquisition, and keep the initialization
+      // error primary — a close that also fails is retained beside it
+      // rather than replacing the reason the open was refused.
+      let closed = false;
+      /**
+       * Release the handle and re-reject with the original failure.
+       * @param {any} error
+       * @returns {Promise<never>}
+       */
+      const failClosed = (error) => {
+        if (closed) return Promise.reject(error);
+        closed = true;
+        /** @param {any} closeError */
+        const both = (closeError) => Promise.reject(new AggregateError([error, closeError],
+          'the store failed to open, and closing the acquired connection failed too'));
+        let closing;
+        try {
+          closing = opened.close();
+        }
+        catch (closeError) {
+          return both(closeError);
+        }
+        return isThenable(closing)
+          ? closing.then(() => Promise.reject(error), both)
+          : Promise.reject(error);
+      };
       const dialect = connection.dialect;
       // The PHYSICAL MAPPING BRANCH for derived index columns. A driver
       // that can index a registered deterministic function generates
@@ -855,25 +958,46 @@ export function openStore(model, options) {
       // drift — that is a migration, not an open.
       const derivedMapping = connection.capabilities.deterministicIndexableFunctions === true
         ? 'virtual' : 'stored';
+      // the SECOND physical branch, and the same posture: a build
+      // without the R*Tree module maps `physical: 'rtree'` back onto
+      // the B-tree over the four columns and SAYS so through
+      // `explain().prefilters[].via` (MODEL-FORMAT §4). Refusing at open
+      // would break the format's stated portability promise; a silent
+      // fallback would break its stated honesty one
+      const rtreeCapable = connection.capabilities.rtree === true;
       /** @type {Map<string, any>} */
       const plans = new Map();
-      for (const [name, collection] of collections)
-        plans.set(name, planCollection(name, collection, dialect, { derived: derivedMapping }));
-      // a table whose column expression calls a function this connection
-      // has not registered cannot even be SELECTed (probed), so the
-      // registration precedes every statement over it
-      const needsDeriveFunctions = derivedMapping === 'virtual'
-        && [...plans.values()].some((plan) => plan.derived.length > 0);
       /** @type {Map<string, any>} */
       const entityPlans = new Map();
-      if (mapping !== null) {
-        for (const name of Object.keys(mapping.entities))
-          entityPlans.set(name, planEntity(name, mapping.entities[name], mapping, dialect));
-        for (const joinName of Object.keys(mapping.joinTables)) {
-          entityPlans.set(joinName,
-            planJoinTable(joinName, mapping.joinTables[joinName], mapping, dialect));
+      // Planning can REFUSE — a derived index over a member the schema
+      // does not type as geography is JD0004 here, not at normalization,
+      // because the physical mapping it plans is a property of the
+      // driver that opened the connection. It is inside the boundary
+      // for that reason: the refusal is raised after acquisition.
+      try {
+        for (const [name, collection] of collections)
+          plans.set(name, planCollection(name, collection, dialect,
+            { derived: derivedMapping, rtree: rtreeCapable }));
+        if (mapping !== null) {
+          for (const name of Object.keys(mapping.entities))
+            entityPlans.set(name, planEntity(name, mapping.entities[name], mapping, dialect));
+          for (const joinName of Object.keys(mapping.joinTables)) {
+            entityPlans.set(joinName,
+              planJoinTable(joinName, mapping.joinTables[joinName], mapping, dialect));
+          }
         }
       }
+      catch (error) {
+        return failClosed(error);
+      }
+      // a table whose column expression calls a function this connection
+      // has not registered cannot even be SELECTed (probed), so the
+      // registration precedes every statement over it. Only a VIRTUAL
+      // derived column needs one: a vector column is stored on every
+      // driver and a model with nothing else registers nothing
+      const needsDeriveFunctions = derivedMapping === 'virtual'
+        && [...plans.values()].some((plan) => plan.generated.some(
+          (column) => column.derive !== undefined && column.stored !== true));
 
       const pragmas = chain(
         memory
@@ -894,39 +1018,6 @@ export function openStore(model, options) {
               return null;
             }))));
 
-      // ————— the rejection boundary around an ACQUIRED connection —————
-      // Initialization continues for a long way past `driver.open`:
-      // pragmas, shape verification, capture, jobs, readiness. Every one
-      // of those can refuse, and a refusal that walks away from the open
-      // handle leaks it — on Windows the database file simply stays
-      // locked, which is how three of these showed up as `EPERM` while
-      // a temporary directory was being removed. So: close exactly once
-      // on any failure after acquisition, and keep the initialization
-      // error primary — a close that also fails is retained beside it
-      // rather than replacing the reason the open was refused.
-      let closed = false;
-      /**
-       * Release the handle and re-reject with the original failure.
-       * @param {any} error
-       * @returns {Promise<never>}
-       */
-      const failClosed = (error) => {
-        if (closed) return Promise.reject(error);
-        closed = true;
-        /** @param {any} closeError */
-        const both = (closeError) => Promise.reject(new AggregateError([error, closeError],
-          'the store failed to open, and closing the acquired connection failed too'));
-        let closing;
-        try {
-          closing = opened.close();
-        }
-        catch (closeError) {
-          return both(closeError);
-        }
-        return isThenable(closing)
-          ? closing.then(() => Promise.reject(error), both)
-          : Promise.reject(error);
-      };
       const opening = () => chain(pragmas, () =>
         chain(needsDeriveFunctions ? registerDeriveFunctions(connection) : null, () =>
         chain(ensureShape(connection, collections, plans, readOnly), () =>