@pithy-sh/vector 0.1.0

package/src/index/limits.ts

@@ -0,0 +1,89 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { NAMESPACE_LIMITS } from "@pithy-sh/core/src/naming/limits";
+
+/**
+ * Vectorize's published ceilings, in one place, verified against
+ * https://developers.cloudflare.com/vectorize/platform/limits/ and
+ * https://developers.cloudflare.com/vectorize/reference/metadata-filtering/ on 2026-07-27.
+ *
+ * They live here rather than inline at each call site for one reason: a limit that is enforced in two places
+ * eventually disagrees with itself. Every guard in this package reads a const from this file, so the number
+ * an error message quotes is the number the check used.
+ *
+ * Nothing here throws. These are values and predicates; the typed errors are raised by the module that owns
+ * the boundary (`index/index.ts` for a query or an upsert, `index/filter.ts` for a filter, `config/config.ts`
+ * for a config parse), because that module knows which `vector/*` code applies.
+ */
+
+/** Components per vector, float32. An index's `dimensions` is fixed at creation and cannot be changed. */
+export const MAX_DIMENSIONS = 1536;
+
+/**
+ * Bytes in an index name, a namespace name, or any other Vectorize identifier.
+ *
+ * The index-name half of this is the same number the naming facade holds
+ * (`NAMESPACE_LIMITS.vectorizeIndex` in `@pithy-sh/core/src/naming/limits`), so it is read from there
+ * rather than typed twice — a limit written in two files eventually disagrees with itself. The rest of
+ * Vectorize's identifiers share the ceiling but are not composed by the facade, which is why this
+ * package still owns the constant they are checked against.
+ *
+ * Vectorize also constrains the charset: `^([a-z]+[a-z0-9_-]*[a-z0-9]+)$` — an index name must **start
+ * with a letter** and end alphanumeric. Pithy's project rule already requires a letter-leading project,
+ * and every composed name leads with the project, so the two agree by construction.
+ */
+export const MAX_NAME_BYTES = NAMESPACE_LIMITS.vectorizeIndex.maxLength;
+
+/** Bytes in a vector id. A document whose id exceeds this can be stored but never addressed in the index. */
+export const MAX_VECTOR_ID_BYTES = 64;
+
+/**
+ * Bytes of metadata carried on one vector. Long source text belongs in D1, which is why this package has a table.
+ * Like the filter ceiling, the compact JSON must be **under** this — 10,240 is already too large.
+ */
+export const MAX_METADATA_BYTES = 10 * 1024;
+
+/** The filter's compact JSON must be **under** this — 2,048 is already too large, not the last accepted size. */
+export const MAX_FILTER_BYTES = 2048;
+
+/** Characters in a filter key. Vectorize states this as characters, not bytes. */
+export const MAX_FILTER_KEY_LENGTH = 512;
+
+/** Metadata indexes per index. A hard ceiling, which is what makes filterability a provisioning-time decision. */
+export const MAX_METADATA_INDEXES = 10;
+
+/** Vectors per upsert call from a Worker. The HTTP API allows 5,000; the binding does not. */
+export const MAX_UPSERT_BATCH = 1000;
+
+/** topK when a query returns values or metadata — the payload makes the response the constraint. */
+export const MAX_TOPK_WITH_PAYLOAD = 50;
+
+/** topK when a query returns neither values nor metadata. */
+export const MAX_TOPK_WITHOUT_PAYLOAD = 100;
+
+/** Matches a query returns when the caller names no `topK`. Small on purpose: a search page, not a scan. */
+export const DEFAULT_TOPK = 10;
+
+const encoder = new TextEncoder();
+
+/** Byte length of a string as UTF-8. Cloudflare states these limits in bytes, and `String.length` is not that. */
+export function byteLength(value: string): number {
+  return encoder.encode(value).length;
+}
+
+/**
+ * Why a key is unusable as a metadata filter key, or `null` when it is fine. Vectorize's rules: non-empty, no
+ * dots (reserved for nesting into sub-objects), no leading `$` (reserved for operators), at most 512
+ * characters. Returned as a message rather than thrown so a config parse can turn it into a Zod issue and a
+ * request boundary can turn it into a typed error.
+ */
+export function filterKeyProblem(key: string): string | null {
+  if (key.length === 0) return "a filter key cannot be empty";
+  if (key.startsWith("$")) return `\`${key}\` starts with $, which Vectorize reserves for operators`;
+  if (key.includes(".")) return `\`${key}\` contains a dot, which Vectorize reserves for nested fields`;
+  if (key.length > MAX_FILTER_KEY_LENGTH) {
+    return `\`${key.slice(0, 32)}…\` is longer than ${MAX_FILTER_KEY_LENGTH} characters`;
+  }
+  return null;
+}

package/src/index/metadata.ts

@@ -0,0 +1,160 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
+import { filterKeyProblem, MAX_METADATA_INDEXES } from "./limits";
+
+/**
+ * One introspection pass over an index's metadata schema, two outputs: the metadata indexes to provision, and
+ * — via `index/filter.ts` — the shape of the filters the index can answer. They come from the same source
+ * because they must agree. Cloudflare states it verbatim:
+ *
+ * > "Vectors upserted before a metadata index was created won't have their metadata contained in that index."
+ *
+ * Filtering on a field indexed late does **not** error. It silently returns partial results: every vector
+ * written before the index existed simply fails to match. Combined with a hard ceiling of ten metadata indexes
+ * per index, that makes filterability a provisioning-time decision wearing the costume of a query-time one. A
+ * thin wrapper over the binding cannot remove that footgun. Declaring it in the schema can, because then one
+ * declaration drives provisioning, the filter type, the drift check `pithy vector provision` runs against the
+ * live index, and the boot check the Worker runs against what that command recorded.
+ *
+ * The marker is Zod 4's `.meta({ filterable: true })`, beside the field's mandatory `.describe()`. `.meta()`
+ * merges rather than replaces, in either order, so a field carries both.
+ */
+
+/** The value type of an indexed metadata property. Vectorize indexes these three and nothing else. */
+export const MetadataIndexType = z
+  .enum(["string", "number", "boolean"])
+  .describe("The value type of an indexed metadata property, which decides how a filter compares against it.");
+export type MetadataIndexType = z.infer<typeof MetadataIndexType>;
+
+/** One metadata index to provision on a Vectorize index — a property name and the type it is indexed as. */
+export const MetadataIndexDescriptor = z
+  .object({
+    propertyName: z.string().min(1).describe("The metadata property this index covers, as named in the schema."),
+    indexType: MetadataIndexType.describe("How Vectorize stores and compares this property's values."),
+  })
+  .describe("One metadata index derived from a field marked filterable in an index's metadata schema.");
+export type MetadataIndexDescriptor = z.infer<typeof MetadataIndexDescriptor>;
+
+/** The result of one introspection pass: what to provision, and every reason the schema is not provisionable. */
+export interface MetadataIntrospection {
+  /** The metadata indexes, in declaration order. Empty when nothing is marked filterable. */
+  indexes: MetadataIndexDescriptor[];
+  /** Human-readable reasons the schema cannot be honored. Empty means the schema is good. */
+  problems: string[];
+}
+
+/** Strip `.optional()`, `.nullable()`, `.default()` and friends down to the type that carries the value. */
+function unwrap(schema: z.ZodType): z.ZodType {
+  let current: z.ZodType = schema;
+  for (;;) {
+    const inner = (current as unknown as { def?: { innerType?: z.ZodType } }).def?.innerType;
+    if (!inner) return current;
+    current = inner;
+  }
+}
+
+/**
+ * Whether a field is marked filterable. The marker is read at every level of the wrapper chain, so
+ * `z.string().meta({ filterable: true }).optional()` counts — the wrapper is a different schema object and
+ * carries no metadata of its own, and a reader who wrapped a marked field plainly meant to keep the mark.
+ */
+export function isFilterable(schema: z.ZodType): boolean {
+  let current: z.ZodType | undefined = schema;
+  while (current) {
+    const meta = current.meta() as { filterable?: unknown } | undefined;
+    if (meta?.filterable === true) return true;
+    current = (current as unknown as { def?: { innerType?: z.ZodType } }).def?.innerType;
+  }
+  return false;
+}
+
+/** The type of every value a `z.enum`/`z.literal` admits, or null when they are not all one indexable type. */
+function uniformPrimitiveType(values: readonly unknown[]): MetadataIndexType | null {
+  if (values.length === 0) return null;
+  const first = typeof values[0];
+  if (first !== "string" && first !== "number" && first !== "boolean") return null;
+  return values.every((value) => typeof value === first) ? first : null;
+}
+
+/** The metadata index type a field maps to, or null when Vectorize cannot index it. */
+function indexTypeOf(schema: z.ZodType): MetadataIndexType | null {
+  const base = unwrap(schema);
+  const def = (base as unknown as { def: { type: string; entries?: Record<string, unknown>; values?: unknown[] } }).def;
+  switch (def.type) {
+    case "string":
+      return "string";
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    // An enum or a literal is a constrained primitive; index it as whatever primitive it constrains, so a
+    // status field declared as an enum is filterable without restating it as a bare string.
+    case "enum":
+      return uniformPrimitiveType(Object.values(def.entries ?? {}));
+    case "literal":
+      return uniformPrimitiveType(def.values ?? []);
+    default:
+      return null;
+  }
+}
+
+/**
+ * Introspect an index's metadata schema. Never throws — it returns every problem it found, so a config parse
+ * can report them all as Zod issues at once instead of failing on the first.
+ */
+export function introspectMetadata(metadata: z.ZodObject): MetadataIntrospection {
+  const indexes: MetadataIndexDescriptor[] = [];
+  const problems: string[] = [];
+
+  for (const [propertyName, field] of Object.entries(metadata.shape)) {
+    const schema = field as z.ZodType;
+    if (!isFilterable(schema)) continue;
+
+    const keyProblem = filterKeyProblem(propertyName);
+    if (keyProblem) {
+      problems.push(`Metadata field ${keyProblem}.`);
+      continue;
+    }
+
+    const indexType = indexTypeOf(schema);
+    if (!indexType) {
+      problems.push(
+        `Metadata field \`${propertyName}\` is marked filterable but Vectorize cannot index its type. Only strings, numbers, and booleans are indexable.`,
+      );
+      continue;
+    }
+
+    indexes.push({ propertyName, indexType });
+  }
+
+  // The eleventh filterable field fails here, at assembly, rather than at provisioning time — where Vectorize
+  // would reject it after the first ten already exist, leaving the index half-configured and every filter on
+  // the rejected field silently partial.
+  if (indexes.length > MAX_METADATA_INDEXES) {
+    problems.push(
+      `${indexes.length} fields are marked filterable; Vectorize allows ${MAX_METADATA_INDEXES} metadata indexes per index. Drop ${indexes.length - MAX_METADATA_INDEXES}: ${indexes.map((index) => index.propertyName).join(", ")}.`,
+    );
+  }
+
+  return { indexes, problems };
+}
+
+/**
+ * The metadata indexes an index's schema declares. Throws on any problem — this is the form provisioning and
+ * the drift check call, where a half-usable answer is worse than none.
+ */
+export function metadataIndexes(metadata: z.ZodObject): MetadataIndexDescriptor[] {
+  const { indexes, problems } = introspectMetadata(metadata);
+  if (problems.length > 0) {
+    throw new ValidationError({
+      message: "This index's metadata schema cannot be provisioned.",
+      action: "Fix the fields marked filterable in the index's metadata schema, then run `pithy vector provision`.",
+      detail: problems.join(" "),
+      issues: problems.map((problem) => ({ path: ["metadata"], message: problem, code: "custom" })),
+    });
+  }
+  return indexes;
+}

package/src/index/provisioned.ts

@@ -0,0 +1,183 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import type { VectorConfig } from "../config/config";
+import { VectorMetadataIndexDriftError } from "../error/errors";
+import { compareMetadataIndexes } from "./drift";
+import { type MetadataIndexDescriptor, metadataIndexes } from "./metadata";
+
+/**
+ * The provisioning record — what `pithy vector provision` observed on the live indexes — and the boot check
+ * that reads it.
+ *
+ * The failure being guarded is the one Vectorize refuses to report. Someone marks a metadata field
+ * `filterable`, deploys, and never re-runs provision. Every query filtering on that field returns a short,
+ * plausible result set, because Cloudflare states it verbatim: *"Vectors upserted before a metadata index was
+ * created won't have their metadata contained in that index."* Nothing errors. The bug surfaces weeks later
+ * as "search feels wrong". A startup error costs one deploy; that costs trust.
+ *
+ * **Why a record and not a live call.** Reading an index's metadata indexes is a Cloudflare control-plane
+ * call, authorized only by an account API token. Doing it at boot would put a control-plane token on the
+ * request path of every search — a strictly worse trade than the bug it catches. So the token stays where it
+ * already is: `pithy vector provision` holds it, already compares declared against live, and now **writes
+ * down what it saw** as one Zod-validated JSON var ({@link VECTOR_PROVISIONED_VAR}) — the same way
+ * `MEDIA_CONFIG` and `EMAIL_THEME` carry structured config into a prebuilt worker. The Worker compares its
+ * declared filterable set against that record with no network at all.
+ *
+ * **Be honest about what this proves.** It proves the config declares nothing that provisioning did not
+ * observe *the last time it ran*. It does not prove anything about Cloudflare right now: someone who deletes
+ * a metadata index from the dashboard leaves the record stale and this check silent. What it catches is the
+ * common, silent case — a schema edited and deployed without re-provisioning — because the record only ever
+ * changes when provision runs.
+ *
+ * **An absent record fails, but only when something is declared filterable.** The two cases are not the same
+ * project. A project with no filterable field has nothing that can drift, so it boots — an adopter who has
+ * added vector but not provisioned yet still serves every other route. A project that *declares* filterable
+ * fields with no record has provably never provisioned, which means the index does not exist either and every
+ * filtered search is already wrong. Booting it would serve exactly the silently-partial results this package
+ * exists to prevent, so it fails and names the command. Running `pithy vector provision` is the whole fix.
+ *
+ * A live metadata index the config does not declare is **not** fatal here either. It may predate the config
+ * or belong to another consumer of the same index, and refusing to boot over a leftover would be hostile. It
+ * costs one of the ten slots, and `pithy vector provision` is where it gets reported.
+ */
+
+/**
+ * The wrangler var the record travels in. Written per environment by `pithy vector provision`, read off the
+ * Worker's env at boot. A var, not a binding: it is plain data, and it must be diffable in `wrangler.jsonc`.
+ */
+export const VECTOR_PROVISIONED_VAR = "VECTOR_PROVISIONED";
+
+/** One metadata index as provisioning found it on the live Vectorize index. */
+export const ObservedMetadataIndex = z
+  .object({
+    propertyName: z.string().min(1).describe("The metadata property the live index covers."),
+    indexType: z
+      .string()
+      .min(1)
+      .describe(
+        "The type Vectorize reports the index was created with, recorded verbatim rather than narrowed to the three types this package can declare — a record of an observation must round-trip whatever was observed, including a type only Cloudflare knows about.",
+      ),
+  })
+  .describe("One metadata index `pithy vector provision` observed on a live Vectorize index.");
+export type ObservedMetadataIndex = z.infer<typeof ObservedMetadataIndex>;
+
+/** One configured index as provisioning left it: the Vectorize name, and every metadata index it then had. */
+export const ProvisionedIndex = z
+  .object({
+    indexName: z.string().min(1).describe("The Vectorize index name this configured index was provisioned as."),
+    metadataIndexes: z
+      .array(ObservedMetadataIndex)
+      .describe(
+        "Every metadata index live on that index when provisioning finished — the declared ones, each waited for until Cloudflare showed it, plus any the config does not declare.",
+      ),
+  })
+  .describe("What `pithy vector provision` last observed for one configured index.");
+export type ProvisionedIndex = z.infer<typeof ProvisionedIndex>;
+
+/** The whole record, keyed by the config's index names. The value of the `VECTOR_PROVISIONED` var. */
+export const VectorProvisionRecord = z
+  .object({
+    indexes: z
+      .record(z.string(), ProvisionedIndex)
+      .describe("Each configured index, keyed by the name used in pithy.config.ts, as provisioning last saw it."),
+  })
+  .describe("What `pithy vector provision` observed, carried into the Worker so boot can check drift offline.");
+export type VectorProvisionRecord = z.infer<typeof VectorProvisionRecord>;
+
+/**
+ * Read the record off a Worker env. Absent or blank returns `undefined` — the caller decides what absence
+ * means. Present but unreadable **throws**: a record that cannot be parsed cannot be compared against, and
+ * treating it as absence would silently downgrade a corrupted record into "never provisioned".
+ */
+export function readProvisionRecord(env: Record<string, unknown>): VectorProvisionRecord | undefined {
+  const raw = env[VECTOR_PROVISIONED_VAR];
+  if (typeof raw !== "string" || raw.trim() === "") return undefined;
+
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(raw);
+  } catch (cause) {
+    throw new VectorMetadataIndexDriftError(
+      {
+        message: `The ${VECTOR_PROVISIONED_VAR} var is not valid JSON, so the metadata indexes cannot be checked.`,
+        action: `Run \`pithy vector provision --env <env>\` to rewrite ${VECTOR_PROVISIONED_VAR}, then redeploy.`,
+        detail: cause instanceof Error ? cause.message : String(cause),
+      },
+      { cause },
+    );
+  }
+
+  const parsed = VectorProvisionRecord.safeParse(decoded);
+  if (!parsed.success) {
+    throw new VectorMetadataIndexDriftError({
+      message: `The ${VECTOR_PROVISIONED_VAR} var is not a provisioning record, so the metadata indexes cannot be checked.`,
+      action: `Run \`pithy vector provision --env <env>\` to rewrite ${VECTOR_PROVISIONED_VAR}, then redeploy.`,
+      detail: parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; "),
+    });
+  }
+  return parsed.data;
+}
+
+/** Every configured index that declares at least one filterable field, with the descriptors it declares. */
+function declaredFilterable(config: VectorConfig): Map<string, MetadataIndexDescriptor[]> {
+  const declared = new Map<string, MetadataIndexDescriptor[]>();
+  for (const [name, index] of Object.entries(config.indexes)) {
+    const fields = index.metadata ? metadataIndexes(index.metadata) : [];
+    if (fields.length > 0) declared.set(name, fields);
+  }
+  return declared;
+}
+
+/**
+ * Refuse to boot when the config declares a filterable field that provisioning never observed, or observed
+ * as a different type. Pure — no network, no token, one comparison of two plain lists.
+ *
+ * The field names ride in the public `message` rather than in `detail`, for the reason core's
+ * `validateBindings` gives for doing the same: they are config keys, not secrets, and this surfaces at
+ * startup, where the reader is the operator staring at a 500 and needs to be told which field and which
+ * command. `detail` carries the same facts for the log.
+ */
+export function assertProvisionedMetadataIndexes(
+  config: VectorConfig,
+  record: VectorProvisionRecord | undefined,
+): void {
+  const declared = declaredFilterable(config);
+  if (declared.size === 0) return;
+
+  if (!record) {
+    const fields = [...declared].flatMap(([name, descriptors]) =>
+      descriptors.map((descriptor) => `${name}.${descriptor.propertyName}`),
+    );
+    throw new VectorMetadataIndexDriftError({
+      message: `No metadata index has been provisioned for ${fields.join(", ")}, so every filter naming one returns partial results.`,
+      action: "Run `pithy vector provision --env <env>`, then redeploy. Re-embed anything written before it.",
+      detail: `no ${VECTOR_PROVISIONED_VAR} var on env; declared filterable: ${fields.join(", ")}`,
+    });
+  }
+
+  const missing: string[] = [];
+  const mismatched: string[] = [];
+  for (const [name, descriptors] of declared) {
+    // An index absent from the record has no observed metadata indexes at all, which the comparison already
+    // reports as every declared field missing — no separate branch, no separate message to keep in step.
+    const report = compareMetadataIndexes(descriptors, record.indexes[name]?.metadataIndexes ?? []);
+    for (const entry of report.missing) missing.push(`${name}.${entry.propertyName} (${entry.indexType})`);
+    for (const entry of report.mismatched) {
+      mismatched.push(`${name}.${entry.propertyName} (declared ${entry.declared}, indexed as ${entry.live})`);
+    }
+  }
+  if (missing.length === 0 && mismatched.length === 0) return;
+
+  const problems = [
+    missing.length > 0 ? `missing: ${missing.join(", ")}` : "",
+    mismatched.length > 0 ? `mismatched: ${mismatched.join(", ")}` : "",
+  ].filter(Boolean);
+  throw new VectorMetadataIndexDriftError({
+    message: `Search is not configured correctly — ${problems.join("; ")}.`,
+    action:
+      "Run `pithy vector provision --env <env>` to create the missing metadata indexes, then redeploy and re-embed. A mis-typed index is fixed only by `pithy vector reset`, which rebuilds the index from the corpus.",
+    detail: `${problems.join("; ")}; checked against what \`pithy vector provision\` last observed, not against Cloudflare now`,
+  });
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The package entrypoint — the surface `pithy add vector` wires into `pithy.config.ts`. Deliberately narrow:
+ * the capability factory, its config types, the `filterable` marker an adopter puts on a metadata field, and
+ * the typed filter builder. Every other module is imported by deep path (`@pithy-sh/vector/src/...`); this is
+ * the documented contract, not a barrel over the package.
+ */
+
+export {
+  isVectorCapability,
+  VECTOR_MIGRATION_ORDER,
+  type VectorCapability,
+  type VectorOptions,
+  vector,
+} from "./capability";
+export {
+  DEFAULT_VECTORIZE_BINDING,
+  resolveIndex,
+  VectorConfig,
+  type VectorConfigInput,
+  VectorIndexConfig,
+  VectorMetric,
+} from "./config/config";
+export { VectorDocument, type VectorDocumentRow } from "./data/document";
+export { filterable, type VectorFilter, vectorFilter } from "./index/filter";
+export { type MetadataIndexDescriptor, metadataIndexes } from "./index/metadata";
+export { vectorExampleSeed } from "./seeds/example";
+export { VECTOR_CAPABILITY, VectorReprocessParams, vectorWorkflows } from "./workflows/specs";

package/src/migrations/0001_documents.ts

@@ -0,0 +1,63 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { type Kysely, sql } from "kysely";
+import type { Migration } from "kysely/migration";
+
+/**
+ * The document corpus: the durable text and metadata behind every vector in every index.
+ *
+ * camelCase identifiers; `CamelCasePlugin` snake-cases them in the DDL. `down` is the tested inverse.
+ *
+ * Two details are load-bearing. The primary key is **`(indexName, id)`** — text, adopter-supplied, never
+ * autoincremented — because the only join between a match and its content is that id, and a second surrogate
+ * key would be a second thing to keep in sync. It is composite rather than `id` alone because a vector id is
+ * unique *within* a Vectorize index, not across them: two indexes may each hold a document called `intro`,
+ * and keying on `id` alone would let a write to one silently overwrite the other's content, metadata, and
+ * index. The `CHECK` constraint enforces Vectorize's 64-byte id ceiling in SQLite itself, measured on the id
+ * cast to a blob so it counts bytes rather than characters: a row whose id the index cannot address is a row
+ * that can be written but never searched, and catching that at insert is far cheaper than discovering it as a
+ * permanently missing search result.
+ *
+ * Two indexes, each for a real read. `(indexName, namespace, id)` is hydration and listing — the path every
+ * search result takes. `(indexName, model)` is `pithy vector reprocess`, which scans for rows whose model
+ * differs from the configured one; without it that scan is a full table read of the corpus.
+ */
+export const vector_0001_documents: Migration = {
+  up: async (db: Kysely<unknown>): Promise<void> => {
+    await db.schema
+      .createTable("pithyVectorDocuments")
+      .addColumn("id", "text", (c) => c.notNull())
+      .addColumn("indexName", "text", (c) => c.notNull())
+      .addColumn("namespace", "text")
+      .addColumn("content", "text")
+      .addColumn("metadata", "text", (c) => c.notNull().defaultTo("{}"))
+      .addColumn("model", "text")
+      .addColumn("createdAt", "integer", (c) => c.notNull())
+      .addColumn("updatedAt", "integer", (c) => c.notNull())
+      // An id is unique within one Vectorize index, never across them. Two indexes may each hold `intro`.
+      .addPrimaryKeyConstraint("pithyVectorDocumentsPk", ["indexName", "id"])
+      // Vectorize caps a vector id at 64 bytes. CAST to blob so length() counts bytes, not characters.
+      .addCheckConstraint("pithyVectorDocumentsIdLength", sql`length(cast(id as blob)) <= 64`)
+      .execute();
+
+    // Hydration and listing: a search returns ids, and this is the read that turns them back into documents.
+    await db.schema
+      .createIndex("pithyVectorDocumentsIndexIdx")
+      .on("pithyVectorDocuments")
+      .columns(["indexName", "namespace", "id"])
+      .execute();
+
+    // Re-embedding: `pithy vector reprocess` selects the rows whose model differs from the configured one.
+    await db.schema
+      .createIndex("pithyVectorDocumentsModelIdx")
+      .on("pithyVectorDocuments")
+      .columns(["indexName", "model"])
+      .execute();
+  },
+  down: async (db: Kysely<unknown>): Promise<void> => {
+    await db.schema.dropIndex("pithyVectorDocumentsModelIdx").execute();
+    await db.schema.dropIndex("pithyVectorDocumentsIndexIdx").execute();
+    await db.schema.dropTable("pithyVectorDocuments").execute();
+  },
+};