@volter/twin-upstashvector 0.1.0

package/dist/src/upstashvector-twin.d.ts

@@ -0,0 +1,67 @@
+import { type SimilarityFunction } from './upstashvector-store.js';
+export type UpstashVectorRequest = {
+    method: string;
+    path: string;
+    body?: string;
+    headers?: Record<string, string>;
+    occurredAt?: string;
+    root?: string;
+    readOnly?: boolean;
+    /**
+     * The token this twin accepts. When set, the request's credential must match it EXACTLY.
+     * When omitted the twin accepts any NON-EMPTY credential and still 401s a missing/blank one —
+     * the honest default for a local twin whose whole point is that you hold no real secret.
+     */
+    token?: string;
+    /** The dimension this index was created with. Omit to let the first upsert lock one in. */
+    dimension?: number;
+    /** The metric this index was created with. Defaults to COSINE. */
+    similarityFunction?: SimilarityFunction;
+};
+export type UpstashVectorResponse = {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+};
+/**
+ * The 401 body — VERBATIM from upstash.com/docs/vector/api/get-started, whose error example is
+ * exactly `{"error": "Unauthorized: Invalid auth token", "status": 401}`.
+ *
+ * (§9 round 1 caught this pack UNDER-claiming: an earlier draft used its own wording and declared
+ * the vendor's text unpublished, when the get-started page publishes it. Note the capital `I` in
+ * "Invalid" — matching it exactly is the difference between a consumer's error assertion passing
+ * against this twin and only passing against the real service. This is now one of TWO strings in
+ * the pack quoted verbatim from the vendor, alongside the dimension-mismatch 422.)
+ */
+export declare const UPSTASH_VECTOR_UNAUTHORIZED_ERROR = "Unauthorized: Invalid auth token";
+/** Every endpoint this twin routes, and the ones it deliberately refuses. */
+export type UpstashVectorCommand = 'upsert' | 'query' | 'fetch' | 'range' | 'delete' | 'update' | 'reset' | 'info' | 'list-namespaces' | 'delete-namespace';
+/**
+ * Extract the caller's credential from `Authorization: Bearer <token>` (what the SDK sends) or a
+ * bare `Authorization: <token>`.
+ *
+ * The optional-group regex matters: `Authorization: Bearer ` — the scheme with an EMPTY token —
+ * trims to the bare word "Bearer". A `/^bearer\s+(.*)$/` pattern does not match it, so a naive
+ * implementation falls through and treats the literal string "Bearer" as the credential,
+ * authenticating a request that carries no token at all.
+ */
+export declare function extractUpstashVectorCredential(headers: Record<string, string> | undefined): string | null;
+/** The parsed shape of a request path: which command, and which namespace. */
+export type UpstashVectorRoute = {
+    command: string;
+    namespace: string;
+};
+/**
+ * Split `/query/my-ns` into `{command:'query', namespace:'my-ns'}`.
+ *
+ * Everything after the first segment is the namespace, percent-DECODED and re-joined — a namespace
+ * is an arbitrary string, so one containing a `/` must survive the round trip rather than being
+ * truncated at the first slash into a DIFFERENT namespace's data.
+ */
+export declare function routeUpstashVectorPath(path: string): UpstashVectorRoute;
+export declare function handleUpstashVectorTwinRequest(req: UpstashVectorRequest): Promise<UpstashVectorResponse>;
+export type UpstashVectorTwinSnapshot = {
+    resourceTypes: readonly string[];
+    implementedEndpoints: readonly string[];
+};
+export declare function upstashvectorTwinSnapshot(): UpstashVectorTwinSnapshot;

package/dist/src/upstashvector-twin.js

@@ -0,0 +1,287 @@
+// UPSTASH VECTOR REST TWIN — THE REQUEST HANDLER. Contract:
+//   handleUpstashVectorTwinRequest({ method, path, body, headers, root, occurredAt, readOnly, token })
+//     -> { status, body, headers }
+//
+// This file is the TRANSPORT half; every vector semantic lives in `upstashvector-store.ts` and the
+// metadata-filter language in `upstashvector-filter.ts`. What is modeled here is Upstash Vector's
+// REST protocol itself:
+//
+//   POST /upsert            body: one vector object OR an array of them
+//   POST /upsert/{ns}       ... into a named namespace (namespaces are a PATH SUFFIX)
+//   POST /query             body: one query object → {result:[...]}
+//   POST /query             body: an ARRAY of query objects → queryMany (see below)
+//   POST /fetch  /range  /delete  /update     (+ their /{ns} forms)
+//   POST|DELETE /reset  /reset/{ns}  /reset?all
+//   GET|POST /info          GET|POST /list-namespaces
+//   POST|DELETE /delete-namespace/{ns}
+//
+// ── FOUR THINGS A NAIVE TWIN GETS WRONG ───────────────────────────────────────────────────────
+//
+// 1. EVERY SDK CALL IS A **POST**, whatever the docs say the method is. `@upstash/vector@1.2.3`'s
+//    `HttpClient.request` hardcodes `method: "POST"` (confirmed in the installed dist), so although
+//    the docs spell `/reset` and `/delete-namespace` as `-X DELETE`, the real SDK never sends
+//    DELETE at all. A twin that accepted only the documented method would 405 the actual client.
+//    Both are accepted here.
+//
+// 2. NAMESPACES ARE A PATH SUFFIX, NOT A BODY FIELD. `index.namespace("ns").query(...)` becomes
+//    `POST /query/ns` — the namespace never appears in the JSON. A twin reading `body.namespace`
+//    would silently serve every namespaced request out of the default namespace, so every tenant
+//    would see every other tenant's vectors.
+//
+// 3. `/query` IS OVERLOADED ON BODY SHAPE. An OBJECT body is one query and answers
+//    `{"result":[...]}`; an ARRAY body is `queryMany` and answers a nested `{"result":[[...],...]}`
+//    — EXCEPT for a single-element array, which the real API answers FLAT. That is not a guess:
+//    `QueryManyCommand.exec` in the installed SDK re-nests it and its own comment says "When a
+//    single query is sent via queryMany, the API returns a flat array of results instead of a
+//    nested array." A twin that always nested would hand `queryMany([q])` a doubly-nested result.
+//
+// 4. AN UNMODELED ENDPOINT MUST 404, NEVER 200. `/upsert-data`, `/query-data` and the
+//    resumable-query family are real vendor surface this twin does not serve; each fails with the
+//    vendor's `{error,status}` envelope naming what is missing, so a caller can never mistake
+//    silence for success.
+//
+// GROUNDED (2026-08-19) — see spec-sources.json and the store module's header. Upstash publishes
+// no literal text for most of its errors and this pack had no live index to probe, so the error
+// STRINGS below are twin-authored except the dimension mismatch, which is quoted from the vendor's
+// own upsert doc. What IS faithful and asserted: the `{result}` / `{error,status}` envelope, the
+// status codes, the routing table, and every response body shape.
+import { DEFAULT_NAMESPACE, IndexSpace, ReadOnlyError, VectorApiError, UPSTASHVECTOR_RESOURCE_TYPES, } from "./upstashvector-store.js";
+/** Response headers. `content-type` is what the SDK's `res.json()` requires. */
+const BASE_HEADERS = {
+    'content-type': 'application/json; charset=utf-8',
+    'access-control-allow-credentials': 'true',
+};
+/**
+ * The 401 body — VERBATIM from upstash.com/docs/vector/api/get-started, whose error example is
+ * exactly `{"error": "Unauthorized: Invalid auth token", "status": 401}`.
+ *
+ * (§9 round 1 caught this pack UNDER-claiming: an earlier draft used its own wording and declared
+ * the vendor's text unpublished, when the get-started page publishes it. Note the capital `I` in
+ * "Invalid" — matching it exactly is the difference between a consumer's error assertion passing
+ * against this twin and only passing against the real service. This is now one of TWO strings in
+ * the pack quoted verbatim from the vendor, alongside the dimension-mismatch 422.)
+ */
+export const UPSTASH_VECTOR_UNAUTHORIZED_ERROR = 'Unauthorized: Invalid auth token';
+/** Real vendor endpoints this twin does NOT serve, each with the manifest gap that tracks it. */
+const UNMODELED_ENDPOINTS = {
+    'upsert-data': 'upstashvector.embedding.upsert_data',
+    'query-data': 'upstashvector.embedding.query_data',
+    'resumable-query': 'upstashvector.resumable.start',
+    'resumable-query-data': 'upstashvector.resumable.start',
+    'resumable-query-next': 'upstashvector.resumable.next',
+    'resumable-query-end': 'upstashvector.resumable.stop',
+};
+const MODELED = new Set([
+    'upsert', 'query', 'fetch', 'range', 'delete', 'update', 'reset', 'info', 'list-namespaces', 'delete-namespace',
+]);
+function lowerHeaders(h) {
+    const out = {};
+    for (const [k, v] of Object.entries(h ?? {}))
+        out[k.toLowerCase()] = v;
+    return out;
+}
+/**
+ * Extract the caller's credential from `Authorization: Bearer <token>` (what the SDK sends) or a
+ * bare `Authorization: <token>`.
+ *
+ * The optional-group regex matters: `Authorization: Bearer ` — the scheme with an EMPTY token —
+ * trims to the bare word "Bearer". A `/^bearer\s+(.*)$/` pattern does not match it, so a naive
+ * implementation falls through and treats the literal string "Bearer" as the credential,
+ * authenticating a request that carries no token at all.
+ */
+export function extractUpstashVectorCredential(headers) {
+    const raw = lowerHeaders(headers).authorization;
+    if (raw === undefined)
+        return null;
+    const trimmed = raw.trim();
+    const bearer = /^bearer(?:\s+(.*))?$/i.exec(trimmed);
+    const token = bearer ? (bearer[1] ?? '').trim() : trimmed;
+    return token === '' ? null : token;
+}
+/**
+ * Split `/query/my-ns` into `{command:'query', namespace:'my-ns'}`.
+ *
+ * Everything after the first segment is the namespace, percent-DECODED and re-joined — a namespace
+ * is an arbitrary string, so one containing a `/` must survive the round trip rather than being
+ * truncated at the first slash into a DIFFERENT namespace's data.
+ */
+export function routeUpstashVectorPath(path) {
+    const clean = (path.split('?')[0] ?? '/').replace(/^\/+/, '');
+    const segments = clean.split('/');
+    const command = decodeSegment(segments[0] ?? '').toLowerCase();
+    const namespace = segments.length > 1 ? segments.slice(1).map(decodeSegment).join('/') : DEFAULT_NAMESPACE;
+    return { command, namespace };
+}
+function decodeSegment(seg) {
+    try {
+        return decodeURIComponent(seg);
+    }
+    catch {
+        return seg; // a malformed escape is passed through rather than turned into a 500
+    }
+}
+export async function handleUpstashVectorTwinRequest(req) {
+    const method = req.method.toUpperCase();
+    const [rawPath, rawQuery] = req.path.split('?');
+    const query = new URLSearchParams(rawQuery ?? '');
+    const headers = lowerHeaders(req.headers);
+    const occurredAt = req.occurredAt ?? new Date().toISOString();
+    // CORS preflight. Answered before auth — a browser preflight carries no Authorization header by
+    // definition, so 401ing it would make the twin unusable from any browser client.
+    if (method === 'OPTIONS') {
+        return {
+            status: 200,
+            body: null,
+            headers: {
+                'access-control-allow-origin': headers.origin ?? '*',
+                'access-control-allow-methods': 'GET,POST,PUT,DELETE,HEAD,OPTIONS',
+                'access-control-allow-headers': headers['access-control-request-headers'] ?? 'authorization,content-type',
+                'access-control-allow-credentials': 'true',
+            },
+        };
+    }
+    // upstash.com/docs/vector/api/get-started documents 405 for an unsupported method. DELETE is
+    // included because the docs spell `/reset` and `/delete-namespace` with `-X DELETE`.
+    if (!['GET', 'POST', 'PUT', 'HEAD', 'DELETE'].includes(method)) {
+        return fail(405, `Method Not Allowed: ${method}`);
+    }
+    // ── auth, before anything else ─────────────────────────────────────────────────────────────
+    const credential = extractUpstashVectorCredential(req.headers);
+    const authorized = req.token === undefined ? credential !== null : credential === req.token;
+    if (!authorized)
+        return fail(401, UPSTASH_VECTOR_UNAUTHORIZED_ERROR);
+    const { command, namespace } = routeUpstashVectorPath(rawPath ?? '/');
+    if (command === '')
+        return fail(404, 'Not Found: no endpoint at /');
+    if (!MODELED.has(command)) {
+        const gap = UNMODELED_ENDPOINTS[command];
+        // A REAL vendor endpoint this twin has not built fails 404 naming the filed gap; anything else
+        // is simply not an Upstash Vector endpoint. Neither can ever be mistaken for a success.
+        return fail(404, gap !== undefined
+            ? `upstashvector: /${command} is real Upstash Vector surface this twin does not model yet (${gap} is the filed gap)`
+            : `Not Found: /${command} is not an Upstash Vector endpoint`);
+    }
+    // GET AND HEAD ARE SAFE METHODS, so neither may mutate anything.
+    //
+    // §9 round 1 found the worst bug in this file: the HEAD check used to live AFTER `runCommand`
+    // and `flush()`, so `HEAD /reset` emptied the index and `HEAD /delete` removed vectors — then
+    // suppressed the body and answered a read-shaped, body-less 200. A destructive operation
+    // disguised as a read is the worst available failure mode. Forcing the request read-only means
+    // a HEAD to a write endpoint takes the ordinary 405 read-only path, while `HEAD /info` still
+    // answers 200 with no body.
+    //
+    // GET is included for the same reason (RFC 9110 defines both as safe): caches, prefetchers,
+    // crawlers and link-checkers issue GET freely, and no documented Upstash Vector client ever
+    // sends GET to a write endpoint — the SDK POSTs everything, and the docs use POST or DELETE. So
+    // the cost of refusing is zero for every real caller, while the cost of allowing it is an index
+    // destroyed by something that thought it was reading. What the REAL service does with
+    // `GET /reset` is UNVERIFIED (no live index to probe) and is filed as
+    // `upstashvector.protocol.get_on_a_write_endpoint`; this twin takes the safe side deliberately
+    // rather than guessing the destructive one.
+    const readOnly = (req.readOnly ?? false) || method === 'HEAD' || method === 'GET';
+    const ctx = {
+        occurredAt,
+        ...(req.root !== undefined ? { root: req.root } : {}),
+        ...(readOnly ? { readOnly: true } : {}),
+        ...(req.dimension !== undefined ? { dimension: req.dimension } : {}),
+        ...(req.similarityFunction !== undefined ? { similarityFunction: req.similarityFunction } : {}),
+    };
+    try {
+        const space = new IndexSpace(ctx);
+        const result = await runCommand(space, command, namespace, req.body, query);
+        await space.flush();
+        // HEAD answers with no body at all.
+        if (method === 'HEAD')
+            return { status: 200, body: null, headers: { ...BASE_HEADERS } };
+        return { status: 200, body: { result }, headers: { ...BASE_HEADERS } };
+    }
+    catch (e) {
+        if (e instanceof ReadOnlyError) {
+            // Distinguish the two reasons a write can be refused. §9 round 2: a `HEAD /upsert` against a
+            // perfectly writable twin used to answer "this twin was started read-only", which is simply
+            // false and sends the reader hunting for a flag they never set.
+            return fail(405, readOnly && !(req.readOnly ?? false)
+                ? `upstashvector: ${method} is a safe method and cannot modify the index — use POST (or PUT/DELETE where the endpoint documents it)`
+                : e.message);
+        }
+        if (e instanceof VectorApiError)
+            return fail(e.status, e.message);
+        // LAST-RESORT ENVELOPE. A twin's caller must always get a response it can reason about, and an
+        // internal fault must be VISIBLE rather than silent — an unhandled rejection would leave the
+        // request with no HTTP answer at all. Surfaced as a loud, twin-attributed 500.
+        return fail(500, `upstashvector: internal fault handling /${command} — ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+/** The vendor's error envelope: `{"error": "...", "status": N}` (upsert doc's own 422 example). */
+function fail(status, error) {
+    return { status, body: { error, status }, headers: { ...BASE_HEADERS } };
+}
+async function runCommand(space, command, namespace, rawBody, query) {
+    switch (command) {
+        case 'info':
+            return space.info();
+        case 'list-namespaces':
+            return space.listNamespaces();
+        case 'delete-namespace':
+            space.deleteNamespace(namespace);
+            return 'Success';
+        case 'reset':
+            // `?all` is a BARE query flag — `ResetCommand` builds the literal string `reset?all`, so the
+            // parameter has an empty value and `query.get('all')` is `''`, not `null`. Testing
+            // `.has('all')` is what makes the SDK's own spelling work.
+            return space.reset(query.has('all') ? { all: true } : { namespace });
+        case 'upsert': {
+            const body = parseJsonBody(rawBody);
+            // The vendor accepts a single object OR an array (its own doc shows both curl forms).
+            return space.upsert(namespace, Array.isArray(body) ? body : [body]);
+        }
+        case 'update':
+            return space.update(namespace, parseJsonBody(rawBody));
+        case 'fetch':
+            return space.fetch(namespace, parseJsonBody(rawBody));
+        case 'range':
+            return space.range(namespace, parseJsonBody(rawBody));
+        case 'delete':
+            return space.delete(namespace, parseJsonBody(rawBody));
+        case 'query': {
+            const body = parseJsonBody(rawBody);
+            if (!Array.isArray(body))
+                return space.query(namespace, body);
+            // queryMany. See the module header, point 3: a ONE-element batch answers FLAT, which is the
+            // shape the installed SDK's own normalization proves the real API returns.
+            if (body.length === 0)
+                throw new VectorApiError('upstashvector: query batch must not be empty', 400);
+            const results = body.map((one) => space.query(namespace, one));
+            return body.length === 1 ? results[0] : results;
+        }
+    }
+}
+/** Parse a JSON request body, refusing what the vendor refuses. */
+function parseJsonBody(raw) {
+    if (raw === undefined || raw.trim() === '')
+        throw new VectorApiError('upstashvector: request body is required', 400);
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new VectorApiError('upstashvector: request body is not valid JSON', 400);
+    }
+}
+export function upstashvectorTwinSnapshot() {
+    return {
+        resourceTypes: UPSTASHVECTOR_RESOURCE_TYPES,
+        implementedEndpoints: [
+            'POST /upsert[/{namespace}] (one vector object or an array of them)',
+            'POST /query[/{namespace}] (an object = one query; an array = queryMany)',
+            'POST /fetch[/{namespace}] (by ids — positionally aligned, null for a miss — or by prefix)',
+            'POST /range[/{namespace}] (offset cursor, nextCursor "" when exhausted)',
+            'POST /update[/{namespace}] ({updated:0|1}, metadataUpdateMode OVERWRITE|PATCH)',
+            'POST|DELETE /delete[/{namespace}] (by ids, prefix or metadata filter)',
+            'POST|DELETE /reset[/{namespace}] and /reset?all',
+            'GET|POST /info (counts + configuration + the per-namespace map)',
+            'GET|POST /list-namespaces',
+            'POST|DELETE /delete-namespace/{namespace}',
+            'OPTIONS (CORS preflight)',
+        ],
+    };
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@volter/twin-upstashvector",
+  "version": "0.1.0",
+  "description": "Local Upstash Vector (REST API) twin: a real stateful vector index served over Upstash Vector's per-index REST protocol — POST /upsert, /query, /fetch, /range, /delete, /update, /reset, /info, /list-namespaces, /delete-namespace, each with its /{namespace} path form — with Bearer-token auth, the {result}/{error,status} envelope, and REAL similarity math (cosine/euclidean/dot-product scores computed from the stored vectors and normalized with Upstash's own published formulas, never faked) plus a real metadata-filter parser/evaluator. Built on @volter/world-core.",
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/upstashvector"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/upstashvector#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-upstashvector": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "@upstash/vector": "1.2.3",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,47 @@
+#!/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.ts';
+import { SIMILARITY_FUNCTIONS, type SimilarityFunction } from './upstashvector-store.ts';
+
+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 as readonly string[]).includes(similarityRaw.toUpperCase())) {
+  process.stderr.write(`--similarity must be one of ${SIMILARITY_FUNCTIONS.join(', ')}\n`);
+  process.exit(1);
+}
+const similarityFunction = similarityRaw?.toUpperCase() as SimilarityFunction | undefined;
+
+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.ts');
+  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/src/index.ts

@@ -0,0 +1,193 @@
+// @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.ts';
+export type {
+  UpstashVectorRequest,
+  UpstashVectorResponse,
+  UpstashVectorRoute,
+  UpstashVectorCommand,
+  UpstashVectorTwinSnapshot,
+} from './upstashvector-twin.ts';
+
+// 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.ts';
+export type {
+  SimilarityFunction,
+  VectorContext,
+  VectorRow,
+  UpstashVectorResourceType,
+} from './upstashvector-store.ts';
+
+// 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.ts';
+export type { FilterNode, FilterValue, ComparisonOp, Token, TokenKind } from './upstashvector-filter.ts';
+
+export { createUpstashVectorTwinFetch, createUpstashVectorTwinServer } from './upstashvector-server.ts';
+export type { UpstashVectorServerOptions, UpstashVectorTwinFetchOptions } from './upstashvector-server.ts';
+
+export {
+  mapVector,
+  mapNamespace,
+  pullUpstashVectorRange,
+  pullUpstashVectorNamespaces,
+  syncUpstashVectorFromReal,
+} from './upstashvector-connector.ts';
+export type {
+  UpstashVectorLikeClient,
+  UpstashVectorRealVector,
+  UpstashVectorBudgetedOptions,
+} from './upstashvector-connector.ts';
+
+// 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.ts';
+export type {
+  UpstashVectorBudgetErrorKind,
+  UpstashVectorBudgetOptions,
+  UpstashVectorBudgetReservation,
+  UpstashVectorBudgetSnapshot,
+} from './upstashvector-budget.ts';
+
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import { registerPack, type TwinPack } from '@volter/world-core';
+import { performUpstashVectorAction, syncUpstashVectorFromRemote } from './upstashvector-connector.ts';
+import { UPSTASHVECTOR_RATE_BUDGET as RATE_BUDGET } from './upstashvector-budget.ts';
+export const pack: TwinPack = {
+  // 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);