@lunora/ai 1.0.0-alpha.11 → 1.0.0-alpha.111

package/dist/rag/index.d.mts

@@ -0,0 +1,1364 @@
+import { Tool } from 'ai';
+import { E as EmbeddingModelInput, a as LunoraAi } from "../packem_shared/types.d-D-WK1t2B.mjs";
+/**
+ * Built-in fixed-window chunker: split into `size`-char windows overlapping by
+ * `overlap` chars. Deliberately simple and deterministic — the zero-config
+ * default. Token-aware / sentence / semantic strategies plug in via
+ * `RagConfig.chunk`.
+ * @experimental
+ */
+declare const fixedWindowChunks: (text: string, size: number, overlap: number) => ReadonlyArray<string>;
+/**
+ * Options shared by the character-budgeted chunkers. `overlap` is a **floor**
+ * in characters: enough trailing atoms are carried into the next window to
+ * cover it, so the realised overlap lands on an atom boundary and is usually a
+ * little larger.
+ */
+interface ChunkerOptions {
+  /** Overlap floor between adjacent chunks, in characters. Default 200. Must be `< size`. */
+  overlap?: number;
+  /** Maximum chunk size, in characters. Default 1000. */
+  size?: number;
+}
+/**
+ * Options for {@link tokenChunker}.
+ *
+ * `countTokens` is **required and injected**: a real token count needs the
+ * model's tokenizer, and `@lunora/ai` will not add one as a dependency or
+ * pretend a characters-per-token constant is a token count — a "token-aware"
+ * chunker built on an estimate is a character chunker with extra steps, and it
+ * silently overshoots on code and non-Latin scripts, which is exactly where the
+ * budget matters. Pass `js-tiktoken`, `gpt-tokenizer`, or your provider's
+ * counter.
+ */
+interface TokenChunkerOptions {
+  /** Token counter for the target model — e.g. `(text) => encoding.encode(text).length`. */
+  countTokens: (text: string) => number;
+  /** Maximum chunk size, in tokens. Default 256. */
+  maxTokens?: number;
+  /** Overlap floor between adjacent chunks, in tokens. Default 0. Must be `< maxTokens`. */
+  overlapTokens?: number;
+}
+/**
+ * Split on sentence boundaries, then greedily pack whole sentences into
+ * `size`-bounded chunks. Prefer this over the fixed window for prose: chunks
+ * start and end where the author ended a thought, which is what the embedding
+ * model was trained on.
+ * @experimental
+ */
+declare const sentenceChunker: (options?: ChunkerOptions) => ((text: string) => ReadonlyArray<string>);
+/**
+ * Split a Markdown document at its ATX headings, then pack each section's
+ * sentences into `size`-bounded chunks.
+ *
+ * Every emitted chunk is prefixed with its **heading trail** (`# Guide > ##
+ * Auth > ### OAuth`), so a chunk taken from deep inside a long document still
+ * carries the context that says what it is about. That prefix is what makes a
+ * mid-document chunk retrievable by a query naming its section rather than its
+ * prose, and it is why this beats {@link sentenceChunker} on structured docs.
+ * @experimental
+ */
+declare const markdownChunker: (options?: ChunkerOptions) => ((text: string) => ReadonlyArray<string>);
+/**
+ * Pack sentences into chunks bounded by a real **token** count rather than a
+ * character count. Use this when the embedding model's context window is the
+ * binding constraint — a 512-token model silently truncates anything longer, so
+ * the tail of an over-long chunk is embedded as if it were never written.
+ * @experimental
+ */
+declare const tokenChunker: (options: TokenChunkerOptions) => ((text: string) => ReadonlyArray<string>);
+/**
+ * What a store can hold and return. Every field is a hard limit `defineRag`
+ * enforces locally, so a breach fails here — naming the store and the limit —
+ * rather than at the backend with nothing saying why.
+ */
+interface RagVectorStoreCapabilities {
+  /**
+   * Ceiling on embedding dimensionality, or `false` for no limit.
+   *
+   * Vectorize stores at most 1536 at 32-bit precision, which rules out
+   * `text-embedding-3-large` (3072) and Qwen3-Embedding (4096). A store with
+   * no such limit declares `false` and those models just work.
+   */
+  maxDimensions: number | false;
+  /**
+   * Ceiling on a vector's id, in bytes, or `false` for no limit.
+   *
+   * Vectorize allows 64, and chunk ids are derived from the namespace and the
+   * caller's source id — a bucket key like
+   * `handbook/engineering/onboarding/day-one.md` under a uuid namespace is
+   * already past it. Without this the upsert is rejected at the far side with
+   * nothing naming the cause, the same failure {@link RagVectorStoreCapabilities.maxMetadataBytes}
+   * exists to replace.
+   */
+  maxIdBytes: number | false;
+  /**
+   * Ceiling on the serialized metadata object per vector, in bytes, or
+   * `false` for no limit. Covers the whole object — chunk text included when
+   * no `textStore` moves it out.
+   */
+  maxMetadataBytes: number | false;
+  /** Ceiling on `topK` when only indexed metadata is requested (text-store mode). */
+  maxTopK: number;
+  /** Ceiling on `topK` when the query asks for full metadata (the default mode). */
+  maxTopKWithMetadata: number;
+}
+/**
+ * The storage operations `defineRag` needs. Deliberately the same four
+ * operations `RagVectors` already exposes — this is a capability-carrying
+ * wrapper, not a new protocol, so adapting an existing implementation is a
+ * one-liner.
+ */
+interface RagVectorStore {
+  capabilities: RagVectorStoreCapabilities;
+  deleteByIds: (ids: ReadonlyArray<string>, namespace?: string) => Promise<unknown>;
+  getByIds: (ids: ReadonlyArray<string>, namespace?: string) => Promise<ReadonlyArray<RagVectorRecord>>;
+  query: (input: RagVectorQueryInput) => Promise<RagVectorMatches>;
+  upsert: (input: RagVectorUpsertInput) => Promise<unknown>;
+}
+/**
+ * Vectorize's documented limits.
+ *
+ * `maxTopKWithMetadata` is 50, matching Vectorize V2. **Legacy V1 indexes cap
+ * at 20** and reject a larger `topK` remotely; a binding handle does not expose
+ * its index version, so this cannot branch on it.
+ */
+declare const VECTORIZE_CAPABILITIES: RagVectorStoreCapabilities;
+/**
+ * Wrap a `ctx.vectors` facade (or any {@link RagVectors}) as a store declaring
+ * Vectorize's limits. This is the default when no `store` is configured, so the
+ * behaviour of an existing `defineRag` is unchanged.
+ * @experimental
+ */
+declare const vectorizeStore: (vectors: RagVectors, indexName: string) => RagVectorStore;
+/**
+ * `(text) => vector` — the embedder shape `ctx.vectors` accepts on both its
+ * write (`upsert`) and read (`query`) inputs. Matches `@lunora/server`'s
+ * `VectorEmbedder` and `@lunora/bindings/vectors`' `EmbedFunction<string>`.
+ * @experimental
+ */
+type RagEmbedder = (input: string) => Promise<ReadonlyArray<number>> | ReadonlyArray<number>;
+/**
+ * `RagVectorMatch` is part of the experimental `@lunora/ai` API and may change without a major version bump.
+ * @experimental
+ */
+interface RagVectorMatch {
+  id: string;
+  metadata?: Record<string, unknown>;
+  score: number;
+}
+/**
+ * `RagVectorMatches` is part of the experimental `@lunora/ai` API and may change without a major version bump.
+ * @experimental
+ */
+interface RagVectorMatches {
+  count: number;
+  matches: ReadonlyArray<RagVectorMatch>;
+}
+/**
+ * `RagVectorQueryInput` is part of the experimental `@lunora/ai` API and may change without a major version bump.
+ * @experimental
+ */
+interface RagVectorQueryInput {
+  /** Embedder used to vectorize `input`. */
+  embed?: RagEmbedder;
+  filter?: Record<string, unknown>;
+  /** Natural-language query text, embedded via `embed`. */
+  input?: string;
+  namespace?: string;
+  /**
+   * How much stored metadata to return on matches. The runtime honours it even
+   * though `@lunora/server`'s ctx type does not declare it — the helper relies
+   * on it to read chunk text back in metadata mode.
+   */
+  returnMetadata?: "all" | "indexed" | "none";
+  topK?: number;
+}
+/**
+ * `RagVectorRecord` is part of the experimental `@lunora/ai` API and may change without a major version bump.
+ * @experimental
+ */
+interface RagVectorRecord {
+  id: string;
+  metadata?: Record<string, unknown>;
+}
+/**
+ * `RagVectorUpsertInput` is part of the experimental `@lunora/ai` API and may change without a major version bump.
+ * @experimental
+ */
+interface RagVectorUpsertInput {
+  /** Embedder used to vectorize `input`. Optional — omitted for text-search indexes. */
+  embed?: RagEmbedder;
+  id: string;
+  input: string;
+  metadata?: Record<string, unknown>;
+  namespace?: string;
+}
+/**
+ * Structural subset of the vector surface the RAG helper needs. Both the
+ * `ctx.vectors` facade on Mutation/Action ctx (`@lunora/server`'s
+ * `VectorSearch`) and the raw `@lunora/bindings/vectors` `LunoraVectors`
+ * satisfy it — declared here so `@lunora/ai` depends on neither package.
+ * @experimental
+ */
+interface RagVectors {
+  deleteByIds: (indexName: string, ids: ReadonlyArray<string>, namespace?: string) => Promise<unknown>;
+  getByIds: (indexName: string, ids: ReadonlyArray<string>, namespace?: string) => Promise<ReadonlyArray<RagVectorRecord>>;
+  query: (indexName: string, input: RagVectorQueryInput) => Promise<RagVectorMatches>;
+  upsert: (indexName: string, input: RagVectorUpsertInput) => Promise<unknown>;
+}
+/**
+ * The two facades `defineRag` binds. An `ActionCtx` satisfies this directly
+ * (`ctx.ai` is action-only, so RAG methods run inside actions); any object
+ * carrying the two facades works in tests.
+ * @experimental
+ */
+interface RagContext {
+  /**
+   * Resolves a Workers AI embedding-model id (or the omitted default) — an
+   * `ActionCtx`'s `ctx.ai` satisfies it. OPTIONAL: when
+   * {@link RagConfig.embeddingModel} is a direct AI SDK `EmbeddingModel` object
+   * (bring-your-own embeddings, e.g. `@ai-sdk/openai`), the helper uses that
+   * object as-is and never reads `ai`, so a hand-built context may omit it and
+   * no `env.AI` binding is needed. A model-id string (or an omitted model) with
+   * no `ai` present throws a directed error.
+   */
+  ai?: Pick<LunoraAi, "embeddingModel">;
+  /**
+   * The verified retrieval identity, read by {@link RagConfig.rlsFilter} to
+   * derive a per-request row filter. An `ActionCtx` carrying `ctx.auth`
+   * satisfies this structurally, so `docs(ctx)` picks the identity up
+   * automatically; tests pass any value. `unknown` on purpose — `@lunora/ai`
+   * stays decoupled from `@lunora/server`'s identity type; `rlsFilter` narrows.
+   */
+  auth?: unknown;
+  /**
+   * Optional conversation / session id. When set (and `trace` is present), each
+   * embedding-model span additionally carries `gen_ai.conversation.id`, so a
+   * RAG embed done inside a multi-turn conversation groups with that
+   * conversation's other generation spans in the trace store. Omitted → the
+   * attribute is absent (backward-compatible).
+   */
+  conversationId?: string;
+  /**
+   * Optional `ctx.metrics` — an `ActionCtx`'s `ctx.metrics` satisfies it. When
+   * present, every embed counts its tokens and cost into the durable
+   * `gen_ai.usage.*` series, like a `ctx.ai.model(...)` call. `unknown` for the
+   * same decoupling reason as `trace`; `defineRag` narrows it.
+   */
+  metrics?: unknown;
+  /**
+   * Optional `ctx.trace` span factory — an `ActionCtx`'s `ctx.trace` satisfies
+   * it structurally. When present, `defineRag` wraps each embedding-model
+   * call in a `generation` span carrying `gen_ai.operation.name: "embeddings"`
+   * and `gen_ai.request.model` up front, plus — attached post-hoc through the
+   * span handle the tracer hands the body — `gen_ai.usage.input_tokens` (from
+   * the embed result's token usage) and `gen_ai.usage.cost` (probed from the
+   * embed result's provider metadata, e.g. AI Gateway) when those are present.
+   * So the embed shows up on the trace waterfall with its usage like any other
+   * instrumented model call. `unknown` on purpose — the same decoupling
+   * rationale as `auth`: `defineRag` narrows it to a callable and runs embeds
+   * untraced when it is absent (a hand-built context / test).
+   */
+  trace?: unknown;
+  /**
+   * The Vectorize facade backing the default store — an `ActionCtx`'s
+   * `ctx.vectors` satisfies it.
+   *
+   * OPTIONAL, because it is never read when {@link RagConfig.store} is set,
+   * and codegen only emits `ctx.vectors` for a schema that declares a vector
+   * index. Requiring it made "the store that needs no Vectorize" impossible
+   * to type-check in an app with no Vectorize index. Absent with no `store`
+   * configured throws a directed error when the RAG is bound.
+   */
+  vectors?: RagVectors;
+}
+/**
+ * Pluggable chunk-text storage. By default chunk text is stored in vector
+ * metadata (`__ragText`), which forces `returnMetadata: "all"` on retrieval and
+ * caps `topK` at 50 (the Vectorize full-metadata ceiling) — and each vector's
+ * metadata must stay under the ~10 KiB Vectorize cap. Supplying a text store
+ * (a DO table, KV, …) moves the text out of metadata: retrieval queries with
+ * `returnMetadata: "indexed"` (topK up to 100) and hydrates text by chunk id.
+ * @experimental
+ */
+interface RagTextStore {
+  /** Fetch chunk texts by id, aligned with the input order; `undefined` for misses. */
+  getMany: (ids: ReadonlyArray<string>, options: {
+    namespace?: string;
+  }) => Promise<ReadonlyArray<string | undefined>>;
+  /** Persist chunk texts. Must be idempotent by chunk `id` (re-index re-puts). */
+  put: (chunks: ReadonlyArray<StoredRagChunk>, options: {
+    namespace?: string;
+  }) => Promise<void>;
+  /** Optional cleanup hook, invoked when a source's chunks are deleted. */
+  remove?: (ids: ReadonlyArray<string>, options: {
+    namespace?: string;
+  }) => Promise<void>;
+}
+/**
+ * A chunk handed to {@link RagTextStore.put} / {@link RagLexicalStore.index}.
+ * @experimental
+ */
+interface StoredRagChunk {
+  chunkIndex: number;
+  id: string;
+  /**
+   * The caller `metadata` attached to this chunk's source at index time
+   * (internal `__rag*` keys excluded).
+   *
+   * Present so a {@link RagLexicalStore} can evaluate the same metadata
+   * filter the vector leg gets. Without it a lexical store has nothing to
+   * filter on and must fail closed on every filtered query — which made
+   * hybrid search and metadata-based RLS mutually exclusive.
+   */
+  metadata?: Record<string, unknown>;
+  sourceId: string;
+  text: string;
+}
+/**
+ * One lexical (BM25) hit returned by {@link RagLexicalStore.search}.
+ * @experimental
+ */
+interface LexicalMatch {
+  /** The chunk vector id — the same id scheme the vector leg uses, so RRF can fuse the two. */
+  id: string;
+  /** BM25 relevance score (higher = better). Used only for the leg's internal ranking; RRF fuses by rank. */
+  score: number;
+  /** The chunk text, returned so a fused lexical-only hit needs no extra hydration round-trip. */
+  text: string;
+}
+/**
+ * Pluggable lexical (BM25 / keyword) store — the production seam for hybrid
+ * retrieval. When {@link RagConfig.lexicalStore} is set, `index()` mirrors each
+ * chunk's text here and `retrieve()` fuses this store's keyword ranking with the
+ * vector store's semantic ranking via Reciprocal Rank Fusion. Mirrors the
+ * {@link RagTextStore} shape (idempotent by chunk `id`, namespace-partitioned).
+ *
+ * `@lunora/ai/rag` ships `bm25LexicalStore()`, an in-memory reference adapter;
+ * production deployments plug a durable one (DO SQLite inverted index, D1,
+ * Vectorize-adjacent search service, …) behind this same interface.
+ * @experimental
+ */
+interface RagLexicalStore {
+  /** Index chunk texts for keyword search. Must be idempotent by chunk `id` (re-index re-puts). */
+  index: (chunks: ReadonlyArray<StoredRagChunk>, options: {
+    namespace?: string;
+  }) => Promise<void>;
+  /** Optional cleanup hook, invoked when a source's chunks are deleted or a re-index shrinks it. */
+  remove?: (ids: ReadonlyArray<string>, options: {
+    namespace?: string;
+  }) => Promise<void>;
+  /**
+   * Rank chunks by lexical relevance to `query`. `filter` carries the same
+   * (RLS-merged) metadata predicate handed to the vector leg — a store that
+   * indexes metadata MUST honour it so hybrid retrieval can't surface a row
+   * the RLS filter would exclude. The shipped `bm25LexicalStore` does — it
+   * evaluates the predicate against each document's stored `metadata`. A store
+   * that indexes no metadata has nothing to filter on and must fail CLOSED on
+   * every filtered query rather than ignore the predicate.
+   */
+  search: (query: string, options: {
+    filter?: Record<string, unknown>;
+    namespace?: string;
+    topK: number;
+  }) => Promise<ReadonlyArray<LexicalMatch>>;
+}
+/**
+ * One graph hit returned by {@link RagGraphStore.related}.
+ * @experimental
+ */
+interface GraphMatch {
+  /** The chunk vector id — the same id scheme the other legs use, so RRF can fuse the three. */
+  id: string;
+  /**
+   * Depth-decaying PROXIMITY, not relevance: `1` for a direct neighbour,
+   * halving per hop — exactly what `ctx.db.related` puts on each node. `hybridRank`
+   * scales this leg's RRF term by it, so a leg of distant hits weighs less than
+   * a leg of direct ones even when the two rank identically among themselves.
+   * Values outside `[0, 1]` are clamped.
+   */
+  score: number;
+  /** The chunk text, returned so a graph-only hit needs no extra hydration round-trip. */
+  text: string;
+}
+/**
+ * Pluggable relation-graph store — the third retrieval signal, alongside the
+ * vector (semantic) and lexical (keyword) legs.
+ *
+ * Keyword and embedding search both answer "which passages look like this
+ * question". Neither can answer "what is this connected to" when the connecting
+ * fact lives in a foreign key rather than in the text — a ticket's customer, a
+ * customer's other tickets, those tickets' messages. `ctx.db.related` walks
+ * exactly that graph, and this is the seam that feeds its result into retrieval.
+ *
+ * Implement it over a Lunora app whose RAG source ids ARE document ids: expand
+ * from the seed ids with `ctx.db.related`, then return the indexed chunks of the
+ * documents it reached, each carrying that node's `score`. Mirrors the
+ * {@link RagLexicalStore} shape (namespace-partitioned, `topK`-bounded).
+ * @experimental
+ */
+interface RagGraphStore {
+  /**
+   * Whether {@link RagGraphStore.related} applies the `filter` it is handed to
+   * every document it returns.
+   *
+   * Required, and asked rather than assumed, because the honest answer is not
+   * derivable: `related` is somebody else's traversal and this package cannot
+   * see whether it narrows. `retrieve()` passes the SAME effective filter to
+   * all three legs — the caller's filter with `RagConfig.rlsFilter` merged
+   * over it — and the vector and lexical stores enforce it. A graph store that
+   * ignored it would return the neighbours of a document the caller may see
+   * even when those neighbours belong to another tenant, which is a leak the
+   * other two legs are specifically built to prevent. So a store that answers
+   * `false` is SKIPPED whenever a filter is in play, rather than trusted:
+   * retrieval loses its third signal and keeps its isolation. With no filter
+   * (no `rlsFilter`, no `RetrieveOptions.filter`) there is nothing to enforce
+   * and `false` costs nothing.
+   *
+   * Answer `true` only if every returned chunk's document really is matched
+   * against the filter — `ctx.db.related` under a schema with RLS policies
+   * does not count on its own, because the filter here is RAG metadata, not a
+   * row policy. The stricter reading is the safe one: if in doubt, `false`.
+   */
+  enforcesFilter: boolean;
+  /**
+   * Expand from the SOURCE document ids the search legs found and return
+   * chunks of the documents they connect to, best (nearest) first.
+   *
+   * Seeded rather than queried: the graph has no notion of a query string, so
+   * it widens a ranking the other legs produced instead of ranking on its own.
+   * A seed id that is not a graph node simply contributes nothing.
+   *
+   * `options.filter` is the effective metadata filter for this retrieval, and
+   * is present only for stores that declared {@link RagGraphStore.enforcesFilter}
+   * — see there for what declaring it commits you to.
+   */
+  related: (sourceIds: ReadonlyArray<string>, options: {
+    filter?: Record<string, unknown>;
+    namespace?: string;
+    topK: number;
+  }) => Promise<ReadonlyArray<GraphMatch>>;
+}
+/**
+ * A pre-defined, reusable filter expression. Declared on `RagConfig.filters`
+ * (keyed by name) and referenced by name from `RetrieveOptions.filter` — avoids
+ * repeating the same tenant/RBAC filter shape across every retrieval site.
+ * @example
+ * ```ts
+ * const docs = defineRag({
+ *   index: "docs",
+ *   filters: {
+ *     published: { filter: { status: "published", deleted: false }, description: "Only published content" },
+ *   },
+ * });
+ * // Later — reference by name:
+ * docs(ctx).retrieve("query", { filter: "published" });
+ * ```
+ * @experimental
+ */
+interface RagNamedFilter {
+  /** Optional human-readable description for observability / Studio display. */
+  description?: string;
+  /** The filter expression passed verbatim to Vectorize's `filter` parameter. */
+  filter: Record<string, unknown>;
+}
+/**
+ * Re-score retrieved candidates against the query. Returns the chunks in their
+ * new order; may drop chunks. See {@link RagConfig.rerank}.
+ * @experimental
+ */
+type RagReranker = (query: string, chunks: ReadonlyArray<RetrievedChunk>) => Promise<ReadonlyArray<RetrievedChunk>> | ReadonlyArray<RetrievedChunk>;
+/**
+ * Rewrite a query, or expand it into several. See {@link RagConfig.transformQuery}.
+ * @experimental
+ */
+type RagQueryTransform = (query: string, info: {
+  conversationId?: string;
+  namespace?: string;
+}) => Promise<ReadonlyArray<string> | string> | ReadonlyArray<string> | string;
+/**
+ * `RagConfig` is part of the experimental `@lunora/ai` API and may change without a major version bump.
+ * @experimental
+ */
+interface RagConfig {
+  /**
+   * Suppress the one-time dev warning emitted when `index`/`retrieve` run
+   * without a `namespace`. Only appropriate for genuinely single-tenant apps —
+   * Vectorize indexes are account-global, so a namespace-less index shares
+   * vectors across every tenant.
+   */
+  allowSharedNamespace?: boolean;
+  /**
+   * Retain up to this many embeddings per bound context, keyed by text, so a
+   * repeated `retrieve()` of the same question does not re-embed it.
+   *
+   * Default 0 (retain nothing beyond one call). Indexing always batches its
+   * embeds regardless of this setting — the batch lives in its own
+   * request-scoped map, released when `index()` returns, so it neither needs
+   * this budget nor evicts what is held in it.
+   *
+   * Sized in entries, not bytes, but budget in bytes: one 1536-dimension
+   * embedding is ~12 KB, so 100 entries is over a megabyte held in the
+   * isolate. Keep it small.
+   */
+  cacheEmbeddings?: number;
+  /**
+   * How many chunks each retrieval leg fetches **before** fusion and
+   * reranking trim the result to `topK`.
+   *
+   * Defaults to `topK * 4` whenever anything downstream reorders — a
+   * `lexicalStore`, a multi-query `transformQuery`, or a `rerank` — and to
+   * plain `topK` otherwise. Bounded by the store ceiling (50 in metadata
+   * mode, 100 with a `textStore`).
+   *
+   * This is the knob that decides how much recall the reordering has to work
+   * with. Fetching only `topK` per leg defeats the point of having two: the
+   * whole reason to run a lexical leg is to surface a chunk the vector leg
+   * ranked *below* `topK`, and it cannot do that if it was never asked for
+   * more than `topK`.
+   */
+  candidates?: number;
+  /** Custom chunker; overrides the built-in fixed-window splitter. */
+  chunk?: (text: string) => ReadonlyArray<string>;
+  /** Overlap (chars) between adjacent chunks. Default 200. Must be < `chunkSize`. */
+  chunkOverlap?: number;
+  /** Target chunk size (chars). Default 1000. */
+  chunkSize?: number;
+  /**
+   * Embedding model, declared once so index + retrieve embed identically: a
+   * Workers AI id (e.g. `@cf/baai/bge-base-en-v1.5`) or any AI SDK
+   * `EmbeddingModel`.
+   *
+   * Omitting it resolves through `ai.embeddingModel(undefined)`, which falls
+   * back to `createAi`'s `defaultEmbeddingModel` — NOT `defaultModel`, which
+   * this said before and which would be a language-model id in an
+   * embedding-model slot. On the generated `ctx.ai` that default comes from
+   * `LUNORA_AI_DEFAULT_EMBEDDING_MODEL` in the Worker env; with neither set,
+   * the first index/retrieve throws.
+   */
+  embeddingModel?: EmbeddingModelInput;
+  /**
+   * Embedding-model version tag — an opt-in discriminator that partitions the
+   * vector space so a model swap can never silently return garbage. Vectors
+   * embedded by one model live in a different space from another's, and
+   * querying across the two returns meaningless neighbours. When set, the tag
+   * is folded into the effective Vectorize namespace (and chunk-id prefix) of
+   * every index/retrieve/remove, so bumping it re-partitions cleanly: old
+   * vectors become unreachable to new queries (empty ≫ wrong) until sources
+   * are re-indexed under the new tag.
+   *
+   * Set + bump this whenever you change {@link RagConfig.embeddingModel} (or
+   * its dimensions). Opt-in and non-breaking — omitting it keeps the exact
+   * chunk-id/namespace scheme of un-versioned indexes. Must match
+   * `^[A-Za-z0-9._-]{1,40}$` (e.g. `"bge-v1.5"`, `"v2"`).
+   */
+  embeddingModelVersion?: string;
+  /**
+   * Pre-defined named filter expressions. Each key is a filter name users
+   * pass through `RetrieveOptions.filter`. Throws at retrieve-time if the
+   * name is not found here — catches spelling mistakes early.
+   */
+  filters?: Record<string, RagNamedFilter>;
+  /**
+   * Pluggable relation-graph store — the third retrieval signal. When set,
+   * `retrieve()` seeds a traversal from the source documents the vector and
+   * lexical legs found and fuses the connected documents' chunks into the same
+   * RRF ranking, weighted by how far away they are. See {@link RagGraphStore}.
+   */
+  graphStore?: RagGraphStore;
+  /** Retrieval depth for the graph leg. Defaults to the effective candidate pool. */
+  graphTopK?: number;
+  /** The Vectorize index name (a `ctx.vectors` index binding key). */
+  index: string;
+  /**
+   * Pluggable lexical (BM25) store for hybrid retrieval. When set, `index()`
+   * mirrors chunk text into it and `retrieve()` fuses the vector (semantic)
+   * and lexical (keyword) rankings via Reciprocal Rank Fusion — recovering the
+   * exact-term / rare-token matches a pure-embedding search misses. Use the
+   * shipped `bm25LexicalStore()` reference adapter or plug your own durable
+   * one. See {@link RagLexicalStore}.
+   */
+  lexicalStore?: RagLexicalStore;
+  /** Retrieval depth for the lexical leg of hybrid search. Defaults to the effective `topK`. */
+  lexicalTopK?: number;
+  /**
+   * Ceiling on the embedding model's dimensionality, checked once per bound
+   * context against the first embedding actually produced. Defaults to
+   * **1536** — Vectorize's per-vector limit at 32-bit precision.
+   *
+   * The default rules out most current large embedding models
+   * (`text-embedding-3-large` and Gemini embedding at 3072,
+   * Qwen3-Embedding at 4096). Without the check they fail at Vectorize with
+   * nothing naming the cause; with it they fail at the first embed, naming
+   * the ceiling and both escapes — truncate via the provider's Matryoshka
+   * `dimensions` option, or set this to `false` when the index is not
+   * Vectorize-backed.
+   *
+   * `false` disables the check entirely: the right setting for a
+   * {@link RagVectors} implementation with a different (or no) ceiling.
+   */
+  maxEmbeddingDimensions?: number | false;
+  /**
+   * Enforce tenant isolation: throw (instead of the one-time dev warning)
+   * when `index`/`retrieve`/`remove` run without a `namespace`. Recommended
+   * for every multi-tenant app — Vectorize indexes are account-global, and
+   * in metadata mode the leaked payload includes raw chunk text.
+   */
+  requireNamespace?: boolean;
+  /**
+   * Re-score the retrieved candidates against the query before they are
+   * trimmed to `topK`. **Injected, not bundled** — a reranker is a model call,
+   * and `@lunora/ai` takes no provider dependency to make one. Adapt yours
+   * with `scoreReranker`/`batchReranker`, or write the two-line hook yourself.
+   *
+   * This is the standard quality step that vector search alone cannot do:
+   * an embedding is computed without the query, so it cannot know which of
+   * two topically-similar passages actually answers *this* question. A
+   * cross-encoder sees both at once and orders them accordingly.
+   *
+   * Retrieval fetches {@link RagConfig.candidates} chunks, hands them
+   * here, and keeps the first `topK` of whatever comes back — so the hook may
+   * reorder and drop, but its output order is final. Runs after hybrid fusion
+   * and before `chunkContext` expansion.
+   */
+  rerank?: RagReranker;
+  /**
+   * Row-level-security filter derived from the retrieval identity. Called once
+   * per `retrieve()` with {@link RagContext.auth} (the bound ctx's `auth`); the
+   * returned Vectorize metadata filter is merged over the caller's `filter`
+   * with **RLS keys winning** (a caller can never widen past what RLS allows),
+   * then applied to both the vector and the lexical legs. Return `undefined` to
+   * add no constraint (e.g. an admin identity). Runs on retrieval only —
+   * indexing is a trusted server path.
+   * @example
+   * ```ts
+   * const docs = defineRag({
+   *   index: "docs",
+   *   // only ever return the caller's own org, whatever else they ask for:
+   *   rlsFilter: (auth) => ({ orgId: (auth as { orgId: string }).orgId }),
+   * });
+   * ```
+   */
+  rlsFilter?: (auth: unknown) => Promise<Record<string, unknown> | undefined> | Record<string, unknown> | undefined;
+  /**
+   * Back this RAG with a different vector store.
+   *
+   * Called once per bound context with that context, so a store needing
+   * per-request state (a Hyperdrive/pgvector connection from `ctx.sql`, a
+   * shard's own SQLite) can build itself from it. Defaults to wrapping
+   * `context.vectors` as a Vectorize-backed store.
+   *
+   * The store declares its own limits, and `defineRag` reads them instead of
+   * assuming Vectorize's — so a pgvector index is not held to a
+   * 1536-dimension ceiling or a 10 KiB metadata budget it does not have.
+   */
+  store?: (context: RagContext) => RagVectorStore;
+  /** Chunk-text storage override — see {@link RagTextStore}. */
+  textStore?: RagTextStore;
+  /** Default retrieval depth. Default 5. Capped by the store: 50 (metadata mode) / 100 (text-store mode) on Vectorize. */
+  topK?: number;
+  /**
+   * Rewrite or expand the query before it is embedded.
+   *
+   * The raw user query is often the worst possible search string: a
+   * conversational follow-up ("what about the other one?") carries its
+   * meaning in the preceding turns, and a short question shares few terms
+   * with the long passage that answers it.
+   *
+   * Return **one** string to rewrite, or **several** to run multi-query
+   * retrieval — each is embedded and searched independently and the rankings
+   * are fused with RRF, which recovers passages any single phrasing would
+   * miss. Returning the query unchanged is a no-op.
+   *
+   * **Injected, not bundled**, for the same reason as {@link RagConfig.rerank}:
+   * every useful strategy (HyDE, multi-query expansion, follow-up rewriting)
+   * needs a language model, and this package does not pick one for you. The
+   * lexical leg searches the first returned query.
+   */
+  transformQuery?: RagQueryTransform;
+}
+/**
+ * `IndexInput` is part of the experimental `@lunora/ai` API and may change without a major version bump.
+ * @experimental
+ */
+interface IndexInput {
+  /**
+   * When `false`, throws if the source text produces zero chunks (e.g. empty
+   * or whitespace-only text). Default `true` (silently produces zero chunks).
+   */
+  allowEmptySources?: boolean;
+  /** Source document id — chunk ids derive from it as `${id}#${chunkIndex}`. */
+  id: string;
+  /**
+   * Relative weight in `[0, 1]` multiplied into this source's match scores at
+   * retrieval time (default 1). Lets canonical docs outrank incidental ones.
+   */
+  importance?: number;
+  /** Source metadata copied onto every chunk vector (e.g. title, url). */
+  metadata?: Record<string, unknown>;
+  /** Tenant/shard key. Required for multi-tenant apps — Vectorize is account-global. */
+  namespace?: string;
+  /**
+   * Called after each chunk is successfully upserted. Useful for progress
+   * tracking during large indexing operations — e.g. updating a UI progress
+   * bar or logging per-chunk status.
+   */
+  onChunk?: (info: {
+    chunkIndex: number;
+    id: string;
+    text: string;
+    total: number;
+  }) => void;
+  /**
+   * Index this source even when its identity hash (`text` + `metadata` +
+   * `importance`) is unchanged.
+   *
+   * The hash short-circuit skips chunking, embedding and every write — which
+   * is what makes a cron re-sync cheap, and also what makes attaching a
+   * `textStore` or `lexicalStore` to an ALREADY-indexed corpus a silent no-op:
+   * the new store is never written, so the keyword leg returns nothing
+   * forever with no error. Set this for the one pass that backfills it.
+   *
+   * It re-embeds, so it is not a setting to leave on.
+   */
+  reindex?: boolean;
+  /** The document body to chunk + embed + upsert. */
+  text: string;
+}
+/**
+ * `IndexResult` is part of the experimental `@lunora/ai` API and may change without a major version bump.
+ * @experimental
+ */
+interface IndexResult {
+  /** Number of chunks the source is indexed into. */
+  chunks: number;
+  /** The deterministic chunk vector ids, in chunk order. */
+  ids: ReadonlyArray<string>;
+  /**
+   * True when the source's identity hash — its `text`, `metadata` and
+   * `importance` together — matched the previously indexed one, so
+   * chunking/embedding/upserts were skipped entirely (a no-op re-sync).
+   * Changing `metadata` alone (a tenant move, an ACL correction) therefore
+   * re-indexes: the old values are what `rlsFilter` scopes retrieval on.
+   */
+  unchanged: boolean;
+}
+/**
+ * `RemoveInput` is part of the experimental `@lunora/ai` API and may change without a major version bump.
+ * @experimental
+ */
+interface RemoveInput {
+  /** The source document id whose chunks are removed. */
+  id: string;
+  namespace?: string;
+}
+/**
+ * `RetrieveOptions` is part of the experimental `@lunora/ai` API and may change without a major version bump.
+ * @experimental
+ */
+interface RetrieveOptions {
+  /**
+   * Also return this many neighbouring chunks around each match (fetched by
+   * deterministic id, not re-queried) — "embed small, retrieve big". Neighbour
+   * text is stitched into the chunk's `text` in document order. Best combined
+   * with `chunkOverlap: 0`, since overlapping windows repeat boundary text.
+   */
+  chunkContext?: {
+    after?: number;
+    before?: number;
+  };
+  /**
+   * Vectorize filter expression — or the name of a pre-defined filter declared
+   * in `RagConfig.filters`. Passing a name that is not registered throws at
+   * call time, catching spelling mistakes early.
+   */
+  filter?: Record<string, unknown> | string;
+  /**
+   * Drop matches whose (importance-adjusted) score falls below this threshold.
+   *
+   * Applied to the VECTOR leg, where the score is still the cosine scale this
+   * option is documented against — every fusion below replaces `score` with an
+   * RRF score, and thresholding that against a cosine number keeps or drops
+   * chunks essentially at random. A chunk the vector leg rejected here stays
+   * rejected even if the lexical leg also ranks it; a lexical-only hit the
+   * vector leg never scored is NOT gated, since its BM25 score is not on this
+   * scale (see `hybridRank`).
+   */
+  minScore?: number;
+  namespace?: string;
+  /**
+   * Fires after retrieval completes, before chunk expansion. Useful for
+   * observability — logging query latency, hit counts, etc.
+   */
+  onRetrieve?: (info: {
+    matches: number;
+    query: string;
+  }) => void;
+  /**
+   * Set `false` to skip {@link RagConfig.rerank} for this call — the escape
+   * hatch for a latency-sensitive path (typeahead, an agent's inner loop)
+   * that cannot afford the extra model round-trip.
+   */
+  rerank?: false;
+  topK?: number;
+  /** Set `false` to skip {@link RagConfig.transformQuery} for this call. */
+  transformQuery?: false;
+}
+/**
+ * `RetrievedChunk` is part of the experimental `@lunora/ai` API and may change without a major version bump.
+ * @experimental
+ */
+interface RetrievedChunk {
+  chunkIndex: number;
+  id: string;
+  /**
+   * The source-level importance weight that was multiplied into this chunk's
+   * score. `1` when no importance was set at index time.
+   */
+  importance: number;
+  /** Caller metadata stored on the vector (internal `__rag*` keys stripped). */
+  metadata?: Record<string, unknown>;
+  /** Cosine similarity, multiplied by the source's `importance` when one was set. */
+  score: number;
+  sourceId: string;
+  text: string;
+}
+/**
+ * `RagSource` is part of the experimental `@lunora/ai` API and may change without a major version bump.
+ * @experimental
+ */
+interface RagSource {
+  id: string;
+  /** Caller metadata from the source's first-seen chunk (internal keys stripped). */
+  metadata?: Record<string, unknown>;
+  /**
+   * The source's importance weight (the `importance` value passed at index
+   * time, default 1), propagated so downstream consumers can factor it into
+   * their own ranking or UI.
+   */
+  weight?: number;
+}
+/**
+ * The retrieve return shape — designed so an agent memory step consumes it directly.
+ * @experimental
+ */
+interface RetrieveResult {
+  /** Ranked chunks (best first). */
+  chunks: ReadonlyArray<RetrievedChunk>;
+  /** Ready-to-inject prompt context: chunks joined under `[source:<id>#<n>]` headers. */
+  context: string;
+  /** Deduped source references, in first-seen (best) order. */
+  sources: ReadonlyArray<RagSource>;
+}
+/**
+ * `RagToolOptions` is part of the experimental `@lunora/ai` API and may change without a major version bump.
+ * @experimental
+ */
+interface RagToolOptions {
+  /** Tool description shown to the model. Defaults to a search description naming the index. */
+  description?: string;
+  /** Namespace applied to every tool-invoked retrieval (the tenant key). */
+  namespace?: string;
+  /** Retrieval depth for tool-invoked retrievals. */
+  topK?: number;
+}
+/**
+ * The per-request RAG surface returned by binding a ctx: `docs(ctx)`.
+ * @experimental
+ */
+interface Rag {
+  /**
+   * Expose `retrieve` as an AI SDK tool (for `generateText`/`streamText`
+   * `tools:` maps), so a model can decide to search the index itself.
+   */
+  asTool: (options?: RagToolOptions) => Tool<{
+    query: string;
+  }, RetrieveResult>;
+  /**
+   * Chunk + embed + upsert one source document. Re-indexing the same `id` is
+   * an atomic-enough replace: unchanged content short-circuits via content
+   * hash, and stale chunks beyond the new count are deleted automatically.
+   */
+  index: (input: IndexInput) => Promise<IndexResult>;
+  /** Delete every chunk of a previously indexed source. */
+  remove: (input: RemoveInput) => Promise<void>;
+  /** Embed the query and return ranked chunks + prompt-ready context. */
+  retrieve: (query: string, options?: RetrieveOptions) => Promise<RetrieveResult>;
+}
+declare const defineRag: (config: RagConfig) => ((context: RagContext) => Rag);
+/**
+ * Guess a MIME type from a file extension. Lowercases and strips a leading `.`
+ * from `extension`; returns `"application/octet-stream"` for unknown extensions.
+ *
+ * Covers the broad set of extensions users are likely to encounter in a web /
+ * document-processing context — images, video, audio, office docs, PDF, text,
+ * archives, and source code. Follows the same approach as Convex's
+ * `guessMimeType` helper.
+ * @experimental
+ */
+declare const guessMimeTypeFromExtension: (extension: string) => string;
+/**
+ * SHA-256 hex digest of binary data. Accepts a `BufferSource` (`ArrayBuffer` or
+ * `ArrayBufferView` such as `Uint8Array`). Useful for content-addressable
+ * storage — pair with `IndexInput.text` to detect duplicates across re-indexes.
+ * @experimental
+ */
+declare const contentHash: (data: BufferSource) => Promise<string>;
+/**
+ * How a leg's reciprocal-rank term is weighted before it is summed.
+ *
+ * `"rank"` is plain RRF: position in the leg is the only signal, which is the
+ * point — cosine, BM25 and graph-proximity scores are not comparable.
+ *
+ * `"proximity"` additionally scales the term by the chunk's own `score`, clamped
+ * into `[0, 1]`. It exists for the graph leg, where `score` is the depth decay
+ * `ctx.db.related` assigned (1, 0.5, 0.25 …) rather than a relevance score: a
+ * depth-2 neighbour should add half of what a depth-1 one does even where the
+ * two are adjacent in the leg's own ranking. Rank alone cannot express that — a
+ * leg of nothing but depth-3 hits would otherwise contribute exactly as much as
+ * a leg of direct neighbours, which is the whole distinction a proximity signal
+ * exists to carry.
+ */
+type FusionWeight = "proximity" | "rank";
+/** One ranked list feeding the fusion, and the rule its contribution follows. */
+interface FusionLeg {
+  /** The leg's chunks, best first. */
+  chunks: ReadonlyArray<RetrievedChunk>;
+  /** Defaults to `"rank"`. See {@link FusionWeight}. */
+  weight?: FusionWeight;
+}
+interface HybridRankOptions {
+  /** RRF damping constant; higher flattens rank differences. Defaults to 60. */
+  k?: number;
+}
+/**
+ * Reciprocal Rank Fusion (RRF): merge ranked lists of chunks by their _rank
+ * position_ rather than their absolute scores, which are not comparable across
+ * different search methods (cosine vs BM25 vs graph proximity).
+ *
+ * Each leg contributes `1 / (k + rank)` to each chunk's fused score, where
+ * `rank` is 0-based position within that leg. The constant `k` (default 60)
+ * dampens the influence of high ranks. A leg declared `weight: "proximity"`
+ * scales its term by the chunk's own score — see {@link FusionWeight}.
+ *
+ * Legs are a LIST rather than one parameter per search method: what a leg needs
+ * to declare is its scoring rule, not its position, and a positional graph slot
+ * forced callers with no lexical leg to write `hybridRank(vector, [], graph)`.
+ *
+ * **The returned chunks carry the fused score in `score`**, multiplied by the
+ * chunk's `importance` so source weighting still applies. Writing it back is
+ * what makes the fusion survive: a caller that re-sorts by `score` — as
+ * `retrieve()` does, to apply importance weighting — would otherwise re-order
+ * by the incomparable inputs and discard the ranking this function computed.
+ * Since BM25 is unbounded while cosine is `[0, 1]`, that silently promoted
+ * every lexical-only hit above every vector hit.
+ *
+ * Importance is applied ONCE, by this call. A caller with several signals passes
+ * them as several legs to ONE call, never one call per leg: the returned list is
+ * both weighted and sorted by that weighting, so handing it back in as a leg
+ * makes the next pass derive its ranks from an already-weighted ordering and
+ * weight it a second time.
+ *
+ * So in hybrid mode `RetrievedChunk.score` is an RRF score (small, ~`1/60`
+ * scale), not a cosine similarity. `retrieve()` applies `minScore` to the
+ * vector leg *before* fusion for exactly this reason — the option is documented
+ * against the cosine scale.
+ *
+ * Ties are broken by preferring the chunk ranked higher in the FIRST leg,
+ * conventionally the vector one and typically the more semantically accurate.
+ *
+ * Callers MUST ensure every chunk across every leg carries a unique, comparable
+ * `id` — guaranteed by the chunk-id scheme `${sourceId}#${chunkIndex}`.
+ * @experimental
+ */
+declare const hybridRank: (legs: ReadonlyArray<FusionLeg>, options?: HybridRankOptions) => ReadonlyArray<RetrievedChunk>;
+/**
+ * An **in-memory** Okapi BM25 lexical store — the reference adapter behind
+ * `RagConfig.lexicalStore`, giving hybrid retrieval its keyword leg with zero
+ * infrastructure. State lives in the worker isolate: it is **not durable and not
+ * shared across isolates**, so it is intended for tests, local development, and
+ * single-isolate workloads. Production deployments plug a durable
+ * {@link RagLexicalStore} (a DO-SQLite inverted index, D1, or an external search
+ * service) behind the same seam.
+ *
+ * Tenant isolation is by `namespace` (each namespace keeps its own index), and
+ * each chunk's source `metadata` is stored alongside it so `search` evaluates
+ * the **same** metadata predicate the vector leg receives — including an
+ * `rlsFilter` result. A hit the filter excludes never reaches fusion.
+ *
+ * That matters because the filter carries the tenant/RBAC scope: a lexical leg
+ * that ignored it would leak excluded chunk text into the fused result no
+ * matter what the vector leg returned. This store previously had no metadata to
+ * check and so refused every filtered query, which made hybrid search and
+ * metadata-based RLS mutually exclusive.
+ * @experimental
+ */
+declare const bm25LexicalStore: () => RagLexicalStore;
+/**
+ * True when `metadata` satisfies every clause of `filter`. An empty or absent
+ * filter matches everything; absent metadata satisfies only an empty filter.
+ *
+ * Clauses are ANDed, matching Vectorize.
+ */
+declare const matchesMetadataFilter: (metadata: Record<string, unknown> | undefined, filter: Record<string, unknown> | undefined) => boolean;
+/** Options for {@link scoreReranker}. */
+interface ScoreRerankerOptions {
+  /**
+   * Drop chunks scoring below this threshold, in the scorer's own scale.
+   * Omitted → nothing is dropped and the reranker only reorders.
+   *
+   * Worth setting: reranking's real value is not just promoting the best
+   * passage but *rejecting* the ones vector search only matched topically,
+   * and a chunk that survives to the prompt is a chunk the model may cite.
+   */
+  minScore?: number;
+  /**
+   * Score one `(query, passage)` pair for relevance. Higher is better; the
+   * scale does not matter, only the ordering it induces.
+   *
+   * Called once per candidate chunk. Wrap a Workers AI reranker
+   * (`ctx.ai.run("@cf/baai/bge-reranker-base", …)`), a Cohere/Voyage rerank
+   * endpoint, or an LLM prompted to rate relevance.
+   */
+  score: (query: string, text: string) => Promise<number> | number;
+}
+/**
+ * Batched variant — score every candidate in one call.
+ */
+interface BatchRerankerOptions {
+  /** Drop chunks scoring below this threshold. See {@link ScoreRerankerOptions.minScore}. */
+  minScore?: number;
+  /**
+   * Score all candidates at once, returning one number per passage **in the
+   * same order**. Prefer this over {@link ScoreRerankerOptions.score} when the
+   * provider has a batch endpoint: cross-encoder APIs are priced and rate
+   * limited per request, so N passages in one call beats N calls.
+   *
+   * A result whose length does not match the input is rejected rather than
+   * zipped against the wrong passages.
+   */
+  scoreAll: (query: string, texts: ReadonlyArray<string>) => Promise<ReadonlyArray<number>> | ReadonlyArray<number>;
+}
+/**
+ * Adapt a per-passage relevance scorer into a {@link RagReranker}.
+ *
+ * The scorer is **injected** — `@lunora/ai` takes no provider dependency to
+ * make a model call. Scoring runs with bounded concurrency so a 50-candidate
+ * pool does not fan out 50 simultaneous subrequests.
+ *
+ * ```ts
+ * defineRag({
+ *   index: "docs",
+ *   rerank: scoreReranker({
+ *     score: async (query, text) => {
+ *       const result = await ctx.ai.run("@cf/baai/bge-reranker-base", { query, contexts: [{ text }] });
+ *       return result.response[0].score;
+ *     },
+ *   }),
+ * });
+ * ```
+ * @experimental
+ */
+declare const scoreReranker: (options: ScoreRerankerOptions) => RagReranker;
+/**
+ * Adapt a **batch** relevance scorer into a {@link RagReranker} — one call for
+ * the whole candidate pool. See {@link BatchRerankerOptions.scoreAll}.
+ * @experimental
+ */
+declare const batchReranker: (options: BatchRerankerOptions) => RagReranker;
+/** One object listed by a {@link RagObjectSource}. */
+interface RagSourceObject {
+  /** Content type, when the source knows it. Falls back to the key's extension. */
+  contentType?: string;
+  /** Stable key — becomes the indexed source id. */
+  key: string;
+  /** Metadata attached to every chunk of this object. */
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Where documents come from. Two operations, both injected.
+ *
+ * `list` is an async iterable rather than an array so the caller decides how to
+ * page a large bucket rather than being forced to build one array up front.
+ * `sync` still collects the KEYS it yields — it needs the full current key set
+ * to work out what disappeared — but never more than one object's BODY at a
+ * time, which is where the memory actually is.
+ */
+interface RagObjectSource {
+  /** Fetch one object's raw text. Return `undefined` to skip it (unreadable, unsupported). */
+  get: (object: RagSourceObject) => Promise<string | undefined> | string | undefined;
+  /** Enumerate the objects to index. */
+  list: () => AsyncIterable<RagSourceObject> | Iterable<RagSourceObject>;
+}
+/** Turn a fetched object's raw text into indexable plain text. */
+type RagExtractor = (raw: string, object: RagSourceObject) => Promise<string | undefined> | string | undefined;
+/** Options for {@link defineRagSource}. */
+interface RagSourceOptions {
+  /**
+   * How many objects to process at once. Default 4.
+   *
+   * Each one is a fetch plus an embed plus an upsert, so this multiplies into
+   * the subrequest budget — the default is deliberately low.
+   */
+  concurrency?: number;
+  /**
+   * Extractors keyed by content type (`text/html`, `application/pdf`, …), or
+   * `"*"` as a fallback. A content type with no extractor and no `"*"` entry
+   * is skipped and counted in `skipped` — never indexed as raw bytes, which
+   * would fill the index with markup or binary noise that embeds to nothing
+   * meaningful.
+   */
+  extractors?: Record<string, RagExtractor>;
+  /** Namespace (tenant/shard key) applied to every indexed object. */
+  namespace?: string;
+  /** Called after each object is handled — for progress reporting. */
+  onObject?: (info: {
+    chunks: number;
+    key: string;
+    status: "indexed" | "skipped" | "unchanged";
+  }) => void;
+}
+/** Per-pass options for {@link RagSourceSync.sync}. */
+interface RagSyncPassOptions {
+  /**
+   * The keys this index is believed to already hold. Any of them missing from
+   * this pass's `list()` is deleted from the index.
+   *
+   * Pruning is what makes the index a mirror rather than an append-only pile:
+   * a document removed at the source but left in the index keeps being
+   * retrieved and cited, which is worse than never having indexed it.
+   *
+   * It is the CALLER's set, and required, because nothing else can hold it
+   * honestly. A previous pass's keys remembered in the instance would be
+   * empty on the shape this helper is documented in — built per request, from
+   * a per-request `rag(ctx)` — so a prune that defaulted on would in practice
+   * never run and never say so. Persist the set (a table, a KV key, the
+   * bucket listing itself) and hand it in.
+   *
+   * Omitted ⇒ nothing is pruned, and `pruned` comes back empty.
+   */
+  knownKeys?: Iterable<string>;
+}
+/** What one {@link RagSourceSync.sync} pass did. */
+interface RagSyncReport {
+  /** Keys indexed for the first time or re-indexed after a change. */
+  indexed: string[];
+  /** Keys deleted from the index because they no longer exist at the source. Empty unless `knownKeys` was supplied. */
+  pruned: string[];
+  /** Keys skipped — no extractor, or the source returned nothing. */
+  skipped: string[];
+  /** Keys whose content hash matched, so nothing was embedded. */
+  unchanged: string[];
+}
+/** The bound ingestion surface. */
+interface RagSourceSync {
+  /** Run one full pass over the source. */
+  sync: (source: RagObjectSource, passOptions?: RagSyncPassOptions) => Promise<RagSyncReport>;
+}
+/**
+ * Declare a bulk-ingestion pass over a {@link Rag}.
+ *
+ * ```ts
+ * const ingest = defineRagSource(docs(ctx), { namespace: ctx.shardKey });
+ *
+ * const report = await ingest.sync(
+ *     {
+ *         list: async function* () {
+ *             for await (const object of bucket.list()) {
+ *                 yield { key: object.key, metadata: { url: object.key } };
+ *             }
+ *         },
+ *         get: async (object) => (await bucket.get(object.key))?.text(),
+ *     },
+ *     // Pass what you already indexed to have deletions mirrored; omit it and
+ *     // nothing is pruned.
+ *     { knownKeys: await ctx.db.query("indexedDocs").collect().then((rows) => rows.map((row) => row.key)) },
+ * );
+ * ```
+ * @experimental
+ */
+declare const defineRagSource: (rag: Rag, options?: RagSourceOptions) => RagSourceSync;
+/**
+ * Run one statement and return its rows.
+ *
+ * Rows come back as plain objects keyed by column name — the shape
+ * `SqlStorage#exec().toArray()`, D1's `.all().results`, and `postgres.js` all
+ * already produce. A statement returning nothing yields an empty array.
+ *
+ * May be synchronous: a Durable Object's SQLite is, and forcing it through a
+ * promise would add a microtask per row batch for nothing.
+ */
+type RagSqlExec = (sql: string, parameters: ReadonlyArray<unknown>) => Promise<ReadonlyArray<Record<string, unknown>>> | ReadonlyArray<Record<string, unknown>>;
+/** Options for {@link sqlLexicalStore}. */
+interface SqlLexicalStoreOptions {
+  /** Execute one statement. See {@link RagSqlExec}. */
+  exec: RagSqlExec;
+  /**
+   * Table-name prefix. Default `lunora_rag_lexical`; the postings table is
+   * this plus `_terms`. Must be a bare SQL identifier.
+   */
+  table?: string;
+}
+declare const sqlLexicalStore: (options: SqlLexicalStoreOptions) => RagLexicalStore;
+/** Options for {@link sqliteVectorStore}. */
+interface SqliteVectorStoreOptions {
+  /**
+   * Keep a `sqlite-vec` `vec0` index (cosine distance) in `<table>_ann`, one
+   * partition per namespace. Requires the extension in the executor's SQLite;
+   * without it the first operation throws naming the missing module.
+   *
+   * The JSON table stays the source of truth: an index created over an
+   * existing table is backfilled from it, and a match the table no longer
+   * holds is dropped. Only an **unfiltered** query uses the index — `vec0`
+   * applies a metadata filter after picking the `k` nearest, which would
+   * return a short page, so a filtered query keeps the exact scan (and its
+   * `maxScan` bound).
+   */
+  ann?: {
+    dimensions: number;
+  };
+  /** Execute one statement. See {@link RagSqlExec}. */
+  exec: RagSqlExec;
+  /**
+   * Ceiling on embedding dimensionality. Defaults to `false` (no limit) —
+   * vectors are stored as JSON, so nothing here cares how wide they are, and
+   * inheriting Vectorize's 1536 would be inventing a constraint.
+   */
+  maxDimensions?: number | false;
+  /**
+   * Upper bound on how many rows a single namespace may be scanned for.
+   * Default 50,000.
+   *
+   * Search is linear, so this is the difference between a slow query and a
+   * Worker that exceeds its CPU budget and is killed with nothing explaining
+   * why. Exceeding it throws, naming the namespace and the count.
+   */
+  maxScan?: number;
+  /** Table name. Default `lunora_rag_vectors`. Must be a bare SQL identifier. */
+  table?: string;
+}
+declare const sqliteVectorStore: (options: SqliteVectorStoreOptions) => RagVectorStore;
+/**
+ * A dispatchable function reference — the `internal.docs.reindex` you pass as
+ * `action`. Typed structurally (rather than `unknown`) so passing the wrong
+ * thing is a compile error: mis-wiring the action is the mistake this API is
+ * most likely to see, and it would otherwise surface as a silent no-op.
+ */
+interface RagSyncActionReference {
+  readonly __lunoraRef: string;
+}
+/** Structural slice of `ctx.scheduler` — enough to defer the re-index. */
+interface RagSyncScheduler {
+  runAfter: (delayMs: number, target: unknown, args?: Record<string, unknown>) => Promise<string>;
+}
+/** Structural slice of the `TriggerCtx` a `.triggers()` handler receives. */
+interface RagSyncTriggerContext {
+  readonly scheduler: RagSyncScheduler;
+}
+/** The trigger events this helper handles, narrowed to what it reads. */
+interface RagSyncEvent {
+  readonly doc?: Record<string, unknown>;
+  readonly id: string;
+  readonly previous?: Record<string, unknown>;
+}
+/** What the scheduled action receives — one document to re-index, or one to drop. */
+interface RagSyncArgs extends Record<string, unknown> {
+  /** `true` when the source's chunks must go: call `rag.remove({ id, namespace })`. */
+  deleted?: boolean;
+  /** The source id — the same `id` you pass to `rag.index`/`rag.remove`. */
+  id: string;
+  /** The {@link RagSyncOptions.metadata} projection, to pass to `rag.index`. Absent on a delete or when there is none. */
+  metadata?: Record<string, unknown>;
+  /** The {@link RagSyncOptions.namespace} projection, to pass to `rag.index`/`rag.remove`. Absent when there is none. */
+  namespace?: string;
+  /** The text to embed. Absent on a delete. */
+  text?: string;
+}
+interface RagSyncOptions<Document extends Record<string, unknown> = Record<string, unknown>> {
+  /**
+   * The internal action to dispatch — it receives {@link RagSyncArgs} and calls
+   * `rag.index` / `rag.remove`. An action, not a mutation: embedding is network
+   * I/O and never runs in the deterministic write path.
+   */
+  action: RagSyncActionReference;
+  /**
+   * How long to wait before re-indexing. A small delay coalesces nothing by
+   * itself, but it keeps the embed off the write's own tail latency. Default
+   * `0` — as soon as the mutation commits.
+   */
+  delayMs?: number;
+  /** The source id to index under. Defaults to the row's own id. */
+  id?: (document: Document) => string;
+  /**
+   * Metadata copied onto every chunk (`rag.index({ metadata })`) — the fields a
+   * `rlsFilter` or `metadataFilter` scopes retrieval by, such as a tenant or
+   * owner id. Compared on update like the text: a row that moves tenant with
+   * unchanged text is re-indexed, so the old tenant stops retrieving it.
+   */
+  metadata?: (document: Document) => Record<string, unknown> | undefined;
+  /**
+   * The Vectorize namespace to index under (`rag.index({ namespace })`), e.g.
+   * the tenant key. When it changes on update, the chunks in the old namespace
+   * are removed before the row is indexed into the new one.
+   */
+  namespace?: (document: Document) => string | undefined;
+  /** The text to embed. Return `undefined` to skip the row (a draft, an empty body). */
+  text: (document: Document) => string | undefined;
+}
+/** One trigger definition, structurally — matches what `.triggers((t) => …)` returns. */
+type RagSyncHandler = (context: RagSyncTriggerContext, event: RagSyncEvent) => Promise<void>;
+/**
+ * Build the three write-path handlers that keep a RAG index in step with a
+ * table. Wire them into the table's `.triggers()`:
+ *
+ * ```ts
+ * const sync = ragSyncTriggers({ action: internal.docs.reindex, text: (doc) => doc.body });
+ *
+ * export const schema = defineSchema({
+ *     docs: defineTable({ body: v.string(), title: v.string() }).triggers((t) => ({
+ *         ragDelete: t.afterDelete(sync.afterDelete),
+ *         ragInsert: t.afterInsert(sync.afterInsert),
+ *         ragUpdate: t.afterUpdate(sync.afterUpdate),
+ *     })),
+ * });
+ * ```
+ *
+ * The action on the other end forwards every field it receives:
+ *
+ * ```ts
+ * export const reindex = internalAction
+ *     .input({
+ *         deleted: v.optional(v.boolean()),
+ *         id: v.string(),
+ *         metadata: v.optional(v.record(v.string(), v.any())),
+ *         namespace: v.optional(v.string()),
+ *         text: v.optional(v.string()),
+ *     })
+ *     .action(async ({ args, ctx }) => {
+ *         const rag = docsRag(ctx);
+ *         const { id, metadata, namespace, text } = args;
+ *
+ *         await (args.deleted === true || text === undefined ? rag.remove({ id, namespace }) : rag.index({ id, metadata, namespace, text }));
+ *     });
+ * ```
+ *
+ * A multi-tenant table also passes `metadata` and/or `namespace` (for example
+ * `metadata: (doc) => ({ orgId: doc.orgId })`). Without them, a row that moves
+ * tenant keeps its old scope in the index and stays retrievable by the tenant it
+ * left. An action that drops `namespace` removes from (or indexes into) the
+ * wrong namespace, and one whose `input` omits `metadata` / `namespace` rejects
+ * the scheduled args and fails every job.
+ *
+ * Re-scoping is not atomic: the triggers only SCHEDULE the work, so after a row
+ * changes namespace its chunks stay retrievable in the old one until the
+ * scheduled delete runs (and until the re-index runs, it is missing from the new
+ * one). The same holds for a metadata change. Lower `delayMs` shortens that
+ * window; it does not close it.
+ */
+declare const ragSyncTriggers: <Document extends Record<string, unknown> = Record<string, unknown>>(options: RagSyncOptions<Document>) => {
+  afterDelete: RagSyncHandler;
+  afterInsert: RagSyncHandler;
+  afterUpdate: RagSyncHandler;
+};
+export { type BatchRerankerOptions, type ChunkerOptions, type FusionLeg, type FusionWeight, type GraphMatch, type HybridRankOptions, type IndexInput, type IndexResult, type LexicalMatch, type Rag, type RagConfig, type RagContext, type RagEmbedder, type RagExtractor, type RagGraphStore, type RagLexicalStore, type RagNamedFilter, type RagObjectSource, type RagQueryTransform, type RagReranker, type RagSource, type RagSourceObject, type RagSourceOptions, type RagSourceSync, type RagSqlExec, type RagSyncActionReference, type RagSyncArgs, type RagSyncOptions, type RagSyncPassOptions, type RagSyncReport, type RagTextStore, type RagToolOptions, type RagVectorMatch, type RagVectorMatches, type RagVectorQueryInput, type RagVectorRecord, type RagVectorStore, type RagVectorStoreCapabilities, type RagVectorUpsertInput, type RagVectors, type RemoveInput, type RetrieveOptions, type RetrieveResult, type RetrievedChunk, type ScoreRerankerOptions, type SqlLexicalStoreOptions, type SqliteVectorStoreOptions, type StoredRagChunk, type TokenChunkerOptions, VECTORIZE_CAPABILITIES, batchReranker, bm25LexicalStore, contentHash, defineRag, defineRagSource, fixedWindowChunks, guessMimeTypeFromExtension, hybridRank, markdownChunker, matchesMetadataFilter, ragSyncTriggers, scoreReranker, sentenceChunker, sqlLexicalStore, sqliteVectorStore, tokenChunker, vectorizeStore };