@jarenjs/db 0.34.0 → 0.43.1

package/dist/types/errors.d.ts

@@ -19,7 +19,7 @@ export declare const DB_CODES: Readonly<{
     JD0001: "the SQLite library is below the supported floor";
     JD0002: "the declared model disagrees with the existing database";
     JD0003: "the driver binding is unavailable on this runtime";
-    JD0004: "an index path is not a singular member selection";
+    JD0004: "a declared index cannot be mapped to a column";
     JD0005: "the model document is invalid";
     JD0010: "strict mode refused a residual";
     JD0011: "the profile refused the document";
@@ -62,9 +62,11 @@ export declare const DB_CODES: Readonly<{
  *  - `JD0003` — the runtime builtin behind a driver could not be
  *    loaded here (Node cannot resolve `bun:`; Bun ships no
  *    `node:sqlite`), or an injected handle is missing
- *  - `JD0004` — an index path does not select exactly one member
- *    (wildcards, slices, filters and descendants are not indexable);
- *    the reason names the expression
+ *  - `JD0004` — a declared index cannot be mapped to a column: its
+ *    path does not select exactly one member (wildcards, slices,
+ *    filters and descendants are not indexable), or its `derive`
+ *    declaration is not one the storage vocabulary carries; the reason
+ *    names the expression or the member and `docPath` points at it
  *  - `JD0005` — the model document is invalid; `docPath` points at
  *    the offending member
  *  - `JD0010` — `strict: true` and part of the query would have run

package/dist/types/index.d.ts

@@ -18,6 +18,7 @@ export { selectPlan, conjoin, assertNoSqlText, PLAN_VERSION } from './algebra.js
 export { typeOfPath, isNumericType } from './types.js';
 export { compileSetResidual, compileRowResidual, sequenceResult } from './residual.js';
 export { deterministicFragment, registerFragment } from './udf.js';
+export { DERIVE_KINDS, BBOX_COMPONENTS, BBOX_INDEX_ORDER, PRECISION_MIN, PRECISION_MAX, deriveGeohash, deriveBboxEdge, derivedValue, memberAt, storedMemberForm, registerDeriveFunctions, } from './derive.js';
 export { createQueryEngine, createQueryState, createEntityQueryEngine, createLoadEngine, INCLUDE_DEPTH_DEFAULT, } from './query.js';
 export { normalizeProfile, SAFE_PROFILE, translateProfilePredicate, applyMandatoryPredicate, applyRowBound, } from './profile.js';
 export { translatePatch } from './patch-sql.js';

package/dist/types/jobs.d.ts

@@ -25,7 +25,10 @@
  *  - **Shutdown is bounded.** Handlers receive an `AbortSignal` and
  *    `stop()` takes a deadline, so a handler that never settles cannot
  *    hold `stop()` — and therefore `store.close()`, and therefore the
- *    database file — open forever.
+ *    database file — open forever. A loop the deadline could not drain
+ *    is CANCELLED, not merely left behind: when its handler finally
+ *    settles it exits without another claim, store write or poll
+ *    timer, and its abandoned job recovers by lease expiry (§5).
  */
 export declare const JOBS_TABLE = "_jaren_jobs";
 export declare const JOB_CHECKPOINTS_TABLE = "_jaren_job_checkpoints";
@@ -117,6 +120,9 @@ export declare function createJobEngine(options: {
          * the loops — but only up to `graceMs`. A handler that ignores its
          * signal cannot hold the process open; the resolved record says so
          * instead, and the lease expiry (§5) lets another worker re-claim.
+         * A loop the grace period could not drain is cancelled outright:
+         * when its handler finally settles it exits without another
+         * claim, store write or poll timer.
          * @param {{ graceMs?: number }} [stopOptions]
          * @returns {Promise<{ drained: boolean, inFlight: number }>}
          */

package/dist/types/migrate.d.ts

@@ -43,9 +43,14 @@ export declare function migrationChecksum(migration: any): string;
  * refuses to run until the author fills it in — the planner cannot
  * infer a data transform and does not pretend to. Renames are declared
  * (`x-rename` on the target collection), never guessed.
+ * The physical mapping of a DERIVED index column depends on the driver
+ * that will run the migration (`derived`), because the two mappings
+ * really are different columns; a migration document planned for one is
+ * not the document the other needs.
  * @param {any} fromModel
  * @param {any} toModel
- * @param {{ id?: string, dialect?: any }} [options]
+ * @param {{ id?: string, dialect?: any,
+ *   derived?: 'virtual' | 'stored' }} [options]
  * @returns {{ migration: any, report: {
  *   renamed: { from: string, to: string }[],
  *   added: string[], removed: string[],
@@ -55,6 +60,7 @@ export declare function migrationChecksum(migration: any): string;
 export declare function planMigration(fromModel: any, toModel: any, options?: {
     id?: string;
     dialect?: any;
+    derived?: 'virtual' | 'stored';
 }): {
     migration: any;
     report: {

package/dist/types/plan.d.ts

@@ -10,16 +10,24 @@
  *
  * The outcome of planning one document:
  *
- *   { plan, mode: 'native' | 'row' | 'set', reasons, rowReturn }
+ *   { plan, mode: 'native' | 'row' | 'set', reasons, rowReturn,
+ *     prefilters }
  *
  * - `native` — everything translated; the plan alone answers.
  * - `row`    — predicates, ordering and window pushed; only the
  *   projection runs in the engine, per fetched row (streams).
+ *   `rowReturn` is the COMPLETE one-row document to run, binding
+ *   included — the collection binding is named by the document, so a
+ *   wrapper built anywhere else would have to guess it.
  * - `set`    — the pushed conjuncts narrow candidates; the WHOLE
  *   compiled document runs over the materialized candidates.
  *
  * `reasons` names every construct that forced work off the database,
  * with reason text drawn from the deliberate-residual table.
+ * `prefilters` names the IMPLIED conjuncts — predicates the planner
+ * ADDED because a spatial one provably implies them (see "Spatial
+ * promotions" below) — with the columns each reads and whether it
+ * decided or merely narrowed.
  */
 /**
  * Assert a node kind is one this planner has decided. Called on every
@@ -45,6 +53,7 @@ export declare function assertDecidedKind(node: any): void;
  *   reasons: { construct: string, reason: string }[],
  *   rowReturn: any,
  *   udfs: string[],
+ *   prefilters: { construct: string, columns: string[], exact: boolean }[],
  * }}
  */
 export declare function planQuery(document: any, shape: any, options?: {
@@ -62,6 +71,11 @@ export declare function planQuery(document: any, shape: any, options?: {
     }[];
     rowReturn: any;
     udfs: string[];
+    prefilters: {
+        construct: string;
+        columns: string[];
+        exact: boolean;
+    }[];
 };
 /**
  * Build the planner shape for one entity: canonical top-level paths

package/dist/types/residual.d.ts

@@ -9,10 +9,17 @@
  *   materialized candidate array. Re-applying pushed conjuncts is
  *   idempotent, so SQL-side narrowing never changes the answer.
  * - `row` — only the projection stayed behind: each fetched row runs
- *   `{ $for: { it: '$[*]' }, $return: [ <ret> ] }` over the one-row
- *   array; the array wrapper packs the item sequence so an
- *   array-VALUED item stays unambiguous, and the per-row results
- *   concatenate in row order (streamable).
+ *   the planner's one-row document over the one-row array; the array
+ *   wrapper packs the item sequence so an array-VALUED item stays
+ *   unambiguous, and the per-row results concatenate in row order
+ *   (streamable).
+ *
+ * Neither mode builds a query document here. The collection binding is
+ * named by the caller's document — `it`, `user`, anything — so a wrapper
+ * synthesized in this file could only guess it, and a guess that
+ * disagreed with the projection's references would surface as an
+ * unbound-external error at request time rather than at compile time.
+ * The planner knows the name and hands both modes something complete.
  */
 /**
  * Compile the whole document for set-mode evaluation. A profile's
@@ -30,12 +37,16 @@ export declare function compileSetResidual(document: any, limits?: any, operator
 } | null): (candidates: any[], externals: any) => any;
 /**
  * Compile the per-row projection for row-mode evaluation.
- * @param {any} returnExpression - The document's raw `$return` value
+ * @param {any} rowDocument - The planner's complete one-row document
+ *   (`{ $for: { <the document's own binding>: '$[*]' },
+ *   $return: [ <its $return> ] }`). It arrives whole because the binding
+ *   and the projection that references it must agree, and the planner is
+ *   the only place that knows the name.
  * @param {any} [limits]
  * @param {{ functions?: any, extensions?: any } | null} [operators]
  * @returns {(row: any, externals: any) => any[]} the row's items
  */
-export declare function compileRowResidual(returnExpression: any, limits?: any, operators?: {
+export declare function compileRowResidual(rowDocument: any, limits?: any, operators?: {
     functions?: any;
     extensions?: any;
 } | null): (row: any, externals: any) => any[];

package/dist/types/udf.d.ts

@@ -39,6 +39,11 @@
  *   [operators] - the store's registered operators (Ring 3); only its
  *   `pushable:'scalar'` subset is admitted. `null`/absent keeps the
  *   original engine-internal-only rule (no host function pushes).
+ * @param {string} [binding='it'] - the name the caller's document gave
+ *   the collection binding. The fragment references it, so the wrapper
+ *   below must bind it: under any other name every reference reads as an
+ *   external, the determinism check below rejects the fragment, and the
+ *   hatch silently never engages.
  * @returns {{ key: string, name: string,
  *   compile: () => (docText: string) => number } | null}
  */
@@ -46,7 +51,7 @@ export declare function deterministicFragment(fragment: any, operators?: {
     functions?: any;
     extensions?: any;
     pushableScalar?: Set<string>;
-} | null): {
+} | null, binding?: string): {
     key: string;
     name: string;
     compile: () => (docText: string) => number;

package/docs/JOBS-FORMAT.md

@@ -125,7 +125,8 @@ stats() }`:
   plainly (§8);
 - `stop({ graceMs })` aborts in-flight handlers and resolves once they
   settle **or** the grace period expires (default 5 s), answering
-  `{ drained, inFlight }` — see §6.1;
+  `{ drained, inFlight }`; a loop the grace period could not drain is
+  **cancelled**, not left running — see §6.1;
 - `stats()` reports claims, completions, failures, wakes, polls and the
   in-flight handler count.
 
@@ -162,6 +163,16 @@ handle really is released. A handler that ignores its signal therefore
 cannot hold the database file open for the life of the process, and the
 lease expiry (§5) lets another worker re-claim its job.
 
+A loop the grace period could not drain is **cancelled**, not merely
+uncounted: when its wedged handler finally settles, the loop exits
+without writing the completion or the failure, without claiming again,
+and without re-arming its poll timer — the store it would touch is the
+one the caller is closing, and the job it abandons recovers by lease
+expiry (§5). A later `start()` builds fresh loops in a new session (and
+re-registers the worker's wake-on-enqueue hook and its place in
+`stopAll`), so a cancelled loop can never be revived as an extra
+claimer.
+
 ## 7. The DAG composition
 
 ```js

package/docs/MIGRATION-FORMAT.md

@@ -53,11 +53,40 @@ shape change is a **transformation of values**, not a table rebuild.
   the migration to proceed. This is how a migration states its own
   precondition — "no user has a null email before the NOT NULL
   index" — and it is checked on the shadow first.
+- `kind: "derive"` recomputes named STORED derived index columns from
+  the documents already in a collection — the backfill described in
+  §2.1. It is idempotent: a derived value is a pure function of the
+  document, so a replay writes what the first run wrote.
 - Steps are ordered, and the order is the contract.
 
+### 2.1 Derived spatial columns and the backfill
+
+MODEL-FORMAT §3.1 gives a derived index (`derive: 'geohash' | 'bbox'`)
+two physical mappings, chosen by what the driver declares. That choice
+belongs to the migration DOCUMENT, because the two mappings really are
+different columns: `planMigration(from, to, { dialect, derived })`
+takes `'virtual'` (the default: a generated column) or `'stored'`, and
+a document planned for one is not the document the other needs.
+
+The difference the runner sees is one step. A generated column arrives
+POPULATED — SQLite computes it from every existing row. A stored one
+arrives `NULL`, and a query pushed to a `NULL` column silently returns
+fewer rows, so the planner emits an explicit `derive` step after the
+`ALTER TABLE … ADD COLUMN`:
+
+```json
+{ "kind": "derive", "collection": "places",
+  "columns": [ { "name": "gx_at_gh7", "derive": "geohash", "precision": 7,
+                 "segments": [ { "name": "at" } ] } ] }
+```
+
+A `jslt` transform on such a collection gets the same treatment for the
+same reason: it rewrites the documents the columns are computed from,
+so the planner follows it with a `derive` step that recomputes them.
+
 ## 3. Planning and the widening/narrowing rule
 
-`planMigration(fromModel, toModel, { dialect, id })` produces
+`planMigration(fromModel, toModel, { dialect, id, derived })` produces
 `{ migration, report }` by diffing the two models' PHYSICAL plans:
 
 - An added collection becomes its full CREATE DDL; a removed

package/docs/MODEL-FORMAT.md

@@ -64,10 +64,89 @@ The store runs over SQLite — on Node (`@jarenjs/db/node`), on Bun
   non-singular path is rejected at open with `JD0004` naming the
   expression. A composite index takes a non-empty array of paths.
 - Index names MUST be identifiers, unique within their collection.
+- `indexes[].derive` declares a **derived** index: the columns are
+  computed FROM the selected member rather than being the member.
+  See §2.1.
 
 An invalid model document is `JD0005` with a `docPath` pointing at the
 offending member. Model checking happens before any database work.
 
+### 2.1 Derived indexes (spatial storage)
+
+A generated column must be a scalar (§3), and a GeoJSON position is an
+array of numbers while a geometry is an object. No path over spatial
+data is therefore indexable as written. `derive` supplies the missing
+vocabulary: it says what indexable scalar is computed from the member.
+
+```jsonc
+"indexes": [
+  { "name": "by_cell", "path": "$.at",       "derive": "geohash", "precision": 7 },
+  { "name": "by_box",  "path": "$.geometry", "derive": "bbox" }
+]
+```
+
+| `derive` | `path` selects | `precision` | columns | type |
+|---|---|---|---|---|
+| `"geohash"` | a position `[lon, lat]`, a `Point`, or any value with a representative position (the mean of its vertices) | 1..12, **required** | one, `<column>` | `TEXT` |
+| `"bbox"` | any GeoJSON value | — | four: `<column>_w`, `<column>_s`, `<column>_e`, `<column>_n` | `REAL` |
+
+`derive` is a CLOSED set of those two values. An open "expression"
+member would be a second query language inside the model document,
+which this format does not have and will not grow.
+
+Every rule below is `JD0004` with a `docPath` at the offending member:
+
+1. **`precision` is required for `geohash`, and refused anywhere
+   else.** There is no safe default, in either direction — the table
+   below is the reason: precision 9 is a ~4.8 m cell (a very large
+   index for city-scale work) and precision 4 is ~20 km. The right
+   value follows from the query radius, which the model cannot know.
+2. **A derived index is never `unique`.** Two distinct positions share
+   a cell — and share a box edge — by construction.
+3. **The path must still be singular, and there must be exactly one of
+   it.** `derive` changes what is computed from the member, never how
+   the member is selected: a wildcard path is refused exactly as it is
+   for an undecorated index, and a composite (array) path is refused
+   because a derivation reads ONE member.
+4. **The schema is still the type source.** A `derive` over a path the
+   collection's schema types as `string`, `integer`, `number` or
+   `boolean` is refused: the mistake is worth catching at open rather
+   than at the first query that quietly returns nothing. A path the
+   schema does not type is accepted — there is nothing to contradict —
+   but **a spatial predicate is only PUSHED onto a column whose member
+   the schema types as an array or an object** (a union of the two is
+   fine; one that also admits `null` is not), because §8.14 raises for
+   a non-geographic operand and a pushed filter would simply not see
+   the row. Declaring the type is what turns a derived index from
+   storage into a plan.
+5. **Two indexes with the same `(path, derive, precision)` share one
+   column set**, extending §3's rule for undecorated paths. Two
+   `geohash` indexes over one path at DIFFERENT precisions are two
+   column sets, and legitimately so: a coarse bucketing index and a
+   fine proximity one are different indexes.
+6. **A `bbox` index covers its four columns in `(w, e, s, n)` order** —
+   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 (§3).
+
+Approximate geohash cell size by precision (the kernel's
+`geohashCellSize` computes the degree figures; the metric ones are at
+the equator):
+
+| precision | cell (lon × lat) | precision | cell (lon × lat) |
+|---|---|---|---|
+| 1 | 5009 km × 4976 km | 7 | 153 m × 152 m |
+| 2 | 1252 km × 622 km | 8 | 38 m × 19 m |
+| 3 | 157 km × 155 km | 9 | 4.8 m × 4.7 m |
+| 4 | 39.1 km × 19.4 km | 10 | 1.2 m × 59 cm |
+| 5 | 4.9 km × 4.9 km | 11 | 14.9 cm × 14.8 cm |
+| 6 | 1.2 km × 607 m | 12 | 3.7 cm × 1.9 cm |
+
+A geohash prefix is **bucketing, not proximity**: two points metres
+apart can sit in different cells, so a proximity probe tests the cell's
+neighbourhood (`geohashNeighbours`) rather than the single cell.
+
 ## 3. Physical mapping
 
 Each collection maps to one table, rendered entirely by the dialect —
@@ -124,6 +203,69 @@ Physical column ORDER is deliberately **not** drift. SQLite's
 freshly built one legitimately disagree there, and this store never reads
 a column positionally.
 
+### 3.1 Derived columns, and the capability branch
+
+A derived column (§2.1) needs a function SQLite does not have, so its
+mapping BRANCHES on what the driver declares. That is what the
+capability table (§4) is for: a driver that cannot do a thing says so
+rather than degrading silently.
+
+| `capabilities.deterministicIndexableFunctions` | mapping | drivers |
+|---|---|---|
+| `true` | a **virtual generated column** whose expression calls a deterministic function the store registers at open — `jaren_geohash(<member>, <precision>)`, `jaren_bbox_w(<member>)`, … over `json(jsonb_extract("doc", '<path>'))` | `node`, `wasm` |
+| `false` | a **stored column** the store writes on every insert, upsert and patch, computed in JavaScript from the same kernel call | `bun` |
+
+Three consequences, each normative:
+
+- **The registered function MUST be deterministic** in the strong
+  sense: the same document bytes give the same cell, forever. It reads
+  the member and never the clock, a random source or store state. That
+  is not a style rule. An INDEX over a registered function makes the
+  table unreadable from a connection that has not registered an
+  identical function — not merely wrong, unreadable: a bare `SELECT`
+  fails with `unknown function`. That hazard is exactly why the mapping
+  is capability-gated rather than always-on, and why the store, the
+  migration runner and the shadow database each register these
+  functions before any statement over such a table.
+- **A derived value is a function of the STORED document.** JSON has no
+  `NaN` and no `Infinity`, so the write path computes from the member
+  as it will be held rather than from the object handed in. Without
+  that the two mappings would answer differently for one document.
+- **The same model document produces two different physical shapes**,
+  and *match* is by declared text (above). A database created under
+  `node` and opened under `bun` therefore reports `JD0002` naming the
+  derived column — correctly: the column really is different. The
+  physical mapping is a property of the driver that CREATED the file,
+  and moving a file between the two is a migration, not an open.
+
+### 3.2 When a derived column is `NULL`
+
+A derived column is SQL `NULL` when the document has no member at the
+index path, and when the member has no bounded position — a value with
+no positions at all, or one whose coordinates are not positions, which
+is what a non-finite coordinate becomes: JSON cannot carry `NaN`, so it
+arrives as `null` and is no longer a number.
+
+The consequence is stated here rather than discovered later: **a row
+whose derived column is `NULL` is not found by a predicate pushed to
+that column.** For the spatial predicates the planner promotes
+(ARCHITECTURE.md, "The implied conjunct") that is not a divergence —
+§8.14 measures a value by its representative position, and that
+position is missing in exactly the cases the box is, so `$within`,
+`$bbox-intersects` and `$distance` answer `false`/empty for such a row
+anyway. Where it does bite is the ERROR behaviour: §8.14 raises
+`JQ2001` for an operand that is not geography at all (a string, a
+stored `null`), and a row the pushed filter never fetched cannot
+raise. The promotion therefore requires the schema to type the member
+as an array or an object and nothing else; a store that wants the
+engine's refusal instead keeps `compileSchema` injected.
+
+Traversal and validity stay separate concerns, as they do in the
+kernel: a value that carries SOME positions is bounded by the positions
+it has. A `LineString` whose second vertex did not survive as a
+position is bounded by its first — a document the GeoJSON meta-schema
+refuses in the first place — and both mappings agree about it.
+
 ## 4. The driver contract and the synchronous fast path
 
 A driver is `{ name, dialect, open(path, options) }`; `open` returns a
@@ -160,7 +302,10 @@ change.
 On the Bun binding, `userFunctions`,
 `deterministicIndexableFunctions` and `sessions` are `false` by
 construction: `bun:sqlite` exposes no `function`, no `aggregate` and
-no `createSession`.
+no `createSession`. `deterministicIndexableFunctions` is the capability
+the derived-column mapping branches on (§3.1), so a model that declares
+a spatial index is portable across all three drivers and the physical
+shape it produces is not.
 
 A library below SQLite **3.45** fails at open with `JD0001` naming
 the version found.
@@ -218,7 +363,9 @@ returns a validation function; the function returns `true`/`false` or
 and `store.capabilities.validated === false` — a declared downgrade.
 The cost of running without one: the database constraints only see the
 key and the indexed members; everything else is stored as given.
-`@jarenjs/db` never imports `@jarenjs/validate`.
+`@jarenjs/db` never runs a validator of its own; what it imports from
+`@jarenjs/validate` is only the pure same-document `$ref`/`$anchor`
+resolution in `@jarenjs/validate/normalize`, for model compilation.
 
 **`patch` validates the result, then updates in place.** The patch is
 applied to the stored document with the copy-on-write engine and the
@@ -280,7 +427,11 @@ SQLite has no per-statement transaction scope and every operation inside
 a callback reaches the connection the same way an unrelated caller does.
 Work that must be in the transaction is therefore safe; an unrelated
 writer on a SHARED store is not. Give each concurrent writer its own
-store when independent writes must not share a rollback.
+store when independent writes must not share a rollback. Closing this
+— scope-bound `tx` handles, with store-level calls waiting on the gate
+while a foreign scope is open — is an open ROADMAP item (`@jarenjs/db`,
+"Strong same-store transaction ownership"); until it lands, one store
+shared by independent request handlers is unsafe for bare writes.
 
 ## 6. Identity
 
@@ -314,7 +465,7 @@ error.
 | `JD0001` | the SQLite library is below the supported floor |
 | `JD0002` | the declared model disagrees with the existing database |
 | `JD0003` | the driver binding is unavailable on this runtime |
-| `JD0004` | an index path is not a singular member selection |
+| `JD0004` | a declared index cannot be mapped to a column |
 | `JD0005` | the model document is invalid |
 | `JD0010` | strict mode refused a residual |
 | `JD0011` | the profile refused the document |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/db",
   "private": false,
-  "version": "0.34.0",
+  "version": "0.43.1",
   "type": "module",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
@@ -71,9 +71,9 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.34.0",
-    "@jarenjs/json": "^0.34.0",
-    "@jarenjs/validate": "^0.34.0"
+    "@jarenjs/core": "^0.43.1",
+    "@jarenjs/json": "^0.43.1",
+    "@jarenjs/validate": "^0.43.1"
   },
   "bin": {
     "jaren-db": "./src/cli.js"

package/schemas/jaren-migration.draft-07.schema.json

@@ -55,6 +55,9 @@
         },
         {
           "$ref": "#/definitions/queryStep"
+        },
+        {
+          "$ref": "#/definitions/deriveStep"
         }
       ]
     },
@@ -139,6 +142,74 @@
         "assert"
       ],
       "additionalProperties": false
+    },
+    "deriveStep": {
+      "description": "Recompute named STORED derived index columns from the documents already in a collection. Only the physical mapping that cannot index a registered deterministic function has these columns; the generated mapping populates them itself. The step is idempotent — a derived value is a pure function of the document — so a replay writes what the first run wrote.",
+      "type": "object",
+      "properties": {
+        "kind": {
+          "const": "derive"
+        },
+        "collection": {
+          "type": "string",
+          "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+        },
+        "columns": {
+          "description": "The columns to recompute, with the derivation and the typed member path each is computed from.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "minLength": 1
+              },
+              "derive": {
+                "enum": [
+                  "geohash",
+                  "bbox"
+                ]
+              },
+              "precision": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 12
+              },
+              "component": {
+                "enum": [
+                  "w",
+                  "s",
+                  "e",
+                  "n"
+                ]
+              },
+              "segments": {
+                "description": "The typed member path the value is computed from: name segments for object members, index segments for array positions.",
+                "type": "array",
+                "items": {
+                  "type": "object"
+                }
+              }
+            },
+            "required": [
+              "name",
+              "derive",
+              "segments"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "note": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "kind",
+        "collection",
+        "columns"
+      ],
+      "additionalProperties": false
     }
   }
 }

package/schemas/jaren-migration.schema.json

@@ -55,6 +55,9 @@
     },
     {
      "$ref": "#/$defs/queryStep"
+    },
+    {
+     "$ref": "#/$defs/deriveStep"
     }
    ]
   },
@@ -139,6 +142,74 @@
     "assert"
    ],
    "additionalProperties": false
+  },
+  "deriveStep": {
+   "description": "Recompute named STORED derived index columns from the documents already in a collection. Only the physical mapping that cannot index a registered deterministic function has these columns; the generated mapping populates them itself. The step is idempotent — a derived value is a pure function of the document — so a replay writes what the first run wrote.",
+   "type": "object",
+   "properties": {
+    "kind": {
+     "const": "derive"
+    },
+    "collection": {
+     "type": "string",
+     "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+    },
+    "columns": {
+     "description": "The columns to recompute, with the derivation and the typed member path each is computed from.",
+     "type": "array",
+     "minItems": 1,
+     "items": {
+      "type": "object",
+      "properties": {
+       "name": {
+        "type": "string",
+        "minLength": 1
+       },
+       "derive": {
+        "enum": [
+         "geohash",
+         "bbox"
+        ]
+       },
+       "precision": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 12
+       },
+       "component": {
+        "enum": [
+         "w",
+         "s",
+         "e",
+         "n"
+        ]
+       },
+       "segments": {
+        "description": "The typed member path the value is computed from: name segments for object members, index segments for array positions.",
+        "type": "array",
+        "items": {
+         "type": "object"
+        }
+       }
+      },
+      "required": [
+       "name",
+       "derive",
+       "segments"
+      ],
+      "additionalProperties": false
+     }
+    },
+    "note": {
+     "type": "string"
+    }
+   },
+   "required": [
+    "kind",
+    "collection",
+    "columns"
+   ],
+   "additionalProperties": false
   }
  }
 }