@volter/twin-turbopuffer 1.0.0 → 1.0.1

package/README.md

@@ -1,141 +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-*` | `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` |
-| 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` |
-| 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:
-
-- **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**: 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
-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.
-
-### 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` 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
-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 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
-
-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/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).
+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

@@ -19,10 +19,6 @@
       "hosts": [
         {
           "hostPattern": "^(?:aws|gcp|azure)-[a-z0-9-]+\\.turbopuffer\\.com$"
-        },
-        {
-          "host": "turbopuffer.com",
-          "pathPattern": "^/(login|dashboard|_twin/users)(/|$)"
         }
       ],
       "archetype": "crud",
@@ -32,23 +28,13 @@
         "standing": "current"
       },
       "transport": "rest",
-      "resources": [
-        "namespace",
-        "document"
-      ],
+      "resources": [],
       "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"
-        }
+        "note": "The pinned SDK requires the region placeholder when a region is supplied; its Node socket client reads TURBOPUFFER_BASE_URL."
       },
       "serveExport": "createTurbopufferTwinServer"
     }

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

@@ -25,7 +25,7 @@
   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.
+  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/`.
@@ -42,14 +42,11 @@
   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.
+- **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

package/dist/spec/sources.json

@@ -1,4 +1,21 @@
 {
+  "https://raw.githubusercontent.com/turbopuffer/turbopuffer-typescript/v2.8.0/src/client.ts": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "baseURL = baseURL.replace('{region}', region);": true,
+      "https://{region}.turbopuffer.com": true,
+      "TURBOPUFFER_BASE_URL": true
+    }
+  },
+  "https://raw.githubusercontent.com/turbopuffer/turbopuffer-typescript/v2.8.0/src/core/error.ts": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "export class NotFoundError extends APIError<404, Headers> {}": true,
+      "export class AuthenticationError extends APIError<401, Headers> {}": true
+    }
+  },
   "https://raw.githubusercontent.com/turbopuffer/turbopuffer-typescript/v2.8.0/src/resources/namespaces.ts": {
     "status": 200,
     "checked": "2026-09-27"
@@ -11,6 +28,14 @@
       "The server returns `202 Accepted` with a `Location` header pointing to the operation.": true
     }
   },
+  "https://turbopuffer.com/docs/auth": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "all endpoints will return a JSON payload in the format": true,
+      "The HTTP API expects the API key to be formatted as a standard Bearer token and passed in the Authorization header:": true
+    }
+  },
   "https://turbopuffer.com/docs/branching.md": {
     "status": 200,
     "checked": "2026-09-27",

package/dist/src/fetch.js

@@ -3,17 +3,11 @@
 import { createPackFetch } from '@volter/world-core';
 import surface from './generated/surface.gen.json' with { type: 'json' };
 import { manifest } from "./manifest.js";
-import { around } from "./semantics/around.js";
-import * as doors from "./semantics/doors.js";
 import { turbopufferSemantics } from "./semantics/index.js";
-import { screen as screen_dashboard } from "./screens/dashboard.js";
 export function createTurbopufferFetch(options = {}) {
     return createPackFetch({
         manifest,
         surface: surface,
         handlers: turbopufferSemantics,
-        doors,
-        around,
-        screens: { "dashboard": screen_dashboard },
     }, options);
 }

package/dist/src/generated/ui.gen.json

@@ -1 +1 @@
-{"generatedBy":"scripts/derive-pack.ts","resources":{"_seq_api_key":{"actions":[],"states":{},"embeds":{}}}}
+{"generatedBy":"scripts/derive-pack.ts","resources":{}}

package/dist/src/index.js

@@ -1,8 +1,10 @@
-// @volter/twin-turbopuffer — the turbopuffer twin (Protocol 3). A fixed file: the descriptor is the manifest's.
+// @volter/twin-turbopuffer — the turbopuffer twin (Protocol 3). A fixed file (create-pack): the descriptor is the manifest's, and the
+// kernel derives the vendor-backed half from the generated surface, unless the manifest declares none (vendorBacked.none;
+// architecture, "The real-system adapters").
 import { packOf, registerPack } from '@volter/world-core';
 import { manifest } from "./manifest.js";
+import surface from './generated/surface.gen.json' with { type: 'json' };
 export { createTurbopufferFetch } from "./fetch.js";
 export { createTurbopufferTwinServer } from "./server.js";
 export { manifest };
-// The descriptor: twin-world's architecture, "The descriptor"; declared in manifest.ts.
-export const pack = registerPack(packOf(manifest));
+export const pack = registerPack(packOf(manifest, surface));