@jarenjs/db 0.34.2 → 0.43.3

package/schemas/jaren-model.schema.json

@@ -21,7 +21,7 @@
    }
   },
   "entities": {
-   "description": "Entity name (an identifier) to entity declaration. The x-entity vocabulary lives INSIDE each entity schema's property subschemas and is documented in MODEL-FORMAT.md \u00a79; stripping it leaves a plain JSON Schema.",
+   "description": "Entity name (an identifier) to entity declaration. The x-entity vocabulary lives INSIDE each entity schema's property subschemas and is documented in MODEL-FORMAT.md §9; stripping it leaves a plain JSON Schema.",
    "type": "object",
    "minProperties": 1,
    "propertyNames": {
@@ -46,7 +46,7 @@
      "type": "object"
     },
     "key": {
-     "description": "Where the caller-supplied key lives in the document, as an RFC 6901 pointer selecting at least one member \u2014 or null when the store allocates.",
+     "description": "Where the caller-supplied key lives in the document, as an RFC 6901 pointer selecting at least one member — or null when the store allocates.",
      "type": [
       "string",
       "null"
@@ -54,7 +54,7 @@
      "pattern": "^/"
     },
     "identity": {
-     "description": "How keys come to be: 'caller' (the default when a key pointer is declared), or \u2014 only with \"key\": null \u2014 'uuid' (crypto.randomUUID) or 'integer' (database-allocated).",
+     "description": "How keys come to be: 'caller' (the default when a key pointer is declared), or — only with \"key\": null — 'uuid' (crypto.randomUUID) or 'integer' (database-allocated).",
      "enum": [
       "caller",
       "uuid",
@@ -80,7 +80,7 @@
    "additionalProperties": false
   },
   "index": {
-   "description": "One index over a singular JSONPath expression (or a composite over several). A non-singular path is rejected at open (JD0004).",
+   "description": "One index over a singular JSONPath expression (or a composite over several). A non-singular path is rejected at open (JD0004). A derived index computes indexable scalars from the selected member instead of indexing it directly.",
    "type": "object",
    "properties": {
     "name": {
@@ -108,6 +108,19 @@
     "unique": {
      "description": "Whether the index enforces uniqueness. Defaults to false.",
      "type": "boolean"
+    },
+    "derive": {
+     "description": "Derive indexable columns from the selected spatial member instead of indexing it: 'geohash' (one TEXT cell column, precision required) or 'bbox' (four REAL columns — west, south, east, north). A derived index is never unique.",
+     "enum": [
+      "geohash",
+      "bbox"
+     ]
+    },
+    "precision": {
+     "description": "Geohash cell length in characters, 1-12. Required beside derive: 'geohash' and refused anywhere else — there is no safe default, because the right cell size depends on the query radius, which the model cannot know.",
+     "type": "integer",
+     "minimum": 1,
+     "maximum": 12
     }
    },
    "required": [
@@ -125,7 +138,7 @@
     },
     "x-rename": {
      "type": "string",
-     "description": "Declares this entity as the rename of the named from-model entity (MIGRATION-FORMAT \u00a79): a rename is declared, never inferred."
+     "description": "Declares this entity as the rename of the named from-model entity (MIGRATION-FORMAT §9): a rename is declared, never inferred."
     }
    },
    "required": [

package/src/algebra.js

@@ -15,7 +15,7 @@
  */
 
 /** The plan format version, carried on every plan. */
-export const PLAN_VERSION = 1;
+export const PLAN_VERSION = 2;
 
 /**
  * @typedef {{ segments: ({ name: string } | { index: number })[],
@@ -35,8 +35,23 @@ export const PLAN_VERSION = 1;
  *   { p: 'strop', kind: 'starts' | 'ends' | 'contains',
  *     ref: PlanRef, operand: PlanOperand } |
  *   { p: 'const', value: boolean } |
- *   { p: 'udf', name: string, key: string }
+ *   { p: 'udf', name: string, key: string } |
+ *   { p: 'bboxOverlap', columns: { w: string, s: string, e: string,
+ *     n: string }, probe: { box: number[] } | { ext: string } } |
+ *   { p: 'cellIn', column: string, cells: string[] } |
+ *   { p: 'cellPrefix', column: string, prefix: string }
  * )} PlanPredicate
+ *   The last three are the SPATIAL forms: predicates over the derived
+ *   index columns a model declares, which a spatial conjunct either
+ *   translates to exactly or is proven to IMPLY. `bboxOverlap` is true
+ *   when the row's stored box meets the probe's (touching edges count,
+ *   as the kernel's `bboxIntersects` does); `cellIn` when the row's
+ *   cell is one of the listed ones (the nine-cell neighbourhood, or a
+ *   single whole cell); `cellPrefix` when it begins with a shorter one.
+ *   None carries a `json_type` guard — the derived column IS the value
+ *   — but each is TOTAL through its own `IS NOT NULL`, so a row with no
+ *   box or no cell answers FALSE rather than SQL's NULL and negation
+ *   still composes classically.
  *
  * @typedef {{ ref: PlanRef, desc: boolean, emptyGreatest: boolean }} PlanOrderTerm
  *

package/src/ddl.js

@@ -17,6 +17,7 @@
 import { analyzeQuery } from '@jarenjs/json/query';
 import { DbCompileError } from './errors.js';
 import { chain } from './driver.js';
+import { BBOX_COMPONENTS, BBOX_INDEX_ORDER } from './derive.js';
 
 /** The fixed physical column names of the 0.1 mapping. */
 export const KEY_COLUMN = 'key';
@@ -76,15 +77,15 @@ export function compileIndexPath(expression, docPath) {
 }
 
 /**
- * The declared schema type at a segment path, walked structurally
- * through `properties` / `items` / `prefixItems`. The collection's
- * schema is the type source — that is why the physical mapping needs
- * no engine-side inference.
+ * The schema subschema at a segment path, walked structurally through
+ * `properties` / `items` / `prefixItems`. The collection's schema is
+ * the type source — that is why the physical mapping needs no
+ * engine-side inference. `undefined` where the walk leaves the schema.
  * @param {any} schema
  * @param {import('./dialect.js').JsonPathSegment[]} segments
- * @returns {string | undefined}
+ * @returns {any}
  */
-export function schemaTypeAt(schema, segments) {
+export function schemaNodeAt(schema, segments) {
   let node = schema;
   for (const segment of segments) {
     if (node === null || typeof node !== 'object') return undefined;
@@ -92,7 +93,21 @@ export function schemaTypeAt(schema, segments) {
       ? node.properties?.[segment.name]
       : node.prefixItems?.[segment.index] ?? node.items;
   }
-  if (node === null || typeof node !== 'object') return undefined;
+  return node === null || typeof node !== 'object' ? undefined : node;
+}
+
+/**
+ * The declared schema type at a segment path: the first non-`null`
+ * member of a union, which is the type a COLUMN takes its storage
+ * from. A caller that must know the whole union (a promotion refusing
+ * a member that may also be `null`) reads {@link schemaNodeAt}.
+ * @param {any} schema
+ * @param {import('./dialect.js').JsonPathSegment[]} segments
+ * @returns {string | undefined}
+ */
+export function schemaTypeAt(schema, segments) {
+  const node = schemaNodeAt(schema, segments);
+  if (node === undefined) return undefined;
   if (typeof node.type === 'string') return node.type;
   if (Array.isArray(node.type)) {
     return node.type.find((t) => typeof t === 'string' && t !== 'null');
@@ -100,39 +115,139 @@ export function schemaTypeAt(schema, segments) {
   return undefined;
 }
 
+/** The scalar schema types a derived index cannot be declared over. */
+const SCALAR_TYPES = new Set(['string', 'integer', 'number', 'boolean']);
+
 /**
  * A stable generated-column name for a canonical path: readable where
  * the path is tame, disambiguated by suffix where sanitizing collides.
+ *
+ * A DERIVED index names its columns from the same stem plus what makes
+ * the derivation distinct — the kind, and the geohash precision, since
+ * two precisions over one path are legitimately two column sets (a
+ * coarse bucketing index and a fine proximity one). A bbox derivation
+ * owns FOUR columns under one stem, so every one of them is claimed
+ * before the stem is accepted.
  * @param {string} canonical
- * @param {Map<string, string>} byCanonical - canonical -> column name
+ * @param {Map<string, string>} byKey - identity -> column name (or stem)
  * @param {Set<string>} taken
+ * @param {{ key?: string, suffix?: string, parts?: readonly string[] }} [options]
  * @returns {string}
  */
-function generatedColumnName(canonical, byCanonical, taken) {
-  const existing = byCanonical.get(canonical);
+function generatedColumnName(canonical, byKey, taken, options = undefined) {
+  const key = options?.key ?? canonical;
+  const existing = byKey.get(key);
   if (existing !== undefined) return existing;
-  const base = `gx_${canonical.replace(/[^A-Za-z0-9]+/g, '_').replace(/^_+|_+$/g, '')}`;
+  const stem = `gx_${canonical.replace(/[^A-Za-z0-9]+/g, '_').replace(/^_+|_+$/g, '')}`;
+  const base = options?.suffix === undefined ? stem : `${stem}_${options.suffix}`;
+  const parts = options?.parts ?? [''];
+  const claims = (/** @type {string} */ candidate) =>
+    parts.map((part) => (part === '' ? candidate : `${candidate}_${part}`));
   let name = base;
-  for (let i = 2; taken.has(name); i++) name = `${base}_${i}`;
-  byCanonical.set(canonical, name);
-  taken.add(name);
+  for (let i = 2; claims(name).some((claimed) => taken.has(claimed)); i++)
+    name = `${base}_${i}`;
+  byKey.set(key, name);
+  for (const claimed of claims(name)) taken.add(claimed);
   return name;
 }
 
+/**
+ * The columns one derived index contributes, appended to the plan's
+ * `generated` (the physical column list) and `derived` (what the write
+ * path and the migration backfill need to recompute a value).
+ *
+ * `derive` changes what is COMPUTED from the member, never how the
+ * member is selected — so the schema is still the type source, and a
+ * derivation over a path the schema types as a scalar is refused here
+ * rather than at the first query that returns nothing.
+ * @param {any} index - the normalized index declaration
+ * @param {any} context
+ * @returns {string[]} the column names the index covers, in order
+ */
+function deriveColumns(index, context) {
+  const {
+    collection, dialect, stored, segments, canonical, pathText,
+    columnByCanonical, taken, generated, derived,
+  } = context;
+  const declaredType = schemaTypeAt(collection.schema, segments);
+  if (declaredType !== undefined && SCALAR_TYPES.has(declaredType)) {
+    throw new DbCompileError('JD0004',
+      `the index path '${index.paths[0]}' is typed '${declaredType}' by the schema, and a `
+      + `${index.derive} index derives from a position or a geometry — an array or an object`,
+      `${index.docPath}/derive`);
+  }
+  const isGeohash = index.derive === 'geohash';
+  // the identity that decides column SHARING: two indexes over the same
+  // path with the same derivation and the same precision are one column
+  // set; two precisions over one path are two, and legitimately so
+  const key = `${canonical}|${index.derive}|${index.precision ?? ''}`;
+  const stem = generatedColumnName(canonical, columnByCanonical, taken, {
+    key,
+    suffix: isGeohash ? `gh${index.precision}` : 'bbox',
+    parts: isGeohash ? undefined : BBOX_COMPONENTS,
+  });
+  const type = dialect.typeFor(isGeohash ? 'string' : 'number', 'generated');
+  const components = isGeohash ? [undefined] : BBOX_COMPONENTS;
+  const nameOf = (/** @type {string | undefined} */ component) =>
+    (component === undefined ? stem : `${stem}_${component}`);
+  if (!generated.some((column) => column.name === nameOf(components[0]))) {
+    for (const component of components) {
+      const column = {
+        name: nameOf(component),
+        type,
+        pathText,
+        canonical,
+        derive: index.derive,
+        precision: index.precision,
+        component,
+        stored,
+      };
+      generated.push({
+        ...column,
+        expression: stored ? null : dialect.derivedColumn(
+          dialect.quoteIdentifier(DOC_COLUMN), pathText, column),
+      });
+      derived.push({
+        name: column.name,
+        derive: index.derive,
+        precision: index.precision,
+        component,
+        segments,
+      });
+    }
+  }
+  // the index COVERS its columns in (w, e, s, n) order, which is not
+  // their declaration order — see BBOX_INDEX_ORDER
+  return isGeohash ? [stem] : BBOX_INDEX_ORDER.map((component) => nameOf(component));
+}
+
 /**
  * Plan one collection's physical shape: the DDL statements to create
  * it and the structural facts an existing table must match (the
  * `JD0002` comparison set).
+ * A derived index (`derive: 'geohash' | 'bbox'`) maps to the same
+ * shape through a registered deterministic function, EXCEPT where the
+ * driver cannot index one (`capabilities.deterministicIndexableFunctions`
+ * is false): there the columns are ordinary ones the store writes. The
+ * two mappings produce different declared text on purpose — a database
+ * built under one and opened under the other really does disagree, and
+ * `verifyShape` says so rather than papering over it.
  * @param {string} name - The collection name (also the table name)
  * @param {{ schema: any, keySegments: { name: string }[] | null,
  *   identity: string, indexes: { name: string, paths: string[],
- *   unique: boolean, docPath: string }[] }} collection - normalized
+ *   unique: boolean, derive?: string | null, precision?: number,
+ *   docPath: string }[] }} collection - normalized
  * @param {any} dialect
+ * @param {{ derived?: 'virtual' | 'stored' }} [options] - the physical
+ *   mapping for derived columns; `'virtual'` (a generated column over a
+ *   registered function) unless the driver says it cannot index one
  * @returns {{
  *   table: string, keyColumn: string, docColumn: string,
  *   keyType: string,
  *   generated: { name: string, type: string, pathText: string,
  *     canonical: string }[],
+ *   derived: { name: string, derive: string, precision?: number,
+ *     component?: string, segments: any[] }[],
  *   columnByCanonical: Map<string, string>,
  *   createSql: string[],
  *   expected: { columns: { name: string, type: string,
@@ -140,7 +255,8 @@ function generatedColumnName(canonical, byCanonical, taken) {
  *     columns: string[] }[] },
  * }}
  */
-export function planCollection(name, collection, dialect) {
+export function planCollection(name, collection, dialect, options = undefined) {
+  const stored = options?.derived === 'stored';
   const keyType = collection.identity === 'integer'
     ? dialect.typeFor('integer', 'key')
     : collection.identity === 'uuid'
@@ -154,6 +270,8 @@ export function planCollection(name, collection, dialect) {
   const taken = new Set([KEY_COLUMN, DOC_COLUMN]);
   /** @type {{ name: string, type: string, pathText: string, canonical: string }[]} */
   const generated = [];
+  /** @type {any[]} */
+  const derived = [];
   /** @type {{ name: string, unique: boolean, columns: string[] }[]} */
   const indexes = [];
 
@@ -168,6 +286,13 @@ export function planCollection(name, collection, dialect) {
           `the index path '${index.paths[i]}' names a member the dialect's JSON path grammar cannot carry`,
           pathDocPath);
       }
+      if (index.derive) {
+        columns.push(...deriveColumns(index, {
+          collection, dialect, stored, segments, canonical, pathText,
+          columnByCanonical, taken, generated, derived,
+        }));
+        continue;
+      }
       const known = columnByCanonical.has(canonical);
       const columnName = generatedColumnName(canonical, columnByCanonical, taken);
       if (!known) {
@@ -210,13 +335,17 @@ export function planCollection(name, collection, dialect) {
     docColumn: DOC_COLUMN,
     keyType,
     generated,
+    derived,
     columnByCanonical,
     createSql,
     expected: {
       columns: [
         { name: KEY_COLUMN, type: keyType, generated: false },
         { name: DOC_COLUMN, type: dialect.docColumnType, generated: false },
-        ...generated.map((g) => ({ name: g.name, type: g.type, generated: true })),
+        // a STORED derived column is an ordinary one: the flag is what
+        // `pragma_table_xinfo` reports, and it is the difference a file
+        // moved between the two physical mappings shows up as
+        ...generated.map((g) => ({ name: g.name, type: g.type, generated: g.stored !== true })),
       ],
       indexes: indexes
         // the COLUMNS keep their declared order — an index is ordered, and

package/src/derive.js

@@ -0,0 +1,284 @@
+//@ts-check
+/**
+ * @file Derived index columns: the one place a declared
+ * `indexes[].derive` becomes a value. A spatial member is an array of
+ * numbers or an object, and a generated column must be a scalar, so a
+ * geohash cell or a bounding-box edge is what actually gets indexed.
+ *
+ * Every cell and every box comes from `@jarenjs/core/geo`; nothing
+ * here computes spatial arithmetic of its own. The same functions
+ * serve BOTH physical mappings — registered as deterministic SQL
+ * functions inside a virtual generated column's expression where the
+ * driver can index them, and called directly on the write path where
+ * it cannot — so the two branches cannot drift into different answers.
+ *
+ * It is also this package's ONLY seam onto `@jarenjs/core/geo` (D1 —
+ * one home for spatial arithmetic, grep-proven by test): the planner's
+ * probe geometry — the box of a literal or bound region, the box of a
+ * bounded-distance circle, a cell's neighbourhood — is computed by the
+ * helpers below rather than by an import of its own.
+ *
+ * Determinism is the contract, not a convenience: a value here is a
+ * pure function of the document bytes. Nothing reads the clock, a
+ * random source or store state, because an INDEX over a function that
+ * did would make the database unreadable from a connection whose
+ * function answered differently — and unreadable, not merely wrong:
+ * a connection that has not registered the function at all cannot even
+ * SELECT the table (probed). That hazard is why the mapping is
+ * capability-gated rather than always-on.
+ */
+
+import {
+  bboxOf, centroidOf, circleBounds, geohashEncode, geohashNeighbours,
+} from '@jarenjs/core/geo';
+
+import { chain } from './driver.js';
+
+/** The closed set of derive kinds. */
+export const DERIVE_KINDS = new Set(['geohash', 'bbox']);
+
+/** A bbox index's four columns, in the order they are declared —
+ * `[west, south, east, north]`, the order the kernel's boxes carry. */
+export const BBOX_COMPONENTS = Object.freeze(['w', 's', 'e', 'n']);
+
+/**
+ * The order a bbox index COVERS its four columns, which is not the
+ * order they are declared in: an intersection test reads
+ * `w <= ? AND e >= ? AND s <= ? AND n >= ?`, so the two longitude
+ * bounds sit together at the front of the index where a leading-column
+ * range can use them. `(a,b)` and `(b,a)` are different indexes.
+ */
+export const BBOX_INDEX_ORDER = Object.freeze(['w', 'e', 's', 'n']);
+
+/** Where each component sits in `[west, south, east, north]`. */
+const BBOX_AT = { w: 0, s: 1, e: 2, n: 3 };
+
+/** The declared geohash precision range (characters). */
+export const PRECISION_MIN = 1;
+export const PRECISION_MAX = 12;
+
+/**
+ * The representative position of any GeoJSON value: the position
+ * itself for a bare `[lon, lat]` or a Point, the mean vertex
+ * otherwise. Null when there is no position, and null when any
+ * position is non-finite — `centroidOf` propagates a NaN through the
+ * mean, so the finiteness of the result is the whole-value test.
+ * @param {any} value
+ * @returns {number[] | null}
+ */
+function representativePosition(value) {
+  const centre = centroidOf(value);
+  if (centre === null) return null;
+  return Number.isFinite(centre[0]) && Number.isFinite(centre[1]) ? centre : null;
+}
+
+/**
+ * The geohash cell of a value at a precision, or null when the value
+ * carries no bounded position.
+ * @param {any} value
+ * @param {number} precision
+ * @returns {string | null}
+ */
+export function deriveGeohash(value, precision) {
+  const position = representativePosition(value);
+  return position === null ? null : geohashEncode(position[0], position[1], precision);
+}
+
+/**
+ * One edge of a value's bounding box, or null when it has none —
+ * including the D6 case where a non-finite coordinate refuses the box
+ * rather than producing one that does not bound its input.
+ * @param {any} value
+ * @param {string} component - `'w'`, `'s'`, `'e'` or `'n'`
+ * @returns {number | null}
+ */
+export function deriveBboxEdge(value, component) {
+  const box = bboxOf(value);
+  return box === null ? null : box[BBOX_AT[component]];
+}
+
+/**
+ * A member as the database will hold it. A derived value must be a
+ * function of the STORED document, not of the object handed to the
+ * write: JSON has no `NaN` and no `Infinity`, so a non-finite
+ * coordinate becomes `null` on the way in and is no longer a position
+ * at all. Computing from the in-memory value would make the two
+ * physical mappings answer differently for the same document, which is
+ * the one thing they may never do.
+ *
+ * Only the indexed MEMBER round-trips, not the whole document — it is
+ * the only part a derived column reads.
+ * @param {any} member
+ * @returns {any} the member as stored, or `undefined` when there is none
+ */
+export function storedMemberForm(member) {
+  if (member === undefined) return undefined;
+  const text = JSON.stringify(member);
+  return text === undefined ? undefined : JSON.parse(text);
+}
+
+/**
+ * The value of one derived column for a document member.
+ * @param {{ derive: string, precision?: number, component?: string }} column
+ * @param {any} member - the value at the index path, or `undefined`
+ * @returns {string | number | null}
+ */
+export function derivedValue(column, member) {
+  if (member === undefined || member === null) return null;
+  return column.derive === 'geohash'
+    ? deriveGeohash(member, /** @type {number} */ (column.precision))
+    : deriveBboxEdge(member, /** @type {string} */ (column.component));
+}
+
+/**
+ * Read the member one derived column is computed from, walking the
+ * same typed segments the physical mapping was planned over.
+ * @param {any} doc
+ * @param {import('./dialect.js').JsonPathSegment[]} segments
+ * @returns {any} the member, or `undefined`
+ */
+export function memberAt(doc, segments) {
+  let node = doc;
+  for (const segment of segments) {
+    if (node === null || typeof node !== 'object') return undefined;
+    node = 'name' in segment ? node[segment.name] : node[segment.index];
+  }
+  return node;
+}
+
+/**
+ * Parse the JSON text a derived column's expression hands the function.
+ * SQLite passes SQL NULL for a member the document does not have, and
+ * `json()` of an extracted member is unambiguous JSON text otherwise.
+ * @param {any} text
+ * @returns {any} the value, or `undefined` when there is none
+ */
+function parseMember(text) {
+  if (typeof text !== 'string') return undefined;
+  try {
+    return JSON.parse(text);
+  }
+  catch {
+    return undefined;
+  }
+}
+
+/**
+ * Register the deterministic functions the virtual generated columns
+ * call. Idempotent per connection by SQLite's own semantics (a second
+ * registration replaces the first with the identical implementation),
+ * and a no-op where the driver cannot index a registered function —
+ * that branch stores the columns instead.
+ *
+ * The four bbox edges share a one-entry memo of the last text they
+ * were asked about, because they are called back to back with the same
+ * argument for one row and the box costs a full walk of the geometry.
+ * The memo is keyed on the argument itself, so it changes no answer.
+ * @param {any} connection
+ * @returns {any} value-or-promise
+ */
+export function registerDeriveFunctions(connection) {
+  if (connection.capabilities?.deterministicIndexableFunctions !== true
+    || typeof connection.registerFunction !== 'function') return null;
+  /** @type {any} */
+  let memoText = null;
+  /** @type {number[] | null} */
+  let memoBox = null;
+  const boxOf = (/** @type {any} */ text) => {
+    if (text === memoText) return memoBox;
+    const value = parseMember(text);
+    memoBox = value === undefined ? null : bboxOf(value);
+    memoText = text;
+    return memoBox;
+  };
+  /** @type {[string, Function][]} */
+  const registrations = [
+    ['jaren_geohash', (/** @type {any} */ text, /** @type {any} */ precision) => {
+      const value = parseMember(text);
+      return value === undefined ? null : deriveGeohash(value, Number(precision));
+    }],
+  ];
+  for (const component of BBOX_COMPONENTS) {
+    registrations.push([`jaren_bbox_${component}`, (/** @type {any} */ text) => {
+      const box = boxOf(text);
+      return box === null ? null : box[BBOX_AT[component]];
+    }]);
+  }
+  const step = (i) => (i >= registrations.length
+    ? null
+    : chain(connection.registerFunction(registrations[i][0],
+      { deterministic: true }, registrations[i][1]), () => step(i + 1)));
+  return step(0);
+}
+
+// ————— Probe geometry: what a PUSHED predicate compares against —————
+//
+// A promoted spatial predicate narrows through the derived columns by
+// comparing them with a box (or a cell) computed from the query's own
+// operand. That operand is known either at plan time (a literal region)
+// or at bind time (an external one), and both go through here so the
+// two answer identically and neither reaches past this file for its
+// arithmetic.
+
+/**
+ * The bounding box of a probe value, or `null` when it has none — the
+ * D6 refusal included, which is what makes an unbounded probe divert to
+ * the full scan instead of narrowing with a box that does not bound it.
+ * @param {any} value - a GeoJSON value or a `[lon, lat]` position
+ * @returns {number[] | null} `[west, south, east, north]`
+ */
+export function probeBox(value) {
+  return bboxOf(value);
+}
+
+/**
+ * The representative position §8.14 measures a probe value by — the
+ * same rule the derived columns use, so the pushed filter and the
+ * engine cannot disagree about where a value IS. `null` when it has no
+ * bounded position.
+ * @param {any} value
+ * @returns {number[] | null}
+ */
+export function probePosition(value) {
+  return representativePosition(value);
+}
+
+/**
+ * The bounding box of the circle of `metres` around a position — the
+ * box a `$distance <= r` predicate narrows with, on the same sphere and
+ * the same radius constant the engine measures with. `null` when the
+ * radius is not a finite non-negative number, or when the circle
+ * reaches a pole, where there is no longitude bound to give.
+ * @param {number[]} position
+ * @param {number} metres
+ * @returns {number[] | null} `[west, south, east, north]`, NOT wrapped
+ *   into `[-180, 180]`: a circle spanning the antimeridian answers a
+ *   west below -180, which is how the planner detects it
+ */
+export function probeCircleBox(position, metres) {
+  return circleBounds(position[0], position[1], metres);
+}
+
+/**
+ * A cell and its neighbours, the nine-cell probe D7 requires — a single
+ * prefix is bucketing, never proximity.
+ * @param {string} cell
+ * @returns {string[]} up to nine cells (fewer past a pole)
+ */
+export function cellNeighbourhood(cell) {
+  return geohashNeighbours(cell);
+}
+
+/**
+ * The value one DERIVED parameter slot binds: an axis of a bound
+ * external's bounding box, computed at bind time because a GeoJSON
+ * object is not a value any database can bind. `null` when the value
+ * has no box, which is what tells the caller to divert.
+ * @param {{ kind: string, external: string, axis: string }} derived
+ * @param {any} value - the bound external
+ * @returns {number | null}
+ */
+export function derivedSlotValue(derived, value) {
+  const box = bboxOf(value);
+  return box === null ? null : box[BBOX_AT[derived.axis]];
+}