@lunora/bindings 1.0.0-alpha.9 → 1.0.0-alpha.91

package/dist/r2sql/index.d.mts

@@ -18,13 +18,29 @@ declare const isSql: (value: unknown) => value is Sql;
 declare const raw: (text: string) => Sql;
 /** Resolve a `string | Sql` to its raw text. A bare string is taken as trusted SQL (callers pass identifiers/fragments here). */
 declare const toText: (value: Sql | string) => string;
+/**
+ * Validate a table/namespace/database identifier that will be spliced into R2 SQL
+ * text (which has no parameter binding and no identifier quoting we can rely on).
+ * Accepts only dotted `\w` segments and throws otherwise, so a client-supplied
+ * `describe`/`showTables` argument can't inject SQL. For a genuinely dynamic
+ * identifier you built yourself, wrap it with {@link raw}.
+ */
+declare const ident: (name: string) => string;
+/**
+ * Validate a table REFERENCE for a `FROM`/`JOIN` position: a dotted identifier
+ * plus an optional `[AS] alias`. Broader than {@link ident} (which forbids the
+ * alias) but still an allowlist — no whitespace beyond the single alias, no
+ * punctuation — so a caller-supplied table string can't inject SQL. Use
+ * {@link raw} for anything more dynamic that you built yourself.
+ */
+declare const tableRef: (ref: string) => string;
 /**
  * Render a JS value as an R2 SQL literal:
  *
  * - `null` / `undefined` → `NULL`
  * - `boolean` → `true` / `false`
  * - finite `number` / `bigint` → the numeric text (non-finite throws — `NaN`/`Infinity` have no SQL literal)
- * - `Date` → an RFC3339 string literal (R2 SQL's `timestamp` form)
+ * - `Date` → an RFC3339 string literal (R2 SQL's `timestamp` form; an invalid `Date` throws)
  * - `string` → a single-quoted, escaped literal
  * - `Array` → a parenthesised, comma-separated list of literals (for `IN (...)`)
  *
@@ -93,6 +109,16 @@ interface R2SqlConfig {
    * so a query never touches the network.
    */
   fetch?: typeof globalThis.fetch;
+  /**
+   * Milliseconds before an in-flight query (the fetch AND its body read) is
+   * aborted and surfaced as an `R2SqlError` with status 504. Defaults to
+   * 60_000 — analytical scans legitimately run tens of seconds. `undefined`
+   * means the default, not unbounded.
+   *
+   * The deadline is carried by the request's `signal`, so a custom `fetch`
+   * (above) that ignores `signal` leaves the query unbounded.
+   */
+  timeoutMs?: number;
 }
 /**
  * One column descriptor in a result's schema: the column `name` and, when the
@@ -109,8 +135,8 @@ interface R2SqlColumn {
  * (`{ success, result, errors }`); we surface the `rows` (the `result` array of
  * column→value records), the inferred/echoed `columns`, and the `rowCount`.
  *
- * `Row` defaults to an open record; supply it (`from<MyRow>(…)` /
- * `query<MyRow>(…)`) to get typed result fields — R2 SQL tables live in Iceberg,
+ * `Row` defaults to an open record; supply it (`from<MyRow>(…)` /
+ * `query<MyRow>(…)`) to get typed result fields — R2 SQL tables live in Iceberg,
  * not `defineSchema`, so the row type is caller-declared rather than inferred.
  */
 interface R2SqlResult<Row = Record<string, unknown>> {
@@ -225,11 +251,11 @@ declare class SelectBuilder<Row = Record<string, unknown>> implements Queryable<
   fullJoin(table: string, on: Condition): this;
   /** `CROSS JOIN table` (no `ON`). */
   crossJoin(table: string): this;
-  /** Add `WHERE` condition(s). Multiple calls (and multiple args) are `AND`-ed. Bind values with the `sql` tag. */
+  /** Add `WHERE` condition(s). Multiple calls (and multiple args) are `AND`-ed, each parenthesised. Bind values with the `sql` tag. */
   where(...conditions: Condition[]): this;
   /** `GROUP BY` column(s)/expression(s). */
   groupBy(...columns: (Sql | string)[]): this;
-  /** Add `HAVING` condition(s) over aggregates; multiple are `AND`-ed. */
+  /** Add `HAVING` condition(s) over aggregates; multiple are `AND`-ed, each parenthesised. */
   having(...conditions: Condition[]): this;
   /**
    * `QUALIFY` — filter on a window function without a subquery, e.g.
@@ -263,8 +289,11 @@ declare class SelectBuilder<Row = Record<string, unknown>> implements Queryable<
 }
 /**
  * Thrown when R2 SQL responds with a non-2xx status, an `success: false`
- * envelope, or an unparseable body; carries the HTTP `status` and the raw body
- * for the caller to surface.
+ * envelope, or an unparseable body; carries the HTTP `status` and a capped body
+ * preview for the caller to surface, with the full body on `cause`.
+ *
+ * The preview is capped because the engine's SQL error text quotes the query
+ * back, and `R2_SQL_ERROR` is non-internal — the message reaches the browser.
  */
 declare class R2SqlError extends LunoraError {
   constructor(status: number, body: string);
@@ -310,9 +339,9 @@ declare class WindowExpression extends Sql {
   gt(value: unknown): Sql;
   /** `expr >= value`. */
   gte(value: unknown): Sql;
-  /** `expr &lt; value`. */
+  /** `expr < value`. */
   lt(value: unknown): Sql;
-  /** `expr &lt;= value`. */
+  /** `expr <= value`. */
   lte(value: unknown): Sql;
   private compare;
 }
@@ -380,4 +409,19 @@ declare const fn: {
   /** `SUM(column) OVER (...)`. */
   sum: (column: Sql | string) => WindowFunction;
 };
-export { type Condition, type OrderTerm, type OverSpec, type QueryExecutor, type Queryable, type R2SqlClient, type R2SqlColumn, type R2SqlConfig, R2SqlError, type R2SqlExplainOptions, type R2SqlResult, SelectBuilder, SetOperation, Sql, WindowExpression, WindowFunction, asc, createR2Sql, desc, fn, isSql, joinSql, lit, raw, renderOrderTerm, sql, toText };
+export { type Condition, type OrderTerm, type OverSpec, type QueryExecutor, type Queryable, type R2SqlClient, type R2SqlColumn, type R2SqlConfig, R2SqlError, type R2SqlExplainOptions, type R2SqlResult,
+/**
+ * `@lunora/bindings/r2sql` — typed, chainable R2 SQL for Lunora.
+ *
+ * Query Cloudflare [R2 SQL](https://developers.cloudflare.com/r2-sql/) — the
+ * serverless engine over Apache Iceberg tables in R2 Data Catalog — from a
+ * Lunora **action** via `ctx.r2sql`. First-class support for the 2026-06-21
+ * features: window functions (`fn.rowNumber().over(...)`), `DISTINCT` /
+ * `DISTINCT ON`, `QUALIFY`, and set operations (`.union()/.intersect()/.except()`).
+ *
+ * R2 SQL is non-deterministic external I/O with no Workers binding, so — like
+ * `ctx.sql` (Hyperdrive) — it is wired onto `ActionCtx` only and its reads are
+ * not tracked by Lunora live queries (see the `r2sql_outside_action` advisor
+ * lint). See the README and `createR2Sql` JSDoc.
+ */
+SelectBuilder, SetOperation, Sql, WindowExpression, WindowFunction, asc, createR2Sql, desc, fn, ident, isSql, joinSql, lit, raw, renderOrderTerm, sql, tableRef, toText };

package/dist/r2sql/index.d.ts

@@ -18,13 +18,29 @@ declare const isSql: (value: unknown) => value is Sql;
 declare const raw: (text: string) => Sql;
 /** Resolve a `string | Sql` to its raw text. A bare string is taken as trusted SQL (callers pass identifiers/fragments here). */
 declare const toText: (value: Sql | string) => string;
+/**
+ * Validate a table/namespace/database identifier that will be spliced into R2 SQL
+ * text (which has no parameter binding and no identifier quoting we can rely on).
+ * Accepts only dotted `\w` segments and throws otherwise, so a client-supplied
+ * `describe`/`showTables` argument can't inject SQL. For a genuinely dynamic
+ * identifier you built yourself, wrap it with {@link raw}.
+ */
+declare const ident: (name: string) => string;
+/**
+ * Validate a table REFERENCE for a `FROM`/`JOIN` position: a dotted identifier
+ * plus an optional `[AS] alias`. Broader than {@link ident} (which forbids the
+ * alias) but still an allowlist — no whitespace beyond the single alias, no
+ * punctuation — so a caller-supplied table string can't inject SQL. Use
+ * {@link raw} for anything more dynamic that you built yourself.
+ */
+declare const tableRef: (ref: string) => string;
 /**
  * Render a JS value as an R2 SQL literal:
  *
  * - `null` / `undefined` → `NULL`
  * - `boolean` → `true` / `false`
  * - finite `number` / `bigint` → the numeric text (non-finite throws — `NaN`/`Infinity` have no SQL literal)
- * - `Date` → an RFC3339 string literal (R2 SQL's `timestamp` form)
+ * - `Date` → an RFC3339 string literal (R2 SQL's `timestamp` form; an invalid `Date` throws)
  * - `string` → a single-quoted, escaped literal
  * - `Array` → a parenthesised, comma-separated list of literals (for `IN (...)`)
  *
@@ -93,6 +109,16 @@ interface R2SqlConfig {
    * so a query never touches the network.
    */
   fetch?: typeof globalThis.fetch;
+  /**
+   * Milliseconds before an in-flight query (the fetch AND its body read) is
+   * aborted and surfaced as an `R2SqlError` with status 504. Defaults to
+   * 60_000 — analytical scans legitimately run tens of seconds. `undefined`
+   * means the default, not unbounded.
+   *
+   * The deadline is carried by the request's `signal`, so a custom `fetch`
+   * (above) that ignores `signal` leaves the query unbounded.
+   */
+  timeoutMs?: number;
 }
 /**
  * One column descriptor in a result's schema: the column `name` and, when the
@@ -109,8 +135,8 @@ interface R2SqlColumn {
  * (`{ success, result, errors }`); we surface the `rows` (the `result` array of
  * column→value records), the inferred/echoed `columns`, and the `rowCount`.
  *
- * `Row` defaults to an open record; supply it (`from<MyRow>(…)` /
- * `query<MyRow>(…)`) to get typed result fields — R2 SQL tables live in Iceberg,
+ * `Row` defaults to an open record; supply it (`from<MyRow>(…)` /
+ * `query<MyRow>(…)`) to get typed result fields — R2 SQL tables live in Iceberg,
  * not `defineSchema`, so the row type is caller-declared rather than inferred.
  */
 interface R2SqlResult<Row = Record<string, unknown>> {
@@ -225,11 +251,11 @@ declare class SelectBuilder<Row = Record<string, unknown>> implements Queryable<
   fullJoin(table: string, on: Condition): this;
   /** `CROSS JOIN table` (no `ON`). */
   crossJoin(table: string): this;
-  /** Add `WHERE` condition(s). Multiple calls (and multiple args) are `AND`-ed. Bind values with the `sql` tag. */
+  /** Add `WHERE` condition(s). Multiple calls (and multiple args) are `AND`-ed, each parenthesised. Bind values with the `sql` tag. */
   where(...conditions: Condition[]): this;
   /** `GROUP BY` column(s)/expression(s). */
   groupBy(...columns: (Sql | string)[]): this;
-  /** Add `HAVING` condition(s) over aggregates; multiple are `AND`-ed. */
+  /** Add `HAVING` condition(s) over aggregates; multiple are `AND`-ed, each parenthesised. */
   having(...conditions: Condition[]): this;
   /**
    * `QUALIFY` — filter on a window function without a subquery, e.g.
@@ -263,8 +289,11 @@ declare class SelectBuilder<Row = Record<string, unknown>> implements Queryable<
 }
 /**
  * Thrown when R2 SQL responds with a non-2xx status, an `success: false`
- * envelope, or an unparseable body; carries the HTTP `status` and the raw body
- * for the caller to surface.
+ * envelope, or an unparseable body; carries the HTTP `status` and a capped body
+ * preview for the caller to surface, with the full body on `cause`.
+ *
+ * The preview is capped because the engine's SQL error text quotes the query
+ * back, and `R2_SQL_ERROR` is non-internal — the message reaches the browser.
  */
 declare class R2SqlError extends LunoraError {
   constructor(status: number, body: string);
@@ -310,9 +339,9 @@ declare class WindowExpression extends Sql {
   gt(value: unknown): Sql;
   /** `expr >= value`. */
   gte(value: unknown): Sql;
-  /** `expr &lt; value`. */
+  /** `expr < value`. */
   lt(value: unknown): Sql;
-  /** `expr &lt;= value`. */
+  /** `expr <= value`. */
   lte(value: unknown): Sql;
   private compare;
 }
@@ -380,4 +409,19 @@ declare const fn: {
   /** `SUM(column) OVER (...)`. */
   sum: (column: Sql | string) => WindowFunction;
 };
-export { type Condition, type OrderTerm, type OverSpec, type QueryExecutor, type Queryable, type R2SqlClient, type R2SqlColumn, type R2SqlConfig, R2SqlError, type R2SqlExplainOptions, type R2SqlResult, SelectBuilder, SetOperation, Sql, WindowExpression, WindowFunction, asc, createR2Sql, desc, fn, isSql, joinSql, lit, raw, renderOrderTerm, sql, toText };
+export { type Condition, type OrderTerm, type OverSpec, type QueryExecutor, type Queryable, type R2SqlClient, type R2SqlColumn, type R2SqlConfig, R2SqlError, type R2SqlExplainOptions, type R2SqlResult,
+/**
+ * `@lunora/bindings/r2sql` — typed, chainable R2 SQL for Lunora.
+ *
+ * Query Cloudflare [R2 SQL](https://developers.cloudflare.com/r2-sql/) — the
+ * serverless engine over Apache Iceberg tables in R2 Data Catalog — from a
+ * Lunora **action** via `ctx.r2sql`. First-class support for the 2026-06-21
+ * features: window functions (`fn.rowNumber().over(...)`), `DISTINCT` /
+ * `DISTINCT ON`, `QUALIFY`, and set operations (`.union()/.intersect()/.except()`).
+ *
+ * R2 SQL is non-deterministic external I/O with no Workers binding, so — like
+ * `ctx.sql` (Hyperdrive) — it is wired onto `ActionCtx` only and its reads are
+ * not tracked by Lunora live queries (see the `r2sql_outside_action` advisor
+ * lint). See the README and `createR2Sql` JSDoc.
+ */
+SelectBuilder, SetOperation, Sql, WindowExpression, WindowFunction, asc, createR2Sql, desc, fn, ident, isSql, joinSql, lit, raw, renderOrderTerm, sql, tableRef, toText };

package/dist/r2sql/index.mjs

@@ -1,7 +1 @@
-export { default as SelectBuilder } from '../packem_shared/SelectBuilder-BOqJQHEv.mjs';
-export { R2SqlError, createR2Sql } from '../packem_shared/R2SqlError-drPKSCZ3.mjs';
-export { asc, desc, renderOrderTerm } from '../packem_shared/asc-DZbQCxh1.mjs';
-export { default as SetOperation } from '../packem_shared/SetOperation-DmPgUL8W.mjs';
-export { Sql, isSql, joinSql, lit, raw, sql, toText } from '../packem_shared/Sql-B3zq2YGx.mjs';
-export { WindowFunction, fn } from '../packem_shared/WindowFunction-DrnuZUF6.mjs';
-export { default as WindowExpression } from '../packem_shared/WindowExpression-BT_uA6g1.mjs';
+import{default as o}from"../packem_shared/SelectBuilder-DJXNSdqC.mjs";import{R2SqlError as l,createR2Sql as f}from"../packem_shared/R2SqlError-ZHgOWClB.mjs";import{asc as d,desc as i,renderOrderTerm as n}from"../packem_shared/asc-DP_WFiAE.mjs";import{default as s}from"../packem_shared/SetOperation-kiI5Wnlm.mjs";import{Sql as m,ident as S,isSql as q,joinSql as c,lit as u,raw as w,sql as R,tableRef as E,toText as O}from"../packem_shared/Sql-BfnxRway.mjs";import{WindowFunction as W,fn as b}from"../packem_shared/WindowFunction-CL4jYy2l.mjs";import{default as B}from"../packem_shared/WindowExpression-VX7EEV3h.mjs";export{l as R2SqlError,o as SelectBuilder,s as SetOperation,m as Sql,B as WindowExpression,W as WindowFunction,d as asc,f as createR2Sql,i as desc,b as fn,S as ident,q as isSql,c as joinSql,u as lit,w as raw,n as renderOrderTerm,R as sql,E as tableRef,O as toText};

package/dist/vectors/index.d.mts

@@ -1,55 +1,5 @@
-/**
- * Minimal structural projection of `VectorizeIndex` so unit tests can pass a
- * plain-object double and the real Cloudflare binding satisfies the same shape.
- * Mirrors the surface documented at
- * https://developers.cloudflare.com/vectorize/reference/client-api/.
- */
-interface VectorizeIndexLike {
-  deleteByIds: (ids: ReadonlyArray<string>) => Promise<VectorizeDeleteMutation>;
-  describe?: () => Promise<VectorizeIndexDetails>;
-  getByIds: (ids: ReadonlyArray<string>) => Promise<ReadonlyArray<VectorizeVector>>;
-  insert: (vectors: ReadonlyArray<VectorizeVector>) => Promise<VectorizeUpsertMutation>;
-  query: (vector: ReadonlyArray<number>, options?: VectorizeQueryOptions) => Promise<VectorizeMatches>;
-  upsert: (vectors: ReadonlyArray<VectorizeVector>) => Promise<VectorizeUpsertMutation>;
-}
-type VectorMetric = "cosine" | "euclidean" | "dot-product";
-interface VectorizeVector {
-  id: string;
-  metadata?: Record<string, unknown>;
-  namespace?: string;
-  values: ReadonlyArray<number>;
-}
-interface VectorizeQueryOptions {
-  filter?: Record<string, unknown>;
-  namespace?: string;
-  returnMetadata?: "none" | "indexed" | "all";
-  returnValues?: boolean;
-  topK?: number;
-}
-interface VectorizeMatch {
-  id: string;
-  metadata?: Record<string, unknown>;
-  namespace?: string;
-  score: number;
-  values?: ReadonlyArray<number>;
-}
-interface VectorizeMatches {
-  count: number;
-  matches: ReadonlyArray<VectorizeMatch>;
-}
-interface VectorizeUpsertMutation {
-  mutationId: string;
-}
-interface VectorizeDeleteMutation {
-  count?: number;
-  mutationId: string;
-}
-interface VectorizeIndexDetails {
-  dimensions: number;
-  processedUpToDatetime?: string;
-  processedUpToMutation?: string;
-  vectorsCount: number;
-}
+import { VectorizeDeleteMutation, VectorizeIndexDetails, VectorizeVector, VectorizeMatches, VectorizeUpsertMutation, VectorizeIndexLike, VectorMetric } from '@lunora/platform';
+export type { VectorMetric, VectorizeDeleteMutation, VectorizeIndexDetails, VectorizeIndexLike, VectorizeMatch, VectorizeMatches, VectorizeQueryOptions, VectorizeUpsertMutation, VectorizeVector } from '@lunora/platform';
 /**
  * Bring-your-own-embedder: a user-supplied async fn that converts a single
  * source value (a row, a chunk, an arbitrary string) into a numeric vector.
@@ -107,6 +57,7 @@ interface VectorMatchesLike {
 interface VectorRecordLike {
   id: string;
   metadata?: Record<string, unknown>;
+  namespace?: string;
   values: ReadonlyArray<number>;
 }
 interface VectorQueryInputLike {
@@ -134,22 +85,125 @@ interface VectorUpsertInputLike {
 /**
  * Structural mirror of `@lunora/server`'s `VectorSearch`. Declared here so the
  * adapter never imports `@lunora/server` (keeps the dependency edge one-way:
- * the generated DO depends on both, neither depends on the other).
+ * the generated DO depends on both, neither depends on the other). `getByIds`/
+ * `deleteByIds` carry an optional trailing `namespace` — a pure addition (more
+ * general, not narrower) that stays assignable to `@lunora/server`'s
+ * `VectorSearchReader`/`VectorSearch`, whose own two-argument signatures are
+ * unchanged: a function accepting an extra OPTIONAL parameter is assignable
+ * wherever a function taking fewer parameters is expected.
  */
 interface VectorSearchLike {
-  deleteByIds: (indexName: string, ids: ReadonlyArray<string>) => Promise<void>;
-  getByIds: (indexName: string, ids: ReadonlyArray<string>) => Promise<ReadonlyArray<VectorRecordLike>>;
+  deleteByIds: (indexName: string, ids: ReadonlyArray<string>, namespace?: string) => Promise<void>;
+  getByIds: (indexName: string, ids: ReadonlyArray<string>, namespace?: string) => Promise<ReadonlyArray<VectorRecordLike>>;
   query: (indexName: string, input: VectorQueryInputLike) => Promise<VectorMatchesLike>;
   upsert: (indexName: string, input: VectorUpsertInputLike) => Promise<void>;
   upsertNow: (indexName: string, input: VectorUpsertInputLike) => Promise<void>;
 }
+/** Options for {@link createContextVectors}. */
+interface CreateContextVectorsOptions {
+  /**
+   * Hold `upsert`'s remote write until the caller's storage transaction has
+   * COMMITTED, running it at once when none is open. The shard host supplies
+   * `ShardDO.deferAfterCommit`; codegen wires it.
+   *
+   * This is what separates `upsert` from `upsertNow`. Vectorize is outside the
+   * shard's SQLite and cannot roll back, so an inline `ctx.vectors.upsert` in a
+   * mutation that later throws leaves a vector pointing at a row that does not
+   * exist — and a search surfaces it. Omitted, both methods write inline, which
+   * is correct for a caller that has no transaction to wait for (an action, a
+   * test, the `@lunora/ai` RAG helpers).
+   */
+  deferAfterCommit?: (work: () => Promise<void>) => Promise<void>;
+  /**
+   * The DO's own shard/tenant key, applied as the default `namespace` for
+   * an operation against an index in `shardedIndexNames` that doesn't pass
+   * one explicitly. `undefined` means this instance HAS no shard key —
+   * always true for the root/default DO instance, since only a per-tenant
+   * instance owns one. See `shardedIndexNames` for what that implies per
+   * index, and {@link createContextVectors}'s docblock for the full
+   * root-instance rule.
+   */
+  namespace?: string;
+  /**
+   * Vector index names sourced from a `.shardBy()`'d table — the ones
+   * `namespace` is a meaningful tenant scope for. `ctx.vectors` is a single
+   * flat facade over EVERY declared index (root-scoped and sharded tables
+   * alike — Vectorize indexes are account-global and `config.vectors(env)`
+   * registers them all in one flat map), reachable from ANY DO instance —
+   * so `namespace` can only be a safe default for the indexes actually
+   * listed here.
+   *
+   * An index NOT in this set (sourced from a root-scoped table) always
+   * stays namespace-less, regardless of `namespace` or which DO instance
+   * calls it — it has no tenant identity to begin with, so scoping it would
+   * silently return nothing for legitimate, intentionally shared data (and,
+   * called from a per-tenant instance, would wrongly search under that
+   * tenant's namespace even though nothing was ever written there under
+   * it). An index IN this set, called from a per-tenant DO instance
+   * (`namespace` is set), defaults to `namespace`, scoping correctly. An
+   * index IN this set, called from the root/default DO instance
+   * (`namespace` is `undefined`) with no explicit override, is unsafe to
+   * default at all — see {@link createContextVectors}'s docblock.
+   *
+   * Omitted (or empty) → no index is ever treated as sharded, i.e.
+   * `namespace` never applies as a default on any call — the unsharded-app,
+   * byte-identical-to-today case.
+   */
+  shardedIndexNames?: ReadonlyArray<string>;
+}
 /**
  * Bridge `LunoraVectors` (returns Vectorize mutation receipts) to the server's
- * `VectorSearch` contract (void mutations, server match/record shapes). Both
- * `upsert` and `upsertNow` write inline — this design has no post-commit queue,
- * so "now" and "deferred" collapse to the same synchronous call.
+ * `VectorSearch` contract (void mutations, server match/record shapes).
+ *
+ * `upsert` vs `upsertNow` — IMPORTANT: with `options.deferAfterCommit` supplied
+ * (codegen wires the shard host's), `upsert` holds the remote write until the
+ * caller's transaction has committed and `upsertNow` writes inline, which is
+ * what `MutationCtx`'s contract documents. Without it both write inline: a
+ * caller with no transaction open has nothing to wait for. The NAMESPACE is
+ * resolved eagerly either way — before the deferral, not inside it — so a
+ * misconfiguration (the root-instance throw below) still reaches the handler
+ * that made the call instead of a post-commit log line nobody is holding.
+ *
+ * Tenant isolation (read side) — IMPORTANT: an explicit `namespace` argument
+ * on any call (`input.namespace` for `query`/`upsert`/`upsertNow`, the
+ * trailing `namespace` parameter for `getByIds`/`deleteByIds`) ALWAYS wins —
+ * this is a deliberate soft default, not a hard boundary: `ctx.vectors` is
+ * trusted server-side app code (the same trust level that lets `ctx.db` read
+ * any table), so a caller that explicitly names a namespace is trusted to
+ * mean it, including a legitimate cross-tenant admin read/write. Absent an
+ * explicit namespace, `options.namespace` (this DO instance's own shard key)
+ * is the DEFAULT for any index in `options.shardedIndexNames` — see that
+ * option's docblock for why the default is index-scoped rather than global.
+ *
+ * Root-instance rule — IMPORTANT: when an operation targets a sharded index
+ * (one in `shardedIndexNames`) and BOTH the explicit argument and
+ * `options.namespace` are absent (this is the root/default DO instance, which
+ * owns no shard key), there is no safe default and no override — this THROWS
+ * rather than silently resolving to "no namespace". A namespace-less
+ * query/getByIds/deleteByIds/upsert against a sharded index would reach or
+ * mutate EVERY tenant's vectors (Vectorize indexes are account-global), which
+ * is the exact cross-tenant leak this file exists to close; returning an
+ * empty result set instead would masquerade that same configuration problem
+ * as "no data", which is worse — a caller debugging it sees nothing rather
+ * than a directed error. This case is reachable in a MIXED schema (some
+ * vectorized tables `.shardBy()`'d, others root-scoped) whenever application
+ * code queries a sharded index's name from the root DO instance without an
+ * explicit namespace; it is not reachable from `createVectorSyncHook`'s own
+ * internal calls, which only ever process a table this DO instance owns (so
+ * a sharded table's write never reaches a root instance in the first place).
+ *
+ * Id path, unrelated axis — IMPORTANT: independent of the override/root rules
+ * above, `getByIds`/`deleteByIds` can't ask Vectorize to filter by namespace
+ * remotely at all (its id-based operations take no `namespace` option), so
+ * once a namespace IS resolved (explicit or defaulted) for these two methods,
+ * isolation is enforced client-side: `getByIds` drops any returned record
+ * whose `namespace` doesn't match (fail closed: a record with no `namespace`
+ * field is treated as a mismatch, never as "belongs to everyone"), and
+ * `deleteByIds` resolves ids via `getByIds` first and only deletes the subset
+ * that belongs to the resolved namespace — silently, by design (see the
+ * `deleteByIds` implementation for the no-signal tradeoff this makes).
  */
-declare const createContextVectors: (lunora: LunoraVectors) => VectorSearchLike;
+declare const createContextVectors: (lunora: LunoraVectors, options?: CreateContextVectorsOptions) => VectorSearchLike;
 /** A single row mutation observed by the ctx-db, fed to {@link createVectorSyncHook}. */
 interface WriteEvent {
   doc?: Record<string, unknown>;
@@ -160,18 +214,30 @@ interface WriteEvent {
 type WriteHook = (event: WriteEvent) => Promise<void>;
 /** Inline vector index declared via `.vectorize(field, ...)` (DSL Shape A). */
 interface TableVectorIndexLike {
+  dimensions?: number;
   embed: VectorEmbedderLike;
   field: string;
   metadata?: ReadonlyArray<string>;
+  metric?: string;
+  /** Declared identifier of what `embed` produces; part of the backfill fingerprint. */
+  model?: string;
   name: string;
 }
 interface TableDefinitionLike {
+  /** `.softDelete()` marker column. A row whose marker is set is hidden from `ctx.db`, so it must have no vector. */
+  softDeleteMode?: {
+    field: string;
+  };
   vectorIndexes?: ReadonlyArray<TableVectorIndexLike>;
 }
 /** Standalone vector index declared via `defineVectorIndex(...)` (DSL Shape B). */
 interface VectorIndexDefinitionLike {
+  dimensions?: number;
   embed: VectorEmbedderLike;
   metadata?: (row: Record<string, unknown>) => Record<string, unknown>;
+  metric?: string;
+  /** Declared identifier of what `embed` produces; part of the backfill fingerprint. */
+  model?: string;
   select: (row: Record<string, unknown>) => string;
   table: string;
 }
@@ -188,7 +254,7 @@ interface SchemaLike {
  * Build a {@link WriteHook} that keeps Vectorize in sync with row writes. On
  * insert/update it embeds each matching index's source (Shape A `row[field]`,
  * Shape B `select(row)`) and upserts; on delete it removes the row's id from
- * every index sourced from the table. Runs inline within the write path.
+ * every index sourced from the table. {@link planRowSync} makes the decision.
  *
  * Tenant isolation — IMPORTANT: Vectorize indexes are account-global and shared
  * by every shard DO. Without a `namespace`, a multi-tenant sharded app has NO
@@ -202,16 +268,41 @@ interface SchemaLike {
  * (regardless of whether metadata is present); a genuinely single-tenant app
  * suppresses it with `allowSharedNamespace: true`.
  *
- * Consistency — IMPORTANT: this hook runs inline within the mutation but talks
- * to Vectorize, which is external and non-transactional. The per-index calls
- * fan out; if one fails after others have already applied, the SQLite write may
- * roll back while the applied Vectorize mutations cannot — leaving SQLite and
- * Vectorize diverged. We mitigate, not eliminate: upserts/deletes are
- * idempotent (keyed by row id), so a retry of the same write converges; and on
- * a fan-out failure we attempt a best-effort compensating delete of the row's
- * id from every affected index before re-throwing. A delete after a failed
- * upsert can itself fail — this is best-effort, the authoritative recovery is
- * re-running the (idempotent) write.
+ * Since plan 255, codegen satisfies the query-side requirement automatically
+ * for a `.shardBy()`'d vectorized table: the `vectors` instance passed in
+ * `options` here is the SAME `createContextVectors(...)` instance exposed as
+ * `ctx.vectors`, constructed with the identical shard-key `namespace` default
+ * AND the identical `shardedIndexNames` — so `ctx.vectors.query`/`getByIds`/
+ * `deleteByIds` are scoped without any app code changes. One consequence of
+ * sharing that instance: this hook's own internal `deleteByIds` calls (on row
+ * delete and on a cleared inline field) now also go through the
+ * namespace-verifying path described on
+ * {@link createContextVectors} — an extra `getByIds` subrequest per
+ * delete-shaped write, not a behavior change (the row being deleted was
+ * written under this same shard's namespace, so the verification passes).
+ * This never hits {@link createContextVectors}'s root-instance throw: a write
+ * event only ever fires for a table THIS DO instance owns, so if this hook
+ * processes a write for a sharded index, this instance IS a real per-tenant
+ * shard (not root) — `namespace` here is never `undefined` for that index.
+ *
+ * Consistency — IMPORTANT: Vectorize is external and non-transactional, so this
+ * hook runs AFTER the mutation's transaction has committed, never inside it (the
+ * shard host holds it — `ShardDO.deferAfterCommit`). That ordering is what stops
+ * a rolled-back write from leaving a vector for a row that does not exist, and a
+ * rolled-back delete from leaving a live row with its vector already purged.
+ *
+ * Two commits to the same row do not race: the shard host drains one
+ * transaction's held work entirely before the next transaction's, so the hooks
+ * apply in COMMIT order even though each may take hundreds of milliseconds. Fan
+ * out within a single hook is still unordered — the indexes are independent.
+ *
+ * What remains is the opposite divergence, and it is the one worth having: the
+ * row is committed and this hook may still fail — fully, or partway through a
+ * fan-out that already applied to some indexes. The row is then indexed in some
+ * indexes and not others. Nothing is compensated, deliberately: the row SURVIVES
+ * a failure here, so purging the indexes that did apply would turn a partially
+ * indexed row into an unsearchable one. Upserts and deletes are idempotent
+ * (keyed by row id), so re-running the same write converges.
  */
 declare const createVectorSyncHook: (options: {
   allowSharedNamespace?: boolean;
@@ -219,6 +310,80 @@ declare const createVectorSyncHook: (options: {
   schema: SchemaLike;
   vectors: VectorSearchLike;
 }) => WriteHook;
+/** A row the backfill could not index, and why. */
+interface VectorBackfillFailure {
+  error: unknown;
+  id: string;
+}
+/**
+ * Index one page of rows for the shard's vector backfill. Resolves with the rows
+ * that failed on their own; REJECTS when the failure is the service's rather than
+ * a row's, so the caller holds its cursor and retries the page — with a
+ * `SERVICE_UNAVAILABLE` `LunoraError` when the error shows the failure to be
+ * transient, and with the raw error when only the whole page failing suggests it.
+ */
+type VectorBackfillSync = (table: string, rows: ReadonlyArray<{
+  doc: Record<string, unknown>;
+  id: string;
+}>) => Promise<ReadonlyArray<VectorBackfillFailure>>;
+/**
+ * The backfill's counterpart to {@link createVectorSyncHook}: the same
+ * {@link planRowSync} decision for a whole page of rows, with the remote calls
+ * batched — every row is embedded (bounded concurrency), then each index takes
+ * ONE `upsertMany` and ONE `deleteByIds` per 1000 rows instead of a call per row.
+ * That is what keeps a page short enough to hold the shard's write-hook chain.
+ *
+ * Failures are split in two, because they need opposite handling.
+ *
+ * A ROW failure is deterministic and would fail on every retry: a non-string
+ * source, a `select()` that throws, text the model rejects, metadata Vectorize
+ * refuses. The row is reported and the page moves on — the live hook only logs
+ * these too, and a backfill that stopped on one would never finish.
+ *
+ * A SERVICE failure is transient: the embedder or Vectorize is unreachable. The
+ * call rejects, so the page is retried. It is recognised by the error where the
+ * error says (an HTTP 5xx/408/429 status, a timeout — see {@link classifyFailure};
+ * these reject as `SERVICE_UNAVAILABLE`), and otherwise as every attempt in a
+ * group of two or more failing, and as a failed `deleteByIds` (which has no row
+ * content to blame). A batch `upsertMany` that fails is retried one row at a
+ * time to tell the two apart. A group that fails whole on every retry — each
+ * row refused for the same reason, with no status to show it — rejects each
+ * time too; the backfill writes such a page off after a few consecutive tries.
+ *
+ * `upsertMany` is the raw binding call, so the namespace is passed explicitly —
+ * the same `namespace` the live hook scopes by.
+ */
+type BackfillSyncOptions = {
+  allowSharedNamespace?: boolean;
+  namespace?: string;
+  schema: SchemaLike;
+  upsertMany: LunoraVectors["upsertMany"];
+  vectors: VectorSearchLike;
+};
+declare const createVectorBackfillSync: (options: BackfillSyncOptions) => VectorBackfillSync;
+/**
+ * Every table with a vector index sourced from it, each with a fingerprint of
+ * what its stored vectors were built from — the input to the shard's vector
+ * backfill, which re-walks a table whose fingerprint changed.
+ *
+ * Covers what the schema can see: index names, the inline source field,
+ * dimensions, metric, inline metadata fields, the declared `model`, and the
+ * table's `.softDelete()` field — a row hidden by a newly chosen marker keeps
+ * its vector until the table is walked again. A
+ * function (`embed`, a Shape B `select`/`metadata`) has no stable identity to
+ * fingerprint — its source text changes with unrelated rebuilds of the bundle,
+ * which would re-embed whole tables for nothing — so the declared `model` string
+ * stands in for `embed`, and any other change is announced by calling the
+ * backfill with `restart: true`.
+ *
+ * `model` joins a descriptor only when declared, and the soft-delete field only
+ * when the table has one, so an index without either keeps the fingerprint it
+ * was recorded under and is not re-embedded for it.
+ */
+declare const vectorBackfillTargets: (schema: SchemaLike) => {
+  profile: string;
+  table: string;
+}[];
 /**
  * One vector index as the generated `LUNORA_VECTOR_INDEXES` registry describes
  * it — the static schema shape, independent of any live binding. Structurally
@@ -282,4 +447,4 @@ interface VectorAdminIntrospectorOptions {
  */
 declare const createVectorAdminIntrospector: (options: VectorAdminIntrospectorOptions) => VectorAdminIntrospector;
 declare const createVectors: (options: LunoraVectorsOptions) => LunoraVectors;
-export { type EmbedFunction, type LunoraVectors, type LunoraVectorsOptions, type QueryInput, type SchemaLike, type TableDefinitionLike, type TableVectorIndexLike, type UpsertInput, type VectorAdminIndexSummary, type VectorAdminIntrospector, type VectorAdminIntrospectorOptions, type VectorAdminQueryMatch, type VectorEmbedderLike, type VectorIndexDefinitionLike, type VectorIndexRegistryEntry, type VectorMatchLike, type VectorMatchesLike, type VectorMetric, type VectorQueryInputLike, type VectorRecordLike, type VectorSearchLike, type VectorUpsertInputLike, type VectorizeDeleteMutation, type VectorizeIndexDetails, type VectorizeIndexLike, type VectorizeMatch, type VectorizeMatches, type VectorizeQueryOptions, type VectorizeUpsertMutation, type VectorizeVector, type WriteEvent, type WriteHook, createContextVectors, createVectorAdminIntrospector, createVectorSyncHook, createVectors };
+export { type EmbedFunction, type LunoraVectors, type LunoraVectorsOptions, type QueryInput, type SchemaLike, type TableDefinitionLike, type TableVectorIndexLike, type UpsertInput, type VectorAdminIndexSummary, type VectorAdminIntrospector, type VectorAdminIntrospectorOptions, type VectorAdminQueryMatch, type VectorBackfillFailure, type VectorBackfillSync, type VectorEmbedderLike, type VectorIndexDefinitionLike, type VectorIndexRegistryEntry, type VectorMatchLike, type VectorMatchesLike, type VectorQueryInputLike, type VectorRecordLike, type VectorSearchLike, type VectorUpsertInputLike, type WriteEvent, type WriteHook, createContextVectors, createVectorAdminIntrospector, createVectorBackfillSync, createVectorSyncHook, createVectors, vectorBackfillTargets };