@jarenjs/db 0.43.1 → 0.46.4

package/src/ddl.js

@@ -17,7 +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';
+import { BBOX_COMPONENTS, BBOX_INDEX_ORDER, derivedMappingFor } from './derive.js';
 
 /** The fixed physical column names of the 0.1 mapping. */
 export const KEY_COLUMN = 'key';
@@ -118,6 +118,21 @@ export function schemaTypeAt(schema, segments) {
 /** The scalar schema types a derived index cannot be declared over. */
 const SCALAR_TYPES = new Set(['string', 'integer', 'number', 'boolean']);
 
+/**
+ * Whether a schema node types its value as `array` and nothing else —
+ * `type: 'array'` or `type: ['array']`. A vector column over a member
+ * the schema also lets be a string (or does not type at all) is a
+ * column that lies: some documents would carry a member the column
+ * silently ignores.
+ * @param {any} node
+ * @returns {boolean}
+ */
+function typedArrayOnly(node) {
+  if (node === undefined) return false;
+  if (node.type === 'array') return true;
+  return Array.isArray(node.type) && node.type.length === 1 && node.type[0] === 'array';
+}
+
 /**
  * A stable generated-column name for a canonical path: readable where
  * the path is tame, disambiguated by suffix where sanitizing collides.
@@ -125,9 +140,9 @@ const SCALAR_TYPES = new Set(['string', 'integer', 'number', 'boolean']);
  * 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.
+ * coarse bucketing index and a fine proximity one); a vector width
+ * likewise. 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>} byKey - identity -> column name (or stem)
  * @param {Set<string>} taken
@@ -151,6 +166,57 @@ function generatedColumnName(canonical, byKey, taken, options = undefined) {
   return name;
 }
 
+/**
+ * The one column a `derive: 'vector'` index contributes: the packed,
+ * l2-normalized member as `dialect.packedVectorType`, STORED on every
+ * driver (`derivedMappingFor`), with no B-tree over it — nothing seeks
+ * a blob of floats; a fetch-and-rank plan reads the whole column — so
+ * the index declaration names a column, not an index, and contributes
+ * nothing to `expected.indexes`. `dims` is part of the identity for
+ * the reason `precision` is: a different width is a different column.
+ * @param {any} index - the normalized index declaration
+ * @param {any} context
+ * @returns {null} — no index covers the column
+ */
+function vectorColumn(index, context) {
+  const {
+    collection, dialect, segments, canonical, pathText, columnByCanonical, taken,
+    generated, derived,
+  } = context;
+  const node = schemaNodeAt(collection.schema, segments);
+  if (!typedArrayOnly(node)) {
+    const typed = node?.type === undefined ? 'not typed' : `typed ${JSON.stringify(node.type)}`;
+    throw new DbCompileError('JD0004',
+      `index '${index.name}': the path '${index.paths[0]}' is ${typed} by the schema, and a `
+      + "vector column needs a member the schema types 'array' and nothing else — a column over "
+      + 'a member that may also be a string, an object or null is a column that lies about '
+      + 'some documents (declare items: { type: \'number\' } and minItems/maxItems equal to '
+      + 'dims beside it)',
+      `${index.docPath}/derive`);
+  }
+  if (typeof dialect.packedVectorType !== 'string') {
+    throw new TypeError(
+      `ddl: the '${dialect.name}' dialect declares no packedVectorType, so it cannot hold a vector column`);
+  }
+  const key = `${canonical}|vector|${index.dims}`;
+  const name = generatedColumnName(canonical, columnByCanonical, taken,
+    { key, suffix: `v${index.dims}` });
+  if (!generated.some((column) => column.name === name)) {
+    generated.push({
+      name,
+      type: dialect.packedVectorType,
+      pathText,
+      canonical,
+      derive: 'vector',
+      dims: index.dims,
+      stored: true,
+      expression: null,
+    });
+    derived.push({ name, derive: 'vector', dims: index.dims, segments });
+  }
+  return null;
+}
+
 /**
  * The columns one derived index contributes, appended to the plan's
  * `generated` (the physical column list) and `derived` (what the write
@@ -162,25 +228,46 @@ function generatedColumnName(canonical, byKey, taken, options = undefined) {
  * 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
+ * @returns {string[] | null} the column names the index covers, in
+ *   order — or `null` when no B-tree covers them (an R\*Tree, or a
+ *   vector column)
  */
 function deriveColumns(index, context) {
   const {
-    collection, dialect, stored, segments, canonical, pathText,
-    columnByCanonical, taken, generated, derived,
+    collection, table, dialect, mapping, segments, canonical, pathText,
+    columnByCanonical, taken, generated, derived, rtreeCapable, virtualTables,
+    physicalByKey,
   } = context;
+  // the per-kind override: a vector column is stored on every driver
+  const stored = derivedMappingFor(index.derive, mapping) === 'stored';
   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 '${index.name}': the path '${index.paths[0]}' is typed '${declaredType}' by the schema, and a `
+      + `${index.derive} index derives from ${index.derive === 'vector'
+        ? 'an array of numbers' : 'a position or a geometry — an array or an object'}`,
       `${index.docPath}/derive`);
   }
+  if (index.derive === 'vector') return vectorColumn(index, context);
   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 ?? ''}`;
+  // `physical` is a property of the COLUMN SET, not of the index: rule 5
+  // lets two indexes share one set, and one set has one shape on disk.
+  // Two indexes asking for two shapes is a model that cannot be built,
+  // and saying so beats silently honouring whichever came first.
+  const wanted = isGeohash ? 'columns' : (index.physical ?? 'columns');
+  const agreed = physicalByKey.get(key);
+  if (agreed !== undefined && agreed !== wanted) {
+    throw new DbCompileError('JD0004',
+      `the index path '${index.paths[0]}' already has a ${index.derive} column set declared `
+      + `physical: '${agreed}', and this index declares '${wanted}' — two indexes over one `
+      + 'path share one column set, and a column set has one shape on disk',
+      `${index.docPath}/physical`);
+  }
+  physicalByKey.set(key, wanted);
   const stem = generatedColumnName(canonical, columnByCanonical, taken, {
     key,
     suffix: isGeohash ? `gh${index.precision}` : 'bbox',
@@ -216,6 +303,31 @@ function deriveColumns(index, context) {
       });
     }
   }
+  if (wanted === 'rtree' && rtreeCapable) {
+    // the R*Tree mapping: the four columns stay (the triggers read them,
+    // and they are the box's one definition) and the B-tree over them
+    // does NOT get built — that is where part of the write cost is
+    // repaid, and it is what makes the two shapes differ in `expected`.
+    // One virtual table per COLUMN SET, never per index (rule 5).
+    if (!virtualTables.some((virtual) => virtual.stem === stem)) {
+      const name = `${table}_${stem}_rtree`;
+      // (w, e, s, n) — the order the virtual table's
+      // (minx, maxx, miny, maxy) carry, and the order the index covers
+      const edges = BBOX_INDEX_ORDER.map((component) => ({ name: nameOf(component) }));
+      const triggers = dialect.ddl.createSyncTriggers(
+        { table, virtualTable: name, prefix: name, edges });
+      virtualTables.push({
+        stem,
+        name,
+        columns: [...dialect.rtree.columns].slice(1),
+        edges: edges.map((edge) => edge.name),
+        createSql: dialect.ddl.createVirtualTable({ name }),
+        fillSql: dialect.ddl.fillVirtualTable({ table, virtualTable: name, edges }),
+        triggers,
+      });
+    }
+    return null;
+  }
   // 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));
@@ -231,32 +343,44 @@ function deriveColumns(index, context) {
  * 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.
+ * `verifyShape` says so rather than papering over it. A
+ * `derive: 'vector'` column is the stored shape under BOTH mappings
+ * (`derivedMappingFor`), so for it the two agree.
  * @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, derive?: string | null, precision?: number,
- *   docPath: string }[] }} collection - normalized
+ *   dims?: 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
+ * @param {{ derived?: 'virtual' | 'stored', rtree?: boolean }} [options]
+ *   - `derived` is the physical mapping for derived columns:
+ *   `'virtual'` (a generated column over a registered function) unless
+ *   the driver says it cannot index one. `rtree` is whether the driver
+ *   carries the R\*Tree module; when it does not, a column set that
+ *   declared `physical: 'rtree'` falls back to the B-tree over its
+ *   columns and `explain().prefilters[].via` reports which shape ran
+ *   (MODEL-FORMAT §4) — a report, not a silent degradation
  * @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[] }[],
+ *     component?: string, dims?: number, segments: any[] }[],
  *   columnByCanonical: Map<string, string>,
  *   createSql: string[],
+ *   virtualTables: { stem: string, name: string, columns: string[],
+ *     edges: string[], createSql: string, fillSql: string,
+ *     triggers: { name: string, sql: string }[] }[],
  *   expected: { columns: { name: string, type: string,
  *     generated: boolean }[], indexes: { name: string, unique: boolean,
  *     columns: string[] }[] },
  * }}
  */
 export function planCollection(name, collection, dialect, options = undefined) {
-  const stored = options?.derived === 'stored';
+  /** @type {'virtual' | 'stored'} */
+  const mapping = options?.derived === 'stored' ? 'stored' : 'virtual';
+  const rtreeCapable = options?.rtree !== false;
   const keyType = collection.identity === 'integer'
     ? dialect.typeFor('integer', 'key')
     : collection.identity === 'uuid'
@@ -274,9 +398,14 @@ export function planCollection(name, collection, dialect, options = undefined) {
   const derived = [];
   /** @type {{ name: string, unique: boolean, columns: string[] }[]} */
   const indexes = [];
+  /** @type {any[]} */
+  const virtualTables = [];
+  /** @type {Map<string, string>} */
+  const physicalByKey = new Map();
 
   for (const index of collection.indexes) {
     const columns = [];
+    let noBtree = false;
     for (let i = 0; i < index.paths.length; i++) {
       const pathDocPath = `${index.docPath}/path`;
       const { segments, canonical } = compileIndexPath(index.paths[i], pathDocPath);
@@ -287,10 +416,13 @@ export function planCollection(name, collection, dialect, options = undefined) {
           pathDocPath);
       }
       if (index.derive) {
-        columns.push(...deriveColumns(index, {
-          collection, dialect, stored, segments, canonical, pathText,
-          columnByCanonical, taken, generated, derived,
-        }));
+        const contributed = deriveColumns(index, {
+          collection, table: name, dialect, mapping, segments, canonical, pathText,
+          columnByCanonical, taken, generated, derived, rtreeCapable, virtualTables,
+          physicalByKey,
+        });
+        if (contributed === null) noBtree = true;
+        else columns.push(...contributed);
         continue;
       }
       const known = columnByCanonical.has(canonical);
@@ -305,6 +437,11 @@ export function planCollection(name, collection, dialect, options = undefined) {
       }
       columns.push(columnName);
     }
+    // a column set realized as an R*Tree has no B-tree over it: the
+    // virtual table IS the index, and the four columns stay only as the
+    // box's one definition (the triggers read them). A vector column
+    // has none either: it is fetched whole and ranked, never sought
+    if (noBtree) continue;
     indexes.push({
       name: `${name}_${index.name}`,
       unique: index.unique,
@@ -327,7 +464,25 @@ export function planCollection(name, collection, dialect, options = undefined) {
       columns: index.columns,
       unique: index.unique,
     })),
+    ...virtualTables.flatMap((virtual) =>
+      [virtual.createSql, ...virtual.triggers.map((trigger) => trigger.sql)]),
   ];
+  // the virtual table and its triggers are named from the column stem,
+  // and an index is named from the model's own index name — two
+  // namespaces that meet in `sqlite_schema`. A collision would have one
+  // object silently standing in for another, so it is refused here
+  const objectNames = [name, ...indexes.map((index) => index.name),
+    ...virtualTables.flatMap((virtual) =>
+      [virtual.name, ...virtual.triggers.map((trigger) => trigger.name)])];
+  const seen = new Set();
+  for (const objectName of objectNames) {
+    if (seen.has(objectName)) {
+      throw new DbCompileError('JD0004',
+        `collection '${name}' would declare two schema objects named '${objectName}'`,
+        collection.docPath ?? `/collections/${name}`);
+    }
+    seen.add(objectName);
+  }
 
   return {
     table: name,
@@ -337,6 +492,7 @@ export function planCollection(name, collection, dialect, options = undefined) {
     generated,
     derived,
     columnByCanonical,
+    virtualTables,
     createSql,
     expected: {
       columns: [
@@ -464,13 +620,40 @@ export function comparableDeclaredSql(sql) {
 function verifyDeclaredSql(connection, plan, disagree) {
   const dialect = connection.dialect;
   const planned = new Map();
+  // an R*Tree virtual table is NOT owned by the collection table —
+  // `declaredSql` is scoped to `tbl_name`, and a virtual table's is
+  // itself — so it is checked by its own look below rather than
+  // reported as an object the database is missing. Its three triggers
+  // ARE the collection's, so drift in both directions falls out of this
+  // comparison for free.
+  const owned = new Set(plan.virtualTables?.map((virtual) => virtual.name) ?? []);
   for (const sql of plan.createSql) {
     const comparable = comparableDeclaredSql(sql);
     // the object's name is the first quoted identifier in the statement
     const name = /"((?:[^"]|"")*)"/.exec(comparable)?.[1]?.replace(/""/g, '"');
-    if (name === undefined) continue;
+    if (name === undefined || owned.has(name)) continue;
     planned.set(name, comparable);
   }
+  /** The virtual tables, each by its own name. */
+  const verifyVirtual = (i) => {
+    const list = plan.virtualTables ?? [];
+    if (i >= list.length) return null;
+    const virtual = list[i];
+    return chain(connection.prepare(dialect.introspect.declaredSql(virtual.name)),
+      (statement) => chain(statement.all([]), (rows) => {
+        const row = rows.find((candidate) => String(candidate.name) === virtual.name);
+        if (row === undefined) {
+          disagree(`the model declares the virtual table '${virtual.name}', `
+            + 'which the database does not have');
+        }
+        const have = comparableDeclaredSql(row.sql);
+        const wanted = comparableDeclaredSql(virtual.createSql);
+        if (have !== wanted) {
+          disagree(`'${virtual.name}' is declared as\n  ${have}\nand the model declares\n  ${wanted}`);
+        }
+        return verifyVirtual(i + 1);
+      }));
+  };
   return chain(connection.prepare(dialect.introspect.declaredSql(plan.table)),
     (statement) => chain(statement.all([]), (rows) => {
       /** @type {Map<string, string>} */
@@ -490,7 +673,7 @@ function verifyDeclaredSql(connection, plan, disagree) {
             + 'an undeclared index or trigger changes deletion semantics and query plans');
         }
       }
-      return null;
+      return verifyVirtual(0);
     }));
 }
 
@@ -523,8 +706,17 @@ export function verifyShape(connection, plan, collection, docPath) {
       const expected = [...plan.expected.columns]
         .map((c) => ({ ...c, type: c.type.toUpperCase() }))
         .sort((a, b) => (a.name < b.name ? -1 : 1));
-      if (actual.length !== expected.length)
-        disagree(`${actual.length} columns exist, the model declares ${expected.length}`);
+      if (actual.length !== expected.length) {
+        // name what is missing or extra: a count alone sends the reader
+        // to a pragma to learn which column a foreign tool dropped
+        const actualNames = new Set(actual.map((column) => column.name));
+        const expectedNames = new Set(expected.map((column) => column.name));
+        const missing = expected.filter((column) => !actualNames.has(column.name));
+        const extra = actual.filter((column) => !expectedNames.has(column.name));
+        disagree(`${actual.length} columns exist, the model declares ${expected.length}`
+          + (missing.length > 0 ? `; missing: ${missing.map((c) => `'${c.name}'`).join(', ')}` : '')
+          + (extra.length > 0 ? `; undeclared: ${extra.map((c) => `'${c.name}'`).join(', ')}` : ''));
+      }
       for (let i = 0; i < expected.length; i++) {
         const want = expected[i];
         const have = actual[i];
@@ -541,8 +733,24 @@ export function verifyShape(connection, plan, collection, docPath) {
             .map((row) => ({ name: String(row.name), unique: Number(row.uniq) !== 0 }))
             .sort((a, b) => (a.name < b.name ? -1 : 1));
           const wantedIndexes = plan.expected.indexes;
-          if (created.length !== wantedIndexes.length)
-            disagree(`${created.length} declared indexes exist, the model declares ${wantedIndexes.length}`);
+          if (created.length !== wantedIndexes.length) {
+            // the COUNT is the fact, but the NAMES are what a reader
+            // needs: a file moved between two physical mappings differs
+            // by exactly one index, and saying which one is the whole
+            // diagnosis
+            const have = new Set(created.map((index) => index.name));
+            const want = new Set(wantedIndexes.map((index) => index.name));
+            const missing = [...want].filter((index) => !have.has(index));
+            const extra = [...have].filter((index) => !want.has(index));
+            disagree(`${created.length} declared indexes exist, the model declares `
+              + `${wantedIndexes.length}`
+              + (missing.length > 0
+                ? ` — the model declares ${missing.join(', ')}, which the database does not have`
+                : '')
+              + (extra.length > 0
+                ? ` — the database has ${extra.join(', ')}, which the model does not declare`
+                : ''));
+          }
           const collectColumns = (i) => {
             if (i >= created.length) return null;
             const have = created[i];

package/src/derive.js

@@ -3,20 +3,36 @@
  * @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.
+ * geohash cell or a bounding-box edge is what actually gets indexed;
+ * an embedding is an array of hundreds of numbers, and what gets
+ * stored is its packed, l2-normalized Float32 form.
  *
- * 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.
+ * Every cell and every box comes from `@jarenjs/core/geo`, and every
+ * normalization and packing from `@jarenjs/core/vector`; nothing here
+ * computes arithmetic of its own. The spatial 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. The vector
+ * kind has ONE mapping, stored everywhere (`DERIVE_MAPPING`), and
+ * registers no function at all: a whole array re-derived per row as a
+ * host call is the cost the spatial work measured at 150×, a stored
+ * column is readable without any registration, and bun has no
+ * function API — one mapping is the only way every driver agrees.
  *
  * 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.
+ * one home for spatial arithmetic, grep-proven by test) and onto
+ * `@jarenjs/core/vector` (the same rule, one home for vector
+ * arithmetic): the planner's probe geometry — the box of a literal or
+ * bound region, the box of a bounded-distance circle, a cell's
+ * neighbourhood — and the k-nearest plan's probe vector and column
+ * score are computed by the helpers below rather than by an import of
+ * their own.
+ *
+ * The switches over the kind are EXHAUSTIVE: a kind with no rule
+ * throws, here and in the dialect, so that adding a kind without
+ * teaching both is a failure at the first call rather than a bbox
+ * edge of the first two floats and `jaren_bbox_undefined(...)` SQL.
  *
  * Determinism is the contract, not a convenience: a value here is a
  * pure function of the document bytes. Nothing reads the clock, a
@@ -31,11 +47,47 @@
 import {
   bboxOf, centroidOf, circleBounds, geohashEncode, geohashNeighbours,
 } from '@jarenjs/core/geo';
+import {
+  isVector, l2Normalize, packVector, unpackVector, dotProduct,
+} from '@jarenjs/core/vector';
 
 import { chain } from './driver.js';
 
 /** The closed set of derive kinds. */
-export const DERIVE_KINDS = new Set(['geohash', 'bbox']);
+export const DERIVE_KINDS = new Set(['geohash', 'bbox', 'vector']);
+
+/**
+ * The per-kind PHYSICAL MAPPING override. A spatial kind takes the
+ * mapping the driver's capability selects (`null` here); the vector
+ * kind is `'stored'` on every driver, for the three reasons in the
+ * file header, and never joins `registerDeriveFunctions`.
+ * @type {Readonly<Record<string, 'stored' | null>>}
+ */
+export const DERIVE_MAPPING = Object.freeze({ geohash: null, bbox: null, vector: 'stored' });
+
+/**
+ * The physical mapping one derived column takes: the kind's override
+ * where it has one, the driver's mapping otherwise.
+ * @param {string} kind
+ * @param {'virtual' | 'stored'} driverMapping
+ * @returns {'virtual' | 'stored'}
+ */
+export function derivedMappingFor(kind, driverMapping) {
+  if (!DERIVE_KINDS.has(kind)) throw new TypeError(`derive: unknown derive kind '${kind}'`);
+  return DERIVE_MAPPING[kind] ?? driverMapping;
+}
+
+/**
+ * The closed set of PHYSICAL realizations a `derive: 'bbox'` index may
+ * ask for. `'columns'` is the default and what an absent member means:
+ * four generated columns under one B-tree. `'rtree'` is the same four
+ * columns (they stay the box's one definition) beside a SQLite R\*Tree
+ * virtual table kept in sync by declared triggers, with no B-tree over
+ * them. The LOGICAL meaning of `derive: 'bbox'` is identical either
+ * way — same rows, same answers — which is the whole point of naming
+ * the shape separately from the derivation.
+ */
+export const PHYSICAL_KINDS = new Set(['columns', 'rtree']);
 
 /** A bbox index's four columns, in the order they are declared —
  * `[west, south, east, north]`, the order the kernel's boxes carry. */
@@ -57,6 +109,10 @@ const BBOX_AT = { w: 0, s: 1, e: 2, n: 3 };
 export const PRECISION_MIN = 1;
 export const PRECISION_MAX = 12;
 
+/** The declared vector width range (components). */
+export const DIMS_MIN = 1;
+export const DIMS_MAX = 8192;
+
 /**
  * The representative position of any GeoJSON value: the position
  * itself for a bare `[lon, lat]` or a Point, the mean vertex
@@ -97,6 +153,47 @@ export function deriveBboxEdge(value, component) {
   return box === null ? null : box[BBOX_AT[component]];
 }
 
+/**
+ * The packed column value of a member ALREADY in its stored form (see
+ * {@link storedMemberForm}): the l2-normalized vector as little-endian
+ * binary32 bytes, or `null` when the member is not a vector of exactly
+ * `dims` finite numbers — absent, the wrong width, a non-finite
+ * component (which JSON turned into `null`), not an array at all. An
+ * unrankable document is INVISIBLE to the column, never a stored-but-
+ * wrong one; the document itself stores fine.
+ *
+ * Normalized because the stored form is what a fetch-and-rank plan
+ * sweeps, and over unit vectors the dot product IS the cosine — the
+ * agreement invariant between this column and an engine computing
+ * cosine over the raw member. A zero vector normalizes to itself and
+ * is stored (it scores 0 against everything; the kernel documents it
+ * and the query format publishes it), not refused.
+ * @param {any} stored - the member as the database holds it
+ * @param {number} dims
+ * @returns {Uint8Array | null}
+ */
+function packedVector(stored, dims) {
+  if (!isVector(stored, dims)) return null;
+  return packVector(l2Normalize(stored));
+}
+
+/**
+ * The value of a `derive: 'vector'` column for a document member — the
+ * ONE seam from this package onto `@jarenjs/core/vector`. The member
+ * round-trips through its stored form first, exactly as the spatial
+ * kinds do: a `Float32Array` in the document is held as an object and
+ * a `NaN` as `null`, and the column must be a function of what is
+ * held, so that a write, a migration backfill and a second open can
+ * never disagree about one row.
+ * @param {any} member - the value at the index path, or `undefined`
+ * @param {number} dims - the declared width
+ * @returns {Uint8Array | null} `4·dims` bytes, or `null` when the
+ *   member is not a vector of that width
+ */
+export function deriveVector(member, dims) {
+  return packedVector(storedMemberForm(member), dims);
+}
+
 /**
  * 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
@@ -118,16 +215,27 @@ export function storedMemberForm(member) {
 }
 
 /**
- * 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}
+ * The value of one derived column for a document member, which the
+ * caller hands over in its STORED form (`storedMemberForm`): the write
+ * path round-trips it, and a migration backfill reads it from the row.
+ * Exhaustive over the kind — see the file header.
+ * @param {{ derive: string, precision?: number, component?: string,
+ *   dims?: number }} column
+ * @param {any} member - the stored value at the index path, or `undefined`
+ * @returns {string | number | Uint8Array | 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));
+  switch (column.derive) {
+    case 'geohash':
+      return deriveGeohash(member, /** @type {number} */ (column.precision));
+    case 'bbox':
+      return deriveBboxEdge(member, /** @type {string} */ (column.component));
+    case 'vector':
+      return packedVector(member, /** @type {number} */ (column.dims));
+    default:
+      throw new TypeError(`derive: no value rule for derive kind '${column.derive}'`);
+  }
 }
 
 /**
@@ -282,3 +390,34 @@ export function derivedSlotValue(derived, value) {
   const box = bboxOf(value);
   return box === null ? null : box[BBOX_AT[derived.axis]];
 }
+
+/**
+ * The probe a k-nearest plan scores the column against: a literal or
+ * bound vector, l2-normalized once, so that its dot product with the
+ * column's normalized form IS the cosine of the raw vectors. `null`
+ * when the value is not a vector of exactly `dims` finite numbers —
+ * the binder's signal to divert the call to the residual, where the
+ * engine answers what it answers everywhere for such a probe (empty
+ * keys for another width, its own refusal for a non-array).
+ * @param {unknown} value
+ * @param {number} dims - the column's declared width
+ * @returns {Float32Array | null}
+ */
+export function probeVector(value, dims) {
+  return isVector(value, dims) ? l2Normalize(value) : null;
+}
+
+/**
+ * One row's column score against a prepared probe: the packed column
+ * unpacked at the declared width and dotted with the probe. `null` for
+ * a row whose column holds no vector — SQL `NULL`, or bytes of another
+ * length — because such a row is unrankable and 0 is a real score.
+ * @param {unknown} bytes - the column value as the driver returns it
+ * @param {number} dims
+ * @param {Float32Array} probe - from {@link probeVector}
+ * @returns {number | null}
+ */
+export function columnScore(bytes, dims, probe) {
+  const vector = unpackVector(/** @type {any} */ (bytes), dims);
+  return vector === null ? null : dotProduct(vector, probe);
+}