@volter/twin-upstashvector 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,233 @@
+# @volter/twin-upstashvector
+
+A local, stateful, vendor-faithful twin of the **Upstash Vector** REST API, built on the shared
+[`@volter/world-core`](../../world-core) kernel.
+
+Point the real, unmodified [`@upstash/vector`](https://www.npmjs.com/package/@upstash/vector) SDK at
+it with nothing but its own public `url` option and it works:
+
+```ts
+import { Index } from '@upstash/vector';
+
+const index = new Index({ url: 'http://127.0.0.1:PORT', token: 'any-non-empty-token' });
+
+await index.upsert([{ id: 'lotr', vector: [1, 0, 0], metadata: { genre: 'fantasy' } }]);
+await index.query({ vector: [1, 0, 0], topK: 3, filter: "genre = 'fantasy'", includeMetadata: true });
+```
+
+```bash
+bunx world-upstashvector serve --port 8080 --dimension 1536 --similarity COSINE
+```
+
+## What makes this a twin and not a mock
+
+**The scores are computed, never faked.** `/query` ranks by a similarity score derived from the
+stored coordinates, using Upstash's own published normalizations
+([similarity functions](https://upstash.com/docs/vector/features/similarityfunctions)):
+
+| metric | score |
+|---|---|
+| `COSINE` | `(1 + cosine_similarity(v1, v2)) / 2` |
+| `EUCLIDEAN` | `1 / (1 + squared_distance(v1, v2))` |
+| `DOT_PRODUCT` | `(1 + dot_product(v1, v2)) / 2` |
+
+So every ranking this twin produces is hand-checkable with a calculator: an exact match under
+`COSINE` scores exactly `1`, an orthogonal vector exactly `0.5`, an opposed vector exactly `0`. A
+vector twin whose `score` was a counter, a random number, or an insertion-order rank would let a
+broken retrieval pipeline pass its tests — which is the entire failure this pack exists to prevent.
+Changing the metric genuinely changes the **order**, not just the number.
+
+**Metadata filtering is a real language.** `filter` strings are tokenized, parsed to an AST and
+evaluated — `=`, `!=`, `<`, `>`, `<=`, `>=`, `GLOB`, `NOT GLOB`, `IN`, `NOT IN`, `CONTAINS`,
+`NOT CONTAINS`, `HAS FIELD`, `HAS NOT FIELD`, `AND`/`OR` with the vendor's documented precedence
+(`AND` binds tighter), parentheses, arbitrarily nested `.` paths, and `[n]` / `[#-1]` array
+indexing. An expression this pack's own tests never anticipated still works, and a **malformed
+filter is rejected with a 400 rather than silently matching everything** — a filter language that
+ignored a typo would turn one mistake into a full-index data leak.
+
+**State lives in the kernel action log**, not in a map: every vector is one kernel subject, so a
+restart against the same `--root` answers the same `/query`.
+
+## Endpoints
+
+| | |
+|---|---|
+| `POST /upsert[/{ns}]` | one vector object or an array of them |
+| `POST /query[/{ns}]` | an object is one query; an **array** is `queryMany` |
+| `POST /fetch[/{ns}]` | by `ids` (positionally aligned, `null` for a miss) or by `prefix` |
+| `POST /range[/{ns}]` | offset cursor; `nextCursor` is `""` when exhausted |
+| `POST /update[/{ns}]` | `{updated: 0\|1}`, `metadataUpdateMode` `OVERWRITE`\|`PATCH` |
+| `POST\|DELETE /delete[/{ns}]` | by `ids`, `prefix` or metadata `filter` → `{deleted: N}` |
+| `POST\|DELETE /reset[/{ns}]`, `/reset?all` | empty one namespace, or all of them |
+| `GET\|POST /info` | counts, configuration, and the per-namespace map |
+| `GET\|POST /list-namespaces` | the default namespace is named `""` |
+| `POST\|DELETE /delete-namespace/{ns}` | removes the namespace **and** its contents |
+
+Three protocol facts a naive twin gets wrong, all confirmed against the installed SDK's own source:
+
+1. **Every SDK call is a `POST`**, whatever the docs say the method is — `@upstash/vector`'s
+   `HttpClient` hardcodes `method: "POST"`, so although the docs spell `/reset` and
+   `/delete-namespace` as `-X DELETE`, the real client never sends `DELETE`. Both are accepted.
+2. **Namespaces are a path suffix, not a body field.** `index.namespace("ns").query(...)` becomes
+   `POST /query/ns`. A twin reading `body.namespace` would serve every namespaced request out of
+   the default namespace — every tenant seeing every other tenant's vectors.
+3. **`/query` is overloaded on body shape**, and a **single-element** `queryMany` batch answers
+   **flat** rather than nested. The SDK's `QueryManyCommand.exec` re-nests exactly that case, and
+   its own comment documents it as real API behaviour.
+
+## Coverage
+
+Partial and honest: the capability manifest (`src/upstashvector-capabilities.ts`) is the **real
+vendor surface** as the denominator — every REST endpoint crossed with every documented feature
+(namespaces, filtering, metadata, similarity functions, sparse/hybrid indexes, embedding models,
+resumable queries, plan limits) — so features this twin has **not** built appear as `todo`s rather
+than being quietly left out of the count. Run `bun scripts/manifest-baseline-one.ts upstashvector`
+for the current numbers.
+
+Modeled and proven: the ten endpoints above, dense vectors with a configurable dimension, all three
+similarity metrics computed for real, namespaces (isolation, list, delete), the full metadata-filter
+language, `metadataUpdateMode`, Bearer auth with a 401, the `{result}` / `{error, status}` envelope,
+`readOnly` mode, and a connector that pulls a real index over an **injected** client.
+
+### Planned (todo), and what this twin does not run
+
+- **The `data`-based endpoints** (`/upsert-data`, `/query-data`) are filed as gaps and **fail
+  loudly with a 404** naming them. This twin runs no embedding model, and hashing text into a
+  pseudo-vector would return confident nonsense rankings that look exactly like a working retrieval
+  pipeline. Send an explicit `vector` — which this twin fully supports — to model the same flow.
+- **`pendingVectorCount`** is filed as a gap: the vendor indexes asynchronously, so a just-upserted
+  vector is briefly pending and unqueryable, while this twin's upsert is synchronous and the count
+  is always `0`. Callers testing read-your-own-write get the strictest behaviour, never a flaky one.
+- Scoring is **exhaustive and therefore exact**: every vector in the namespace is scored and ranked,
+  rather than reproducing DiskANN's approximate recall. Consequence worth knowing: **this twin will
+  never reproduce a recall miss the real index would have.** A single local process likewise has no
+  replicas, so there is no replication lag to observe.
+
+### Grounding, and what could NOT be grounded
+
+Grounded (2026-08-19) from the vendor's REST endpoint docs, its feature docs, and the
+**actually-installed `@upstash/vector@1.2.3` source** (its `HttpClient` and every `Command`'s
+endpoint construction) — see `spec-sources.json`.
+
+**This pack had no live Upstash Vector index to probe**, unlike its sibling
+[`upstash`](../upstash), which live-probed a real ephemeral database for every literal
+error string. That difference is disclosed rather than papered over:
+
+- **Two** error messages here are the vendor's verbatim published text: the dimension mismatch
+  `Invalid vector dimension: N, expected: M` (the `/upsert` page's own 422 example) and the 401
+  body `{"error": "Unauthorized: Invalid auth token", "status": 401}` (the get-started page's own
+  error example — note the capital `I`). The capabilities that assert them say so.
+- Every **other** error capability asserts the **status code** and the documented `{error, status}`
+  **envelope**, both of which are grounded, and does **not** claim a vendor wording this pack never
+  read. `upstashvector.errors.vendor_error_strings` is the filed gap for closing this with a live
+  probe.
+- Four behaviours are explicitly **twin-defined** where the vendor is silent, and are marked as
+  such in the manifest and in code: the query **tie-break** (equal scores order by id ascending, so
+  rankings are reproducible), the **zero-vector** cosine result (`0` similarity → score `0.5`,
+  rather than letting a `NaN` serialise to `null`), **refusing to delete the default namespace**
+  (`/reset` is how you empty it), and **refusing an empty `filter` on `/delete`** — on `/query` an
+  empty filter harmlessly means "no filter", but the same reading on a delete would mean "match
+  every vector", so a caller's template rendering to `""` gets a 400 rather than a wiped namespace.
+
+### A pull is a mirror, and local writes win over it
+
+`syncUpstashVectorFromReal` writes the kernel's **observed** layer; local writes are projected
+**over** it. So an id you have already upserted locally keeps its local value, and a later pull of
+that same id does not surface. That is deliberate — a mirror refresh must never silently revert a
+local commit — and it is the same fork model `qstash` and `upstash` use. But it means "pulled
+vectors are queryable" holds for ids with **no** local write, not unconditionally, and the pull
+currently counts shadowed ids in `deltasAppended` as though they landed. Filed as
+`upstashvector.connector.pull_shadowed_by_local_writes`.
+
+### Safe methods never mutate
+
+`GET` and `HEAD` are safe methods (RFC 9110), so neither can modify the index here: a `GET /reset`
+or `HEAD /delete` is refused `405` and changes nothing. No documented Upstash Vector client sends
+one — the SDK `POST`s everything — so the cost of refusing is zero for real callers, while the cost
+of allowing it is an index destroyed by something that thought it was reading. What the real
+service does with those requests is unverified and filed as
+`upstashvector.protocol.get_on_a_write_endpoint`.
+
+A pulled index also has no `config` subject, so its dimension is **inferred** from the stored
+vectors when they all agree — so `/info` reports the real dimension, a mis-sized query gets the
+vendor's 422 rather than a silent empty result, and a later upsert cannot lock in a rival dimension
+and orphan the pulled data. (`upstashvector.connector.pull_index_configuration` tracks pulling the
+declared value from `/info` instead of inferring it.) If a pull ever delivers **mixed** lengths, no
+dimension can be honestly inferred, so the next write is **refused** — start the twin with an
+explicit `--dimension` rather than letting one write orphan the others.
+
+The connector also **refuses** a vendor row it cannot store faithfully, by id: a non-numeric or
+overflow-scale coordinate, or an id/namespace carrying an unpaired UTF-16 surrogate. Coercing
+instead would substitute a different vector for the real one — `NaN` becomes `null` in JSON and
+`Number(null)` is `0`.
+
+### Rate budget
+
+Upstash publishes **no requests-per-second limit for Upstash Vector** — this was checked, and the
+absence is the finding. The published figures are per-**day** caps and per-request billing
+($0.4/100K on Pay-As-You-Go; 10,000 queries/day on Free), plus shape limits (max dimension 1,536
+Free → 5,000 Pro, max topK 1,000, metadata 48 KB/vector, data 1 MB/vector). Since no scalar rate is
+documented, the declaration stays **at** the kernel's austere fallback — 60 units / 60s at the
+default weight of 2 = **30 requests/minute** — rather than inventing headroom. `range` costs 6
+because its cost scales with the customer's index rather than with the request, and it is the only
+entrypoint that loops.
+
+**What that ceiling does and does not protect.** It bounds a **burst** (a 60-second rolling window,
+fail-closed) and is the tightest burst the architecture permits without a published vendor rate to
+cite. It does **not** bound daily spend: 30/minute is 43,200/day, roughly **4.3x looser** than the
+Free tier's 10,000 queries/day, so sustained pulling at the ceiling would exhaust a Free index's
+daily quota in about 5.5 hours. A rolling-minute window structurally cannot bound a daily quota —
+watch that yourself on a long or repeated sync. (Contrast `upstash`, which *is* more permissive than the fallback, and
+is so precisely because Upstash publishes a scalar 10,000 commands/sec for Redis.)
+
+### Host routing — a shared apex with `upstash`
+
+Upstash Vector index endpoints and Upstash Redis database endpoints live on the **same apex**,
+`*.upstash.io`, so the injector's `VENDOR_HOSTS` table has to tell them apart. It does so by host
+**shape**, which is stable and checkable:
+
+```
+Vector   https://<slug>-<region>-vector.upstash.io   e.g. living-whale-89944-us1-vector.upstash.io
+Redis    https://<slug>.upstash.io                   e.g. striking-osprey-20681.upstash.io
+QStash   https://qstash.upstash.io                   (fixed host, its own pack)
+```
+
+Every real Upstash Vector host carries a `-vector` token immediately before `.upstash.io`, so
+`upstashvector` matches `h.endsWith('-vector.upstash.io')` and `upstash` was narrowed to
+exclude it. Without that narrowing the pre-existing Redis suffix matcher would have swallowed every
+Vector request the moment `UPSTASH_TWIN_URL` was set — a silently mis-routed request that
+looks like a bug in the wrong pack. See `packages/world-core/inject.cjs` and
+`scripts/vendor-hosts.test.ts`, which pins both directions.
+
+### No UI mirror
+
+Upstash Vector is an **API-first** vendor: an integrator *calls* this product from code, and the
+Upstash console is a provisioning-and-metrics dashboard — where you create an index and read its
+charts — not where the work happens. Nobody browses their vector index to do their job; they query
+it from an application. So this pack ships **no mirror** and has **no UI capabilities**; a screen
+here would be a fabricated one. This is the same call as the sibling `upstash` pack and as
+`pinecone`, the repo's other vector-database twin. The capability test asserts it, so a UI
+capability cannot appear here by accident.
+
+## Layout
+
+| file | |
+|---|---|
+| `src/upstashvector-twin.ts` | the request handler — routing, auth, envelope |
+| `src/upstashvector-store.ts` | the index core: kernel-backed state **and the similarity math** |
+| `src/upstashvector-filter.ts` | the metadata-filter tokenizer, parser and evaluator |
+| `src/upstashvector-server.ts` | `createUpstashVectorTwinServer({ root, port, readOnly, token, dimension, similarityFunction })` |
+| `src/upstashvector-connector.ts` | pull over an **injected** client (no SDK import, no token held) |
+| `src/upstashvector-budget.ts` | the rate-budget declaration + the guard every live call goes through |
+| `src/upstashvector-capabilities.ts` | the capability manifest — the real vendor surface |
+| `src/upstashvector-conformance.ts` | dev-only endpoint probes (lazy-imported by the CLI) |
+
+## Tests
+
+```bash
+bun test src/*.test.ts
+```
+
+`src/upstashvector-sdk.integration.test.ts` drives the **real, unmodified** `@upstash/vector` SDK
+against the twin over HTTP — the fidelity proof. The SDK is a **devDependency only**; the pack
+imports no SDK at runtime and holds no token.

package/dist/src/cli.d.ts

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

package/dist/src/cli.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-upstashvector CLI: serve the KERNEL-BACKED Upstash Vector REST twin, or run conformance.
+// State lives in the @volter/world-core action log (no in-memory side-store). Conformance is dev-only +
+// lazy-imported so the bin runs without @volter/world-tooling (E2).
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createUpstashVectorTwinServer } from "./upstashvector-server.js";
+import { SIMILARITY_FUNCTIONS } from "./upstashvector-store.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') || undefined;
+// The token this twin will DEMAND. Omit it and any non-empty credential is accepted (a missing one
+// is still a vendor-shaped 401) — the right default for a local twin that holds no real secret.
+const token = optionValue(rest, '--token') || undefined;
+const dimension = Number(optionValue(rest, '--dimension', '0')) || undefined;
+const similarityRaw = optionValue(rest, '--similarity') || undefined;
+const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+if (similarityRaw !== undefined && !SIMILARITY_FUNCTIONS.includes(similarityRaw.toUpperCase())) {
+    process.stderr.write(`--similarity must be one of ${SIMILARITY_FUNCTIONS.join(', ')}\n`);
+    process.exit(1);
+}
+const similarityFunction = similarityRaw?.toUpperCase();
+if (cmd === 'serve' || cmd === undefined) {
+    const s = await createUpstashVectorTwinServer({
+        readOnly,
+        ...(root ? { root } : {}),
+        ...(port ? { port } : {}),
+        ...(token ? { token } : {}),
+        ...(dimension ? { dimension } : {}),
+        ...(similarityFunction ? { similarityFunction } : {}),
+    });
+    process.stdout.write(`upstashvector twin (Upstash Vector REST: /upsert /query /fetch /range /delete /update /reset /info, namespaces as a path suffix)${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${s.port}\n`
+        + `  point a client at it with UPSTASH_VECTOR_REST_URL=http://127.0.0.1:${s.port} and any non-empty UPSTASH_VECTOR_REST_TOKEN\n`);
+    await keepProcessAlive();
+}
+else if (cmd === 'conformance') {
+    const { checkUpstashVectorConformance } = await import("./upstashvector-conformance.js");
+    const report = await checkUpstashVectorConformance();
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    if (!report.ok)
+        process.exitCode = 1;
+}
+else {
+    process.stdout.write('Usage: world-upstashvector serve|conformance [--port N] [--root DIR] [--token T] [--dimension N] [--similarity COSINE|EUCLIDEAN|DOT_PRODUCT] [--read-only]\n');
+}

package/dist/src/index.d.ts

@@ -0,0 +1,14 @@
+export { handleUpstashVectorTwinRequest, routeUpstashVectorPath, upstashvectorTwinSnapshot, extractUpstashVectorCredential, UPSTASH_VECTOR_UNAUTHORIZED_ERROR, } from './upstashvector-twin.js';
+export type { UpstashVectorRequest, UpstashVectorResponse, UpstashVectorRoute, UpstashVectorCommand, UpstashVectorTwinSnapshot, } from './upstashvector-twin.js';
+export { IndexSpace, SERVICE, DEFAULT_NAMESPACE, DEFAULT_SIMILARITY, SIMILARITY_FUNCTIONS, UPSTASHVECTOR_RESOURCE_TYPES, CONFIG_SUBJECT_ID, VectorApiError, ReadOnlyError, cosineSimilarity, dotProduct, squaredDistance, similarityScore, vectorSubjectId, namespaceSubjectId, } from './upstashvector-store.js';
+export type { SimilarityFunction, VectorContext, VectorRow, UpstashVectorResourceType, } from './upstashvector-store.js';
+export { parseFilter, tokenizeFilter, evaluateFilter, matchesFilter, resolvePath, parsePath, globMatch, FilterError, MISSING, } from './upstashvector-filter.js';
+export type { FilterNode, FilterValue, ComparisonOp, Token, TokenKind } from './upstashvector-filter.js';
+export { createUpstashVectorTwinFetch, createUpstashVectorTwinServer } from './upstashvector-server.js';
+export type { UpstashVectorServerOptions, UpstashVectorTwinFetchOptions } from './upstashvector-server.js';
+export { mapVector, mapNamespace, pullUpstashVectorRange, pullUpstashVectorNamespaces, syncUpstashVectorFromReal, } from './upstashvector-connector.js';
+export type { UpstashVectorLikeClient, UpstashVectorRealVector, UpstashVectorBudgetedOptions, } from './upstashvector-connector.js';
+export { UPSTASHVECTOR_BUDGETED_METHODS, UPSTASHVECTOR_BUDGET_CEILING, UPSTASHVECTOR_BUDGET_MAX_RETRY_AFTER_S, UPSTASHVECTOR_BUDGET_WINDOW_MS, UPSTASHVECTOR_CALL_WEIGHTS, UPSTASHVECTOR_RATE_BUDGET, UpstashVectorBudget, UpstashVectorBudgetError, upstashvectorBudgetPath, upstashvectorCallWeight, upstashvectorClientBudget, guardUpstashVectorClient, } from './upstashvector-budget.js';
+export type { UpstashVectorBudgetErrorKind, UpstashVectorBudgetOptions, UpstashVectorBudgetReservation, UpstashVectorBudgetSnapshot, } from './upstashvector-budget.js';
+import { type TwinPack } from '@volter/world-core';
+export declare const pack: TwinPack;

package/dist/src/index.js

@@ -0,0 +1,106 @@
+// @volter/twin-upstashvector — the Upstash Vector REST API twin, built on the shared @volter/world-core
+// kernel. Per-index host transport (`https://<slug>-<region>-vector.upstash.io`), the vendor's
+// command-per-path REST surface (`/upsert`, `/query`, `/fetch`, `/range`, `/delete`, `/update`,
+// `/reset`, `/info`, `/list-namespaces`, `/delete-namespace`) with namespaces as a PATH SUFFIX,
+// Bearer-token auth, and the `{result}` / `{error,status}` envelope.
+//
+// Behind that protocol is a REAL vector index. Two things make that claim more than a slogan:
+//
+//   1. THE SCORES ARE COMPUTED, NEVER FAKED. `/query` ranks by a similarity score derived from the
+//      stored coordinates using Upstash's own published normalizations —
+//      COSINE `(1 + cosine_similarity)/2`, EUCLIDEAN `1/(1 + squared_distance)`,
+//      DOT_PRODUCT `(1 + dot_product)/2` — so any ranking this twin produces can be hand-checked
+//      with a calculator. A vector twin whose `score` was a counter or an insertion-order rank
+//      would let a broken retrieval pipeline pass its tests, which is the exact failure this pack
+//      exists to prevent.
+//   2. METADATA FILTERING IS A REAL LANGUAGE. `filter` strings are tokenized, parsed to an AST and
+//      evaluated (`=`, `!=`, `<`, `>`, `<=`, `>=`, `GLOB`, `IN`, `NOT IN`, `CONTAINS`,
+//      `HAS FIELD`, `HAS NOT FIELD`, `AND`/`OR` with the documented precedence, nested `.` paths and
+//      `[]`/`[#-n]` array indexing) — so an expression this pack's own tests never anticipated
+//      still works, and a malformed one is REJECTED rather than silently matching everything.
+//
+// State lives ENTIRELY in the kernel action log (no side-store): every vector is one kernel
+// subject, so a restart against the same root answers the same `/query`.
+//
+// THE FILED GAPS: this twin runs no embedding model, so the `data`-based `/upsert-data` and
+// `/query-data` surfaces fail loudly rather than hashing text into a fake vector; sparse/hybrid
+// indexes and the resumable-query family are modeled as filed gaps, not silently accepted.
+// See README ## Coverage.
+export { handleUpstashVectorTwinRequest, routeUpstashVectorPath, upstashvectorTwinSnapshot, extractUpstashVectorCredential, UPSTASH_VECTOR_UNAUTHORIZED_ERROR, } from "./upstashvector-twin.js";
+// The index core — exported so a caller can drive the vector semantics (and the MATH) in-process,
+// without HTTP. `similarityScore` in particular is the claim this pack stands on, so it must be
+// callable and checkable directly.
+export { IndexSpace, SERVICE, DEFAULT_NAMESPACE, DEFAULT_SIMILARITY, SIMILARITY_FUNCTIONS, UPSTASHVECTOR_RESOURCE_TYPES, CONFIG_SUBJECT_ID, VectorApiError, ReadOnlyError, cosineSimilarity, dotProduct, squaredDistance, similarityScore, vectorSubjectId, namespaceSubjectId, } from "./upstashvector-store.js";
+// The metadata-filter language. Exported because filter fidelity is a headline claim of this pack
+// and a consumer (or a reviewer) must be able to run an expression against it directly.
+export { parseFilter, tokenizeFilter, evaluateFilter, matchesFilter, resolvePath, parsePath, globMatch, FilterError, MISSING, } from "./upstashvector-filter.js";
+export { createUpstashVectorTwinFetch, createUpstashVectorTwinServer } from "./upstashvector-server.js";
+export { mapVector, mapNamespace, pullUpstashVectorRange, pullUpstashVectorNamespaces, syncUpstashVectorFromReal, } from "./upstashvector-connector.js";
+// The client-side rate budget — the fail-closed backstop every live call goes through. The
+// MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives here is this vendor's
+// DECLARATION (window/ceiling/per-method weights) plus `guardUpstashVectorClient`, the choke point
+// the connector entrypoints apply unconditionally. Exported so an operator can inspect spend
+// (`snapshot`) and a caller can catch `UpstashVectorBudgetError` by type; there is deliberately no
+// export that disables the guard.
+export { UPSTASHVECTOR_BUDGETED_METHODS, UPSTASHVECTOR_BUDGET_CEILING, UPSTASHVECTOR_BUDGET_MAX_RETRY_AFTER_S, UPSTASHVECTOR_BUDGET_WINDOW_MS, UPSTASHVECTOR_CALL_WEIGHTS, UPSTASHVECTOR_RATE_BUDGET, UpstashVectorBudget, UpstashVectorBudgetError, upstashvectorBudgetPath, upstashvectorCallWeight, upstashvectorClientBudget, guardUpstashVectorClient, } from "./upstashvector-budget.js";
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import { registerPack } from '@volter/world-core';
+import { performUpstashVectorAction, syncUpstashVectorFromRemote } from "./upstashvector-connector.js";
+import { UPSTASHVECTOR_RATE_BUDGET as RATE_BUDGET } from "./upstashvector-budget.js";
+export const pack = {
+    // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of
+    // the real state system. Moved 2026-09-08.
+    protocol: '2',
+    // The refresh ranges every namespace, which on a real index is a lot of vectors. Fifteen minutes.
+    refresh: { every: '15m', webhook: false, onDemand: { atMost: '30s' } },
+    stateSystem: { perform: performUpstashVectorAction, refresh: syncUpstashVectorFromRemote },
+    // The round trip is an upsert — Upstash Vector's own write, and an upsert of the same id is the
+    // vendor's own idempotence rather than a refusal, so a second send on a branch lands cleanly.
+    roundTrip: { method: 'POST', path: '/upsert', body: { id: 'round-trip', vector: [0.1, 0.2, 0.3], metadata: { round: 'trip' } }, headers: { authorization: 'Bearer round-trip' } },
+    parityOrigin: 'http://twin',
+    shapeParity: 'held',
+    // The SAME object upstashvector-budget.ts declares at module load — one source of truth, so
+    // registering the pack and importing the connector can never arm two different ceilings.
+    rateBudget: RATE_BUDGET,
+    vendor: 'upstashvector',
+    transport: 'rest',
+    archetype: 'crud',
+    bin: 'world-upstashvector',
+    resources: ['vector', 'namespace', 'config'],
+    specSource: 'upstash.com/docs/vector/api/endpoints/* + features/{namespaces,filtering,similarityfunctions,metadata} + the installed @upstash/vector@1.2.3 compiled source (HttpClient + every Command\'s endpoint construction); see spec-sources.json.',
+    description: 'Upstash Vector REST twin — a real stateful dense-vector index (upsert/query/fetch/range/update/delete/reset/info, namespaces as a path suffix) served over Upstash Vector\'s REST protocol with Bearer auth and the {result}/{error,status} envelope. Similarity scores are COMPUTED from the stored coordinates using Upstash\'s own published normalizations (cosine/euclidean/dot-product), and metadata filtering is a real parsed expression language, so rankings are hand-checkable rather than faked. Kernel-backed; no embedding model (data-based upsert/query fail loudly).',
+    browserRouting: { apiPathPrefix: '/', loaderHost: 'https://twin-vector.upstash.io' },
+    // Adoption, moved off the central maps unchanged (descriptor-first back-migration, adding-a-twin.md §3,
+    // 2026-08-31). The `scopes` entry is the exact PACKAGE name, not an apex: the @upstash/ scope
+    // spans several DIFFERENT Upstash products, each with its own pack. The stem comes from
+    // UPSTASH_VECTOR_REST_URL / _REST_TOKEN (the SDK's own env names, including its NEXT_PUBLIC_
+    // variants, which the framework-prefix strip handles).
+    adoption: {
+        // Upstash's official Vector Python SDK (upstash/vector-py).
+        pypi: ['upstash-vector'],
+        sdks: ['@upstash/vector'], scopes: ['@upstash/vector'], envStems: ['UPSTASHVECTOR'],
+    },
+    // SAME APEX as Upstash Redis, so the two are told apart by host SHAPE — the one discriminator
+    // that is stable and checkable:
+    //   Vector  https://<slug>-<region>-vector.upstash.io  (living-whale-89944-us1-vector.upstash.io,
+    //                                                       boss-lioness-52864-gcp-usc1-vector.upstash.io)
+    //   Redis   https://<slug>.upstash.io                  (striking-osprey-20681.upstash.io)
+    // Every real Vector index endpoint carries a `-vector` token immediately before the apex: the
+    // product suffix is appended to the index slug (which is where the region lives). Corroborated
+    // three ways — ~90 literal hostnames found in public code, live DNS (real index hosts CNAME into
+    // per-region `*-vector` fleets), and the REST token itself, which base64-decodes to
+    // `<slug><role>` where `<slug>` is exactly the host minus `-vector.upstash.io`.
+    //
+    // The two predicates are MUTUALLY EXCLUSIVE by construction rather than by declaration order:
+    // the Redis rule (still in the hand VENDOR_HOSTS table, because it needs exclusions this
+    // descriptor's rule kinds cannot express) explicitly excludes `*-vector.upstash.io`, and
+    // vendor-hosts.test.ts pins both directions. `resolveTwin` iterates VENDOR_HOSTS in insertion
+    // order, so an overlap would have made routing depend on key order — it does not.
+    //
+    // Upstash publishes no hostname format in its docs (every example uses the
+    // $UPSTASH_VECTOR_REST_URL placeholder), so this rule is grounded in observed reality rather
+    // than a spec. A custom-domain or private-link Vector endpoint would not match; that is the safe
+    // direction — it simply is not intercepted, rather than being routed to the wrong twin.
+    hosts: [{ suffix: '-vector.upstash.io' }],
+};
+registerPack(pack);