@volter/twin-turbopuffer 0.1.0

package/src/turbopuffer-capabilities.ts

@@ -0,0 +1,455 @@
+// Turbopuffer capability manifest — the vendor's surface as the denominator, authored top-down from
+// the installed @turbopuffer/turbopuffer@2.8.0 (every Namespace method in src/resources/
+// namespaces.ts, every write/query parameter, every filter operator and rank_by form in
+// src/resources/custom.ts, the list endpoint in top-level.ts), not from what this twin built.
+//
+// Every `done` verify drives the REAL `handleTurbopufferTwinRequest` over a FRESH temp root with a
+// pinned clock and asserts VALUES. The verifies were authored but NOT executed in the build that
+// wrote them (the owner's rule for that build forbade running tests); the product-door evidence
+// was a real @turbopuffer/turbopuffer client driving a served twin (README ## Coverage). They are
+// queued for the catalog gate.
+//
+// Turbopuffer is API-first — an integrator calls it from code; its dashboard manages keys and
+// billing — so there is no mirror and no UI capability (README § No UI mirror).
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { checkCapabilities, type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
+import type { RemoteExecute, TwinAction } from '@volter/world-core';
+import { handleTurbopufferTwinRequest } from './turbopuffer-twin.ts';
+import { checkTurbopufferConformance } from './turbopuffer-conformance.ts';
+import { performTurbopufferAction, syncTurbopufferFromRemote } from './turbopuffer-connector.ts';
+
+const AT = '2026-09-23T00:00:00.000Z';
+const AUTH = { authorization: 'Bearer tpuf_capability' };
+
+type Res = { status: number; body: any };
+type Tp = {
+  root: string;
+  req: (method: string, path: string, body?: unknown, headers?: Record<string, string>) => Promise<Res>;
+  write: (ns: string, body: unknown) => Promise<Res>;
+  query: (ns: string, body: unknown) => Promise<Res>;
+};
+
+async function withRoot(fn: (tp: Tp) => Promise<boolean>): Promise<boolean> {
+  const root = mkdtempSync(join(tmpdir(), 'turbopuffer-cap-'));
+  const req: Tp['req'] = async (method, path, body, headers = AUTH) => {
+    const r = await handleTurbopufferTwinRequest({ method, path, headers, root, occurredAt: AT, ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+    return { status: r.status, body: r.body as any };
+  };
+  try {
+    return await fn({ root, req, write: (ns, b) => req('POST', `/v2/namespaces/${ns}`, b), query: (ns, b) => req('POST', `/v2/namespaces/${ns}/query`, b) });
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+const ids = (r: Res): unknown[] => (Array.isArray(r.body?.rows) ? r.body.rows.map((x: any) => x.id) : ['<no rows>']);
+const same = (a: unknown, b: unknown): boolean => JSON.stringify(a) === JSON.stringify(b);
+const isError = (r: Res, status: number): boolean => r.status === status && r.body?.status === 'error' && typeof r.body?.error === 'string';
+
+const FTS = { title: { type: 'string', full_text_search: { tokenizer: 'word_v2' } } };
+const PEOPLE = {
+  upsert_rows: [
+    { id: 'p1', title: 'steven tey dub founder', group: 'g1', tags: ['a', 'b'], score: 10 },
+    { id: 'p2', title: 'stephanie writer', group: 'g2', tags: ['b'], score: 5 },
+    { id: 'p3', title: 'kiran dub dub engineer', tags: [], score: 7 },
+  ],
+  schema: FTS,
+};
+const all = { rank_by: ['id', 'asc'], top_k: 100 };
+
+const done = (id: string, area: string, title: string, tier: CapabilitySpec['tier'], verify: CapabilitySpec['verify'], dimension: CapabilitySpec['dimension'] = 'api'): CapabilitySpec =>
+  ({ id, area, title, dimension, tier, expected: 'done', verify });
+const todo = (id: string, area: string, title: string, tier: CapabilitySpec['tier'], dimension: CapabilitySpec['dimension'] = 'api'): CapabilitySpec =>
+  ({ id, area, title, dimension, tier, expected: 'todo' });
+
+export const TURBOPUFFER_CAPABILITIES: CapabilitySpec[] = [
+  // ── write ────────────────────────────────────────────────────────────────────────────────
+  done('turbopuffer.write.upsert_rows', 'write', 'write upsert_rows stores documents that a query returns with their attributes', 'core', () => withRoot(async (tp) => {
+    const w = await tp.write('ns', PEOPLE);
+    const q = await tp.query('ns', { ...all, include_attributes: ['group', 'score'] });
+    return w.status === 200 && w.body.status === 'OK' && w.body.rows_upserted === 3 && w.body.rows_affected === 3
+      && same(q.body.rows, [{ id: 'p1', group: 'g1', score: 10 }, { id: 'p2', group: 'g2', score: 5 }, { id: 'p3', group: null, score: 7 }]);
+  })),
+  done('turbopuffer.write.upsert_replaces_document', 'write', 'an upsert replaces the whole document (attributes it omits are gone)', 'core', () => withRoot(async (tp) => {
+    await tp.write('ns', { upsert_rows: [{ id: 1, x: 'one', y: 'two' }] });
+    await tp.write('ns', { upsert_rows: [{ id: 1, x: 'uno' }] });
+    const q = await tp.query('ns', { ...all, include_attributes: true });
+    return same(q.body.rows, [{ id: 1, x: 'uno' }]);
+  })),
+  done('turbopuffer.write.upsert_columns', 'write', 'write upsert_columns stores column-oriented documents and refuses ragged columns', 'common', () => withRoot(async (tp) => {
+    const w = await tp.write('ns', { upsert_columns: { id: ['a', 'b'], n: [1, 2] } });
+    const q = await tp.query('ns', { ...all, include_attributes: ['n'] });
+    const bad = await tp.write('ns', { upsert_columns: { id: ['c', 'd'], n: [1] } });
+    return w.body.rows_upserted === 2 && same(q.body.rows, [{ id: 'a', n: 1 }, { id: 'b', n: 2 }]) && isError(bad, 400);
+  })),
+  done('turbopuffer.write.patch_rows', 'write', 'patch_rows / patch_columns merge into existing documents and never create one', 'common', () => withRoot(async (tp) => {
+    await tp.write('ns', { upsert_rows: [{ id: 'a', x: 1, y: 2 }] });
+    const w = await tp.write('ns', { patch_rows: [{ id: 'a', y: 3, z: 'new' }, { id: 'ghost', y: 9 }] });
+    const c = await tp.write('ns', { patch_columns: { id: ['a'], x: [5] } });
+    const q = await tp.query('ns', { ...all, include_attributes: true });
+    return w.body.rows_patched === 1 && c.body.rows_patched === 1 && same(q.body.rows, [{ id: 'a', x: 5, y: 3, z: 'new' }]);
+  })),
+  done('turbopuffer.write.deletes', 'write', 'write deletes removes documents by id', 'core', () => withRoot(async (tp) => {
+    await tp.write('ns', PEOPLE);
+    const w = await tp.write('ns', { deletes: ['p1', 'p3'] });
+    const q = await tp.query('ns', all);
+    return w.status === 200 && w.body.rows_deleted === 2 && same(ids(q), ['p2']);
+  })),
+  done('turbopuffer.write.delete_by_filter', 'write', 'delete_by_filter removes exactly the documents the filter matches', 'common', () => withRoot(async (tp) => {
+    await tp.write('ns', PEOPLE);
+    const w = await tp.write('ns', { delete_by_filter: ['score', 'Gte', 7] });
+    const q = await tp.query('ns', all);
+    return w.body.rows_deleted === 2 && same(ids(q), ['p2']);
+  })),
+  done('turbopuffer.write.patch_by_filter', 'write', 'patch_by_filter patches exactly the documents the filter matches', 'common', () => withRoot(async (tp) => {
+    await tp.write('ns', PEOPLE);
+    const w = await tp.write('ns', { patch_by_filter: { filters: ['group', 'Eq', 'g1'], patch: { flagged: true } } });
+    const q = await tp.query('ns', { ...all, filters: ['flagged', 'Eq', true] });
+    return w.body.rows_patched === 1 && same(ids(q), ['p1']);
+  })),
+  done('turbopuffer.write.return_affected_ids', 'write', 'return_affected_ids lists upserted, patched and deleted ids', 'niche', () => withRoot(async (tp) => {
+    await tp.write('ns', { upsert_rows: [{ id: 'a' , v: 1 }] });
+    const w = await tp.write('ns', { upsert_rows: [{ id: 'b', v: 2 }], patch_rows: [{ id: 'a', v: 3 }], deletes: ['a'], return_affected_ids: true });
+    return same(w.body.upserted_ids, ['b']) && same(w.body.patched_ids, ['a']) && same(w.body.deleted_ids, ['a']) && w.body.rows_affected === 3;
+  })),
+  done('turbopuffer.write.schema_declared', 'write', 'a declared schema is kept; full-text attributes default to filterable:false', 'core', () => withRoot(async (tp) => {
+    await tp.write('ns', { ...PEOPLE, schema: { ...FTS, group: { type: 'string', filterable: true } } });
+    const s = await tp.req('GET', '/v1/namespaces/ns/schema');
+    return s.status === 200 && s.body.title.type === 'string' && s.body.title.filterable === false
+      && s.body.title.full_text_search.tokenizer === 'word_v2' && s.body.title.full_text_search.k1 === 1.2 && s.body.group.filterable === true
+      && s.body.score.type === 'int' && s.body.tags.type === '[]string';
+  })),
+  done('turbopuffer.write.schema_type_conflict', 'write', 'a value or schema of the wrong type is refused with a 400 and writes nothing', 'common', () => withRoot(async (tp) => {
+    await tp.write('ns', { upsert_rows: [{ id: 'a', n: 1 }] });
+    const bad = await tp.write('ns', { upsert_rows: [{ id: 'b', n: 'one' }] });
+    const badSchema = await tp.write('ns', { upsert_rows: [{ id: 'c', n: 2 }], schema: { n: 'string' } });
+    const q = await tp.query('ns', all);
+    return isError(bad, 400) && isError(badSchema, 400) && same(ids(q), ['a']);
+  })),
+  done('turbopuffer.write.invalid_requests', 'write', 'malformed writes (bad id, empty request, unknown field, bad namespace name) are refused with 400', 'common', () => withRoot(async (tp) => {
+    const a = await tp.write('ns', { upsert_rows: [{ id: -1 }] });
+    const b = await tp.write('ns', {});
+    const c = await tp.write('ns', { upsert_rowz: [] });
+    const d = await tp.write('bad%20name', { upsert_rows: [{ id: 'x' }] });
+    const q = await tp.query('ns', all);
+    return isError(a, 400) && isError(b, 400) && isError(c, 400) && isError(d, 400) && isError(q, 404);
+  })),
+  done('turbopuffer.write.vectors', 'write', 'vectors need a distance_metric and a consistent dimension', 'common', () => withRoot(async (tp) => {
+    const noMetric = await tp.write('ns', { upsert_rows: [{ id: 'a', vector: [1, 0] }] });
+    const okw = await tp.write('ns', { upsert_rows: [{ id: 'a', vector: [1, 0] }], distance_metric: 'cosine_distance' });
+    const wrongDims = await tp.write('ns', { upsert_rows: [{ id: 'b', vector: [1, 0, 0] }], distance_metric: 'cosine_distance' });
+    return isError(noMetric, 400) && okw.status === 200 && isError(wrongDims, 400);
+  })),
+  done('turbopuffer.write.dirty_state_recreate', 'write', 'a namespace deleted and re-written starts clean (no resurrected documents or schema)', 'common', () => withRoot(async (tp) => {
+    await tp.write('ns', { upsert_rows: [{ id: 'old', n: 1 }] });
+    await tp.req('DELETE', '/v2/namespaces/ns');
+    const w = await tp.write('ns', { upsert_rows: [{ id: 'new', n: 'now a string' }] });
+    const q = await tp.query('ns', { ...all, include_attributes: true });
+    return w.status === 200 && same(q.body.rows, [{ id: 'new', n: 'now a string' }]);
+  })),
+  todo('turbopuffer.write.conditional', 'write', 'conditional writes: upsert_condition / patch_condition / delete_condition with $ref_new', 'common'),
+  todo('turbopuffer.write.encryption', 'write', 'customer-managed encryption (encryption.mode customer-managed)', 'niche'),
+  todo('turbopuffer.write.sharding', 'write', 'sharding config on a namespace\'s inaugural write', 'niche'),
+  todo('turbopuffer.write.respond_async', 'write', 'Prefer: respond-async — a 202 with Location polling (the twin always answers synchronously, which the SDK accepts)', 'niche'),
+  todo('turbopuffer.write.backpressure', 'write', 'write backpressure (429 when unindexed data exceeds the limit) and disable_backpressure', 'niche'),
+
+  // ── namespaces ───────────────────────────────────────────────────────────────────────────
+  done('turbopuffer.namespaces.delete_all', 'namespaces', 'deleteAll removes the namespace; later reads and a second deleteAll answer 404', 'core', () => withRoot(async (tp) => {
+    await tp.write('ns', PEOPLE);
+    const d = await tp.req('DELETE', '/v2/namespaces/ns');
+    const q = await tp.query('ns', all);
+    const again = await tp.req('DELETE', '/v2/namespaces/ns');
+    return d.status === 200 && same(d.body, { status: 'OK' }) && isError(q, 404) && isError(again, 404);
+  })),
+  done('turbopuffer.namespaces.list', 'namespaces', 'GET /v1/namespaces lists namespaces by prefix with cursor paging', 'common', () => withRoot(async (tp) => {
+    for (const n of ['app-a', 'app-b', 'other']) await tp.write(n, { upsert_rows: [{ id: 1 }] });
+    const p1 = await tp.req('GET', '/v1/namespaces?prefix=app-&page_size=1');
+    const p2 = await tp.req('GET', `/v1/namespaces?prefix=app-&page_size=1&cursor=${p1.body.next_cursor}`);
+    return same(p1.body.namespaces, [{ id: 'app-a' }]) && p1.body.next_cursor === 'app-a' && same(p2.body.namespaces, [{ id: 'app-b' }]) && p2.body.next_cursor === undefined;
+  })),
+  done('turbopuffer.namespaces.metadata', 'namespaces', 'GET /v2/namespaces/{ns}/metadata reports row count, bytes, timestamps and schema', 'common', () => withRoot(async (tp) => {
+    await tp.write('ns', PEOPLE);
+    const m = await tp.req('GET', '/v2/namespaces/ns/metadata');
+    const missing = await tp.req('GET', '/v2/namespaces/nope/metadata');
+    return m.status === 200 && m.body.approx_row_count === 3 && m.body.approx_logical_bytes > 0 && m.body.created_at === AT
+      && same(m.body.index, { status: 'up-to-date' }) && m.body.schema.title.type === 'string' && isError(missing, 404);
+  })),
+  done('turbopuffer.namespaces.schema_get', 'namespaces', 'GET /v1/namespaces/{ns}/schema returns every attribute\'s resolved config', 'common', () => withRoot(async (tp) => {
+    await tp.write('ns', { upsert_rows: [{ id: 'a', f: 1.5, ok: true }] });
+    const s = await tp.req('GET', '/v1/namespaces/ns/schema');
+    return s.status === 200 && s.body.f.type === 'float' && s.body.ok.type === 'bool' && s.body.f.filterable === true;
+  })),
+  done('turbopuffer.namespaces.schema_update', 'namespaces', 'POST /v1/namespaces/{ns}/schema updates configs and refuses a type change', 'niche', () => withRoot(async (tp) => {
+    await tp.write('ns', { upsert_rows: [{ id: 'a', note: 'hello world' }] });
+    const u = await tp.req('POST', '/v1/namespaces/ns/schema', { note: { type: 'string', full_text_search: { tokenizer: 'word_v2' }, filterable: true } });
+    const bad = await tp.req('POST', '/v1/namespaces/ns/schema', { note: 'int' });
+    const q = await tp.query('ns', { rank_by: ['note', 'BM25', 'world'] });
+    return u.status === 200 && u.body.note.full_text_search.tokenizer === 'word_v2' && isError(bad, 400) && same(ids(q), ['a']);
+  })),
+  done('turbopuffer.namespaces.hint_cache_warm', 'namespaces', 'GET /v1/namespaces/{ns}/hint_cache_warm is accepted for an existing namespace', 'niche', () => withRoot(async (tp) => {
+    await tp.write('ns', { upsert_rows: [{ id: 1 }] });
+    const h = await tp.req('GET', '/v1/namespaces/ns/hint_cache_warm');
+    const missing = await tp.req('GET', '/v1/namespaces/nope/hint_cache_warm');
+    return h.status === 202 && h.body.status === 'ACCEPTED' && isError(missing, 404);
+  })),
+  todo('turbopuffer.namespaces.copy_from', 'namespaces', 'copyFrom / copy_from_namespace (incl. cross-region with source_api_key)', 'niche'),
+  todo('turbopuffer.namespaces.branch_from', 'namespaces', 'branchFrom / branch_from_namespace copy-on-write clones', 'niche'),
+  todo('turbopuffer.namespaces.update_metadata', 'namespaces', 'PATCH /v1/namespaces/{ns}/metadata (pinning replicas)', 'niche'),
+
+  // ── query ────────────────────────────────────────────────────────────────────────────────
+  done('turbopuffer.query.missing_namespace', 'query', 'querying a namespace that does not exist answers 404', 'core', () => withRoot(async (tp) => {
+    const q = await tp.query('nope', all);
+    return isError(q, 404) && q.body.error.includes('nope');
+  })),
+  done('turbopuffer.query.bm25', 'query', 'rank_by BM25 ranks matching documents by score and omits non-matching ones', 'core', () => withRoot(async (tp) => {
+    await tp.write('ns', PEOPLE);
+    const q = await tp.query('ns', { rank_by: ['title', 'BM25', 'dub'], top_k: 10 });
+    const rows = q.body.rows;
+    return same(ids(q), ['p3', 'p1']) && rows[0].$dist > rows[1].$dist && rows[1].$dist > 0;
+  })),
+  done('turbopuffer.query.bm25_last_as_prefix', 'query', 'BM25 last_as_prefix matches a typed prefix; a lone prefix token scores every match 1', 'common', () => withRoot(async (tp) => {
+    await tp.write('ns', PEOPLE);
+    const q = await tp.query('ns', { rank_by: ['title', 'BM25', 'ste', { last_as_prefix: true }] });
+    const exact = await tp.query('ns', { rank_by: ['title', 'BM25', 'ste'] });
+    return same(ids(q), ['p1', 'p2']) && q.body.rows.every((r: any) => r.$dist === 1) && same(exact.body.rows, []);
+  })),
+  done('turbopuffer.query.bm25_combinators', 'query', 'rank_by Sum / Max / Product over BM25 clauses', 'niche', () => withRoot(async (tp) => {
+    await tp.write('ns', { upsert_rows: [{ id: 'a', t: 'red', u: 'blue' }, { id: 'b', t: 'red', u: 'green' }], schema: { t: { type: 'string', full_text_search: { tokenizer: 'word_v2' } }, u: { type: 'string', full_text_search: { tokenizer: 'word_v2' } } } });
+    const sum = await tp.query('ns', { rank_by: ['Sum', [['t', 'BM25', 'red'], ['u', 'BM25', 'blue']]] });
+    const prod = await tp.query('ns', { rank_by: ['Product', 2, ['u', 'BM25', 'green']] });
+    const one = await tp.query('ns', { rank_by: ['u', 'BM25', 'green'] });
+    return same(ids(sum), ['a', 'b']) && sum.body.rows[0].$dist > sum.body.rows[1].$dist && Math.abs(prod.body.rows[0].$dist - 2 * one.body.rows[0].$dist) < 1e-9;
+  })),
+  done('turbopuffer.query.rank_by_attribute', 'query', 'rank_by [attr, asc|desc] orders by attribute, absent values last', 'core', () => withRoot(async (tp) => {
+    await tp.write('ns', { upsert_rows: [{ id: 'a', n: 2 }, { id: 'b', n: 9 }, { id: 'c' }, { id: 'd', n: 5 }] });
+    const desc = await tp.query('ns', { rank_by: ['n', 'desc'] });
+    const byId = await tp.query('ns', { rank_by: ['id', 'desc'], top_k: 2 });
+    return same(ids(desc), ['b', 'd', 'a', 'c']) && same(ids(byId), ['d', 'c']) && desc.body.rows[0].$dist === undefined;
+  })),
+  done('turbopuffer.query.ann', 'query', 'rank_by [vector, ANN, q] ranks by exact cosine / euclidean-squared distance', 'core', () => withRoot(async (tp) => {
+    await tp.write('ns', { upsert_rows: [{ id: 'x', vector: [1, 0] }, { id: 'y', vector: [0, 1] }, { id: 'z', vector: [1, 1] }], distance_metric: 'cosine_distance' });
+    const q = await tp.query('ns', { rank_by: ['vector', 'ANN', [1, 0]], top_k: 3, include_attributes: ['vector'] });
+    const d = q.body.rows.map((r: any) => r.$dist);
+    const badDims = await tp.query('ns', { rank_by: ['vector', 'ANN', [1, 0, 0]] });
+    return same(ids(q), ['x', 'z', 'y']) && Math.abs(d[0]) < 1e-12 && Math.abs(d[1] - (1 - Math.SQRT1_2)) < 1e-9 && Math.abs(d[2] - 1) < 1e-12
+      && same(q.body.rows[0].vector, [1, 0]) && isError(badDims, 400);
+  })),
+  done('turbopuffer.query.top_k', 'query', 'top_k / limit truncate the ranked rows (default 10)', 'core', () => withRoot(async (tp) => {
+    await tp.write('ns', { upsert_rows: Array.from({ length: 12 }, (_, i) => ({ id: i })) });
+    const def = await tp.query('ns', { rank_by: ['id', 'asc'] });
+    const two = await tp.query('ns', { rank_by: ['id', 'asc'], limit: 2 });
+    const bad = await tp.query('ns', { rank_by: ['id', 'asc'], top_k: 0 });
+    return def.body.rows.length === 10 && same(ids(two), [0, 1]) && isError(bad, 400);
+  })),
+  done('turbopuffer.query.include_attributes', 'query', 'include_attributes false|true|[names] and exclude_attributes shape the returned rows', 'core', () => withRoot(async (tp) => {
+    await tp.write('ns', { upsert_rows: [{ id: 'a', x: 1, y: 2 }] });
+    const none = await tp.query('ns', { ...all, include_attributes: false });
+    const some = await tp.query('ns', { ...all, include_attributes: ['y'] });
+    const allAttrs = await tp.query('ns', { ...all, include_attributes: true });
+    const ex = await tp.query('ns', { ...all, exclude_attributes: ['x'] });
+    return same(none.body.rows, [{ id: 'a' }]) && same(some.body.rows, [{ id: 'a', y: 2 }]) && same(allAttrs.body.rows, [{ id: 'a', x: 1, y: 2 }]) && same(ex.body.rows, [{ id: 'a', y: 2 }]);
+  })),
+  done('turbopuffer.query.aggregate_by', 'query', 'aggregate_by Count / Count(attr) / Sum(attr) over the filtered documents', 'common', () => withRoot(async (tp) => {
+    await tp.write('ns', PEOPLE);
+    const q = await tp.query('ns', { filters: ['score', 'Gt', 5], aggregate_by: { total: ['Count'], grouped: ['Count', 'group'], points: ['Sum', 'score'] } });
+    return q.status === 200 && same(q.body.aggregations, { total: 2, grouped: 1, points: 17 }) && q.body.rows === undefined && typeof q.body.billing === 'object';
+  })),
+  done('turbopuffer.query.multi_query', 'query', 'multiQuery answers each sub-query independently, in order', 'common', () => withRoot(async (tp) => {
+    await tp.write('ns', PEOPLE);
+    const q = await tp.req('POST', '/v2/namespaces/ns/query?stainless_overload=multiQuery', { queries: [{ rank_by: ['title', 'BM25', 'writer'], include_attributes: false }, { filters: ['group', 'Eq', 'g1'], aggregate_by: { n: ['Count'] } }] });
+    return q.status === 200 && same(q.body.results, [{ rows: [{ id: 'p2', $dist: q.body.results?.[0]?.rows?.[0]?.$dist }] }, { aggregations: { n: 1 } }]) && q.body.results[0].rows[0].$dist > 0;
+  })),
+  done('turbopuffer.query.rank_by_required', 'query', 'a query with neither rank_by nor aggregate_by is refused with 400', 'common', () => withRoot(async (tp) => {
+    await tp.write('ns', PEOPLE);
+    return isError(await tp.query('ns', { top_k: 3 }), 400);
+  })),
+  done('turbopuffer.query.response_envelope', 'query', 'query responses carry billing and performance objects', 'common', () => withRoot(async (tp) => {
+    await tp.write('ns', PEOPLE);
+    const q = await tp.query('ns', all);
+    return q.body.billing.billable_logical_bytes_queried > 0 && q.body.billing.billable_logical_bytes_returned > 0 && q.body.performance.approx_namespace_size === 3;
+  })),
+  todo('turbopuffer.query.group_by', 'query', 'group_by with aggregation_groups', 'common'),
+  todo('turbopuffer.query.compute_attributes', 'query', 'compute_attributes expressions ($ref_new, Highlight, VectorDist, Embed)', 'niche'),
+  todo('turbopuffer.query.aggregate_with_rank', 'query', 'aggregate_by together with rank_by in one query', 'niche'),
+  todo('turbopuffer.query.limit_per', 'query', 'limit.per (per-attribute diversity limits)', 'niche'),
+  todo('turbopuffer.query.multi_rerank', 'query', 'multiQuery rerank_by RRF fusion on the server', 'niche'),
+  todo('turbopuffer.query.rank_expressions', 'query', 'rank_by expressions beyond BM25/Sum/Max/Product: Saturate, Decay, Dist, Attribute, filters as rank terms', 'niche'),
+  todo('turbopuffer.query.highlight', 'query', 'Highlight expressions and highlight config (fragments, offsets)', 'niche'),
+  todo('turbopuffer.query.explain', 'query', 'POST /v2/namespaces/{ns}/explain_query', 'niche'),
+  todo('turbopuffer.query.recall', 'query', 'POST /v1/namespaces/{ns}/_debug/recall', 'niche'),
+
+  // ── filters ──────────────────────────────────────────────────────────────────────────────
+  done('turbopuffer.filters.eq_in', 'filters', 'Eq / NotEq / In / NotIn, where an absent attribute matches NotIn and NotEq', 'core', () => withRoot(async (tp) => {
+    await tp.write('ns', PEOPLE);
+    const eq = await tp.query('ns', { ...all, filters: ['group', 'Eq', 'g1'] });
+    const inq = await tp.query('ns', { ...all, filters: ['group', 'In', ['g1', 'g2']] });
+    const notIn = await tp.query('ns', { ...all, filters: ['group', 'NotIn', ['g1']] });
+    const notEq = await tp.query('ns', { ...all, filters: ['group', 'NotEq', 'g2'] });
+    const idIn = await tp.query('ns', { ...all, filters: ['id', 'In', ['p3', 'p1']] });
+    return same(ids(eq), ['p1']) && same(ids(inq), ['p1', 'p2']) && same(ids(notIn), ['p2', 'p3']) && same(ids(notEq), ['p1', 'p3']) && same(ids(idIn), ['p1', 'p3']);
+  })),
+  done('turbopuffer.filters.array_ops', 'filters', 'Contains / NotContains / ContainsAny / NotContainsAny on []string attributes', 'common', () => withRoot(async (tp) => {
+    await tp.write('ns', PEOPLE);
+    const any = await tp.query('ns', { ...all, filters: ['tags', 'ContainsAny', ['a', 'z']] });
+    const notAny = await tp.query('ns', { ...all, filters: ['tags', 'NotContainsAny', ['a']] });
+    const has = await tp.query('ns', { ...all, filters: ['tags', 'Contains', 'b'] });
+    return same(ids(any), ['p1']) && same(ids(notAny), ['p2', 'p3']) && same(ids(has), ['p1', 'p2']);
+  })),
+  done('turbopuffer.filters.range', 'filters', 'Lt / Lte / Gt / Gte and the Any* array forms', 'common', () => withRoot(async (tp) => {
+    await tp.write('ns', { upsert_rows: [{ id: 'a', n: 1, ns: [1, 9] }, { id: 'b', n: 5, ns: [2] }, { id: 'c', n: 9, ns: [] }] });
+    const lt = await tp.query('ns', { ...all, filters: ['n', 'Lt', 5] });
+    const gte = await tp.query('ns', { ...all, filters: ['n', 'Gte', 5] });
+    const anyGt = await tp.query('ns', { ...all, filters: ['ns', 'AnyGt', 5] });
+    return same(ids(lt), ['a']) && same(ids(gte), ['b', 'c']) && same(ids(anyGt), ['a']);
+  })),
+  done('turbopuffer.filters.boolean', 'filters', 'And / Or / Not compose filters', 'core', () => withRoot(async (tp) => {
+    await tp.write('ns', PEOPLE);
+    const q = await tp.query('ns', { ...all, filters: ['And', [['score', 'Gte', 5], ['Or', [['group', 'Eq', 'g1'], ['Not', ['tags', 'Contains', 'b']]]]]] });
+    return same(ids(q), ['p1', 'p3']);
+  })),
+  done('turbopuffer.filters.glob', 'filters', 'Glob / NotGlob / IGlob pattern filters', 'niche', () => withRoot(async (tp) => {
+    await tp.write('ns', { upsert_rows: [{ id: 'a', path: 'src/app.ts' }, { id: 'b', path: 'SRC/lib.ts' }, { id: 'c', path: 'docs/a.md' }] });
+    const g = await tp.query('ns', { ...all, filters: ['path', 'Glob', 'src/*.ts'] });
+    const ig = await tp.query('ns', { ...all, filters: ['path', 'IGlob', 'src/*'] });
+    const ng = await tp.query('ns', { ...all, filters: ['path', 'NotGlob', '*.ts'] });
+    return same(ids(g), ['a']) && same(ids(ig), ['a', 'b']) && same(ids(ng), ['c']);
+  })),
+  done('turbopuffer.filters.not_filterable', 'filters', 'a comparison filter on a non-filterable attribute is refused with 400', 'common', () => withRoot(async (tp) => {
+    await tp.write('ns', PEOPLE);
+    const q = await tp.query('ns', { ...all, filters: ['title', 'Eq', 'x'] });
+    const bad = await tp.query('ns', { ...all, filters: ['group', 'Between', [1, 2]] });
+    return isError(q, 400) && isError(bad, 400);
+  })),
+  done('turbopuffer.filters.contains_all_tokens', 'filters', 'ContainsAllTokens (with last_as_prefix) reads the full-text index', 'common', () => withRoot(async (tp) => {
+    await tp.write('ns', PEOPLE);
+    const q = await tp.query('ns', { ...all, filters: ['title', 'ContainsAllTokens', 'dub fo', { last_as_prefix: true }] });
+    const exact = await tp.query('ns', { ...all, filters: ['title', 'ContainsAllTokens', 'dub fo'] });
+    const noFts = await tp.query('ns', { ...all, filters: ['group', 'ContainsAllTokens', 'g1'] });
+    return same(ids(q), ['p1']) && same(ids(exact), []) && isError(noFts, 400);
+  })),
+  done('turbopuffer.filters.contains_any_token', 'filters', 'ContainsAnyToken matches documents sharing any query token', 'common', () => withRoot(async (tp) => {
+    await tp.write('ns', PEOPLE);
+    const q = await tp.query('ns', { ...all, filters: ['title', 'ContainsAnyToken', 'writer engineer'] });
+    const stop = await tp.query('ns', { ...all, filters: ['title', 'ContainsAllTokens', 'the'] });
+    return same(ids(q), ['p2', 'p3']) && same(ids(stop), []);
+  })),
+  done('turbopuffer.filters.id_paging', 'filters', 'id range filters page mixed numeric and string ids in rank_by [id, asc] order without skipping either type', 'common', () => withRoot(async (tp) => {
+    await tp.write('ns', { upsert_rows: [{ id: 'b' }, { id: 2 }, { id: 'a' }, { id: 10 }] });
+    const first = await tp.query('ns', { rank_by: ['id', 'asc'], top_k: 2 });
+    const next = await tp.query('ns', { rank_by: ['id', 'asc'], top_k: 2, filters: ['id', 'Gt', 10] });
+    return same(ids(first), [2, 10]) && same(ids(next), ['a', 'b']);
+  })),
+  todo('turbopuffer.filters.regex', 'filters', 'Regex filters (regex: true attributes)', 'common'),
+  todo('turbopuffer.filters.fuzzy', 'filters', 'Fuzzy filters (edit-distance matching)', 'niche'),
+  todo('turbopuffer.filters.contains_token_sequence', 'filters', 'ContainsTokenSequence (phrase) filters', 'niche'),
+
+  // ── full-text search configuration ───────────────────────────────────────────────────────
+  done('turbopuffer.fts.word_v2', 'fts', 'word_v2 splits URLs and punctuation into word tokens, case-insensitively; stopwords are kept unless remove_stopwords is set', 'core', () => withRoot(async (tp) => {
+    await tp.write('ns', { upsert_rows: [{ id: 'u', title: 'https://www.ScottDigital-42.techcorp.io' }, { id: 's', title: 'the and of' }], schema: FTS });
+    await tp.write('stop', { upsert_rows: [{ id: 's', title: 'the and of' }], schema: { title: { type: 'string', full_text_search: { tokenizer: 'word_v2', remove_stopwords: true } } } });
+    const q = await tp.query('ns', { rank_by: ['title', 'BM25', 'scottdigital'] });
+    const kept = await tp.query('ns', { rank_by: ['title', 'BM25', 'the'] });
+    const stop = await tp.query('stop', { rank_by: ['title', 'BM25', 'the'] });
+    return same(ids(q), ['u']) && same(ids(kept), ['s']) && same(stop.body.rows, []);
+  })),
+  done('turbopuffer.fts.unmodelled_config_refused', 'fts', 'unmodelled tokenizers and languages are refused, never silently approximated', 'common', () => withRoot(async (tp) => {
+    const v4 = await tp.write('ns', { upsert_rows: [{ id: 'a', t: 'x' }], schema: { t: { type: 'string', full_text_search: { tokenizer: 'word_v0' } } } });
+    const stem = await tp.write('ns', { upsert_rows: [{ id: 'a', t: 'x' }], schema: { t: { type: 'string', full_text_search: { tokenizer: 'word_v2', language: 'german' } } } });
+    return isError(v4, 400) && v4.body.error.includes('turbopuffer.fts.tokenizers') && isError(stem, 400);
+  })),
+  todo('turbopuffer.fts.tokenizers', 'fts', 'tokenizers word_v0 / word_v1 / word_v3 / word_v4 (the default)', 'common'),
+  todo('turbopuffer.fts.stemming', 'fts', 'language-specific stemming', 'common'),
+  todo('turbopuffer.fts.languages', 'fts', 'non-English languages (stopword lists, stemmers)', 'niche'),
+  todo('turbopuffer.fts.exact_bm25_scores', 'fts', 'BM25 $dist values byte-equal to Turbopuffer\'s own scorer (the twin\'s are deterministic textbook Okapi)', 'common'),
+
+  // ── vectors / schema options ─────────────────────────────────────────────────────────────
+  todo('turbopuffer.vectors.base64', 'vectors', 'base64 vector encoding (writes and vector_encoding: base64)', 'niche'),
+  todo('turbopuffer.vectors.named_attributes', 'vectors', 'vector-typed attributes other than "vector"', 'niche'),
+  todo('turbopuffer.vectors.multi', 'vectors', 'multi-vector ANN / late interaction', 'niche'),
+  todo('turbopuffer.vectors.sparse', 'vectors', 'sparse vectors ({}f16) and SparseKNN', 'niche'),
+  todo('turbopuffer.vectors.embed', 'vectors', 'server-side embedding (Embed expressions, embed schema)', 'common'),
+  todo('turbopuffer.schema.embed', 'schema', 'the embed schema option', 'niche'),
+  todo('turbopuffer.schema.fuzzy', 'schema', 'the fuzzy schema option', 'niche'),
+  todo('turbopuffer.schema.sparse_knn', 'schema', 'the sparse_knn schema option', 'niche'),
+
+  // ── protocol ─────────────────────────────────────────────────────────────────────────────
+  done('turbopuffer.auth.bearer', 'auth', 'requests without a Bearer API key are refused with 401', 'core', () => withRoot(async (tp) => {
+    const none = await tp.req('GET', '/v1/namespaces', undefined, {});
+    const empty = await tp.req('GET', '/v1/namespaces', undefined, { authorization: 'Bearer ' });
+    const okr = await tp.req('GET', '/v1/namespaces');
+    return isError(none, 401) && isError(empty, 401) && okr.status === 200;
+  })),
+  done('turbopuffer.wire.region_prefix', 'wire', 'a leading region segment (TURBOPUFFER_BASE_URL=<twin>/{region}) reaches the same namespace', 'core', () => withRoot(async (tp) => {
+    await tp.req('POST', '/aws-us-east-1/v2/namespaces/ns', { upsert_rows: [{ id: 'r' }] });
+    const q = await tp.req('POST', '/v2/namespaces/ns/query', all);
+    const q2 = await tp.req('POST', '//gcp-us-central1/v2/namespaces/ns/query', all);
+    return same(ids(q), ['r']) && same(ids(q2), ['r']);
+  })),
+  done('turbopuffer.errors.envelope', 'errors', 'errors wear {status:"error", error}; unknown routes 404; unmodelled routes name their gap', 'common', () => withRoot(async (tp) => {
+    const unknown = await tp.req('GET', '/v9/whatever');
+    const gap = await tp.req('POST', '/v2/namespaces/ns/explain_query', {});
+    const bad = await handleTurbopufferTwinRequest({ method: 'POST', path: '/v2/namespaces/ns', headers: AUTH, root: tp.root, occurredAt: AT, body: '{not json' });
+    return isError(unknown, 404) && isError(gap, 404) && gap.body.error.includes('turbopuffer.query.explain') && bad.status === 400;
+  })),
+  todo('turbopuffer.errors.vendor_error_strings', 'errors', 'Turbopuffer\'s literal error message strings (the twin\'s are its own)', 'common'),
+  todo('turbopuffer.legacy.v1_api', 'legacy', 'the v1 namespace API older SDKs call (POST /v1/namespaces/{ns}, /v1/namespaces/{ns}/query)', 'niche'),
+  done('turbopuffer.conformance.endpoint_probe', 'conformance', 'one live request per claimed endpoint asserts its outcome; the router census holds', 'common', async () => (await checkTurbopufferConformance()).ok),
+
+  // ── connector (the real state system) ────────────────────────────────────────────────────
+  done('turbopuffer.connector.perform_write', 'connector', 'perform replays a recorded write / deleteAll / schema update against the vendor wire', 'core', async () => {
+    const seen: Array<{ method: string; path: string; body?: string }> = [];
+    const execute: RemoteExecute = async (r) => { seen.push({ method: r.method, path: r.path, ...(typeof r.body === 'string' ? { body: r.body } : {}) }); return { status: 200, headers: {}, body: '{"status":"OK","rows_affected":1}' }; };
+    const base = { id: 'x', service: 'turbopuffer', op: 'set', subject: { type: 'namespace', id: 'my-ns' }, occurredAt: AT } as unknown as TwinAction;
+    const input = { upsert_rows: [{ id: 'a', t: 'x' }] };
+    const w = await performTurbopufferAction(execute, { ...base, operation: 'namespace.write', input } as TwinAction, { resolve: (_t, id) => id });
+    await performTurbopufferAction(execute, { ...base, operation: 'namespace.delete_all' } as TwinAction, { resolve: (_t, id) => id });
+    let refused = false;
+    try { await performTurbopufferAction(execute, { ...base, operation: 'namespace.bogus' } as TwinAction, { resolve: (_t, id) => id }); } catch { refused = true; }
+    return w.externalId === 'my-ns' && seen[0]?.method === 'POST' && seen[0]?.path === '/v2/namespaces/my-ns' && same(JSON.parse(seen[0]?.body ?? 'null'), input)
+      && seen[1]?.method === 'DELETE' && seen[1]?.path === '/v2/namespaces/my-ns' && refused;
+  }, 'connector'),
+  done('turbopuffer.connector.refresh', 'connector', 'refresh observes a real account\'s namespaces, schema and documents into the tree', 'common', async () => {
+    const vendor = mkdtempSync(join(tmpdir(), 'turbopuffer-vendor-'));
+    const local = mkdtempSync(join(tmpdir(), 'turbopuffer-local-'));
+    try {
+      const send = async (root: string, method: string, path: string, body?: string) => {
+        const r = await handleTurbopufferTwinRequest({ method, path, headers: AUTH, root, occurredAt: AT, ...(body === undefined ? {} : { body }) });
+        return { status: r.status, headers: {}, body: JSON.stringify(r.body) };
+      };
+      await send(vendor, 'POST', '/v2/namespaces/remote', JSON.stringify(PEOPLE));
+      const execute: RemoteExecute = (r) => send(vendor, r.method, r.path, typeof r.body === 'string' ? r.body : undefined);
+      const report = await syncTurbopufferFromRemote(execute, { root: local, occurredAt: AT });
+      const q = JSON.parse((await send(local, 'POST', '/v2/namespaces/remote/query', JSON.stringify({ rank_by: ['title', 'BM25', 'writer'], include_attributes: ['group'] }))).body);
+      let threw = false;
+      try { await syncTurbopufferFromRemote(async () => ({ status: 401, headers: {}, body: '{"status":"error","error":"unauthorized"}' }), { root: local }); } catch { threw = true; }
+      return report.observed === 4 && same(q.rows?.map((r: any) => [r.id, r.group]), [['p2', 'g2']]) && threw;
+    } finally {
+      rmSync(vendor, { recursive: true, force: true });
+      rmSync(local, { recursive: true, force: true });
+    }
+  }, 'connector'),
+];
+
+/** Committed area census: the SDK's surface groups (write, query, filters, full-text, vectors,
+ *  schema options, namespace management) plus the protocol and connector areas. */
+export const TURBOPUFFER_AREAS = [
+  'auth',
+  'conformance',
+  'connector',
+  'errors',
+  'filters',
+  'fts',
+  'legacy',
+  'namespaces',
+  'query',
+  'schema',
+  'vectors',
+  'wire',
+  'write',
+] as const;
+
+export function turbopufferCapabilities(): Promise<CapabilityReport> {
+  return checkCapabilities('turbopuffer', TURBOPUFFER_CAPABILITIES);
+}

package/src/turbopuffer-conformance.ts

@@ -0,0 +1,101 @@
+// Turbopuffer conformance (dev-only; lazily imported by the CLI). One real request per claimed
+// endpoint against a throwaway root, each asserting an OUTCOME only the live handler produces
+// (values, not statuses), plus a ROUTER_SURFACE pass: every route the router branches on is named
+// and exercised, and an unclaimed route must answer the not-found envelope.
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { handleTurbopufferTwinRequest, turbopufferTwinSnapshot } from './turbopuffer-twin.ts';
+
+export type TurbopufferConformanceReport = { ok: boolean; checksRun: number; failures: string[] };
+
+const AUTH = { authorization: 'Bearer conformance' };
+const AT = '2026-09-23T00:00:00.000Z';
+
+type Probe = { endpoint: string; method: string; path: string; body?: unknown; expect: (status: number, body: any) => boolean };
+
+const PROBES: Probe[] = [
+  {
+    endpoint: 'POST /v2/namespaces/{ns}', method: 'POST', path: '/v2/namespaces/conf',
+    body: { upsert_rows: [{ id: 'a', title: 'alpha beta' }, { id: 'b', title: 'beta gamma', tag: 'x' }], schema: { title: { type: 'string', full_text_search: { tokenizer: 'word_v2' } } } },
+    expect: (s, b) => s === 200 && b.status === 'OK' && b.rows_affected === 2 && b.rows_upserted === 2,
+  },
+  {
+    endpoint: 'POST /v2/namespaces/{ns}/query', method: 'POST', path: '/v2/namespaces/conf/query',
+    body: { rank_by: ['title', 'BM25', 'gamma'], top_k: 5, include_attributes: ['title'] },
+    expect: (s, b) => s === 200 && Array.isArray(b.rows) && b.rows.length === 1 && b.rows[0].id === 'b' && b.rows[0].title === 'beta gamma' && typeof b.rows[0].$dist === 'number',
+  },
+  {
+    endpoint: 'GET /v2/namespaces/{ns}/metadata', method: 'GET', path: '/v2/namespaces/conf/metadata',
+    expect: (s, b) => s === 200 && b.approx_row_count === 2 && b.schema?.title?.full_text_search?.tokenizer === 'word_v2',
+  },
+  {
+    endpoint: 'GET /v1/namespaces/{ns}/schema', method: 'GET', path: '/v1/namespaces/conf/schema',
+    expect: (s, b) => s === 200 && b.tag?.type === 'string' && b.title?.filterable === false,
+  },
+  {
+    endpoint: 'POST /v1/namespaces/{ns}/schema', method: 'POST', path: '/v1/namespaces/conf/schema',
+    body: { tag: { type: 'string', filterable: true } },
+    expect: (s, b) => s === 200 && b.tag?.filterable === true,
+  },
+  {
+    endpoint: 'GET /v1/namespaces/{ns}/hint_cache_warm', method: 'GET', path: '/v1/namespaces/conf/hint_cache_warm',
+    expect: (s, b) => s === 202 && b.status === 'ACCEPTED',
+  },
+  {
+    endpoint: 'GET /v1/namespaces', method: 'GET', path: '/v1/namespaces?prefix=con',
+    expect: (s, b) => s === 200 && Array.isArray(b.namespaces) && b.namespaces.length === 1 && b.namespaces[0].id === 'conf',
+  },
+  {
+    endpoint: 'DELETE /v2/namespaces/{ns}', method: 'DELETE', path: '/v2/namespaces/conf',
+    expect: (s, b) => s === 200 && b.status === 'OK',
+  },
+];
+
+/** Every method+path pair the router branches on; each must be reached by a live request below. */
+const ROUTER_SURFACE: Array<{ method: string; path: string; claimed: boolean }> = [
+  { method: 'GET', path: '/v1/namespaces', claimed: true },
+  { method: 'POST', path: '/v2/namespaces/x', claimed: true },
+  { method: 'DELETE', path: '/v2/namespaces/x', claimed: true },
+  { method: 'POST', path: '/v2/namespaces/x/query', claimed: true },
+  { method: 'GET', path: '/v2/namespaces/x/metadata', claimed: true },
+  { method: 'GET', path: '/v1/namespaces/x/schema', claimed: true },
+  { method: 'POST', path: '/v1/namespaces/x/schema', claimed: true },
+  { method: 'GET', path: '/v1/namespaces/x/hint_cache_warm', claimed: true },
+  { method: 'PATCH', path: '/v1/namespaces/x/metadata', claimed: false },
+  { method: 'POST', path: '/v2/namespaces/x/explain_query', claimed: false },
+];
+
+export async function checkTurbopufferConformance(options: { root?: string } = {}): Promise<TurbopufferConformanceReport> {
+  const failures: string[] = [];
+  let checksRun = 0;
+  const root = options.root ?? mkdtempSync(join(tmpdir(), 'turbopuffer-conformance-'));
+  const send = (method: string, path: string, body?: unknown) =>
+    handleTurbopufferTwinRequest({ method, path, headers: AUTH, root, occurredAt: AT, ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+  try {
+    // Two-way bijection between the probe table and the snapshot's claimed endpoints.
+    const claimed = new Set(turbopufferTwinSnapshot().implementedEndpoints);
+    const probed = new Set(PROBES.map((p) => p.endpoint));
+    for (const e of claimed) if (!probed.has(e)) failures.push(`claimed endpoint without a probe: ${e}`);
+    for (const e of probed) if (!claimed.has(e)) failures.push(`probe for an unclaimed endpoint: ${e}`);
+    for (const p of PROBES) {
+      checksRun++;
+      const res = await send(p.method, p.path, p.body);
+      if (!p.expect(res.status, res.body)) failures.push(`${p.endpoint}: unexpected ${res.status} ${JSON.stringify(res.body).slice(0, 200)}`);
+    }
+    // Router census: an unclaimed route answers a 404 naming its gap; a claimed one is not the router's miss.
+    for (const r of ROUTER_SURFACE) {
+      checksRun++;
+      const res = await send(r.method, r.path, r.method === 'GET' || r.method === 'DELETE' ? undefined : {});
+      const miss = res.status === 404 && JSON.stringify(res.body).includes('not found: ');
+      if (r.claimed && miss) failures.push(`router: ${r.method} ${r.path} is claimed but answered the router miss`);
+      if (!r.claimed && !(res.status === 404 && JSON.stringify(res.body).includes('filed gap'))) failures.push(`router: ${r.method} ${r.path} should answer the filed-gap 404`);
+    }
+    checksRun++;
+    const unknown = await send('GET', '/v9/never');
+    if (!(unknown.status === 404 && (unknown.body as { status?: string }).status === 'error')) failures.push('an unknown route must answer the error envelope with 404');
+  } finally {
+    if (options.root === undefined) rmSync(root, { recursive: true, force: true });
+  }
+  return { ok: failures.length === 0, checksRun, failures };
+}