@lunora/bindings 0.0.0 → 1.0.0-alpha.2

package/dist/r2sql/index.d.ts

@@ -0,0 +1,383 @@
+/**
+* A composed SQL fragment. Carries the finished `text`; `toString()` returns it
+* so a fragment can be dropped straight into a template or `String(...)`.
+*/
+declare class Sql {
+  readonly text: string;
+  constructor(text: string);
+  toString(): string;
+}
+/** True when `value` is a {@link Sql} fragment (an already-trusted, pre-escaped span). */
+declare const isSql: (value: unknown) => value is Sql;
+/**
+* Wrap an already-trusted string as a {@link Sql} fragment so {@link sql}
+* splices it **verbatim** (no escaping). Use ONLY for SQL you constructed
+* yourself (identifiers, keywords, sub-fragments) — never for user input.
+*/
+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;
+/**
+* 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)
+* - `string` → a single-quoted, escaped literal
+* - `Array` → a parenthesised, comma-separated list of literals (for `IN (...)`)
+*
+* Anything else (object, symbol, function) throws — there is no safe SQL literal
+* for it, and silently coercing would risk a malformed or injectable statement.
+*/
+declare const lit: (value: unknown) => string;
+/**
+* Tagged template producing a safe {@link Sql} fragment. Each interpolation is
+* escaped with {@link lit} unless it is already a {@link Sql} (spliced
+* verbatim), so user values can never break out of their literal.
+*/
+declare const sql: (strings: TemplateStringsArray, ...values: unknown[]) => Sql;
+/** Join SQL fragments/strings with `separator` into one {@link Sql} (e.g. `AND`-ed conditions). */
+declare const joinSql: (parts: ReadonlyArray<Sql | string>, separator: string) => Sql;
+/** A single `ORDER BY` term: a bare column/expression (ASC) or one tagged via {@link asc} / {@link desc}. */
+type OrderTerm = Sql | string | {
+  dir: "ASC" | "DESC";
+  expr: Sql | string;
+};
+/** Tag an order term ascending — `asc("total")` → `total ASC`. */
+declare const asc: (expr: Sql | string) => OrderTerm;
+/** Tag an order term descending — `desc("total")` → `total DESC`. */
+declare const desc: (expr: Sql | string) => OrderTerm;
+/** Render one {@link OrderTerm} to SQL. */
+declare const renderOrderTerm: (term: OrderTerm) => string;
+/**
+* Public types for `@lunora/bindings/r2sql`.
+*
+* R2 SQL is Cloudflare's serverless, distributed query engine over **Apache
+* Iceberg** tables in [R2 Data Catalog](https://developers.cloudflare.com/r2/data-catalog/).
+* It has **no Workers binding** — every query is an HTTPS round-trip to the REST
+* endpoint (`POST …/r2-sql/query/{bucket}`). So, like Hyperdrive's `ctx.sql`, the
+* client is **non-deterministic external I/O**: it is wired onto `ActionCtx`
+* only (see the `r2sql_outside_action` advisor lint) and its reads are NOT
+* tracked by Lunora live queries.
+*
+* Everything here is deliberately structural (no hard dependency on
+* `@cloudflare/workers-types`) so unit tests can inject a plain `fetch` double
+* and never touch the network — mirroring `AnalyticsSqlConfig` in
+* `@lunora/bindings/analytics`.
+*/
+/**
+* Configuration for a {@link import("./client").R2SqlClient | R2SqlClient}.
+*
+* `apiToken` is a **secret** — a Cloudflare API token scoped to R2 SQL (read),
+* R2 Data Catalog, and R2 storage. It is never a binding and must never be
+* auto-scaffolded with a real value; the caller provides it from
+* env/`.dev.vars`.
+*/
+interface R2SqlConfig {
+  /** Cloudflare account id that owns the bucket/catalog. */
+  accountId: string;
+  /** API token with R2 SQL read + R2 Data Catalog + R2 storage scope. A secret — never a binding. */
+  apiToken: string;
+  /** The R2 bucket (warehouse) whose Data Catalog the queries run against. */
+  bucket: string;
+  /**
+  * Override the REST base URL. Defaults to Cloudflare's public R2 SQL host
+  * (`https://api.sql.cloudflarestorage.com/api/v1/accounts`). Injected in
+  * tests, or pointed at a regional/preview host.
+  */
+  endpoint?: string;
+  /**
+  * `fetch` implementation. Defaults to the global `fetch`; injected in tests
+  * so a query never touches the network.
+  */
+  fetch?: typeof globalThis.fetch;
+}
+/**
+* One column descriptor in a result's schema: the column `name` and, when the
+* engine reports it, the Iceberg storage `type` (`integer`, `string`,
+* `timestamp`, …). R2 SQL does not always echo a schema block, so `type` is
+* optional and `columns` may be derived from the first row's keys.
+*/
+interface R2SqlColumn {
+  name: string;
+  type?: string;
+}
+/**
+* A parsed R2 SQL result. R2 SQL returns a Cloudflare envelope
+* (`{ 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&lt;MyRow>(…)` /
+* `query&lt;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>> {
+  /** Column descriptors, echoed by the engine or inferred from the first row. */
+  columns: R2SqlColumn[];
+  /** Total rows returned. */
+  rowCount: number;
+  /** The result rows. */
+  rows: Row[];
+}
+/** Options for {@link import("./client").R2SqlClient.explain | explain}. */
+interface R2SqlExplainOptions {
+  /**
+  * `"json"` runs `EXPLAIN FORMAT JSON` (structured plan); `"text"` (default)
+  * runs a plain `EXPLAIN`.
+  */
+  format?: "json" | "text";
+}
+/**
+* Executes a finished SQL string against R2 SQL and returns the parsed result.
+* Deliberately non-generic (the row type is a caller-side concern) — the typed
+* `run()` / `query()` boundaries cast the open result to the declared row.
+*/
+type QueryExecutor = (statement: string) => Promise<R2SqlResult>;
+/** Anything that compiles to a statement and can run — a {@link import("./builder").SelectBuilder | SelectBuilder} or {@link import("./set-operation").SetOperation | SetOperation}. */
+interface Queryable<Row = Record<string, unknown>> {
+  /**
+  * True when this query carries its own `ORDER BY`/`LIMIT`, so a set
+  * operation must parenthesise it (R2 SQL rejects a bare `LIMIT` before a set
+  * operator). Read structurally by the set-operation renderer to avoid an
+  * import cycle.
+  */
+  readonly needsWrapForSetOperation?: boolean;
+  run: () => Promise<R2SqlResult<Row>>;
+  toSQL: () => string;
+}
+/** A `WHERE`/`HAVING`/`QUALIFY`/`ON` condition: trusted SQL text or a {@link Sql} fragment (use the `sql` tag to bind values safely). */
+type Condition = Sql | string;
+/** One member of a {@link SetOperation}: the leading query has no operator; each subsequent one carries the operator that joins it. */
+interface SetMember {
+  operator?: string;
+  query: Queryable<unknown>;
+}
+/**
+* A composition of queries via set operations. Chain more operations, or apply a
+* single `ORDER BY` / `LIMIT` to the combined result.
+*/
+declare class SetOperation<Row = Record<string, unknown>> implements Queryable<Row> {
+  /**
+  * Always `true`: a nested set operation must be parenthesised when it is a
+  * member of another set operation, or mixed operators mis-associate — e.g.
+  * `a.union(b.except(c))` must render `a UNION (b EXCEPT c)`, not the flat
+  * `a UNION b EXCEPT c`.
+  */
+  readonly needsWrapForSetOperation = true;
+  private readonly exec;
+  private readonly members;
+  private readonly orderByItems;
+  private limitValue?;
+  constructor(exec: QueryExecutor, members: SetMember[]);
+  /** Append `UNION other`. */
+  union(other: Queryable<unknown>): this;
+  /** Append `UNION ALL other`. */
+  unionAll(other: Queryable<unknown>): this;
+  /** Append `INTERSECT other`. */
+  intersect(other: Queryable<unknown>): this;
+  /** Append `EXCEPT other`. */
+  except(other: Queryable<unknown>): this;
+  /** `ORDER BY` applied to the combined result. */
+  orderBy(...terms: OrderTerm[]): this;
+  /** `LIMIT` applied to the combined result. */
+  limit(n: number): this;
+  /** Re-type the combined result rows. */
+  returns<NextRow>(): SetOperation<NextRow>;
+  /** Render the combined statement. */
+  toSQL(): string;
+  /** Execute the combined query and return the typed result. */
+  run(): Promise<R2SqlResult<Row>>;
+  private add;
+}
+/**
+* A fluent `SELECT` over one Iceberg table (`namespace.table`), generic over the
+* caller-declared `Row` result type.
+*/
+declare class SelectBuilder<Row = Record<string, unknown>> implements Queryable<Row> {
+  private readonly exec;
+  private readonly table;
+  private readonly selectItems;
+  private distinctFlag;
+  private readonly distinctOnItems;
+  private readonly joins;
+  private readonly whereConditions;
+  private readonly groupByItems;
+  private readonly havingConditions;
+  private qualifyCondition?;
+  private readonly orderByItems;
+  private limitValue?;
+  constructor(exec: QueryExecutor, table: string);
+  /** The `SELECT` list. Omit/empty for `SELECT *`. Items are columns, expressions, or aliased window fragments (`fn.rowNumber().over(...).as("rk")`). */
+  select(...items: (Sql | string)[]): this;
+  /** `SELECT DISTINCT` — unique rows. */
+  distinct(): this;
+  /** `DISTINCT ON (cols)` — the first row per distinct combination, ordered by {@link orderBy}. */
+  distinctOn(...columns: (Sql | string)[]): this;
+  /** `INNER JOIN table ON condition`. */
+  innerJoin(table: string, on: Condition): this;
+  /** `LEFT JOIN table ON condition`. */
+  leftJoin(table: string, on: Condition): this;
+  /** `RIGHT JOIN table ON condition`. */
+  rightJoin(table: string, on: Condition): this;
+  /** `FULL OUTER JOIN table ON condition`. */
+  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. */
+  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. */
+  having(...conditions: Condition[]): this;
+  /**
+  * `QUALIFY` — filter on a window function without a subquery, e.g.
+  * `.qualify(fn.rowNumber().over({ partitionBy: "region", orderBy: desc("total") }).lte(3))`.
+  */
+  qualify(condition: Condition): this;
+  /** `ORDER BY` term(s) — bare strings (ASC) or {@link import("./order").asc | asc}/{@link import("./order").desc | desc} tags. */
+  orderBy(...terms: OrderTerm[]): this;
+  /** `LIMIT n` (R2 SQL: 1–10,000, default 500). */
+  limit(n: number): this;
+  /** Re-type the result rows without changing the query (the builder carries no schema of its own). */
+  returns<NextRow>(): SelectBuilder<NextRow>;
+  /** `this UNION other` — all rows from both, duplicates removed. */
+  union(other: Queryable<unknown>): SetOperation<Row>;
+  /** `this UNION ALL other` — all rows from both, duplicates kept. */
+  unionAll(other: Queryable<unknown>): SetOperation<Row>;
+  /** `this INTERSECT other` — rows present in both. */
+  intersect(other: Queryable<unknown>): SetOperation<Row>;
+  /** `this EXCEPT other` — rows in `this` but not `other`. */
+  except(other: Queryable<unknown>): SetOperation<Row>;
+  /** True when this query carries its own `ORDER BY`/`LIMIT` — so a set operation must parenthesise it. */
+  get needsWrapForSetOperation(): boolean;
+  /** Render the `SELECT` statement (no trailing semicolon). */
+  toSQL(): string;
+  /** Execute the query and return the typed result. */
+  run(): Promise<R2SqlResult<Row>>;
+  /** The `SELECT [DISTINCT [ON (...)]]` head. */
+  private renderHead;
+  private addJoin;
+  private setOperation;
+}
+/**
+* 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.
+*/
+declare class R2SqlError extends Error {
+  readonly status: number;
+  constructor(status: number, body: string);
+}
+/**
+* The typed R2 SQL surface bound to `ctx.r2sql` on **`ActionCtx` only**. This is
+* the exact type the generated ctx imports as
+* `import("@lunora/bindings/r2sql").R2SqlClient` — keep the name and shape stable.
+*/
+interface R2SqlClient {
+  /** Run `DESCRIBE namespace.table` — column names and Iceberg types. */
+  describe: (table: string) => Promise<R2SqlResult>;
+  /** Run `EXPLAIN [FORMAT JSON] sql` — the execution plan, without running the query. */
+  explain: (statement: Sql | string, options?: R2SqlExplainOptions) => Promise<R2SqlResult>;
+  /** Start a chainable `SELECT` over `table` (`namespace.table`), generic over the caller-declared `Row`. */
+  from: <Row = Record<string, unknown>>(table: string) => SelectBuilder<Row>;
+  /** Run a raw SQL statement (the escape hatch). Use the `sql` tag to bind values safely. */
+  query: <Row = Record<string, unknown>>(statement: Sql | string) => Promise<R2SqlResult<Row>>;
+  /** Run `SHOW DATABASES` — the available namespaces. */
+  showDatabases: () => Promise<R2SqlResult>;
+  /** Run `SHOW TABLES IN namespace` — the tables in a namespace. */
+  showTables: (namespace: string) => Promise<R2SqlResult>;
+}
+/**
+* Build an {@link R2SqlClient}. Each query POSTs to the bucket's
+* `r2-sql/query/{bucket}` endpoint with the bearer token, then normalises the
+* envelope into {@link R2SqlResult}.
+*/
+declare const createR2Sql: (config: R2SqlConfig) => R2SqlClient;
+/**
+* A windowed expression. Extends {@link Sql}, so it is usable anywhere a raw
+* fragment is; `.as(alias)` makes a `SELECT` item, and the comparison helpers
+* (`.lte`, `.gt`, `.between`, …) make `QUALIFY` conditions.
+*/
+declare class WindowExpression extends Sql {
+  /** Alias the expression — `... AS alias` — for use in a `SELECT` list. */
+  as(alias: string): Sql;
+  /** `expr BETWEEN low AND high`. */
+  between(low: unknown, high: unknown): Sql;
+  /** `expr = value`. */
+  eq(value: unknown): Sql;
+  /** `expr > value`. */
+  gt(value: unknown): Sql;
+  /** `expr >= value`. */
+  gte(value: unknown): Sql;
+  /** `expr &lt; value`. */
+  lt(value: unknown): Sql;
+  /** `expr &lt;= value`. */
+  lte(value: unknown): Sql;
+  private compare;
+}
+/** The `OVER (...)` window specification. */
+interface OverSpec {
+  /**
+  * A raw frame clause, e.g. `"ROWS BETWEEN 2 PRECEDING AND CURRENT ROW"`.
+  * Spliced verbatim — it is keyword-only SQL, not a value.
+  */
+  frame?: string;
+  /** `ORDER BY` term(s) within the window. */
+  orderBy?: OrderTerm | OrderTerm[];
+  /** `PARTITION BY` column(s)/expression(s). */
+  partitionBy?: Sql | string | (Sql | string)[];
+}
+/**
+* A window function awaiting its `OVER (...)`. Call {@link WindowFunction.over |
+* .over} to bind a window and get a {@link WindowExpression}.
+*/
+declare class WindowFunction {
+  private readonly callText;
+  constructor(callText: string);
+  /** Attach the window frame, yielding a {@link WindowExpression}. */
+  over(spec?: OverSpec): WindowExpression;
+}
+/**
+* Window-function builders. Each returns a {@link WindowFunction}; chain
+* `.over(...)` to bind the window.
+*
+* Ranking: `rowNumber`, `rank`, `denseRank`, `percentRank`, `cumeDist`,
+* `ntile`. Offset/value: `lag`, `lead`, `firstValue`, `lastValue`, `nthValue`.
+* Aggregates used as windows: `sum`, `avg`, `count`, `min`, `max`.
+*/
+declare const fn: {
+  /** `AVG(column) OVER (...)`. */
+  avg: (column: Sql | string) => WindowFunction;
+  /** `COUNT(column) OVER (...)` — omit the column for `COUNT(*)`. */
+  count: (column?: Sql | string) => WindowFunction;
+  /** `CUME_DIST() OVER (...)`. */
+  cumeDist: () => WindowFunction;
+  /** `DENSE_RANK() OVER (...)`. */
+  denseRank: () => WindowFunction;
+  /** `FIRST_VALUE(column) OVER (...)`. */
+  firstValue: (column: Sql | string) => WindowFunction;
+  /** `LAG(column[, offset[, default]]) OVER (...)`. */
+  lag: (column: Sql | string, offset?: number, fallback?: unknown) => WindowFunction;
+  /** `LAST_VALUE(column) OVER (...)`. */
+  lastValue: (column: Sql | string) => WindowFunction;
+  /** `LEAD(column[, offset[, default]]) OVER (...)`. */
+  lead: (column: Sql | string, offset?: number, fallback?: unknown) => WindowFunction;
+  /** `MAX(column) OVER (...)`. */
+  max: (column: Sql | string) => WindowFunction;
+  /** `MIN(column) OVER (...)`. */
+  min: (column: Sql | string) => WindowFunction;
+  /** `NTH_VALUE(column, n) OVER (...)`. */
+  nthValue: (column: Sql | string, n: number) => WindowFunction;
+  /** `NTILE(buckets) OVER (...)`. */
+  ntile: (buckets: number) => WindowFunction;
+  /** `PERCENT_RANK() OVER (...)`. */
+  percentRank: () => WindowFunction;
+  /** `RANK() OVER (...)`. */
+  rank: () => WindowFunction;
+  /** `ROW_NUMBER() OVER (...)`. */
+  rowNumber: () => WindowFunction;
+  /** `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 };

package/dist/r2sql/index.mjs

@@ -0,0 +1,7 @@
+export { default as SelectBuilder } from '../packem_shared/SelectBuilder-DHaXZwn_.mjs';
+export { R2SqlError, createR2Sql } from '../packem_shared/R2SqlError-DlDd_SrE.mjs';
+export { asc, desc, renderOrderTerm } from '../packem_shared/asc-Cur-xO8v.mjs';
+export { default as SetOperation } from '../packem_shared/SetOperation-RDHcxccj.mjs';
+export { Sql, isSql, joinSql, lit, raw, sql, toText } from '../packem_shared/Sql-DceGtcUd.mjs';
+export { WindowFunction, fn } from '../packem_shared/WindowFunction-DA3pGC3N.mjs';
+export { default as WindowExpression } from '../packem_shared/WindowExpression-Cg9s2xcr.mjs';

package/dist/vectors/index.d.mts

@@ -0,0 +1,285 @@
+/**
+* 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.
+*/
+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.
+  */
+  indexes: Record<string, VectorizeIndexLike>;
+}
+interface UpsertInput<TInput = unknown> {
+  embed: EmbedFunction<TInput>;
+  id: string;
+  input: TInput;
+  metadata?: Record<string, unknown>;
+  namespace?: string;
+}
+interface QueryInput<TInput = unknown> {
+  embed?: EmbedFunction<TInput>;
+  filter?: Record<string, unknown>;
+  input?: TInput;
+  namespace?: string;
+  returnMetadata?: "none" | "indexed" | "all";
+  returnValues?: boolean;
+  topK?: number;
+  /** Either a precomputed vector or a value to embed via `embed`. */
+  vector?: ReadonlyArray<number>;
+}
+interface LunoraVectors {
+  deleteByIds: (indexName: string, ids: ReadonlyArray<string>) => Promise<VectorizeDeleteMutation>;
+  describe: (indexName: string) => Promise<VectorizeIndexDetails>;
+  getByIds: (indexName: string, ids: ReadonlyArray<string>) => Promise<ReadonlyArray<VectorizeVector>>;
+  query: <TInput>(indexName: string, input: QueryInput<TInput>) => Promise<VectorizeMatches>;
+  upsert: <TInput>(indexName: string, input: UpsertInput<TInput>) => Promise<VectorizeUpsertMutation>;
+  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.
+*/
+type VectorEmbedderLike = (input: string) => Promise<ReadonlyArray<number>> | ReadonlyArray<number>;
+interface VectorMatchLike {
+  id: string;
+  metadata?: Record<string, unknown>;
+  score: number;
+}
+interface VectorMatchesLike {
+  count: number;
+  matches: ReadonlyArray<VectorMatchLike>;
+}
+interface VectorRecordLike {
+  id: string;
+  metadata?: Record<string, unknown>;
+  values: ReadonlyArray<number>;
+}
+interface VectorQueryInputLike {
+  embed?: VectorEmbedderLike;
+  filter?: Record<string, unknown>;
+  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.
+  */
+  returnMetadata?: "none" | "indexed" | "all";
+  topK?: number;
+  vector?: ReadonlyArray<number>;
+}
+interface VectorUpsertInputLike {
+  embed: VectorEmbedderLike;
+  id: string;
+  input: string;
+  metadata?: Record<string, unknown>;
+  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).
+*/
+interface VectorSearchLike {
+  deleteByIds: (indexName: string, ids: ReadonlyArray<string>) => Promise<void>;
+  getByIds: (indexName: string, ids: ReadonlyArray<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>;
+}
+/**
+* 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;
+/** A single row mutation observed by the ctx-db, fed to {@link createVectorSyncHook}. */
+interface WriteEvent {
+  doc?: Record<string, unknown>;
+  id: string;
+  op: "delete" | "insert" | "update";
+  table: string;
+}
+type WriteHook = (event: WriteEvent) => Promise<void>;
+/** Inline vector index declared via `.vectorize(field, ...)` (DSL Shape A). */
+interface TableVectorIndexLike {
+  embed: VectorEmbedderLike;
+  field: string;
+  metadata?: ReadonlyArray<string>;
+  name: string;
+}
+interface TableDefinitionLike {
+  vectorIndexes?: ReadonlyArray<TableVectorIndexLike>;
+}
+/** Standalone vector index declared via `defineVectorIndex(...)` (DSL Shape B). */
+interface VectorIndexDefinitionLike {
+  embed: VectorEmbedderLike;
+  metadata?: (row: Record<string, unknown>) => Record<string, unknown>;
+  select: (row: Record<string, unknown>) => string;
+  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.
+*/
+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.
+*/
+declare const createVectorSyncHook: (options: {
+  allowSharedNamespace?: boolean;
+  namespace?: string;
+  schema: SchemaLike;
+  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`.
+*/
+interface VectorIndexRegistryEntry {
+  dimensions?: number;
+  field?: string;
+  metadata?: ReadonlyArray<string>;
+  metric?: VectorMetric;
+  name: string;
+  table: string;
+}
+/** A registry entry merged with the live `describe()` stats (when the binding is reachable). */
+interface VectorAdminIndexSummary extends VectorIndexRegistryEntry {
+  processedUpToMutation?: string;
+  vectorsCount?: number;
+}
+/** One nearest-neighbour hit from an admin similarity query. */
+interface VectorAdminQueryMatch {
+  id: string;
+  metadata?: Record<string, unknown>;
+  score: number;
+}
+/**
+* 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: {
+    name: string;
+    text: string;
+    topK?: number;
+  }) => Promise<{
+    matches: VectorAdminQueryMatch[];
+  }>;
+}
+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.
+  */
+  embedders?: Record<string, EmbedFunction<string>>;
+  /** Live Vectorize bindings keyed by index name, from `env`. */
+  indexes: Record<string, VectorizeIndexLike>;
+  /** The generated `LUNORA_VECTOR_INDEXES` registry (Vectorize can't enumerate at runtime). */
+  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.
+*/
+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 };