@volter/twin-turbopuffer 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,145 @@
+# @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 |

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-turbopuffer CLI: serve the KERNEL-BACKED Turbopuffer twin, or run conformance. State lives
+// in the @volter/world-core log under --root. Conformance is dev-only + lazy-imported.
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createTurbopufferTwinServer } from "./turbopuffer-server.js";
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', String(process.env.PORT ?? '0'))) || undefined;
+const root = optionValue(rest, '--root') || process.env.VOLTER_STATE_DIR || undefined;
+const token = optionValue(rest, '--token') || undefined;
+const readOnly = hasFlag(rest, '--read-only');
+if (cmd === 'serve' || cmd === undefined) {
+    const s = await createTurbopufferTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(token ? { token } : {}) });
+    process.stdout.write(`turbopuffer twin (v2 namespaces: write, query, multiQuery, deleteAll, metadata, schema)${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${s.port}\n`
+        + `  point the SDK at it with TURBOPUFFER_BASE_URL=http://127.0.0.1:${s.port}/{region} and any non-empty TURBOPUFFER_API_KEY\n`);
+    await keepProcessAlive();
+}
+else if (cmd === 'conformance') {
+    const { checkTurbopufferConformance } = await import("./turbopuffer-conformance.js");
+    const report = await checkTurbopufferConformance(root ? { root } : {});
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    if (!report.ok)
+        process.exitCode = 1;
+}
+else {
+    process.stdout.write('Usage: world-turbopuffer serve|conformance [--port N] [--root DIR] [--token KEY] [--read-only]\n');
+}

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

@@ -0,0 +1 @@
+{"generatedBy":"scripts/derive-pack.ts","spec":"openapi.yaml.gz","format":"openapi","version":"0.0.1","resources":[{"name":"NamespaceSummary","schema":"NamespaceSummary","fields":[{"name":"id","type":"string","nullable":false,"required":true}],"stateCandidates":[],"expandable":[]}],"operations":[{"id":"get_v1_namespaces","method":"get","path":"/v1/namespaces","pathParams":[],"query":[{"name":"cursor","type":"string","required":false},{"name":"page_size","type":"integer","required":false},{"name":"prefix","type":"string","required":false}],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"NamespaceSummary","list":true,"key":"namespaces"},"class":"list","resource":"NamespaceSummary"},{"id":"post_v1_namespaces_namespace_debug_recall","method":"post","path":"/v1/namespaces/{namespace}/_debug/recall","pathParams":["namespace"],"query":[],"body":[{"name":"filters","type":"any","required":false},{"name":"include_ground_truth","type":"boolean","required":false},{"name":"num","type":"integer","required":false},{"name":"rank_by","type":"any","required":false},{"name":"top_k","type":"integer","required":false}],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"get_v1_namespaces_namespace_hint_cache_warm","method":"get","path":"/v1/namespaces/{namespace}/hint_cache_warm","pathParams":["namespace"],"query":[],"body":[],"bodyEncoding":"none","successStatus":202,"class":"computed"},{"id":"get_v1_namespaces_namespace_metadata","method":"get","path":"/v1/namespaces/{namespace}/metadata","pathParams":["namespace"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"},{"id":"patch_v1_namespaces_namespace_metadata","method":"patch","path":"/v1/namespaces/{namespace}/metadata","pathParams":["namespace"],"query":[],"body":[{"name":"pinning","type":"union","required":false}],"bodyEncoding":"json","successStatus":200,"class":"update"},{"id":"get_v1_namespaces_namespace_operations_token","method":"get","path":"/v1/namespaces/{namespace}/operations/{token}","pathParams":["namespace","token"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"},{"id":"get_v1_namespaces_namespace_schema","method":"get","path":"/v1/namespaces/{namespace}/schema","pathParams":["namespace"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"},{"id":"post_v1_namespaces_namespace_schema","method":"post","path":"/v1/namespaces/{namespace}/schema","pathParams":["namespace"],"query":[],"body":[],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"post_v2_namespaces_namespace","method":"post","path":"/v2/namespaces/{namespace}","pathParams":["namespace"],"query":[],"body":[{"name":"branch_from_namespace","type":"BranchFromNamespaceParams","required":false},{"name":"copy_from_namespace","type":"CopyFromNamespaceParams","required":false},{"name":"delete_by_filter","type":"any","required":false},{"name":"delete_by_filter_allow_partial","type":"boolean","required":false},{"name":"delete_condition","type":"any","required":false},{"name":"deletes","type":"array","required":false},{"name":"disable_backpressure","type":"boolean","required":false},{"name":"distance_metric","type":"DistanceMetric","required":false},{"name":"encryption","type":"Encryption","required":false},{"name":"patch_by_filter","type":"PatchByFilter","required":false},{"name":"patch_by_filter_allow_partial","type":"boolean","required":false},{"name":"patch_columns","type":"Columns","required":false},{"name":"patch_condition","type":"any","required":false},{"name":"patch_rows","type":"array","required":false},{"name":"return_affected_ids","type":"boolean","required":false},{"name":"schema","type":"object","required":false},{"name":"sharding","type":"ShardingConfig","required":false},{"name":"upsert_columns","type":"Columns","required":false},{"name":"upsert_condition","type":"any","required":false},{"name":"upsert_rows","type":"array","required":false}],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"delete_v2_namespaces_namespace","method":"delete","path":"/v2/namespaces/{namespace}","pathParams":["namespace"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"delete"},{"id":"post_v2_namespaces_namespace_explain_query","method":"post","path":"/v2/namespaces/{namespace}/explain_query","pathParams":["namespace"],"query":[],"body":[],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"get_v2_namespaces_namespace_metadata","method":"get","path":"/v2/namespaces/{namespace}/metadata","pathParams":["namespace"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"},{"id":"post_v2_namespaces_namespace_query","method":"post","path":"/v2/namespaces/{namespace}/query","pathParams":["namespace"],"query":[],"body":[],"bodyEncoding":"json","successStatus":200,"class":"non-resource"}]}

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

@@ -0,0 +1 @@
+{"generatedBy":"scripts/derive-pack.ts","resources":{}}

package/dist/src/index.d.ts

@@ -0,0 +1,11 @@
+import { type TwinPack } from '@volter/world-core';
+export { handleTurbopufferTwinRequest, extractTurbopufferApiKey, normalizeTurbopufferPath, turbopufferTwinSnapshot, } from './turbopuffer-twin.js';
+export type { TurbopufferTwinRequest, TurbopufferTwinResponse } from './turbopuffer-twin.js';
+export { createTurbopufferTwinFetch, createTurbopufferTwinServer } from './turbopuffer-server.js';
+export type { TurbopufferTwinFetchOptions } from './turbopuffer-server.js';
+export { performTurbopufferAction, syncTurbopufferFromReal, syncTurbopufferFromRemote, mapSchemaAttr } from './turbopuffer-connector.js';
+export { SERVICE, TURBOPUFFER_RESOURCE_TYPES, TurbopufferError, applyWrite, runQuery, loadNamespaces, schemaWire, cosineDistance, euclideanSquared, } from './turbopuffer-store.js';
+export type { NamespaceState, AttrConfig, Doc } from './turbopuffer-store.js';
+export { compileFilter } from './turbopuffer-filter.js';
+export { tokenize, queryTerms, bm25Score, buildCorpus, DEFAULT_FTS } from './turbopuffer-text.js';
+export declare const pack: TwinPack;

package/dist/src/index.js

@@ -0,0 +1,65 @@
+// @volter/twin-turbopuffer — the Turbopuffer API twin (v2 namespaces), built on @volter/world-core.
+// Namespaces and their documents are kernel state; writes (upsert/patch/delete by id or filter,
+// with schema and distance metric) land as one kernel action per request; queries filter, BM25-rank
+// (deterministic, see turbopuffer-text.ts), order by attribute, rank by exact vector distance and
+// count. See README ## Coverage for what is modelled and what fails loudly.
+import { registerPack } from '@volter/world-core';
+import { performTurbopufferAction, syncTurbopufferFromRemote } from "./turbopuffer-connector.js";
+export { handleTurbopufferTwinRequest, extractTurbopufferApiKey, normalizeTurbopufferPath, turbopufferTwinSnapshot, } from "./turbopuffer-twin.js";
+export { createTurbopufferTwinFetch, createTurbopufferTwinServer } from "./turbopuffer-server.js";
+export { performTurbopufferAction, syncTurbopufferFromReal, syncTurbopufferFromRemote, mapSchemaAttr } from "./turbopuffer-connector.js";
+export { SERVICE, TURBOPUFFER_RESOURCE_TYPES, TurbopufferError, applyWrite, runQuery, loadNamespaces, schemaWire, cosineDistance, euclideanSquared, } from "./turbopuffer-store.js";
+export { compileFilter } from "./turbopuffer-filter.js";
+export { tokenize, queryTerms, bm25Score, buildCorpus, DEFAULT_FTS } from "./turbopuffer-text.js";
+// Registry descriptor (TwinPack) — the SINGLE HOME for this vendor's world-facing facts.
+// `bun scripts/pack-facts.ts` compiles `adoption` / `hosts` / `endpointEnv` into
+// packages/world-core/generated/pack-facts.json; re-run it after ANY edit below.
+export const pack = {
+    vendor: 'turbopuffer',
+    transport: 'rest',
+    protocol: '2',
+    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, deleteAll, metadata, schema, list namespaces. 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.',
+    refresh: { every: '15m', onDemand: { atMost: '30s' } },
+    stateSystem: { perform: performTurbopufferAction, refresh: syncTurbopufferFromRemote },
+    // An upsert of a caller-chosen id: the vendor's own idempotence, so the branch re-send lands cleanly.
+    roundTrip: {
+        method: 'POST',
+        path: '/v2/namespaces/round-trip',
+        body: { upsert_rows: [{ id: 'round-trip', title: 'round trip' }] },
+        headers: { authorization: 'Bearer round-trip' },
+    },
+    // 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.
+    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.',
+    },
+};
+registerPack(pack);

package/dist/src/key-gate.d.ts

@@ -0,0 +1,3 @@
+import type { SemanticsContext } from '@volter/world-core';
+/** The gate's answer for a request to `operation`, or undefined when it may pass. */
+export declare function keyGate(ctx: SemanticsContext, request: Request, operation: string): Response | undefined;

package/dist/src/key-gate.js

@@ -0,0 +1,39 @@
+// The API key gate, in front of the derived dispatch. "The HTTP API expects the API key to be formatted as a standard
+// Bearer token and passed in the Authorization header", and keys are made and expired on the dashboard
+// (https://turbopuffer.com/docs/auth; screens/dashboard.tsx).
+//
+// What the gate refuses, and where turbopuffer's documentation stops:
+// - a key the dashboard made and then expired, and a key of turbopuffer's form (`tpuf_…`) the dashboard never made:
+//   401, the twin's reading. turbopuffer's pages print only the error body (https://turbopuffer.com/docs/api-overview)
+//   and name no status for a bad key; 401 is the status turbopuffer's own client reads as a failed authentication
+//   (`if (status === 401) return new AuthenticationError(...)`, https://raw.githubusercontent.com/turbopuffer/turbopuffer-typescript/v2.8.0/src/core/error.ts).
+// - a key without the permission an operation needs, only where turbopuffer says which: listing namespaces "is available
+//   to API keys with list or admin permissions" (https://turbopuffer.com/docs/namespaces). 403, the twin's reading, by
+//   the same client line's neighbour (`if (status === 403) return new PermissionDeniedError(...)`); no page prints the
+//   answer for a key that lacks a permission. The messages are the twin's.
+// Every other operation admits any live key: the docs name read/write permissions without saying which endpoint needs
+// which, so the twin enforces none of them (manifest.ts records the gap).
+// A key that is not of turbopuffer's form is the World's own (a World pointing an application at the twin with a key
+// of its choosing) and is not checked here; the request handler still refuses a request with no key (401).
+import { createHash } from 'node:crypto';
+const refuse = (status, error) => Response.json({ status: 'error', error }, { status });
+/** Operations whose permission turbopuffer documents, and the permissions that admit a key to each. */
+const NEEDS = { get_v1_namespaces: ['list', 'admin'] };
+/** The gate's answer for a request to `operation`, or undefined when it may pass. */
+export function keyGate(ctx, request, operation) {
+    const m = /^bearer\s+(\S+)\s*$/i.exec(request.headers.get('authorization') ?? '');
+    const key = m?.[1];
+    if (!key || !key.startsWith('tpuf_'))
+        return undefined;
+    const sha = createHash('sha256').update(key).digest('hex');
+    const held = ctx.rowsRaw('_api_key').find((k) => k.key_sha256 === sha);
+    if (!held)
+        return refuse(401, 'unauthorized: the API key is not valid');
+    if (held.expired_at)
+        return refuse(401, 'unauthorized: the API key has expired');
+    const needs = NEEDS[operation];
+    const grants = Array.isArray(held.grants) ? held.grants : [];
+    if (needs && !needs.some((g) => grants.includes(g)))
+        return refuse(403, `forbidden: this API key needs the ${needs.join(' or ')} permission`);
+    return undefined;
+}

package/dist/src/manifest.d.ts

@@ -0,0 +1,2 @@
+import type { DerivedManifest } from '@volter/world-core';
+export declare const manifest: DerivedManifest;

package/dist/src/manifest.js

@@ -0,0 +1,28 @@
+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',
+    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' },
+    // 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 } },
+    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',
+        }],
+    resources: {},
+};

package/dist/src/screens/dashboard.d.ts

@@ -0,0 +1,11 @@
+import type { SemanticsContext } from '@volter/world-core';
+export declare const DASHBOARD_HOST = "turbopuffer.com";
+export declare const GRANTS: readonly ["read", "write", "list", "admin"];
+export type Grant = (typeof GRANTS)[number];
+type Row = Record<string, unknown>;
+/** The organization's live and expired keys, oldest first. */
+export declare function keysOf(ctx: SemanticsContext, organization: string): Row[];
+/** turbopuffer.com's pages and the World's sign-up door, or undefined for any other path. `contextFor` gives the
+ *  pack's semantics context for a request. */
+export declare function dashboard(request: Request, contextFor: (request: Request) => Promise<SemanticsContext>): Promise<Response | undefined>;
+export {};