@volter/twin-turbopuffer 0.1.0

package/dist/src/turbopuffer-twin.js

@@ -0,0 +1,406 @@
+// 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 } 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, } from "./turbopuffer-store.js";
+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 = [
+    { 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, error) {
+    return { status, body: { status: 'error', error }, headers: { ...JSON_HEADERS } };
+}
+function ok(body) {
+    return { status: 200, body, headers: { ...JSON_HEADERS } };
+}
+function lowerHeaders(h) {
+    const out = {};
+    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) {
+    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) {
+    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) {
+    let name;
+    try {
+        name = decodeURIComponent(seg);
+    }
+    catch {
+        name = seg;
+    }
+    assertNamespaceName(name);
+    return name;
+}
+function parseBody(raw) {
+    if (raw === undefined || raw.trim() === '')
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw badRequest('invalid request: body is not valid JSON');
+    }
+}
+function notFound(ns) {
+    return new TurbopufferError(404, `namespace '${ns}' was not found`);
+}
+function readSpace(ns, root) {
+    const space = loadNamespaces(twinResources(SERVICE, root)).get(ns);
+    if (space === undefined)
+        throw notFound(ns);
+    return space;
+}
+export async function handleTurbopufferTwinRequest(req) {
+    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, root) {
+    readSpace(ns, root);
+    return { status: 202, body: { status: 'ACCEPTED', message: 'cache warm hint accepted' }, headers: { ...JSON_HEADERS } };
+}
+function unrouted(method, path) {
+    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, path, e) {
+    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, ns, method, path, at) {
+    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, query) {
+    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] } : {}),
+    };
+}
+async function commit(req, decide) {
+    if (req.readOnly)
+        return fail(405, 'read_only: this twin was started read-only; writes are refused');
+    const { value } = await applyTwinWriteAtomic(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) {
+    if (e instanceof TurbopufferError)
+        return { kind: 'skip', value: { ok: false, error: e } };
+    throw e;
+}
+function write(req, ns, body, at) {
+    return commit(req, (spaces) => {
+        const b = body !== null && typeof body === 'object' && !Array.isArray(body) ? body : {};
+        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,
+                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, body) {
+    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.copy_from_namespace !== undefined;
+}
+async function asyncCopy(req, ns, body, at) {
+    if (req.readOnly)
+        return fail(405, 'read_only: this twin was started read-only; writes are refused');
+    const { value: token } = await applyTwinWriteAtomic(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) => ({ 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,
+                    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, ns, token, at) {
+    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, ns, at) {
+    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, ns, body, at) {
+    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, body, root) {
+    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;
+    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, queries, results) {
+    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] ?? {});
+    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();
+    results.forEach((r, i) => r.rows.forEach((row, at) => {
+        const id = JSON.stringify(row.id);
+        const hit = fused.get(id) ?? { row, score: 0 };
+        hit.score += weights[i] / (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) {
+    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() {
+    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',
+        ],
+    };
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@volter/twin-turbopuffer",
+  "version": "0.1.0",
+  "description": "Local Turbopuffer twin: v2 namespaces (write upserts/patches/deletes by id or filter with schema and distance_metric; query with filters, deterministic BM25 incl. last_as_prefix, attribute order, exact ANN and Count/Sum aggregates; multiQuery; deleteAll; metadata; schema; namespace listing) served to the unmodified @turbopuffer/turbopuffer client. Built on @volter/world-core.",
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/turbopuffer"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/turbopuffer#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-turbopuffer": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "dependencies": {
+    "@volter/world-ui": "0.1.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-turbopuffer CLI: serve the KERNEL-BACKED Turbopuffer twin, or run conformance. State lives
+// in the @volter/world-core log under --root. Conformance is dev-only + lazy-imported.
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createTurbopufferTwinServer } from './turbopuffer-server.ts';
+
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', String(process.env.PORT ?? '0'))) || undefined;
+const root = optionValue(rest, '--root') || process.env.VOLTER_STATE_DIR || undefined;
+const token = optionValue(rest, '--token') || undefined;
+const readOnly = hasFlag(rest, '--read-only');
+
+if (cmd === 'serve' || cmd === undefined) {
+  const s = await createTurbopufferTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(token ? { token } : {}) });
+  process.stdout.write(
+    `turbopuffer twin (v2 namespaces: write, query, multiQuery, deleteAll, metadata, schema)${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${s.port}\n`
+    + `  point the SDK at it with TURBOPUFFER_BASE_URL=http://127.0.0.1:${s.port}/{region} and any non-empty TURBOPUFFER_API_KEY\n`,
+  );
+  await keepProcessAlive();
+} else if (cmd === 'conformance') {
+  const { checkTurbopufferConformance } = await import('./turbopuffer-conformance.ts');
+  const report = await checkTurbopufferConformance(root ? { root } : {});
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+} else {
+  process.stdout.write('Usage: world-turbopuffer serve|conformance [--port N] [--root DIR] [--token KEY] [--read-only]\n');
+}

package/src/generated/surface.gen.json

@@ -0,0 +1 @@
+{"generatedBy":"scripts/derive-pack.ts","spec":"openapi.yaml.gz","format":"openapi","version":"0.0.1","resources":[{"name":"NamespaceSummary","schema":"NamespaceSummary","fields":[{"name":"id","type":"string","nullable":false,"required":true}],"stateCandidates":[],"expandable":[]}],"operations":[{"id":"get_v1_namespaces","method":"get","path":"/v1/namespaces","pathParams":[],"query":[{"name":"cursor","type":"string","required":false},{"name":"page_size","type":"integer","required":false},{"name":"prefix","type":"string","required":false}],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"NamespaceSummary","list":true,"key":"namespaces"},"class":"list","resource":"NamespaceSummary"},{"id":"post_v1_namespaces_namespace_debug_recall","method":"post","path":"/v1/namespaces/{namespace}/_debug/recall","pathParams":["namespace"],"query":[],"body":[{"name":"filters","type":"any","required":false},{"name":"include_ground_truth","type":"boolean","required":false},{"name":"num","type":"integer","required":false},{"name":"rank_by","type":"any","required":false},{"name":"top_k","type":"integer","required":false}],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"get_v1_namespaces_namespace_hint_cache_warm","method":"get","path":"/v1/namespaces/{namespace}/hint_cache_warm","pathParams":["namespace"],"query":[],"body":[],"bodyEncoding":"none","successStatus":202,"class":"computed"},{"id":"get_v1_namespaces_namespace_metadata","method":"get","path":"/v1/namespaces/{namespace}/metadata","pathParams":["namespace"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"},{"id":"patch_v1_namespaces_namespace_metadata","method":"patch","path":"/v1/namespaces/{namespace}/metadata","pathParams":["namespace"],"query":[],"body":[{"name":"pinning","type":"union","required":false}],"bodyEncoding":"json","successStatus":200,"class":"update"},{"id":"get_v1_namespaces_namespace_operations_token","method":"get","path":"/v1/namespaces/{namespace}/operations/{token}","pathParams":["namespace","token"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"},{"id":"get_v1_namespaces_namespace_schema","method":"get","path":"/v1/namespaces/{namespace}/schema","pathParams":["namespace"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"},{"id":"post_v1_namespaces_namespace_schema","method":"post","path":"/v1/namespaces/{namespace}/schema","pathParams":["namespace"],"query":[],"body":[],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"post_v2_namespaces_namespace","method":"post","path":"/v2/namespaces/{namespace}","pathParams":["namespace"],"query":[],"body":[{"name":"branch_from_namespace","type":"BranchFromNamespaceParams","required":false},{"name":"copy_from_namespace","type":"CopyFromNamespaceParams","required":false},{"name":"delete_by_filter","type":"any","required":false},{"name":"delete_by_filter_allow_partial","type":"boolean","required":false},{"name":"delete_condition","type":"any","required":false},{"name":"deletes","type":"array","required":false},{"name":"disable_backpressure","type":"boolean","required":false},{"name":"distance_metric","type":"DistanceMetric","required":false},{"name":"encryption","type":"Encryption","required":false},{"name":"patch_by_filter","type":"PatchByFilter","required":false},{"name":"patch_by_filter_allow_partial","type":"boolean","required":false},{"name":"patch_columns","type":"Columns","required":false},{"name":"patch_condition","type":"any","required":false},{"name":"patch_rows","type":"array","required":false},{"name":"return_affected_ids","type":"boolean","required":false},{"name":"schema","type":"object","required":false},{"name":"sharding","type":"ShardingConfig","required":false},{"name":"upsert_columns","type":"Columns","required":false},{"name":"upsert_condition","type":"any","required":false},{"name":"upsert_rows","type":"array","required":false}],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"delete_v2_namespaces_namespace","method":"delete","path":"/v2/namespaces/{namespace}","pathParams":["namespace"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"delete"},{"id":"post_v2_namespaces_namespace_explain_query","method":"post","path":"/v2/namespaces/{namespace}/explain_query","pathParams":["namespace"],"query":[],"body":[],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"get_v2_namespaces_namespace_metadata","method":"get","path":"/v2/namespaces/{namespace}/metadata","pathParams":["namespace"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"},{"id":"post_v2_namespaces_namespace_query","method":"post","path":"/v2/namespaces/{namespace}/query","pathParams":["namespace"],"query":[],"body":[],"bodyEncoding":"json","successStatus":200,"class":"non-resource"}]}

package/src/generated/ui.gen.json

@@ -0,0 +1 @@
+{"generatedBy":"scripts/derive-pack.ts","resources":{}}

package/src/index.ts

@@ -0,0 +1,92 @@
+// @volter/twin-turbopuffer — the Turbopuffer API twin (v2 namespaces), built on @volter/world-core.
+// Namespaces and their documents are kernel state; writes (upsert/patch/delete by id or filter,
+// with schema and distance metric) land as one kernel action per request; queries filter, BM25-rank
+// (deterministic, see turbopuffer-text.ts), order by attribute, rank by exact vector distance and
+// count. See README ## Coverage for what is modelled and what fails loudly.
+import { registerPack, type TwinPack } from '@volter/world-core';
+import { performTurbopufferAction, syncTurbopufferFromRemote } from './turbopuffer-connector.ts';
+
+export {
+  handleTurbopufferTwinRequest,
+  extractTurbopufferApiKey,
+  normalizeTurbopufferPath,
+  turbopufferTwinSnapshot,
+} from './turbopuffer-twin.ts';
+export type { TurbopufferTwinRequest, TurbopufferTwinResponse } from './turbopuffer-twin.ts';
+export { createTurbopufferTwinFetch, createTurbopufferTwinServer } from './turbopuffer-server.ts';
+export type { TurbopufferTwinFetchOptions } from './turbopuffer-server.ts';
+export { performTurbopufferAction, syncTurbopufferFromReal, syncTurbopufferFromRemote, mapSchemaAttr } from './turbopuffer-connector.ts';
+export {
+  SERVICE,
+  TURBOPUFFER_RESOURCE_TYPES,
+  TurbopufferError,
+  applyWrite,
+  runQuery,
+  loadNamespaces,
+  schemaWire,
+  cosineDistance,
+  euclideanSquared,
+} from './turbopuffer-store.ts';
+export type { NamespaceState, AttrConfig, Doc } from './turbopuffer-store.ts';
+export { compileFilter } from './turbopuffer-filter.ts';
+export { tokenize, queryTerms, bm25Score, buildCorpus, DEFAULT_FTS } from './turbopuffer-text.ts';
+
+// Registry descriptor (TwinPack) — the SINGLE HOME for this vendor's world-facing facts.
+// `bun scripts/pack-facts.ts` compiles `adoption` / `hosts` / `endpointEnv` into
+// packages/world-core/generated/pack-facts.json; re-run it after ANY edit below.
+export const pack: TwinPack = {
+  vendor: 'turbopuffer',
+  transport: 'rest',
+  protocol: '2',
+  archetype: 'crud',
+  bin: 'world-turbopuffer',
+  resources: ['namespace', 'document'],
+  specSource:
+    'the OpenAPI document @turbopuffer/turbopuffer@2.8.0 was generated from (spec/openapi.yaml.gz, provenance in spec/SOURCE.md), with its generator pseudo-paths folded into the operations turbopuffer documents (spec/patches.json); the calls dubinc/dub makes (apps/web/lib/api/partners/search/providers/turbopuffer.ts).',
+  description:
+    'Turbopuffer v2 namespaces twin — write (upsert/patch/delete rows or columns, delete/patch by filter, schema, distance_metric), query (filters, BM25 with last_as_prefix and Sum/Max/Product, attribute order, exact ANN, Count/Sum aggregates), multiQuery, deleteAll, metadata, schema, list namespaces. Deterministic BM25 (textbook Okapi over a word_v2 approximation — not byte-equal to the vendor). Kernel-backed, no mirror; unmodelled surface answers 400/404 naming its todo.',
+
+  refresh: { every: '15m', onDemand: { atMost: '30s' } },
+  stateSystem: { perform: performTurbopufferAction, refresh: syncTurbopufferFromRemote },
+  // An upsert of a caller-chosen id: the vendor's own idempotence, so the branch re-send lands cleanly.
+  roundTrip: {
+    method: 'POST',
+    path: '/v2/namespaces/round-trip',
+    body: { upsert_rows: [{ id: 'round-trip', title: 'round trip' }] },
+    headers: { authorization: 'Bearer round-trip' },
+  },
+
+  // ADOPTION — the official Node client (`@turbopuffer/turbopuffer`, the scope is Turbopuffer's
+  // alone), the official Python client (`turbopuffer` on PyPI), and the TURBOPUFFER_ env stem
+  // (TURBOPUFFER_API_KEY / _REGION / _BASE_URL, all read by the SDK in client.ts).
+  adoption: {
+    sdks: ['@turbopuffer/turbopuffer'],
+    pypi: ['turbopuffer'],
+    scopes: ['@turbopuffer/'],
+    envStems: ['TURBOPUFFER'],
+  },
+
+  // INTERCEPTION — the SDK's default base URL is `https://{region}.turbopuffer.com`
+  // (client.ts:273), the region filled from the `region` option or TURBOPUFFER_REGION: regional
+  // hosts such as aws-us-east-1.turbopuffer.com and gcp-us-central1.turbopuffer.com.
+  hosts: [{ hostPattern: '^(?:aws|gcp|azure)-[a-z0-9-]+\\.turbopuffer\\.com$' },
+    // the dashboard's sign-in and API keys pages and the World's sign-up door (screens/dashboard.tsx); the rest of
+    // turbopuffer.com (its site and docs) is left alone
+    { host: 'turbopuffer.com', pathPattern: '^/(login|dashboard|_twin/users)(/|$)' },
+  ],
+
+  // WORLD WIRING — under Node the SDK sends through undici's `Agent.request`
+  // (internal/custom/fetch-node.ts, selected by the package's `#fetch` import map for the `node`
+  // condition), which neither the injector's http/https/fetch patches nor HTTPS_PROXY reach. The
+  // SDK's own `TURBOPUFFER_BASE_URL` (client.ts:253) is the interception. It must carry the
+  // `{region}` placeholder: a client that passes `region` (Dub passes "aws-us-east-1") throws
+  // "region is set, but would be ignored" against a base URL without one (client.ts:282-285). The
+  // twin accepts and ignores that leading region segment.
+  endpointEnv: {
+    name: 'TURBOPUFFER_TWIN_URL',
+    templates: { TURBOPUFFER_BASE_URL: '${url}/{region}' },
+    note: 'grounded in @turbopuffer/turbopuffer@2.8.0 src/client.ts:253-288 (TURBOPUFFER_BASE_URL, {region} placeholder substitution) and internal/custom/fetch-node.ts (undici Agent.request under node, outside the injector); the injector also claims the regional *.turbopuffer.com hosts for fetch-based runtimes.',
+  },
+};
+
+registerPack(pack);

package/src/key-gate.ts

@@ -0,0 +1,39 @@
+// The API key gate, in front of the derived dispatch. "The HTTP API expects the API key to be formatted as a standard
+// Bearer token and passed in the Authorization header", and keys are made and expired on the dashboard
+// (https://turbopuffer.com/docs/auth; screens/dashboard.tsx).
+//
+// What the gate refuses, and where turbopuffer's documentation stops:
+// - a key the dashboard made and then expired, and a key of turbopuffer's form (`tpuf_…`) the dashboard never made:
+//   401, the twin's reading. turbopuffer's pages print only the error body (https://turbopuffer.com/docs/api-overview)
+//   and name no status for a bad key; 401 is the status turbopuffer's own client reads as a failed authentication
+//   (`if (status === 401) return new AuthenticationError(...)`, https://raw.githubusercontent.com/turbopuffer/turbopuffer-typescript/v2.8.0/src/core/error.ts).
+// - a key without the permission an operation needs, only where turbopuffer says which: listing namespaces "is available
+//   to API keys with list or admin permissions" (https://turbopuffer.com/docs/namespaces). 403, the twin's reading, by
+//   the same client line's neighbour (`if (status === 403) return new PermissionDeniedError(...)`); no page prints the
+//   answer for a key that lacks a permission. The messages are the twin's.
+// Every other operation admits any live key: the docs name read/write permissions without saying which endpoint needs
+// which, so the twin enforces none of them (manifest.ts records the gap).
+// A key that is not of turbopuffer's form is the World's own (a World pointing an application at the twin with a key
+// of its choosing) and is not checked here; the request handler still refuses a request with no key (401).
+import { createHash } from 'node:crypto';
+import type { SemanticsContext } from '@volter/world-core';
+
+const refuse = (status: number, error: string): Response => Response.json({ status: 'error', error }, { status });
+
+/** Operations whose permission turbopuffer documents, and the permissions that admit a key to each. */
+const NEEDS: Record<string, readonly string[]> = { get_v1_namespaces: ['list', 'admin'] };
+
+/** The gate's answer for a request to `operation`, or undefined when it may pass. */
+export function keyGate(ctx: SemanticsContext, request: Request, operation: string): Response | undefined {
+  const m = /^bearer\s+(\S+)\s*$/i.exec(request.headers.get('authorization') ?? '');
+  const key = m?.[1];
+  if (!key || !key.startsWith('tpuf_')) return undefined;
+  const sha = createHash('sha256').update(key).digest('hex');
+  const held = ctx.rowsRaw('_api_key').find((k) => k.key_sha256 === sha);
+  if (!held) return refuse(401, 'unauthorized: the API key is not valid');
+  if (held.expired_at) return refuse(401, 'unauthorized: the API key has expired');
+  const needs = NEEDS[operation];
+  const grants = Array.isArray(held.grants) ? (held.grants as string[]) : [];
+  if (needs && !needs.some((g) => grants.includes(g))) return refuse(403, `forbidden: this API key needs the ${needs.join(' or ')} permission`);
+  return undefined;
+}