@pithy-sh/vector 0.1.0

package/src/http/handlers.ts

@@ -0,0 +1,206 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { NotFoundError } from "@pithy-sh/core/src/error/pithyError";
+import type { VectorIndexConfig } from "../config/config";
+import type { VectorDocument } from "../data/document";
+import type { DocumentStore } from "../data/documents";
+import type { VectorAi } from "../embed/embed";
+import { embedBatched } from "../embed/embed";
+import { compileFilter } from "../index/filter";
+import { deleteVectors, queryVectors, upsertVectors, type VectorStore, type VectorUpsert } from "../index/index";
+import type { MetadataIndexDescriptor } from "../index/metadata";
+import type { QueryInput, UpsertDocumentsInput, VectorDocumentInput } from "./schemas";
+
+/**
+ * The vector route handlers, over an injected {@link HandlerDeps} rather than a request context — so every
+ * one of them is unit-tested against fakes with no Worker, no Vectorize, and no network. Vectorize has no
+ * local emulation, so this is the only way any of this gets a test at all.
+ *
+ * Nothing here parses a request. Shape is declared on the route line with `zValidator`, so a handler is
+ * handed a value that has already been validated and takes it typed — what is left in these functions is
+ * the ordering, the embedding, and the Vectorize ceilings, which are the parts a schema cannot state.
+ *
+ * Two orderings here are load-bearing and are the reason these are handlers rather than three lines each.
+ *
+ * **A write lands in D1 first, and the row's `model` is set only after Vectorize accepts the vector.** The
+ * corpus is the durable thing: Vectorize hands back ids and scores, never content, so a document that
+ * reached the index but not the table can never be re-embedded. Writing D1 first makes a half-failed write
+ * recoverable, and leaving `model` null until the vector is accepted makes it recoverable *by the default
+ * `pithy vector reprocess` pass*, which selects exactly the rows whose model is not the configured one.
+ *
+ * **A delete leaves the index first.** The reverse order — D1 then Vectorize — turns a failure into a vector
+ * that still matches queries but can never be hydrated, which surfaces as a result set that quietly shrinks.
+ *
+ * Vectorize applies writes asynchronously: `mutationId` is an acknowledgement, not a completed write.
+ * Nothing here reads back what it just wrote.
+ */
+
+/** Everything a handler needs, resolved per request by the route layer. */
+export interface HandlerDeps {
+  /** The document corpus in D1 — what results hydrate from and re-embeds read out of. */
+  documents: DocumentStore;
+  /** The Vectorize index this request addresses, resolved from the index's declared binding. */
+  store: VectorStore;
+  /** The Workers AI binding, for embedding text. */
+  ai: VectorAi;
+  /** The resolved config of the index named in the path. */
+  index: VectorIndexConfig;
+  /** The index's name as `pithy.config.ts` declares it — the D1 scope key and the path segment. */
+  indexName: string;
+  /** The metadata indexes this index declares, introspected once at route registration. */
+  filterable: readonly MetadataIndexDescriptor[];
+  /** Matches to return when a query names no `topK` — the capability's configured `defaultTopK`. */
+  defaultTopK: number;
+  /** Id source for a document that supplies none. */
+  newId(): string;
+  /** Clock, injected so timestamps are assertable. */
+  now(): Date;
+}
+
+/** What a write returns: the ids written and Vectorize's acknowledgement of the enqueued mutation. */
+export interface UpsertResult {
+  /** The document ids written, in request order. */
+  ids: string[];
+  /** Vectorize's mutation id. The write is enqueued, not yet visible to a query. */
+  mutationId: string;
+}
+
+/** One match, hydrated. `document` is null when the index holds a vector the corpus no longer has. */
+export interface QueryMatchResult {
+  /** The matched vector's id. */
+  id: string;
+  /** The similarity score, as scored by the index's metric. */
+  score: number;
+  /** The document behind the match, or null when D1 has no row for it. */
+  document: VectorDocument | null;
+}
+
+/** What a search returns. */
+export interface QueryResult {
+  /** How many matches came back. */
+  count: number;
+  /** The matches, nearest first, each hydrated from the document corpus. */
+  matches: QueryMatchResult[];
+}
+
+/**
+ * Write one or many documents into an index. Text is embedded with the index's pinned model; a supplied
+ * `values` array is inserted as-is. Ids may be supplied to make the write idempotent.
+ */
+export async function upsertDocuments(deps: HandlerDeps, body: UpsertDocumentsInput): Promise<UpsertResult> {
+  // The two accepted write shapes — a batch, or a bare document — normalized into one list.
+  const inputs: VectorDocumentInput[] = "documents" in body ? [...body.documents] : [body];
+  const at = deps.now();
+
+  // Embed every text in one call: Workers AI charges per request, and a batch keeps the vectors of one
+  // write in the same model invocation.
+  const toEmbed = inputs.filter((input) => input.text !== undefined);
+  const embedded =
+    toEmbed.length > 0
+      ? await embedBatched(
+          deps.ai,
+          deps.index,
+          toEmbed.map((input) => input.text as string),
+        )
+      : [];
+
+  const ids: string[] = [];
+  const documents: VectorDocument[] = [];
+  const vectors: VectorUpsert[] = [];
+  let embeddedAt = 0;
+
+  for (const input of inputs) {
+    const id = input.id ?? deps.newId();
+    const values = input.values ?? (embedded[embeddedAt++] as number[]);
+    const namespace = input.namespace ?? deps.index.namespace;
+    ids.push(id);
+    documents.push({
+      id,
+      indexName: deps.indexName,
+      namespace: namespace ?? null,
+      content: input.content ?? input.text ?? null,
+      metadata: input.metadata ?? {},
+      // Null until Vectorize accepts the vector — see the ordering note at the top of this file.
+      model: null,
+      createdAt: at,
+      updatedAt: at,
+    });
+    vectors.push({
+      id,
+      values,
+      ...(input.metadata ? { metadata: input.metadata } : {}),
+      ...(namespace ? { namespace } : {}),
+    });
+  }
+
+  await deps.documents.put(documents);
+  const mutationId = await upsertVectors(deps.store, deps.index, vectors);
+  await deps.documents.markEmbedded(deps.indexName, ids, deps.index.model, at);
+
+  return { ids, mutationId };
+}
+
+/**
+ * Search an index and hydrate the matches from the document corpus. Vectorize returns ids and scores;
+ * neither values nor metadata is requested, which both keeps the response small and raises the topK ceiling
+ * from 50 to 100 — the content comes from D1, where it is authoritative anyway.
+ */
+export async function queryDocuments(deps: HandlerDeps, input: QueryInput): Promise<QueryResult> {
+  const vector = input.values ?? ((await embedBatched(deps.ai, deps.index, [input.text as string]))[0] as number[]);
+  const filter = input.filter ? compileFilter(deps.filterable, input.filter) : undefined;
+
+  const result = await queryVectors(deps.store, deps.index, vector, {
+    topK: input.topK ?? deps.defaultTopK,
+    ...(input.namespace ? { namespace: input.namespace } : {}),
+    ...(filter ? { filter } : {}),
+  });
+
+  const hydrated = await deps.documents.byIds(
+    deps.indexName,
+    result.matches.map((match) => match.id),
+  );
+  const byId = new Map(hydrated.map((document) => [document.id, document]));
+
+  return {
+    count: result.count,
+    // Order comes from Vectorize, not from D1: the score ranking is the answer, and a match the corpus has
+    // lost is reported as a null document rather than dropped, because a silently shorter result set is the
+    // failure mode this package exists to make visible.
+    matches: result.matches.map((match) => ({
+      id: match.id,
+      score: match.score,
+      document: byId.get(match.id) ?? null,
+    })),
+  };
+}
+
+/** Fetch one hydrated document. */
+export async function getDocument(deps: HandlerDeps, id: string): Promise<VectorDocument> {
+  const document = await deps.documents.get(deps.indexName, id);
+  if (!document) {
+    throw new NotFoundError({
+      message: "No such document.",
+      action: "Check the id, or write the document first.",
+      detail: `no document '${id}' in index '${deps.indexName}'`,
+    });
+  }
+  return document;
+}
+
+/** What a delete returns. */
+export interface DeleteResult {
+  /** The id that was removed. */
+  id: string;
+  /** Vectorize's mutation id for the enqueued delete. */
+  mutationId: string;
+}
+
+/** Delete a document from the index and from the corpus, in that order. */
+export async function deleteDocument(deps: HandlerDeps, id: string): Promise<DeleteResult> {
+  // Read first, so an unknown id is a 404 rather than a mutation against nothing.
+  await getDocument(deps, id);
+  const mutationId = await deleteVectors(deps.store, [id]);
+  await deps.documents.remove(deps.indexName, id);
+  return { id, mutationId };
+}

package/src/http/provisionGuard.ts

@@ -0,0 +1,39 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PithyMiddleware } from "@pithy-sh/core/src/capability/capability";
+import type { VectorConfig } from "../config/config";
+import { assertProvisionedMetadataIndexes, readProvisionRecord } from "../index/provisioned";
+
+/**
+ * The boot check, as middleware: compare the filterable fields this config declares against what
+ * `pithy vector provision` last observed, and refuse to serve if they disagree.
+ *
+ * **Why middleware and not the `compose` hook.** `compose` is the obvious home — it fires once when
+ * `createBackend` assembles the backend — but it is handed the composed capabilities and nothing else,
+ * because in Workers there *is* no `env` at assembly. Bindings and vars arrive per request. The record lives
+ * in a var, so the earliest moment it can be read is the first request. That is exactly why core's own
+ * `validateBindings` runs there too, memoized, rather than at module load: "in Workers `env` is per-request,
+ * so there is no env to check until a request arrives." First request is what boot means here.
+ *
+ * **It gates every route, not just the vector ones.** Same precedent, same reasoning: a missing binding fails
+ * the whole app rather than the capability that needed it, because a Worker deployed against the wrong
+ * configuration should be unmistakably broken, not subtly wrong. `GET /health` is registered before any
+ * capability middleware and answers without reaching this, so an orchestrator's health probe still gets a
+ * response — the deploy fails on real traffic, where a human is reading the error.
+ *
+ * The result is memoized only on success. A failure leaves the check armed, so it re-runs and re-throws on
+ * the next request instead of collapsing into a bare 500 with no explanation.
+ */
+export function provisionGuard(config: VectorConfig): PithyMiddleware {
+  let verified = false;
+  return (app) => {
+    app.use("*", async (c, next) => {
+      if (!verified) {
+        assertProvisionedMetadataIndexes(config, readProvisionRecord(c.env as Record<string, unknown>));
+        verified = true;
+      }
+      await next();
+    });
+  };
+}

package/src/http/routes.ts

@@ -0,0 +1,162 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { zValidator } from "@hono/zod-validator";
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import { validationHook } from "@pithy-sh/core/src/http/validation";
+import type { Context, Hono } from "hono";
+import type { VectorConfig, VectorIndexConfig } from "../config/config";
+import { vectorDocuments } from "../data/documents";
+import { vectorDatabase } from "../data/tables";
+import type { VectorAi } from "../embed/embed";
+import { VectorIndexNotFoundError } from "../error/errors";
+import type { VectorStore } from "../index/index";
+import { type MetadataIndexDescriptor, metadataIndexes } from "../index/metadata";
+import { requireAuth } from "./guard";
+import { deleteDocument, getDocument, type HandlerDeps, queryDocuments, upsertDocuments } from "./handlers";
+import { QueryInput, UpsertDocumentsInput, VectorDocumentParams, VectorIndexParams } from "./schemas";
+
+/**
+ * The vector routes, what each accepts, and their declared verification strategies — every one of them
+ * `bearer | session`:
+ *
+ *   POST   /vector/:index/documents      → write one or many  param: VectorIndexParams, json: UpsertDocumentsInput
+ *   POST   /vector/:index/query          → search             param: VectorIndexParams, json: QueryInput
+ *   GET    /vector/:index/documents/:id  → fetch one hydrated param: VectorDocumentParams
+ *   DELETE /vector/:index/documents/:id  → delete from both   param: VectorDocumentParams
+ *
+ * Every route is gated by {@link requireAuth} — there is no public vector surface. A corpus is content the
+ * adopter owns, and an unauthenticated search endpoint is an exfiltration endpoint. `requireAuth` is copied
+ * into this package rather than imported from `@pithy-sh/auth`, so a project with no auth capability
+ * composed denies every route instead of serving them open.
+ *
+ * The validators sit **after** the guard, deliberately: an unauthenticated request carrying a malformed body
+ * is a 401, not a 400 — shape is never answered for a caller who has not been verified.
+ *
+ * `:index` names an index in `pithy.config.ts`, never a Cloudflare resource — an unknown one is a 404 from
+ * config alone, before any binding is touched. The param schema bounds the segment's *shape* only; the name
+ * is still resolved in the dep resolver, so which indexes exist stays unprobeable. Each index's metadata
+ * schema is introspected **once**, here at registration, rather than per request: the descriptors are what
+ * the filter compiler checks against, and they change only when the config does.
+ */
+
+/** The bindings the vector routes read off the request env. */
+export interface VectorRoutesEnv {
+  /** The app database the document corpus lives in. */
+  DB: D1Database;
+  /** The Workers AI binding used to embed text. */
+  AI: VectorAi;
+}
+
+export interface VectorRoutesOptions {
+  /** The resolved vector config. */
+  config: VectorConfig;
+  /** The path the routes mount under. Defaults to `/vector`. */
+  basePath?: string;
+  /** Test seam: resolve handler deps for one index from the request context. Defaults to the env resolver. */
+  resolveDeps?: (c: Context<PithyHonoEnv>, indexName: string) => HandlerDeps;
+}
+
+/** Read a binding by name, throwing rather than returning undefined — a missing binding is a config fault. */
+function binding<T>(c: Context<PithyHonoEnv>, name: string, action: string): T {
+  const value = (c.env as Record<string, unknown>)[name] as T | undefined;
+  if (!value) {
+    throw new InternalError({
+      message: "Search is not configured.",
+      action,
+      detail: `the \`${name}\` binding was not present on env`,
+    });
+  }
+  return value;
+}
+
+/** The config for a named index, or a 404 — index names come from config, so an unknown one is not found. */
+function indexConfig(config: VectorConfig, name: string): VectorIndexConfig {
+  const index = config.indexes[name];
+  if (!index) {
+    throw new VectorIndexNotFoundError({
+      detail: `no index '${name}' in config; declared: ${Object.keys(config.indexes).join(", ") || "none"}`,
+    });
+  }
+  return index;
+}
+
+/** Register the vector sub-router. Returned as the capability's `routes` hook. */
+export function registerVectorRoutes(options: VectorRoutesOptions): (app: Hono<PithyHonoEnv>) => void {
+  const base = options.basePath ?? "/vector";
+  const { config } = options;
+
+  // Introspect every index's metadata once. `metadataIndexes` throws on an unprovisionable schema, and doing
+  // it here means that failure lands at assembly rather than on a caller's first filtered search.
+  const filterable = new Map<string, MetadataIndexDescriptor[]>();
+  for (const [name, index] of Object.entries(config.indexes)) {
+    filterable.set(name, index.metadata ? metadataIndexes(index.metadata) : []);
+  }
+
+  const resolve =
+    options.resolveDeps ??
+    ((c: Context<PithyHonoEnv>, indexName: string): HandlerDeps => {
+      const index = indexConfig(config, indexName);
+      return {
+        documents: vectorDocuments(vectorDatabase(binding<D1Database>(c, "DB", "Bind a D1 database named DB."))),
+        store: binding<VectorStore>(
+          c,
+          index.binding,
+          `Bind the Vectorize index as \`${index.binding}\` in wrangler.jsonc, then run \`pithy vector provision\`.`,
+        ),
+        ai: binding<VectorAi>(c, "AI", "Bind Workers AI as `AI` in wrangler.jsonc."),
+        index,
+        indexName,
+        filterable: filterable.get(indexName) ?? [],
+        defaultTopK: config.defaultTopK,
+        newId: () => crypto.randomUUID(),
+        now: () => new Date(),
+      };
+    });
+
+  return (app) => {
+    app.post(
+      `${base}/:index/documents`,
+      requireAuth(),
+      zValidator("param", VectorIndexParams, validationHook),
+      zValidator("json", UpsertDocumentsInput, validationHook),
+      async (c) => {
+        const deps = resolve(c, c.req.valid("param").index);
+        return c.json(await upsertDocuments(deps, c.req.valid("json")), 201);
+      },
+    );
+
+    app.post(
+      `${base}/:index/query`,
+      requireAuth(),
+      zValidator("param", VectorIndexParams, validationHook),
+      zValidator("json", QueryInput, validationHook),
+      async (c) => {
+        const deps = resolve(c, c.req.valid("param").index);
+        return c.json(await queryDocuments(deps, c.req.valid("json")));
+      },
+    );
+
+    app.get(
+      `${base}/:index/documents/:id`,
+      requireAuth(),
+      zValidator("param", VectorDocumentParams, validationHook),
+      async (c) => {
+        const params = c.req.valid("param");
+        return c.json(await getDocument(resolve(c, params.index), params.id));
+      },
+    );
+
+    app.delete(
+      `${base}/:index/documents/:id`,
+      requireAuth(),
+      zValidator("param", VectorDocumentParams, validationHook),
+      async (c) => {
+        const params = c.req.valid("param");
+        return c.json(await deleteDocument(resolve(c, params.index), params.id));
+      },
+    );
+  };
+}

package/src/http/schemas.ts

@@ -0,0 +1,158 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { MAX_NAME_BYTES, MAX_TOPK_WITHOUT_PAYLOAD, MAX_UPSERT_BATCH, MAX_VECTOR_ID_BYTES } from "../index/limits";
+
+/**
+ * The request schemas for the vector routes. Each is declared on the route line with
+ * `zValidator(target, Schema, validationHook)`, so a malformed request is a `validation/invalid_input` 400
+ * before any handler runs (CLAUDE.md §Zod). They carry only the shape rules — the Vectorize ceilings
+ * (dimensions, id bytes, metadata size, filter size) are enforced once, in `index/index.ts`, so the numbers
+ * cannot disagree between two files.
+ *
+ * The param schemas are **shape** checks, not existence checks. Resolving `:index` against the configured
+ * indexes stays where it was, in the route's dep resolver, and an index the config does not declare is still
+ * a `vector/index_not_found` 404 — never a 400 that would turn the set of configured index names into
+ * something a caller can probe for.
+ *
+ * Every write and every query accepts **either** `text` — embedded here with the index's pinned model — or a
+ * precomputed `values` array. Both, or neither, is refused: a caller who sends both has two sources of truth
+ * for one vector, and nothing downstream could say which one the index holds.
+ */
+
+/** An index name is a path segment and a Cloudflare resource name, so it is lowercase, digits, and dashes. */
+const INDEX_NAME = /^[a-z0-9][a-z0-9-]*$/;
+
+/**
+ * The `:index` segment. Bounded to exactly what `VectorConfig` accepts as a key — a name outside this shape
+ * cannot be configured, so it could never have resolved, and rejecting it here narrows nothing.
+ */
+const IndexSegment = z
+  .string()
+  .max(MAX_NAME_BYTES)
+  .regex(INDEX_NAME, "An index name is lowercase, digits, and dashes — it is a path segment.")
+  .describe(
+    "The index this request addresses, as `pithy.config.ts` names it. Resolved against the configured indexes in the route, where an unknown name is a `vector/index_not_found` 404.",
+  );
+
+/** The path params of a route that names an index and nothing else. */
+export const VectorIndexParams = z
+  .object({ index: IndexSegment })
+  .describe("The path params of an index-scoped vector route.");
+export type VectorIndexParams = z.output<typeof VectorIndexParams>;
+
+/** The path params of a route that addresses one document inside an index. */
+export const VectorDocumentParams = z
+  .object({
+    index: IndexSegment,
+    id: z
+      .string()
+      .min(1)
+      .max(MAX_VECTOR_ID_BYTES)
+      .describe(
+        `The document's id, which is also its vector id. Opaque to this capability — bounded, not parsed. Vectorize refuses an id over ${MAX_VECTOR_ID_BYTES} bytes at write time, so a longer one could never name a document.`,
+      ),
+  })
+  .describe("The path params of a route addressing one document in one index.");
+export type VectorDocumentParams = z.output<typeof VectorDocumentParams>;
+
+/** Why a payload's vector source is unusable, or null. Both bodies take text **or** values, never both. */
+function sourceProblem(value: { text?: unknown; values?: unknown }): string | null {
+  const hasText = value.text !== undefined;
+  const hasValues = value.values !== undefined;
+  if (hasText && hasValues) return "Send `text` or `values`, not both — two sources for one vector.";
+  if (!hasText && !hasValues) return "Send `text` to embed, or `values` for a precomputed embedding.";
+  return null;
+}
+
+/** One document on its way into an index. */
+export const VectorDocumentInput = z
+  .object({
+    id: z
+      .string()
+      .min(1)
+      .optional()
+      .describe(
+        "The document's id, which is also its vector id. Supply your own to make a write idempotent — the same id replaces rather than duplicates, within this index. The same id in another index is a different document. Omitted means one is generated.",
+      ),
+    text: z
+      .string()
+      .min(1)
+      .optional()
+      .describe("The text to embed with this index's pinned model. Stored as the document's content."),
+    values: z
+      .array(z.number())
+      .optional()
+      .describe("A precomputed embedding, inserted as-is. Must be exactly the index's dimensions long."),
+    content: z
+      .string()
+      .optional()
+      .describe("The text to store as this document's content, when it differs from what was embedded."),
+    metadata: z
+      .record(z.string(), z.unknown())
+      .optional()
+      .describe("The metadata this vector carries. Fields marked filterable in the index's schema are queryable."),
+    namespace: z
+      .string()
+      .min(1)
+      .optional()
+      .describe("The namespace this vector belongs to. Falls back to the index's configured namespace."),
+  })
+  .check((ctx) => {
+    const problem = sourceProblem(ctx.value);
+    if (problem) ctx.issues.push({ code: "custom", input: ctx.value, path: ["text"], message: problem });
+  })
+  .describe("One document to write into an index: what to embed (or an embedding), plus its metadata.");
+export type VectorDocumentInput = z.output<typeof VectorDocumentInput>;
+
+/** A batch write. The array form; a bare document is accepted too and normalized into this shape. */
+export const VectorDocumentBatch = z
+  .object({
+    documents: z
+      .array(VectorDocumentInput)
+      .min(1)
+      .max(MAX_UPSERT_BATCH)
+      .describe(
+        `The documents to write, at most ${MAX_UPSERT_BATCH} — the ceiling the Vectorize binding accepts in one call.`,
+      ),
+  })
+  .describe("A batch of documents to write into an index in one call.");
+export type VectorDocumentBatch = z.output<typeof VectorDocumentBatch>;
+
+/** The write body: one document, or a batch. Both land in the same handler path. */
+export const UpsertDocumentsInput = z
+  .union([VectorDocumentBatch, VectorDocumentInput])
+  .describe("The body of a document write: either a `documents` array or a single document object.");
+export type UpsertDocumentsInput = z.output<typeof UpsertDocumentsInput>;
+
+/** A search. */
+export const QueryInput = z
+  .object({
+    text: z.string().min(1).optional().describe("The query text, embedded with this index's pinned model."),
+    values: z.array(z.number()).optional().describe("A precomputed query vector, used as-is."),
+    topK: z
+      .number()
+      .int()
+      .min(1)
+      .max(MAX_TOPK_WITHOUT_PAYLOAD)
+      .optional()
+      .describe("How many matches to return. Defaults to the capability's configured `defaultTopK`."),
+    namespace: z
+      .string()
+      .min(1)
+      .optional()
+      .describe("Restrict the search to one namespace. Falls back to the index's configured namespace."),
+    filter: z
+      .record(z.string(), z.unknown())
+      .optional()
+      .describe(
+        "A metadata filter over the index's filterable fields. A field with no metadata index is refused rather than silently ignored — filtering on one returns partial results with no error.",
+      ),
+  })
+  .check((ctx) => {
+    const problem = sourceProblem(ctx.value);
+    if (problem) ctx.issues.push({ code: "custom", input: ctx.value, path: ["text"], message: problem });
+  })
+  .describe("A similarity search over one index, optionally narrowed by a metadata filter.");
+export type QueryInput = z.output<typeof QueryInput>;