@volter/twin-turbopuffer 0.1.0

package/src/turbopuffer-store.ts

@@ -0,0 +1,1157 @@
+// THE NAMESPACE CORE — Turbopuffer's namespaces and documents as kernel state, and the pure
+// functions that apply a write and answer a query against them.
+//
+// STATE LIVES IN THE KERNEL TREE. A namespace is one `namespace` subject (its schema, distance
+// metric, vector dimensions and timestamps); every document is one `document` subject keyed
+// `<namespace>/<n|s>:<id>` (the id's JSON type is part of its identity: 7 and "7" are two
+// documents). A write request is ONE kernel action — the namespace subject's fields plus a
+// projection that updates/deletes the documents it touched — decided under the kernel's action lock
+// (`applyTwinWriteAtomic`), because Turbopuffer applies a write request atomically. The action's
+// `input` is the request body as the caller sent it, which is exactly what the perform adapter
+// replays against the real vendor.
+//
+// Everything below this header is PURE: it reads a snapshot and returns the next one. The handler
+// (turbopuffer-twin.ts) owns the wire and the kernel calls.
+import { createHash } from 'node:crypto';
+import { ownFields, type TwinResource } from '@volter/world-core';
+import { assertModelledFts, attributeValue, badRequest, compareScalars, compileFilter, docTokens, TurbopufferError, type AttrConfig, type Doc, type FilterContext } from './turbopuffer-filter.ts';
+import { bm25Score, buildCorpus, DEFAULT_FTS, MODELED_TOKENIZERS, queryTerms, TOKENIZERS, type Corpus, type FtsConfig } from './turbopuffer-text.ts';
+
+export { badRequest, TurbopufferError } from './turbopuffer-filter.ts';
+export type { AttrConfig, Doc } from './turbopuffer-filter.ts';
+
+export const SERVICE = 'turbopuffer';
+export const TURBOPUFFER_RESOURCE_TYPES = ['namespace', 'document'] as const;
+
+/** Namespace names: `[A-Za-z0-9-_.]{1,128}` (turbopuffer.com/docs/write, "namespace"). */
+const NAMESPACE_NAME = /^[A-Za-z0-9._-]{1,128}$/;
+export const DISTANCE_METRICS = ['cosine_distance', 'euclidean_squared'] as const;
+/** The attribute types the SDK's `AttributeSchemaConfig.type` doc enumerates. */
+const SCALAR_TYPES = ['string', 'int', 'uint', 'float', 'uuid', 'datetime', 'bool'] as const;
+
+export type NamespaceState = {
+  name: string;
+  schema: Record<string, AttrConfig>;
+  distance_metric: string | null;
+  vector_dims: number | null;
+  created_at: string;
+  updated_at: string;
+  /** when its documents last changed (a schema-only write moves `updated_at` alone) */
+  last_write_at: string;
+  /** the namespace a branch was made from (metadata's `branching.parent`) */
+  parent?: string;
+  docs: Map<string, Doc>;
+};
+
+export function assertNamespaceName(name: string): void {
+  if (!NAMESPACE_NAME.test(name)) throw badRequest(`invalid namespace name "${name}": must be 1-128 characters of [A-Za-z0-9-_.]`);
+}
+
+const utf8 = new TextEncoder();
+function utf8Length(s: string): number {
+  return utf8.encode(s).length;
+}
+
+export function docKey(id: string | number): string {
+  return typeof id === 'number' ? `n:${id}` : `s:${id}`;
+}
+
+export function documentSubjectId(ns: string, id: string | number): string {
+  return `${ns}/${docKey(id)}`;
+}
+
+// ── loading the snapshot from the tree ──────────────────────────────────────────────────────
+
+/** Fold the tree's `namespace` / `document` subjects into live namespaces. */
+export function loadNamespaces(resources: readonly TwinResource[]): Map<string, NamespaceState> {
+  const out = new Map<string, NamespaceState>();
+  for (const r of resources) {
+    if (r.type !== 'namespace') continue;
+    const f = ownFields(r);
+    // `deleted` is the kernel's mark for a subject a complete refresh no longer saw; `gone` is deleteAll's.
+    if (f.gone === true || f.deleted === true || typeof f.name !== 'string') continue;
+    out.set(f.name, {
+      name: f.name,
+      schema: (f.schema !== null && typeof f.schema === 'object' ? f.schema : {}) as Record<string, AttrConfig>,
+      distance_metric: typeof f.distance_metric === 'string' ? f.distance_metric : null,
+      vector_dims: typeof f.vector_dims === 'number' ? f.vector_dims : null,
+      created_at: typeof f.created_at === 'string' ? f.created_at : r.updatedAt,
+      updated_at: typeof f.updated_at === 'string' ? f.updated_at : r.updatedAt,
+      last_write_at: typeof f.last_write_at === 'string' ? f.last_write_at : typeof f.updated_at === 'string' ? f.updated_at : r.updatedAt,
+      ...(typeof f.parent === 'string' ? { parent: f.parent } : {}),
+      docs: new Map(),
+    });
+  }
+  for (const r of resources) {
+    if (r.type !== 'document') continue;
+    const f = ownFields(r);
+    if (f.deleted === true || typeof f.namespace !== 'string') continue;
+    const ns = out.get(f.namespace);
+    if (ns === undefined) continue;
+    const id = f.doc_id;
+    if (typeof id !== 'string' && typeof id !== 'number') continue;
+    ns.docs.set(docKey(id), {
+      key: docKey(id),
+      id,
+      attributes: (f.attributes !== null && typeof f.attributes === 'object' ? f.attributes : {}) as Record<string, unknown>,
+      vector: Array.isArray(f.vector) ? (f.vector as number[]) : null,
+    });
+  }
+  return out;
+}
+
+export function namespaceFields(ns: NamespaceState): Record<string, unknown> {
+  return {
+    name: ns.name,
+    schema: ns.schema,
+    distance_metric: ns.distance_metric,
+    vector_dims: ns.vector_dims,
+    created_at: ns.created_at,
+    updated_at: ns.updated_at,
+    last_write_at: ns.last_write_at,
+    parent: ns.parent ?? null,
+    gone: false,
+  };
+}
+
+export function documentFields(ns: string, d: Doc): Record<string, unknown> {
+  return { namespace: ns, doc_id: d.id, attributes: d.attributes, vector: d.vector };
+}
+
+// ── schema ──────────────────────────────────────────────────────────────────────────────────
+
+/** "Vectors are attributes with a vector type (`[N]f32`, `[N]f16`, or `[N]i8` where N is the number of dimensions)"
+ *  (https://turbopuffer.com/docs/write, Vectors). */
+export function isVectorType(t: string): boolean {
+  return /^\[\d+\](f16|f32|i8)$/.test(t);
+}
+
+const dimsOf = (t: string): number => Number(/^\[(\d+)\]/.exec(t)?.[1] ?? NaN);
+
+function isKnownType(t: string): boolean {
+  if ((SCALAR_TYPES as readonly string[]).includes(t)) return true;
+  if (t.startsWith('[]') && (SCALAR_TYPES as readonly string[]).includes(t.slice(2))) return true;
+  // "`{}f16`: Sparse vector with string keys and 16-bit floats as weights"; "`bytes` holds arbitrary binary data …
+  // passed and returned as base64-encoded strings" (https://turbopuffer.com/docs/write, type)
+  return isVectorType(t) || isVectorArrayType(t) || t === '{}f16' || t === 'bytes';
+}
+
+/** "`[][N]f32`: Variable-length array of `N` dimensional f32 vectors, used for late-interaction (multi-vector) search"
+ *  (https://turbopuffer.com/docs/write, type). */
+export function isVectorArrayType(t: string): boolean {
+  return /^\[\]\[\d+\]f32$/.test(t);
+}
+
+function normalizeFts(raw: unknown, attr: string, type: string): FtsConfig | false {
+  if (raw === undefined || raw === false || raw === null) return false;
+  if (type !== 'string' && type !== '[]string') throw badRequest(`invalid schema for attribute "${attr}": full_text_search requires the string or []string type`);
+  const given = raw === true ? {} : raw;
+  if (typeof given !== 'object' || Array.isArray(given)) throw badRequest(`invalid schema for attribute "${attr}": full_text_search must be a boolean or an object`);
+  const cfg: FtsConfig = { ...DEFAULT_FTS };
+  for (const [k, v] of Object.entries(given as Record<string, unknown>)) {
+    const set = FTS_OPTIONS[k];
+    if (!set) throw badRequest(`invalid schema for attribute "${attr}": unknown full_text_search option "${k}"`);
+    set(cfg, v, attr, k);
+  }
+  // Refused rather than approximated: an unmodelled tokenizer or a stemmer would silently rank
+  // differently from the vendor (see turbopuffer-text.ts's header).
+  if (!MODELED_TOKENIZERS.includes(cfg.tokenizer)) throw badRequest(`turbopuffer twin: tokenizer "${cfg.tokenizer}" on attribute "${attr}" is real Turbopuffer surface this twin does not model yet — word_v4, word_v3, word_v2 and pre_tokenized_array are modelled (turbopuffer.fts.tokenizers is the filed gap)`);
+  // stemming is modelled for English (./turbopuffer-stem.ts), the one language the twin models
+  if (cfg.language !== 'english') throw badRequest(`turbopuffer twin: language "${cfg.language}" on attribute "${attr}" is not modelled (turbopuffer.fts.languages is the filed gap)`);
+  return cfg;
+}
+
+function tokenizerOption(cfg: FtsConfig, v: unknown, attr: string): void {
+  if (typeof v !== 'string' || !(TOKENIZERS as readonly string[]).includes(v)) throw badRequest(`invalid schema for attribute "${attr}": unknown tokenizer ${JSON.stringify(v)}`);
+  cfg.tokenizer = v;
+}
+
+function flagOption(cfg: FtsConfig, v: unknown, attr: string, k: string): void {
+  if (typeof v !== 'boolean') throw badRequest(`invalid schema for attribute "${attr}": full_text_search.${k} must be a boolean`);
+  cfg[k as 'case_sensitive' | 'remove_stopwords' | 'stemming' | 'ascii_folding'] = v;
+}
+
+function languageOption(cfg: FtsConfig, v: unknown, attr: string): void {
+  if (typeof v !== 'string') throw badRequest(`invalid schema for attribute "${attr}": full_text_search.language must be a string`);
+  cfg.language = v;
+}
+
+/** full_text_search's options (https://turbopuffer.com/docs/write, full_text_search). k3: "Query term frequency
+ *  saturation parameter for BM25 scoring. Must be greater than zero. Defaults to 8.0"; the twin's queries count each term
+ *  once, so it is kept, not applied. */
+const FTS_OPTIONS: Record<string, (cfg: FtsConfig, v: unknown, attr: string, k: string) => void> = {
+  tokenizer: tokenizerOption, case_sensitive: flagOption, remove_stopwords: flagOption, stemming: flagOption, ascii_folding: flagOption,
+  language: languageOption, max_token_length: (cfg, v, attr) => maxTokenLength(cfg, v, attr),
+  k1: (cfg, v, attr) => bm25Parameter(cfg, 'k1', v, attr), b: (cfg, v, attr) => bm25Parameter(cfg, 'b', v, attr), k3: (cfg, v, attr) => bm25Parameter(cfg, 'k3', v, attr),
+};
+
+/** `max_token_length`: "Maximum length of a token in bytes. … Has to be between `1` and `254` (inclusive). Defaults to
+ *  `39`" (https://turbopuffer.com/docs/write, full_text_search). */
+function maxTokenLength(cfg: FtsConfig, v: unknown, attr: string): void {
+  if (typeof v !== 'number' || !Number.isInteger(v) || v < 1 || v > 254) throw badRequest(`invalid schema for attribute "${attr}": max_token_length has to be between 1 and 254`);
+  cfg.max_token_length = v;
+}
+
+/** `k1`, `b` and `k3`, BM25's parameters (https://turbopuffer.com/docs/write, full_text_search; /docs/fts, Advanced tuning). */
+function bm25Parameter(cfg: FtsConfig, k: 'k1' | 'b' | 'k3', v: unknown, attr: string): void {
+  if (typeof v !== 'number' || !Number.isFinite(v) || v < 0) throw badRequest(`invalid schema for attribute "${attr}": full_text_search.${k} must be a non-negative number`);
+  cfg[k] = v;
+}
+
+const SCHEMA_OPTIONS = ['type', 'filterable', 'full_text_search', 'glob', 'regex', 'fuzzy', 'ann', 'sparse_knn', 'embed'];
+
+/** Normalize one schema entry (`"string"` or a config object) into the stored form. */
+export function normalizeAttrSchema(attr: string, raw: unknown): AttrConfig {
+  const given = typeof raw === 'string' ? { type: raw } : raw;
+  if (given === null || typeof given !== 'object' || Array.isArray(given)) throw badRequest(`invalid schema for attribute "${attr}": expected a type string or a config object`);
+  const g = given as Record<string, unknown>;
+  // `embed` is native embedding, applied by mergeSchema (embedSchema)
+  for (const k of Object.keys(g)) if (!SCHEMA_OPTIONS.includes(k)) throw badRequest(`invalid schema for attribute "${attr}": unknown option "${k}"`);
+  if (typeof g.type !== 'string' || !isKnownType(g.type)) throw badRequest(`invalid schema for attribute "${attr}": unknown type ${JSON.stringify(g.type)}`);
+  if (g.ann !== undefined && g.ann !== false && !isVectorType(g.type) && !isVectorArrayType(g.type)) throw badRequest(`invalid schema for attribute "${attr}": ann requires a vector type`);
+  // "On a vector array attribute (`[][N]f32`), `ann: {"late_interaction": true}` builds the index used for
+  // late-interaction (multi-vector) search. Set `ann: false` to store the per-token vectors without building the index
+  // (exact kNN queries still work, but not ANN queries)" (https://turbopuffer.com/docs/write, ann)
+  const late = isVectorArrayType(g.type);
+  if (late && !(g.ann === false || (g.ann !== null && typeof g.ann === 'object' && (g.ann as Record<string, unknown>).late_interaction === true && Object.keys(g.ann as object).length === 1))) throw badRequest(`invalid schema for attribute "${attr}": a [][N]f32 attribute takes ann: {"late_interaction": true} or ann: false`);
+  const annOptions = !late && g.ann !== null && typeof g.ann === 'object' ? Object.keys(g.ann as object) : [];
+  if (annOptions.some((k) => k !== 'distance_metric')) throw badRequest(`invalid schema for attribute "${attr}": unknown ann option in ${JSON.stringify(annOptions)}`);
+  // "sparse_knn … When configured, this attribute can be used as part of a `SparseKNN` query. This is only supported on
+  // the `{}f16` type. This requires a `distance_metric` string field, which only supports `dot_product`"; "`{}f16`
+  // attributes are not filterable", and neither is `bytes` ("does not support indexing or filtering of any kind")
+  if (g.sparse_knn !== undefined && g.sparse_knn !== null) {
+    const sk = g.sparse_knn as Record<string, unknown>;
+    if (g.type !== '{}f16') throw badRequest(`invalid schema for attribute "${attr}": sparse_knn is only supported on the {}f16 type`);
+    if (typeof sk !== 'object' || Array.isArray(sk) || sk.distance_metric !== 'dot_product' || Object.keys(sk).length !== 1) throw badRequest(`invalid schema for attribute "${attr}": sparse_knn requires distance_metric "dot_product"`);
+  }
+  if ((g.type === '{}f16' || g.type === 'bytes') && g.filterable === true) throw badRequest(`invalid schema for attribute "${attr}": ${g.type} attributes are not filterable`);
+  if (g.filterable !== undefined && typeof g.filterable !== 'boolean') throw badRequest(`invalid schema for attribute "${attr}": filterable must be a boolean`);
+  const fts = normalizeFts(g.full_text_search, attr, g.type);
+  const annMetric = g.ann !== null && typeof g.ann === 'object' ? (g.ann as Record<string, unknown>).distance_metric : undefined;
+  if (annMetric !== undefined && !(DISTANCE_METRICS as readonly string[]).includes(annMetric as string)) throw badRequest(`invalid schema for attribute "${attr}": ann.distance_metric must be one of ${DISTANCE_METRICS.join(', ')}`);
+  return {
+    ...(typeof annMetric === 'string' ? { ann_distance_metric: annMetric } : {}),
+    type: g.type,
+    // "by default, BM25-enabled attributes are not filterable" (SDK AttributeSchemaConfig doc).
+    ...(late ? { late_interaction: g.ann !== false } : {}),
+    // glob, regex and fuzzy: "If set, `filterable` defaults to `false`; you can override this by setting `filterable: true`"
+    filterable: g.type === '{}f16' || g.type === 'bytes' || late ? false : typeof g.filterable === 'boolean' ? g.filterable : fts === false && g.regex !== true && g.fuzzy !== true && g.glob !== true,
+    ...(g.sparse_knn !== undefined && g.sparse_knn !== null ? { sparse_knn: { distance_metric: 'dot_product' } } : {}),
+    full_text_search: fts,
+    ...(g.glob === true ? { glob: true } : {}),
+    ...(g.regex === true ? { regex: true } : {}),
+    ...(g.fuzzy === true ? { fuzzy: true } : {}),
+  };
+}
+
+/** The type Turbopuffer infers for an attribute first written without a declared schema. */
+function inferType(v: unknown): string | null {
+  if (typeof v === 'string') return 'string';
+  if (typeof v === 'boolean') return 'bool';
+  if (typeof v === 'number') return Number.isInteger(v) ? 'int' : 'float';
+  // an object, or anything else no type is inferred from, is refused by the caller
+  if (!Array.isArray(v)) return null;
+  const first = v.find((x) => x !== null);
+  if (first === undefined) return '[]string';
+  const inner = inferType(first);
+  return inner === null || inner.startsWith('[') ? null : `[]${inner}`;
+}
+
+function valueMatchesType(v: unknown, type: string): boolean {
+  if (type.startsWith('[]')) return Array.isArray(v) && v.every((x) => x === null || valueMatchesType(x, type.slice(2)));
+  switch (type) {
+    case 'string': case 'uuid': case 'datetime': return typeof v === 'string';
+    case 'bool': return typeof v === 'boolean';
+    case 'float': return typeof v === 'number' && Number.isFinite(v);
+    case 'int': return typeof v === 'number' && Number.isInteger(v);
+    case 'uint': return typeof v === 'number' && Number.isInteger(v) && v >= 0;
+    case 'bytes': return typeof v === 'string' && /^[A-Za-z0-9+/]*={0,2}$/.test(v) && v.length % 4 === 0;
+    // "Max dimensions per sparse vector: 1,024" (https://turbopuffer.com/docs/limits)
+    case '{}f16': return v !== null && typeof v === 'object' && !Array.isArray(v) && Object.keys(v).length <= 1024 && Object.values(v).every((x) => typeof x === 'number' && Number.isFinite(x));
+  }
+  return false;
+}
+
+// ── writes ──────────────────────────────────────────────────────────────────────────────────
+
+const WRITE_KEYS = new Set(['upsert_condition', 'patch_condition', 'delete_condition', 'upsert_rows', 'upsert_columns', 'patch_rows', 'patch_columns', 'deletes', 'delete_by_filter', 'delete_by_filter_allow_partial', 'patch_by_filter', 'patch_by_filter_allow_partial', 'schema', 'distance_metric', 'return_affected_ids', 'disable_backpressure']);
+const UNMODELED_WRITE_KEYS: Record<string, string> = {
+  encryption: 'turbopuffer.write.encryption',
+  sharding: 'turbopuffer.write.sharding',
+};
+
+export type WriteOutcome = {
+  next: NamespaceState;
+  created: boolean;
+  upserts: Doc[];
+  deletes: string[];
+  response: Record<string, unknown>;
+};
+
+function assertId(id: unknown, where: string): string | number {
+  const valid = (typeof id === 'string' && id.length > 0 && id.length <= 64 * 1024) || (typeof id === 'number' && Number.isSafeInteger(id) && id >= 0);
+  if (!valid) throw badRequest(`invalid ${where}: a document id must be a non-empty string or an unsigned integer, got ${JSON.stringify(id)}`);
+  return id as string | number;
+}
+
+function rowsFromColumns(cols: unknown, where: string): Record<string, unknown>[] {
+  if (cols === null || typeof cols !== 'object' || Array.isArray(cols)) throw badRequest(`invalid ${where}: expected an object of columns`);
+  const c = cols as Record<string, unknown>;
+  if (!Array.isArray(c.id)) throw badRequest(`invalid ${where}: the id column is required`);
+  const n = c.id.length;
+  for (const [k, v] of Object.entries(c)) {
+    if (!Array.isArray(v)) throw badRequest(`invalid ${where}: column "${k}" must be an array`);
+    if (v.length !== n) throw badRequest(`invalid ${where}: column "${k}" has ${v.length} values but the id column has ${n}`);
+  }
+  return Array.from({ length: n }, (_, i) => Object.fromEntries(Object.entries(c).map(([k, v]) => [k, (v as unknown[])[i]])));
+}
+
+function rowList(v: unknown, where: string): Record<string, unknown>[] {
+  if (!Array.isArray(v)) throw badRequest(`invalid ${where}: expected an array of rows`);
+  return v.map((r, i) => {
+    if (r === null || typeof r !== 'object' || Array.isArray(r)) throw badRequest(`invalid ${where}[${i}]: expected an object`);
+    return r as Record<string, unknown>;
+  });
+}
+
+function logicalBytes(d: Doc): number {
+  return utf8Length(JSON.stringify(d.id)) + utf8Length(JSON.stringify(d.attributes)) + (d.vector ? d.vector.length * 4 : 0);
+}
+
+export function approxLogicalBytes(ns: NamespaceState): number {
+  let n = 0;
+  for (const d of ns.docs.values()) n += logicalBytes(d);
+  return n;
+}
+
+/** `copy_from_namespace` and `branch_from_namespace` (https://turbopuffer.com/docs/write): the destination is made as a
+ *  copy of the source's documents, schema and distance metric. "The destination namespace you are copying into must be
+ *  empty. The initial request currently cannot make schema changes or contain documents"; a branch is "an instant
+ *  copy-on-write clone of the source namespace. The destination namespace must be empty", and "reads, writes, queries,
+ *  and deletes on one namespace do not affect the other". A copy answers "namespace cloned successfully" (the async
+ *  copy's result, https://turbopuffer.com/docs/api-overview), and a destination that exists "destination namespace
+ *  already exists" (the same page's failed result).
+ *
+ *  Where the docs stop and the twin decides: a World holds one organization's namespaces in one store whatever region a
+ *  request names, so a copy's `source_region` and `source_api_key` read the same store; `rows_affected` counts the
+ *  documents cloned; a copy bills the logical bytes copied and a branch none ("billed at a flat rate"); a branch's
+ *  answer carries the copy's message. Pure. */
+export function applyClone(spaces: Map<string, NamespaceState>, name: string, rawBody: unknown, at: string): WriteOutcome {
+  assertNamespaceName(name);
+  const body = rawBody as Record<string, unknown>;
+  const branch = body.branch_from_namespace !== undefined;
+  const key = branch ? 'branch_from_namespace' : 'copy_from_namespace';
+  if (body.copy_from_namespace !== undefined && branch) throw badRequest('invalid write request: copy_from_namespace and branch_from_namespace cannot both be set');
+  for (const k of Object.keys(body)) if (k !== key && k !== 'return_affected_ids' && k !== 'disable_backpressure') throw cloneRefusal(k, key);
+  const raw = body[key];
+  const cfg = typeof raw === 'string' ? { source_namespace: raw } : raw !== null && typeof raw === 'object' && !Array.isArray(raw) ? raw as Record<string, unknown> : undefined;
+  const allowed = branch ? ['source_namespace'] : ['source_namespace', 'source_api_key', 'source_region', 'dest_encryption'];
+  if (!cfg || typeof cfg.source_namespace !== 'string' || Object.keys(cfg).some((k) => !allowed.includes(k))) throw badRequest(`invalid ${key}: expected a namespace name or { ${allowed.join(', ')} }`);
+  if (cfg.dest_encryption !== undefined) throw badRequest('turbopuffer twin: "dest_encryption" is real Turbopuffer surface this twin does not model yet (turbopuffer.write.encryption is the filed gap)');
+  const source = spaces.get(cfg.source_namespace);
+  if (source === undefined) throw new TurbopufferError(404, `namespace '${cfg.source_namespace}' was not found`);
+  if (spaces.has(name)) throw badRequest('destination namespace already exists');
+  const docs = new Map([...source.docs].map(([k, d]) => [k, { ...d, attributes: { ...d.attributes } }]));
+  const next: NamespaceState = {
+    name, schema: structuredClone(source.schema), distance_metric: source.distance_metric, vector_dims: source.vector_dims,
+    created_at: at, updated_at: at, last_write_at: at, ...(branch ? { parent: source.name } : {}), docs,
+  };
+  const upserts = [...docs.values()];
+  const bytes = branch ? 0 : upserts.reduce((n, d) => n + logicalBytes(d), 0);
+  const response = {
+    status: 'OK', message: 'namespace cloned successfully', rows_affected: upserts.length,
+    ...(body.return_affected_ids === true && upserts.length ? { upserted_ids: upserts.map((d) => d.id) } : {}),
+    billing: { billable_logical_bytes_written: bytes }, performance: { server_total_ms: 0 },
+  };
+  return { next, created: true, upserts, deletes: [], response };
+}
+
+/** A clone request carrying something else: "The initial request currently cannot make schema changes or contain
+ *  documents" (https://turbopuffer.com/docs/write, copy_from_namespace); its `encryption` and `sharding`, which the page
+ *  lets a copy set, are not modelled. */
+function cloneRefusal(k: string, key: string): TurbopufferError {
+  if (k === 'encryption' || k === 'sharding') return gap(`"${k}" on a ${key} request`, `turbopuffer.write.${k}`);
+  return badRequest(`invalid write request: a ${key} request cannot also carry "${k}"`);
+}
+
+/** Apply one write request body to a namespace (or create it). Pure. */
+export function applyWrite(existing: NamespaceState | undefined, name: string, rawBody: unknown, at: string): WriteOutcome {
+  assertNamespaceName(name);
+  if (rawBody === null || typeof rawBody !== 'object' || Array.isArray(rawBody)) throw badRequest('invalid write request: expected a JSON object');
+  const body = rawBody as Record<string, unknown>;
+  for (const k of Object.keys(body)) {
+    const gap = UNMODELED_WRITE_KEYS[k];
+    if (gap !== undefined) throw badRequest(`turbopuffer twin: "${k}" is real Turbopuffer surface this twin does not model yet (${gap} is the filed gap)`);
+    if (!WRITE_KEYS.has(k)) throw badRequest(`invalid write request: unknown field "${k}"`);
+  }
+  const ops = ['upsert_rows', 'upsert_columns', 'patch_rows', 'patch_columns', 'deletes', 'delete_by_filter', 'patch_by_filter'].filter((k) => body[k] !== undefined);
+  if (ops.length === 0 && body.schema === undefined) throw badRequest('invalid write request: the request contains no write operation');
+
+  const ns: NamespaceState = existing
+    ? { ...existing, schema: { ...existing.schema }, docs: new Map(existing.docs) }
+    : { name, schema: {}, distance_metric: null, vector_dims: null, created_at: at, updated_at: at, last_write_at: at, docs: new Map() };
+  // "updated_at … when the namespace's data or schema was last modified"; "last_write_at … when the namespace's data was
+  // last modified" (https://turbopuffer.com/docs/metadata)
+  ns.updated_at = at;
+  if (ops.length > 0) ns.last_write_at = at;
+
+  // 1. schema (declared) — a type may never change under an attribute that already has one.
+  if (body.schema !== undefined) {
+    if (body.schema === null || typeof body.schema !== 'object' || Array.isArray(body.schema)) throw badRequest('invalid write request: schema must be an object');
+    for (const [attr, raw] of Object.entries(body.schema as Record<string, unknown>)) mergeSchema(ns, attr, raw, existing === undefined);
+  }
+  // 2. distance metric — fixed once set.
+  if (body.distance_metric !== undefined) {
+    if (typeof body.distance_metric !== 'string' || !(DISTANCE_METRICS as readonly string[]).includes(body.distance_metric)) throw badRequest(`invalid write request: distance_metric must be one of ${DISTANCE_METRICS.join(', ')}`);
+    if (ns.distance_metric !== null && ns.distance_metric !== body.distance_metric) throw badRequest(`invalid write request: namespace "${name}" uses distance_metric ${ns.distance_metric}, not ${body.distance_metric}`);
+    ns.distance_metric = body.distance_metric;
+  }
+
+  const upserted = new Map<string, Doc>();
+  const deleted = new Set<string>();
+  const upsertedIds: (string | number)[] = [];
+  const patchedIds: (string | number)[] = [];
+  const deletedIds: (string | number)[] = [];
+  let rowsUpserted = 0;
+  let rowsPatched = 0;
+  let rowsDeleted = 0;
+  const ctx = (): FilterContext => ({ schema: ns.schema, tokenCache: new Map() });
+  const remove = (key: string) => { const d = ns.docs.get(key); if (d) { ns.docs.delete(key); upserted.delete(key); deleted.add(key); } };
+  const put = (d: Doc) => { ns.docs.set(d.key, d); upserted.set(d.key, d); deleted.delete(d.key); };
+
+  // Order of application: filtered deletes, filtered patches, upserts, patches, deletes.
+  if (body.delete_by_filter !== undefined) {
+    const pred = compileFilter(body.delete_by_filter, ctx());
+    for (const d of [...ns.docs.values()]) if (pred(d)) { remove(d.key); rowsDeleted++; deletedIds.push(d.id); }
+  }
+  if (body.patch_by_filter !== undefined) {
+    const pbf = body.patch_by_filter as Record<string, unknown> | null;
+    if (pbf === null || typeof pbf !== 'object' || Array.isArray(pbf) || pbf.patch === null || typeof pbf.patch !== 'object' || Array.isArray(pbf.patch)) throw badRequest('invalid patch_by_filter: expected { filters, patch }');
+    const pred = compileFilter(pbf.filters, ctx());
+    const patch = pbf.patch as Record<string, unknown>;
+    if ('id' in patch) throw badRequest('invalid patch_by_filter: the patch may not set id');
+    for (const d of [...ns.docs.values()]) if (pred(d)) { put(patchDoc(ns, d, patch)); rowsPatched++; patchedIds.push(d.id); }
+  }
+  const upsertRows = [
+    ...(body.upsert_rows !== undefined ? rowList(body.upsert_rows, 'upsert_rows') : []),
+    ...(body.upsert_columns !== undefined ? rowsFromColumns(body.upsert_columns, 'upsert_columns') : []),
+  ];
+  const passes = conditionOf(ns, body, 'upsert_condition');
+  const passesPatch = conditionOf(ns, body, 'patch_condition');
+  const passesDelete = conditionOf(ns, body, 'delete_condition');
+  for (const row of upsertRows) {
+    const current = row.id === undefined ? undefined : ns.docs.get(docKey(assertId(row.id, 'upsert_rows')));
+    if (current !== undefined && passes && !passes(current, row)) continue;
+    const d = buildDoc(ns, row, 'upsert_rows');
+    embedRow(ns, d);
+    checkAllVectors(ns, d, 'upsert_rows');
+    put(d);
+    rowsUpserted++;
+    upsertedIds.push(d.id);
+  }
+  const patchRows = [
+    ...(body.patch_rows !== undefined ? rowList(body.patch_rows, 'patch_rows') : []),
+    ...(body.patch_columns !== undefined ? rowsFromColumns(body.patch_columns, 'patch_columns') : []),
+  ];
+  for (const row of patchRows) {
+    const id = assertId(row.id, 'patch_rows');
+    const current = ns.docs.get(docKey(id));
+    if (current === undefined) continue; // a patch never creates a document
+    if (passesPatch && !passesPatch(current, row)) continue;
+    const { id: _id, ...patch } = row;
+    put(patchDoc(ns, current, patch));
+    rowsPatched++;
+    patchedIds.push(id);
+  }
+  if (body.deletes !== undefined) {
+    if (!Array.isArray(body.deletes)) throw badRequest('invalid deletes: expected an array of ids');
+    for (const raw of body.deletes) {
+      const id = assertId(raw, 'deletes');
+      if (passesDelete && !conditionalDelete(ns, id, passesDelete)) continue;
+      remove(docKey(id));
+      rowsDeleted++;
+      deletedIds.push(id);
+    }
+  }
+
+  const upserts = [...upserted.values()];
+  const bytes = upserts.reduce((n, d) => n + logicalBytes(d), 0);
+  const queried = ['upsert_condition', 'patch_condition', 'delete_condition', 'patch_by_filter', 'delete_by_filter'].some((k) => body[k] !== undefined);
+  const queriedBytes = existing ? approxLogicalBytes(existing) : 0;
+  const returnIds = body.return_affected_ids === true;
+  const response: Record<string, unknown> = {
+    status: 'OK',
+    // the Write page's answers: "message": "documents committed successfully"
+    message: 'documents committed successfully',
+    rows_affected: rowsUpserted + rowsPatched + rowsDeleted,
+    ...(upsertRows.length > 0 ? { rows_upserted: rowsUpserted } : {}),
+    ...(patchRows.length > 0 || body.patch_by_filter !== undefined ? { rows_patched: rowsPatched } : {}),
+    ...(body.deletes !== undefined || body.delete_by_filter !== undefined ? { rows_deleted: rowsDeleted } : {}),
+    ...(body.delete_by_filter !== undefined || body.patch_by_filter !== undefined ? { rows_remaining: false } : {}),
+    ...(returnIds && upsertedIds.length > 0 ? { upserted_ids: upsertedIds } : {}),
+    ...(returnIds && patchedIds.length > 0 ? { patched_ids: patchedIds } : {}),
+    ...(returnIds && deletedIds.length > 0 ? { deleted_ids: deletedIds } : {}),
+    billing: {
+      billable_logical_bytes_written: bytes,
+      // "query (object, optional): query billing information when the write involves a query-like operation (for a
+      // conditional write, patch_by_filter, delete_by_filter …)" (https://turbopuffer.com/docs/write); the twin bills the
+      // namespace's logical bytes as queried and none as returned, its reading
+      ...(queried ? { query: { billable_logical_bytes_queried: queriedBytes, billable_logical_bytes_returned: 0 } } : {}),
+    },
+    performance: { server_total_ms: 0 },
+  };
+  return { next: ns, created: existing === undefined, upserts, deletes: [...deleted], response };
+}
+
+/** Whether a conditional delete of `id` goes ahead: "If the document does not exist, the write is … skipped
+ *  unconditionally for patches and deletes", and "`$ref_new` references are given a `null` value for all attributes"
+ *  (https://turbopuffer.com/docs/write, delete_condition). */
+function conditionalDelete(ns: NamespaceState, id: string | number, passes: (current: Doc, next: Record<string, unknown>) => boolean): boolean {
+  const current = ns.docs.get(docKey(id));
+  return current !== undefined && passes(current, {});
+}
+
+/** A write's condition (https://turbopuffer.com/docs/write, Conditional writes): "The condition syntax matches the
+ *  filters parameter in the query API, with an additional feature: you can reference the new value being written using
+ *  $ref_new references", evaluated "using the current value of the document with the matching ID". For deletes,
+ *  "`$ref_new` references are given a `null` value for all attributes". Undefined when the body sets none. */
+function conditionOf(ns: NamespaceState, body: Record<string, unknown>, key: string): ((current: Doc, next: Record<string, unknown>) => boolean) | undefined {
+  const cond = body[key];
+  if (cond === undefined) return undefined;
+  if (!Array.isArray(cond)) throw badRequest(`invalid ${key}: expected a filter`);
+  const resolve = (node: unknown, next: Record<string, unknown>): unknown => {
+    if (Array.isArray(node)) return node.map((n) => resolve(n, next));
+    if (node !== null && typeof node === 'object') {
+      const ref = (node as Record<string, unknown>).$ref_new;
+      if (Object.keys(node).length !== 1 || typeof ref !== 'string') throw badRequest(`invalid ${key}: an object in a condition must be {"$ref_new": "<attribute>"}`);
+      return next[ref] ?? null;
+    }
+    return node;
+  };
+  compileFilter(resolve(cond, {}), { schema: ns.schema, tokenCache: new Map() }); // a condition that does not parse refuses the write
+  return (current, next) => compileFilter(resolve(cond, next), { schema: ns.schema, tokenCache: new Map() })(current);
+}
+
+function mergeSchema(ns: NamespaceState, attr: string, raw: unknown, creating = false): void {
+  if (attr === 'id') return mergeIdSchema(ns, raw);
+  const next = normalizeAttrSchema(attr, raw);
+  const prev = ns.schema[attr];
+  const embed = raw !== null && typeof raw === 'object' && !Array.isArray(raw) && 'embed' in (raw as object) ? (raw as Record<string, unknown>).embed : undefined;
+  if (embed === undefined) { if (prev?.embed) next.embed = prev.embed; } else embedSchema(ns, attr, next, prev, embed, creating);
+  if (prev !== undefined && prev.type !== next.type) throw badRequest(`invalid schema for attribute "${attr}": cannot change type from ${prev.type} to ${next.type}`);
+  if (attr === 'vector' || isVectorType(next.type)) {
+    const dims = dimsOf(next.type);
+    // "Vector attributes require an ANN index, configured via the `ann` schema parameter"; `ann` "Must be set to `true`
+    // for vector type attributes" (https://turbopuffer.com/docs/write)
+    const ann = raw !== null && typeof raw === 'object' ? (raw as Record<string, unknown>).ann : undefined;
+    if (ann !== true && (ann === null || typeof ann !== 'object')) throw badRequest(`invalid schema for attribute "${attr}": vector attributes require ann: true`);
+    if (attr === 'vector') {
+      if (ns.vector_dims !== null && ns.vector_dims !== dims) throw badRequest(`invalid schema: vector has ${ns.vector_dims} dimensions, not ${dims}`);
+      ns.vector_dims = dims;
+    // "Vector columns must be declared in the schema and are fixed at namespace creation time" (Multiple vector columns)
+    } else if (prev === undefined && !creating) throw badRequest(`invalid schema for attribute "${attr}": vector columns are fixed at namespace creation time`);
+    if (next.ann_distance_metric !== undefined) annMetric(ns, next.ann_distance_metric);
+    delete next.ann_distance_metric;
+  }
+  ns.schema[attr] = next;
+}
+
+// "Document IDs are unsigned 64-bit integers, 128-bit UUIDs, or strings up to 64 bytes" and a UUID id "must be set
+// explicitly in the schema" (https://turbopuffer.com/docs/write: `"id": "uuid"` in its Configuring the schema example);
+// "All attributes are nullable, except for `id`". The id's type is otherwise the first document's: `uint` for a number
+// (the Namespace metadata example answers `"id": {"type": "uint"}`), `string` for a string.
+const ID_TYPES = ['uint', 'uuid', 'string'];
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function mergeIdSchema(ns: NamespaceState, raw: unknown): void {
+  const type = typeof raw === 'string' ? raw : raw !== null && typeof raw === 'object' && !Array.isArray(raw) ? (raw as Record<string, unknown>).type : undefined;
+  if (typeof type !== 'string' || !ID_TYPES.includes(type)) throw badRequest(`invalid schema for attribute "id": type must be one of ${ID_TYPES.join(', ')}`);
+  const prev = ns.schema.id;
+  if (prev !== undefined && prev.type !== type) throw badRequest(`invalid schema for attribute "id": cannot change type from ${prev.type} to ${type}`);
+  ns.schema.id = { type, filterable: true, full_text_search: false };
+}
+
+/** An id against the namespace's id type, which the first document sets when no schema did. */
+function checkIdType(ns: NamespaceState, id: string | number, where: string): void {
+  const declared = ns.schema.id?.type;
+  if (declared === undefined) { ns.schema.id = { type: typeof id === 'number' ? 'uint' : 'string', filterable: true, full_text_search: false }; return; }
+  const ok = declared === 'uint' ? typeof id === 'number' : declared === 'uuid' ? typeof id === 'string' && UUID.test(id) : typeof id === 'string';
+  if (!ok) throw badRequest(`invalid ${where}: the id ${JSON.stringify(id)} is not of the namespace's id type ${declared}`);
+}
+
+// ── native embedding ──────────────────────────────────────────────────────────────────────
+// https://turbopuffer.com/docs/embedding and /docs/write (embed): "use the `embed` property on an attribute's schema to
+// specify an embedding model. Writes and queries to that attribute are turned into vectors on the fly." `embed` "Can
+// only be set on `string` fields", and is a model name or {model, attribute?, dims?, dtype?}: `attribute` is "The
+// vector attribute that stores embedding vectors for this field. If omitted, turbopuffer creates a computed vector
+// attribute named `embed_<attribute>`. … Required when enabling embedding on an existing attribute"; `dims` "If not set,
+// will use the model's default dimensionality. … Must match the size of the vector specified in `attribute`". `embed`
+// "can be added or removed, but not modified", and `null` removes it ("any future write to this namespace requires
+// writing the embed_text vector"). "With `embed` set, you can still provide a vector yourself. Each row that includes
+// a vector is stored as-is, and rows with no vector have one computed". A query ranks by `["Embed", text, {model?}]`
+// under ANN or kNN; `model` is "Required when using the `Embed` function to rank a vector attribute with native
+// embedding, optional when ranking a source attribute that has `embed` set in the schema".
+// Where the docs stop and the twin decides: an embedding is a labelled placeholder, not a model's output (the twin runs
+// no model): a unit vector derived from the model's name and the text, the same for a document and a query of the same
+// text, so ANN over it ranks by nothing a model knows; the models are the Embedding page's and its changelog's, and a
+// model's default dimensions, which the page shows only on request, are 1024 (the dims every example on the page
+// names); a stored vector is f32; the tokens embedded, which the page says both answers carry, are not answered, since
+// no page names their field.
+export const EMBEDDING_MODELS = [
+  'baai/bge-m3', 'cohere/embed-v4.0', 'google/gemini-embedding-2', 'nvidia/nemotron-3-embed-1b', 'nvidia/nemotron-3-embed-8b',
+  'openai/text-embedding-3-large', 'openai/text-embedding-3-small', 'openai/text-embedding-ada-002', 'qwen/qwen3-embedding-0p6b',
+  'qwen/qwen3-embedding-4b', 'qwen/qwen3-embedding-8b', 'voyage/voyage-4', 'voyage/voyage-4-large', 'voyage/voyage-4-lite',
+  'voyage/voyage-4-nano', 'voyage/voyage-code-3', 'voyage/voyage-code-4', 'zeroentropy/zembed-1',
+  // deprecated, still available (https://turbopuffer.com/docs/embedding/changelog, August 2026)
+  'cohere/embed-english-v3.0', 'google/gemini-embedding-001', 'google/text-embedding-005', 'voyage/voyage-3-large', 'voyage/voyage-3.5', 'voyage/voyage-3.5-lite',
+];
+const DEFAULT_EMBED_DIMS = 1024;
+const sha256Bytes = (s: string): Buffer => createHash('sha256').update(s).digest();
+
+function checkModel(model: unknown): string {
+  if (typeof model !== 'string' || !EMBEDDING_MODELS.includes(model)) throw badRequest(`invalid embed: unknown embedding model ${JSON.stringify(model)}`);
+  return model;
+}
+
+function embedSchema(ns: NamespaceState, attr: string, next: AttrConfig, prev: AttrConfig | undefined, raw: unknown, creating: boolean): void {
+  if (raw === null) { delete next.embed; return; }
+  if (next.type !== 'string') throw badRequest(`invalid schema for attribute "${attr}": embed can only be set on string fields`);
+  const cfg = typeof raw === 'string' ? { model: raw } : raw !== null && typeof raw === 'object' && !Array.isArray(raw) ? raw as Record<string, unknown> : undefined;
+  if (!cfg || Object.keys(cfg).some((k) => !['model', 'attribute', 'dims', 'dtype'].includes(k))) throw badRequest(`invalid schema for attribute "${attr}": embed is a model name or { model, attribute, dims, dtype }`);
+  const model = checkModel(cfg.model);
+  if (prev?.embed) { next.embed = keptEmbed(prev.embed, model, cfg, attr); return; }
+  const existingAttr = prev !== undefined || (!creating && [...ns.docs.values()].some((d) => d.attributes[attr] !== undefined));
+  if (existingAttr && cfg.attribute === undefined) throw badRequest(`invalid schema for attribute "${attr}": attribute is required when enabling embedding on an existing attribute`);
+  const target = typeof cfg.attribute === 'string' ? cfg.attribute : `embed_${attr}`;
+  if (cfg.dtype !== undefined && cfg.dtype !== 'f32') throw badRequest(`invalid schema for attribute "${attr}": the twin stores embeddings as f32`);
+  const column = target === 'vector' ? (ns.vector_dims !== null ? `[${ns.vector_dims}]f32` : undefined) : ns.schema[target]?.type;
+  const dims = typeof cfg.dims === 'number' ? cfg.dims : column ? dimsOf(column) : DEFAULT_EMBED_DIMS;
+  if (column !== undefined && dimsOf(column) !== dims) throw badRequest(`invalid schema for attribute "${attr}": dims ${dims} does not match the size of "${target}" (${column})`);
+  if (column === undefined) {
+    if (target === 'vector') { ns.vector_dims = dims; ns.schema.vector = { type: `[${dims}]f32`, filterable: false, full_text_search: false }; }
+    else ns.schema[target] = { type: `[${dims}]f32`, filterable: false, full_text_search: false };
+  }
+  next.embed = { model, attribute: target, dims };
+}
+
+/** An `embed` sent again for an attribute that has one: "embed (can be added or removed, but not modified)"
+ *  (https://turbopuffer.com/docs/write, Updating attributes). */
+function keptEmbed(prev: NonNullable<AttrConfig['embed']>, model: string, cfg: Record<string, unknown>, attr: string): NonNullable<AttrConfig['embed']> {
+  if (prev.model !== model || (cfg.attribute !== undefined && cfg.attribute !== prev.attribute)) throw badRequest(`invalid schema for attribute "${attr}": embed can be added or removed, but not modified`);
+  return prev;
+}
+
+/** The placeholder embedding of a text: a unit vector of `dims` derived from the model's name and the text. */
+export function placeholderEmbedding(model: string, text: string, dims: number): number[] {
+  const out: number[] = [];
+  let block = new Uint8Array();
+  for (let i = 0; out.length < dims; i++) {
+    if (i % 8 === 0) block = new Uint8Array(sha256Bytes(`${model}\u0000${text}\u0000${i / 8}`));
+    const j = (i % 8) * 4;
+    out.push(((block[j]! << 8 | block[j + 1]!) / 65535) * 2 - 1);
+  }
+  const norm = Math.sqrt(out.reduce((n, x) => n + x * x, 0)) || 1;
+  return out.map((x) => x / norm);
+}
+
+/** Fill each embedded attribute's vector where the row sent none ("rows with no vector have one computed"). */
+function embedRow(ns: NamespaceState, d: Doc): void {
+  for (const [attr, c] of Object.entries(ns.schema)) {
+    if (!c.embed) continue;
+    const text = d.attributes[attr];
+    if (typeof text !== 'string') continue;
+    const target = c.embed.attribute;
+    if (target === 'vector') { if (d.vector === null) d.vector = placeholderEmbedding(c.embed.model, text, c.embed.dims); }
+    else if (d.attributes[target] === undefined) d.attributes[target] = placeholderEmbedding(c.embed.model, text, c.embed.dims);
+  }
+}
+
+function checkVector(ns: NamespaceState, v: unknown, where: string): number[] {
+  if (typeof v === 'string') throw badRequest(`turbopuffer twin: base64-encoded vectors are not modelled (turbopuffer.vectors.base64 is the filed gap)`);
+  if (!Array.isArray(v) || v.length === 0 || !v.every((x) => typeof x === 'number' && Number.isFinite(x))) throw badRequest(`invalid ${where}: vector must be a non-empty array of finite numbers`);
+  if (ns.distance_metric === null) throw badRequest(`invalid ${where}: distance_metric is required when writing vectors`);
+  if (ns.vector_dims === null) {
+    ns.vector_dims = v.length;
+    ns.schema.vector = { type: `[${v.length}]f32`, filterable: false, full_text_search: false };
+  } else if (v.length !== ns.vector_dims) throw badRequest(`invalid ${where}: vector has ${v.length} dimensions, but the namespace has ${ns.vector_dims}`);
+  return v as number[];
+}
+
+function checkAttribute(ns: NamespaceState, attr: string, v: unknown, where: string): void {
+  const declared = ns.schema[attr];
+  if (declared !== undefined && isVectorType(declared.type)) { checkVectorValue(declared.type, attr, v, where); return; }
+  if (declared !== undefined && isVectorArrayType(declared.type)) {
+    // "Every vector in the array must have the same dimensionality (`N`)" (https://turbopuffer.com/docs/query, Late interaction)
+    if (!Array.isArray(v)) throw badRequest(`invalid ${where}: attribute "${attr}" is ${declared.type}, an array of vectors`);
+    for (const x of v) checkVectorValue(declared.type.slice(2), attr, x, where);
+    return;
+  }
+  if (attr.startsWith('$')) throw badRequest(`invalid ${where}: attribute names may not start with "$" ("${attr}")`);
+  if (attr.length > 128) throw badRequest(`invalid ${where}: attribute name "${attr.slice(0, 32)}…" is longer than 128 characters`);
+  let config = ns.schema[attr];
+  if (config === undefined) {
+    const inferred = inferType(v);
+    if (inferred === null) throw badRequest(`invalid ${where}: attribute "${attr}" has an unsupported value ${JSON.stringify(v).slice(0, 80)}`);
+    config = { type: inferred, filterable: true, full_text_search: false };
+    ns.schema[attr] = config;
+  }
+  if (!valueMatchesType(v, config.type)) throw badRequest(`invalid ${where}: attribute "${attr}" has type ${config.type}, but the value ${JSON.stringify(v).slice(0, 80)} does not match it`);
+}
+
+/** `ann: {distance_metric}` (the spec's AnnConfig): the namespace's metric, which "will apply to all vector columns
+ *  configured for this namespace" (https://turbopuffer.com/docs/write, distance_metric). */
+function annMetric(ns: NamespaceState, metric: string): void {
+  if (ns.distance_metric !== null && ns.distance_metric !== metric) throw badRequest(`invalid schema: namespace uses distance_metric ${ns.distance_metric}, not ${metric}`);
+  ns.distance_metric = metric;
+}
+
+/** A value of a vector column: "encoded as either a JSON array of numbers, or as a base64-encoded string", and "Elements
+ *  of a vector attribute must have the same number of dimensions" (https://turbopuffer.com/docs/write, Vectors). The
+ *  twin keeps the numbers as sent, its reading: the docs do not say how an f16 or i8 column answers a value read back.
+ *  An i8 element is an integer from -128 to 127, the twin's reading of the type's name. */
+function checkVectorValue(type: string, attr: string, v: unknown, where: string): void {
+  if (typeof v === 'string') throw badRequest(`turbopuffer twin: base64-encoded vectors are not modelled (turbopuffer.vectors.base64 is the filed gap)`);
+  const dims = dimsOf(type);
+  if (!Array.isArray(v) || v.length !== dims || !v.every((x) => typeof x === 'number' && Number.isFinite(x))) throw badRequest(`invalid ${where}: attribute "${attr}" must be ${dims} numbers (${type})`);
+  if (type.endsWith('i8') && !v.every((x) => Number.isInteger(x) && x >= -128 && x <= 127)) throw badRequest(`invalid ${where}: attribute "${attr}" is ${type}, so each element must be an integer from -128 to 127`);
+}
+
+/** "A namespace may or may not have vector indexes. If it does, all documents must include all vector attributes"
+ *  (https://turbopuffer.com/docs/write, upsert_rows). */
+function checkAllVectors(ns: NamespaceState, d: Doc, where: string): void {
+  for (const [attr, c] of Object.entries(ns.schema)) {
+    if (!isVectorType(c.type)) continue;
+    const has = attr === 'vector' ? d.vector !== null : d.attributes[attr] !== undefined;
+    if (!has) throw badRequest(`invalid ${where}: every document must include every vector attribute, and ${JSON.stringify(d.id)} has no "${attr}"`);
+  }
+}
+
+function buildDoc(ns: NamespaceState, row: Record<string, unknown>, where: string): Doc {
+  const id = assertId(row.id, where);
+  checkIdType(ns, id, where);
+  const attributes: Record<string, unknown> = {};
+  let vector: number[] | null = null;
+  for (const [k, v] of Object.entries(row)) {
+    if (k === 'id') continue;
+    if (k === 'vector') { if (v !== null && v !== undefined) vector = checkVector(ns, v, where); continue; }
+    if (v === null || v === undefined) continue; // null is "no value" — the attribute is absent
+    checkAttribute(ns, k, v, where);
+    attributes[k] = v;
+  }
+  return { key: docKey(id), id, attributes, vector };
+}
+
+function patchDoc(ns: NamespaceState, d: Doc, patch: Record<string, unknown>): Doc {
+  const attributes = { ...d.attributes };
+  let vector = d.vector;
+  for (const [k, v] of Object.entries(patch)) {
+    if (k === 'vector') { vector = v === null ? null : checkVector(ns, v, 'patch'); continue; }
+    if (v === null || v === undefined) { delete attributes[k]; continue; }
+    checkAttribute(ns, k, v, 'patch');
+    attributes[k] = v;
+  }
+  return { ...d, attributes, vector };
+}
+
+// ── queries ─────────────────────────────────────────────────────────────────────────────────
+
+const QUERY_KEYS = new Set(['group_by', 'rank_by', 'filters', 'top_k', 'limit', 'include_attributes', 'exclude_attributes', 'aggregate_by', 'consistency', 'distance_metric', 'vector_encoding']);
+const UNMODELED_QUERY_KEYS: Record<string, string> = {
+  compute_attributes: 'turbopuffer.query.compute_attributes',
+};
+
+type Ranked = { doc: Doc; dist?: number };
+
+export type QueryResult = { rows?: Record<string, unknown>[]; aggregations?: Record<string, unknown>; aggregation_groups?: Record<string, unknown>[] };
+
+/** `vector_encoding` other than float: "base64" is documented ("The encoding to use for vectors in the response", the
+ *  spec's VectorEncoding) and not modelled; anything else is refused. */
+export function vectorEncodingRefusal(v: unknown): TurbopufferError {
+  return v === 'base64' ? gap('vector_encoding "base64"', 'turbopuffer.vectors.base64') : badRequest('invalid query: vector_encoding must be "float" or "base64"');
+}
+
+function gap(what: string, id: string): TurbopufferError {
+  return badRequest(`turbopuffer twin: ${what} is real Turbopuffer surface this twin does not model yet (${id} is the filed gap)`);
+}
+
+/** Answer one query (the body of `POST /v2/namespaces/{ns}/query`, or one of `queries[]`). Pure. */
+export function runQuery(ns: NamespaceState, rawQuery: unknown, opts: { multi?: boolean } = {}): QueryResult {
+  if (rawQuery === null || typeof rawQuery !== 'object' || Array.isArray(rawQuery)) throw badRequest('invalid query: expected a JSON object');
+  const q = rawQuery as Record<string, unknown>;
+  for (const k of Object.keys(q)) {
+    const g = UNMODELED_QUERY_KEYS[k];
+    if (g !== undefined) throw gap(`the query parameter "${k}"`, g);
+    if (!QUERY_KEYS.has(k) || (opts.multi && (k === 'consistency' || k === 'vector_encoding'))) throw badRequest(`invalid query: unknown field "${k}"`);
+  }
+  if (q.vector_encoding !== undefined && q.vector_encoding !== 'float') throw vectorEncodingRefusal(q.vector_encoding);
+  checkConsistency(q.consistency);
+  const ctx: FilterContext = { schema: ns.schema, tokenCache: new Map() };
+  const pred = q.filters === undefined || q.filters === null ? () => true : compileFilter(q.filters, ctx);
+  const matched = [...ns.docs.values()].filter(pred);
+
+  if (q.group_by !== undefined && q.aggregate_by === undefined) throw badRequest('invalid query: group_by is only valid when aggregate_by is set');
+  if (q.aggregate_by !== undefined) {
+    // "Cannot be specified with rank_by or include_attributes" (https://turbopuffer.com/docs/query, aggregate_by)
+    if (q.rank_by !== undefined || q.include_attributes !== undefined) throw badRequest('invalid query: aggregate_by cannot be specified with rank_by or include_attributes');
+    if (q.group_by !== undefined) return { aggregation_groups: groupAggregate(q.aggregate_by, q.group_by, matched, q.limit === undefined && q.top_k === undefined ? MAX_GROUPS : resolveLimit(q.top_k, q.limit)) };
+    return { aggregations: aggregate(q.aggregate_by, matched) };
+  }
+  // The Query page lists rank_by "required unless aggregate_by is set", but the Quickstart's runnable example sends a
+  // query with only `filters` and `limit` (`"filters": ["text", "Regex", "\\w+fish"]`), and "To find all documents
+  // matching filters when order isn't important to you, rank by the `id` attribute" (Lookups): the twin answers a query
+  // with neither as that lookup, in id order, its reading of the two pages.
+  const rankBy = q.rank_by ?? ['id', 'asc'];
+
+  const per = limitPer(q.limit);
+  const limit = resolveLimit(q.top_k, q.limit);
+  const ranked = rank(ns, rankBy, matched, ctx, q.distance_metric);
+  const rows = diversify(ranked, per, limit).map((r) => projectRow(r, q.include_attributes, q.exclude_attributes));
+  return { rows };
+}
+
+export function checkConsistency(c: unknown): void {
+  if (c === undefined) return;
+  if (c === null || typeof c !== 'object' || Array.isArray(c)) throw badRequest('invalid query: consistency must be an object');
+  const level = (c as Record<string, unknown>).level;
+  // The twin is always strongly consistent, which satisfies both levels.
+  if (level !== undefined && level !== 'strong' && level !== 'eventual') throw badRequest('invalid query: consistency.level must be "strong" or "eventual"');
+}
+
+function resolveLimit(topK: unknown, limit: unknown): number {
+  let n: unknown = topK;
+  if (limit !== undefined) {
+    if (typeof limit === 'object' && limit !== null && !Array.isArray(limit)) {
+      const l = limit as Record<string, unknown>;
+      n = l.total;
+    } else n = limit;
+  }
+  if (n === undefined) return 10;
+  if (typeof n !== 'number' || !Number.isInteger(n) || n < 1) throw badRequest('invalid query: top_k / limit must be a positive integer');
+  return n;
+}
+
+/** `limit.per` (https://turbopuffer.com/docs/query): "limits the number of documents with the same value for a set of
+ *  attributes (the "limit key") that can appear in the results", with `attributes` and `limit`. */
+function limitPer(limit: unknown): { attributes: string[]; limit: number } | undefined {
+  if (limit === null || typeof limit !== 'object' || Array.isArray(limit)) return undefined;
+  const per = (limit as Record<string, unknown>).per;
+  if (per === undefined) return undefined;
+  const p = per as Record<string, unknown>;
+  if (per === null || typeof per !== 'object' || !Array.isArray(p.attributes) || !p.attributes.every((a) => typeof a === 'string') || typeof p.limit !== 'number' || !Number.isInteger(p.limit) || p.limit < 1) throw badRequest('invalid query: limit.per must be { attributes: string[], limit: positive integer }');
+  return { attributes: p.attributes as string[], limit: p.limit };
+}
+
+/** The ranked documents in order, at most `per.limit` for each value of the limit key, until `total`. */
+function diversify(ranked: Ranked[], per: { attributes: string[]; limit: number } | undefined, total: number): Ranked[] {
+  if (!per) return ranked.slice(0, total);
+  const seen = new Map<string, number>();
+  const out: Ranked[] = [];
+  for (const r of ranked) {
+    if (out.length >= total) break;
+    const key = JSON.stringify(per.attributes.map((a) => attributeValue(r.doc, a)));
+    const n = seen.get(key) ?? 0;
+    if (n >= per.limit) continue;
+    seen.set(key, n + 1);
+    out.push(r);
+  }
+  return out;
+}
+
+/** "Max aggregation groups per query: 10k" (https://turbopuffer.com/docs/limits). */
+const MAX_GROUPS = 10_000;
+
+/** `group_by` (https://turbopuffer.com/docs/query): "Groups documents by the specified attributes or expressions (the
+ *  "group key") before computing aggregates. Aggregates are computed separately for each group. Up to limit.total
+ *  groups are returned, ordered by group key." An entry is an attribute name, or `{label: ["ForEachUnique", attr]}`,
+ *  which "creates a separate group for each unique element of the array". Answered as `aggregation_groups`: "one for
+ *  each aggregation group, containing the group key and the computed value of each requested aggregation".
+ *  Where the docs stop and the twin decides: a document whose grouping attribute is absent is grouped under null, and
+ *  null sorts first; with no limit every group is answered, up to the 10k limit. */
+function groupAggregate(spec: unknown, groupBy: unknown, docs: Doc[], limit: number): Record<string, unknown>[] {
+  if (!Array.isArray(groupBy) || groupBy.length === 0) throw badRequest('invalid query: group_by must be a non-empty array');
+  const keys = groupBy.map((g) => {
+    if (typeof g === 'string') return { label: g, attr: g, each: false };
+    const entries = g !== null && typeof g === 'object' && !Array.isArray(g) ? Object.entries(g as Record<string, unknown>) : [];
+    const [label, expr] = entries[0] ?? [];
+    if (entries.length !== 1 || !Array.isArray(expr) || expr[0] !== 'ForEachUnique' || typeof expr[1] !== 'string') throw badRequest(`invalid group_by entry ${JSON.stringify(g)}: expected an attribute name or {label: ["ForEachUnique", attribute]}`);
+    return { label: label!, attr: expr[1], each: true };
+  });
+  const groups = new Map<string, { key: unknown[]; docs: Doc[] }>();
+  for (const d of docs) {
+    let tuples: unknown[][] = [[]];
+    for (const k of keys) {
+      const v = attributeValue(d, k.attr);
+      const values = k.each ? (Array.isArray(v) ? [...new Map(v.map((x) => [JSON.stringify(x), x])).values()] : []) : [v];
+      tuples = tuples.flatMap((t) => values.map((x) => [...t, x]));
+    }
+    for (const t of tuples) {
+      const id = JSON.stringify(t);
+      const g = groups.get(id) ?? { key: t, docs: [] };
+      g.docs.push(d);
+      groups.set(id, g);
+    }
+  }
+  // an array value (a group key of an array attribute, the Quickstart's `"category": ["fish"]`) orders element by element
+  const one = (x: unknown, y: unknown): number => (x === null && y === null ? 0 : x === null ? -1 : y === null ? 1 : Array.isArray(x) || Array.isArray(y) ? compareArrays(x, y) : compareScalars(x, y));
+  const order = (a: unknown[], b: unknown[]): number => a.map((x, i) => one(x, b[i])).find((c) => c !== 0 && !Number.isNaN(c)) ?? 0;
+  function compareArrays(x: unknown, y: unknown): number {
+    const xs = Array.isArray(x) ? x : [x]; const ys = Array.isArray(y) ? y : [y];
+    for (let i = 0; i < Math.min(xs.length, ys.length); i++) { const c = compareScalars(xs[i], ys[i]); if (c !== 0 && !Number.isNaN(c)) return c; }
+    return xs.length - ys.length;
+  }
+  return [...groups.values()].sort((a, b) => order(a.key, b.key)).slice(0, limit)
+    .map((g) => ({ ...Object.fromEntries(keys.map((k, i) => [k.label, g.key[i] ?? null])), ...aggregate(spec, g.docs) }));
+}
+
+function aggregate(spec: unknown, docs: Doc[]): Record<string, unknown> {
+  if (spec === null || typeof spec !== 'object' || Array.isArray(spec)) throw badRequest('invalid query: aggregate_by must be an object');
+  const out: Record<string, unknown> = {};
+  for (const [label, fn] of Object.entries(spec as Record<string, unknown>)) {
+    if (!Array.isArray(fn) || fn.length === 0) throw badRequest(`invalid aggregate "${label}": expected ["Count"], ["Count", attr] or ["Sum", attr]`);
+    if (fn[0] === 'Count' && fn.length === 1) out[label] = docs.length;
+    else if (fn[0] === 'Count' && fn.length === 2 && typeof fn[1] === 'string') out[label] = docs.filter((d) => attributeValue(d, fn[1] as string) !== null).length;
+    else if (fn[0] === 'Sum' && fn.length === 2 && typeof fn[1] === 'string') {
+      let sum = 0;
+      // Summed in id order, so every root folds the same floats in the same order.
+      for (const d of [...docs].sort((a, b) => compareIds(a.id, b.id))) { const v = attributeValue(d, fn[1] as string); if (typeof v === 'number') sum += v; }
+      out[label] = sum;
+    } else throw badRequest(`invalid aggregate "${label}": expected ["Count"], ["Count", attr] or ["Sum", attr]`);
+  }
+  return out;
+}
+
+function compareIds(a: string | number, b: string | number): number {
+  if (typeof a === 'number' && typeof b === 'number') return a - b;
+  if (typeof a === 'number') return -1;
+  if (typeof b === 'number') return 1;
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+function rank(ns: NamespaceState, rankBy: unknown, docs: Doc[], ctx: FilterContext, metric: unknown): Ranked[] {
+  if (!Array.isArray(rankBy) || rankBy.length === 0) throw badRequest(`invalid rank_by: ${JSON.stringify(rankBy)}`);
+  // [[attr, 'asc'|'desc'], ...] — multi-attribute order.
+  if (Array.isArray(rankBy[0])) return orderBy(rankBy as unknown[], docs);
+  if (rankBy.length === 2 && (rankBy[1] === 'asc' || rankBy[1] === 'desc')) return orderBy([rankBy], docs);
+  if (rankBy[1] === 'ANN' || rankBy[1] === 'kNN') return nearest(ns, rankBy, docs, metric);
+  // Text ranking: BM25 clauses and their Sum / Max / Product combinators.
+  const corpora = new Map<string, Corpus>();
+  const scorer = textScorer(ns, rankBy, ctx, corpora);
+  const out: Ranked[] = [];
+  for (const d of docs) {
+    const s = scorer(d);
+    if (s !== 0) out.push({ doc: d, dist: s }); // "Documents with a score of zero are excluded from results"
+  }
+  return out.sort((a, b) => (b.dist! - a.dist!) || compareIds(a.doc.id, b.doc.id));
+}
+
+function textScorer(ns: NamespaceState, clause: unknown, ctx: FilterContext, corpora: Map<string, Corpus>): (d: Doc) => number {
+  if (!Array.isArray(clause) || clause.length < 2) throw badRequest(`invalid rank_by clause: ${JSON.stringify(clause)}`);
+  if (clause[0] === 'Sum' || clause[0] === 'Max') {
+    if (!Array.isArray(clause[1]) || clause[1].length === 0) throw badRequest(`invalid rank_by: ${clause[0]} takes a non-empty array of clauses`);
+    const parts = (clause[1] as unknown[]).map((c) => textScorer(ns, c, ctx, corpora));
+    return clause[0] === 'Sum' ? (d) => parts.reduce((n, p) => n + p(d), 0) : (d) => Math.max(...parts.map((p) => p(d)));
+  }
+  if (clause[0] === 'Product') {
+    const [w, inner] = typeof clause[1] === 'number' ? [clause[1], clause[2]] : [clause[2], clause[1]];
+    if (typeof w !== 'number') throw badRequest('invalid rank_by: Product takes a number and a clause');
+    const part = textScorer(ns, inner, ctx, corpora);
+    return (d) => w * part(d);
+  }
+  // SparseKNN (https://turbopuffer.com/docs/query): "rank by the distance between a sparse vector attribute and a sparse
+  // vector query", with the attribute's `dot_product` metric, and "compatible with FTS operators: Sum, Max". A larger dot
+  // product ranks higher, and "Documents with a score of zero are excluded from results".
+  if (clause[1] === 'SparseKNN') {
+    const [attr, , q] = clause;
+    const cfg = typeof attr === 'string' ? ns.schema[attr] : undefined;
+    if (cfg === undefined || cfg.type !== '{}f16' || cfg.sparse_knn === undefined) throw badRequest(`invalid rank_by: SparseKNN needs a {}f16 attribute with sparse_knn configured, not ${JSON.stringify(attr)}`);
+    if (q === null || typeof q !== 'object' || Array.isArray(q) || !Object.values(q).every((x) => typeof x === 'number')) throw badRequest('invalid rank_by: the SparseKNN query must be an object of numeric weights');
+    const query = Object.entries(q as Record<string, number>);
+    return (d) => {
+      const v = d.attributes[attr as string] as Record<string, number> | undefined;
+      return v ? query.reduce((n, [k, w]) => n + w * (v[k] ?? 0), 0) : 0;
+    };
+  }
+  if (clause[0] === 'Saturate' || clause[0] === 'Decay' || clause[0] === 'Dist' || clause[0] === 'Attribute') throw gap(`the ${clause[0]} rank_by expression`, 'turbopuffer.query.rank_expressions');
+  // "Rank by filter: Filters can be used inside rank_by expressions to conditionally boost documents matching certain
+  // criteria. Documents that pass the filter get a score of 1, and are otherwise scored 0" (https://turbopuffer.com/docs/query)
+  if (clause[0] === 'And' || clause[0] === 'Or' || clause[0] === 'Not' || (typeof clause[1] === 'string' && !['BM25', 'asc', 'desc', 'ANN', 'kNN'].includes(clause[1]))) {
+    const pass = compileFilter(clause, ctx);
+    return (d) => (pass(d) ? 1 : 0);
+  }
+  if (clause[1] !== 'BM25') throw rankClauseRefusal(clause);
+  const attr = clause[0];
+  if (typeof attr !== 'string') throw badRequest('invalid rank_by: BM25 needs an attribute name');
+  const config = ns.schema[attr];
+  if (config === undefined || config.full_text_search === false) throw badRequest(`invalid rank_by: attribute "${attr}" does not have full-text search enabled`);
+  const fts = config.full_text_search;
+  assertModelledFts(attr, fts);
+  const query = clause[2];
+  if (typeof query !== 'string' && !(Array.isArray(query) && query.every((x) => typeof x === 'string'))) throw badRequest('invalid rank_by: the BM25 query must be a string or an array of strings');
+  const params = (clause[3] ?? {}) as Record<string, unknown>;
+  if (typeof params !== 'object' || params === null || Array.isArray(params)) throw badRequest('invalid rank_by: BM25 params must be an object');
+  for (const k of Object.keys(params)) if (k !== 'last_as_prefix') throw badRequest(`invalid rank_by: unknown BM25 param "${k}"`);
+  const terms = queryTerms(query, fts, params.last_as_prefix === true);
+  let corpus = corpora.get(attr);
+  if (corpus === undefined) {
+    // IDF and average length are over the WHOLE namespace, not the filtered subset.
+    corpus = buildCorpus([...ns.docs.values()].map((d) => [d.key, attributeValue(d, attr)] as [string, unknown]), fts);
+    corpora.set(attr, corpus);
+  }
+  const c = corpus;
+  // Keep the shared token cache warm for any token filter in the same query.
+  return (d) => { docTokens(ctx, attr, fts, d); return bm25Score(d.key, c, terms, fts); };
+}
+
+/** A rank_by clause that is none of the kinds modelled: an attribute order inside a text expression (the Query page's
+ *  "Rank by attribute" uses the `Attribute` operator, not modelled), or no rank_by at all. */
+function rankClauseRefusal(clause: unknown[]): TurbopufferError {
+  return clause[1] === 'asc' || clause[1] === 'desc' ? gap('an attribute order inside a text rank expression', 'turbopuffer.query.rank_expressions') : badRequest(`invalid rank_by clause: ${JSON.stringify(clause)}`);
+}
+
+function nearest(ns: NamespaceState, rankBy: unknown[], docs: Doc[], metric: unknown): Ranked[] {
+  const [attrRaw, op, targetRaw] = rankBy;
+  let attr = attrRaw;
+  let target = targetRaw;
+  // ["Embed", text, {model?}]: the text embedded as the query vector (native embedding, above)
+  if (Array.isArray(targetRaw) && targetRaw[0] === 'Embed') {
+    const [, text, params] = targetRaw as [unknown, unknown, Record<string, unknown> | undefined];
+    if (typeof text !== 'string') throw badRequest('invalid rank_by: Embed takes the text to embed');
+    const source = typeof attr === 'string' ? ns.schema[attr] : undefined;
+    const model = params?.model !== undefined ? checkModel(params.model) : source?.embed?.model;
+    if (model === undefined) throw badRequest(`invalid rank_by: Embed on ${JSON.stringify(attr)} needs a model: the attribute has no embed configured`);
+    if (source?.embed) attr = source.embed.attribute;
+    const col = attr === 'vector' ? (ns.vector_dims !== null ? `[${ns.vector_dims}]f32` : undefined) : typeof attr === 'string' ? ns.schema[attr]?.type : undefined;
+    if (col === undefined || !isVectorType(col)) throw badRequest(`invalid rank_by: attribute ${JSON.stringify(attr)} is not a vector attribute`);
+    target = placeholderEmbedding(model, text, dimsOf(col));
+  }
+  const column = typeof attr === 'string' ? ns.schema[attr] : undefined;
+  if (column !== undefined && isVectorArrayType(column.type)) return lateInteraction(ns, attr as string, column, op, target, docs, metric);
+  if (typeof attr !== 'string' || (attr !== 'vector' && (column === undefined || !isVectorType(column.type)))) throw badRequest(`invalid rank_by: attribute ${JSON.stringify(attr)} is not a vector attribute`);
+  const dims = attr === 'vector' ? ns.vector_dims : dimsOf(column!.type);
+  const valueOf = (d: Doc): number[] | null => (attr === 'vector' ? d.vector : Array.isArray(d.attributes[attr]) ? d.attributes[attr] as number[] : null);
+  if (!Array.isArray(target) || !target.every((x) => typeof x === 'number')) throw badRequest('invalid rank_by: the ANN target must be a vector of numbers or ["Embed", text]');
+  const m = metric ?? ns.distance_metric;
+  if (m !== 'cosine_distance' && m !== 'euclidean_squared') throw badRequest('invalid query: the namespace has no distance_metric; write vectors with one first');
+  if (dims !== null && target.length !== dims) throw badRequest(`invalid query: the query vector has ${target.length} dimensions, but "${attr}" has ${dims}`);
+  const q = target as number[];
+  const out: Ranked[] = [];
+  for (const d of docs) {
+    const v = valueOf(d);
+    if (v === null || v.length !== q.length) continue;
+    out.push({ doc: d, dist: m === 'cosine_distance' ? cosineDistance(q, v) : euclideanSquared(q, v) });
+  }
+  return out.sort((a, b) => (a.dist! - b.dist!) || compareIds(a.doc.id, b.doc.id));
+}
+
+/** Late interaction (https://turbopuffer.com/docs/query): "Pass a query as an array of vectors with `ANN` to rank
+ *  documents with late interaction. … Each document's `$dist` is the sum of the distance from each query vector to its
+ *  closest vector in the document (lower is better), and results are ordered ascending"; `kNN` "for situations that
+ *  require perfect recall"; ANN needs the attribute's late-interaction index. The distance is the namespace's metric.
+ *  Where the docs stop and the twin decides: the feature "is in private beta. Contact us to enable late interaction for
+ *  your organization", and the twin enables it for every organization; ANN and kNN rank exactly alike here. */
+function lateInteraction(ns: NamespaceState, attr: string, column: AttrConfig, op: unknown, target: unknown, docs: Doc[], metric: unknown): Ranked[] {
+  if (op === 'ANN' && !column.late_interaction) throw badRequest(`invalid rank_by: attribute "${attr}" was stored with ann: false, so it takes kNN, not ANN`);
+  const dims = dimsOf(column.type.slice(2));
+  if (!Array.isArray(target) || target.length === 0 || !target.every((q) => Array.isArray(q) && q.length === dims && q.every((x) => typeof x === 'number'))) throw badRequest(`invalid rank_by: a late-interaction query is a non-empty array of ${dims}-dimensional vectors`);
+  const m = metric ?? ns.distance_metric;
+  if (m !== 'cosine_distance' && m !== 'euclidean_squared') throw badRequest('invalid query: the namespace has no distance_metric; write vectors with one first');
+  const dist = m === 'cosine_distance' ? cosineDistance : euclideanSquared;
+  const out: Ranked[] = [];
+  for (const d of docs) {
+    const vs = d.attributes[attr];
+    if (!Array.isArray(vs) || vs.length === 0) continue;
+    const score = (target as number[][]).reduce((n, q) => n + Math.min(...(vs as number[][]).map((v) => dist(q, v))), 0);
+    out.push({ doc: d, dist: score });
+  }
+  return out.sort((a, b) => (a.dist! - b.dist!) || compareIds(a.doc.id, b.doc.id));
+}
+
+export function cosineDistance(a: readonly number[], b: readonly number[]): number {
+  let dot = 0; let na = 0; let nb = 0;
+  for (let i = 0; i < a.length; i++) { dot += a[i]! * b[i]!; na += a[i]! * a[i]!; nb += b[i]! * b[i]!; }
+  const denom = Math.sqrt(na) * Math.sqrt(nb);
+  // turbopuffer's vectors are f32, so their similarity is taken at f32 precision: two equal vectors are distance 0, as
+  // the Query page's vector example answers (`{ "$dist": 0.0, "id": 1 }`), not a double's rounding residue
+  return denom === 0 ? 1 : 1 - Math.fround(dot / denom);
+}
+
+export function euclideanSquared(a: readonly number[], b: readonly number[]): number {
+  let s = 0;
+  for (let i = 0; i < a.length; i++) { const x = a[i]! - b[i]!; s += x * x; }
+  return s;
+}
+
+function orderBy(orders: unknown[], docs: Doc[]): Ranked[] {
+  const keys = orders.map((o) => {
+    if (!Array.isArray(o) || o.length !== 2 || typeof o[0] !== 'string' || (o[1] !== 'asc' && o[1] !== 'desc')) throw badRequest(`invalid rank_by: expected [attribute, "asc" | "desc"], got ${JSON.stringify(o)}`);
+    return { attr: o[0], dir: o[1] === 'asc' ? 1 : -1 };
+  });
+  // absent values sort last, in either direction; documents equal on every key order by id
+  const one = (a: Doc, b: Doc, attr: string, dir: number): number => {
+    const va = attributeValue(a, attr);
+    const vb = attributeValue(b, attr);
+    return va === null && vb === null ? 0 : va === null ? 1 : vb === null ? -1 : (attr === 'id' ? compareIds(va as string | number, vb as string | number) : compareScalars(va, vb)) * dir;
+  };
+  return docs.map((doc) => ({ doc })).sort((a, b) => keys.map(({ attr, dir }) => one(a.doc, b.doc, attr, dir)).find((c) => c !== 0 && !Number.isNaN(c)) ?? compareIds(a.doc.id, b.doc.id));
+}
+
+function projectRow(r: Ranked, include: unknown, exclude: unknown): Record<string, unknown> {
+  const row: Record<string, unknown> = { id: r.doc.id };
+  if (r.dist !== undefined) row.$dist = r.dist;
+  let names: string[] = [];
+  const all = [...Object.keys(r.doc.attributes), ...(r.doc.vector !== null ? ['vector'] : [])];
+  if (exclude !== undefined) {
+    if (!Array.isArray(exclude) || !exclude.every((x) => typeof x === 'string')) throw badRequest('invalid query: exclude_attributes must be an array of strings');
+    if (include !== undefined && include !== false) throw badRequest('invalid query: include_attributes and exclude_attributes cannot both be set');
+    names = all.filter((n) => !exclude.includes(n));
+  } else if (include === true) names = all;
+  else if (Array.isArray(include)) {
+    if (!include.every((x) => typeof x === 'string')) throw badRequest('invalid query: include_attributes must be a boolean or an array of strings');
+    names = include.filter((n) => n !== 'id');
+  } else if (include !== undefined && include !== false) throw badRequest('invalid query: include_attributes must be a boolean or an array of strings');
+  for (const n of names) {
+    if (n === 'vector') { if (r.doc.vector !== null) row.vector = r.doc.vector; continue; }
+    const v = r.doc.attributes[n];
+    row[n] = v === undefined ? null : v;
+  }
+  return row;
+}
+
+/** The wire form of a namespace's schema: every attribute with its full resolved config. */
+export function schemaWire(ns: NamespaceState): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [attr, c] of Object.entries(ns.schema)) {
+    if (attr === 'id') { out.id = { type: c.type }; continue; }
+    out[attr] = {
+      type: c.type,
+      ...(isVectorType(c.type) ? { ann: { distance_metric: ns.distance_metric } } : { filterable: c.filterable }),
+      ...(c.full_text_search !== false ? { full_text_search: c.full_text_search } : {}),
+      ...(c.glob ? { glob: true } : {}),
+      ...(c.regex ? { regex: true } : {}),
+      ...(c.fuzzy ? { fuzzy: true } : {}),
+      ...(c.sparse_knn ? { sparse_knn: c.sparse_knn } : {}),
+    };
+  }
+  return out;
+}
+
+export function queryBilling(ns: NamespaceState, returned: unknown): Record<string, number> {
+  return {
+    billable_logical_bytes_queried: approxLogicalBytes(ns),
+    billable_logical_bytes_returned: utf8Length(JSON.stringify(returned ?? null)),
+  };
+}
+
+export function queryPerformance(ns: NamespaceState): Record<string, unknown> {
+  return {
+    // "last_included_write_at (string): the timestamp of the last write operation that the query observed"
+    // (https://turbopuffer.com/docs/query, Response); the twin's queries observe every write
+    last_included_write_at: ns.last_write_at,
+    approx_namespace_size: ns.docs.size,
+    cache_hit_ratio: 1,
+    cache_temperature: 'hot',
+    exhaustive_search_count: 0,
+    query_execution_ms: 0,
+    server_total_ms: 0,
+  };
+}