@jarenjs/db 0.34.0 → 0.43.1

package/ARCHITECTURE.md

@@ -66,6 +66,11 @@ binds arrays.
   generated columns. The plan carries both the CREATE statements and
   the structural facts an existing table must match (`JD0002` when it
   does not — nothing is ever altered).
+- `src/derive.js` — the one place a declared `derive` becomes a value.
+  A geohash cell or a bounding-box edge from `@jarenjs/core/geo`, and
+  the deterministic SQL functions a generated column's expression
+  calls. The SAME functions serve both physical mappings, so the two
+  branches cannot drift into different answers.
 - `src/patch-sql.js` — RFC 6902 to JSON-set primitives, discriminated
   against the live document (a pointer cannot say array-or-object on
   its own). Untranslatable operations fall back to a whole-document
@@ -127,7 +132,9 @@ below, and that table's reasons are what `explain()` reports.
 
 ### The translated set
 
-A single-binding FLWOR over the collection (`$for: { it: '$[*]' }`)
+A single-binding FLWOR over the collection (`$for: { <name>: '$[*]' }`
+— the examples here write `it`, but the binding is the **document's** to
+name and nothing translates differently under another one)
 with: comparison predicates (`$eq $ne $lt $le $gt $ge`) between a
 singular member path and a literal or external; `$and`/`$or`/`$not`
 composition; `$exists`/`$empty`; `$starts-with`/`$ends-with`/
@@ -136,7 +143,15 @@ composition; `$exists`/`$empty`; `$starts-with`/`$ends-with`/
 collation); a top-level `$subsequence` window with literal bounds; the
 top-level aggregates `$count` (bare-binding return only) and
 `$sum`/`$avg`/`$min`/`$max` over a singular schema-typed path; and the
-whole-document projection `$return: '$it'`.
+whole-document projection that returns the bare binding.
+
+Plus the spatial predicates a **derived** index makes decidable:
+`$bbox-intersects` against a literal or external region, a geohash
+prefix no longer than a `derive: 'geohash'` column's precision, and the
+nine-cell neighbourhood probe over that same column — each over a
+member the schema types as an array or an object. Those are exact; the
+spatial predicates that only NARROW are rows in the residual table, and
+the implied-conjunct table below carries every proof.
 
 ### The deliberate-residual table
 
@@ -150,7 +165,11 @@ whole-document projection `$return: '$it'`.
 | string operators with an external pattern | the pattern's type is unknowable at plan time and the engine ERRORS on non-string patterns |
 | comparisons where both sides are paths | join territory |
 | array/object literals in comparisons | deep-equality has no guarded native form |
-| spatial predicates | no spatial index vocabulary in the model format |
+| `$within` over a `derive: 'bbox'` column | a bounding-box pre-filter is pushed; exact containment refines in the engine |
+| a bounded `$distance` over a `derive: 'bbox'` column | a geodesic-circle box pre-filter is pushed; the exact distance refines in the engine |
+| a geohash prefix LONGER than the column's precision | a cell-range pre-filter over the derived column's precision is pushed; the longer prefix refines in the engine |
+| a spatial predicate over a member with no matching derived index, or one the schema does not type as an array or an object | nothing is proven; the whole predicate runs in the engine (the deterministic-function hatch may still take it) |
+| an unbounded `$distance` (`>= r`), a circle reaching a pole or crossing the antimeridian, a probe with no bounding box | no conservative box exists — pushing nothing is correct, pushing a wrong box is not |
 
 ### The type truth table
 
@@ -189,10 +208,20 @@ generated column where one exists), `?` = the bound operand:
 | `$eq` path, external | `(jt = 'text' AND typeof(?) = 'text' AND v = ?) OR (jt IN ('integer','real') AND typeof(?) IN ('integer','real') AND v = ?)` |
 | `$ne` path, external | `jt IS NOT NULL AND NOT (…the $eq form…)` |
 | ordering vs external | the same two-branch form with `op` |
-| `$starts-with` path, string | `jt = 'text' AND substr(v, 1, length(?)) = ?` |
+| `$starts-with` path, string | `jt = 'text' AND (v >= ? AND v < ?)` — the prefix and its code-point successor |
 | `$ends-with` path, string | `jt = 'text' AND (length(?) = 0 OR substr(v, -length(?)) = ?)` |
 | `$contains` path, string | `jt = 'text' AND instr(v, ?) > 0` |
 
+**The prefix predicate is index-usable, and the other two are not.**
+`$starts-with` emits a half-open range over the value, so a declared
+index on that path is *seeked*, not scanned — worth declaring one for.
+The bounds are computed at emit time, which the planner's own rule
+makes exact: a string operator translates only with a literal,
+non-empty pattern, so its code-point successor is known there. (A
+pattern of nothing but U+10FFFF has no successor and falls back to the
+scannable `substr` form.) `$ends-with` and `$contains` have no
+index-usable spelling and read every row of the collection.
+
 The guards make the forms sound for typed AND untyped paths alike —
 the schema type's job is choosing the generated COLUMN (the index),
 never weakening the guard. Two documented preconditions: string
@@ -209,14 +238,78 @@ matters to you.
 execute time, if any referenced external is missing or not a string or
 finite number, the call runs the always-compiled set residual instead
 of the native statement — same answer, one branch, no wrong-typed SQL.
+A **derived** slot is the exception that proves it: a GeoJSON region is
+not bindable at all, so what binds is one edge of its bounding box per
+slot, computed at bind time; such a call diverts only when the bound
+value has no box.
+
+### The implied conjunct (spatial)
+
+Every conjunct above is a conjunct **of the document**: it translates
+exactly or it does not. A spatial predicate mostly cannot — there is no
+`ST_Within` in SQLite and this package does not build one — but it
+*implies* one that can be, over the columns a model declares with
+`indexes[].derive` (MODEL-FORMAT §2.1).
+
+> An **implied conjunct** is a predicate the planner ADDS to the SQL
+> that is not in the document, proven below to be implied by one that
+> is. It narrows; it never decides. The conjunct it came from stays in
+> the residual.
+
+Three properties make that safe, and each is asserted by test: **no
+false negatives** (every row the document's predicate keeps passes the
+implied one — the proofs below); **idempotent refinement** (the residual
+re-runs the original predicate over the narrowed candidates, which is
+why an implied conjunct forces the SET residual and not the row one);
+and **`strict: true` refuses it** (an implied conjunct leaves its own
+reason behind, so the plan is never native and `JD0010` names it).
+
+Throughout, `B(v)` is the value's bounding box and `<c>_w`/`_s`/`_e`/`_n`
+are a `bbox` index's columns; `<c>` is a `geohash` index's column at its
+declared precision `k`. Every promotion requires the schema to type the
+member as an array or an object **and nothing else** — §8.14 answers
+`JQ2001` for a non-geographic operand, and a union that also admits
+`null` is not geography.
+
+| Jaren predicate | pushed | exact? | why it is implied |
+|---|---|---|---|
+| `$bbox-intersects(<path>, <literal\|external>)` | `w <= L_e AND e >= L_w AND s <= L_n AND n >= L_s` | **exact** | the derived columns ARE `B(row)`, so box overlap is fully decidable. `<=`/`>=`, not `<`/`>`: the kernel counts touching edges as intersecting, and a strict comparison would disagree on every shared edge |
+| `$within(<path>, <literal\|external>)` | the same four comparisons against `B(area)` | implied | the representative position is inside `B(subject)` — a bare position IS the box, and a centroid is a mean of positions, which lies within their min/max — and inside the area's surface implies inside `B(area)`; so the two boxes share at least that position ∎ |
+| `{$le\|$lt: [{$distance: [<path>, <literal>]}, r]}` | the same four comparisons against `circleBounds(probe, r)` | implied | every position within `r` metres lies inside the circle's box, which the kernel computes on the same sphere and the same `EARTH_RADIUS` the engine measures with — so the two cannot disagree by model. `$ge`/`$gt` is NOT promoted: no box narrows "farther than r" |
+| `{$starts-with: [{$geohash: [<path>, k]}, "<cell>"]}`, cell length ≤ k | `<c> IN ("<cell>")` or `<c> >= "<cell>" AND <c> < successor` | **exact** | the column HOLDS `$geohash(row, k)`, and geohash is a prefix code, so a prefix test on the expression is the same test on the column |
+| the same, cell length > k | the cell truncated to k | implied | the column can only confirm its own first k characters |
+| `{$exists: {$index-of: [{$geohash-neighbours: "<cell>"}, {$geohash: [<path>, k]}]}}`, cell length = k | `<c> IN (…the nine cells…)` | **exact** | the membership test compares whole strings and the column is exactly one of them. Nine cells, never one: two points ten metres apart can differ in the FIRST character of their cell (D7), so a single prefix is bucketing and only the neighbourhood is proximity |
+
+The implied forms carry no `json_type` guard — a derived column IS the
+value — but each is TOTAL through its own `IS NOT NULL`, so a row with
+no box answers `FALSE` rather than SQL's `NULL` and negation composes
+classically. An implied conjunct may not be negated at all: negating a
+superset is a subset, and that drops rows. That guard also makes the
+leading term a two-sided range, which is what SQLite will actually
+**seek**: with a one-sided range it prefers a table scan, and a scan over
+a virtual generated column pays a registered-function call per row.
+
+**A pre-filter decides which rows the engine SEES, so it also decides
+which rows can raise.** The row set is unchanged — that is what the
+table above proves — but a row the pre-filter excludes never reaches
+the engine and therefore never throws: a stored `null` under a member
+the schema types as geography, or a value with no bounded position
+under §8.14's membership recipe (`$index-of` refuses an empty search
+item). This is the same class as the string-operator and aggregate
+preconditions above, and the same answer: keep `compileSchema` injected
+if that distinction matters to you.
 
 ### The two residual modes
 
 - **Row residual** — only the projection is untranslated: predicates,
   ordering and the window are fully pushed; each fetched row runs
-  `{ $for: { it: '$[*]' }, $return: [ <the document's $return> ] }`
-  (the array wrapper keeps array-valued items unambiguous) and the
-  items concatenate in row order. Streams.
+  `{ $for: { <the document's own binding>: '$[*]' },
+  $return: [ <the document's $return> ] }` (the array wrapper keeps
+  array-valued items unambiguous) and the items concatenate in row
+  order. Streams. **The planner emits that one-row document whole**,
+  binding included, rather than handing the projection to be re-wrapped
+  elsewhere: the wrapper must bind what the projection references, and
+  only the planner knows what the caller called it.
 - **Set residual** — anything else: the pushed predicate conjuncts
   narrow candidates (`$and` splits; a partially translatable `$or`
   does not), and the WHOLE original compiled document runs over the
@@ -227,13 +320,18 @@ of the native statement — same answer, one branch, no wrong-typed SQL.
 
 Extends `compileJsonQuery(...).explain()`'s shape — `{ externals,
 operators, functions, collations, limits }` — with `{ sql, params,
-indexes, residual, barriers, scanNarrative }`. `params` lists the
-bound slots in order (external names and literal markers — values are
-ALWAYS bound, never interpolated). `indexes` names the declared
+indexes, prefilters, residual, barriers, scanNarrative }`. `params`
+lists the bound slots in order (external names, literal markers, and
+derived slots naming the external and box axis they compute — values
+are ALWAYS bound, never interpolated). `indexes` names the declared
 indexes whose generated columns the pushed predicates and ordering
 touch, and the `scanNarrative` is the database's own `EXPLAIN QUERY
 PLAN` prose so the claim is checkable against the engine that will run
-it. `estimatedRows` is ABSENT on SQLite drivers — the capability slot
+it. `prefilters` is the implied conjuncts — `{ construct, columns,
+exact }` each — because whether a declared index is earning its keep is
+not readable from `sql` alone, and because `indexes` says what a
+predicate TOUCHES while the narrative says what the database will
+DO. `estimatedRows` is ABSENT on SQLite drivers — the capability slot
 is empty and no number is fabricated. `residual` is `null` or
 `{ mode: 'row' | 'set', reasons: [{ construct, reason }] }` with
 reasons drawn from the deliberate-residual table. With
@@ -247,7 +345,12 @@ predicate conjunct as a deterministic function used in the `WHERE`
 clause. Gated on `capabilities.userFunctions` (absent on Bun by
 construction) and applied only to fragments with no externals, no
 functions and no collations — deterministic and side-effect-free by
-analysis, not by hope. Registration is keyed by `contentKey(fragment)`
+analysis, not by hope. The fragment is a raw conjunct over the caller's
+collection binding, so the planner passes that binding's **name** in:
+wrapped under any other name every reference would read as an external,
+the determinism rule would reject the fragment, and the hatch would
+silently not engage — no error and no reason in `explain()`.
+Registration is keyed by `contentKey(fragment)`
 so identical fragments share one registration, and the planner MUST
 produce a correct plan with the capability disabled (tested that way).
 Preference order: native SQL → deterministic function → residual, and

package/README.md

@@ -86,6 +86,53 @@ const adults = await users.execute({
   plus real indexes, typed from the collection's schema. Opening an
   existing database verifies the declared shape and refuses to alter
   it — reshaping is the migration story.
+- **Spatial members get indexable columns.** A position is an array and
+  a geometry is an object, so neither is indexable as it stands. An
+  index declaring `derive: 'geohash'` (with a required `precision`) or
+  `derive: 'bbox'` materializes the cell, or the four box edges, as
+  columns computed by `@jarenjs/core/geo` — a generated column over a
+  registered deterministic function where the driver can index one, and
+  a stored column the store writes where it cannot.
+- **A spatial query is two stages, and `explain()` names both.** A
+  `$within`, a `$bbox-intersects`, a bounded `$distance` or a geohash
+  probe over such a collection narrows **in SQLite** through the index
+  and refines **in the engine**. `$bbox-intersects` and a geohash cell
+  test are exact and need no refinement; `$within` and a bounded
+  `$distance` push a bounding box the truth table proves they imply,
+  and the exact predicate re-runs over the narrowed candidates —
+  `explain().prefilters` says which, over what columns, and whether it
+  decided or merely narrowed.
+
+```js
+// the collection declares  indexes: [{ name: 'by_box', path: '$.at',
+//   derive: 'bbox' }]  and types that member  at: { type: ['array', 'object'] }
+// — a predicate is only PUSHED onto a member the schema types as geography
+const places = store.collection('places');
+const nearby = {
+  $for: { p: '$[*]' },
+  $where: { $within: ['$p.at', '$region'] },
+  $return: '$p',
+};
+await places.execute(nearby, { externals: { region } });
+
+const how = await places.explain(nearby, { externals: { region } });
+how.prefilters;
+// [{ construct: '$within',
+//    columns: ['gx_at_bbox_w', 'gx_at_bbox_e', 'gx_at_bbox_s', 'gx_at_bbox_n'],
+//    exact: false }]
+how.residual.reasons[0].reason;
+// 'a bounding-box pre-filter is pushed; exact containment refines in the engine'
+how.scanNarrative;
+// 'SEARCH places USING INDEX places_by_box (gx_at_bbox_w>? AND gx_at_bbox_w<?); …'
+```
+
+  The region arrives as a bound parameter: a GeoJSON object is not a
+  value any database can bind, so what binds is one edge of its box per
+  slot, computed at bind time from the same kernel the stored columns
+  came from. A circle that reaches a pole or crosses the antimeridian
+  pushes **nothing** — there is no single box to push — and the answer
+  is the same, reached by reading more rows. `explain()` is what makes
+  that checkable rather than quoted.
 - **Migrations are documents.** `planMigration` diffs two models into
   rendered-DDL + JSLT-transform + assertion steps; a shadow database
   replays the whole chain before the real store is touched; a

package/dist/types/algebra.d.ts

@@ -13,7 +13,7 @@
  * design (see ARCHITECTURE.md's deliberate-residual table).
  */
 /** The plan format version, carried on every plan. */
-export declare const PLAN_VERSION = 1;
+export declare const PLAN_VERSION = 2;
 export type PlanRef = {
     segments: ({
         name: string;
@@ -56,6 +56,27 @@ export type PlanPredicate = ({
     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;
 });
 export type PlanOrderTerm = {
     ref: PlanRef;
@@ -96,8 +117,23 @@ export type Plan = {
  *   { 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/dist/types/ddl.d.ts

@@ -27,10 +27,20 @@ export declare function compileIndexPath(expression: string, docPath: string): {
     canonical: string;
 };
 /**
- * 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 {any}
+ */
+export declare function schemaNodeAt(schema: any, segments: import('./dialect.js').JsonPathSegment[]): any;
+/**
+ * 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}
@@ -40,16 +50,29 @@ export declare function schemaTypeAt(schema: any, segments: import('./dialect.js
  * 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,
@@ -67,9 +90,13 @@ export declare function planCollection(name: string, collection: {
         name: string;
         paths: string[];
         unique: boolean;
+        derive?: string | null;
+        precision?: number;
         docPath: string;
     }[];
-}, dialect: any): {
+}, dialect: any, options?: {
+    derived?: 'virtual' | 'stored';
+}): {
     table: string;
     keyColumn: string;
     docColumn: string;
@@ -80,6 +107,13 @@ export declare function planCollection(name: string, collection: {
         pathText: string;
         canonical: string;
     }[];
+    derived: {
+        name: string;
+        derive: string;
+        precision?: number;
+        component?: string;
+        segments: any[];
+    }[];
     columnByCanonical: Map<string, string>;
     createSql: string[];
     expected: {

package/dist/types/derive.d.ts

@@ -0,0 +1,161 @@
+/**
+ * @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.
+ */
+/** The closed set of derive kinds. */
+export declare const DERIVE_KINDS: Set<string>;
+/** A bbox index's four columns, in the order they are declared —
+ * `[west, south, east, north]`, the order the kernel's boxes carry. */
+export declare const BBOX_COMPONENTS: readonly string[];
+/**
+ * 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 declare const BBOX_INDEX_ORDER: readonly string[];
+/** The declared geohash precision range (characters). */
+export declare const PRECISION_MIN = 1;
+export declare const PRECISION_MAX = 12;
+/**
+ * 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 declare function deriveGeohash(value: any, precision: number): string | null;
+/**
+ * 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 declare function deriveBboxEdge(value: any, component: string): number | null;
+/**
+ * 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 declare function storedMemberForm(member: any): any;
+/**
+ * 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 declare function derivedValue(column: {
+    derive: string;
+    precision?: number;
+    component?: string;
+}, member: any): string | number | null;
+/**
+ * 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 declare function memberAt(doc: any, segments: import('./dialect.js').JsonPathSegment[]): any;
+/**
+ * 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 declare function registerDeriveFunctions(connection: any): any;
+/**
+ * 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 declare function probeBox(value: any): number[] | null;
+/**
+ * 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 declare function probePosition(value: any): number[] | null;
+/**
+ * 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 declare function probeCircleBox(position: number[], metres: number): number[] | null;
+/**
+ * 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 declare function cellNeighbourhood(cell: string): string[];
+/**
+ * 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 declare function derivedSlotValue(derived: {
+    kind: string;
+    external: string;
+    axis: string;
+}, value: any): number | null;

package/dist/types/dialect.d.ts

@@ -44,6 +44,8 @@ export type JsonPathSegment = {
  *   limitClause: (limit: number, offset?: number) => string,
  *   jsonPathText: (segments: JsonPathSegment[]) => string | null,
  *   jsonExtract: (columnSql: string, pathText: string) => string,
+ *   derivedExpression?: (memberSql: string, column: { derive: string,
+ *     precision?: number, component?: string }) => string,
  *   jsonSet: (exprSql: string, pathText: string, valueSql: string) => string,
  *   jsonRemove: (exprSql: string, pathText: string) => string,
  *   jsonAppend: (exprSql: string, arrayPathText: string, valueSql: string) => string,
@@ -52,7 +54,8 @@ export type JsonPathSegment = {
  *   jsonAgg: (exprSql: string) => string,
  *   jsonTypeOf: (columnSql: string, pathText: string) => string,
  *   valueTypeOf: (paramSql: string) => string,
- *   strStartsWith: (valueSql: string, patternA: string, patternB: string) => string,
+ *   strStartsWith: (valueSql: string, lowerParamSql: string, upperParamSql: string) => string,
+ *   strStartsWithExact: (valueSql: string, patternA: string, patternB: string) => string,
  *   strEndsWith: (valueSql: string, patternA: string, patternB: string, patternC: string) => string,
  *   strContains: (valueSql: string, patternSql: string) => string,
  *   orderNulls: (nullsFirst: boolean) => string,
@@ -88,6 +91,11 @@ export declare function createDialect(spec: {
     limitClause: (limit: number, offset?: number) => string;
     jsonPathText: (segments: JsonPathSegment[]) => string | null;
     jsonExtract: (columnSql: string, pathText: string) => string;
+    derivedExpression?: (memberSql: string, column: {
+        derive: string;
+        precision?: number;
+        component?: string;
+    }) => string;
     jsonSet: (exprSql: string, pathText: string, valueSql: string) => string;
     jsonRemove: (exprSql: string, pathText: string) => string;
     jsonAppend: (exprSql: string, arrayPathText: string, valueSql: string) => string;
@@ -96,7 +104,8 @@ export declare function createDialect(spec: {
     jsonAgg: (exprSql: string) => string;
     jsonTypeOf: (columnSql: string, pathText: string) => string;
     valueTypeOf: (paramSql: string) => string;
-    strStartsWith: (valueSql: string, patternA: string, patternB: string) => string;
+    strStartsWith: (valueSql: string, lowerParamSql: string, upperParamSql: string) => string;
+    strStartsWithExact: (valueSql: string, patternA: string, patternB: string) => string;
     strEndsWith: (valueSql: string, patternA: string, patternB: string, patternC: string) => string;
     strContains: (valueSql: string, patternSql: string) => string;
     orderNulls: (nullsFirst: boolean) => string;

package/dist/types/driver.d.ts

@@ -28,6 +28,7 @@
  * them without a contract change; pretending SQLite has them is the
  * silent degradation this suite refuses.
  */
+import { isThenable, chain, toPromise } from '@jarenjs/core/function';
 /** The minimum SQLite the store accepts, asserted at open. */
 export declare const SQLITE_FLOOR = "3.45.0";
 /**
@@ -38,26 +39,7 @@ export declare const SQLITE_FLOOR = "3.45.0";
  * busy timeout) or another transaction on this one.
  */
 export declare const DEFAULT_QUEUE_TIMEOUT = 5000;
-/**
- * @param {any} value
- * @returns {boolean} true when the value is a thenable
- */
-export declare function isThenable(value: any): boolean;
-/**
- * Sync-capable-async composition: apply `next` to a driver result
- * without allocating a promise when the result is already a value.
- * @param {any} value - A driver return: a value or a promise
- * @param {(value: any) => any} next
- * @returns {any} `next`'s result, promise-wrapped only if the input was
- */
-export declare function chain(value: any, next: (value: any) => any): any;
-/**
- * Lift a driver result into a promise — the ONE allocation the public
- * asynchronous surface pays per call.
- * @param {any} value
- * @returns {Promise<any>}
- */
-export declare function toPromise(value: any): Promise<any>;
+export { isThenable, chain, toPromise };
 /**
  * Compare two dotted version strings numerically.
  * @param {string} a

package/dist/types/emit.d.ts

@@ -18,10 +18,13 @@ export type ParamSlot = {
     external: string;
 } | {
     literal: unknown;
+} | {
+    derived: {
+        kind: 'bboxAxis';
+        external: string;
+        axis: 'w' | 's' | 'e' | 'n';
+    };
 };
-/**
- * @typedef {{ external: string } | { literal: unknown }} ParamSlot
- */
 /**
  * Emit one plan as SQL plus its ordered parameter slots.
  * @param {import('./algebra.js').Plan} plan