@volter/twin-turbopuffer 0.1.0

package/src/turbopuffer-text.ts

@@ -0,0 +1,204 @@
+// FULL-TEXT SEARCH — the tokenizer and the BM25 scorer behind `rank_by: [attr, 'BM25', q]` and the
+// `ContainsAllTokens` / `ContainsAnyToken` filters.
+//
+// ── WHAT IS GROUNDED, AND WHERE THE EVIDENCE STOPS ──────────────────────────────────────────
+// Grounded in the installed `@turbopuffer/turbopuffer@2.8.0` (src/resources/namespaces.ts,
+// `FullTextSearchConfig`): the defaults — `k1` 1.2, `b` 0.75, case-insensitive, `language`
+// english, `stemming` false, `ascii_folding` false, `max_token_length` 39
+// BYTES (tokens longer are filtered out), and "by default, BM25-enabled attributes are not
+// filterable". `remove_stopwords` defaults to false: "Defaults to false (i.e. keep common words)"
+// (https://turbopuffer.com/docs/write, full_text_search) since "`remove_stopwords` now defaults to `false`"
+// (https://turbopuffer.com/docs/roadmap, January 2026); the spec's description, and the client's doc comment, still
+// say true. Grounded in Dub's provider (apps/web/lib/api/partners/search/providers/
+// turbopuffer.ts, measured against the real service): `word_v2` splits a URL into its
+// components (so `scottdigital` matches `https://www.scottdigital-42.techcorp.io`), and "a
+// single-token `last_as_prefix` query scores every match at exactly 1".
+//
+// EXTRAPOLATED (deterministic, not the vendor's exact algorithm): `word_v2` is modelled as
+// maximal runs of Unicode letters, digits, marks and `_`; the English stopword list is the
+// classic Lucene/tantivy 33-word list; BM25 is the textbook Okapi form with the Lucene IDF
+// `ln(1 + (N − n + 0.5)/(n + 0.5))` over the namespace's documents that carry the attribute, and a
+// `last_as_prefix` final token contributes a constant 1 per matching document. Scores are
+// therefore deterministic and ordered sensibly, but they are not byte-equal to Turbopuffer's.
+// Tokenizers other than `word_v2` and `pre_tokenized_array`, stemming, and non-English languages
+// are refused (400) rather than silently approximated.
+
+import { stemEnglish } from './turbopuffer-stem.ts';
+
+export const TOKENIZERS = ['pre_tokenized_array', 'word_v0', 'word_v1', 'word_v2', 'word_v3', 'word_v4'] as const;
+/** The tokenizers this twin models. Every other one in `TOKENIZERS` is refused with a 400. */
+export const MODELED_TOKENIZERS: readonly string[] = ['word_v4', 'word_v3', 'word_v2', 'pre_tokenized_array'];
+/** The vendor's default tokenizer (namespaces.ts: "Defaults to `word_v4`"). */
+export const DEFAULT_TOKENIZER = 'word_v4';
+
+export type FtsConfig = {
+  tokenizer: string;
+  case_sensitive: boolean;
+  remove_stopwords: boolean;
+  stemming: boolean;
+  ascii_folding: boolean;
+  language: string;
+  max_token_length: number;
+  k1: number;
+  b: number;
+  k3?: number;
+};
+
+export const DEFAULT_FTS: FtsConfig = {
+  tokenizer: DEFAULT_TOKENIZER,
+  case_sensitive: false,
+  remove_stopwords: false,
+  stemming: false,
+  ascii_folding: false,
+  language: 'english',
+  max_token_length: 39,
+  k1: 1.2,
+  b: 0.75,
+};
+
+const ENGLISH_STOPWORDS: ReadonlySet<string> = new Set([
+  'a', 'an', 'and', 'are', 'as', 'at', 'be', 'but', 'by', 'for', 'if', 'in', 'into', 'is', 'it', 'no', 'not',
+  'of', 'on', 'or', 'such', 'that', 'the', 'their', 'then', 'there', 'these', 'they', 'this', 'to', 'was',
+  'will', 'with',
+]);
+
+const WORD = /[\p{L}\p{N}\p{M}_]+/gu;
+const encoder = new TextEncoder();
+
+function normalizeToken(token: string, cfg: FtsConfig): string {
+  let t = cfg.case_sensitive ? token : token.toLowerCase();
+  if (cfg.ascii_folding) t = t.normalize('NFD').replace(/\p{M}+/gu, '');
+  return t;
+}
+
+/**
+ * Tokenize one value (a string, or a `[]string`, whose elements are tokenized and concatenated).
+ * `keepStopwords` is used for the final prefix token of a `last_as_prefix` query, which must not
+ * vanish because the user has so far typed only `an` of `anna`.
+ */
+export function tokenize(value: unknown, cfg: FtsConfig, opts: { keepStopwords?: boolean } = {}): string[] {
+  const parts: string[] = Array.isArray(value) ? value.filter((v): v is string => typeof v === 'string') : typeof value === 'string' ? [value] : [];
+  if (cfg.tokenizer === 'word_v4' || cfg.tokenizer === 'word_v3') return parts.flatMap((part) => uax29Tokens(part, cfg, opts));
+  const out: string[] = [];
+  for (const part of parts) {
+    const raw = cfg.tokenizer === 'pre_tokenized_array' ? [part] : (part.match(WORD) ?? []);
+    for (const r of raw) {
+      const t = normalizeToken(r, cfg);
+      if (t === '' || encoder.encode(t).length > cfg.max_token_length) continue;
+      if (cfg.remove_stopwords && !opts.keepStopwords && ENGLISH_STOPWORDS.has(t)) continue;
+      out.push(cfg.stemming ? stemEnglish(t) : t);
+    }
+  }
+  return out;
+}
+
+// ── word_v4 and word_v3 ─────────────────────────────────────────────────────────────────────
+// "The `word_v4` and `word_v3` tokenizers use Unicode v17.0 text segmentation rules (UAX #29) for accurate
+// segmentation across most languages, scripts, and emojis. `word_v4` is the current default for new namespaces; it
+// behaves like `word_v3`, but is roughly 3x faster and fixes a few tokenization edge cases. It's powered by our
+// open-source alyze library" (https://turbopuffer.com/docs/fts, Tokenizers). Modelled on alyze at
+// 1de437c8604b751f26e7061070b9d2b35aebdc73 (github.com/turbopuffer/alyze, src/analyze/mod.rs, src/uax29/word/mod.rs):
+// - word boundaries by UAX #29, and only "word-like" segments become tokens: a segment "is 'word-like' if it contains
+//   any char that is ALetter, HebrewLetter, or Numeric, Ideographic or Extended_Pictographic, Other_Number general
+//   category, [or] a character whose Script is something meaningful … as opposed to Script=Common/Inherited/Unknown";
+// - then, in alyze's order: the maximum token length (alyze admits a token within the limit in bytes or in
+//   characters, `s.len() <= max || s.chars().nth(max).is_none()`), lowercasing unless case_sensitive, stopword removal
+//   (the Lucene English list, as word_v2's), and ASCII folding, lowercased again.
+// Where the evidence stops: the twin segments with the host's Intl.Segmenter (ICU's UAX #29, with runs of ideographs
+// and hiragana split back into characters as UAX #29's rules leave them; ICU's dictionary segmentation of Thai, Lao,
+// Khmer and Burmese is kept, which alyze may not do), whose Unicode version is
+// the runtime's, not 17.0; alyze's own DFA may differ from ICU on edge cases, and the "few tokenization edge cases"
+// word_v4 fixes over word_v3 are not documented, so the two are one tokenizer here; ASCII folding strips combining
+// marks after NFD, where alyze's `ascii_fold` may map more characters (ß, æ).
+const segmenter = new Intl.Segmenter('und', { granularity: 'word' });
+const WORD_LIKE = /[\p{L}\p{Nd}\p{No}\p{Extended_Pictographic}\p{Ideographic}]|[^\p{Script=Common}\p{Script=Inherited}\p{Script=Unknown}]/u;
+
+function uax29Tokens(text: string, cfg: FtsConfig, opts: { keepStopwords?: boolean }): string[] {
+  const out: string[] = [];
+  // ICU joins runs of ideographs and hiragana by dictionary; UAX #29's rules break between them (neither is ALetter,
+  // and no rule joins them), so such a run is split back into its characters
+  const segments = [...segmenter.segment(text)].flatMap(({ segment }) => (/^[\p{Ideographic}\p{Script=Hiragana}]+$/u.test(segment) ? [...segment] : [segment]));
+  for (const segment of segments) {
+    if (!WORD_LIKE.test(segment)) continue;
+    if (!(encoder.encode(segment).length <= cfg.max_token_length || [...segment].length <= cfg.max_token_length)) continue;
+    let t = cfg.case_sensitive ? segment : segment.toLowerCase();
+    if (cfg.remove_stopwords && !opts.keepStopwords && ENGLISH_STOPWORDS.has(t)) continue;
+    if (cfg.stemming) t = stemEnglish(t);
+    out.push(cfg.ascii_folding && /[^\x00-\x7f]/.test(t) ? foldToken(t, cfg) : t);
+  }
+  return out;
+}
+
+/** alyze's ASCII folding of a non-ASCII token, lowercased again unless case_sensitive ("ASCII folding can produce
+ *  uppercase ASCII characters, so we'll lowercase again if case folding is enabled", alyze src/analyze/mod.rs). */
+function foldToken(t: string, cfg: FtsConfig): string {
+  const folded = t.normalize('NFD').replace(/\p{M}+/gu, '');
+  return cfg.case_sensitive ? folded : folded.toLowerCase();
+}
+
+/** A query's terms, split into the exact terms and the optional trailing prefix. */
+export type QueryTerms = { exact: string[]; prefix: string | null };
+
+export function queryTerms(query: unknown, cfg: FtsConfig, lastAsPrefix: boolean): QueryTerms {
+  if (!lastAsPrefix) return { exact: [...new Set(tokenize(query, cfg))], prefix: null };
+  // The prefix is the LAST token of the raw input, kept even when it is a stopword.
+  const all = tokenize(query, cfg, { keepStopwords: true });
+  if (all.length === 0) return { exact: [], prefix: null };
+  const prefix = all[all.length - 1]!;
+  const head = cfg.remove_stopwords ? all.slice(0, -1).filter((t) => !ENGLISH_STOPWORDS.has(t)) : all.slice(0, -1);
+  return { exact: [...new Set(head)], prefix };
+}
+
+/** Does a document's token list satisfy the terms? `all` for ContainsAllTokens, else any. */
+export function tokensMatch(docTokens: readonly string[], terms: QueryTerms, mode: 'all' | 'any'): boolean {
+  const set = new Set(docTokens);
+  const checks: boolean[] = terms.exact.map((t) => set.has(t));
+  if (terms.prefix !== null) {
+    const p = terms.prefix;
+    checks.push(docTokens.some((t) => t.startsWith(p)));
+  }
+  // A query whose every token is dropped (all stopwords, all over-length) matches nothing, in
+  // either mode — the same documents BM25 would score above zero. The vendor's answer here is
+  // unverified; this keeps the twin's count and its ranked search in agreement.
+  if (checks.length === 0) return false;
+  return mode === 'all' ? checks.every(Boolean) : checks.some(Boolean);
+}
+
+/** The per-attribute corpus statistics BM25 needs, computed once per query over the namespace. */
+export type Corpus = { n: number; avgdl: number; df: Map<string, number>; docs: Map<string, string[]> };
+
+export function buildCorpus(entries: Iterable<[string, unknown]>, cfg: FtsConfig): Corpus {
+  const docs = new Map<string, string[]>();
+  const df = new Map<string, number>();
+  let total = 0;
+  for (const [key, value] of entries) {
+    if (value === null || value === undefined) continue;
+    const tokens = tokenize(value, cfg);
+    docs.set(key, tokens);
+    total += tokens.length;
+    for (const t of new Set(tokens)) df.set(t, (df.get(t) ?? 0) + 1);
+  }
+  return { n: docs.size, avgdl: docs.size === 0 ? 0 : total / docs.size, df, docs };
+}
+
+/** BM25 of one document against the query terms; 0 means "no term matched". */
+export function bm25Score(key: string, corpus: Corpus, terms: QueryTerms, cfg: FtsConfig): number {
+  const tokens = corpus.docs.get(key);
+  if (tokens === undefined || tokens.length === 0) return 0;
+  let score = 0;
+  const dl = tokens.length;
+  for (const term of terms.exact) {
+    let tf = 0;
+    for (const t of tokens) if (t === term) tf++;
+    if (tf === 0) continue;
+    const n = corpus.df.get(term) ?? 0;
+    const idf = Math.log(1 + (corpus.n - n + 0.5) / (n + 0.5));
+    const norm = corpus.avgdl === 0 ? 1 : 1 - cfg.b + cfg.b * (dl / corpus.avgdl);
+    score += idf * ((tf * (cfg.k1 + 1)) / (tf + cfg.k1 * norm));
+  }
+  if (terms.prefix !== null) {
+    const p = terms.prefix;
+    if (tokens.some((t) => t.startsWith(p))) score += 1;
+  }
+  return score;
+}

package/src/turbopuffer-twin.ts

@@ -0,0 +1,429 @@
+// TURBOPUFFER TWIN — THE REQUEST HANDLER. Contract:
+//   handleTurbopufferTwinRequest({ method, path, body, headers, root, occurredAt, readOnly, token })
+//     -> { status, body, headers }
+//
+// The wire, grounded in the installed @turbopuffer/turbopuffer@2.8.0 (src/resources/namespaces.ts,
+// src/client.ts — see the README's "Grounded wire" table):
+//
+//   GET    /v1/namespaces                           list namespaces (prefix, page_size, cursor)
+//   POST   /v2/namespaces/{ns}                      write: upsert/patch/delete rows or columns, by
+//                                                   id or by filter, with schema + distance_metric
+//   DELETE /v2/namespaces/{ns}                      deleteAll
+//   POST   /v2/namespaces/{ns}/query                query; a body carrying `queries` is multiQuery
+//                                                   (the SDK also tags it ?stainless_overload=multiQuery)
+//   GET    /v2/namespaces/{ns}/metadata             metadata
+//   GET    /v1/namespaces/{ns}/schema               schema
+//   POST   /v1/namespaces/{ns}/schema               updateSchema
+//   GET    /v1/namespaces/{ns}/hint_cache_warm      hintCacheWarm
+//
+// A leading region segment (`/aws-us-east-1/v2/...`) is accepted and ignored: it is how a world
+// points an unmodified client here through the SDK's own `TURBOPUFFER_BASE_URL`, whose `{region}`
+// placeholder the client fills in (client.ts:273-281) — see the pack descriptor's `endpointEnv`.
+//
+// Errors wear the `{ "status": "error", "error": "<message>" }` envelope. The message STRINGS are
+// twin-authored (this build had no account to probe the real service); the statuses follow the
+// SDK's error classes (400 BadRequest, 401 Authentication, 404 NotFound).
+import { createHash } from 'node:crypto';
+import { applyTwinWriteAtomic, ownFields, twinResources, type TwinWriteInput } from '@volter/world-core';
+import {
+  applyClone,
+  applyWrite,
+  approxLogicalBytes,
+  assertNamespaceName,
+  badRequest,
+  checkConsistency,
+  documentFields,
+  documentSubjectId,
+  loadNamespaces,
+  namespaceFields,
+  queryBilling,
+  queryPerformance,
+  runQuery,
+  schemaWire,
+  SERVICE,
+  TurbopufferError,
+  TURBOPUFFER_RESOURCE_TYPES,
+  vectorEncodingRefusal,
+  type NamespaceState,
+} from './turbopuffer-store.ts';
+
+export type TurbopufferTwinRequest = {
+  method: string;
+  path: string;
+  body?: string;
+  headers?: Record<string, string>;
+  root?: string;
+  occurredAt?: string;
+  readOnly?: boolean;
+  /** The API key the twin demands. Omit to accept any non-empty key (a missing one still 401s). */
+  token?: string;
+};
+export type TurbopufferTwinResponse = { status: number; body: unknown; headers?: Record<string, string> };
+
+const JSON_HEADERS = { 'content-type': 'application/json' };
+
+/** Real Turbopuffer routes this twin does not serve yet, each with the manifest gap that tracks it. */
+const UNMODELED_ROUTES: Array<{ method: string; re: RegExp; gap: string }> = [
+  { method: 'PATCH', re: /^\/v1\/namespaces\/[^/]+\/metadata$/, gap: 'turbopuffer.namespaces.update_metadata' },
+  { method: 'POST', re: /^\/v2\/namespaces\/[^/]+\/explain_query$/, gap: 'turbopuffer.query.explain' },
+  { method: 'POST', re: /^\/v1\/namespaces\/[^/]+\/_debug\/recall$/, gap: 'turbopuffer.query.recall' },
+  { method: 'POST', re: /^\/v1\/namespaces\/[^/]+(\/query)?$/, gap: 'turbopuffer.legacy.v1_api' },
+  { method: 'GET', re: /^\/v1\/namespaces\/[^/]+$/, gap: 'turbopuffer.legacy.v1_api' },
+  { method: 'DELETE', re: /^\/v1\/namespaces\/[^/]+$/, gap: 'turbopuffer.legacy.v1_api' },
+];
+
+function fail(status: number, error: string): TurbopufferTwinResponse {
+  return { status, body: { status: 'error', error }, headers: { ...JSON_HEADERS } };
+}
+
+function ok(body: unknown): TurbopufferTwinResponse {
+  return { status: 200, body, headers: { ...JSON_HEADERS } };
+}
+
+function lowerHeaders(h: Record<string, string> | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(h ?? {})) out[k.toLowerCase()] = v;
+  return out;
+}
+
+/** `Authorization: Bearer <key>` (client.ts `authHeaders`). An empty key is no key. */
+export function extractTurbopufferApiKey(headers: Record<string, string> | undefined): string | null {
+  const raw = lowerHeaders(headers).authorization;
+  if (raw === undefined) return null;
+  const m = /^bearer(?:\s+(.*))?$/i.exec(raw.trim());
+  if (!m) return null;
+  const key = (m[1] ?? '').trim();
+  return key === '' ? null : key;
+}
+
+/** Collapse duplicate slashes and drop a leading region segment (see the header). */
+export function normalizeTurbopufferPath(rawPath: string): string {
+  let p = `/${rawPath.replace(/^\/+/, '')}`.replace(/\/{2,}/g, '/');
+  p = p.replace(/^\/(?:aws|gcp|azure)-[a-z0-9-]+(?=\/v\d+\/)/, '');
+  return p.length > 1 ? p.replace(/\/+$/, '') : p;
+}
+
+function decodeNs(seg: string): string {
+  let name: string;
+  try { name = decodeURIComponent(seg); } catch { name = seg; }
+  assertNamespaceName(name);
+  return name;
+}
+
+function parseBody(raw: string | undefined): unknown {
+  if (raw === undefined || raw.trim() === '') return {};
+  try { return JSON.parse(raw); } catch { throw badRequest('invalid request: body is not valid JSON'); }
+}
+
+function notFound(ns: string): TurbopufferError {
+  return new TurbopufferError(404, `namespace '${ns}' was not found`);
+}
+
+function readSpace(ns: string, root: string | undefined): NamespaceState {
+  const space = loadNamespaces(twinResources(SERVICE, root)).get(ns);
+  if (space === undefined) throw notFound(ns);
+  return space;
+}
+
+export async function handleTurbopufferTwinRequest(req: TurbopufferTwinRequest): Promise<TurbopufferTwinResponse> {
+  const method = req.method.toUpperCase();
+  const [rawPath, rawQuery] = req.path.split('?');
+  const query = new URLSearchParams(rawQuery ?? '');
+  const path = normalizeTurbopufferPath(rawPath ?? '/');
+  const at = req.occurredAt ?? new Date().toISOString();
+
+  const key = extractTurbopufferApiKey(req.headers);
+  if (key === null) return fail(401, 'missing API key: send Authorization: Bearer <TURBOPUFFER_API_KEY>');
+  if (req.token !== undefined && key !== req.token) return fail(401, 'invalid API key');
+
+  try {
+    if (path === '/v1/namespaces') {
+      if (method !== 'GET') return fail(405, `method ${method} not allowed on ${path}`);
+      return ok(listNamespaces(req.root, query));
+    }
+    let m = /^\/v2\/namespaces\/([^/]+)$/.exec(path);
+    if (m) {
+      const ns = decodeNs(m[1]!);
+      if (method === 'POST') {
+        const body = parseBody(req.body);
+        return asyncRequested(req, body) ? await asyncCopy(req, ns, body, at) : await write(req, ns, body, at);
+      }
+      return method === 'DELETE' ? await deleteAll(req, ns, at) : unrouted(method, path);
+    }
+    m = /^\/v2\/namespaces\/([^/]+)\/query$/.exec(path);
+    if (m) {
+      return method === 'POST' ? ok(queryNamespace(decodeNs(m[1]!), parseBody(req.body), req.root)) : unrouted(method, path);
+    }
+    m = /^\/v1\/namespaces\/([^/]+)\/operations\/([^/]+)$/.exec(path);
+    if (m && method === 'GET') return pollOperation(req, decodeNs(m[1]!), decodeURIComponent(m[2]!), at);
+    // GET /v1/namespaces/:namespace/metadata is the docs' path (https://turbopuffer.com/docs/metadata); the client sends /v2
+    m = /^\/v[12]\/namespaces\/([^/]+)\/metadata$/.exec(path);
+    if (m && method === 'GET') return ok(metadata(readSpace(decodeNs(m[1]!), req.root)));
+    m = /^\/v1\/namespaces\/([^/]+)\/schema$/.exec(path);
+    if (m) return await schemaRoute(req, decodeNs(m[1]!), method, path, at);
+    m = /^\/v1\/namespaces\/([^/]+)\/hint_cache_warm$/.exec(path);
+    return m && method === 'GET' ? hintCacheWarm(decodeNs(m[1]!), req.root) : unrouted(method, path);
+  } catch (e) {
+    return e instanceof TurbopufferError ? fail(e.status, e.message) : internalFault(method, path, e);
+  }
+}
+
+/** A request this handler has no route for: a method a path does not take (405), a route of turbopuffer's the twin does
+ *  not model (404 naming its gap), or none (404). The derived dispatch hands this handler only the operations it serves,
+ *  so only the protocol 2 harness (turbopuffer-conformance.ts's router census) asks these. */
+/** The twin has no cache to warm: every namespace is always "hot". Accepting the hint is its answer, 202 as the spec's
+ *  operation answers it. */
+function hintCacheWarm(ns: string, root: string | undefined): TurbopufferTwinResponse {
+  readSpace(ns, root);
+  return { status: 202, body: { status: 'ACCEPTED', message: 'cache warm hint accepted' }, headers: { ...JSON_HEADERS } };
+}
+
+function unrouted(method: string, path: string): TurbopufferTwinResponse {
+  const r = UNMODELED_ROUTES.find((x) => x.method === method && x.re.test(path));
+  if (r) return fail(404, `turbopuffer twin: ${method} ${path} is real Turbopuffer surface this twin does not model yet (${r.gap} is the filed gap)`);
+  return /^(\/v2\/namespaces\/[^/]+(\/query)?|\/v1\/namespaces\/[^/]+\/schema)$/.test(path) ? fail(405, `method ${method} not allowed on ${path}`) : fail(404, `not found: ${method} ${path}`);
+}
+
+/** The engine's own bug guard: an error that is not a refusal of turbopuffer's. */
+function internalFault(method: string, path: string, e: unknown): TurbopufferTwinResponse {
+  return fail(500, `turbopuffer twin: internal fault handling ${method} ${path} — ${e instanceof Error ? e.message : String(e)}`);
+}
+
+/** GET and POST /v1/namespaces/{namespace}/schema, the spec's "Get namespace schema" and "Update namespace schema",
+ *  which the client sends (`schema()`, `updateSchema()`); turbopuffer's pages now show a namespace's schema in its
+ *  metadata and change it with a write carrying only `{"schema": …}`. */
+async function schemaRoute(req: TurbopufferTwinRequest, ns: string, method: string, path: string, at: string): Promise<TurbopufferTwinResponse> {
+  if (method === 'GET') return ok(schemaWire(readSpace(ns, req.root)));
+  return method === 'POST' ? await updateSchema(req, ns, parseBody(req.body), at) : unrouted(method, path);
+}
+
+// ── routes ──────────────────────────────────────────────────────────────────────────────────
+
+function listNamespaces(root: string | undefined, query: URLSearchParams): Record<string, unknown> {
+  const prefix = query.get('prefix') ?? '';
+  const sizeRaw = query.get('page_size');
+  // "page_size … default: 100 … (max of 1000)" (https://turbopuffer.com/docs/namespaces)
+  const pageSize = sizeRaw === null ? 100 : Number(sizeRaw);
+  if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > 1000) throw badRequest('invalid page_size: must be an integer between 1 and 1000');
+  const cursor = query.get('cursor') ?? '';
+  const names = [...loadNamespaces(twinResources(SERVICE, root)).keys()]
+    .filter((n) => n.startsWith(prefix) && (cursor === '' || n > cursor))
+    .sort();
+  const page = names.slice(0, pageSize);
+  return {
+    namespaces: page.map((id) => ({ id })),
+    ...(names.length > pageSize ? { next_cursor: page[page.length - 1] } : {}),
+  };
+}
+
+type Decided = { ok: true; response: unknown } | { ok: false; error: TurbopufferError };
+
+async function commit(
+  req: TurbopufferTwinRequest,
+  decide: (spaces: Map<string, NamespaceState>) => { response: unknown; write: TwinWriteInput },
+): Promise<TurbopufferTwinResponse> {
+  if (req.readOnly) return fail(405, 'read_only: this twin was started read-only; writes are refused');
+  const { value } = await applyTwinWriteAtomic<Decided>(SERVICE, (resources) => {
+    try { const { response, write } = decide(loadNamespaces(resources)); return { kind: 'write', value: { ok: true, response }, write }; } catch (e) { return refusedDecision(e); }
+  }, req.root);
+  return value.ok ? ok(value.response) : fail(value.error.status, value.error.message);
+}
+
+/** A write the store refused (a TurbopufferError) is skipped and answered; any other error is the engine's. */
+function refusedDecision(e: unknown): { kind: 'skip'; value: Decided } {
+  if (e instanceof TurbopufferError) return { kind: 'skip', value: { ok: false, error: e } };
+  throw e;
+}
+
+function write(req: TurbopufferTwinRequest, ns: string, body: unknown, at: string): Promise<TurbopufferTwinResponse> {
+  return commit(req, (spaces) => {
+    const b = body !== null && typeof body === 'object' && !Array.isArray(body) ? body as Record<string, unknown> : {};
+    const out = b.copy_from_namespace !== undefined || b.branch_from_namespace !== undefined ? applyClone(spaces, ns, body, at) : applyWrite(spaces.get(ns), ns, body, at);
+    return {
+      response: out.response,
+      write: {
+        operation: 'namespace.write',
+        subjectType: 'namespace',
+        subjectId: ns,
+        fields: namespaceFields(out.next),
+        input: body as Record<string, unknown>,
+        projection: {
+          updates: out.upserts.map((d) => ({ type: 'document', id: documentSubjectId(ns, d.id), fields: documentFields(ns, d) })),
+          deletes: out.deletes.map((k) => ({ type: 'document', id: `${ns}/${k}` })),
+        },
+        occurredAt: at,
+        actor: { kind: 'agent' },
+      },
+    };
+  });
+}
+
+// ── asynchronous requests ───────────────────────────────────────────────────────────────────
+// https://turbopuffer.com/docs/api-overview, Asynchronous requests: "Currently supported operations: copy_from_namespace,
+// recall evaluation. Send the `Prefer: respond-async` header to allow the server to start the operation in the
+// background. The server returns `202 Accepted` with a `Location` header pointing to the operation. Poll that location
+// to check on progress: The response is `{"status": "running"}` until the operation finishes, then carries the result.
+// The result is retained for one hour after the operation finishes, polling after will return `404`." Its example
+// answers `Preference-Applied: respond-async`, `Location: /v1/namespaces/<ns>/operations/tpuf-abc123` and
+// `{"token": "tpuf-abc123"}`; a finished poll `{"status": "finished", "result": {"success": <the write's answer>}}` or
+// `{"status": "finished", "result": {"error": {"status_code": 400, "detail": {"status": "error", "error": …}}}}`.
+// Where the docs stop and the twin decides: the twin copies at once, so an operation is finished when it is started and
+// no poll answers "running"; recall evaluation is not served, so a copy is the only asynchronous operation; the token is
+// `tpuf-` and 12 hex digits derived from the namespace, the moment and the count of operations.
+const RETAINED_MS = 60 * 60 * 1000;
+
+function asyncRequested(req: TurbopufferTwinRequest, body: unknown): boolean {
+  const prefer = lowerHeaders(req.headers).prefer ?? '';
+  const wants = prefer.split(',').some((p) => p.trim().toLowerCase() === 'respond-async');
+  return wants && body !== null && typeof body === 'object' && !Array.isArray(body) && (body as Record<string, unknown>).copy_from_namespace !== undefined;
+}
+
+async function asyncCopy(req: TurbopufferTwinRequest, ns: string, body: unknown, at: string): Promise<TurbopufferTwinResponse> {
+  if (req.readOnly) return fail(405, 'read_only: this twin was started read-only; writes are refused');
+  const { value: token } = await applyTwinWriteAtomic<string>(SERVICE, (resources) => {
+    const n = resources.filter((r) => r.type === '_operation').length + 1;
+    const token = `tpuf-${createHash('sha256').update(`${ns}:${at}:${n}`).digest('hex').slice(0, 12)}`;
+    const record = (result: Record<string, unknown>) => ({ type: '_operation', id: `${ns}/${token}`, fields: { namespace: ns, token, finished_at: at, result } });
+    try {
+      const out = applyClone(loadNamespaces(resources), ns, body, at);
+      return { kind: 'write', value: token, write: {
+        operation: 'namespace.write', subjectType: 'namespace', subjectId: ns, fields: namespaceFields(out.next), input: body as Record<string, unknown>,
+        projection: { updates: [...out.upserts.map((d) => ({ type: 'document', id: documentSubjectId(ns, d.id), fields: documentFields(ns, d) })), record({ success: out.response })] },
+        occurredAt: at, actor: { kind: 'agent' },
+      } };
+    } catch (e) {
+      if (!(e instanceof TurbopufferError)) throw e;
+      const op = record({ error: { status_code: e.status, detail: { status: 'error', error: e.message } } });
+      return { kind: 'write', value: token, write: { operation: 'operation.record', subjectType: op.type, subjectId: op.id, fields: op.fields, occurredAt: at, actor: { kind: 'system' } } };
+    }
+  }, req.root);
+  return { status: 202, body: { token }, headers: { ...JSON_HEADERS, 'preference-applied': 'respond-async', location: `/v1/namespaces/${encodeURIComponent(ns)}/operations/${token}` } };
+}
+
+function pollOperation(req: TurbopufferTwinRequest, ns: string, token: string, at: string): TurbopufferTwinResponse {
+  const op = twinResources(SERVICE, req.root).find((r) => r.type === '_operation' && r.id === `${ns}/${token}`);
+  const f = op ? ownFields(op) : undefined;
+  if (!f || Date.parse(at) - Date.parse(String(f.finished_at)) > RETAINED_MS) return fail(404, `operation '${token}' was not found`);
+  return ok({ status: 'finished', result: f.result });
+}
+
+function deleteAll(req: TurbopufferTwinRequest, ns: string, at: string): Promise<TurbopufferTwinResponse> {
+  return commit(req, (spaces) => {
+    const space = spaces.get(ns);
+    if (space === undefined) throw notFound(ns);
+    return {
+      response: { status: 'OK' },
+      write: {
+        operation: 'namespace.delete_all',
+        subjectType: 'namespace',
+        subjectId: ns,
+        fields: { ...namespaceFields(space), schema: {}, distance_metric: null, vector_dims: null, updated_at: at, gone: true },
+        projection: { deletes: [...space.docs.keys()].map((k) => ({ type: 'document', id: `${ns}/${k}` })) },
+        occurredAt: at,
+        actor: { kind: 'agent' },
+      },
+    };
+  });
+}
+
+function updateSchema(req: TurbopufferTwinRequest, ns: string, body: unknown, at: string): Promise<TurbopufferTwinResponse> {
+  return commit(req, (spaces) => {
+    const space = spaces.get(ns);
+    if (space === undefined) throw notFound(ns);
+    const out = applyWrite(space, ns, { schema: body }, at);
+    return {
+      response: schemaWire(out.next),
+      write: {
+        operation: 'namespace.update_schema',
+        subjectType: 'namespace',
+        subjectId: ns,
+        fields: namespaceFields(out.next),
+        input: { schema: body },
+        occurredAt: at,
+        actor: { kind: 'agent' },
+      },
+    };
+  });
+}
+
+function queryNamespace(ns: string, body: unknown, root: string | undefined): Record<string, unknown> {
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) throw badRequest('invalid query: expected a JSON object');
+  const space = readSpace(ns, root);
+  const b = body as Record<string, unknown>;
+  if (b.queries !== undefined) {
+    for (const k of Object.keys(b)) {
+      if (k !== 'queries' && k !== 'rerank_by' && k !== 'consistency' && k !== 'vector_encoding') throw badRequest(`invalid multi-query: unknown field "${k}"`);
+    }
+    if (!Array.isArray(b.queries) || b.queries.length === 0) throw badRequest('invalid multi-query: queries must be a non-empty array');
+    checkConsistency(b.consistency);
+    if (b.vector_encoding !== undefined && b.vector_encoding !== 'float') throw vectorEncodingRefusal(b.vector_encoding);
+    const results = b.queries.map((q) => runQuery(space, q, { multi: true }));
+    const answered = b.rerank_by === undefined ? results : [rerankRrf(b.rerank_by, b.queries, results)];
+    return { results: answered, billing: queryBilling(space, answered), performance: queryPerformance(space) };
+  }
+  const result = runQuery(space, b);
+  return { ...result, billing: queryBilling(space, result), performance: queryPerformance(space) };
+}
+
+/** `rerank_by: ["RRF", {rank_constant?, weights?}]` (https://turbopuffer.com/docs/query, Reciprocal rank fusion): "The
+ *  results contain a single list combining all the subquery results, sorted by descending RRF score. The RRF score for
+ *  each row is reported in the `$dist` field. It is calculated as the sum of `weight / (rank_constant + rank)` across all
+ *  subquery results", rank 1-based, `rank_constant` "defaults to 60 and can be set to any integer greater than zero",
+ *  each weight "defaults to 1 and can be set to any number greater than zero. Exactly one weight must be provided for
+ *  each subquery", and "RRF reranking requires at least two subqueries and is not supported for aggregations".
+ *  Where the docs stop and the twin decides: a row carries the attributes its first subquery returned; rows of equal
+ *  score order by id; every fused row is answered (the docs' "up to limit.total" names no limit on a multi-query). */
+function rerankRrf(spec: unknown, queries: unknown[], results: Array<Record<string, unknown>>): Record<string, unknown> {
+  if (!Array.isArray(spec) || spec[0] !== 'RRF' || spec.length > 2) throw badRequest('invalid rerank_by: the supported reranking function is ["RRF"] or ["RRF", {rank_constant, weights}]');
+  const cfg = (spec[1] ?? {}) as Record<string, unknown>;
+  if (cfg === null || typeof cfg !== 'object' || Array.isArray(cfg) || Object.keys(cfg).some((k) => k !== 'rank_constant' && k !== 'weights')) throw badRequest('invalid rerank_by: RRF takes { rank_constant, weights }');
+  const k = cfg.rank_constant ?? 60;
+  if (typeof k !== 'number' || !Number.isInteger(k) || k <= 0) throw badRequest('invalid rerank_by: rank_constant must be an integer greater than zero');
+  const weights = cfg.weights ?? queries.map(() => 1);
+  if (!Array.isArray(weights) || weights.length !== queries.length || !weights.every((w) => typeof w === 'number' && w > 0)) throw badRequest('invalid rerank_by: exactly one weight greater than zero must be provided for each subquery');
+  if (queries.length < 2) throw badRequest('invalid rerank_by: RRF reranking requires at least two subqueries');
+  if (results.some((r) => r.rows === undefined)) throw badRequest('invalid rerank_by: RRF reranking is not supported for aggregations');
+  const fused = new Map<string, { row: Record<string, unknown>; score: number }>();
+  results.forEach((r, i) => (r.rows as Array<Record<string, unknown>>).forEach((row, at) => {
+    const id = JSON.stringify(row.id);
+    const hit = fused.get(id) ?? { row, score: 0 };
+    hit.score += (weights[i] as number) / (k + at + 1);
+    fused.set(id, hit);
+  }));
+  const rows = [...fused.values()].sort((a, b) => b.score - a.score || JSON.stringify(a.row.id).localeCompare(JSON.stringify(b.row.id)))
+    .map(({ row, score }) => { const { $dist: _d, ...rest } = row; return { ...rest, $dist: score }; });
+  return { rows };
+}
+
+function metadata(space: NamespaceState): Record<string, unknown> {
+  return {
+    approx_logical_bytes: approxLogicalBytes(space),
+    approx_row_count: space.docs.size,
+    created_at: space.created_at,
+    last_write_at: space.last_write_at,
+    updated_at: space.updated_at,
+    encryption: { mode: 'default' },
+    index: { status: 'up-to-date' },
+    schema: schemaWire(space),
+    // "branching … Only present for branched namespaces. … `parent` (string): The namespace this was branched from"
+    ...(space.parent !== undefined ? { branching: { parent: space.parent } } : {}),
+  };
+}
+
+// ── the conformance snapshot ────────────────────────────────────────────────────────────────
+
+export function turbopufferTwinSnapshot(): { resourceTypes: readonly string[]; implementedEndpoints: readonly string[] } {
+  return {
+    resourceTypes: TURBOPUFFER_RESOURCE_TYPES,
+    implementedEndpoints: [
+      'GET /v1/namespaces',
+      'POST /v2/namespaces/{ns}',
+      'DELETE /v2/namespaces/{ns}',
+      'POST /v2/namespaces/{ns}/query',
+      'GET /v2/namespaces/{ns}/metadata',
+      'GET /v1/namespaces/{ns}/schema',
+      'POST /v1/namespaces/{ns}/schema',
+      'GET /v1/namespaces/{ns}/hint_cache_warm',
+    ],
+  };
+}