@lunora/bindings 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/vectors/index.d.mts

@@ -1,67 +1,17 @@
+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';
 /**
-* 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;
-}
-/**
-* 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.
-* The runtime calls this at upsert time so we don't couple to any provider.
-*/
+ * 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.
+ * The runtime calls this at upsert time so we don't couple to any provider.
+ */
 type EmbedFunction<TInput = unknown> = (input: TInput) => Promise<ReadonlyArray<number>> | ReadonlyArray<number>;
 interface LunoraVectorsOptions {
   /**
-  * Map of logical index name -> Vectorize binding. Most apps wire one
-  * binding per index; multi-index apps register all of them here so calls
-  * like `vectors.query("docs-body", ...)` can resolve to the right binding.
-  */
+   * Map of logical index name -> Vectorize binding. Most apps wire one
+   * binding per index; multi-index apps register all of them here so calls
+   * like `vectors.query("docs-body", ...)` can resolve to the right binding.
+   */
   indexes: Record<string, VectorizeIndexLike>;
 }
 interface UpsertInput<TInput = unknown> {
@@ -91,9 +41,9 @@ interface LunoraVectors {
   upsertMany: <TInput>(indexName: string, inputs: ReadonlyArray<UpsertInput<TInput>>) => Promise<VectorizeUpsertMutation>;
 }
 /**
-* `(input: string) => vector`. Matches `@lunora/server`'s `VectorEmbedder` so
-* the bridged surface is assignable to the server's `VectorSearch` contract.
-*/
+ * `(input: string) => vector`. Matches `@lunora/server`'s `VectorEmbedder` so
+ * the bridged surface is assignable to the server's `VectorSearch` contract.
+ */
 type VectorEmbedderLike = (input: string) => Promise<ReadonlyArray<number>> | ReadonlyArray<number>;
 interface VectorMatchLike {
   id: string;
@@ -107,6 +57,7 @@ interface VectorMatchesLike {
 interface VectorRecordLike {
   id: string;
   metadata?: Record<string, unknown>;
+  namespace?: string;
   values: ReadonlyArray<number>;
 }
 interface VectorQueryInputLike {
@@ -115,11 +66,11 @@ interface VectorQueryInputLike {
   input?: string;
   namespace?: string;
   /**
-  * How much stored metadata to return on matches. Defaults to `"indexed"`
-  * (only fields declared as index metadata) rather than `"all"`, so a query
-  * never leaks arbitrary stored fields by default. Callers that genuinely
-  * need every field opt in with `"all"`; pass `"none"` to drop metadata.
-  */
+   * How much stored metadata to return on matches. Defaults to `"indexed"`
+   * (only fields declared as index metadata) rather than `"all"`, so a query
+   * never leaks arbitrary stored fields by default. Callers that genuinely
+   * need every field opt in with `"all"`; pass `"none"` to drop metadata.
+   */
   returnMetadata?: "none" | "indexed" | "all";
   topK?: number;
   vector?: ReadonlyArray<number>;
@@ -132,24 +83,107 @@ interface VectorUpsertInputLike {
   namespace?: string;
 }
 /**
-* 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).
-*/
+ * 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). `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 {
+  /**
+   * 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.
-*/
-declare const createContextVectors: (lunora: LunoraVectors) => VectorSearchLike;
+ * 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.
+ *
+ * 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, options?: CreateContextVectorsOptions) => VectorSearchLike;
 /** A single row mutation observed by the ctx-db, fed to {@link createVectorSyncHook}. */
 interface WriteEvent {
   doc?: Record<string, unknown>;
@@ -176,43 +210,60 @@ interface VectorIndexDefinitionLike {
   table: string;
 }
 /**
-* Structural mirror of `@lunora/server`'s `Schema`, narrowed to the fields the
-* sync hook reads. Carries live `embed`/`select` closures, so the hook must be
-* built from the imported `schema` value — never a serialized descriptor.
-*/
+ * Structural mirror of `@lunora/server`'s `Schema`, narrowed to the fields the
+ * sync hook reads. Carries live `embed`/`select` closures, so the hook must be
+ * built from the imported `schema` value — never a serialized descriptor.
+ */
 interface SchemaLike {
   tables: Record<string, TableDefinitionLike>;
   vectorIndexes: Record<string, VectorIndexDefinitionLike>;
 }
 /**
-* 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.
-*
-* Tenant isolation — IMPORTANT: Vectorize indexes are account-global and shared
-* by every shard DO. Without a `namespace`, a multi-tenant sharded app has NO
-* isolation between tenants in the vector index — one tenant's vectors are
-* queryable by another (ids/scores leak existence + semantic similarity even
-* when no metadata is indexed). The caller MUST pass `options.namespace` (the
-* shard / tenant key) so upserts are scoped, and MUST apply the same namespace
-* on the query side — query-side namespace filtering is mandatory, not optional.
-* The namespace is threaded onto upserts here; pass it from the shard DO that
-* owns this hook. Any namespace-less sync emits a one-time-per-index dev warning
-* (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.
-*/
+ * 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.
+ *
+ * Tenant isolation — IMPORTANT: Vectorize indexes are account-global and shared
+ * by every shard DO. Without a `namespace`, a multi-tenant sharded app has NO
+ * isolation between tenants in the vector index — one tenant's vectors are
+ * queryable by another (ids/scores leak existence + semantic similarity even
+ * when no metadata is indexed). The caller MUST pass `options.namespace` (the
+ * shard / tenant key) so upserts are scoped, and MUST apply the same namespace
+ * on the query side — query-side namespace filtering is mandatory, not optional.
+ * The namespace is threaded onto upserts here; pass it from the shard DO that
+ * owns this hook. Any namespace-less sync emits a one-time-per-index dev warning
+ * (regardless of whether metadata is present); a genuinely single-tenant app
+ * suppresses it with `allowSharedNamespace: true`.
+ *
+ * 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, on a cleared inline field, and on compensation after a failed
+ * upsert) 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: 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.
+ */
 declare const createVectorSyncHook: (options: {
   allowSharedNamespace?: boolean;
   namespace?: string;
@@ -220,11 +271,11 @@ declare const createVectorSyncHook: (options: {
   vectors: VectorSearchLike;
 }) => WriteHook;
 /**
-* One vector index as the generated `LUNORA_VECTOR_INDEXES` registry describes
-* it — the static schema shape, independent of any live binding. Structurally
-* the codegen `LunoraVectorIndex`, restated here so this package stays free of a
-* dependency on `@lunora/codegen`.
-*/
+ * One vector index as the generated `LUNORA_VECTOR_INDEXES` registry describes
+ * it — the static schema shape, independent of any live binding. Structurally
+ * the codegen `LunoraVectorIndex`, restated here so this package stays free of a
+ * dependency on `@lunora/codegen`.
+ */
 interface VectorIndexRegistryEntry {
   dimensions?: number;
   field?: string;
@@ -245,9 +296,9 @@ interface VectorAdminQueryMatch {
   score: number;
 }
 /**
-* The admin introspector the worker passes to `createWorker({ vectorIntrospector })`.
-* `queryIndex` is present only when at least one embedder is wired.
-*/
+ * The admin introspector the worker passes to `createWorker({ vectorIntrospector })`.
+ * `queryIndex` is present only when at least one embedder is wired.
+ */
 interface VectorAdminIntrospector {
   listIndexes: () => Promise<VectorAdminIndexSummary[]>;
   queryIndex?: (options: {
@@ -260,11 +311,11 @@ interface VectorAdminIntrospector {
 }
 interface VectorAdminIntrospectorOptions {
   /**
-  * Per-index embedder (text → vector), keyed by index name. Supply the
-  * schema's embedders to enable studio similarity queries; omit it (or leave
-  * an index out) and that index lists read-only — `queryIndex` is withheld
-  * entirely when no embedder is provided.
-  */
+   * Per-index embedder (text → vector), keyed by index name. Supply the
+   * schema's embedders to enable studio similarity queries; omit it (or leave
+   * an index out) and that index lists read-only — `queryIndex` is withheld
+   * entirely when no embedder is provided.
+   */
   embedders?: Record<string, EmbedFunction<string>>;
   /** Live Vectorize bindings keyed by index name, from `env`. */
   indexes: Record<string, VectorizeIndexLike>;
@@ -272,14 +323,14 @@ interface VectorAdminIntrospectorOptions {
   registry: ReadonlyArray<VectorIndexRegistryEntry>;
 }
 /**
-* Build the read-only Vectorize introspector backing the studio's vector
-* browser. `listIndexes` returns the static registry, enriching each entry with
-* live `describe()` stats when the matching binding is present (a binding that
-* throws or lacks `describe` degrades to the static shape rather than failing
-* the whole list). `queryIndex` embeds the query text via the index's embedder
-* and runs an ANN search; it is omitted when no embedders are configured, so the
-* worker reports `VECTOR_QUERY_UNSUPPORTED` rather than half-answering.
-*/
+ * Build the read-only Vectorize introspector backing the studio's vector
+ * browser. `listIndexes` returns the static registry, enriching each entry with
+ * live `describe()` stats when the matching binding is present (a binding that
+ * throws or lacks `describe` degrades to the static shape rather than failing
+ * the whole list). `queryIndex` embeds the query text via the index's embedder
+ * and runs an ANN search; it is omitted when no embedders are configured, so the
+ * worker reports `VECTOR_QUERY_UNSUPPORTED` rather than half-answering.
+ */
 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 VectorEmbedderLike, type VectorIndexDefinitionLike, type VectorIndexRegistryEntry, type VectorMatchLike, type VectorMatchesLike, type VectorQueryInputLike, type VectorRecordLike, type VectorSearchLike, type VectorUpsertInputLike, type WriteEvent, type WriteHook, createContextVectors, createVectorAdminIntrospector, createVectorSyncHook, createVectors };