@volter/twin-turbopuffer 0.1.0

package/dist/src/turbopuffer-store.js

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