@volter/twin-turbopuffer 0.1.37 → 1.0.1

package/README.md

@@ -1,145 +1,14 @@
 # @volter/twin-turbopuffer
 
-A local, stateful twin of the [Turbopuffer](https://turbopuffer.com) API (v2 namespaces), built on
-`@volter/world-core`. The unmodified `@turbopuffer/turbopuffer` client writes documents into it and
-queries them back: filters, BM25 full-text ranking, attribute ordering, exact vector distance and
-counts are computed from the stored documents, deterministically.
-
-The motivating consumer is Dub's partner search (`apps/web/lib/api/partners/search/providers/
-turbopuffer.ts`): its sync jobs `write` `upsert_rows` with a declared schema and `deletes`, its
-search runs a `multiQuery` of BM25 branches with `last_as_prefix`, `ContainsAllTokens` and program /
-group / tag filters, its count runs `aggregate_by: { total: ['Count'] }`, and its maintenance script
-calls `deleteAll`.
-
-## Pointing a client at it
-
-```sh
-world-turbopuffer serve --port 8787 --root ./state
-TURBOPUFFER_API_KEY=anything TURBOPUFFER_BASE_URL='http://127.0.0.1:8787/{region}' node app.js
-```
-
-In a World, `volter-world init` wires this for you: the service exports `TURBOPUFFER_TWIN_URL` and
-`TURBOPUFFER_BASE_URL=${url}/{region}`. The `{region}` placeholder is required: the SDK throws
-"region is set, but would be ignored" when a caller passes `region` (Dub passes `aws-us-east-1`)
-and the base URL has no placeholder. The twin accepts and ignores the leading region segment.
-
-## Grounded wire
-
-Grounded in the installed `@turbopuffer/turbopuffer@2.8.0` (`src/` paths below are that package's).
-
-| Fact | Value | Source |
-|---|---|---|
-| Default host | `https://{region}.turbopuffer.com`, e.g. `aws-us-east-1.turbopuffer.com` | `src/client.ts:273` |
-| Region | `region` option or `TURBOPUFFER_REGION`; required when the URL has `{region}` | `src/client.ts:255`, `274-286` |
-| Base URL override | `TURBOPUFFER_BASE_URL` (or `baseURL`); `{region}` is substituted into it | `src/client.ts:253`, `281` |
-| Auth | `Authorization: Bearer <apiKey>` (`TURBOPUFFER_API_KEY`) | `src/client.ts:254`, `383` |
-| Request headers | `Accept: application/json`, `Accept-Encoding: identity`, `User-Agent`, `X-Stainless-*`, `Prefer: respond-async` | `src/client.ts:858-864`, `src/internal/custom/respond-async.ts` |
-| Request body | JSON; gzip only with `compression: true` (default false) | `src/client.ts:299`, `812` |
-| Node transport | undici `Agent.request`, selected by the `#fetch` import map for the `node` condition | `package.json` `imports`, `src/internal/custom/fetch-node.ts` |
-| List namespaces | `GET /v1/namespaces?prefix&page_size&cursor` → `{ namespaces: [{id}], next_cursor }` | `src/client.ts:368`, `src/core/pagination.ts:123` |
-| Write | `POST /v2/namespaces/{ns}` | `src/resources/namespaces.ts:174` |
-| deleteAll | `DELETE /v2/namespaces/{ns}` → `{ status: 'OK' }` | `namespaces.ts:46`, `1100` |
-| Query | `POST /v2/namespaces/{ns}/query` | `namespaces.ts:104` |
-| multiQuery | `POST /v2/namespaces/{ns}/query?stainless_overload=multiQuery` with `{ queries }` | `namespaces.ts:90` |
-| Metadata | `GET /v2/namespaces/{ns}/metadata` | `namespaces.ts:79` |
-| Schema | `GET` / `POST /v1/namespaces/{ns}/schema` | `namespaces.ts:126`, `163` |
-| Cache warm | `GET /v1/namespaces/{ns}/hint_cache_warm` | `namespaces.ts:68` |
-| Write response | `{ status: 'OK', message, rows_affected, rows_upserted?, rows_patched?, rows_deleted?, *_ids?, billing }` | `namespaces.ts:1231-1294` |
-| Query response | `{ rows?, aggregations?, billing, performance }`; a row is `{ id, $dist?, ...attributes }` | `namespaces.ts:850-868`, `1159-1175` |
-| FTS defaults | tokenizer `word_v4`, `k1` 1.2, `b` 0.75, case-insensitive, stopwords kept (`remove_stopwords` false since January 2026), no stemming, `max_token_length` 39 | `namespaces.ts:474-526` |
-| Filterable default | full-text attributes are not filterable unless `filterable: true` | `namespaces.ts:249-253` |
-| Errors | status → `BadRequestError` 400, `AuthenticationError` 401, `NotFoundError` 404, … | `src/core/error.ts` |
-
-Under Node the SDK sends through undici's `Agent.request`, which neither the injector's
-http/https/fetch patches nor `HTTPS_PROXY` reach, so `TURBOPUFFER_BASE_URL` is the interception.
-The descriptor also claims the regional hosts (`^(aws|gcp|azure)-….turbopuffer.com$`) for runtimes
-that use the fetch build (Bun, edge).
-
-## Coverage
-
-Modelled (each has a `done` capability with a verify in `src/turbopuffer-capabilities.ts`):
-
-- **write**: `upsert_rows`, `upsert_columns`, `patch_rows`, `patch_columns`, `deletes`,
-  `delete_by_filter`, `patch_by_filter`, `schema`, `distance_metric`, `return_affected_ids`,
-  `disable_backpressure` (accepted; the twin has no backpressure). One write request is one kernel
-  action. Extrapolated, not in the SDK: the twin applies it in the order filtered deletes →
-  filtered patches → upserts → patches → deletes.
-  Upserts replace the whole document; patches merge and never create; a `null` value removes the
-  attribute. Attribute types are declared or inferred on first write (`string`, `int`, `float`,
-  `bool`, `[]string`, …) and a mismatched value or type change is refused with 400.
-- **query**: `filters` (Eq, NotEq, In, NotIn, Contains, NotContains, ContainsAny, NotContainsAny,
-  Lt/Lte/Gt/Gte, AnyLt/AnyLte/AnyGt/AnyGte, Glob/NotGlob/IGlob/NotIGlob, ContainsAllTokens,
-  ContainsAnyToken with `last_as_prefix`, And/Or/Not); `rank_by` BM25 (with `last_as_prefix`,
-  `Sum`, `Max`, `Product`), attribute order (`[attr, asc|desc]` and lists of them), and
-  `[vector, ANN|kNN, q]` with exact `cosine_distance` / `euclidean_squared`; `top_k` / `limit`
-  (default 10); `include_attributes` / `exclude_attributes`; `aggregate_by` Count, Count(attr),
-  Sum(attr); `consistency` (the twin is always strongly consistent); `multiQuery`.
-- **namespaces**: list (prefix, cursor paging), metadata, schema read and update, cache-warm hint,
-  deleteAll. A query, metadata or schema read on a namespace that does not exist answers 404.
-- **auth**: a missing or empty Bearer key is 401; `--token` makes the twin demand one exact key.
-- **real state system**: `performTurbopufferAction` replays a recorded write / deleteAll / schema
-  update against the vendor; `syncTurbopufferFromRemote` observes namespaces, schema and documents
-  (paged by id) from a real account.
-
-Semantics a caller depends on: an attribute a document does not carry reads as null, so `NotIn`,
-`NotEq` and `NotContainsAny` match it (Dub omits `groupId`/`country` for exactly this). A
-comparison filter on a non-filterable attribute is refused with 400; the token filters require
-`full_text_search` on the attribute.
-
-### Deterministic, not byte-equal
-
-Scores and tokens are deterministic but are not Turbopuffer's exact numbers. `word_v2` is modelled
-as maximal runs of Unicode letters, digits, marks and `_` (so a URL splits into its components, as
-Dub measured); English stopwords are the 33-word Lucene list; BM25 is textbook Okapi with the
-Lucene IDF `ln(1 + (N − n + 0.5)/(n + 0.5))` over the namespace's documents carrying the attribute;
-a `last_as_prefix` final token contributes a constant 1 per matching document (Dub observed that a
-single-token prefix query scores every match exactly 1). Ties order by id ascending. Error message
-strings and the `{ status: 'error', error }` body are the twin's own reading (this build had no
-account to probe); the SDK surfaces that body verbatim as `APIError.error`, and the statuses map to
-the SDK's error classes. `billing` and `performance` are deterministic (logical bytes from the stored JSON,
-zero timings, a "hot" cache).
-
-Also the twin's own choices, not grounded in the SDK: namespace names `[A-Za-z0-9-_.]{1,128}`;
-`page_size` at most 1000; `deletes` counts every requested id in `rows_deleted`; an undeclared
-integer attribute is inferred as `int`; an attribute a row lacks projects as `null` when named in
-`include_attributes`; a token filter whose every token is dropped (stopwords) matches nothing; id
-comparisons order numbers before strings. A namespace refreshed from a real account whose
-full-text config the twin does not model (the default `word_v4`, stemming, another language) is
-stored, but BM25 and token filters on it are refused with a 400 naming the gap.
-
-### Planned (todo)
-
-Refused with a 400 or 404 naming the gap, never answered with a fabricated success: conditional
-writes (`upsert_condition` / `patch_condition` / `delete_condition`), `copy_from_namespace`,
-`branch_from_namespace`, `encryption`, `sharding`, `respond-async` polling (the twin answers
-synchronously, which the SDK accepts), write backpressure, metadata PATCH (pinning), explain_query,
-recall, `group_by`, `compute_attributes`, `aggregate_by` together with `rank_by`, `limit.per`,
-`rerank_by`, rank expressions beyond BM25/Sum/Max/Product, highlights, Regex / Fuzzy /
-ContainsTokenSequence filters, tokenizers other than `word_v2` and `pre_tokenized_array` (including
-the default `word_v4`, so `full_text_search: true` is refused), stemming, non-English languages,
-byte-equal BM25 scores, base64 vectors, named / multi / sparse vectors, server-side embedding, the
-v1 namespace API older SDKs call, and the vendor's literal error strings.
-
-The capability verifies were written but not run in the build that added this pack; the evidence
-recorded there was the real `@turbopuffer/turbopuffer@2.8.0` client, constructed as Dub constructs
-it, performing Dub's write → multiQuery → count → delete → deleteAll sequence against a served twin
-through `TURBOPUFFER_BASE_URL`. The census `baseline` stays 0 until the catalog gate measures it.
-
-### No UI mirror
-
-Turbopuffer is used from code: an application writes and queries namespaces through the SDK. The
-turbopuffer.com dashboard manages API keys, billing and namespace inspection; the work does not
-happen there.
-
-## Layout
-
-| File | Role |
-|---|---|
-| `src/turbopuffer-twin.ts` | routing, auth, the error envelope, kernel reads and writes |
-| `src/turbopuffer-store.ts` | namespaces and documents as tree subjects; pure write and query |
-| `src/turbopuffer-filter.ts` | the filter language |
-| `src/turbopuffer-text.ts` | tokenizer and BM25 |
-| `src/turbopuffer-server.ts` | the fetch adapter and server |
-| `src/turbopuffer-connector.ts` | perform and refresh adapters |
-| `src/turbopuffer-capabilities.ts` | the capability manifest |
-| `src/turbopuffer-conformance.ts` | endpoint probes and router census |
+Protocol 3 twin of turbopuffer's API. Nothing is served: every spec operation
+answers the vendor-shaped JSON gap (`404`, `{"status":"error","error":"not found"}`).
+The [API overview](https://turbopuffer.com/docs/auth) documents this error envelope;
+the pinned SDK maps 404 to `NotFoundError`. The vendor does not publish the exact
+unknown-path message, so the pack uses `not found` in that envelope.
+No vendor resource, namespace engine, screen, credential door or refresh is served.
+
+Dub partner search requires an operator-supplied `TURBOPUFFER_API_KEY`; reads also
+need `PARTNER_SEARCH_READ_ENABLED=true`. Both ship empty. The pinned settings are
+recorded under `optional` in `journeys/demand.json`, and the life has no acts.
+Published examples remain in `spec/doc-examples.json` and count as unserved.
+`spec/SOURCE.md` preserves the vendor's document, its hash and path corrections.

package/dist/generated/pack-facts.json

@@ -0,0 +1,43 @@
+{
+  "//": "GENERATED by scripts/pack-facts.ts — current pack descriptors and explicit world-runtime server backings; no prior-artifact entries are retained.",
+  "packs": {
+    "turbopuffer": {
+      "adoption": {
+        "sdks": [
+          "@turbopuffer/turbopuffer"
+        ],
+        "pypi": [
+          "turbopuffer"
+        ],
+        "scopes": [
+          "@turbopuffer/"
+        ],
+        "envStems": [
+          "TURBOPUFFER"
+        ]
+      },
+      "hosts": [
+        {
+          "hostPattern": "^(?:aws|gcp|azure)-[a-z0-9-]+\\.turbopuffer\\.com$"
+        }
+      ],
+      "archetype": "crud",
+      "protocol": {
+        "declared": "3",
+        "major": 3,
+        "standing": "current"
+      },
+      "transport": "rest",
+      "resources": [],
+      "endpointEnv": {
+        "name": "TURBOPUFFER_TWIN_URL",
+        "templates": {
+          "TURBOPUFFER_BASE_URL": "${url}/{region}"
+        },
+        "note": "The pinned SDK requires the region placeholder when a region is supplied; its Node socket client reads TURBOPUFFER_BASE_URL."
+      },
+      "serveExport": "createTurbopufferTwinServer"
+    }
+  },
+  "undeclared": []
+}

package/dist/journeys/coverage.json

@@ -0,0 +1,60 @@
+{
+  "vendor": "turbopuffer",
+  "missing": 0,
+  "stale": [],
+  "code": {
+    "lines": 46,
+    "run": 44,
+    "recorded": 2,
+    "missing": 0
+  },
+  "state": {
+    "declared": 0,
+    "reached": 0,
+    "recorded": 0,
+    "missing": [],
+    "undeclared": []
+  },
+  "files": [
+    {
+      "file": "semantics/index.ts",
+      "lines": {
+        "found": 2,
+        "hit": 2
+      },
+      "missing": []
+    },
+    {
+      "file": "manifest.ts",
+      "lines": {
+        "found": 23,
+        "hit": 23
+      },
+      "missing": []
+    },
+    {
+      "file": "index.ts",
+      "lines": {
+        "found": 7,
+        "hit": 7
+      },
+      "missing": []
+    },
+    {
+      "file": "server.ts",
+      "lines": {
+        "found": 4,
+        "hit": 2
+      },
+      "missing": []
+    },
+    {
+      "file": "fetch.ts",
+      "lines": {
+        "found": 10,
+        "hit": 10
+      },
+      "missing": []
+    }
+  ]
+}

package/dist/journeys/customer-life.json

@@ -0,0 +1,7 @@
+{
+  "vendor": "turbopuffer",
+  "host": "aws-us-east-1.turbopuffer.com",
+  "author": "Codex pack builder",
+  "about": "Demanded calls are recorded in demand.json and remain unserved in the retained gap. Scope is unchanged pending a separate implementation; supplying credentials is not opt-in.",
+  "steps": []
+}

package/dist/journeys/customer-life.outline.md

@@ -0,0 +1,13 @@
+# turbopuffer customer life
+
+Author: Codex pack builder.
+
+Demanded calls are recorded in demand.json and remain unserved in the retained gap. Scope is unchanged pending a separate implementation; supplying credentials is not opt-in.
+
+Dub at `7e0101363b2ab30afc537c1893f159d1dcba513a` checks the key in
+`apps/web/lib/api/partners/search/provider.ts:13` and the read flag at line 34.
+The key authenticates demanded indexing; `PARTNER_SEARCH_READ_ENABLED` is the separate default-off read choice in `apps/web/.env.example:32`.
+
+The retained gap has no modeled customer acts, credentials, screens or stored state; demand.json records the unserved demand.
+Every spec operation answers the vendor-shaped gap. Published examples stay
+in the spec and are counted as unserved; the life has no steps.

package/dist/journeys/decisions.json

@@ -0,0 +1,83 @@
+{
+  "about": "Demanded calls are recorded in demand.json and remain unserved in the retained gap. Scope is unchanged pending a separate implementation; supplying credentials is not opt-in.",
+  "decisions": [
+    {
+      "operation": "get_v1_namespaces",
+      "demand": "None; Dub integration is opt-in.",
+      "mechanism": "unmodeled",
+      "why": "Demanded calls are recorded in demand.json and remain unserved in the retained gap. Scope is unchanged pending a separate implementation; supplying credentials is not opt-in."
+    },
+    {
+      "operation": "post_v1_namespaces_namespace_debug_recall",
+      "demand": "None; Dub integration is opt-in.",
+      "mechanism": "unmodeled",
+      "why": "Demanded calls are recorded in demand.json and remain unserved in the retained gap. Scope is unchanged pending a separate implementation; supplying credentials is not opt-in."
+    },
+    {
+      "operation": "get_v1_namespaces_namespace_hint_cache_warm",
+      "demand": "None; Dub integration is opt-in.",
+      "mechanism": "unmodeled",
+      "why": "Demanded calls are recorded in demand.json and remain unserved in the retained gap. Scope is unchanged pending a separate implementation; supplying credentials is not opt-in."
+    },
+    {
+      "operation": "get_v1_namespaces_namespace_metadata",
+      "demand": "None; Dub integration is opt-in.",
+      "mechanism": "unmodeled",
+      "why": "Demanded calls are recorded in demand.json and remain unserved in the retained gap. Scope is unchanged pending a separate implementation; supplying credentials is not opt-in."
+    },
+    {
+      "operation": "patch_v1_namespaces_namespace_metadata",
+      "demand": "None; Dub integration is opt-in.",
+      "mechanism": "unmodeled",
+      "why": "Demanded calls are recorded in demand.json and remain unserved in the retained gap. Scope is unchanged pending a separate implementation; supplying credentials is not opt-in."
+    },
+    {
+      "operation": "get_v1_namespaces_namespace_operations_token",
+      "demand": "None; Dub integration is opt-in.",
+      "mechanism": "unmodeled",
+      "why": "Demanded calls are recorded in demand.json and remain unserved in the retained gap. Scope is unchanged pending a separate implementation; supplying credentials is not opt-in."
+    },
+    {
+      "operation": "get_v1_namespaces_namespace_schema",
+      "demand": "None; Dub integration is opt-in.",
+      "mechanism": "unmodeled",
+      "why": "Demanded calls are recorded in demand.json and remain unserved in the retained gap. Scope is unchanged pending a separate implementation; supplying credentials is not opt-in."
+    },
+    {
+      "operation": "post_v1_namespaces_namespace_schema",
+      "demand": "None; Dub integration is opt-in.",
+      "mechanism": "unmodeled",
+      "why": "Demanded calls are recorded in demand.json and remain unserved in the retained gap. Scope is unchanged pending a separate implementation; supplying credentials is not opt-in."
+    },
+    {
+      "operation": "post_v2_namespaces_namespace",
+      "demand": "Shipped application call: apps/web/lib/api/partners/search/providers/turbopuffer.ts:405,416",
+      "mechanism": "unmodeled",
+      "why": "Demanded calls are recorded in demand.json and remain unserved in the retained gap. Scope is unchanged pending a separate implementation; supplying credentials is not opt-in."
+    },
+    {
+      "operation": "delete_v2_namespaces_namespace",
+      "demand": "None; Dub integration is opt-in.",
+      "mechanism": "unmodeled",
+      "why": "Demanded calls are recorded in demand.json and remain unserved in the retained gap. Scope is unchanged pending a separate implementation; supplying credentials is not opt-in."
+    },
+    {
+      "operation": "post_v2_namespaces_namespace_explain_query",
+      "demand": "None; Dub integration is opt-in.",
+      "mechanism": "unmodeled",
+      "why": "Demanded calls are recorded in demand.json and remain unserved in the retained gap. Scope is unchanged pending a separate implementation; supplying credentials is not opt-in."
+    },
+    {
+      "operation": "get_v2_namespaces_namespace_metadata",
+      "demand": "None; Dub integration is opt-in.",
+      "mechanism": "unmodeled",
+      "why": "Demanded calls are recorded in demand.json and remain unserved in the retained gap. Scope is unchanged pending a separate implementation; supplying credentials is not opt-in."
+    },
+    {
+      "operation": "post_v2_namespaces_namespace_query",
+      "demand": "None; Dub integration is opt-in.",
+      "mechanism": "unmodeled",
+      "why": "Demanded calls are recorded in demand.json and remain unserved in the retained gap. Scope is unchanged pending a separate implementation; supplying credentials is not opt-in."
+    }
+  ]
+}

package/dist/journeys/demand.json

@@ -0,0 +1,27 @@
+{
+  "measured": "Application calls and optional settings are recorded below at the cited commits.",
+  "applications": [
+    {
+      "name": "dubinc/dub",
+      "client": "partner search indexing and reads",
+      "backend": [
+        {
+          "call": "namespace.write: index upserts and deletes",
+          "operation": "post_v2_namespaces_namespace",
+          "evidence": "apps/web/lib/api/partners/search/providers/turbopuffer.ts:405,416"
+        }
+      ],
+      "commit": "7e0101363b2a",
+      "gate": "Shipped indexing/sync jobs use the write provider once its credential is supplied; PARTNER_SEARCH_READ_ENABLED controls only reads, not indexing (apps/web/lib/api/partners/search/provider.ts:9-19,22-38; apps/web/lib/api/partners/search/sync.ts:36,98).",
+      "evidence": "apps/web/lib/api/partners/search/provider.ts:13,34"
+    }
+  ],
+  "optional": [
+    {
+      "application": "dubinc/dub",
+      "what": "Index reads for partner search, separately from demanded indexing writes",
+      "setting": "Configuration (1): PARTNER_SEARCH_READ_ENABLED=true replaces false; read provider is separate from write provider (apps/web/lib/api/partners/search/provider.ts:22-38; apps/web/.env.example:32).",
+      "evidence": "apps/web/lib/api/partners/search/provider.ts:34"
+    }
+  ]
+}

package/dist/journeys/score.json

@@ -0,0 +1,82 @@
+{
+  "vendor": "turbopuffer",
+  "life": {
+    "steps": 0,
+    "verdict": "unjudged",
+    "judge": null,
+    "authors": []
+  },
+  "failures": [],
+  "flags": [],
+  "coverage": {
+    "vendor": "turbopuffer",
+    "missing": 0,
+    "stale": [],
+    "code": {
+      "lines": 46,
+      "run": 44,
+      "recorded": 2,
+      "missing": 0
+    },
+    "state": {
+      "declared": 0,
+      "reached": 0,
+      "recorded": 0,
+      "missing": [],
+      "undeclared": []
+    },
+    "files": [
+      {
+        "file": "semantics/index.ts",
+        "lines": {
+          "found": 2,
+          "hit": 2
+        },
+        "missing": []
+      },
+      {
+        "file": "manifest.ts",
+        "lines": {
+          "found": 23,
+          "hit": 23
+        },
+        "missing": []
+      },
+      {
+        "file": "index.ts",
+        "lines": {
+          "found": 7,
+          "hit": 7
+        },
+        "missing": []
+      },
+      {
+        "file": "server.ts",
+        "lines": {
+          "found": 4,
+          "hit": 2
+        },
+        "missing": []
+      },
+      {
+        "file": "fetch.ts",
+        "lines": {
+          "found": 10,
+          "hit": 10
+        },
+        "missing": []
+      }
+    ]
+  },
+  "examples": {
+    "done": false,
+    "replayed": true,
+    "verdict": "unjudged",
+    "failures": [],
+    "line": "examples: 99 published, 0 of patch-removed operations, 99 of operations the twin does not serve, 0 replayed, 0 recorded; 0 failing   done: no"
+  },
+  "breadth": {
+    "operations": 13,
+    "gap": 13
+  }
+}

package/dist/journeys/unreachable.json

@@ -0,0 +1,12 @@
+{
+  "code": [
+    {
+      "file": "server.ts",
+      "declarations": [
+        "createTurbopufferTwinServer"
+      ],
+      "world": "host-process",
+      "why": "The journeys use the pack fetch in process; the server factory binds the external HTTP host, outside an in-process World walk."
+    }
+  ]
+}

package/dist/journeys/vendor-examples.json

@@ -0,0 +1,7 @@
+{
+  "vendor": "turbopuffer",
+  "host": "aws-us-east-1.turbopuffer.com",
+  "author": "Codex pack builder",
+  "about": "No demanded application calls turbopuffer; Dub partner search requires an operator-supplied TURBOPUFFER_API_KEY, and reads also require PARTNER_SEARCH_READ_ENABLED=true. Both ship empty. Published examples are retained and counted as unserved.",
+  "steps": []
+}

package/dist/spec/SOURCE.md

@@ -0,0 +1,56 @@
+# turbopuffer spec — provenance
+
+- **File:** `openapi.yaml.gz`, gzip of the OpenAPI document turbopuffer's official TypeScript client was generated
+  from, the vendor's bytes unchanged inside (OpenAPI 3.1.0, `info.version` `0.0.1`).
+- **Upstream:** the client's `.stats.yml` at tag `v2.8.0`
+  (https://github.com/turbopuffer/turbopuffer-typescript/blob/v2.8.0/.stats.yml; 2.8.0 is the version dubinc/dub pins)
+  names `openapi_spec_url`
+  https://storage.googleapis.com/stainless-sdk-openapi-specs/turbopuffer-benesch/turbopuffer-e18ebc6e8f59aa35045717e326162e1e56ac3f344771f4149e17e1104f7b1c06.yml,
+  `openapi_spec_hash` `3db106e23d2536c8a73917ebb6047b19` (the MD5 of these bytes) and 14 configured endpoints. Fetched
+  2026-09-27.
+- **Also published:** turbopuffer's API overview names a public specification, https://github.com/turbopuffer/turbopuffer-openapi
+  (https://turbopuffer.com/docs/auth, "Specification"). Its `openapi.yml` at commit `155e59adbecaa92b00a9c66edfad419cf0fe5c17`
+  (2026-08-04), whose `.stats.yml` names the same spec hash, parses to the same document as this file (it differs
+  only in YAML formatting). That repository's head has moved on (16 endpoints, adding the asynchronous copy's start and
+  poll); the file vendored here is the one the pinned client speaks.
+- **SHA-256 of the uncompressed document:** `245e887f04ab7c111d8ab8b0812a631a0f04f4a7804f2f04c6601d90d090a27b`.
+- **Operation ids:** the document names none, so each operation's id is the reader's `method_path` slug
+  (`post_v2_namespaces_namespace` is the write, `post_v2_namespaces_namespace_query` the query).
+- **Corrections:** `patches.json` (RFC 6902, each with its reason and evidence), applied before the IR. The document
+  writes three pseudo-paths, `/v2/namespaces/{namespace}?stainless_overload=branchFrom`, `...?stainless_overload=copyFrom`
+  and `/v2/namespaces/{namespace}/query?stainless_overload=multiQuery`: its generator's way of giving one path and
+  method a second client method. The client sends that query key (`src/resources/namespaces.ts` at v2.8.0), but
+  turbopuffer's documentation names no such parameter: it branches and copies with `branch_from_namespace` and
+  `copy_from_namespace` in the body of `POST /v2/namespaces/:namespace` (https://turbopuffer.com/docs/write,
+  https://turbopuffer.com/docs/branching) and posts a multi-query's `queries` to the plain query path
+  (https://turbopuffer.com/docs/query). The patches fold each pseudo-path into that operation (the write body already
+  has both fields; the copy's `dest_encryption` moves into `CopyFromNamespaceConfig`; the query takes either body and
+  answers `QueryResult` or `MultiQueryResult`), leaving 13 operations. The derived routes retain the documented paths; all operations are unmodeled.
+  **Inference, not observation:** that turbopuffer's own server ignores `stainless_overload` is read from the
+  documentation, which never mentions it; no request to the real service was made.
+- **Read by:** `bun scripts/derive-pack.ts turbopuffer`, which writes `../src/generated/`.
+- **Pages cited:** the documentation's curl examples are rendered in the HTML pages' script payload, not their text;
+  the `.md` form of a page (https://turbopuffer.com/docs/query.md, listed in https://turbopuffer.com/llms.txt) is cited
+  where a quote comes from one.
+- **The pages' examples** (`doc-examples.json`, 99): every example turbopuffer's documentation publishes for an
+  operation of this spec, from the API reference (Overview, Write, Query, Namespace metadata, Warm cache, List namespaces,
+  Delete namespace, Recall) and the guides (Quickstart, Full-Text Search, Branching, Embedding, Permissions, Ingestion,
+  Regions, Testing, Export, Backups, Pinning), read from each page's `.md` form (https://turbopuffer.com/llms.txt lists
+  them). An example is one request: a page's multi-language block shows one request in each client language, so it
+  counts once, by its curl form where it has one and otherwise by the request the page's client code sends (the
+  Embedding page's TypeScript, the Backups, Export, Testing, Pagination and custom-tokenization Python). The Chunking
+  page's example calls no turbopuffer operation, and the Quickstart's Connect block only sets shell variables; neither is
+  counted. The examples of Pinning (`PATCH /v1/namespaces/{namespace}/metadata`) and Recall are counted and not
+  replayed: the twin does not serve those operations.
+- **Where the pages and this spec disagree:** the metadata page's example names `approx_size_bytes`,
+  `approx_num_rows` and `encryption.sse`, while its Response section and the spec name `approx_logical_bytes`,
+  `approx_row_count` and `encryption.mode`. The delete page shows `status: ok`, while the spec answers `OK`.
+  The spec defaults `remove_stopwords` to true and names `$embed_<attribute>`; the Write page defaults it to false
+  and names `embed_<attribute>`. No operation is served, so these examples remain unserved rather than replayed.
+- **APIs the pages document and this spec omits, outside the count until modelled:** the asynchronous form of a copy
+  (`Prefer: respond-async`, answered 202 with a `Location` to poll, https://turbopuffer.com/docs/auth "Asynchronous
+  requests"), and the export read `GET /v1/namespaces/{namespace}` and `HEAD /v1/namespaces/{namespace}`, which the
+  document's own header says it leaves out (deprecated in favour of paging queries and the schema).
+- **Outside any API:** API keys are made and expired on turbopuffer's dashboard ("You can create and expire tokens in
+  the dashboard", https://turbopuffer.com/docs/auth); its audit log names the two acts (`api-key-created`,
+  `api-key-marked-as-expired`, https://turbopuffer.com/docs/audit-logs).