@volter/twin-upstashvector 0.1.0

package/dist/src/upstashvector-capabilities.js

@@ -0,0 +1,1108 @@
+// upstashvector capability manifest — the EXPECTED REAL-PRODUCT SURFACE (the target), authored
+// top-down from what the Upstash Vector REST API actually does, NOT from what this twin has built.
+//
+// GROUNDED (2026-08-19), all read-only — see spec-sources.json:
+//   (a) upstash.com/docs/vector/api/endpoints/{upsert,query,fetch,range,delete,reset,info} and
+//       upstash.com/docs/vector/api/get-started (the status-code table);
+//   (b) upstash.com/docs/vector/features/{namespaces,filtering,similarityfunctions,metadata,
+//       sparseindexes,embeddingmodels,resumablequery};
+//   (c) the ACTUALLY-INSTALLED `@upstash/vector@1.2.3` package source (its HttpClient and every
+//       Command's endpoint construction), which is where the SDK-shaped facts come from: every
+//       call is a POST, namespaces are a path suffix, `reset({all:true})` is `reset?all`, and
+//       `queryMany` posts an ARRAY to `/query` whose single-element form answers FLAT.
+// The DENOMINATOR is enumerated from the vendor's own docs nav — every REST endpoint crossed with
+// every documented feature (namespaces, filtering, metadata, similarity functions, sparse/hybrid
+// indexes, embedding models, resumable queries, plan limits) — so whole features this twin has NOT
+// built (sparse/hybrid, embedding models, resumable queries) appear as `todo`s rather than being
+// quietly left out of the count.
+//
+// `verify()` (required to count as done) is ground truth: every API verify drives the REAL
+// `handleUpstashVectorTwinRequest` over a FRESH temp root with a PINNED clock, and asserts VALUES —
+// never a bare status code. Nothing here is a mock.
+//
+// ── WHAT THIS PACK COULD NOT GROUND, STATED PLAINLY ───────────────────────────────────────────
+// Its sibling `upstash` live-probed a real ephemeral database for every literal error string.
+// This build had NO live Upstash Vector index, so it could not do the same. Exactly one error
+// message here is quoted verbatim from the vendor's own docs — the dimension mismatch
+// (`Invalid vector dimension: N, expected: M`, from the /upsert endpoint's 422 example) — and its
+// capability says so. Every other error capability asserts the STATUS and the documented
+// `{error,status}` ENVELOPE, which ARE grounded, and does not claim a vendor wording this pack
+// never read. Capabilities whose titles would require an unverified vendor string are `todo`.
+//
+// (Upstash Vector is an API-first vendor — docs/contributing/architecture.md C1b: an integrator CALLS this product
+// from code and the Upstash console is a provisioning/metrics dashboard, not where the work
+// happens — so this pack ships NO mirror and there are no UI capabilities. Same call as the
+// sibling upstash pack, and as pinecone, the other vector-database pack in this repo.
+// See README ## Coverage § No UI mirror.)
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { applyTwinWrite } from '@volter/world-core';
+import { checkCapabilities, verifyBoundary } from '@volter/world-tooling';
+import { handleUpstashVectorTwinRequest } from "./upstashvector-twin.js";
+import { checkUpstashVectorConformance } from "./upstashvector-conformance.js";
+import { cosineSimilarity, dotProduct, squaredDistance, similarityScore, IndexSpace, VectorApiError } from "./upstashvector-store.js";
+import { syncUpstashVectorFromReal, pullUpstashVectorRange, pullUpstashVectorNamespaces, mapVector, mapNamespace, } from "./upstashvector-connector.js";
+import { UpstashVectorBudget, guardUpstashVectorClient, upstashvectorCallWeight, UPSTASHVECTOR_BUDGET_CEILING } from "./upstashvector-budget.js";
+/** The pinned clock every verify runs against, so ids and actions are deterministic. */
+const AT = '2026-01-01T00:00:00.000Z';
+const AT_MS = Date.parse(AT);
+/** A later instant, for verifies that need the clock to ADVANCE (repeated identical writes). */
+const laterAt = (ms) => new Date(AT_MS + ms).toISOString();
+const AUTH = { authorization: 'Bearer twin-capability-token' };
+async function withRoot(steps, setup = {}) {
+    const root = mkdtempSync(join(tmpdir(), 'upstashvector-cap-'));
+    const raw = (req) => handleUpstashVectorTwinRequest({
+        method: req.method ?? 'POST',
+        path: req.path ?? '/info',
+        root,
+        occurredAt: req.at ?? AT,
+        headers: req.headers === undefined ? AUTH : req.headers,
+        ...(req.body !== undefined ? { body: req.body } : {}),
+        ...(req.readOnly !== undefined ? { readOnly: req.readOnly } : {}),
+        ...(req.token !== undefined ? { token: req.token } : {}),
+        // Per-request overrides win over the withRoot-level index configuration. Parenthesised
+        // deliberately: `...A ?? B !== undefined ? X : {}` is legal but reads as the wrong grouping.
+        ...((req.dimension ?? setup.dimension) !== undefined ? { dimension: (req.dimension ?? setup.dimension) } : {}),
+        ...((req.similarityFunction ?? setup.similarityFunction) !== undefined ? { similarityFunction: (req.similarityFunction ?? setup.similarityFunction) } : {}),
+    });
+    const run = (async (command, body, opts = {}) => {
+        const path = `/${command}${opts.ns !== undefined && opts.ns !== '' ? `/${encodeURIComponent(opts.ns)}` : ''}${opts.query ?? ''}`;
+        const res = await raw({
+            path,
+            ...(opts.method !== undefined ? { method: opts.method } : {}),
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+            ...(opts.at !== undefined ? { at: opts.at } : {}),
+            ...(opts.headers !== undefined ? { headers: opts.headers } : {}),
+        });
+        const b = (res.body ?? {});
+        return { status: res.status, result: b.result, error: b.error, errorStatus: b.status };
+    });
+    run.raw = raw;
+    run.root = root;
+    try {
+        return await verifyBoundary('upstashvector.withRoot', () => steps(run, root));
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+/** A counting fake Upstash Vector client for the connector/budget verifies. */
+function fakeVectorClient(pages) {
+    const calls = [];
+    const client = {
+        info: async () => { calls.push('info'); return { vectorCount: Object.values(pages).flat().length }; },
+        listNamespaces: async () => { calls.push('listNamespaces'); return Object.keys(pages); },
+        range: async (args, opts) => {
+            calls.push(`range:${opts?.namespace ?? ''}`);
+            const all = pages[opts?.namespace ?? ''] ?? [];
+            const start = args.cursor === '' ? 0 : Number(args.cursor);
+            const page = all.slice(start, start + args.limit);
+            const next = start + page.length;
+            return { nextCursor: next >= all.length ? '' : String(next), vectors: page };
+        },
+    };
+    return { client, calls };
+}
+/** Round a float for comparison against a hand-computed expectation. */
+const near = (a, b, eps = 1e-9) => typeof a === 'number' && Math.abs(a - b) < eps;
+const done = (id, area, title, dimension, tier, verify) => ({ id, area, title, dimension, tier, expected: 'done', verify });
+const todo = (id, area, title, dimension, tier) => ({ id, area, title, dimension, tier, expected: 'todo' });
+export const UPSTASHVECTOR_CAPABILITIES = [
+    // ── PROTOCOL ────────────────────────────────────────────────────────────────────────────────
+    done('upstashvector.protocol.result_envelope', 'protocol', 'every success answers HTTP 200 with the vendor\'s {"result": …} envelope, whose payload TYPE is per-endpoint — a string for /upsert and /reset, an array for /query and /fetch, an object for /info and /range (all six asserted)', 'api', 'core', () => withRoot(async (r) => {
+        // All SIX payload types the title enumerates, not a sample of three (§9 round 1).
+        const up = await r('upsert', { id: 'a', vector: [1, 0] });
+        const q = await r('query', { vector: [1, 0], topK: 1 });
+        const fetched = await r('fetch', { ids: ['a'] });
+        const info = await r('info', undefined, { method: 'GET' });
+        const page = await r('range', { cursor: '', limit: 10 });
+        const reset = await r('reset', undefined, { at: laterAt(1000) });
+        const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+        return up.status === 200 && up.result === 'Success' && up.error === undefined
+            && reset.status === 200 && reset.result === 'Success'
+            && q.status === 200 && Array.isArray(q.result) && q.result.length === 1
+            && fetched.status === 200 && Array.isArray(fetched.result) && fetched.result.length === 1
+            && info.status === 200 && isPlainObject(info.result)
+            && page.status === 200 && isPlainObject(page.result)
+            && Array.isArray(page.result.vectors);
+    })),
+    done('upstashvector.protocol.error_envelope', 'protocol', 'every failure answers the vendor\'s {"error": …, "status": N} envelope with `status` EQUAL to the HTTP status (the shape the /upsert doc\'s own 422 example shows)', 'api', 'core', () => withRoot(async (r) => {
+        await r('upsert', { id: 'a', vector: [1, 0] });
+        const bad = await r('upsert', { id: 'b', vector: [1, 0, 0] });
+        const missing = await r('nosuchendpoint', {});
+        return bad.status === 422 && bad.errorStatus === 422 && typeof bad.error === 'string' && bad.result === undefined
+            && missing.status === 404 && missing.errorStatus === 404 && typeof missing.error === 'string';
+    })),
+    done('upstashvector.protocol.namespace_is_a_path_suffix', 'protocol', 'the namespace is a PATH SUFFIX (`POST /query/ns`), never a body field — so `/upsert/a` and `/upsert/b` are genuinely isolated stores and a body `namespace` key is NOT honoured', 'api', 'core', () => withRoot(async (r) => {
+        await r('upsert', { id: 'x', vector: [1, 0] }, { ns: 'team-a' });
+        await r('upsert', { id: 'y', vector: [0, 1] }, { ns: 'team-b' });
+        // A body-level `namespace` must be ignored: honouring it would let a caller escape the path.
+        await r('upsert', { id: 'z', vector: [1, 1], namespace: 'team-a' });
+        const a = await r('range', { cursor: '', limit: 10 }, { ns: 'team-a' });
+        const b = await r('range', { cursor: '', limit: 10 }, { ns: 'team-b' });
+        const dflt = await r('range', { cursor: '', limit: 10 });
+        const ids = (x) => (x.result.vectors).map((v) => v.id);
+        return JSON.stringify(ids(a)) === JSON.stringify(['x'])
+            && JSON.stringify(ids(b)) === JSON.stringify(['y'])
+            && JSON.stringify(ids(dflt)) === JSON.stringify(['z']);
+    })),
+    done('upstashvector.protocol.post_and_documented_method_both_work', 'protocol', '/reset and /delete-namespace accept BOTH the DELETE their own doc pages spell and the POST the real SDK actually sends (@upstash/vector\'s HttpClient hardcodes method:"POST", so a DELETE-only twin would 405 every real client — while get-started\'s allow-list omits DELETE entirely, so accepting both is the only way to satisfy every documented caller)', 'api', 'core', () => withRoot(async (r) => {
+        await r('upsert', { id: 'a', vector: [1, 0] }, { ns: 'n1' });
+        await r('upsert', { id: 'b', vector: [1, 0] }, { ns: 'n2' });
+        const postDelete = await r('delete-namespace', undefined, { ns: 'n1', method: 'POST' });
+        const httpDelete = await r('delete-namespace', undefined, { ns: 'n2', method: 'DELETE' });
+        const resetPost = await r('reset', undefined, { method: 'POST' });
+        const resetDelete = await r('reset', undefined, { method: 'DELETE' });
+        const names = await r('list-namespaces', undefined, { method: 'GET' });
+        return postDelete.result === 'Success' && httpDelete.result === 'Success'
+            && resetPost.result === 'Success' && resetDelete.result === 'Success'
+            && JSON.stringify(names.result) === JSON.stringify(['']);
+    })),
+    done('upstashvector.protocol.unknown_endpoint_404', 'protocol', 'a path that is not an Upstash Vector endpoint answers 404 — never a fabricated 200', 'api', 'core', () => withRoot(async (r) => {
+        const bogus = await r('totally-made-up', {});
+        const rootPath = await r.raw({ path: '/' });
+        return bogus.status === 404 && bogus.errorStatus === 404
+            && rootPath.status === 404 && rootPath.body.status === 404;
+    })),
+    done('upstashvector.protocol.unmodeled_endpoint_fails_naming_the_gap', 'protocol', 'a REAL vendor endpoint this twin has not built (/upsert-data, /query-data, /resumable-query*) answers 404 NAMING the manifest gap that tracks it — the unmodeled-ops-fail-like-the-vendor rule, made checkable', 'api', 'core', () => withRoot(async (r) => {
+        const upsertData = await r('upsert-data', { id: 'a', data: 'hello' });
+        const queryData = await r('query-data', { data: 'hello', topK: 1 });
+        const resumable = await r('resumable-query', { vector: [1, 0], topK: 1, maxIdle: 10 });
+        return upsertData.status === 404 && (upsertData.error ?? '').includes('upstashvector.embedding.upsert_data')
+            && queryData.status === 404 && (queryData.error ?? '').includes('upstashvector.embedding.query_data')
+            && resumable.status === 404 && (resumable.error ?? '').includes('upstashvector.resumable.start');
+    })),
+    done('upstashvector.protocol.method_not_allowed_405', 'protocol', 'an HTTP method outside {GET,POST,PUT,HEAD,DELETE,OPTIONS} answers 405. NB the vendor\'s docs CONTRADICT themselves: get-started says verbatim "Only HEAD, GET, POST, and PUT methods are allowed", yet the /reset and /delete-namespace pages document `-X DELETE`. This twin accepts DELETE — the permissive direction, so neither documented caller is refused', 'api', 'niche', () => withRoot(async (r) => {
+        const patch = await r.raw({ method: 'PATCH', path: '/info' });
+        return patch.status === 405 && patch.body.status === 405;
+    })),
+    done('upstashvector.protocol.cors_preflight', 'protocol', 'OPTIONS is a CORS preflight answering 200 with an EMPTY body and the echoed origin — and it is answered BEFORE auth, since a browser preflight carries no Authorization header by definition', 'api', 'niche', () => withRoot(async (r) => {
+        const preflight = await r.raw({ method: 'OPTIONS', path: '/query', headers: { origin: 'https://app.example.test', 'access-control-request-headers': 'authorization' } });
+        return preflight.status === 200 && preflight.body === null
+            && preflight.headers?.['access-control-allow-origin'] === 'https://app.example.test'
+            && preflight.headers?.['access-control-allow-headers'] === 'authorization';
+    })),
+    done('upstashvector.protocol.malformed_body_400', 'protocol', 'a missing or non-JSON request body answers 400 with the error envelope, never a 200 with an empty result', 'api', 'common', () => withRoot(async (r) => {
+        const empty = await r.raw({ path: '/query', body: '' });
+        const garbage = await r.raw({ path: '/query', body: '{not json' });
+        return empty.status === 400 && empty.body.status === 400
+            && garbage.status === 400 && garbage.body.status === 400;
+    })),
+    done('upstashvector.protocol.safe_methods_never_mutate', 'protocol', 'HEAD answers 200 with no body at all on a READ, and — because RFC 9110 defines both HEAD and GET as SAFE methods — neither can ever mutate: HEAD or GET against /upsert, /delete or /reset is refused 405 and changes nothing. (§9 round 1 found the opposite: HEAD ran the command and committed the write, then suppressed the body, so `HEAD /reset` silently emptied the index behind a read-shaped 200.)', 'api', 'common', () => withRoot(async (r) => {
+        await r('upsert', [{ id: 'a', vector: [1, 0] }, { id: 'b', vector: [0, 1] }]);
+        const head = await r.raw({ method: 'HEAD', path: '/info' });
+        const get = await r.raw({ method: 'GET', path: '/info' });
+        const headReset = await r.raw({ method: 'HEAD', path: '/reset', body: '{}' });
+        const headDelete = await r.raw({ method: 'HEAD', path: '/delete', body: JSON.stringify({ ids: ['a'] }) });
+        const headUpsert = await r.raw({ method: 'HEAD', path: '/upsert', body: JSON.stringify({ id: 'sneaky', vector: [1, 1] }) });
+        // …and GET, which caches/prefetchers/crawlers issue freely.
+        const getReset = await r.raw({ method: 'GET', path: '/reset' });
+        const getDelete = await r.raw({ method: 'GET', path: '/delete', body: JSON.stringify({ ids: ['a'] }) });
+        const after = await r('info', undefined, { method: 'GET' });
+        return head.status === 200 && head.body === null
+            && get.status === 200 && get.body.result !== undefined
+            && headReset.status === 405 && headDelete.status === 405 && headUpsert.status === 405
+            && getReset.status === 405 && getDelete.status === 405
+            // THE POINT: the index is untouched by every one of them.
+            && after.result.vectorCount === 2;
+    })),
+    done('upstashvector.filtering.malformed_path_is_a_parse_error', 'filtering', 'a malformed metadata PATH (an unterminated `[` subscript, a non-integer index) is rejected at PARSE time with a 400, so the answer never depends on how much data happens to be stored. (§9 round 1: these parsed fine and only failed inside the evaluator, so the SAME filter answered an internal 500 against a populated namespace and a silent 200 [] against an empty one.)', 'api', 'core', () => withRoot(async (r) => {
+        const bad = ['a[0 = 1', 'HAS FIELD a[', "tags[x] = 'v'", 'a[] = 1'];
+        const empties = [];
+        const populated = [];
+        // FIRST against an EMPTY namespace…
+        for (const filter of bad)
+            empties.push((await r('query', { vector: [1, 0], topK: 5, filter })).status);
+        await r('upsert', { id: 'a', vector: [1, 0], metadata: { tags: ['x'] } });
+        // …then against a POPULATED one. The two must agree.
+        for (const filter of bad)
+            populated.push((await r('query', { vector: [1, 0], topK: 5, filter })).status);
+        // …and the delete path must agree too, without removing anything.
+        const del = await r('delete', { filter: 'a[0 = 1' }, { at: laterAt(1000) });
+        const survived = await r('info', undefined, { method: 'GET' });
+        return empties.every((s) => s === 400) && populated.every((s) => s === 400)
+            && JSON.stringify(empties) === JSON.stringify(populated)
+            && del.status === 400
+            && survived.result.vectorCount === 1;
+    })),
+    // ── AUTH ────────────────────────────────────────────────────────────────────────────────────
+    done('upstashvector.auth.missing_token_401', 'auth', 'a missing credential answers HTTP 401 with the vendor\'s VERBATIM published body \u2014 {"error": "Unauthorized: Invalid auth token", "status": 401} \u2014 quoted from upstash.com/docs/vector/api/get-started\'s own error example (note the capital I in "Invalid"). One of the two strings in this pack taken word-for-word from the vendor, alongside the dimension-mismatch 422', 'api', 'core', () => withRoot(async (r) => {
+        const none = await r.raw({ path: '/info', method: 'GET', headers: {} });
+        const wrong = await r.raw({ path: '/info', method: 'GET', token: 'the-real-one', headers: { authorization: 'Bearer nope' } });
+        // Assert the string EXACTLY. §9 round 2 sabotaged this constant to
+        // 'totally wrong sabotaged string' and the whole suite still passed, because the verify only
+        // checked `typeof error === 'string'` — a claimed-verbatim vendor body that nothing pinned.
+        // A byte-for-byte assertion is the only thing that makes "verbatim" mean anything.
+        const expected = 'Unauthorized: Invalid auth token';
+        return none.status === 401 && none.body.status === 401
+            && none.body.error === expected
+            && none.body.result === undefined
+            // The vendor draws no distinction between missing and wrong: same status, same body.
+            && wrong.status === 401 && wrong.body.error === expected;
+    })),
+    done('upstashvector.auth.empty_bearer_is_unauthorized', 'auth', 'the header `Authorization: Bearer ` (the scheme with an EMPTY token) is 401, not authenticated as the literal string "Bearer" — the parsing trap a `/^bearer\\s+(.*)$/` pattern walks straight into', 'api', 'common', () => withRoot(async (r) => {
+        const blank = await r.raw({ path: '/info', method: 'GET', headers: { authorization: 'Bearer ' } });
+        const bareWord = await r.raw({ path: '/info', method: 'GET', headers: { authorization: 'Bearer' } });
+        const ok = await r.raw({ path: '/info', method: 'GET', headers: { authorization: 'Bearer real-token' } });
+        return blank.status === 401 && bareWord.status === 401 && ok.status === 200;
+    })),
+    done('upstashvector.auth.exact_token_enforced', 'auth', 'when the twin is started WITH a token, only that exact credential is accepted and any other is 401 — so a world can prove its app is sending the credential it thinks it is', 'api', 'common', () => withRoot(async (r) => {
+        const right = await r.raw({ path: '/info', method: 'GET', token: 'secret-abc', headers: { authorization: 'Bearer secret-abc' } });
+        const wrong = await r.raw({ path: '/info', method: 'GET', token: 'secret-abc', headers: { authorization: 'Bearer secret-xyz' } });
+        return right.status === 200 && wrong.status === 401;
+    })),
+    done('upstashvector.auth.bare_authorization_header', 'auth', 'a bare `Authorization: <token>` without the Bearer scheme is accepted and drives the FULL surface (a vector upserted under a bare header is readable under one), matching the sibling Upstash REST surface\'s probed tolerance — while a bare header carrying only whitespace is still 401', 'api', 'niche', () => withRoot(async (r) => {
+        const bare = { authorization: 'plain-token' };
+        // Assert VALUES through the bare-auth path, not just a status: a status-only check here
+        // survives a dead handler (§9 / the mutation gate caught exactly that).
+        const wrote = await r.raw({ path: '/upsert', body: JSON.stringify({ id: 'bare', vector: [0.25, 0.75], metadata: { via: 'bare-auth' } }), headers: bare });
+        const read = await r.raw({ path: '/fetch', body: JSON.stringify({ ids: ['bare'], includeMetadata: true, includeVectors: true }), headers: bare });
+        const rows = read.body.result ?? [];
+        const blank = await r.raw({ path: '/info', method: 'GET', headers: { authorization: '   ' } });
+        return wrote.body.result === 'Success'
+            && rows.length === 1 && rows[0].id === 'bare'
+            && JSON.stringify(rows[0].vector) === JSON.stringify([0.25, 0.75])
+            && JSON.stringify(rows[0].metadata) === JSON.stringify({ via: 'bare-auth' })
+            && blank.status === 401;
+    })),
+    // ── UPSERT ──────────────────────────────────────────────────────────────────────────────────
+    done('upstashvector.upsert.single_and_batch', 'upsert', 'POST /upsert accepts EITHER one vector object or an array of them (both curl forms the vendor documents), and every element becomes queryable state', 'api', 'core', () => withRoot(async (r) => {
+        const one = await r('upsert', { id: 'solo', vector: [1, 0] });
+        const many = await r('upsert', [{ id: 'a', vector: [0, 1] }, { id: 'b', vector: [1, 1] }]);
+        const page = await r('range', { cursor: '', limit: 10 });
+        const ids = (page.result.vectors).map((v) => v.id);
+        return one.result === 'Success' && many.result === 'Success' && JSON.stringify(ids) === JSON.stringify(['a', 'b', 'solo']);
+    })),
+    done('upstashvector.upsert.replaces_rather_than_merges', 'upsert', 're-upserting an existing id REPLACES the whole vector — an upsert without `metadata` CLEARS the metadata the id previously had. (The vendor\'s upsert page does NOT state replace-vs-merge; that it ships a separate /update endpoint carrying a metadataUpdateMode is the INFERENCE this models, not a documented fact. What is asserted here is the twin behaviour.)', 'api', 'core', () => withRoot(async (r) => {
+        await r('upsert', { id: 'a', vector: [1, 0], metadata: { colour: 'red' }, data: 'first' });
+        const before = await r('fetch', { ids: ['a'], includeMetadata: true, includeData: true });
+        await r('upsert', { id: 'a', vector: [0, 1] }, { at: laterAt(1000) });
+        const after = await r('fetch', { ids: ['a'], includeMetadata: true, includeData: true, includeVectors: true });
+        const b0 = before.result[0];
+        const a0 = after.result[0];
+        return JSON.stringify(b0.metadata) === JSON.stringify({ colour: 'red' }) && b0.data === 'first'
+            && a0.metadata === undefined && a0.data === undefined
+            && JSON.stringify(a0.vector) === JSON.stringify([0, 1]);
+    })),
+    done('upstashvector.upsert.dimension_locked_and_enforced', 'upsert', 'the index enforces ONE dimension: the first upsert locks it in and a later mismatch is refused with HTTP 422 and the vendor\'s VERBATIM message "Invalid vector dimension: N, expected: M" (the only error string in this pack quoted from Upstash\'s own docs — the /upsert endpoint\'s 422 example)', 'api', 'core', () => withRoot(async (r) => {
+        await r('upsert', { id: 'a', vector: [0.1, 0.2] });
+        const bad = await r('upsert', { id: 'b', vector: [0.1, 0.2, 0.3] });
+        const stillOne = await r('range', { cursor: '', limit: 10 });
+        return bad.status === 422 && bad.error === 'Invalid vector dimension: 3, expected: 2'
+            && (stillOne.result.vectors).length === 1;
+    })),
+    done('upstashvector.upsert.dimension_configured_at_creation', 'upsert', 'a twin started with an explicit `dimension` enforces it from the very FIRST upsert (matching a real index, whose dimension is fixed at creation) rather than adopting whatever arrived first', 'api', 'common', () => withRoot(async (r) => {
+        const bad = await r('upsert', { id: 'a', vector: [1, 0] });
+        const good = await r('upsert', { id: 'b', vector: [1, 0, 0, 0] });
+        return bad.status === 422 && bad.error === 'Invalid vector dimension: 2, expected: 4' && good.result === 'Success';
+    }, { dimension: 4 })),
+    done('upstashvector.upsert.batch_is_validated_atomically', 'upsert', 'one bad element refuses the WHOLE batch before anything is written — a partially-applied upsert would leave state the caller never asked for', 'api', 'common', () => withRoot(async (r) => {
+        await r('upsert', { id: 'seed', vector: [1, 0] });
+        const batch = await r('upsert', [{ id: 'ok1', vector: [0, 1] }, { id: 'bad', vector: [0, 1, 2] }], { at: laterAt(1000) });
+        const page = await r('range', { cursor: '', limit: 10 });
+        const ids = (page.result.vectors).map((v) => v.id);
+        return batch.status === 422 && JSON.stringify(ids) === JSON.stringify(['seed']);
+    })),
+    done('upstashvector.upsert.rejects_malformed_elements', 'upsert', 'a missing `vector`, an empty/absent id, a non-array vector and a non-finite coordinate are each refused at the boundary (a NaN coordinate would poison every score it touched and JSON-serialise to null)', 'api', 'common', () => withRoot(async (r) => {
+        const noVector = await r('upsert', { id: 'a' });
+        const noId = await r('upsert', { vector: [1, 0] });
+        const emptyId = await r('upsert', { id: '', vector: [1, 0] });
+        const notArray = await r('upsert', { id: 'a', vector: 'nope' });
+        const nan = await r('upsert', { id: 'a', vector: [1, null] });
+        const page = await r('range', { cursor: '', limit: 10 });
+        return [noVector, noId, emptyId, notArray, nan].every((x) => x.status === 400 && x.result === undefined)
+            && (page.result.vectors).length === 0;
+    })),
+    done('upstashvector.upsert.numeric_ids_accepted', 'upsert', 'a JSON-number id is accepted and carried as its string form (the SDK types ids as `number|string`), so `fetch([123])` finds what `upsert({id:123})` wrote', 'api', 'niche', () => withRoot(async (r) => {
+        await r('upsert', { id: 123, vector: [1, 0] });
+        const got = await r('fetch', { ids: [123] });
+        const alsoString = await r('fetch', { ids: ['123'] });
+        return got.result[0]?.id === '123'
+            && alsoString.result[0]?.id === '123';
+    })),
+    done('upstashvector.upsert.data_alongside_a_vector', 'upsert', '`data` may accompany an explicit `vector` (the SDK\'s "Upsert data alongside with your embedding" form) and round-trips through includeData — it is only `data` WITHOUT a vector that needs an embedding model', 'api', 'common', () => withRoot(async (r) => {
+        const ok = await r('upsert', { id: 'tokyo', vector: [1, 0], data: 'Tokyo is the capital of Japan.' });
+        const got = await r('fetch', { ids: ['tokyo'], includeData: true });
+        return ok.result === 'Success' && got.result[0]?.data === 'Tokyo is the capital of Japan.';
+    })),
+    done('upstashvector.upsert.sparse_vector_refused_not_ignored', 'upsert', 'a `sparseVector` payload is REFUSED with 422 rather than silently dropped — accepting it while ignoring it would make a hybrid-index caller\'s recall look fine while half their signal vanished', 'api', 'common', () => withRoot(async (r) => {
+        const sparse = await r('upsert', { id: 'a', vector: [1, 0], sparseVector: { indices: [2, 3], values: [0.1, 0.9] } });
+        return sparse.status === 422 && (sparse.error ?? '').includes('upstashvector.sparse.upsert');
+    })),
+    // ── SCORING (the claim this pack stands on) ─────────────────────────────────────────────────
+    done('upstashvector.scoring.cosine_formula', 'scoring', 'COSINE scores are computed from the stored coordinates with Upstash\'s published normalization "(1 + cosine_similarity(v1, v2)) / 2" — checked against hand-computed values, including the identical-vector score of exactly 1 and the orthogonal score of exactly 0.5', 'api', 'core', () => withRoot(async (r) => {
+        await r('upsert', [
+            { id: 'same', vector: [1, 0] },
+            { id: 'orthogonal', vector: [0, 1] },
+            { id: 'opposite', vector: [-1, 0] },
+        ]);
+        const q = await r('query', { vector: [1, 0], topK: 3 });
+        const rows = q.result;
+        const byId = Object.fromEntries(rows.map((x) => [x.id, x.score]));
+        // cos(same)=1 → 1 ; cos(orthogonal)=0 → 0.5 ; cos(opposite)=-1 → 0
+        return rows.length === 3 && near(byId.same, 1) && near(byId.orthogonal, 0.5) && near(byId.opposite, 0)
+            && near(similarityScore('COSINE', [1, 0], [0, 1]), 0.5)
+            && near(cosineSimilarity([3, 4], [3, 4]), 1);
+    }, { similarityFunction: 'COSINE' })),
+    done('upstashvector.scoring.euclidean_formula', 'scoring', 'EUCLIDEAN scores use the published "1 / (1 + squared_distance(v1, v2))" — so an exact match scores 1 and a squared distance of 3 scores exactly 0.25, both checked against the arithmetic', 'api', 'core', () => withRoot(async (r) => {
+        await r('upsert', [{ id: 'exact', vector: [1, 2] }, { id: 'far', vector: [2, 3] }]);
+        const q = await r('query', { vector: [1, 2], topK: 2 });
+        const rows = q.result;
+        // squared_distance([1,2],[2,3]) = 1+1 = 2 → 1/(1+2) = 1/3
+        return rows[0].id === 'exact' && near(rows[0].score, 1)
+            && rows[1].id === 'far' && near(rows[1].score, 1 / 3)
+            && squaredDistance([0, 0], [1, 1]) === 2
+            && near(similarityScore('EUCLIDEAN', [0, 0, 0], [1, 1, 1]), 0.25);
+    }, { similarityFunction: 'EUCLIDEAN' })),
+    done('upstashvector.scoring.dot_product_formula', 'scoring', 'DOT_PRODUCT applies the published "(1 + dot_product(v1, v2)) / 2" LITERALLY, including to non-unit vectors — so magnitude affects the score and a longer parallel vector outranks a shorter one where COSINE would tie them. NB the vendor says dot-product vectors "need to be normalized to be of unit length" and that scores are "between 0 and 1"; this twin does not silently normalize for you, so a non-unit input can exceed 1. Whether the real index clamps, normalizes, or returns the same value is UNVERIFIED (no live index to probe) — what is asserted here is the twin arithmetic', 'api', 'core', () => withRoot(async (r) => {
+        await r('upsert', [{ id: 'short', vector: [1, 0] }, { id: 'long', vector: [3, 0] }]);
+        const q = await r('query', { vector: [1, 0], topK: 2 });
+        const rows = q.result;
+        // dot([1,0],[3,0])=3 → 2 ; dot([1,0],[1,0])=1 → 1. Under COSINE these two would TIE at 1.
+        return rows[0].id === 'long' && near(rows[0].score, 2)
+            && rows[1].id === 'short' && near(rows[1].score, 1)
+            && dotProduct([1, 2, 3], [4, 5, 6]) === 32;
+    }, { similarityFunction: 'DOT_PRODUCT' })),
+    done('upstashvector.scoring.metric_changes_the_ranking', 'scoring', 'the configured metric genuinely drives the ORDER, not just the number: the same three vectors and the same query rank differently under COSINE than under DOT_PRODUCT — proof the score is computed rather than stored', 'api', 'core', async () => {
+        const rank = async (fn) => {
+            let out = [];
+            await withRoot(async (r) => {
+                await r('upsert', [{ id: 'unit', vector: [1, 0] }, { id: 'big', vector: [5, 0] }, { id: 'diag', vector: [1, 1] }]);
+                const q = await r('query', { vector: [1, 0], topK: 3 });
+                out = q.result.map((x) => x.id);
+                return true;
+            }, { similarityFunction: fn });
+            return out;
+        };
+        const cos = await rank('COSINE');
+        const dot = await rank('DOT_PRODUCT');
+        // COSINE: unit and big are both exactly parallel to the query (score 1) so they tie and the id
+        // tie-break puts 'big' first; diag is at 45° (score ~0.854) and comes last.
+        // DOT_PRODUCT: big (5) > unit (1) = diag (1), so 'big' leads by a real margin.
+        return JSON.stringify(cos) === JSON.stringify(['big', 'unit', 'diag'])
+            && JSON.stringify(dot) === JSON.stringify(['big', 'diag', 'unit']);
+    }),
+    done('upstashvector.scoring.deterministic_tie_break', 'scoring', 'vectors with EQUAL scores come back in a stable id-ascending order, so a ranking is reproducible run to run (the vendor does not specify a tie-break; this one is the twin\'s, and it is documented as such)', 'api', 'common', () => withRoot(async (r) => {
+        await r('upsert', [{ id: 'zzz', vector: [1, 0] }, { id: 'aaa', vector: [1, 0] }, { id: 'mmm', vector: [1, 0] }]);
+        const first = await r('query', { vector: [1, 0], topK: 3 });
+        const second = await r('query', { vector: [1, 0], topK: 3 });
+        const ids = (x) => x.result.map((v) => v.id);
+        return JSON.stringify(ids(first)) === JSON.stringify(['aaa', 'mmm', 'zzz'])
+            && JSON.stringify(ids(first)) === JSON.stringify(ids(second));
+    })),
+    done('upstashvector.scoring.every_score_is_a_finite_number', 'scoring', 'a `score` is ALWAYS a finite number — a zero-length vector scores 0.5 under COSINE instead of NaN, and a coordinate too large for the float32 the index stores is refused at the boundary (400) instead of overflowing. Both matter for the same reason: JSON.stringify renders NaN and Infinity as `null`, so the caller would get a result row with a null score, no error anywhere, and a ranking silently degraded to id order because the comparator sees a falsy difference. (§9 round 1 found the overflow half.)', 'api', 'common', () => withRoot(async (r) => {
+        await r('upsert', [{ id: 'zero', vector: [0, 0] }, { id: 'real', vector: [1, 0] }]);
+        const q = await r('query', { vector: [1, 0], topK: 2 });
+        const rows = q.result;
+        // An overflow-scale coordinate is refused rather than stored and discovered at query time.
+        const huge = await r('upsert', { id: 'huge', vector: [1e308, 1e308] });
+        const stillFine = await r('query', { vector: [1, 0], topK: 5 });
+        const after = stillFine.result;
+        return rows.every((x) => typeof x.score === 'number' && Number.isFinite(x.score))
+            && near(rows.find((x) => x.id === 'zero').score, 0.5)
+            && cosineSimilarity([0, 0], [1, 0]) === 0
+            && huge.status === 400 && huge.result === undefined
+            && after.length === 2 && after.every((x) => Number.isFinite(x.score));
+    })),
+    // ── QUERY ───────────────────────────────────────────────────────────────────────────────────
+    done('upstashvector.query.topk_and_default', 'query', 'topK bounds the result count and DEFAULTS to 10 when omitted (the vendor\'s documented default), so an unbounded index does not dump itself into a response', 'api', 'core', () => withRoot(async (r) => {
+        await r('upsert', Array.from({ length: 15 }, (_, i) => ({ id: `v${String(i).padStart(2, '0')}`, vector: [i / 100, 1] })));
+        const explicit = await r('query', { vector: [0, 1], topK: 3 });
+        const defaulted = await r('query', { vector: [0, 1] });
+        return explicit.result.length === 3 && defaulted.result.length === 10;
+    })),
+    done('upstashvector.query.include_flags', 'query', 'includeVectors / includeMetadata / includeData each add exactly their field and are OFF by default — and an absent metadata/data key is OMITTED rather than sent as null (the shape the vendor\'s own fetch example shows)', 'api', 'core', () => withRoot(async (r) => {
+        await r('upsert', { id: 'a', vector: [1, 0], metadata: { k: 'v' }, data: 'text' });
+        await r('upsert', { id: 'b', vector: [1, 0] }, { at: laterAt(10) });
+        const bare = await r('query', { vector: [1, 0], topK: 1 });
+        const full = await r('query', { vector: [1, 0], topK: 2, includeVectors: true, includeMetadata: true, includeData: true });
+        const b0 = bare.result[0];
+        const rows = full.result;
+        const withMeta = rows.find((x) => x.id === 'a');
+        const without = rows.find((x) => x.id === 'b');
+        return b0.vector === undefined && b0.metadata === undefined && b0.data === undefined && typeof b0.score === 'number'
+            && JSON.stringify(withMeta.vector) === JSON.stringify([1, 0])
+            && JSON.stringify(withMeta.metadata) === JSON.stringify({ k: 'v' }) && withMeta.data === 'text'
+            && without.metadata === undefined && without.data === undefined && JSON.stringify(without.vector) === JSON.stringify([1, 0]);
+    })),
+    done('upstashvector.query.query_many_batch', 'query', 'an ARRAY body on /query is `queryMany`: N>1 answers a NESTED array (one result list per query), while a ONE-element batch answers FLAT — the asymmetry the installed SDK\'s QueryManyCommand.exec re-nests, and its own comment documents as real API behaviour', 'api', 'common', () => withRoot(async (r) => {
+        await r('upsert', [{ id: 'a', vector: [1, 0] }, { id: 'b', vector: [0, 1] }]);
+        const two = await r('query', [{ vector: [1, 0], topK: 1 }, { vector: [0, 1], topK: 1 }]);
+        const one = await r('query', [{ vector: [1, 0], topK: 1 }]);
+        const nested = two.result;
+        const flat = one.result;
+        return Array.isArray(nested) && nested.length === 2 && Array.isArray(nested[0])
+            && nested[0][0].id === 'a' && nested[1][0].id === 'b'
+            && Array.isArray(flat) && flat.length === 1 && !Array.isArray(flat[0]) && flat[0].id === 'a';
+    })),
+    done('upstashvector.query.dimension_mismatch_422', 'query', 'a query vector whose length disagrees with the index answers 422 with the vendor\'s verbatim dimension message — the same guard the write path applies, so a mis-sized query fails loudly instead of ranking on a truncated overlap. Holds for any index that HAS a dimension: one upserted into, one configured at construction, or (since the \u00a79 fix) one that was merely PULLED, whose dimension is inferred from the stored vectors when they all agree', 'api', 'common', () => withRoot(async (r) => {
+        await r('upsert', { id: 'a', vector: [1, 0] });
+        const bad = await r('query', { vector: [1, 0, 0], topK: 1 });
+        return bad.status === 422 && bad.error === 'Invalid vector dimension: 3, expected: 2';
+    })),
+    done('upstashvector.query.empty_index_and_missing_vector', 'query', 'a query against an empty index answers an EMPTY array (not an error), while a query with no `vector` at all answers 400 — absence of results and absence of a query are different failures', 'api', 'common', () => withRoot(async (r) => {
+        const empty = await r('query', { vector: [1, 0], topK: 5 });
+        const noVector = await r('query', { topK: 5 });
+        return empty.status === 200 && Array.isArray(empty.result) && empty.result.length === 0
+            && noVector.status === 400;
+    })),
+    // ── FETCH ───────────────────────────────────────────────────────────────────────────────────
+    done('upstashvector.fetch.by_ids_is_positional_with_nulls', 'fetch', 'fetch by ids returns an array POSITIONALLY ALIGNED with the request, with `null` where "no such vector exists with the provided id" (the vendor\'s own wording) — so index N of the answer always describes id N of the ask', 'api', 'core', () => withRoot(async (r) => {
+        await r('upsert', [{ id: 'a', vector: [1, 0] }, { id: 'c', vector: [0, 1] }]);
+        const got = await r('fetch', { ids: ['a', 'missing', 'c'] });
+        const rows = got.result;
+        return rows.length === 3 && rows[0]?.id === 'a' && rows[1] === null && rows[2]?.id === 'c';
+    })),
+    done('upstashvector.fetch.by_prefix', 'fetch', 'fetch by `prefix` returns only the matching ids (no nulls), in id order', 'api', 'common', () => withRoot(async (r) => {
+        await r('upsert', [{ id: 'doc-2', vector: [1, 0] }, { id: 'doc-1', vector: [0, 1] }, { id: 'img-1', vector: [1, 1] }]);
+        const got = await r('fetch', { prefix: 'doc-' });
+        const ids = got.result.map((x) => x.id);
+        return JSON.stringify(ids) === JSON.stringify(['doc-1', 'doc-2']);
+    })),
+    done('upstashvector.fetch.include_flags_and_bad_request', 'fetch', 'fetch honours the include flags, and a body with neither `ids` nor `prefix` answers 400 rather than silently returning everything', 'api', 'common', () => withRoot(async (r) => {
+        await r('upsert', { id: 'a', vector: [1, 0], metadata: { n: 1 } });
+        const full = await r('fetch', { ids: ['a'], includeVectors: true, includeMetadata: true });
+        const neither = await r('fetch', {});
+        const row = full.result[0];
+        return JSON.stringify(row.vector) === JSON.stringify([1, 0])
+            && JSON.stringify(row.metadata) === JSON.stringify({ n: 1 })
+            && neither.status === 400;
+    })),
+    // ── RANGE ───────────────────────────────────────────────────────────────────────────────────
+    done('upstashvector.range.pagination_walks_the_whole_index', 'range', 'successive /range calls threaded through `nextCursor` visit every vector exactly once, and the walk terminates with nextCursor "" — the vendor\'s documented end-of-range signal', 'api', 'core', () => withRoot(async (r) => {
+        await r('upsert', Array.from({ length: 5 }, (_, i) => ({ id: `v${i}`, vector: [i, 1] })));
+        const seen = [];
+        let cursor = '';
+        let guard = 0;
+        let last = '';
+        for (; guard < 10; guard++) {
+            const page = await r('range', { cursor, limit: 2 });
+            const body = page.result;
+            seen.push(...body.vectors.map((v) => v.id));
+            last = body.nextCursor;
+            if (body.nextCursor === '')
+                break;
+            cursor = body.nextCursor;
+        }
+        return last === '' && JSON.stringify(seen) === JSON.stringify(['v0', 'v1', 'v2', 'v3', 'v4'])
+            && new Set(seen).size === 5;
+    })),
+    done('upstashvector.range.prefix_and_include_flags', 'range', '/range narrows to a `prefix` and honours the include flags, and an unparseable cursor answers 400 rather than silently restarting the walk from the top', 'api', 'common', () => withRoot(async (r) => {
+        await r('upsert', [{ id: 'a-1', vector: [1, 0], metadata: { t: 'x' } }, { id: 'b-1', vector: [0, 1] }]);
+        const page = await r('range', { cursor: '', limit: 10, prefix: 'a-', includeMetadata: true });
+        const body = page.result;
+        const bogus = await r('range', { cursor: 'not-a-cursor', limit: 10 });
+        return body.vectors.length === 1 && body.vectors[0].id === 'a-1'
+            && JSON.stringify(body.vectors[0].metadata) === JSON.stringify({ t: 'x' })
+            && body.nextCursor === '' && bogus.status === 400;
+    })),
+    // ── UPDATE ──────────────────────────────────────────────────────────────────────────────────
+    done('upstashvector.update.overwrite_is_the_default', 'update', '/update with metadata replaces the metadata object wholesale by default (metadataUpdateMode OVERWRITE) and answers {updated:1}, leaving the vector itself untouched', 'api', 'common', () => withRoot(async (r) => {
+        await r('upsert', { id: 'a', vector: [1, 0], metadata: { colour: 'red', size: 'L' } });
+        const upd = await r('update', { id: 'a', metadata: { colour: 'blue' } }, { at: laterAt(1000) });
+        const got = await r('fetch', { ids: ['a'], includeMetadata: true, includeVectors: true });
+        const row = got.result[0];
+        return JSON.stringify(upd.result) === JSON.stringify({ updated: 1 })
+            && JSON.stringify(row.metadata) === JSON.stringify({ colour: 'blue' })
+            && JSON.stringify(row.vector) === JSON.stringify([1, 0]);
+    })),
+    done('upstashvector.update.patch_mode_merges', 'update', 'metadataUpdateMode PATCH MERGES the supplied keys over the existing metadata instead of replacing it — the behavioural difference that makes the mode worth having', 'api', 'common', () => withRoot(async (r) => {
+        await r('upsert', { id: 'a', vector: [1, 0], metadata: { colour: 'red', size: 'L' } });
+        const upd = await r('update', { id: 'a', metadata: { colour: 'blue' }, metadataUpdateMode: 'PATCH' }, { at: laterAt(1000) });
+        const got = await r('fetch', { ids: ['a'], includeMetadata: true });
+        const meta = got.result[0].metadata;
+        const bogus = await r('update', { id: 'a', metadata: {}, metadataUpdateMode: 'SIDEWAYS' });
+        return JSON.stringify(upd.result) === JSON.stringify({ updated: 1 })
+            && meta.colour === 'blue' && meta.size === 'L' && bogus.status === 400;
+    })),
+    done('upstashvector.update.vector_and_missing_id', 'update', '/update can replace the coordinates (re-checking the dimension), and an id that does not exist answers {updated:0} — a normal answer, not an error', 'api', 'common', () => withRoot(async (r) => {
+        await r('upsert', { id: 'a', vector: [1, 0] });
+        const moved = await r('update', { id: 'a', vector: [0, 1] }, { at: laterAt(1000) });
+        const q = await r('query', { vector: [0, 1], topK: 1 });
+        const nobody = await r('update', { id: 'ghost', metadata: { x: 1 } });
+        const wrongDim = await r('update', { id: 'a', vector: [0, 1, 2] });
+        return JSON.stringify(moved.result) === JSON.stringify({ updated: 1 })
+            && near(q.result[0].score, 1)
+            && JSON.stringify(nobody.result) === JSON.stringify({ updated: 0 })
+            && wrongDim.status === 422;
+    })),
+    // ── DELETE ──────────────────────────────────────────────────────────────────────────────────
+    done('upstashvector.delete.by_ids_counts_only_real_hits', 'delete', '/delete by ids answers the vendor\'s {deleted:N} where N counts vectors that ACTUALLY existed — an unknown id contributes 0 rather than erroring, and a repeated id counts once', 'api', 'core', () => withRoot(async (r) => {
+        await r('upsert', [{ id: 'a', vector: [1, 0] }, { id: 'b', vector: [0, 1] }]);
+        const del = await r('delete', { ids: ['a', 'ghost', 'a'] }, { at: laterAt(1000) });
+        const left = await r('range', { cursor: '', limit: 10 });
+        return JSON.stringify(del.result) === JSON.stringify({ deleted: 1 })
+            && JSON.stringify((left.result.vectors).map((v) => v.id)) === JSON.stringify(['b']);
+    })),
+    done('upstashvector.delete.by_prefix', 'delete', '/delete by `prefix` removes exactly the matching ids and reports the real count', 'api', 'common', () => withRoot(async (r) => {
+        await r('upsert', [{ id: 'tmp-1', vector: [1, 0] }, { id: 'tmp-2', vector: [0, 1] }, { id: 'keep', vector: [1, 1] }]);
+        const del = await r('delete', { prefix: 'tmp-' }, { at: laterAt(1000) });
+        const left = await r('range', { cursor: '', limit: 10 });
+        return JSON.stringify(del.result) === JSON.stringify({ deleted: 2 })
+            && JSON.stringify((left.result.vectors).map((v) => v.id)) === JSON.stringify(['keep']);
+    })),
+    done('upstashvector.delete.by_metadata_filter', 'delete', '/delete by metadata `filter` runs the real filter language over the real metadata and removes exactly the matches (the vendor documents this as a full scan)', 'api', 'common', () => withRoot(async (r) => {
+        await r('upsert', [
+            { id: 'a', vector: [1, 0], metadata: { status: 'stale', hits: 1 } },
+            { id: 'b', vector: [0, 1], metadata: { status: 'fresh', hits: 9 } },
+            { id: 'c', vector: [1, 1], metadata: { status: 'stale', hits: 8 } },
+        ]);
+        const del = await r('delete', { filter: "status = 'stale' AND hits < 5" }, { at: laterAt(1000) });
+        const left = await r('range', { cursor: '', limit: 10 });
+        const neither = await r('delete', {});
+        // An EMPTY filter is REFUSED on a delete rather than read as "match everything" — a caller's
+        // template rendering to '' must never wipe the namespace. (On /query the same empty string
+        // harmlessly means "no filter"; the asymmetry is deliberate and is the safe direction.)
+        const emptyFilter = await r('delete', { filter: '' }, { at: laterAt(2000) });
+        const survived = await r('range', { cursor: '', limit: 10 });
+        return JSON.stringify(del.result) === JSON.stringify({ deleted: 1 })
+            && JSON.stringify((left.result.vectors).map((v) => v.id)) === JSON.stringify(['b', 'c'])
+            && neither.status === 400
+            && emptyFilter.status === 400 && emptyFilter.result === undefined
+            && JSON.stringify((survived.result.vectors).map((v) => v.id)) === JSON.stringify(['b', 'c']);
+    })),
+    // ── RESET ───────────────────────────────────────────────────────────────────────────────────
+    done('upstashvector.reset.namespace_and_all', 'reset', '/reset empties ONE namespace, /reset?all empties every namespace — and `?all` is the bare query flag the SDK\'s ResetCommand actually spells (`reset?all`, with no value)', 'api', 'core', () => withRoot(async (r) => {
+        await r('upsert', { id: 'd', vector: [1, 0] });
+        await r('upsert', { id: 'n', vector: [0, 1] }, { ns: 'other' });
+        const one = await r('reset', undefined, { ns: 'other', at: laterAt(1000) });
+        const afterOne = await r('info', undefined, { method: 'GET' });
+        const all = await r('reset', undefined, { query: '?all', at: laterAt(2000) });
+        const afterAll = await r('info', undefined, { method: 'GET' });
+        const count = (x) => x.result.vectorCount;
+        return one.result === 'Success' && count(afterOne) === 1
+            && all.result === 'Success' && count(afterAll) === 0;
+    })),
+    done('upstashvector.reset.keeps_the_namespace_existing', 'reset', 'a reset EMPTIES a namespace but leaves it existing — which is what distinguishes /reset from /delete-namespace, and the reason namespaces are tracked as their own kernel subject rather than derived from "does any vector mention this name"', 'api', 'common', () => withRoot(async (r) => {
+        await r('upsert', { id: 'n', vector: [1, 0] }, { ns: 'keepme' });
+        await r('reset', undefined, { ns: 'keepme', at: laterAt(1000) });
+        const afterReset = await r('list-namespaces', undefined, { method: 'GET' });
+        await r('delete-namespace', undefined, { ns: 'keepme', at: laterAt(2000) });
+        const afterDelete = await r('list-namespaces', undefined, { method: 'GET' });
+        return JSON.stringify(afterReset.result) === JSON.stringify(['', 'keepme'])
+            && JSON.stringify(afterDelete.result) === JSON.stringify(['']);
+    })),
+    // ── NAMESPACES ──────────────────────────────────────────────────────────────────────────────
+    done('upstashvector.namespaces.isolation', 'namespaces', 'a query in one namespace NEVER sees another namespace\'s vectors, even when they share ids — the isolation guarantee namespaces exist to provide, and the bug a naive `vec:<ns>:<id>` subject key would introduce', 'api', 'core', () => withRoot(async (r) => {
+        await r('upsert', { id: 'shared', vector: [1, 0], metadata: { owner: 'a' } }, { ns: 'tenant-a' });
+        await r('upsert', { id: 'shared', vector: [1, 0], metadata: { owner: 'b' } }, { ns: 'tenant-b' });
+        const a = await r('query', { vector: [1, 0], topK: 10, includeMetadata: true }, { ns: 'tenant-a' });
+        const b = await r('query', { vector: [1, 0], topK: 10, includeMetadata: true }, { ns: 'tenant-b' });
+        const rowsA = a.result;
+        const rowsB = b.result;
+        return rowsA.length === 1 && rowsB.length === 1
+            && JSON.stringify(rowsA[0].metadata) === JSON.stringify({ owner: 'a' })
+            && JSON.stringify(rowsB[0].metadata) === JSON.stringify({ owner: 'b' });
+    })),
+    done('upstashvector.namespaces.colon_in_names_and_ids', 'namespaces', 'namespaces and ids containing the subject-key delimiter (`:`) stay isolated — `ns "a", id "b:c"` and `ns "a:b", id "c"` are DIFFERENT vectors. A naive un-encoded key would collapse both onto one subject, silently destroying one tenant\'s data', 'api', 'niche', () => withRoot(async (r) => {
+        await r('upsert', { id: 'b:c', vector: [1, 0], metadata: { which: 'first' } }, { ns: 'a' });
+        await r('upsert', { id: 'c', vector: [0, 1], metadata: { which: 'second' } }, { ns: 'a:b' });
+        const first = await r('fetch', { ids: ['b:c'], includeMetadata: true }, { ns: 'a' });
+        const second = await r('fetch', { ids: ['c'], includeMetadata: true }, { ns: 'a:b' });
+        const m = (x) => JSON.stringify(x.result[0]?.metadata);
+        return m(first) === JSON.stringify({ which: 'first' }) && m(second) === JSON.stringify({ which: 'second' });
+    })),
+    done('upstashvector.namespaces.list', 'namespaces', '/list-namespaces returns every namespace including the default one, which is named "" (empty string) and always exists even on a brand-new index', 'api', 'common', () => withRoot(async (r) => {
+        const fresh = await r('list-namespaces', undefined, { method: 'GET' });
+        await r('upsert', { id: 'a', vector: [1, 0] }, { ns: 'zeta' });
+        await r('upsert', { id: 'b', vector: [1, 0] }, { ns: 'alpha' });
+        const after = await r('list-namespaces', undefined, { method: 'GET' });
+        return JSON.stringify(fresh.result) === JSON.stringify([''])
+            && JSON.stringify(after.result) === JSON.stringify(['', 'alpha', 'zeta']);
+    })),
+    done('upstashvector.namespaces.delete_namespace', 'namespaces', '/delete-namespace removes the namespace AND everything in it, leaving other namespaces untouched; an unknown namespace answers 404 and the DEFAULT namespace is refused (twin-defined — /reset is how you empty it)', 'api', 'common', () => withRoot(async (r) => {
+        await r('upsert', { id: 'a', vector: [1, 0] }, { ns: 'doomed' });
+        await r('upsert', { id: 'b', vector: [0, 1] }, { ns: 'safe' });
+        const del = await r('delete-namespace', undefined, { ns: 'doomed', at: laterAt(1000) });
+        const names = await r('list-namespaces', undefined, { method: 'GET' });
+        const info = await r('info', undefined, { method: 'GET' });
+        const unknown = await r('delete-namespace', undefined, { ns: 'never-existed' });
+        const dflt = await r.raw({ path: '/delete-namespace/', method: 'DELETE' });
+        return del.result === 'Success'
+            && JSON.stringify(names.result) === JSON.stringify(['', 'safe'])
+            && info.result.vectorCount === 1
+            && unknown.status === 404 && dflt.status === 400;
+    })),
+    // ── FILTERING ───────────────────────────────────────────────────────────────────────────────
+    done('upstashvector.filtering.comparison_operators', 'filtering', 'the full comparison set — `=`, `!=`, `<`, `>`, `<=`, `>=` — filters a query against real metadata, on both numbers and strings', 'api', 'core', () => withRoot(async (r) => {
+        await r('upsert', [
+            { id: 'tr', vector: [1, 0], metadata: { country: 'Turkey', population: 15460000, capital: false } },
+            { id: 'de', vector: [1, 0], metadata: { country: 'Germany', population: 3600000, capital: true } },
+            { id: 'fr', vector: [1, 0], metadata: { country: 'France', population: 2100000, capital: true } },
+        ]);
+        const hits = async (filter) => {
+            const q = await r('query', { vector: [1, 0], topK: 10, filter });
+            return q.result.map((x) => x.id).sort();
+        };
+        return JSON.stringify(await hits("country = 'Turkey'")) === JSON.stringify(['tr'])
+            && JSON.stringify(await hits("country != 'Turkey'")) === JSON.stringify(['de', 'fr'])
+            && JSON.stringify(await hits('population > 3000000')) === JSON.stringify(['de', 'tr'])
+            && JSON.stringify(await hits('population < 3000000')) === JSON.stringify(['fr'])
+            && JSON.stringify(await hits('population >= 3600000')) === JSON.stringify(['de', 'tr'])
+            && JSON.stringify(await hits('population <= 2100000')) === JSON.stringify(['fr']);
+    })),
+    done('upstashvector.filtering.and_or_precedence_and_parentheses', 'filtering', 'AND binds TIGHTER than OR (the vendor\'s documented precedence) and parentheses override it — proven by an expression whose two readings select DIFFERENT rows, so a twin that got precedence backwards fails here', 'api', 'core', () => withRoot(async (r) => {
+        await r('upsert', [
+            { id: 'a', vector: [1, 0], metadata: { x: 1, y: 1 } },
+            { id: 'b', vector: [1, 0], metadata: { x: 2, y: 1 } },
+            { id: 'c', vector: [1, 0], metadata: { x: 2, y: 2 } },
+        ]);
+        const hits = async (filter) => {
+            const q = await r('query', { vector: [1, 0], topK: 10, filter });
+            return q.result.map((x) => x.id).sort();
+        };
+        // `x = 1 OR x = 2 AND y = 2` reads as `x=1 OR (x=2 AND y=2)` → {a, c}
+        // Parenthesised the other way, `(x = 1 OR x = 2) AND y = 2` → {c} alone.
+        return JSON.stringify(await hits('x = 1 OR x = 2 AND y = 2')) === JSON.stringify(['a', 'c'])
+            && JSON.stringify(await hits('(x = 1 OR x = 2) AND y = 2')) === JSON.stringify(['c'])
+            && JSON.stringify(await hits('x = 2 AND y = 1')) === JSON.stringify(['b']);
+    })),
+    done('upstashvector.filtering.in_and_not_in', 'filtering', '`IN (…)` and `NOT IN (…)` match against a parenthesised literal list, and a vector MISSING the field matches neither — absence is asked about with HAS FIELD, not smuggled into NOT IN', 'api', 'common', () => withRoot(async (r) => {
+        await r('upsert', [
+            { id: 'de', vector: [1, 0], metadata: { country: 'Germany' } },
+            { id: 'tr', vector: [1, 0], metadata: { country: 'Turkey' } },
+            { id: 'us', vector: [1, 0], metadata: { country: 'USA' } },
+            { id: 'none', vector: [1, 0], metadata: { other: 1 } },
+        ]);
+        const hits = async (filter) => {
+            const q = await r('query', { vector: [1, 0], topK: 10, filter });
+            return q.result.map((x) => x.id).sort();
+        };
+        return JSON.stringify(await hits("country IN ('Germany', 'Turkey')")) === JSON.stringify(['de', 'tr'])
+            && JSON.stringify(await hits("country NOT IN ('Germany', 'Turkey')")) === JSON.stringify(['us']);
+    })),
+    done('upstashvector.filtering.glob', 'filtering', 'GLOB runs a real pattern matcher — `*`, `?`, `[abc]` classes, `[^…]` negation and `[a-z]` RANGES — driven through the twin, including the vendor\'s own documented example pattern `?[sz]*[^m-z]`', 'api', 'common', () => withRoot(async (r) => {
+        await r('upsert', [
+            { id: 'istanbul', vector: [1, 0], metadata: { city: 'Istanbul' } },
+            { id: 'ankara', vector: [1, 0], metadata: { city: 'Ankara' } },
+            { id: 'izmir', vector: [1, 0], metadata: { city: 'Izmir' } },
+        ]);
+        const hits = async (filter) => {
+            const q = await r('query', { vector: [1, 0], topK: 10, filter });
+            return q.result.map((x) => x.id).sort();
+        };
+        return JSON.stringify(await hits("city GLOB 'I*'")) === JSON.stringify(['istanbul', 'izmir'])
+            && JSON.stringify(await hits("city GLOB '?[sz]*'")) === JSON.stringify(['istanbul', 'izmir'])
+            && JSON.stringify(await hits("city GLOB 'A?kara'")) === JSON.stringify(['ankara'])
+            && JSON.stringify(await hits("city GLOB '*[^r]'")) === JSON.stringify(['ankara', 'istanbul'])
+            && JSON.stringify(await hits("city NOT GLOB 'I*'")) === JSON.stringify(['ankara'])
+            // A RANGE, which the title names and the verify previously did not exercise (§9 round 1).
+            // Ankara ends 'a' and Istanbul ends 'l' — both inside a..m; Izmir ends 'r', outside it.
+            && JSON.stringify(await hits("city GLOB '*[a-m]'")) === JSON.stringify(['ankara', 'istanbul'])
+            && JSON.stringify(await hits("city GLOB '*[m-z]'")) === JSON.stringify(['izmir'])
+            // The vendor's OWN documented example pattern, likewise named by the title. Istanbul ends
+            // 'l' (outside m..z) and matches; Izmir ends 'r' (inside) and does not.
+            && JSON.stringify(await hits("city GLOB '?[sz]*[^m-z]'")) === JSON.stringify(['istanbul']);
+    })),
+    done('upstashvector.filtering.contains_and_has_field', 'filtering', 'CONTAINS tests array membership and HAS FIELD / HAS NOT FIELD test key PRESENCE — the operators that make "this vector has no such key" expressible rather than conflated with "its value differs"', 'api', 'common', () => withRoot(async (r) => {
+        await r('upsert', [
+            { id: 'a', vector: [1, 0], metadata: { tags: ['tourism', 'finance'], geo: { lat: 1 } } },
+            { id: 'b', vector: [1, 0], metadata: { tags: ['mining'] } },
+        ]);
+        const hits = async (filter) => {
+            const q = await r('query', { vector: [1, 0], topK: 10, filter });
+            return q.result.map((x) => x.id).sort();
+        };
+        return JSON.stringify(await hits("tags CONTAINS 'tourism'")) === JSON.stringify(['a'])
+            && JSON.stringify(await hits("tags NOT CONTAINS 'tourism'")) === JSON.stringify(['b'])
+            && JSON.stringify(await hits('HAS FIELD geo')) === JSON.stringify(['a'])
+            && JSON.stringify(await hits('HAS NOT FIELD geo')) === JSON.stringify(['b'])
+            && JSON.stringify(await hits('HAS FIELD geo.lat')) === JSON.stringify(['a']);
+    })),
+    done('upstashvector.filtering.nested_paths_and_array_indexing', 'filtering', 'identifiers address arbitrarily deep nested objects with `.` and individual array elements with `[n]` — including the vendor\'s end-relative `[#-1]` form, where `#` marks indexing from the back', 'api', 'common', () => withRoot(async (r) => {
+        await r('upsert', [
+            { id: 'a', vector: [1, 0], metadata: { geo: { coord: { lat: 41.0 } }, tags: ['first', 'middle', 'last'] } },
+            { id: 'b', vector: [1, 0], metadata: { geo: { coord: { lat: 12.0 } }, tags: ['only'] } },
+        ]);
+        const hits = async (filter) => {
+            const q = await r('query', { vector: [1, 0], topK: 10, filter });
+            return q.result.map((x) => x.id).sort();
+        };
+        return JSON.stringify(await hits('geo.coord.lat > 40')) === JSON.stringify(['a'])
+            && JSON.stringify(await hits("tags[0] = 'first'")) === JSON.stringify(['a'])
+            && JSON.stringify(await hits("tags[#-1] = 'last'")) === JSON.stringify(['a'])
+            && JSON.stringify(await hits("tags[#-1] = 'only'")) === JSON.stringify(['b'])
+            && JSON.stringify(await hits("tags[5] = 'nope'")) === JSON.stringify([]);
+    })),
+    done('upstashvector.filtering.literals_and_quoting', 'filtering', 'string literals may be single OR double quoted, booleans accept both the documented `1`/`0` spelling and `true`/`false`, and a comparison against a MISSING field is false rather than an error', 'api', 'common', () => withRoot(async (r) => {
+        await r('upsert', [
+            { id: 'a', vector: [1, 0], metadata: { name: "O'Hare", live: true } },
+            { id: 'b', vector: [1, 0], metadata: { name: 'Plain', live: false } },
+        ]);
+        const hits = async (filter) => {
+            const q = await r('query', { vector: [1, 0], topK: 10, filter });
+            return q.result.map((x) => x.id).sort();
+        };
+        return JSON.stringify(await hits('name = "O\'Hare"')) === JSON.stringify(['a'])
+            && JSON.stringify(await hits("name = 'Plain'")) === JSON.stringify(['b'])
+            && JSON.stringify(await hits('live = 1')) === JSON.stringify(['a'])
+            && JSON.stringify(await hits('live = true')) === JSON.stringify(['a'])
+            && JSON.stringify(await hits('live = 0')) === JSON.stringify(['b'])
+            && JSON.stringify(await hits('nosuchkey = 1')) === JSON.stringify([]);
+    })),
+    done('upstashvector.filtering.malformed_filter_is_rejected', 'filtering', 'a malformed filter answers 400 and matches NOTHING — a filter language that silently ignored a typo would turn one mistake into a full-index data leak, which is the single most dangerous way a filter can fail', 'api', 'core', () => withRoot(async (r) => {
+        await r('upsert', [{ id: 'a', vector: [1, 0], metadata: { x: 1 } }, { id: 'b', vector: [1, 0], metadata: { x: 2 } }]);
+        const bad = ['x =', 'x == 1', '(x = 1', "x = 'unterminated", 'x IN ()', 'HAS FIELD', 'x = unquoted', ''];
+        const statuses = [];
+        for (const filter of bad) {
+            const q = await r('query', { vector: [1, 0], topK: 10, filter });
+            // An empty filter string is legitimately "no filter"; everything else must be a 400.
+            statuses.push(filter === '' ? (Array.isArray(q.result) && q.result.length === 2 ? 200 : 0) : q.status);
+        }
+        return JSON.stringify(statuses) === JSON.stringify([400, 400, 400, 400, 400, 400, 400, 200]);
+    })),
+    done('upstashvector.filtering.applies_to_query_and_delete_alike', 'filtering', 'the SAME parsed filter language drives /query and /delete — one implementation, so the rows a filter selects are exactly the rows it would remove', 'api', 'common', () => withRoot(async (r) => {
+        const seed = [
+            { id: 'a', vector: [1, 0], metadata: { tier: 'free', seats: 1 } },
+            { id: 'b', vector: [1, 0], metadata: { tier: 'pro', seats: 40 } },
+            { id: 'c', vector: [1, 0], metadata: { tier: 'pro', seats: 2 } },
+        ];
+        await r('upsert', seed);
+        const filter = "tier = 'pro' AND seats > 10";
+        const q = await r('query', { vector: [1, 0], topK: 10, filter });
+        const selected = q.result.map((x) => x.id);
+        const del = await r('delete', { filter }, { at: laterAt(1000) });
+        const left = await r('range', { cursor: '', limit: 10 });
+        return JSON.stringify(selected) === JSON.stringify(['b'])
+            && JSON.stringify(del.result) === JSON.stringify({ deleted: selected.length })
+            && JSON.stringify((left.result.vectors).map((v) => v.id)) === JSON.stringify(['a', 'c']);
+    })),
+    // ── METADATA ────────────────────────────────────────────────────────────────────────────────
+    done('upstashvector.metadata.round_trips_arbitrary_json', 'metadata', 'metadata round-trips as arbitrary JSON — nested objects, arrays, numbers, booleans and null all come back byte-identical, so a caller can store the document shape they actually use', 'api', 'core', () => withRoot(async (r) => {
+        const meta = { title: 'Lord of the Rings', genre: ['fantasy', 'classic'], year: 1954, inPrint: true, sequel: null, nested: { a: { b: [1, 2, 3] } } };
+        await r('upsert', { id: 'lotr', vector: [1, 0], metadata: meta });
+        const got = await r('fetch', { ids: ['lotr'], includeMetadata: true });
+        return JSON.stringify(got.result[0].metadata) === JSON.stringify(meta);
+    })),
+    done('upstashvector.metadata.rejects_non_object', 'metadata', 'a non-object `metadata` (an array, a string) is refused with 400 rather than stored in a shape no filter could ever address', 'api', 'niche', () => withRoot(async (r) => {
+        const arr = await r('upsert', { id: 'a', vector: [1, 0], metadata: ['not', 'an', 'object'] });
+        const str = await r('upsert', { id: 'b', vector: [1, 0], metadata: 'nope' });
+        return arr.status === 400 && str.status === 400;
+    })),
+    // ── INFO ────────────────────────────────────────────────────────────────────────────────────
+    done('upstashvector.info.counts_and_configuration', 'info', '/info reports the real vectorCount, the index dimension and the configured similarityFunction — all derived from live state, so they move when the index does', 'api', 'core', () => withRoot(async (r) => {
+        const empty = await r('info', undefined, { method: 'GET' });
+        await r('upsert', [{ id: 'a', vector: [1, 0, 0] }, { id: 'b', vector: [0, 1, 0] }]);
+        const filled = await r('info', undefined, { method: 'GET' });
+        await r('delete', { ids: ['a'] }, { at: laterAt(1000) });
+        const afterDelete = await r('info', undefined, { method: 'GET' });
+        const i0 = empty.result;
+        const i1 = filled.result;
+        const i2 = afterDelete.result;
+        return i0.vectorCount === 0 && i1.vectorCount === 2 && i2.vectorCount === 1
+            && i1.dimension === 3 && i1.similarityFunction === 'EUCLIDEAN' && i1.pendingVectorCount === 0
+            && JSON.stringify(i1.denseIndex) === JSON.stringify({ dimension: 3, similarityFunction: 'EUCLIDEAN' });
+    }, { similarityFunction: 'EUCLIDEAN' })),
+    done('upstashvector.info.per_namespace_map', 'info', '/info carries the per-namespace `namespaces` map keyed by namespace name (the default one under the empty-string key), each with its own vectorCount — the vendor\'s own documented shape', 'api', 'common', () => withRoot(async (r) => {
+        await r('upsert', [{ id: 'a', vector: [1, 0] }, { id: 'b', vector: [0, 1] }]);
+        await r('upsert', { id: 'c', vector: [1, 1] }, { ns: 'ns' });
+        const info = (await r('info', undefined, { method: 'GET' })).result;
+        return info.namespaces[''] !== undefined && info.namespaces[''].vectorCount === 2
+            && info.namespaces.ns !== undefined && info.namespaces.ns.vectorCount === 1
+            && info.namespaces[''].pendingVectorCount === 0;
+    })),
+    done('upstashvector.info.index_size_uses_the_published_formula', 'info', 'indexSize is computed with the VENDOR\'S OWN published accounting — upstash.com/docs/vector/help/faq: "Each dimension is estimated to be 4 bytes, resulting in vector storage being calculated as vector count * dimension count * 4 bytes", combined with the metadata and data a vector carries — so the exact byte count is checkable arithmetic, and it grows and shrinks with real state', 'api', 'niche', () => withRoot(async (r) => {
+        const size = async () => (await r('info', undefined, { method: 'GET' })).result.indexSize;
+        const empty = await size();
+        // Two 2-dimension vectors, no metadata, no data ⇒ 2 vectors × 2 dims × 4 bytes = 16.
+        await r('upsert', [{ id: 'a', vector: [1, 0] }, { id: 'b', vector: [0, 1] }]);
+        const bare = await size();
+        // Adding metadata adds exactly its encoded length: JSON.stringify({"k":"v"}) is 9 bytes.
+        const meta = { k: 'v' };
+        await r('upsert', { id: 'c', vector: [1, 1], metadata: meta }, { at: laterAt(1000) });
+        const withMeta = await size();
+        await r('delete', { ids: ['a'] }, { at: laterAt(2000) });
+        const trimmed = await size();
+        return empty === 0
+            && bare === 2 * 2 * 4
+            && withMeta === bare + 2 * 4 + Buffer.byteLength(JSON.stringify(meta), 'utf8')
+            && trimmed === withMeta - 2 * 4;
+    })),
+    // ── SAFETY ──────────────────────────────────────────────────────────────────────────────────
+    done('upstashvector.safety.read_only_forbids_writes', 'safety', 'a twin started read-only answers 405 to every WRITE (/upsert, /update, /delete, /reset, /delete-namespace) while reads keep working, and appends NOTHING to the kernel action log even when started WITH an index configuration — the pure-mirror mode a pulled index is served in', 'api', 'core', () => withRoot(async (r) => {
+        await r('upsert', { id: 'a', vector: [1, 0], metadata: { k: 'v' } });
+        await r('upsert', { id: 'n', vector: [0, 1] }, { ns: 'doomed', at: laterAt(10) });
+        // All FIVE writes the title names — /delete-namespace was previously unasserted (§9 round 1).
+        const writes = await Promise.all([
+            r.raw({ path: '/upsert', body: JSON.stringify({ id: 'b', vector: [0, 1] }), readOnly: true }),
+            r.raw({ path: '/update', body: JSON.stringify({ id: 'a', metadata: {} }), readOnly: true }),
+            r.raw({ path: '/delete', body: JSON.stringify({ ids: ['a'] }), readOnly: true }),
+            r.raw({ path: '/reset', readOnly: true, body: '{}' }),
+            r.raw({ path: '/delete-namespace/doomed', method: 'DELETE', readOnly: true }),
+        ]);
+        const read = await r.raw({ path: '/query', body: JSON.stringify({ vector: [1, 0], topK: 1, includeMetadata: true }), readOnly: true });
+        const rows = read.body.result;
+        const stillThere = await r('fetch', { ids: ['a'] });
+        const nsIntact = await r('list-namespaces', undefined, { method: 'GET' });
+        // …and a read-only twin must append NOTHING to the action log, even when it was started WITH
+        // an index configuration. §9 round 1 found a GET /info doing exactly that: the constructor
+        // marked the config dirty and flush() wrote it, because no assertWritable() guarded that path.
+        const quiet = mkdtempSync(join(tmpdir(), 'upstashvector-ro-'));
+        let appended = 0;
+        try {
+            await handleUpstashVectorTwinRequest({ method: 'GET', path: '/info', root: quiet, occurredAt: AT, headers: AUTH, readOnly: true, dimension: 4 });
+            const log = join(quiet, '.volter', 'world', 'upstashvector', 'actions.jsonl');
+            appended = existsSync(log) ? readFileSync(log, 'utf8').split('\n').filter((l) => l.trim() !== '').length : 0;
+        }
+        finally {
+            rmSync(quiet, { recursive: true, force: true });
+        }
+        return writes.every((x) => x.status === 405)
+            && read.status === 200 && rows.length === 1 && JSON.stringify(rows[0].metadata) === JSON.stringify({ k: 'v' })
+            && stillThere.result[0] !== null
+            && JSON.stringify(nsIntact.result) === JSON.stringify(['', 'doomed'])
+            && appended === 0;
+    })),
+    // ── PERSISTENCE (the kernel-backed claim, and the dirty-state verifies) ─────────────────────
+    done('upstashvector.persistence.state_survives_a_fresh_process', 'persistence', 'state lives in the kernel action log, not in memory: a BRAND-NEW IndexSpace over the same root sees every vector, its metadata and the index\'s locked-in dimension — the "kill the process and it still answers" property', 'api', 'core', () => withRoot(async (r, root) => {
+        await r('upsert', { id: 'a', vector: [0.5, 0.5], metadata: { kept: true } });
+        await r('upsert', { id: 'b', vector: [1, 0] }, { ns: 'other', at: laterAt(10) });
+        // A fresh space, constructed directly — nothing carried over from the requests above.
+        const reborn = new IndexSpace({ occurredAt: laterAt(5000), root });
+        const a = reborn.getVector('', 'a');
+        return a !== undefined && JSON.stringify(a.values) === JSON.stringify([0.5, 0.5])
+            && JSON.stringify(a.metadata) === JSON.stringify({ kept: true })
+            && reborn.indexDimension === 2
+            && JSON.stringify(reborn.listNamespaces()) === JSON.stringify(['', 'other'])
+            && reborn.getVector('other', 'b') !== undefined
+            && reborn.getVector('other', 'a') === undefined;
+    })),
+    done('upstashvector.persistence.delete_then_recreate', 'persistence', 'a DIRTY-STATE verify: deleting a vector and re-upserting the same id yields the NEW value, not a resurrected old one — the tombstone must not swallow the re-add, and the re-add must not inherit dead metadata', 'api', 'core', () => withRoot(async (r) => {
+        await r('upsert', { id: 'a', vector: [1, 0], metadata: { generation: 1 }, data: 'old' });
+        await r('delete', { ids: ['a'] }, { at: laterAt(1000) });
+        const gone = await r('fetch', { ids: ['a'] });
+        await r('upsert', { id: 'a', vector: [0, 1] }, { at: laterAt(2000) });
+        const back = await r('fetch', { ids: ['a'], includeMetadata: true, includeVectors: true, includeData: true });
+        const row = back.result[0];
+        const count = (await r('info', undefined, { method: 'GET' })).result.vectorCount;
+        return gone.result[0] === null
+            && row.id === 'a' && JSON.stringify(row.vector) === JSON.stringify([0, 1])
+            && row.metadata === undefined && row.data === undefined
+            && count === 1;
+    })),
+    done('upstashvector.persistence.same_instant_rewrite_is_not_swallowed', 'persistence', 'a DIRTY-STATE verify for the kernel\'s action dedupe: writing a vector back to a value it ALREADY HELD, at the SAME pinned millisecond, must still take effect. The kernel dedupes by (content + occurredAt ms), so without a per-subject write ordinal the second write is dropped as a replay and state silently disagrees with the reply the caller got', 'api', 'core', () => withRoot(async (r) => {
+        const at = laterAt(0); // every write below shares ONE millisecond, deliberately
+        await r('upsert', { id: 'a', vector: [1, 0], metadata: { v: 'first' } }, { at });
+        await r('upsert', { id: 'a', vector: [1, 0], metadata: { v: 'second' } }, { at });
+        await r('upsert', { id: 'a', vector: [1, 0], metadata: { v: 'first' } }, { at }); // back to the ORIGINAL
+        const got = await r('fetch', { ids: ['a'], includeMetadata: true });
+        const row = got.result[0];
+        // The reply said the third write applied; state must agree. A dedupe-dropped write would
+        // leave `second` here — a reply and a projection disagreeing, the worst shape of wrong answer.
+        return JSON.stringify(row.metadata) === JSON.stringify({ v: 'first' });
+    })),
+    done('upstashvector.persistence.corrupt_stored_vector_cannot_poison_a_ranking', 'persistence', 'a stored vector whose coordinates are unreadable — a `null` (which is what a NaN becomes once it has been through JSON), a string, or an overflow-scale number — is treated as CORRUPT and excluded from every read, so it can neither be returned nor drag a ranking into `"score": null`. This is the defence for state this pack did not write: the connector refuses such rows at ingest, but a root written by an older build or another tool can still hold one, and `Number(null) === 0` means a coercing reader would silently substitute a different vector. (§9 round 2 found the coercion; the revert matrix then showed the guard was unreachable through the connector, so it is pinned HERE, by writing the poison to the kernel directly.)', 'api', 'common', () => withRoot(async (r, root) => {
+        await r('upsert', { id: 'good', vector: [1, 0] });
+        // Straight into the kernel, bypassing every twin boundary — exactly what a foreign writer does.
+        const poison = async (vid, values) => {
+            await applyTwinWrite('upstashvector', {
+                operation: 'vector.upsert',
+                subjectType: 'vector',
+                subjectId: `vec::${encodeURIComponent(vid)}`,
+                fields: { ns: '', vid, values, metadata: null, data: '', gone: false, _rev: 1 },
+                occurredAt: laterAt(1000),
+                actor: { kind: 'agent' },
+            }, root);
+        };
+        await poison('nulled', [null, 1]); // a NaN that has round-tripped through JSON
+        await poison('stringy', ['abc', 1]);
+        await poison('huge', [1e308, 1]);
+        const q = await r('query', { vector: [1, 0], topK: 10 });
+        const rows = q.result;
+        const info = (await r('info', undefined, { method: 'GET' })).result;
+        const fetched = await r('fetch', { ids: ['nulled', 'stringy', 'huge', 'good'] });
+        const fetchedRows = fetched.result;
+        return q.status === 200
+            // Only the readable vector ranks, and its score is a real number.
+            && rows.length === 1 && rows[0].id === 'good' && Number.isFinite(rows[0].score)
+            // The corrupt rows are invisible everywhere, not just in the ranking.
+            && info.vectorCount === 1
+            && fetchedRows[0] === null && fetchedRows[1] === null && fetchedRows[2] === null
+            && fetchedRows[3]?.id === 'good';
+    })),
+    done('upstashvector.persistence.interleaved_namespace_churn', 'persistence', 'a DIRTY-STATE verify over accumulated history: deleting a namespace and recreating one with the SAME name starts EMPTY, and never resurrects the deleted namespace\'s vectors from the log', 'api', 'common', () => withRoot(async (r) => {
+        await r('upsert', [{ id: 'x', vector: [1, 0] }, { id: 'y', vector: [0, 1] }], { ns: 'reused' });
+        await r('delete-namespace', undefined, { ns: 'reused', at: laterAt(1000) });
+        await r('upsert', { id: 'z', vector: [1, 1] }, { ns: 'reused', at: laterAt(2000) });
+        const page = await r('range', { cursor: '', limit: 10 }, { ns: 'reused' });
+        const ids = (page.result.vectors).map((v) => v.id);
+        const info = (await r('info', undefined, { method: 'GET' })).result;
+        return JSON.stringify(ids) === JSON.stringify(['z']) && info.vectorCount === 1;
+    })),
+    // ── CONNECTOR ───────────────────────────────────────────────────────────────────────────────
+    done('upstashvector.connector.pull_over_injected_client', 'connector', 'the connector pulls a real index over an INJECTED client (never an imported SDK) and folds it into the twin, so pulled vectors and namespaces are queryable through the twin\'s own API. SCOPE (\u00a79 round 1): this is the kernel\'s fork model \u2014 a pull writes the OBSERVED layer and local writes are projected OVER it, so an id the caller has already written locally keeps its LOCAL value and a later pull of that same id does not surface. That is deliberate (local commits must not be silently reverted by a mirror refresh) and is shared with qstash/upstash, but it means "pulled vectors are queryable" holds for ids with no local write, not unconditionally. upstashvector.connector.pull_shadowed_by_local_writes files the reporting gap', 'connector', 'core', () => withRoot(async (r, root) => {
+        const { client } = fakeVectorClient({
+            '': [{ id: 'p1', vector: [1, 0], metadata: { src: 'real' } }, { id: 'p2', vector: [0, 1] }],
+            team: [{ id: 'p3', vector: [1, 1] }],
+        });
+        const res = await syncUpstashVectorFromReal(client, { root, occurredAt: AT, budgetOptions: { path: join(root, 'budget.json') } });
+        const q = await r('query', { vector: [1, 0], topK: 1, includeMetadata: true });
+        const rows = q.result;
+        const teamPage = await r('range', { cursor: '', limit: 10 }, { ns: 'team' });
+        // 4, not 5: three vectors plus the ONE named namespace. The default namespace ('') always
+        // exists on every index and the store synthesizes it, so the pull no longer mints a subject
+        // for state the write handler could never produce.
+        return res.observed === 4 && res.deltasAppended > 0
+            && rows.length === 1 && rows[0].id === 'p1' && JSON.stringify(rows[0].metadata) === JSON.stringify({ src: 'real' })
+            && (teamPage.result.vectors).map((v) => v.id).join(',') === 'p3';
+    })),
+    done('upstashvector.connector.pull_is_idempotent', 'connector', 'a re-pull of IDENTICAL vendor state appends ZERO deltas (the kernel\'s shadow-diff dedup) — which is what makes a pull safe to run on a schedule instead of growing the log without bound', 'connector', 'core', () => withRoot(async (_r, root) => {
+        const { client } = fakeVectorClient({ '': [{ id: 'p1', vector: [1, 0], metadata: { a: 1 } }] });
+        const opts = { root, occurredAt: AT, budgetOptions: { path: join(root, 'budget.json') } };
+        const first = await syncUpstashVectorFromReal(client, opts);
+        const second = await syncUpstashVectorFromReal(client, opts);
+        return first.deltasAppended > 0 && second.deltasAppended === 0 && second.observed === first.observed;
+    })),
+    done('upstashvector.connector.bounded_walk', 'connector', 'the range walk is BOUNDED by `limit` and stops at the vendor\'s empty cursor — an unbounded walk of a production index is exactly the spend the rate budget exists to stop, so the bound is a safety property, not a convenience', 'connector', 'common', () => withRoot(async (_r, root) => {
+        const many = Array.from({ length: 40 }, (_, i) => ({ id: `v${i}`, vector: [i, 1] }));
+        const { client, calls } = fakeVectorClient({ '': many });
+        const limited = await pullUpstashVectorRange(client, { limit: 7, pageSize: 3, budgetOptions: { path: join(root, 'budget.json') } });
+        const namespaces = await pullUpstashVectorNamespaces(client, { budgetOptions: { path: join(root, 'budget.json') } });
+        return limited.length === 7 && limited[0].id === 'v0'
+            && calls.filter((c) => c.startsWith('range')).length <= 4
+            && JSON.stringify(namespaces) === JSON.stringify(['']);
+    })),
+    done('upstashvector.connector.pulled_index_is_coherent', 'connector', 'a PULLED index behaves like a locally-written one: its dimension is inferred from the stored vectors (so /info reports it instead of 0), a mis-sized query gets the vendor\'s 422 instead of a silent empty result, and a later upsert cannot lock in a different dimension and orphan the pulled data. When a pull delivers MIXED lengths no dimension can be honestly inferred, so the next write is REFUSED rather than allowed to pick a winner. (§9 rounds 1-2: all four behaviours were broken or unpinned.)', 'connector', 'core', async () => {
+        // A uniform pulled root — nothing local was ever written, so only the pull's own state exists.
+        const uniform = await withRoot(async (r, root) => {
+            const { client } = fakeVectorClient({ '': [{ id: 'p1', vector: [1, 0, 0] }, { id: 'p2', vector: [0, 1, 0] }] });
+            await syncUpstashVectorFromReal(client, { root, occurredAt: AT, budgetOptions: { path: join(root, 'b.json') } });
+            const info = (await r('info', undefined, { method: 'GET' })).result;
+            const mismatched = await r('query', { vector: [1, 0], topK: 5 });
+            const ranked = await r('query', { vector: [1, 0, 0], topK: 1 });
+            const orphaning = await r('upsert', { id: 'local', vector: [1, 0] }, { at: laterAt(1000) });
+            return info.dimension === 3 && info.vectorCount === 2
+                // NOT a silent 200 [] — the promised 422, with the vendor's verbatim message.
+                && mismatched.status === 422 && mismatched.error === 'Invalid vector dimension: 2, expected: 3'
+                && ranked.result[0].id === 'p1'
+                // …and a mis-sized local write cannot lock in a rival dimension.
+                && orphaning.status === 422;
+        });
+        // A MIXED pulled root — no honest dimension exists, so a write must be refused, not guessed.
+        const mixed = await withRoot(async (r, root) => {
+            const { client } = fakeVectorClient({ '': [{ id: 'a', vector: [1, 0, 0] }, { id: 'b', vector: [0, 1] }] });
+            await syncUpstashVectorFromReal(client, { root, occurredAt: AT, budgetOptions: { path: join(root, 'b.json') } });
+            const write = await r('upsert', { id: 'local', vector: [1, 0] }, { at: laterAt(1000) });
+            const after = (await r('info', undefined, { method: 'GET' })).result;
+            return write.status === 422 && (write.error ?? '').includes('differing dimensions')
+                // Nothing was written, so neither pulled vector was orphaned.
+                && after.vectorCount === 2;
+        });
+        return uniform && mixed;
+    }),
+    done('upstashvector.connector.refuses_unstorable_vendor_rows', 'connector', 'a vendor row this twin cannot store faithfully is REFUSED by id rather than coerced — a non-numeric or overflow-scale coordinate would otherwise become a silent 0 (NaN -> JSON null -> Number(null)) or poison every score it touches into `"score": null` on the wire, ranking FIRST under DOT_PRODUCT. Ids that cannot even be addressed (an unpaired UTF-16 surrogate) are refused the same way instead of throwing a raw URIError off the pull\'s hot path. (§9 rounds 1-2.)', 'connector', 'common', () => withRoot(async () => {
+        const refused = (fn) => {
+            try {
+                fn();
+                return false;
+            }
+            catch (e) {
+                return e instanceof VectorApiError && e.status === 422 || e instanceof VectorApiError && e.status === 400;
+            }
+        };
+        return refused(() => mapVector({ id: 'bad', vector: ['abc', 1] }))
+            && refused(() => mapVector({ id: 'huge', vector: [1e308, 1] }))
+            && refused(() => mapVector({ id: 'nan', vector: [Number.NaN] }))
+            && refused(() => mapVector({ id: 'empty', vector: [] }))
+            // Un-addressable ids and namespaces, on BOTH mappers.
+            && refused(() => mapVector({ id: 'x\uD800', vector: [1, 0] }))
+            && refused(() => mapVector({ id: 'ok', namespace: 'n\uD800', vector: [1, 0] }))
+            && refused(() => mapNamespace('n\uD800'))
+            // …while a well-formed row still maps cleanly.
+            && mapVector({ id: 'fine', vector: [1, 0] }).id === 'vec::fine'
+            && mapNamespace('team').id === 'ns:team';
+    })),
+    done('upstashvector.connector.map_vector_is_pure', 'connector', '`mapVector` is a PURE mapper (a real vector → a kernel resource) that touches no client — so the namespace lands in `ns`, the vector id in `vid`, and neither collides with the kernel\'s reserved META keys (`type`/`id`/`updatedAt`), which projectResources SILENTLY DROPS', 'connector', 'common', () => withRoot(async () => {
+        const mapped = mapVector({ id: 'v-1', namespace: 'team', vector: [1, 2], metadata: { a: 1 }, data: 'text' });
+        const fields = mapped.fields;
+        return mapped.type === 'vector' && mapped.id === 'vec:team:v-1'
+            && fields.vid === 'v-1' && fields.ns === 'team' && fields.gone === false
+            && JSON.stringify(fields.values) === JSON.stringify([1, 2])
+            && fields.id === undefined && fields.type === undefined && fields.updatedAt === undefined;
+    })),
+    done('upstashvector.connector.rate_budget_refuses_past_the_ceiling', 'connector', 'every live call goes through the fail-closed budget: after the ceiling is spent the next call THROWS and the injected fake records NO further call — the count, not the throw, is what proves nothing reached the vendor', 'connector', 'core', () => withRoot(async (_r, root) => {
+        const { client, calls } = fakeVectorClient({ '': [{ id: 'v0', vector: [1, 0] }] });
+        const budget = new UpstashVectorBudget({ path: join(root, 'budget.json'), token: 'cap-test' });
+        // Guarded ONCE, with the budget whose ledger path is injected above — never against the
+        // operator's real ~/.volter file. (Guarding is idempotent, so wrapping once is enough.)
+        const guardedClient = guardUpstashVectorClient(client, { budget: budget });
+        // `info` is priced at the default weight of 2, so the ceiling allows exactly ceiling/2 calls.
+        const allowed = UPSTASHVECTOR_BUDGET_CEILING / 2;
+        const guardedInfo = () => guardedClient.info();
+        for (let i = 0; i < allowed; i++)
+            await guardedInfo();
+        const spent = calls.filter((c) => c === 'info').length;
+        let threw = false;
+        try {
+            await guardedInfo();
+        }
+        catch {
+            threw = true;
+        }
+        const after = calls.filter((c) => c === 'info').length;
+        return spent === allowed && threw && after === spent
+            && upstashvectorCallWeight('range') === 6 && upstashvectorCallWeight('info') === 2;
+    })),
+    // ── CONFORMANCE ─────────────────────────────────────────────────────────────────────────────
+    done('upstashvector.conformance.endpoint_probe', 'conformance', 'the conformance check ISSUES REAL REQUESTS against every endpoint the twin claims and asserts the VALUES they return, and cross-checks the declared kernel subject types in both directions — so a dead handler or a drifted inventory fails it', 'api', 'common', async () => {
+        const report = await checkUpstashVectorConformance();
+        return report.ok && report.violations.length === 0 && report.endpointsChecked >= 10 && report.resourceTypesChecked === 3;
+    }),
+    // ══════════════════════════════════════════════════════════════════════════════════════════
+    // THE DENOMINATOR — real Upstash Vector surface this twin has NOT built.
+    // ══════════════════════════════════════════════════════════════════════════════════════════
+    // Embedding models (upstash.com/docs/vector/features/embeddingmodels).
+    todo('upstashvector.embedding.upsert_data', 'embedding', 'POST /upsert-data — accept a raw-text `data` upsert against the index\'s configured embedding model (today it answers 404; an explicit `vector` is fully supported)', 'api', 'core'),
+    todo('upstashvector.embedding.query_data', 'embedding', 'POST /query-data — accept a raw-text `data` query against the index\'s configured embedding model (today it answers 404)', 'api', 'core'),
+    todo('upstashvector.embedding.model_reported_in_info', 'embedding', '/info reports the index\'s configured embeddingModel inside denseIndex/sparseIndex — this twin has no model so it reports neither, and a caller reading that field sees it absent rather than a fabricated name', 'api', 'niche'),
+    // Sparse & hybrid indexes (upstash.com/docs/vector/features/sparseindexes).
+    todo('upstashvector.sparse.upsert', 'sparse', 'upsert a `sparseVector` ({indices, values}) into a SPARSE index — refused with 422 today rather than silently dropped', 'api', 'common'),
+    todo('upstashvector.sparse.query', 'sparse', 'query a SPARSE index with a sparseVector and rank by the sparse scoring model', 'api', 'common'),
+    todo('upstashvector.sparse.hybrid_index', 'sparse', 'HYBRID indexes carrying BOTH a dense and a sparse vector per id, with /info reporting indexType HYBRID', 'api', 'common'),
+    todo('upstashvector.sparse.fusion_algorithms', 'sparse', 'the hybrid fusion algorithms the SDK exposes — RRF (default) and DBSF — which decide how dense and sparse rankings are combined', 'api', 'niche'),
+    todo('upstashvector.sparse.weighting_strategy', 'sparse', 'the IDF weighting strategy for sparse/hybrid queries', 'api', 'niche'),
+    todo('upstashvector.sparse.query_mode', 'sparse', 'queryMode HYBRID | DENSE | SPARSE, which selects which half of a hybrid index a query searches', 'api', 'niche'),
+    // Resumable queries (upstash.com/docs/vector/features/resumablequery).
+    todo('upstashvector.resumable.start', 'resumable', 'POST /resumable-query — start a server-side query session with a maxIdle timeout, returning a uuid plus the first batch of scores', 'api', 'common'),
+    todo('upstashvector.resumable.next', 'resumable', 'POST /resumable-query-next — fetch the next `additionalK` results of an open session', 'api', 'common'),
+    todo('upstashvector.resumable.stop', 'resumable', 'POST /resumable-query-end — end a session and release its server-side state', 'api', 'common'),
+    todo('upstashvector.resumable.idle_expiry', 'resumable', 'a resumable session expiring after maxIdle seconds, so a later fetchNext fails the way the vendor fails it', 'api', 'niche'),
+    // Published plan limits (upstash.com/pricing/vector + the docs' limits tables).
+    todo('upstashvector.limits.coordinate_precision', 'limits', 'the numeric PRECISION Upstash stores coordinates at. The FAQ publishes 4 bytes per dimension as a BILLING estimate, from which float32 is an inference, not a documented fact \u2014 this twin bounds coordinates to float32 range on that inference (which makes the similarity arithmetic total) but the real precision, and whether the vendor rounds or refuses a wider value, needs a live index to confirm', 'api', 'niche'),
+    todo('upstashvector.limits.max_dimension', 'limits', 'the per-plan maximum vector dimension (1,536 on Free through 5,000 on Pro) enforced at upsert', 'api', 'common'),
+    todo('upstashvector.limits.max_topk', 'limits', 'the documented maximum topK of 1,000, refused above that rather than silently truncated', 'api', 'common'),
+    todo('upstashvector.limits.metadata_size', 'limits', 'the 48 KB per-vector metadata ceiling, refused with the vendor\'s error', 'api', 'niche'),
+    todo('upstashvector.limits.data_size', 'limits', 'the 1 MB per-vector `data` ceiling', 'api', 'niche'),
+    todo('upstashvector.limits.max_batch_size', 'limits', 'the maximum number of vectors accepted in one /upsert batch', 'api', 'niche'),
+    todo('upstashvector.limits.daily_query_quota', 'limits', 'the per-plan daily query quota (10,000/day on Free) and the throttle response it produces — Upstash publishes no HTTP status or body for it, so modeling it needs a live probe first', 'api', 'niche'),
+    todo('upstashvector.limits.storage_quota', 'limits', 'the per-plan storage ceiling (1 GB Free through 1 TB Pro) and the refusal that follows exhausting it', 'api', 'niche'),
+    // Protocol surface not yet modeled.
+    todo('upstashvector.protocol.get_on_a_write_endpoint', 'protocol', 'what the REAL service does with a safe method against a write endpoint (GET /reset, HEAD /delete) is unverified \u2014 no documented client sends one, so this twin refuses them 405 rather than guessing the destructive answer. Confirming the vendor behaviour needs a live index to probe', 'api', 'niche'),
+    todo('upstashvector.protocol.request_size_limit', 'protocol', 'the maximum HTTP request size and the status it is refused with — the sibling upstash pack live-probed a 413 for Redis, but Upstash publishes no figure for Vector and this build had no index to probe', 'api', 'niche'),
+    todo('upstashvector.protocol.telemetry_headers', 'protocol', 'the Upstash-Telemetry-{Sdk,Platform,Runtime} headers the SDK sends by default — accepted and ignored today; recording them would let a world assert which client spoke to it', 'api', 'niche'),
+    todo('upstashvector.protocol.retry_semantics', 'protocol', 'the SDK retries 5 times with exponential backoff by default; a twin that could arm a deterministic transient failure would let a consumer prove their retry path actually runs', 'api', 'niche'),
+    todo('upstashvector.errors.vendor_error_strings', 'errors', 'the LITERAL error bodies Upstash Vector returns for auth, malformed filters, unknown namespaces and quota exhaustion — this pack asserts the documented {error,status} envelope and status codes, but has verbatim text for the dimension mismatch ONLY. Closing this gap needs a live index to probe, exactly as the sibling upstash pack did', 'api', 'common'),
+    // Index management (the console/management surface, not the per-index data plane).
+    todo('upstashvector.management.create_index', 'management', 'creating an index (name, region, similarity function, dimension, embedding model) — the Upstash management API rather than the per-index REST surface this pack models', 'api', 'niche'),
+    todo('upstashvector.management.list_indexes', 'management', 'listing and describing the indexes an account owns', 'api', 'niche'),
+    todo('upstashvector.management.delete_index', 'management', 'deleting a whole index', 'api', 'niche'),
+    todo('upstashvector.management.readonly_token', 'management', 'the read-only REST token an index issues alongside its read-write one, which must reject writes at the vendor rather than at the caller', 'api', 'common'),
+    // Runtime.
+    todo('upstashvector.runtime.pending_vector_count', 'runtime', 'pendingVectorCount tracks vectors still being indexed (this twin\'s upsert is synchronous, so it is always 0)', 'api', 'common'),
+    // Connector surface.
+    todo('upstashvector.connector.push', 'connector', 'push locally-upserted vectors back to a real Upstash Vector index — deliberately not built: an upsert REPLACES, so a blind write-back to a production index is destructive, and the safe design (an explicit id allowlist plus a dry-run diff) has not been settled', 'connector', 'common'),
+    todo('upstashvector.connector.pull_metadata_only', 'connector', 'a cheap metadata-only pull (range with includeVectors:false) for callers who want the corpus shape without paying to move every coordinate', 'connector', 'niche'),
+    todo('upstashvector.connector.partial_sync_on_budget_exhaustion', 'connector', 'syncUpstashVectorFromReal accumulates every namespace\'s rows and calls syncPull ONCE at the end, so a rate-budget refusal part-way through discards every row already paid for \u2014 with the default limits a real index of >=5 namespaces cannot complete a default sync, and the operator is billed for the walk with nothing retained. Folding per namespace (or catching the refusal and syncing what was observed) is strictly better and is not built (\u00a79 round 1)', 'connector', 'common'),
+    todo('upstashvector.connector.pull_shadowed_by_local_writes', 'connector', 'a pull REPORTS deltasAppended for ids that a local write is shadowing, so the caller is told the pull landed when the twin will keep answering with the local value \u2014 and a re-pull of a locally-DELETED id reports deltasAppended:0 ("vendor and twin agree") while the vendor row stays invisible. The kernel\'s fork semantics are correct; what is missing is the connector REPORTING the shadowed ids so an operator can see the divergence (\u00a79 round 1)', 'connector', 'common'),
+    todo('upstashvector.connector.pull_index_configuration', 'connector', 'pulling the real index\'s dimension and similarityFunction from /info so a pulled twin configures itself instead of inferring the dimension from the first vector it sees', 'connector', 'common'),
+    todo('upstashvector.connector.fixtures', 'connector', 'seed a small library of realistic corpora (a docs-search index, a product catalogue, a memory store) for eval worlds', 'connector', 'niche'),
+];
+export const UPSTASHVECTOR_AREAS = [
+    'protocol', 'auth', 'upsert', 'query', 'scoring', 'fetch', 'range', 'update', 'delete', 'reset',
+    'namespaces', 'filtering', 'metadata', 'info', 'sparse', 'embedding', 'resumable', 'limits',
+    'errors', 'management', 'safety', 'persistence', 'runtime', 'connector', 'conformance',
+];
+export async function upstashvectorCapabilities() {
+    return checkCapabilities('upstashvector', UPSTASHVECTOR_CAPABILITIES);
+}