@pithy-sh/vector 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pithy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @pithy-sh/vector
+
+Semantic search over your own content, in your own Cloudflare account. Workers AI embeds, Vectorize indexes, D1 keeps the text.
+
+The interesting part of this package is not the search. It is the metadata, which Vectorize makes a provisioning-time decision wearing the costume of a query-time one — and gives you no error when you get it wrong.
+
+```sh
+pithy add vector
+```
+
+**Documentation: [pithy.sh/docs/capabilities/vector](https://pithy.sh/docs/capabilities/vector).** Overview, adding it, using it, and the reference: the embedding models, metadata indexes, provisioning, the reprocess worker.
+
+_Everything else is on the site. `pithy.sh/docs` is canonical — new prose goes there, not here._
+
+## License
+
+MIT — adopter-side app value. The root `LICENSE` covers it.

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@pithy-sh/vector",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pithy-sh/pithy.git",
+    "directory": "packages/vector"
+  },
+  "files": [
+    "src",
+    "pithy.manifest.json",
+    "!src/**/*.test.*"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./src/*": "./src/*.ts"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit false --outDir dist",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:node": "vitest run --project=node",
+    "test:workers": "vitest run --project=workers",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "clean": "rm -rf dist .turbo",
+    "reset": "bun run clean && rm -rf node_modules"
+  },
+  "dependencies": {
+    "@cloudflare/workers-types": "^5.20260729.1",
+    "@hono/zod-validator": "^0.9.0",
+    "@pithy-sh/cloudflare": "workspace:*",
+    "@pithy-sh/core": "workspace:*",
+    "@pithy-sh/secrets": "workspace:*",
+    "hono": "^4.13.2",
+    "kysely": "^0.29.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-plugin": "^1.0.0",
+    "@pithy-sh/tsconfig": "workspace:*",
+    "@types/node": "^22.15.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "comment-json": "^5.0.0",
+    "kysely-d1": "^0.4.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.0",
+    "wrangler": "^4.115.0"
+  }
+}

package/pithy.manifest.json

@@ -0,0 +1,47 @@
+{
+  "name": "vector",
+  "package": "@pithy-sh/vector",
+  "requiredBindings": [
+    {
+      "type": "vectorize",
+      "name": "VECTORIZE",
+      "remote": true
+    },
+    {
+      "type": "ai",
+      "name": "AI",
+      "remote": true
+    },
+    {
+      "type": "d1",
+      "name": "DB"
+    },
+    {
+      "type": "workflow",
+      "name": "VECTOR_REPROCESS",
+      "job": "reprocess",
+      "className": "VectorReprocessWorkflow",
+      "optional": true
+    }
+  ],
+  "peerCapabilities": [],
+  "optionalCapabilities": ["auth"],
+  "migrationNamespace": "vector",
+  "whenToEnable": "Semantic search over your own content — ask in a sentence, get the passages that mean the same thing. Embeddings come from Workers AI and live in your own Vectorize index; the source text lives in your D1, because Vectorize returns ids and scores, not content, and caps metadata at 10 KiB. What this adds over calling the binding yourself is the part that bites: an index's filterable metadata is declared in Zod, so one declaration provisions the metadata indexes, types the filter builder, and is reconciled against the live index every time you run `pithy vector provision`. Vectorize does not error when you filter on a field it indexed late — it silently drops every vector written before the index existed, and you get a short result set that looks fine. So `provision` records what it observed, and the Worker refuses to boot when the config declares a filterable field that record does not have — edit a metadata schema, deploy without re-provisioning, and you get an error naming the field instead of quietly wrong search. A filter naming a field the schema does not mark filterable is refused outright rather than run. The model is pinned per index and used for writes and queries alike, so an index cannot be built in one embedding space and searched in another. Routes scope to the caller, so add auth too.",
+  "scaffold": [
+    "Add a `vector({ indexes: { ... } })` block to pithy.config.ts and declare at least one index: the Workers AI `model` that fills it, the `dimensions` that model produces, and a `metric` (`cosine` for text).",
+    "Give each index a `metadata` Zod object describing what its vectors carry, and mark the fields you will filter on with `filterable(...)` beside their `.describe()`. Vectorize allows ten metadata indexes per index, and a field indexed after vectors are written does not apply to them — decide this before you ingest.",
+    "Bind `VECTORIZE` (Vectorize) and `AI` (Workers AI) in each wrangler.jsonc env, plus the `DB` D1 binding your other capabilities use. Both are marked remote: neither has a local emulation, so `wrangler dev` reaches the real resource. A second index names its own `binding` — one Vectorize binding addresses exactly one index.",
+    "Run `pithy vector provision --env <env>` to create the index, its metadata indexes, and the prebuilt reprocess worker. It waits for each metadata index to become live: Vectorize applies them asynchronously, and a vector written before one exists is never covered by it. It then writes what it observed into wrangler.jsonc as the `VECTOR_PROVISIONED` var for that environment — commit it. The Worker checks its declared filterable fields against that record at boot and refuses to serve on a mismatch, so re-run provision whenever you change a metadata schema.",
+    "Run `pithy migrate` to create pithy_vector_documents — the durable corpus results hydrate from and re-embeds read out of.",
+    "Add `@pithy-sh/auth` if it is not already installed. Search routes scope to the authenticated caller; without auth every route is denied.",
+    "Changed a model, or added a filterable field after ingest? Run `pithy vector reprocess` — it re-embeds the rows whose model differs from config, and `--all` re-embeds the corpus. A late metadata index needs `pithy vector reset`, which rebuilds the index from that corpus."
+  ],
+  "configOptions": [
+    {
+      "key": "defaultTopK",
+      "default": 10,
+      "describe": "How many matches a query returns when the caller names none. A search page, not a scan — Vectorize's own ceiling is 50 per query when values or metadata come back, 100 when neither does. There is no `indexes` block above: `pithy add` can only seed scalar options, so add one by hand before any search works. Each index names its model, its dimensions, its metric, and the Zod object describing its metadata — mark a field `.meta({ filterable: true })` to make it filterable, then run `pithy vector provision`. Until an index is declared the routes answer `vector/index_not_found`."
+    }
+  ]
+}

package/src/capability.ts

@@ -0,0 +1,120 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { BindingSpecInput } from "@pithy-sh/core/src/capability/bindings";
+import { type Capability, defineCapability } from "@pithy-sh/core/src/capability/capability";
+import type { DatabaseSpecMap } from "@pithy-sh/core/src/data/databases";
+import type { KvNamespaceSpecMap } from "@pithy-sh/core/src/kv/namespaces";
+import { workflowBindings } from "@pithy-sh/core/src/workflow/bindings";
+import type { Migration } from "kysely/migration";
+import { VectorConfig, type VectorConfigInput } from "./config/config";
+import { vectorTables } from "./data/tables";
+import { provisionGuard } from "./http/provisionGuard";
+import { registerVectorRoutes } from "./http/routes";
+import { vector_0001_documents } from "./migrations/0001_documents";
+import { vectorExampleSeed } from "./seeds/example";
+import { PACKAGE_VERSION } from "./version.generated";
+import { vectorWorkflows } from "./workflows/specs";
+
+/**
+ * Where vector's migrations sort in the app database. Unique per database; the registry composes keys like
+ * `0900_vector_0001_documents`. Sits after storage (800).
+ */
+export const VECTOR_MIGRATION_ORDER = 900;
+
+/** The options `pithy add vector` writes into `pithy.config.ts`: the config, plus where the routes mount. */
+export type VectorOptions = VectorConfigInput & {
+  /** The path the routes mount under. Defaults to `/vector`. */
+  basePath?: string;
+};
+
+/**
+ * The vector capability, with its resolved config attached. The workflow slice is kept literal so a composed
+ * project types `c.var.workflows.trigger("vector/reprocess", …)` precisely — an unregistered key or a
+ * mistyped payload is a compile error, not a 500.
+ */
+export interface VectorCapability
+  extends Capability<DatabaseSpecMap, KvNamespaceSpecMap, "vector", typeof vectorWorkflows> {
+  /** The resolved vector config. */
+  vectorConfig: VectorConfig;
+}
+
+/**
+ * The vector capability: semantic search over the adopter's own Vectorize indexes and Workers AI embeddings.
+ *
+ * Fully optional. Config, migrations, and bindings arrive only on `pithy add vector`, and `pithy remove
+ * vector` is the clean inverse. The index is Vectorize and the embeddings are Workers AI, both in the
+ * adopter's account, reached through bindings — nothing routes through a Pithy-operated service.
+ *
+ * What this package adds over a thin wrapper is one thing: an index's filterable metadata is declared in Zod,
+ * beside the rest of its schema. That single declaration provisions the metadata indexes, types the filter
+ * builder, and is compared against the live index by `pithy vector provision` — because Vectorize does not
+ * error when you filter on a field it indexed late. It silently omits every vector written before the index
+ * existed, which is a bug with no error message and no obvious cause.
+ *
+ * That declaration is checked three times, each as early as it can be. `VectorConfig.parse` below refuses an
+ * unindexable filterable field, an eleventh one, and two indexes sharing a binding. `pithy vector provision`
+ * compares the declaration against the live index over the control plane, waits for each metadata index to
+ * become visible, and records what it saw. And {@link provisionGuard} re-checks that record at boot, so a
+ * schema edited and deployed without re-provisioning fails with `vector/metadata_index_drift` instead of
+ * quietly returning partial results. The boot check reads a var, never the network: an account API token has
+ * no business on the request path of a search.
+ *
+ * `dependsOn` is deliberately empty. Auth is a seam, not a peer: without `@pithy-sh/auth` the routes deny
+ * rather than open, which is the right failure and needs no dependency edge.
+ *
+ * The `VECTORIZE` and `AI` bindings are declared `remote` because neither has a local emulation. Without it
+ * `wrangler dev` binds nothing and every search fails locally for a reason that looks like a code fault.
+ */
+export function vector(options: VectorOptions = { indexes: {} }): VectorCapability {
+  const { basePath, ...configInput } = options;
+  // Parse the index set at assembly — an unindexable filterable field, an eleventh one, or a model/dimension
+  // mismatch fails on deploy, not on the first search.
+  const resolved = VectorConfig.parse(configInput);
+
+  const migrations: Record<string, Migration> = { "0001_documents": vector_0001_documents };
+  const requiredBindings: BindingSpecInput[] = [
+    // One Vectorize binding per configured index — a binding addresses exactly one index, so a project with
+    // two indexes needs two. Deduplicated in config order; a single-index project sees just `VECTORIZE`.
+    ...[...new Set(Object.values(resolved.indexes).map((index) => index.binding))].map((name) => ({
+      type: "vectorize" as const,
+      name,
+      remote: true,
+    })),
+    { type: "ai", name: "AI", remote: true },
+    { type: "d1", name: "DB" },
+    // The reprocess Workflow's binding, derived from the spec rather than restated. Optional: it exists only
+    // once `pithy vector provision` has deployed the vector worker, and an unprovisioned project must still
+    // boot and serve every search route.
+    ...workflowBindings(vectorWorkflows),
+  ];
+
+  const capability = defineCapability({
+    name: "vector",
+    // The package version this capability ships at, stamped by `scripts/stampVersions.ts` — a Worker
+    // cannot read its own package.json. Reported per capability by the control-plane manifest.
+    version: PACKAGE_VERSION,
+    requiredBindings,
+    config: VectorConfig,
+    workflows: vectorWorkflows,
+    databases: {
+      app: {
+        binding: "DB",
+        tables: vectorTables(),
+        migrationOrder: VECTOR_MIGRATION_ORDER,
+        migrations,
+      },
+    },
+    seeds: [vectorExampleSeed],
+    // The drift check runs as middleware because the record it reads is a var, and in Workers vars arrive
+    // per request — there is no env at assembly for a `compose` hook to read.
+    middleware: [provisionGuard(resolved)],
+    routes: registerVectorRoutes({ config: resolved, ...(basePath !== undefined ? { basePath } : {}) }),
+  });
+
+  return Object.assign(capability, { vectorConfig: resolved });
+}
+
+export function isVectorCapability(capability: Capability): capability is VectorCapability {
+  return capability.name === "vector" && "vectorConfig" in capability;
+}

package/src/cloudflare-test.d.ts

@@ -0,0 +1,12 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/// <reference types="@cloudflare/vitest-plugin/types" />
+
+// Bindings the Workers-runtime test project provides to `*.workers.test.ts`, matching the Miniflare config
+// in `vitest.workers.config.ts`: the app `DB` database the `pithy_vector_*` tables live in.
+declare namespace Cloudflare {
+  interface Env {
+    DB: D1Database;
+  }
+}

package/src/config/config.ts

@@ -0,0 +1,181 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { byteLength, DEFAULT_TOPK, MAX_DIMENSIONS, MAX_NAME_BYTES, MAX_TOPK_WITHOUT_PAYLOAD } from "../index/limits";
+import { introspectMetadata } from "../index/metadata";
+
+/**
+ * The vector capability's config — the thin, user-owned surface in `pithy.config.ts`. Every field is
+ * `.describe()`d: the descriptions feed the self-documenting CLI (CLAUDE.md §Config).
+ *
+ * An index is declared, not discovered. It names the embedding model that fills it, the vector shape that
+ * model produces, the metric to compare by, and — the part that matters — a Zod object describing the
+ * metadata its vectors carry, with the filterable fields marked. That one declaration drives four things
+ * that must never disagree: the metadata indexes `pithy vector provision` creates, the type of the filter
+ * builder, the drift check that same command runs against the live index, and the boot check the Worker runs
+ * against what that command recorded — which is how a schema edited and deployed without re-provisioning
+ * fails loudly instead of returning partial results.
+ *
+ * The model is pinned per index because an index built with one model and queried with another does not
+ * fail. It returns neighbors in a space the query vector does not live in — plausible results, quietly
+ * wrong. Dimensions and metric are fixed at index creation and cannot be changed afterwards, so they are
+ * validated here, where the fix is an edit rather than a migration.
+ */
+
+/** An index name is a path segment and a Cloudflare resource name, so it is lowercase, digits, and dashes. */
+const INDEX_NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+/** A wrangler binding name: uppercase, digits, underscores. The env key the Vectorize index arrives on. */
+const BINDING_NAME_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+
+/** The binding an index arrives on when it does not name its own. The single-index case, which is most of them. */
+export const DEFAULT_VECTORIZE_BINDING = "VECTORIZE";
+
+/** How nearest neighbors are scored. Fixed when the index is created — changing it means a new index. */
+export const VectorMetric = z
+  .enum(["cosine", "euclidean", "dot-product"])
+  .describe(
+    "How this index scores nearest neighbors. `cosine` for text embeddings (the usual choice), `euclidean` for spatial distance, `dot-product` for magnitude-sensitive scoring. Fixed at index creation.",
+  );
+export type VectorMetric = z.infer<typeof VectorMetric>;
+
+/**
+ * A metadata schema: a Zod object, not a value. It is held as a schema so this package can introspect it —
+ * one pass yields the metadata indexes to provision and the type of the filter builder.
+ */
+const MetadataObject = z
+  .custom<z.ZodObject>((value) => value instanceof z.ZodObject, {
+    message: "An index's `metadata` must be a Zod object schema — z.object({ ... }), not a value.",
+  })
+  .describe(
+    "The metadata every vector in this index carries, as a Zod object. Mark a field `.meta({ filterable: true })` — beside its `.describe()` — to make it filterable; each marked field becomes a Vectorize metadata index, and Vectorize allows ten per index.",
+  );
+
+export const VectorIndexConfig = z
+  .object({
+    model: z
+      .string()
+      .min(1)
+      .describe(
+        "The Workers AI embedding model that fills this index — `@cf/baai/bge-base-en-v1.5` and friends. Pinned per index and applied to writes *and* queries: an index built with one model and queried with another returns plausible, quietly wrong results.",
+      ),
+    dimensions: z
+      .number()
+      .int()
+      .min(1)
+      .max(MAX_DIMENSIONS)
+      .describe(
+        `How many components each vector carries. It must match the model's output — 768 for bge-base, 1024 for bge-large. Vectorize allows at most ${MAX_DIMENSIONS}, and the value is fixed at index creation.`,
+      ),
+    metric: VectorMetric.default("cosine"),
+    binding: z
+      .string()
+      .regex(BINDING_NAME_PATTERN)
+      .default(DEFAULT_VECTORIZE_BINDING)
+      .describe(
+        "The wrangler binding this index arrives on. One Vectorize binding addresses exactly one index, so a project with two indexes names two bindings — leaving both on the default would silently point one index's writes at the other's vectors.",
+      ),
+    metadata: MetadataObject.optional(),
+    namespace: z
+      .string()
+      .optional()
+      .describe(
+        "The namespace writes and queries use when a caller names none. Namespaces partition one index — a tenant, a locale, a corpus — and are cheaper than one index per partition.",
+      ),
+  })
+  .describe("One vector index: the model that fills it, the shape it holds, and the metadata it can filter on.");
+export type VectorIndexConfig = z.output<typeof VectorIndexConfig>;
+
+export const VectorConfig = z
+  .object({
+    indexes: z
+      .record(z.string(), VectorIndexConfig)
+      .prefault({})
+      .describe(
+        "Every index this app searches, keyed by a short name used in routes and in `pithy vector provision`. Indexes are config, not database rows — their shape is fixed at creation, so they belong where a change is reviewable. Defaults to none: `pithy add vector` can only seed scalar options, so the capability has to compose before an index block is hand-written, or the generated `pithy.config.ts` would fail to load and take every other `pithy` command down with it. With no index configured, the routes answer `vector/index_not_found` and the drift check has nothing to compare — which is the honest state of a capability that is installed but not yet set up.",
+      ),
+    defaultTopK: z
+      .number()
+      .int()
+      .min(1)
+      .max(MAX_TOPK_WITHOUT_PAYLOAD)
+      .default(DEFAULT_TOPK)
+      .describe(
+        "How many matches a query returns when the caller names no `topK`. A search page, not a scan. Vectorize's own ceiling is 50 per query when values or metadata come back, 100 when neither does.",
+      ),
+  })
+  .describe("Configuration for the vector capability — the set of indexes this app searches.")
+  .check((ctx) => {
+    const names = Object.keys(ctx.value.indexes);
+    const bindings = new Map<string, string>();
+
+    // No index is a legal, if inert, state — deliberately, and it is the state `pithy add vector`
+    // leaves behind. `renderRegistration` can only seed scalar config options, so the generated
+    // `pithy.config.ts` reads `vector({ defaultTopK: 10 })` with no `indexes` block; rejecting that
+    // would make the file throw on load, and `loadProject` sits under every other `pithy` command —
+    // including the `pithy migrate` that `pithy add` runs immediately afterwards. The command would
+    // break the project it was asked to set up. An unconfigured capability that answers
+    // `vector/index_not_found` is the honest intermediate state; a config that cannot be loaded is not.
+
+    for (const name of names) {
+      if (!INDEX_NAME_PATTERN.test(name)) {
+        ctx.issues.push({
+          code: "custom",
+          input: ctx.value,
+          path: ["indexes", name],
+          message: `Index name \`${name}\` must be lowercase letters, digits, and dashes — it is a Cloudflare resource name and a path segment.`,
+        });
+      }
+      if (byteLength(name) > MAX_NAME_BYTES) {
+        ctx.issues.push({
+          code: "custom",
+          input: ctx.value,
+          path: ["indexes", name],
+          message: `Index name \`${name}\` is longer than ${MAX_NAME_BYTES} bytes, which Vectorize rejects.`,
+        });
+      }
+
+      const index = ctx.value.indexes[name];
+      if (!index) continue;
+
+      // A Vectorize binding addresses one index. Two indexes sharing a binding is not a warning case:
+      // every write to one would land in the other, and nothing would error.
+      const shared = bindings.get(index.binding);
+      if (shared !== undefined) {
+        ctx.issues.push({
+          code: "custom",
+          input: ctx.value,
+          path: ["indexes", name, "binding"],
+          message: `Indexes \`${shared}\` and \`${name}\` both bind \`${index.binding}\`. One binding addresses one index — give each index its own.`,
+        });
+      } else {
+        bindings.set(index.binding, name);
+      }
+
+      if (index.namespace !== undefined && byteLength(index.namespace) > MAX_NAME_BYTES) {
+        ctx.issues.push({
+          code: "custom",
+          input: ctx.value,
+          path: ["indexes", name, "namespace"],
+          message: `Namespace \`${index.namespace}\` is longer than ${MAX_NAME_BYTES} bytes, which Vectorize rejects.`,
+        });
+      }
+
+      // Introspect here, at parse time, so an unindexable field or an eleventh filterable one fails on deploy
+      // — not at provisioning time, where the first ten indexes already exist and the eleventh is silently
+      // absent from every filter that names it.
+      if (index.metadata) {
+        for (const problem of introspectMetadata(index.metadata).problems) {
+          ctx.issues.push({ code: "custom", input: ctx.value, path: ["indexes", name, "metadata"], message: problem });
+        }
+      }
+    }
+  });
+export type VectorConfig = z.output<typeof VectorConfig>;
+export type VectorConfigInput = z.input<typeof VectorConfig>;
+
+/** The index with this name, or undefined. Names come from config, so an unknown one is a 404. */
+export function resolveIndex(config: VectorConfig, name: string): VectorIndexConfig | undefined {
+  return config.indexes[name];
+}

package/src/config/workerConfig.ts

@@ -0,0 +1,75 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { MetadataIndexDescriptor, metadataIndexes } from "../index/metadata";
+import type { VectorConfig } from "./config";
+import { VectorMetric } from "./config";
+
+/**
+ * The vector config as the prebuilt reprocess worker receives it — a **serializable projection**, not the
+ * config itself.
+ *
+ * `VectorConfig.indexes[x].metadata` holds a live `z.ZodObject`. A Zod schema is not JSON, so the media
+ * pattern of stringifying the whole config into a `vars` entry cannot be copied here: the metadata field
+ * would arrive as an unusable husk and every filter the worker compiled against it would be wrong. So the
+ * worker gets what it actually needs — the model, the vector shape, the binding, the namespace, and the
+ * *result* of introspecting the metadata schema (the filterable descriptors), which is plain data.
+ *
+ * The projection happens at provision time, on the CLI side, where the real schema exists. That means a
+ * schema change reaches the worker only on the next `pithy vector provision` — which is correct, because a
+ * new filterable field needs a metadata index provisioned before it can be filtered on anyway.
+ */
+
+/** One index as the worker sees it: everything needed to embed, write, and filter, with no Zod in sight. */
+export const VectorWorkerIndex = z
+  .object({
+    indexName: z
+      .string()
+      .min(1)
+      .describe("The provisioned Vectorize index name for this environment — what the binding addresses."),
+    binding: z.string().min(1).describe("The wrangler binding this index arrives on in the worker's env."),
+    model: z.string().min(1).describe("The Workers AI embedding model pinned to this index."),
+    dimensions: z.number().int().positive().describe("How many components each vector carries."),
+    metric: VectorMetric.describe("How this index scores nearest neighbors."),
+    namespace: z.string().optional().describe("The namespace writes and queries use when a caller names none."),
+    filterable: z
+      .array(MetadataIndexDescriptor)
+      .describe(
+        "The metadata indexes this index declares, introspected from its Zod metadata schema at provision time. Plain data, because a Zod schema cannot travel through a wrangler var.",
+      ),
+  })
+  .describe("One index as the prebuilt reprocess worker sees it — the serializable half of a VectorIndexConfig.");
+export type VectorWorkerIndex = z.infer<typeof VectorWorkerIndex>;
+
+/** The whole projection, keyed by the config's index names — the `VECTOR_CONFIG` var the worker parses. */
+export const VectorWorkerConfig = z
+  .object({
+    indexes: z
+      .record(z.string(), VectorWorkerIndex)
+      .describe("Every index the worker may reprocess, keyed by the name used in pithy.config.ts and on routes."),
+  })
+  .describe("The vector capability's config as the prebuilt reprocess worker receives it: serializable, Zod-free.");
+export type VectorWorkerConfig = z.infer<typeof VectorWorkerConfig>;
+
+/**
+ * Project a resolved config into the worker's view for one environment. `resolveIndexName` maps a config
+ * index name to its provisioned Vectorize index name, so the same projection serves every environment.
+ * Throws through {@link metadataIndexes} if a metadata schema is not provisionable — the same failure
+ * `pithy vector provision` would hit, raised before a worker is deployed against it.
+ */
+export function toWorkerConfig(config: VectorConfig, resolveIndexName: (name: string) => string): VectorWorkerConfig {
+  const indexes: Record<string, VectorWorkerIndex> = {};
+  for (const [name, index] of Object.entries(config.indexes)) {
+    indexes[name] = {
+      indexName: resolveIndexName(name),
+      binding: index.binding,
+      model: index.model,
+      dimensions: index.dimensions,
+      metric: index.metric,
+      ...(index.namespace !== undefined ? { namespace: index.namespace } : {}),
+      filterable: index.metadata ? metadataIndexes(index.metadata) : [],
+    };
+  }
+  return { indexes };
+}

package/src/data/document.ts

@@ -0,0 +1,77 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteDate, sqliteJson } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+
+/**
+ * One embedded document — the row in `pithy_vector_documents`, keyed by `(indexName, id)`.
+ *
+ * The key is composite because a Vectorize id is unique within an index, not across them: `docs` and `faqs`
+ * may each hold a document called `intro`, and they are different documents.
+ *
+ * This table earns its place three times over, and each reason is independently sufficient:
+ *
+ * 1. **Vectorize returns ids and scores, not content.** A match is `{ id, score }` — the text a user reads
+ *    has to come from somewhere, and hydrating results from this table is that somewhere.
+ * 2. **Long source text cannot live in Vectorize at all.** Metadata is capped at 10 KiB per vector, so a
+ *    document of any real length exceeds the ceiling and must be stored outside the index.
+ * 3. **Re-embedding needs a durable corpus.** Changing the model, or adding a metadata index late, invalidates
+ *    what is already in the index — and Cloudflare does not give the text back. Without this table, a
+ *    re-embed is a re-ingest, which for most adopters means it never happens.
+ *
+ * `metadata` is stored through `sqliteJson`, so it is validated on both sides and never hand-serialized.
+ * `model` records which model produced the vector, which is what makes `pithy vector reprocess` able to
+ * re-embed exactly the rows that drifted rather than the whole corpus.
+ */
+
+/** The metadata a document carries. Vectorize can only *filter* strings, numbers, and booleans; it stores more. */
+export const VectorDocumentMetadata = z
+  .record(z.string(), z.unknown())
+  .describe(
+    "The metadata this document's vector carries, as stored. Vectorize indexes only the fields marked filterable in the index's metadata schema; the rest ride along for hydration.",
+  );
+export type VectorDocumentMetadata = z.infer<typeof VectorDocumentMetadata>;
+
+export const VectorDocument = z
+  .object({
+    id: z
+      .string()
+      .describe(
+        "The document's id, which is also its Vectorize vector id — at most 64 bytes, because a longer id cannot be addressed in the index. Unique within an index, not across them: it is half of the primary key.",
+      ),
+    indexName: z
+      .string()
+      .describe(
+        "The index this document was embedded into, as named in pithy.config.ts. The other half of the primary key, so the same id in two indexes is two documents.",
+      ),
+    namespace: z.string().nullable().describe("The namespace this document belongs to, or null for the default."),
+    content: z
+      .string()
+      .nullable()
+      .describe("The source text that was embedded. Null when the adopter keeps the text elsewhere."),
+    metadata: sqliteJson(VectorDocumentMetadata).describe(
+      "The document's metadata, stored as JSON and validated on read and write.",
+    ),
+    model: z
+      .string()
+      .nullable()
+      .describe(
+        "The embedding model that produced this document's vector. `pithy vector reprocess` re-embeds exactly the rows whose model differs from config.",
+      ),
+    createdAt: SQLiteDate.describe("When the document was first embedded."),
+    updatedAt: SQLiteDate.describe("When the document was last re-embedded or its metadata changed."),
+  })
+  .describe("One embedded document — the row in `pithy_vector_documents`, keyed by `(indexName, id)`.");
+export type VectorDocument = z.output<typeof VectorDocument>;
+export type VectorDocumentRow = z.input<typeof VectorDocument>;
+
+/**
+ * The document schema with an index's own metadata shape, so a read validates the adopter's fields instead of
+ * accepting any JSON. The table is the same; only the metadata codec narrows.
+ */
+export function vectorDocumentFor<M extends z.ZodObject>(metadata: M) {
+  return VectorDocument.extend({
+    metadata: sqliteJson(metadata).describe("The document's metadata, validated against this index's schema."),
+  });
+}