@volter/twin-turbopuffer 1.0.0 → 1.0.1

package/dist/src/manifest.js

@@ -1,94 +1,33 @@
 export const manifest = {
-    vendor: 'turbopuffer',
-    service: 'turbopuffer',
-    body: {},
-    // the core mints no id (it owns no operation); a document's id is the caller's
-    ids: { template: '{prefix}_{n}' },
-    time: 'iso',
+    vendor: 'turbopuffer', service: 'turbopuffer', body: {}, ids: { template: '{uuid}' }, time: 'iso',
+    // source: https://turbopuffer.com/docs/auth "all endpoints will return a JSON payload in the format"
     error: { status: 'error', error: '{message}' },
-    readOnly: { status: 405, message: 'read_only: this twin was started read-only; writes are refused' },
-    malformedBody: { status: 400, message: 'invalid request: body is not valid JSON' },
-    notFound: { status: 404, message: 'not found' },
-    // an operation the twin does not serve, or a path turbopuffer does not have, in turbopuffer's error body
-    // (https://turbopuffer.com/docs/auth, "Error responses"). Where the documentation stops: no page prints the answer to
-    // an unknown path or an operation the twin does not model; 404 is the twin's.
-    gap: { status: 404, message: 'not found: {method} {path}' },
-    // a leading region segment (`/aws-us-east-1/v2/...`): how TURBOPUFFER_BASE_URL=<twin>/{region} reaches the twin
-    pathPrefix: '/(?:aws|gcp|azure)-[a-z0-9-]+(?=/v\\d+/)',
-    discovery: {
-        twinOf: 'the Turbopuffer API (v2 namespaces: write, query and multi-query, deleteAll, metadata, schema, namespace listing, cache warm hint)',
-        stores: 'namespaces (schema, distance metric) and their documents; queries filter, BM25-rank, order and count them deterministically',
-        identity: 'Send `Authorization: Bearer <any non-empty key>`, as the SDK does from TURBOPUFFER_API_KEY. A leading region path segment (/aws-us-east-1/v2/...) is accepted, which is how TURBOPUFFER_BASE_URL=<twin>/{region} reaches the twin.',
-    },
-    // the World's doors (./semantics/doors.ts)
-    doors: [
-        { id: 'setPassword', method: 'POST', path: '/_twin/users/{email}/password', note: "a person, their organization and its plan, as turbopuffer's sign-up makes them" },
-        { id: 'appCredentials', method: 'POST', path: '/_twin/app-credentials', note: 'the API key the World\'s application holds, as the runtime issues it at every boot' },
-    ],
-    // GET /v1/namespaces answers `{namespaces, next_cursor}`, paged by `cursor` and `page_size`
-    // (https://turbopuffer.com/docs/namespaces); the handler answers it. Required by the type; the core lists nothing.
-    list: { style: 'envelope', envelope: { namespaces: '{data}' }, limit: { param: 'page_size', default: 100, max: 1000 } },
+    readOnly: { status: 403, message: 'This World is read-only.' },
+    // source: https://raw.githubusercontent.com/turbopuffer/turbopuffer-typescript/v2.8.0/src/core/error.ts "export class NotFoundError extends APIError<404, Headers> {}"
+    // The documentation specifies the error envelope but no unknown-path message; use not found in that envelope.
+    notFound: { status: 404, message: 'not found' }, gap: { status: 404, message: 'not found' },
+    // source: https://turbopuffer.com/docs/auth "The HTTP API expects the API key to be formatted as a standard Bearer token and passed in the Authorization header:"
+    // Where documentation stops: Bearer authentication is documented, but missing-key versus unknown-route precedence is not; the gap stands.
+    auth: { header: 'authorization', scheme: 'Bearer', gateWhenAbsent: true,
+        // source: https://raw.githubusercontent.com/turbopuffer/turbopuffer-typescript/v2.8.0/src/core/error.ts "export class AuthenticationError extends APIError<401, Headers> {}"
+        // Exact missing/invalid-key messages are not published.
+        missing: { status: 401, message: 'API key required' }, invalidKeys: [], invalid: { status: 401, message: 'Invalid API key' } },
     deleted: {},
-    // turbopuffer's dashboard (https://turbopuffer.com/docs/auth: "You can create and expire tokens in the dashboard"):
-    // its sign-in, and the page where an organization's API keys are made and expired (screens/dashboard.tsx)
-    screens: [{
-            id: 'login', kind: 'flow', host: 'turbopuffer.com', path: '/login',
-            demand: 'every dashboard page asks who is signed in', status: 'done',
-            controls: ['Email', 'Password', 'Continue'], source: 'https://turbopuffer.com/docs/auth',
-        }, {
-            id: 'api-keys', kind: 'workspace', host: 'turbopuffer.com', path: '/dashboard/api-keys',
-            demand: 'every API key a customer uses is made here, and expired here when it is rotated or the customer leaves', status: 'done',
-            controls: ['Name', 'Read', 'Write', 'List', 'Admin', 'Create API key', 'Expire'], source: 'https://turbopuffer.com/docs/auth',
-        }, {
-            // every page of the dashboard's host, the sign-in and the keys pages above among them
-            id: 'dashboard', kind: 'workspace', host: 'turbopuffer.com', path: '/',
-            demand: 'an API key is made and expired only on the dashboard', status: 'done', source: 'https://turbopuffer.com/docs/auth',
-        }],
-    // a query writes nothing: a read-only World answers it
-    reads: ['post_v2_namespaces_namespace_query'],
-    resources: {
-        _seq_api_key: { idPrefix: '', ids: '{n}' },
-    },
-    // the descriptor, as data (twin-world's architecture, "The descriptor"): the pack registers packOf(manifest). No
-    // state system: a World's writes are not performed against turbopuffer, nor its namespaces observed (the gap).
+    resources: {},
+    unmodeled: ['get_v1_namespaces', 'post_v1_namespaces_namespace_debug_recall', 'get_v1_namespaces_namespace_hint_cache_warm', 'get_v1_namespaces_namespace_metadata', 'patch_v1_namespaces_namespace_metadata', 'get_v1_namespaces_namespace_operations_token', 'get_v1_namespaces_namespace_schema', 'post_v1_namespaces_namespace_schema', 'post_v2_namespaces_namespace', 'delete_v2_namespaces_namespace', 'post_v2_namespaces_namespace_explain_query', 'get_v2_namespaces_namespace_metadata', 'post_v2_namespaces_namespace_query'],
+    vendorBacked: { none: 'No vendor resource or operation is served; every spec operation answers the gap.' },
+    discovery: { twinOf: 'turbopuffer namespaces API', stores: 'No vendor resources', behavior: 'Every spec operation answers the vendor-shaped gap; Dub indexing is demand and remains unserved; reads require an off-by-default flag.' },
+    // source: https://raw.githubusercontent.com/turbopuffer/turbopuffer-typescript/v2.8.0/src/client.ts "baseURL = baseURL.replace('{region}', region);"
+    pathPrefix: '/(?:aws|gcp|azure)-[a-z0-9-]+(?=/v\\d+/)',
     descriptor: {
-        transport: 'rest',
-        protocol: '3',
-        archetype: 'crud',
-        bin: 'world-turbopuffer',
-        resources: ['namespace', 'document'],
-        specSource: 'the OpenAPI document @turbopuffer/turbopuffer@2.8.0 was generated from (spec/openapi.yaml.gz, provenance in spec/SOURCE.md), with its generator pseudo-paths folded into the operations turbopuffer documents (spec/patches.json); the calls dubinc/dub makes (apps/web/lib/api/partners/search/providers/turbopuffer.ts).',
-        description: 'Turbopuffer v2 namespaces twin — write (upsert/patch/delete rows or columns, delete/patch by filter, schema, distance_metric), query (filters, BM25 with last_as_prefix and Sum/Max/Product, attribute order, exact ANN, Count/Sum aggregates), multiQuery and deleteAll, as Dub\'s partner search calls them. Deterministic BM25 (textbook Okapi over a word_v2 approximation — not byte-equal to the vendor). Kernel-backed, no mirror; unmodelled surface answers 400/404 naming its todo.',
-        // ADOPTION — the official Node client (`@turbopuffer/turbopuffer`, the scope is Turbopuffer's
-        // alone), the official Python client (`turbopuffer` on PyPI), and the TURBOPUFFER_ env stem
-        // (TURBOPUFFER_API_KEY / _REGION / _BASE_URL, all read by the SDK in client.ts).
-        adoption: {
-            sdks: ['@turbopuffer/turbopuffer'],
-            pypi: ['turbopuffer'],
-            scopes: ['@turbopuffer/'],
-            envStems: ['TURBOPUFFER'],
-        },
-        // INTERCEPTION — the SDK's default base URL is `https://{region}.turbopuffer.com`
-        // (client.ts:273), the region filled from the `region` option or TURBOPUFFER_REGION: regional
-        // hosts such as aws-us-east-1.turbopuffer.com and gcp-us-central1.turbopuffer.com.
-        hosts: [{ hostPattern: '^(?:aws|gcp|azure)-[a-z0-9-]+\\.turbopuffer\\.com$' },
-            // the dashboard's sign-in and API keys pages and the World's sign-up door (screens/dashboard.tsx); the rest of
-            // turbopuffer.com (its site and docs) is left alone
-            { host: 'turbopuffer.com', pathPattern: '^/(login|dashboard|_twin/users)(/|$)' },
-        ],
-        // WORLD WIRING — under Node the SDK sends through undici's `Agent.request`
-        // (internal/custom/fetch-node.ts, selected by the package's `#fetch` import map for the `node`
-        // condition), which neither the injector's http/https/fetch patches nor HTTPS_PROXY reach. The
-        // SDK's own `TURBOPUFFER_BASE_URL` (client.ts:253) is the interception. It must carry the
-        // `{region}` placeholder: a client that passes `region` (Dub passes "aws-us-east-1") throws
-        // "region is set, but would be ignored" against a base URL without one (client.ts:282-285). The
-        // twin accepts and ignores that leading region segment.
-        // the application's TURBOPUFFER_API_KEY, issued once the twin is up (./semantics/doors.ts)
-        credentialDoor: { path: '/_twin/app-credentials', body: {}, fill: { TURBOPUFFER_API_KEY: 'api_key' } },
-        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.',
-        },
+        protocol: '3', transport: 'rest', archetype: 'crud', bin: 'world-turbopuffer', resources: [],
+        specSource: 'The OpenAPI document for @turbopuffer/turbopuffer@2.8.0 (spec/openapi.yaml.gz), with provenance and hash in spec/SOURCE.md.',
+        description: 'turbopuffer API twin: every spec operation answers the vendor-shaped gap.',
+        adoption: { sdks: ['@turbopuffer/turbopuffer'], pypi: ['turbopuffer'], scopes: ['@turbopuffer/'], envStems: ['TURBOPUFFER'] },
+        // source: https://raw.githubusercontent.com/turbopuffer/turbopuffer-typescript/v2.8.0/src/client.ts "https://{region}.turbopuffer.com"
+        hosts: [{ hostPattern: '^(?:aws|gcp|azure)-[a-z0-9-]+\\.turbopuffer\\.com$' }],
+        // source: https://raw.githubusercontent.com/turbopuffer/turbopuffer-typescript/v2.8.0/src/client.ts "TURBOPUFFER_BASE_URL"
+        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.' },
+        clientCasesNone: 'Demanded calls remain unserved; no SDK case is claimed for the retained gap.',
     },
 };

package/dist/src/semantics/index.js

@@ -1,6 +1 @@
-import * as namespaces from "./namespaces.js";
-export const turbopufferSemantics = {
-    delete_v2_namespaces_namespace: namespaces.delete_v2_namespaces_namespace,
-    post_v2_namespaces_namespace: namespaces.post_v2_namespaces_namespace,
-    post_v2_namespaces_namespace_query: namespaces.post_v2_namespaces_namespace_query,
-};
+export const turbopufferSemantics = {};

package/dist/src/semantics/states.d.ts

@@ -0,0 +1 @@
+export declare const states: {};

package/dist/src/semantics/states.js

@@ -0,0 +1,2 @@
+// No stored vendor resources are served, so there are no state machines or notState rulings.
+export const states = {};

package/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/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/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/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/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/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/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/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/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/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@volter/twin-turbopuffer",
-  "version": "1.0.0",
-  "description": "Local Turbopuffer twin: v2 namespaces (write upserts/patches/deletes by id or filter with schema and distance_metric; query with filters, deterministic BM25 incl. last_as_prefix, attribute order, exact ANN and Count/Sum aggregates; multiQuery; deleteAll; metadata; schema; namespace listing) served to the unmodified @turbopuffer/turbopuffer client. Built on @volter/world-core.",
+  "version": "1.0.1",
+  "description": "turbopuffer Protocol 3 twin: every spec operation answers the vendor-shaped gap; demanded calls remain unserved.",
   "author": "Volter (https://github.com/volter-ai)",
   "license": "Apache-2.0",
   "files": [
     "src",
+    "journeys",
     "spec",
     "README.md",
     "LICENSE",
@@ -30,13 +31,8 @@
   "bin": {
     "world-turbopuffer": "dist/src/cli.js"
   },
-  "dependencies": {
-    "@volter/world-ui": "^1.0.1",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7"
-  },
   "peerDependencies": {
-    "@volter/world-core": "^3.0.1"
+    "@volter/world-core": "^3.0.38"
   },
   "devDependencies": {
     "@types/bun": "^1.2.20",

package/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/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/src/fetch.ts

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

package/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/src/index.ts

@@ -1,10 +1,12 @@
-// @volter/twin-turbopuffer — the turbopuffer twin (Protocol 3). A fixed file: the descriptor is the manifest's.
-import { packOf, registerPack } from '@volter/world-core';
+// @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, type DerivedSurface } from '@volter/world-core';
 import { manifest } from './manifest.ts';
+import surface from './generated/surface.gen.json' with { type: 'json' };
 
 export { createTurbopufferFetch } from './fetch.ts';
 export { createTurbopufferTwinServer } from './server.ts';
 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 as unknown as DerivedSurface));