@pithy-sh/vector 0.1.0

package/src/index/drift.ts

@@ -0,0 +1,119 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { VectorMetadataIndexDriftError } from "../error/errors";
+import type { MetadataIndexDescriptor, MetadataIndexType } from "./metadata";
+
+/**
+ * The check that a declared filterable field actually has a live metadata index.
+ *
+ * A declared-but-missing metadata index is **fatal**. Failing loudly is deliberate, and the alternative is
+ * worse than it looks. Auto-create-and-warn produces two things: a warning in a log nobody reads, and a search
+ * that returns partial results for every vector written before the index existed — because Cloudflare states,
+ * verbatim, *"Vectors upserted before a metadata index was created won't have their metadata contained in that
+ * index."* Nothing errors. The filter just quietly stops matching most of the corpus, and the bug surfaces
+ * weeks later as "search feels wrong", which is close to untraceable.
+ *
+ * **The live comparison runs where the control plane is reachable, which is the CLI — not inside the
+ * Worker.** `listMetadataIndexes` is a Cloudflare REST call, and the only credential that authorizes it is an
+ * account API token. Handing a Worker one so it could self-check at boot would put a control-plane token on
+ * the request path of every search, which is a far worse trade than the bug it would catch. So the live
+ * comparison happens in `pithy vector provision`, which already holds the token.
+ * {@link assertMetadataIndexes} is the strict form of it, for a caller that wants drift to be an error rather
+ * than a report.
+ *
+ * The Worker still checks — it just checks offline. Provisioning writes down what it observed, and
+ * `index/provisioned.ts` compares the config's declarations against that record at boot, reusing
+ * {@link compareMetadataIndexes} so both halves apply one rule. That check proves the config declares nothing
+ * provisioning did not see *the last time it ran*; it does not prove anything about Cloudflare right now. It
+ * catches the case that actually happens: a metadata schema edited and deployed without re-provisioning.
+ *
+ * A live index the config does not declare is **not** fatal. It may predate the config, or belong to another
+ * consumer of the same Vectorize index, and deleting it is destructive; it is reported so `pithy vector
+ * provision` can surface it, because it still spends one of the ten slots.
+ */
+
+/** A metadata index whose live type does not match the type the schema declares. */
+export interface MetadataIndexMismatch {
+  /** The metadata property. */
+  propertyName: string;
+  /** The type the config's metadata schema declares. */
+  declared: MetadataIndexType;
+  /** The type the live index was created with. */
+  live: string;
+}
+
+/** What one comparison of declared against live metadata indexes found. */
+export interface MetadataIndexReport {
+  /** Declared filterable, with no live metadata index. Fatal: filters on these silently return partial results. */
+  missing: MetadataIndexDescriptor[];
+  /** Declared and live, but indexed as a different type. Fatal: comparisons against the wrong type never match. */
+  mismatched: MetadataIndexMismatch[];
+  /** Live, but not declared. Not fatal — but it still spends one of the ten metadata-index slots. */
+  extra: { propertyName: string; indexType: string }[];
+}
+
+/** The subset of the Vectorize control plane this check reads. Structural, so a test injects a fake. */
+export interface MetadataIndexSource {
+  /** The metadata indexes that exist on an index right now. */
+  listMetadataIndexes(indexName: string): Promise<{ propertyName: string; indexType: string }[]>;
+}
+
+/** Compare what the schema declares against what the index has. Pure — no network, so it is trivially tested. */
+export function compareMetadataIndexes(
+  declared: readonly MetadataIndexDescriptor[],
+  live: readonly { propertyName: string; indexType: string }[],
+): MetadataIndexReport {
+  const liveByName = new Map(live.map((index) => [index.propertyName, index]));
+  const declaredNames = new Set(declared.map((index) => index.propertyName));
+
+  const missing: MetadataIndexDescriptor[] = [];
+  const mismatched: MetadataIndexMismatch[] = [];
+  for (const index of declared) {
+    const match = liveByName.get(index.propertyName);
+    if (!match) {
+      missing.push(index);
+      continue;
+    }
+    if (match.indexType !== index.indexType) {
+      mismatched.push({ propertyName: index.propertyName, declared: index.indexType, live: match.indexType });
+    }
+  }
+
+  const extra = live.filter((index) => !declaredNames.has(index.propertyName)).map((index) => ({ ...index }));
+  return { missing, mismatched, extra };
+}
+
+/**
+ * Fetch the live metadata indexes and refuse to continue if any declared one is missing or mis-typed. Returns
+ * the full report so a caller — `pithy vector doctor`, provisioning — can also surface the undeclared ones.
+ *
+ * Takes a {@link MetadataIndexSource} rather than reaching for one, because the only thing that can implement
+ * it is a control-plane client holding an API token. That is the CLI, never the Worker.
+ */
+export async function assertMetadataIndexes(
+  source: MetadataIndexSource,
+  indexName: string,
+  declared: readonly MetadataIndexDescriptor[],
+): Promise<MetadataIndexReport> {
+  const report = compareMetadataIndexes(declared, await source.listMetadataIndexes(indexName));
+
+  if (report.missing.length > 0 || report.mismatched.length > 0) {
+    const missing = report.missing.map((index) => `${index.propertyName} (${index.indexType})`);
+    const mismatched = report.mismatched.map(
+      (index) => `${index.propertyName} (declared ${index.declared}, indexed as ${index.live})`,
+    );
+    throw new VectorMetadataIndexDriftError({
+      message: `Search on \`${indexName}\` is not configured correctly.`,
+      action: `Run \`pithy vector provision\` to create the missing metadata indexes on \`${indexName}\`, then re-embed — Vectorize does not index vectors written before an index existed.`,
+      detail: [
+        missing.length > 0 ? `missing: ${missing.join(", ")}` : "",
+        mismatched.length > 0 ? `mismatched: ${mismatched.join(", ")}` : "",
+      ]
+        .filter(Boolean)
+        .join("; "),
+    });
+  }
+
+  return report;
+}

package/src/index/filter.ts

@@ -0,0 +1,278 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import type { z } from "zod";
+import { VectorFilterTooLargeError, VectorUnfilterableFieldError } from "../error/errors";
+import { byteLength, filterKeyProblem, MAX_FILTER_BYTES } from "./limits";
+import { introspectMetadata, type MetadataIndexDescriptor } from "./metadata";
+
+/**
+ * The typed metadata filter builder.
+ *
+ * Filtering an unindexed field is the failure this package exists to prevent, and it is invisible at runtime:
+ * Vectorize accepts the filter and returns a short, plausible result set. So the guard is layered. A filter
+ * naming a field that is not marked filterable is a **compile-time type error** for a caller who marked the
+ * field with {@link filterable}; `vector/unfilterable_field` is the runtime guard behind it, for a caller
+ * arriving through an untyped boundary — an HTTP body, a job payload, JavaScript.
+ *
+ * `.meta({ filterable: true })` is the runtime marker: it drives provisioning and the drift check. The type
+ * system cannot see it — `.meta()` returns the same type it was called on — so {@link filterable} sets the
+ * same marker *and* brands the field's type. Mark fields with it and the builder types itself. Mark them with
+ * a bare `.meta({ filterable: true })` and everything still provisions and still filters; only the
+ * compile-time narrowing is lost.
+ */
+
+/** A metadata value Vectorize can filter on. Nested objects and arrays are not filterable. */
+export type FilterPrimitive = string | number | boolean;
+
+/** The comparison operators Vectorize's metadata filtering accepts. */
+export interface FilterComparison<V extends FilterPrimitive> {
+  /** Equal to. */
+  $eq?: V;
+  /** Not equal to. */
+  $ne?: V;
+  /** In this set. */
+  $in?: readonly V[];
+  /** Not in this set. */
+  $nin?: readonly V[];
+  /** Strictly less than. */
+  $lt?: V;
+  /** Less than or equal to. */
+  $lte?: V;
+  /** Strictly greater than. */
+  $gt?: V;
+  /** Greater than or equal to. */
+  $gte?: V;
+}
+
+const OPERATORS = ["$eq", "$ne", "$in", "$nin", "$lt", "$lte", "$gt", "$gte"] as const;
+const SET_OPERATORS: readonly string[] = ["$in", "$nin"];
+
+/** The brand {@link filterable} stamps on a field's type. Type-level only — it never exists at runtime. */
+declare const filterableBrand: unique symbol;
+
+/** A metadata field marked filterable: the same schema, carrying a type-level mark the builder can read. */
+export type Filterable<T extends z.ZodType> = T & { readonly [filterableBrand]: true };
+
+/**
+ * Mark a metadata field filterable. Sets `.meta({ filterable: true })` — the marker provisioning and drift
+ * both read — and brands the type so {@link vectorFilter} accepts this field and rejects the others.
+ */
+export function filterable<T extends z.ZodType>(schema: T): Filterable<T> {
+  return schema.meta({ filterable: true }) as Filterable<T>;
+}
+
+/** The keys of a metadata schema that were marked with {@link filterable}. */
+export type FilterableKeys<S extends z.ZodObject> = {
+  [K in keyof S["shape"]]: S["shape"][K] extends { readonly [filterableBrand]: true } ? K : never;
+}[keyof S["shape"]];
+
+/** A field's filterable value type, or `never` when it decodes to something Vectorize cannot compare. */
+type FilterValueOf<S extends z.ZodObject, K extends keyof S["shape"]> =
+  NonNullable<z.output<S["shape"][K]>> extends infer V ? (V extends FilterPrimitive ? V : never) : never;
+
+/**
+ * A filter over a metadata schema's filterable fields. A bare value is `$eq` — Vectorize's own shorthand —
+ * and an operator object is the long form.
+ */
+export type VectorFilter<S extends z.ZodObject> = {
+  [K in FilterableKeys<S> & string]?: FilterValueOf<S, K> | FilterComparison<FilterValueOf<S, K>>;
+};
+
+/** The compiled filter: the plain object handed to Vectorize's `query`. */
+export type CompiledFilter = Record<string, unknown>;
+
+function isPrimitive(value: unknown): value is FilterPrimitive {
+  return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+
+/** Whether a value matches the type the property was indexed as. A mismatch never matches anything. */
+function matchesIndexType(value: unknown, indexType: MetadataIndexDescriptor["indexType"]): boolean {
+  if (value === null) return true;
+  return typeof value === indexType;
+}
+
+function assertValueType(key: string, operator: string, value: unknown, descriptor: MetadataIndexDescriptor): void {
+  if (SET_OPERATORS.includes(operator)) {
+    if (!Array.isArray(value) || value.length === 0) {
+      throw new ValidationError({
+        message: `\`${operator}\` needs a non-empty list of values.`,
+        action: "Pass an array of values to compare against.",
+        detail: `filter key '${key}' operator '${operator}' received ${JSON.stringify(value)}`,
+      });
+    }
+    for (const entry of value) {
+      if (!matchesIndexType(entry, descriptor.indexType)) {
+        throw new ValidationError({
+          message: `\`${key}\` is indexed as ${descriptor.indexType}; compare it against ${descriptor.indexType} values.`,
+          action: "Match the filter's value type to the field's type in the index's metadata schema.",
+          detail: `filter key '${key}' operator '${operator}' received ${JSON.stringify(entry)}`,
+        });
+      }
+    }
+    return;
+  }
+  if (!matchesIndexType(value, descriptor.indexType)) {
+    throw new ValidationError({
+      message: `\`${key}\` is indexed as ${descriptor.indexType}; compare it against ${descriptor.indexType} values.`,
+      action: "Match the filter's value type to the field's type in the index's metadata schema.",
+      detail: `filter key '${key}' operator '${operator}' received ${JSON.stringify(value)}`,
+    });
+  }
+}
+
+/**
+ * Validate an untyped filter against the metadata indexes an index actually has, and return the object to
+ * hand Vectorize. This is the runtime half of the guard: every key must be indexed, every operator must be one
+ * Vectorize knows, every value must match the property's index type, and the compact JSON must stay under
+ * 2,048 bytes.
+ */
+export function compileFilter(descriptors: readonly MetadataIndexDescriptor[], filter: CompiledFilter): CompiledFilter {
+  const byName = new Map(descriptors.map((descriptor) => [descriptor.propertyName, descriptor]));
+  const compiled: CompiledFilter = {};
+
+  for (const [key, condition] of Object.entries(filter)) {
+    if (condition === undefined) continue;
+
+    const keyProblem = filterKeyProblem(key);
+    if (keyProblem) {
+      throw new ValidationError({
+        message: "That filter key is not usable.",
+        action: "Filter keys are non-empty, carry no dots, do not start with $, and stay under 512 characters.",
+        detail: `filter key ${keyProblem}`,
+      });
+    }
+
+    const descriptor = byName.get(key);
+    if (!descriptor) {
+      throw new VectorUnfilterableFieldError({
+        detail: `no metadata index for '${key}'; indexed: ${descriptors.map((d) => d.propertyName).join(", ") || "none"}`,
+      });
+    }
+
+    if (isPrimitive(condition) || condition === null) {
+      // Vectorize's shorthand: a bare value means $eq. Expanded here so one compiled shape reaches the wire.
+      assertValueType(key, "$eq", condition, descriptor);
+      compiled[key] = { $eq: condition };
+      continue;
+    }
+
+    if (typeof condition !== "object") {
+      throw new ValidationError({
+        message: `\`${key}\` needs a value or a comparison.`,
+        action: "Pass a value, or an object of operators such as { $in: [...] }.",
+        detail: `filter key '${key}' received ${typeof condition}`,
+      });
+    }
+
+    const operators: Record<string, unknown> = {};
+    for (const [operator, value] of Object.entries(condition as Record<string, unknown>)) {
+      if (value === undefined) continue;
+      if (!OPERATORS.includes(operator as (typeof OPERATORS)[number])) {
+        throw new ValidationError({
+          message: `\`${operator}\` is not a filter operator.`,
+          action: `Use one of ${OPERATORS.join(", ")}.`,
+          detail: `filter key '${key}' used operator '${operator}'`,
+        });
+      }
+      assertValueType(key, operator, value, descriptor);
+      operators[operator] = value;
+    }
+
+    if (Object.keys(operators).length === 0) {
+      throw new ValidationError({
+        message: `\`${key}\` has no comparison.`,
+        action: `Give it a value, or one of ${OPERATORS.join(", ")}.`,
+        detail: `filter key '${key}' compiled to an empty comparison`,
+      });
+    }
+    compiled[key] = operators;
+  }
+
+  assertFilterSize(compiled);
+  return compiled;
+}
+
+/**
+ * Reject a filter whose compact JSON reaches Vectorize's ceiling. Checked here, before the call, because
+ * Vectorize's own rejection arrives as an opaque error with no indication which filter was at fault.
+ */
+export function assertFilterSize(filter: CompiledFilter): void {
+  const size = byteLength(JSON.stringify(filter));
+  if (size >= MAX_FILTER_BYTES) {
+    throw new VectorFilterTooLargeError({
+      detail: `filter JSON is ${size} bytes; the limit is under ${MAX_FILTER_BYTES}`,
+    });
+  }
+}
+
+/**
+ * Evaluate a compiled filter against one document's metadata, in memory.
+ *
+ * Vectorize evaluates filters inside the index; this evaluates the same filter against a D1 row. It exists
+ * for `pithy vector reprocess --filter`, which selects rows out of the document corpus rather than out of the
+ * index. Metadata lives in a JSON column, so no SQL predicate can answer it without hand-written extraction
+ * — and re-embedding one document costs orders of magnitude more than reading it, so scanning a page and
+ * filtering it here is not the expensive half.
+ *
+ * The semantics are Vectorize's: an absent property matches only `$ne`/`$nin`, and every named property must
+ * match (implicit AND). Pass a filter that {@link compileFilter} produced, so every condition is already in
+ * operator form.
+ */
+export function matchesCompiledFilter(metadata: Record<string, unknown>, filter: CompiledFilter): boolean {
+  for (const [key, condition] of Object.entries(filter)) {
+    const value = metadata[key];
+    const operators = condition as Record<string, unknown>;
+    for (const [operator, operand] of Object.entries(operators)) {
+      if (!compare(value, operator, operand)) return false;
+    }
+  }
+  return true;
+}
+
+/** One operator against one value. An absent value matches only the negative operators, as Vectorize does. */
+function compare(value: unknown, operator: string, operand: unknown): boolean {
+  switch (operator) {
+    case "$eq":
+      return value === operand;
+    case "$ne":
+      return value !== operand;
+    case "$in":
+      return Array.isArray(operand) && operand.includes(value);
+    case "$nin":
+      return Array.isArray(operand) && !operand.includes(value);
+    case "$lt":
+      return ordered(value, operand, (a, b) => a < b);
+    case "$lte":
+      return ordered(value, operand, (a, b) => a <= b);
+    case "$gt":
+      return ordered(value, operand, (a, b) => a > b);
+    case "$gte":
+      return ordered(value, operand, (a, b) => a >= b);
+    default:
+      return false;
+  }
+}
+
+/**
+ * Apply an ordered comparison, but only between two values of the same primitive type. An absent property,
+ * or a type mismatch, matches nothing — the same answer Vectorize gives.
+ */
+function ordered(
+  value: unknown,
+  operand: unknown,
+  compareTo: (left: number | string, right: number | string) => boolean,
+): boolean {
+  if (typeof value !== typeof operand) return false;
+  if (typeof value !== "number" && typeof value !== "string") return false;
+  return compareTo(value, operand as number | string);
+}
+
+/**
+ * Build a filter against an index's metadata schema. The typed entry point: the compiler rejects a field that
+ * was not marked {@link filterable}, and the runtime checks below catch the same mistake arriving untyped.
+ */
+export function vectorFilter<S extends z.ZodObject>(metadata: S, filter: VectorFilter<S>): CompiledFilter {
+  return compileFilter(introspectMetadata(metadata).indexes, filter as CompiledFilter);
+}

package/src/index/index.ts

@@ -0,0 +1,244 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { InternalError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
+import type { VectorIndexConfig } from "../config/config";
+import { VectorDimensionMismatchError, VectorMetadataTooLargeError, VectorTopKExceededError } from "../error/errors";
+import { assertFilterSize, type CompiledFilter } from "./filter";
+import {
+  byteLength,
+  DEFAULT_TOPK,
+  MAX_METADATA_BYTES,
+  MAX_NAME_BYTES,
+  MAX_TOPK_WITH_PAYLOAD,
+  MAX_TOPK_WITHOUT_PAYLOAD,
+  MAX_UPSERT_BATCH,
+  MAX_VECTOR_ID_BYTES,
+} from "./limits";
+
+/**
+ * The Vectorize calls, over the `env.VECTORIZE` binding (bindings-first — CLAUDE.md §Cloudflare access).
+ *
+ * The binding is typed structurally as {@link VectorStore} rather than depending on the exact `VectorizeIndex`
+ * shape, so a test injects a fake and the code never reaches for a global. That is not a testing nicety here:
+ * Cloudflare ships **no local emulation for Vectorize**, so injection is the only way to unit-test any of this
+ * at all. The seam is always the first parameter.
+ *
+ * Every ceiling Vectorize publishes is checked before the call, not after. Vectorize's own rejections arrive
+ * as opaque errors that name neither the limit nor the offending vector, and the worst of them — a topK above
+ * the ceiling for the requested payload — is the kind of mistake that ships.
+ */
+
+/** A vector on its way into the index: an id, its components, and the metadata a filter can match on. */
+export interface VectorUpsert {
+  /** The vector's id — at most 64 bytes, and the join key back to the document row. */
+  id: string;
+  /** The embedding, exactly `dimensions` long. */
+  values: number[];
+  /** The metadata this vector carries. Under 10 KiB; long text belongs in the document table. */
+  metadata?: Record<string, unknown>;
+  /** The namespace this vector belongs to, when the index is partitioned. */
+  namespace?: string;
+}
+
+/** Options a similarity query accepts. */
+export interface VectorQueryOptions {
+  /**
+   * How many matches to return. Falls back to {@link DEFAULT_TOPK} — a caller that wants the capability's
+   * configured `defaultTopK` passes it, because this seam takes one index's config, not the project's.
+   */
+  topK?: number;
+  /** Restrict the search to one namespace. */
+  namespace?: string;
+  /** A compiled metadata filter — build it with `vectorFilter`, never by hand. */
+  filter?: CompiledFilter;
+  /** Return each match's components. Costs payload, and lowers the topK ceiling to 50. */
+  returnValues?: boolean;
+  /** Return each match's metadata. Costs payload, and lowers the topK ceiling to 50. */
+  returnMetadata?: boolean;
+}
+
+/**
+ * The subset of the Vectorize binding this module uses. Responses are `unknown`: their shape is the runtime's,
+ * so it is validated here rather than trusted.
+ */
+export interface VectorStore {
+  /** Insert or replace vectors. Asynchronous — the returned mutation id is an acknowledgement, not a write. */
+  upsert(vectors: VectorUpsert[]): Promise<unknown>;
+  /** Find the nearest neighbors of a vector. */
+  query(vector: number[], options?: Record<string, unknown>): Promise<unknown>;
+  /** Delete vectors by id. Optional here so a fake may omit it; guarded before use. */
+  deleteByIds?: (ids: string[]) => Promise<unknown>;
+}
+
+const MutationAck = z
+  .object({ mutationId: z.string().describe("Vectorize's id for the enqueued mutation.") })
+  .describe("The acknowledgement Vectorize returns for an enqueued write — the write itself lands later.");
+
+const QueryMatch = z
+  .object({
+    id: z.string().describe("The matched vector's id."),
+    score: z.number().describe("The similarity score, as scored by the index's metric."),
+    values: z.array(z.number()).optional().describe("The matched vector's components, when values were requested."),
+    metadata: z
+      .record(z.string(), z.unknown())
+      .optional()
+      .describe("The matched vector's metadata, when metadata was requested."),
+    namespace: z.string().nullish().describe("The namespace the match belongs to, when the index is partitioned."),
+  })
+  .describe("One nearest-neighbor match Vectorize returned.");
+
+const QueryResponse = z
+  .object({
+    count: z.number().describe("How many matches came back."),
+    matches: z.array(QueryMatch).describe("The matches, nearest first."),
+  })
+  .describe("The shape of a Vectorize query response.");
+
+/** A query's result: the matches, nearest first. */
+export type VectorQueryResult = z.infer<typeof QueryResponse>;
+
+/** A namespace is a Vectorize identifier, so it carries the same 64-byte ceiling as an index name. */
+function assertNamespace(namespace: string | undefined): void {
+  if (namespace === undefined) return;
+  if (namespace.length === 0 || byteLength(namespace) > MAX_NAME_BYTES) {
+    throw new ValidationError({
+      message: "That namespace is not usable.",
+      action: `A namespace is between 1 and ${MAX_NAME_BYTES} bytes.`,
+      detail: `namespace '${namespace}' is ${byteLength(namespace)} bytes`,
+    });
+  }
+}
+
+/** The vector must be exactly as long as the index was created for. Dimensions cannot be changed later. */
+function assertDimensions(index: VectorIndexConfig, values: number[], context: string): void {
+  if (values.length !== index.dimensions) {
+    throw new VectorDimensionMismatchError({
+      detail: `${context}: got ${values.length} components, index expects ${index.dimensions} (model ${index.model})`,
+    });
+  }
+}
+
+/**
+ * Validate and upsert a batch. Returns Vectorize's mutation id — an acknowledgement, not a completed write:
+ * Vectorize applies writes asynchronously, so nothing here may be read back immediately.
+ */
+export async function upsertVectors(
+  store: VectorStore,
+  index: VectorIndexConfig,
+  vectors: VectorUpsert[],
+): Promise<string> {
+  if (vectors.length === 0) {
+    throw new ValidationError({
+      message: "Nothing to write.",
+      action: "Pass at least one vector.",
+      detail: "upsertVectors received an empty batch",
+    });
+  }
+  if (vectors.length > MAX_UPSERT_BATCH) {
+    throw new ValidationError({
+      message: "Too many vectors in one write.",
+      action: `Write at most ${MAX_UPSERT_BATCH} vectors per call and repeat.`,
+      detail: `upsertVectors received ${vectors.length} vectors; the Workers binding accepts ${MAX_UPSERT_BATCH}`,
+    });
+  }
+
+  for (const vector of vectors) {
+    if (vector.id.length === 0 || byteLength(vector.id) > MAX_VECTOR_ID_BYTES) {
+      throw new ValidationError({
+        message: "That vector id is not usable.",
+        action: `A vector id is between 1 and ${MAX_VECTOR_ID_BYTES} bytes.`,
+        detail: `vector id '${vector.id.slice(0, 32)}…' is ${byteLength(vector.id)} bytes`,
+      });
+    }
+    assertDimensions(index, vector.values, `vector '${vector.id}'`);
+    if (vector.metadata) {
+      const size = byteLength(JSON.stringify(vector.metadata));
+      if (size >= MAX_METADATA_BYTES) {
+        throw new VectorMetadataTooLargeError({
+          detail: `vector '${vector.id}' carries ${size} bytes of metadata; the limit is ${MAX_METADATA_BYTES}`,
+        });
+      }
+    }
+    assertNamespace(vector.namespace);
+  }
+
+  const raw = await store.upsert(vectors);
+  const parsed = MutationAck.safeParse(raw);
+  if (!parsed.success) {
+    throw new InternalError({
+      message: "The vector store returned something unexpected.",
+      detail: "Vectorize upsert returned an unexpected shape",
+    });
+  }
+  return parsed.data.mutationId;
+}
+
+/**
+ * Validate and run a similarity query. `topK` is checked against the ceiling that applies to *this* query:
+ * Vectorize allows 100 matches when it returns neither values nor metadata, and 50 when it returns either.
+ */
+export async function queryVectors(
+  store: VectorStore,
+  index: VectorIndexConfig,
+  vector: number[],
+  options: VectorQueryOptions = {},
+): Promise<VectorQueryResult> {
+  assertDimensions(index, vector, "query vector");
+  assertNamespace(options.namespace ?? index.namespace);
+
+  const returnsPayload = options.returnValues === true || options.returnMetadata === true;
+  const ceiling = returnsPayload ? MAX_TOPK_WITH_PAYLOAD : MAX_TOPK_WITHOUT_PAYLOAD;
+  const topK = options.topK ?? DEFAULT_TOPK;
+  if (topK < 1) {
+    throw new ValidationError({
+      message: "Ask for at least one match.",
+      action: "topK is a positive whole number.",
+      detail: `topK was ${topK}`,
+    });
+  }
+  if (topK > ceiling) {
+    throw new VectorTopKExceededError({
+      detail: `topK ${topK} exceeds ${ceiling} for a query that returns ${returnsPayload ? "values or metadata" : "neither values nor metadata"}`,
+    });
+  }
+  if (options.filter) assertFilterSize(options.filter);
+
+  const namespace = options.namespace ?? index.namespace;
+  const raw = await store.query(vector, {
+    topK,
+    returnValues: options.returnValues === true,
+    returnMetadata: options.returnMetadata === true,
+    ...(namespace ? { namespace } : {}),
+    ...(options.filter ? { filter: options.filter } : {}),
+  });
+
+  const parsed = QueryResponse.safeParse(raw);
+  if (!parsed.success) {
+    throw new InternalError({
+      message: "The vector store returned something unexpected.",
+      detail: "Vectorize query returned an unexpected shape",
+    });
+  }
+  return parsed.data;
+}
+
+/** Delete vectors by id. Guarded, because a fake — or an older binding — may not carry the method. */
+export async function deleteVectors(store: VectorStore, ids: string[]): Promise<string> {
+  if (!store.deleteByIds) {
+    throw new InternalError({
+      message: "This vector index cannot delete.",
+      detail: "the Vectorize binding does not expose deleteByIds",
+    });
+  }
+  const raw = await store.deleteByIds(ids);
+  const parsed = MutationAck.safeParse(raw);
+  if (!parsed.success) {
+    throw new InternalError({
+      message: "The vector store returned something unexpected.",
+      detail: "Vectorize deleteByIds returned an unexpected shape",
+    });
+  }
+  return parsed.data.mutationId;
+}