@pithy-sh/vector 0.1.0

package/src/data/documents.ts

@@ -0,0 +1,168 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { chunkByBoundParameters } from "@pithy-sh/core/src/data/boundParameters";
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { VectorDocument } from "./document";
+import { VECTOR_DOCUMENTS_TABLE, type VectorDatabase } from "./tables";
+
+/**
+ * The document corpus's reads and writes, in one place.
+ *
+ * Everything crossing the JS/SQLite line goes through the table's Zod codecs — `VectorDocument.encode` on
+ * the way in, `VectorDocument.parse` on the way out (CLAUDE.md §Data layer). No `JSON.stringify`, no epoch
+ * arithmetic, no `0/1` anywhere in this file.
+ *
+ * The store is a **structural seam** ({@link DocumentStore}) rather than a class over Kysely, because the
+ * reprocess Workflow and the HTTP handlers both take it and both are unit-tested with a fake. The Kysely
+ * implementation is {@link vectorDocuments}, exercised against real D1 in a Workers-runtime test.
+ *
+ * `model` is written **after** the vector reaches Vectorize, never with the row. A row whose model is null
+ * is a document that is durable but not yet searchable, which is precisely the set `pithy vector reprocess`
+ * should pick up — so the ordering makes a half-failed write self-healing instead of invisible.
+ */
+
+/** A page of the corpus, read in keyset order. */
+export interface DocumentPageRequest {
+  /** The index whose documents to read, as named in `pithy.config.ts`. */
+  indexName: string;
+  /** Read ids strictly greater than this one. Null starts at the beginning. */
+  after: string | null;
+  /** How many rows to read. The caller caps this at Vectorize's upsert batch. */
+  limit: number;
+  /**
+   * When set, read only rows whose `model` differs from this one (including rows with no model at all).
+   * That is the default `pithy vector reprocess` scan: re-embed exactly what drifted.
+   */
+  staleModel?: string;
+}
+
+/** The corpus operations the routes and the reprocess Workflow use. Structural, so a test injects a fake. */
+export interface DocumentStore {
+  /**
+   * Insert or replace documents, keyed by `(indexName, id)`. Idempotent — the same call twice leaves the
+   * same rows. The same id in two indexes is two documents, and neither displaces the other.
+   */
+  put(documents: readonly VectorDocument[]): Promise<void>;
+  /** One document, or null. */
+  get(indexName: string, id: string): Promise<VectorDocument | null>;
+  /** Documents by id, for hydrating a query's matches. Order is not guaranteed; the caller re-orders by score. */
+  byIds(indexName: string, ids: readonly string[]): Promise<VectorDocument[]>;
+  /** Delete one document. Returns whether a row was there to delete. */
+  remove(indexName: string, id: string): Promise<boolean>;
+  /** One keyset page, ordered by id ascending. */
+  page(request: DocumentPageRequest): Promise<VectorDocument[]>;
+  /**
+   * Record that these ids, in this index, are now embedded with `model`, as of `at`. The write that makes a
+   * row searchable. Scoped by index, so stamping `docs` never touches an identically-named `faqs` row.
+   */
+  markEmbedded(indexName: string, ids: readonly string[], model: string, at: Date): Promise<void>;
+}
+
+/**
+ * `byIds` binds the index name before its id list — one slot the chunk never gets.
+ *
+ * A query for `topK: 100` hydrates 100 ids, so a chunk sized at D1's cap itself would bind 101 and be
+ * rejected. The count is stated here, next to the query it describes; add a `where` below and this
+ * number moves with it.
+ */
+const BY_IDS_FIXED_PARAMETERS = 1;
+
+/** `markEmbedded` binds `model`, `updatedAt`, and the index name before a single id is counted. */
+const MARK_EMBEDDED_FIXED_PARAMETERS = 3;
+
+/** The Kysely-backed {@link DocumentStore} over the app database's `DB` binding. */
+export function vectorDocuments(db: VectorDatabase): DocumentStore {
+  return {
+    async put(documents) {
+      if (documents.length === 0) return;
+      for (const document of documents) {
+        // Encode through the table's codecs, then upsert on the primary key: a re-ingest of the same id is
+        // a replace, so an interrupted batch can simply be re-run.
+        const row = VectorDocument.encode(document);
+        await db
+          .insertInto(VECTOR_DOCUMENTS_TABLE)
+          .values(row)
+          .onConflict((conflict) =>
+            // The conflict target is the whole primary key. On `id` alone, writing `intro` to `faqs` would
+            // overwrite `docs`'s `intro` — same id, different index, different document.
+            conflict.columns(["indexName", "id"]).doUpdateSet({
+              namespace: row.namespace,
+              content: row.content,
+              metadata: row.metadata,
+              model: row.model,
+              updatedAt: row.updatedAt,
+            }),
+          )
+          .execute();
+      }
+    },
+
+    async get(indexName, id) {
+      const row = await db
+        .selectFrom(VECTOR_DOCUMENTS_TABLE)
+        .selectAll()
+        .where("id", "=", id)
+        .where("indexName", "=", indexName)
+        .executeTakeFirst();
+      return row ? VectorDocument.parse(row) : null;
+    },
+
+    async byIds(indexName, ids) {
+      if (ids.length === 0) return [];
+      const documents: VectorDocument[] = [];
+      for (const group of chunkByBoundParameters(ids, BY_IDS_FIXED_PARAMETERS)) {
+        const rows = await db
+          .selectFrom(VECTOR_DOCUMENTS_TABLE)
+          .selectAll()
+          .where("indexName", "=", indexName)
+          .where("id", "in", group)
+          .execute();
+        for (const row of rows) documents.push(VectorDocument.parse(row));
+      }
+      return documents;
+    },
+
+    async remove(indexName, id) {
+      const result = await db
+        .deleteFrom(VECTOR_DOCUMENTS_TABLE)
+        .where("id", "=", id)
+        .where("indexName", "=", indexName)
+        .executeTakeFirst();
+      return (result.numDeletedRows ?? 0n) > 0n;
+    },
+
+    async page(request) {
+      let query = db
+        .selectFrom(VECTOR_DOCUMENTS_TABLE)
+        .selectAll()
+        .where("indexName", "=", request.indexName)
+        .orderBy("id", "asc")
+        .limit(request.limit);
+      if (request.after !== null) query = query.where("id", ">", request.after);
+      if (request.staleModel !== undefined) {
+        // `model IS NULL` counts as stale: a row written but never embedded is exactly what needs a pass.
+        query = query.where((builder) =>
+          builder.or([builder.eb("model", "is", null), builder.eb("model", "!=", request.staleModel as string)]),
+        );
+      }
+      const rows = await query.execute();
+      return rows.map((row) => VectorDocument.parse(row));
+    },
+
+    async markEmbedded(indexName, ids, model, at) {
+      if (ids.length === 0) return;
+      // The timestamp goes through the same codec the column is declared with — never a hand-rolled epoch.
+      const updatedAt = SQLiteDate.encode(at);
+      for (const group of chunkByBoundParameters(ids, MARK_EMBEDDED_FIXED_PARAMETERS)) {
+        // Scoped by index, like every other statement here: an id names a row only together with its index.
+        await db
+          .updateTable(VECTOR_DOCUMENTS_TABLE)
+          .set({ model, updatedAt })
+          .where("indexName", "=", indexName)
+          .where("id", "in", group)
+          .execute();
+      }
+    },
+  };
+}

package/src/data/tables.ts

@@ -0,0 +1,31 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { createDatabase, type DatabaseSchema } from "@pithy-sh/core/src/data/db";
+import type { Kysely } from "kysely";
+import type { z } from "zod";
+import { VectorDocument } from "./document";
+
+/** The document corpus. `CamelCasePlugin` snake-cases it to `pithy_vector_documents`. */
+export const VECTOR_DOCUMENTS_TABLE = "pithyVectorDocuments";
+
+/** The vector tables map. One table: the corpus every index hydrates from and re-embeds out of. */
+export function vectorTables(): Record<string, z.ZodObject> {
+  return {
+    [VECTOR_DOCUMENTS_TABLE]: VectorDocument,
+  };
+}
+
+/** The typed Kysely database over the vector tables. */
+export type VectorTables = {
+  [VECTOR_DOCUMENTS_TABLE]: typeof VectorDocument;
+};
+export type VectorDatabase = Kysely<DatabaseSchema<VectorTables>>;
+
+/** Build the vector database from the `DB` binding (CamelCasePlugin installed). */
+export function vectorDatabase(d1: D1Database): VectorDatabase {
+  return createDatabase(d1, {
+    [VECTOR_DOCUMENTS_TABLE]: VectorDocument,
+  }) as unknown as VectorDatabase;
+}

package/src/embed/embed.ts

@@ -0,0 +1,126 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { InternalError, UpstreamError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
+import type { VectorIndexConfig } from "../config/config";
+import { VectorDimensionMismatchError } from "../error/errors";
+
+/**
+ * The Workers AI embedding call, over the `env.AI` binding (bindings-first — CLAUDE.md §Cloudflare access).
+ *
+ * The binding is typed structurally as {@link VectorAi} rather than depending on the exact `Ai` shape, so a
+ * test injects a fake and the code never reaches for a global. As with the index seam, this is the only way
+ * to test any of it: Cloudflare ships no local emulation for Workers AI. The seam is the first parameter and
+ * the model id trails, matching `@pithy-sh/media`'s enrichment calls.
+ *
+ * `@pithy-sh/cloudflare`'s `aiManager` is deliberately not used. It is the REST client — it needs an API
+ * token and an account id, which a Worker has neither of, and should not.
+ *
+ * {@link embedForIndex} is the call production code makes. It pins the model to the index's declared one for
+ * writes *and* queries, which removes the failure people actually hit: an index built with one model, queried
+ * with another. Nothing errors. The neighbors just come back from a space the query vector does not live in.
+ */
+
+/** The subset of the Workers AI binding this module uses. */
+export interface VectorAi {
+  /** Run a model by id with an input body; the response shape varies per model, so it is `unknown`. */
+  run(model: string, input: Record<string, unknown>): Promise<unknown>;
+}
+
+const EmbeddingResponse = z
+  .object({
+    shape: z
+      .array(z.number())
+      .optional()
+      .describe("The response's dimensions as [count, size], when the model reports them."),
+    data: z.array(z.array(z.number())).describe("One embedding per input text, in the order the texts were given."),
+  })
+  .describe("The shape of a Workers AI text-embedding response.");
+
+/**
+ * Embed texts with a named model. Returns one vector per text, in order. The model is a parameter with no
+ * default: an embedding whose model is implicit is an embedding nobody can reproduce.
+ */
+export async function embedTexts(ai: VectorAi, texts: string[], model: string): Promise<number[][]> {
+  if (texts.length === 0) {
+    throw new ValidationError({
+      message: "Nothing to embed.",
+      action: "Pass at least one piece of text.",
+      detail: "embedTexts received an empty batch",
+    });
+  }
+
+  // A rejection out of the binding is the one fault in this function a second attempt can answer
+  // differently: every other refusal here is deterministic in the input or in the model's answer. It
+  // therefore carries `core/upstream_failed`, which `vectorWorkflowRetry` states — a raw throw would be
+  // `unclassified` to `classifyWorkflowFault`, and unclassified is terminal (pithy-sh/pithy#348). The
+  // binding's own words stay in `detail`, which the HTTP codec strips.
+  let raw: unknown;
+  try {
+    raw = await ai.run(model, { text: texts });
+  } catch (error) {
+    throw new UpstreamError(
+      {
+        message: "The embedding model could not be reached.",
+        detail: `Workers AI rejected an embedding call with model '${model}'`,
+      },
+      { cause: error },
+    );
+  }
+  const parsed = EmbeddingResponse.safeParse(raw);
+  if (!parsed.success) {
+    throw new InternalError({
+      message: "The embedding model returned something unexpected.",
+      detail: `embedding model '${model}' returned an unexpected shape`,
+    });
+  }
+  if (parsed.data.data.length !== texts.length) {
+    throw new InternalError({
+      message: "The embedding model returned the wrong number of vectors.",
+      detail: `embedding model '${model}' returned ${parsed.data.data.length} vectors for ${texts.length} texts`,
+    });
+  }
+  return parsed.data.data;
+}
+
+/**
+ * Embed texts for one index, with that index's pinned model, and prove the result fits the index. A model
+ * swapped in config without re-creating the index fails here, on the first write or query, naming both — far
+ * cheaper than a corpus embedded half in one space and half in another.
+ */
+export async function embedForIndex(ai: VectorAi, index: VectorIndexConfig, texts: string[]): Promise<number[][]> {
+  const vectors = await embedTexts(ai, texts, index.model);
+  for (const [position, vector] of vectors.entries()) {
+    if (vector.length !== index.dimensions) {
+      throw new VectorDimensionMismatchError({
+        detail: `model '${index.model}' produced ${vector.length} components at position ${position}; the index expects ${index.dimensions}`,
+      });
+    }
+  }
+  return vectors;
+}
+
+/**
+ * Texts sent to Workers AI in one call.
+ *
+ * Not a published Vectorize limit — a deliberate chunk size. A model's per-request text cap varies by model,
+ * and one call carrying a thousand documents is a large, slow, all-or-nothing request: a single timeout
+ * discards every embedding in it. Chunking costs a few more round trips and makes a failure lose a hundred
+ * documents instead of a thousand.
+ */
+export const EMBED_CHUNK = 100;
+
+/**
+ * Embed a batch of any size for one index, in {@link EMBED_CHUNK}-sized calls, preserving order. The form
+ * every caller writing more than a handful of documents should use — a route handling a full batch, and every
+ * page of a reprocess run.
+ */
+export async function embedBatched(ai: VectorAi, index: VectorIndexConfig, texts: string[]): Promise<number[][]> {
+  const vectors: number[][] = [];
+  for (let start = 0; start < texts.length; start += EMBED_CHUNK) {
+    const chunk = texts.slice(start, start + EMBED_CHUNK);
+    for (const vector of await embedForIndex(ai, index, chunk)) vectors.push(vector);
+  }
+  return vectors;
+}

package/src/error/errors.ts

@@ -0,0 +1,146 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
+
+/**
+ * `@pithy-sh/vector` throw sugar. The `vector/*` codes live in core's closed `KitErrorPayload` union
+ * (CLAUDE.md §Errors); these subclasses are the package-local vehicles that set one of those members.
+ * Runtime code in this package throws one of these, never a plain `new Error`.
+ *
+ * The messages carry the ceiling that was breached, because "topK is too large" without the number sends the
+ * reader to the docs. Public text stays in `message`/`action`; the offending value goes in `detail`, which
+ * the HTTP codec strips.
+ */
+
+interface VectorErrorArgs {
+  message?: string;
+  action?: string;
+  detail?: string;
+  /**
+   * Values a translating client interpolates into its own wording for this code. Client-facing, so —
+   * unlike `action` and `detail` — these cross the boundary with `message`.
+   */
+  params?: MessageParams;
+}
+
+export class VectorMetadataIndexDriftError extends PithyError {
+  constructor(args: VectorErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "vector/metadata_index_drift",
+        status: 500,
+        message: args.message ?? "Search is not configured correctly.",
+        action:
+          args.action ??
+          "Run `pithy vector provision` to create the missing metadata indexes, then re-embed anything written before them.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class VectorDimensionMismatchError extends PithyError {
+  constructor(args: VectorErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "vector/dimension_mismatch",
+        status: 400,
+        message: args.message ?? "That vector is the wrong size for this index.",
+        action:
+          args.action ??
+          "An index's dimensions are fixed at creation. Embed with the model the index declares, or create a new index.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class VectorTopKExceededError extends PithyError {
+  constructor(args: VectorErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "vector/topk_exceeded",
+        status: 400,
+        message: args.message ?? "Too many matches requested.",
+        action: args.action ?? "Ask for at most 50 matches with values or metadata, 100 without.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class VectorFilterTooLargeError extends PithyError {
+  constructor(args: VectorErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "vector/filter_too_large",
+        status: 400,
+        message: args.message ?? "That filter is too large.",
+        action: args.action ?? "A filter's compact JSON must stay under 2,048 bytes. Narrow it, or split the query.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class VectorMetadataTooLargeError extends PithyError {
+  constructor(args: VectorErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "vector/metadata_too_large",
+        status: 400,
+        message: args.message ?? "That vector carries too much metadata.",
+        action:
+          args.action ??
+          "A vector's metadata must stay under 10 KiB. Keep long text in the document table and reference it by id.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class VectorIndexNotFoundError extends PithyError {
+  constructor(args: VectorErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "vector/index_not_found",
+        status: 404,
+        message: args.message ?? "That index does not exist.",
+        action: args.action ?? "Check the index name against the `indexes` block in pithy.config.ts.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class VectorUnfilterableFieldError extends PithyError {
+  constructor(args: VectorErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "vector/unfilterable_field",
+        status: 400,
+        message: args.message ?? "You cannot filter on that field.",
+        action:
+          args.action ??
+          "Mark the field `.meta({ filterable: true })` in the index's metadata schema, run `pithy vector provision`, and re-embed — Vectorize does not index what was written before the metadata index existed.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}

package/src/http/guard.ts

@@ -0,0 +1,27 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import { UnauthorizedError } from "@pithy-sh/core/src/error/pithyError";
+import type { MiddlewareHandler } from "hono";
+
+/**
+ * The vector routes' identity gate. Every vector route declares the `bearer`/`session` verification
+ * strategy; this middleware enforces it through the core `AuthContext` seam (`c.var.auth`), which
+ * `@pithy-sh/auth` populates. It never validates a credential itself — it only asserts one resolved.
+ *
+ * It is **copied**, not imported from `@pithy-sh/auth`. That is the point: this package's `dependsOn` stays
+ * empty, and a project with no auth capability composed leaves `c.var.auth` null, so every vector route is
+ * denied. A missing dependency that denies is a safe default; one that opens is not.
+ */
+export function requireAuth(): MiddlewareHandler<PithyHonoEnv> {
+  return async (c, next) => {
+    if (!c.var.auth) {
+      throw new UnauthorizedError({
+        message: "Authentication required.",
+        action: "Sign in and retry with a valid session or bearer token.",
+      });
+    }
+    await next();
+  };
+}