@volter/twin-turbopuffer 0.1.37 → 1.0.0

package/README.md

@@ -33,17 +33,13 @@ Grounded in the installed `@turbopuffer/turbopuffer@2.8.0` (`src/` paths below a
 | 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 headers | `Accept: application/json`, `Accept-Encoding: identity`, `User-Agent`, `X-Stainless-*` | `src/client.ts:858-864` |
 | 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` |
@@ -57,7 +53,7 @@ that use the fetch build (Bun, edge).
 
 ## Coverage
 
-Modelled (each has a `done` capability with a verify in `src/turbopuffer-capabilities.ts`):
+Modelled:
 
 - **write**: `upsert_rows`, `upsert_columns`, `patch_rows`, `patch_columns`, `deletes`,
   `delete_by_filter`, `patch_by_filter`, `schema`, `distance_metric`, `return_affected_ids`,
@@ -74,12 +70,13 @@ Modelled (each has a `done` capability with a verify in `src/turbopuffer-capabil
   `[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.
+- **namespaces**: deleteAll. A query on a namespace that does not exist answers 404. Listing, metadata, the schema
+  endpoints and the cache-warm hint are called by no application here ([journeys/demand.json](./journeys/demand.json))
+  and answer the gap.
+- **auth**: a missing or empty Bearer key is 401; a key the dashboard (or the World's credential door, which issues the
+  application's `TURBOPUFFER_API_KEY`) never made, or one it expired, is 401.
+- **no state system** (the gap): a World's writes are not performed against turbopuffer, and a real account's
+  namespaces are not observed.
 
 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
@@ -103,16 +100,13 @@ Also the twin's own choices, not grounded in the SDK: namespace names `[A-Za-z0-
 `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.
+comparisons order numbers before strings.
 
 ### 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,
+`branch_from_namespace` and their asynchronous operations, `encryption`, `sharding`, 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
@@ -120,10 +114,9 @@ the default `word_v4`, so `full_text_search: true` is refused), stemming, non-En
 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.
+The evidence recorded when the pack was built 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`.
 
 ### No UI mirror
 
@@ -135,11 +128,14 @@ happen there.
 
 | 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 |
+| `src/fetch.ts` | the region segment, the API key gate, the derived dispatch |
+| `src/server.ts` | the discovery door, the dashboard, the server |
+| `src/semantics/namespaces.ts` | the handlers, one per operation |
+| `src/semantics/shared.ts` | the namespaces from the tree, the error body, a write landed |
+| `src/engine/namespace.ts` | namespaces and documents; the pure write and query |
+| `src/engine/filter.ts` | the filter language |
+| `src/engine/text.ts`, `src/engine/stem.ts` | tokenizer, English stemming and BM25 |
+| `src/screens/api-keys.tsx` | the dashboard's sign-in and API keys |
+
+A World's writes are not performed against turbopuffer and its namespaces are not observed from it (no state system:
+the gap).

package/dist/generated/pack-facts.json

@@ -0,0 +1,57 @@
+{
+  "//": "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$"
+        },
+        {
+          "host": "turbopuffer.com",
+          "pathPattern": "^/(login|dashboard|_twin/users)(/|$)"
+        }
+      ],
+      "archetype": "crud",
+      "protocol": {
+        "declared": "3",
+        "major": 3,
+        "standing": "current"
+      },
+      "transport": "rest",
+      "resources": [
+        "namespace",
+        "document"
+      ],
+      "endpointEnv": {
+        "name": "TURBOPUFFER_TWIN_URL",
+        "templates": {
+          "TURBOPUFFER_BASE_URL": "${url}/{region}"
+        },
+        "note": "grounded in @turbopuffer/turbopuffer@2.8.0 src/client.ts:253-288 (TURBOPUFFER_BASE_URL, {region} placeholder substitution) and internal/custom/fetch-node.ts (undici Agent.request under node, outside the injector); the injector also claims the regional *.turbopuffer.com hosts for fetch-based runtimes."
+      },
+      "credentialDoor": {
+        "path": "/_twin/app-credentials",
+        "body": {},
+        "fill": {
+          "TURBOPUFFER_API_KEY": "api_key"
+        }
+      },
+      "serveExport": "createTurbopufferTwinServer"
+    }
+  },
+  "undeclared": []
+}

package/dist/spec/SOURCE.md

@@ -0,0 +1,59 @@
+# 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 11 operations. The twin routes by path and ignores the key.
+  **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** (each an `exampleDiffers` in `../journeys/vendor-examples.json`): the
+  metadata page's example answer names `approx_size_bytes`, `approx_num_rows` and `encryption: {"sse": true}`, where the
+  same page's Response section and this spec's `NamespaceMetadata` name `approx_logical_bytes`, `approx_row_count` and
+  `encryption.mode`; the delete page's example answers `"status": "ok"`, where this spec's delete answer is the constant
+  `"OK"`. The twin answers the spec. `remove_stopwords` defaults to `true` in this spec's description and to `false` on
+  the Write page ("Defaults to false (i.e. keep common words)") and in the January 2026 changelog; the twin answers the
+  page. The spec names an embedding's computed attribute `$embed_<attribute>`, the Write and Embedding pages
+  `embed_<attribute>`; the twin answers the pages.
+- **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).