@volter/twin-upstashvector 0.1.0

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

@@ -0,0 +1,7 @@
+export type UpstashVectorConformanceReport = {
+    ok: boolean;
+    endpointsChecked: number;
+    resourceTypesChecked: number;
+    violations: string[];
+};
+export declare function checkUpstashVectorConformance(): Promise<UpstashVectorConformanceReport>;

package/dist/src/upstashvector-conformance.js

@@ -0,0 +1,163 @@
+// upstashvector conformance (dev-only; lazy-imported by the CLI, NEVER from index.ts/runtime — E2).
+//
+// This is NOT the static self-referential snapshot check some packs ship. §9 refuted that pattern
+// elsewhere in this repo on the grounds that comparing one constant to another cannot detect a dead
+// handler — so this check ISSUES REAL REQUESTS (the azureformrecognizer `conformance.endpoint_probe`
+// pattern, as adopted by the sibling upstash pack): it drives every endpoint the snapshot
+// claims through `handleUpstashVectorTwinRequest` against a throwaway root and requires each to be
+// genuinely routed and to answer with the right envelope AND the right values. A twin whose handler
+// returned `{}` fails this, which is the whole point.
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { handleUpstashVectorTwinRequest, upstashvectorTwinSnapshot } from "./upstashvector-twin.js";
+import { UPSTASHVECTOR_RESOURCE_TYPES } from "./upstashvector-store.js";
+const AT = '2026-01-01T00:00:00.000Z';
+export async function checkUpstashVectorConformance() {
+    const snapshot = upstashvectorTwinSnapshot();
+    const violations = [];
+    const root = mkdtempSync(join(tmpdir(), 'upstashvector-conf-'));
+    const auth = { authorization: 'Bearer twin-conformance-token' };
+    const result = (r) => r.body.result;
+    const probes = [
+        {
+            label: 'POST /upsert[/{namespace}] (one vector object or an array of them)',
+            method: 'POST', path: '/upsert', body: JSON.stringify([{ id: 'c-1', vector: [1, 0], metadata: { kind: 'a' } }, { id: 'c-2', vector: [0, 1] }]),
+            expect: (r) => r.status === 200 && result(r) === 'Success',
+        },
+        {
+            label: 'POST /query[/{namespace}] (an object = one query; an array = queryMany)',
+            method: 'POST', path: '/query', body: JSON.stringify({ vector: [1, 0], topK: 1, includeMetadata: true }),
+            expect: (r) => {
+                const rows = result(r);
+                // The nearest vector to [1,0] IS c-1, and under COSINE its score is exactly 1 — a value,
+                // not a status. A handler returning a constant or an empty array fails here.
+                return r.status === 200 && Array.isArray(rows) && rows.length === 1 && rows[0].id === 'c-1' && rows[0].score === 1
+                    && JSON.stringify(rows[0].metadata) === JSON.stringify({ kind: 'a' });
+            },
+        },
+        {
+            label: 'POST /fetch[/{namespace}] (by ids — positionally aligned, null for a miss — or by prefix)',
+            method: 'POST', path: '/fetch', body: JSON.stringify({ ids: ['c-2', 'c-missing'], includeVectors: true }),
+            expect: (r) => {
+                const rows = result(r);
+                return r.status === 200 && Array.isArray(rows) && rows.length === 2
+                    && rows[0]?.id === 'c-2' && JSON.stringify(rows[0]?.vector) === JSON.stringify([0, 1])
+                    && rows[1] === null;
+            },
+        },
+        {
+            label: 'POST /range[/{namespace}] (offset cursor, nextCursor "" when exhausted)',
+            method: 'POST', path: '/range', body: JSON.stringify({ cursor: '', limit: 1 }),
+            expect: (r) => {
+                const page = result(r);
+                return r.status === 200 && page.nextCursor === '1' && page.vectors?.length === 1 && page.vectors[0].id === 'c-1';
+            },
+        },
+        {
+            label: 'POST /update[/{namespace}] ({updated:0|1}, metadataUpdateMode OVERWRITE|PATCH)',
+            method: 'POST', path: '/update', body: JSON.stringify({ id: 'c-2', metadata: { kind: 'b' } }),
+            expect: (r) => JSON.stringify(result(r)) === JSON.stringify({ updated: 1 }),
+        },
+        {
+            label: 'GET|POST /info (counts + configuration + the per-namespace map)',
+            method: 'GET', path: '/info',
+            expect: (r) => {
+                const info = result(r);
+                return r.status === 200 && info.vectorCount === 2 && info.dimension === 2
+                    && info.similarityFunction === 'COSINE' && info.namespaces !== undefined && '' in info.namespaces;
+            },
+        },
+        {
+            label: 'POST /upsert[/{namespace}] into a namespace, then GET|POST /list-namespaces',
+            method: 'POST', path: '/upsert/team-a', body: JSON.stringify({ id: 'n-1', vector: [1, 1] }),
+            expect: (r) => r.status === 200 && result(r) === 'Success',
+        },
+        {
+            label: 'GET|POST /list-namespaces',
+            method: 'GET', path: '/list-namespaces',
+            expect: (r) => JSON.stringify(result(r)) === JSON.stringify(['', 'team-a']),
+        },
+        {
+            label: 'POST|DELETE /delete[/{namespace}] (by ids, prefix or metadata filter)',
+            method: 'POST', path: '/delete', body: JSON.stringify({ ids: ['c-1'] }),
+            expect: (r) => JSON.stringify(result(r)) === JSON.stringify({ deleted: 1 }),
+        },
+        {
+            label: 'POST|DELETE /delete-namespace/{namespace}',
+            method: 'DELETE', path: '/delete-namespace/team-a',
+            expect: (r) => r.status === 200 && result(r) === 'Success',
+        },
+        {
+            label: 'POST|DELETE /reset[/{namespace}] and /reset?all',
+            method: 'POST', path: '/reset?all',
+            expect: (r) => r.status === 200 && result(r) === 'Success',
+        },
+        {
+            label: 'OPTIONS (CORS preflight)',
+            method: 'OPTIONS', path: '/query',
+            expect: (r) => r.status === 200 && r.body === null,
+        },
+    ];
+    try {
+        for (const probe of probes) {
+            // The namespace-upsert probe is a SETUP step for list-namespaces and deliberately shares that
+            // endpoint's inventory entry, so it is exempt from the label check below.
+            const setupProbe = probe.label.startsWith('POST /upsert[/{namespace}] into a namespace');
+            if (!setupProbe && !snapshot.implementedEndpoints.includes(probe.label)) {
+                violations.push(`probe '${probe.label}' has no matching entry in implementedEndpoints`);
+                continue;
+            }
+            const response = await handleUpstashVectorTwinRequest({
+                method: probe.method,
+                path: probe.path,
+                headers: auth,
+                root,
+                occurredAt: AT,
+                ...(probe.body !== undefined ? { body: probe.body } : {}),
+            });
+            if (!probe.expect(response)) {
+                violations.push(`endpoint '${probe.label}' did not answer as declared (status ${response.status}, body ${JSON.stringify(response.body)})`);
+            }
+        }
+        // Every claimed endpoint must have a probe — otherwise the inventory could grow entries nothing
+        // exercises, which is exactly the drift a self-referential snapshot cannot see.
+        for (const endpoint of snapshot.implementedEndpoints) {
+            if (!probes.some((p) => p.label === endpoint))
+                violations.push(`declared endpoint '${endpoint}' has no conformance probe`);
+        }
+        // The inventory must match what the handler WRITES, in BOTH directions. Asserting only one
+        // direction leaves the loop vacuous against the drift it claims to catch (the bug §9 round 2
+        // found in the sibling upstash pack's first version of this check).
+        const written = ['vector', 'namespace', 'config'];
+        for (const type of UPSTASHVECTOR_RESOURCE_TYPES) {
+            if (!written.includes(type))
+                violations.push(`declared resource type '${type}' is not written by any handler path`);
+        }
+        for (const type of written) {
+            if (!UPSTASHVECTOR_RESOURCE_TYPES.includes(type)) {
+                violations.push(`the handler writes subject type '${type}' but UPSTASHVECTOR_RESOURCE_TYPES does not declare it`);
+            }
+        }
+        // …and the reset above must have genuinely emptied the index, so the probes' writes are proven
+        // to have reached real state rather than merely having returned 200s.
+        const after = await handleUpstashVectorTwinRequest({ method: 'GET', path: '/info', headers: auth, root, occurredAt: AT });
+        const info = after.body.result;
+        if (info?.vectorCount !== 0) {
+            violations.push(`/reset?all ran but the index still reports ${String(info?.vectorCount)} vectors`);
+        }
+        // The 'config' subject must SURVIVE a reset — the index keeps its dimension when emptied.
+        if (info?.dimension !== 2) {
+            violations.push(`the 'config' subject is declared but the index's dimension did not persist across reset (dimension=${String(info?.dimension)})`);
+        }
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+    return {
+        ok: violations.length === 0,
+        endpointsChecked: snapshot.implementedEndpoints.length,
+        resourceTypesChecked: snapshot.resourceTypes.length,
+        violations,
+    };
+}

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

@@ -0,0 +1,109 @@
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { type UpstashVectorBudgetedOptions } from './upstashvector-budget.js';
+export type { UpstashVectorBudgetedOptions };
+/**
+ * The subset of a real Upstash Vector client this connector calls. Every member is OPTIONAL: a
+ * client that cannot do one of these makes the corresponding pull observe nothing, which is the
+ * honest outcome — inventing a value would turn "cannot see" into "saw an empty index", and a
+ * subsequent push would then delete real data.
+ */
+export interface UpstashVectorLikeClient {
+    info?: () => Promise<unknown>;
+    listNamespaces?: () => Promise<string[]>;
+    range?: (args: {
+        cursor: string;
+        limit: number;
+        includeMetadata?: boolean;
+        includeVectors?: boolean;
+        includeData?: boolean;
+    }, opts?: {
+        namespace?: string;
+    }) => Promise<unknown>;
+}
+/** The twin-side shape of one pulled vector, before it becomes a kernel resource. */
+export type UpstashVectorRealVector = {
+    id: string;
+    namespace?: string;
+    vector: number[];
+    metadata?: Record<string, unknown> | null;
+    data?: string | null;
+};
+/**
+ * Pure mapper (a real vector → a kernel `SyncResource`). Never touches a client, so the mutation
+ * harness's connector-seam sweep (which sabotages exports matching sync/push/pull/fullSync) leaves
+ * it real — the pack convention, mirroring qstash's `mapMessage` and upstash's `mapKey`.
+ *
+ * The field names deliberately avoid the kernel's reserved META keys (`type`/`id`/`updatedAt`,
+ * which `projectResources` SILENTLY DROPS): the vector's own id is stored as `vid` and its
+ * namespace as `ns`. This is the same layout `upstashvector-store.ts` writes, so a pulled vector
+ * and a locally upserted one are indistinguishable to every read path.
+ */
+export declare function mapVector(real: UpstashVectorRealVector): SyncResource;
+/**
+ * A namespace observed on the vendor, so `list-namespaces` reflects a pull.
+ *
+ * Uses the store's `namespaceSubjectId` rather than re-implementing it. §9 round 2 found this
+ * function had drifted into its own bare `encodeURIComponent` call, which meant (a) two
+ * implementations of one subject key, a latent collision risk, and (b) the surrogate guard added
+ * to `encodeKeyPart` did not cover it — so `mapNamespace('\ud800')` still threw a raw `URIError`
+ * off the pull's hot path, after `listNamespaces()` had already been paid for. One implementation,
+ * one guard.
+ */
+export declare function mapNamespace(name: string): SyncResource;
+/**
+ * Walk ONE namespace with `/range`, bounded by `limit`.
+ *
+ * The bound is the point: an unbounded walk of a production index is precisely the spend this
+ * connector's budget exists to stop, and an entrypoint that offered one would be inviting the
+ * caller to burn a whole allowance in a loop.
+ */
+export declare function pullUpstashVectorRange(rawClient: UpstashVectorLikeClient, opts?: {
+    namespace?: string;
+    limit?: number;
+    pageSize?: number;
+} & UpstashVectorBudgetedOptions): Promise<UpstashVectorRealVector[]>;
+/**
+ * Discover the namespaces that exist on the vendor. A client without `listNamespaces` observes
+ * only the default namespace, which is the honest floor rather than an invented list.
+ */
+export declare function pullUpstashVectorNamespaces(rawClient: UpstashVectorLikeClient, opts?: UpstashVectorBudgetedOptions): Promise<string[]>;
+/**
+ * D7 entry point: pull the current real state of an index and fold it into the twin via ONE
+ * one observation. Returns `{observed, deltasAppended}` — a re-pull of identical
+ * state appends ZERO deltas, which is what makes the pull idempotent.
+ */
+export declare function syncUpstashVectorFromReal(rawClient: UpstashVectorLikeClient, opts?: {
+    root?: string;
+    occurredAt?: string;
+    namespaces?: string[];
+    limit?: number;
+    pageSize?: number;
+} & UpstashVectorBudgetedOptions): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/**
+ * An `UpstashVectorLikeClient` over the kernel's executor. At a REAL boundary the kernel sets the
+ * sealed credential over these headers (executor.ts); at the twin's own wire any credential is one.
+ *
+ * EVERY call is a POST, whatever the docs spell: `@upstash/vector`'s `HttpClient.request` hardcodes
+ * it, so a client that sent the documented method would be talking to a surface the real SDK never
+ * uses. Namespaces are a PATH SUFFIX, not a body field.
+ */
+export declare function upstashVectorClientOver(execute: RemoteExecute): UpstashVectorLikeClient;
+/** The refresh adapter: Upstash Vector enumerates (`/list-namespaces`, then `/range` per
+ *  namespace), so the whole index comes back without the world having to say what it holds. */
+export declare function syncUpstashVectorFromRemote(execute: RemoteExecute, opts?: {
+    root?: string;
+    origin?: string;
+    occurredAt?: string;
+} & UpstashVectorBudgetedOptions): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/**
+ * The perform adapter: an upsert and a delete cross; a namespace reset does too. Everything else a
+ * world records about its index — a query it ran, a count it took — is a READ at the vendor and has
+ * nothing to write.
+ */
+export declare function performUpstashVectorAction(execute: RemoteExecute, action: TwinAction, _ctx: PerformContext): Promise<PushOutcome>;

package/dist/src/upstashvector-connector.js

@@ -0,0 +1,286 @@
+// upstashvector CONNECTOR — the live-vendor pull path that gives this twin the "git for SaaS"
+// lifecycle over an INJECTED client (the auth boundary). The pack imports NO SDK and holds NO
+// token; a consumer injects something structurally satisfying `UpstashVectorLikeClient` (a real
+// `@upstash/vector` `Index` is assignable as-is, since its `info`/`range`/`listNamespaces` methods
+// have exactly these shapes — asserted at the type level in the SDK integration test).
+//
+// ── PULL WALKS `/range`, AND THE WALK IS BOUNDED ──────────────────────────────────────────────
+// Upstash Vector has no "give me everything" endpoint; `/range` is the supported pagination and it
+// is unbounded in the size of the caller's index. A vector index is routinely millions of rows, so
+// an unbounded walk is exactly the shape that turns one careless call into a very large bill —
+// Upstash Vector bills PER REQUEST ($0.4/100K on Pay-As-You-Go) and the free tier caps queries per
+// DAY. So every entrypoint takes a hard `limit`, loops a bounded number of pages, and GUARDS the
+// injected client before touching it (`guardUpstashVectorClient`, which is idempotent). There is
+// deliberately no option that turns the guard off.
+//
+// ── PUSH IS A FILED GAP, NOT AN OVERSIGHT ─────────────────────────────────────────────────────
+// See `upstashvector.connector.push` in the manifest: writing local vectors back into a real index
+// is destructive (an upsert REPLACES) and the safe design — an explicit id allowlist plus a
+// dry-run diff — has not been settled.
+import { observeResources } from '@volter/world-core';
+import { DEFAULT_NAMESPACE, VectorApiError, namespaceSubjectId, vectorSubjectId } from "./upstashvector-store.js";
+import { upstashvectorBudgetOf, guardUpstashVectorClient } from "./upstashvector-budget.js";
+const SERVICE = 'upstashvector';
+/**
+ * Pure mapper (a real vector → a kernel `SyncResource`). Never touches a client, so the mutation
+ * harness's connector-seam sweep (which sabotages exports matching sync/push/pull/fullSync) leaves
+ * it real — the pack convention, mirroring qstash's `mapMessage` and upstash's `mapKey`.
+ *
+ * The field names deliberately avoid the kernel's reserved META keys (`type`/`id`/`updatedAt`,
+ * which `projectResources` SILENTLY DROPS): the vector's own id is stored as `vid` and its
+ * namespace as `ns`. This is the same layout `upstashvector-store.ts` writes, so a pulled vector
+ * and a locally upserted one are indistinguishable to every read path.
+ */
+export function mapVector(real) {
+    const ns = real.namespace ?? DEFAULT_NAMESPACE;
+    // Validate the COORDINATES here, at the ingest boundary, with the same rule the HTTP write path
+    // applies. §9 round 2 found the hole: a vendor row carrying a non-numeric or overflow-scale
+    // coordinate flowed straight into the kernel, and a `NaN` serialised to JSON as `null` came back
+    // as 0 — a silently substituted coordinate — while an overflow-scale one poisoned every score it
+    // touched into `"score": null` on the wire, ranking FIRST under DOT_PRODUCT. Refusing loudly, by
+    // id, is the only answer that neither corrupts data nor hides it.
+    assertStorableVector(real.vector, real.id);
+    return {
+        type: 'vector',
+        id: vectorSubjectId(ns, real.id),
+        // Gotcha (kernel field MERGE, never a deep merge or an omission-clear): every field a later
+        // local write could overwrite is written explicitly here, so a pulled vector can never inherit
+        // stale metadata or a dead `gone` flag from a previous incarnation of the same subject.
+        fields: {
+            ns,
+            vid: real.id,
+            values: real.vector,
+            metadata: real.metadata ?? null,
+            data: real.data ?? '',
+            gone: false,
+        },
+    };
+}
+/**
+ * A namespace observed on the vendor, so `list-namespaces` reflects a pull.
+ *
+ * Uses the store's `namespaceSubjectId` rather than re-implementing it. §9 round 2 found this
+ * function had drifted into its own bare `encodeURIComponent` call, which meant (a) two
+ * implementations of one subject key, a latent collision risk, and (b) the surrogate guard added
+ * to `encodeKeyPart` did not cover it — so `mapNamespace('\ud800')` still threw a raw `URIError`
+ * off the pull's hot path, after `listNamespaces()` had already been paid for. One implementation,
+ * one guard.
+ */
+export function mapNamespace(name) {
+    return { type: 'namespace', id: namespaceSubjectId(name), fields: { name, gone: false } };
+}
+/** The float32 width the index stores — see `upstashvector-store.ts`'s `readVector`. */
+const FLOAT32_MAX = 3.4028234663852886e38;
+/** Refuse a vendor vector this twin cannot store faithfully, naming the id. */
+function assertStorableVector(vector, id) {
+    if (!Array.isArray(vector) || vector.length === 0) {
+        throw new VectorApiError(`upstashvector connector: vector '${id}' arrived with no coordinates`, 422);
+    }
+    for (const n of vector) {
+        if (typeof n !== 'number' || !Number.isFinite(n) || Math.abs(n) > FLOAT32_MAX) {
+            throw new VectorApiError(`upstashvector connector: vector '${id}' has a coordinate this index cannot store (${String(n)}) — `
+                + 'refusing rather than coercing it, which would substitute a different vector for the real one', 422);
+        }
+    }
+}
+/** One page of the vendor's `/range` response, defensively narrowed. */
+function readRangePage(raw) {
+    const o = (raw ?? {});
+    const vectors = [];
+    for (const item of Array.isArray(o.vectors) ? o.vectors : []) {
+        const v = (item ?? {});
+        if (typeof v.id !== 'string' && typeof v.id !== 'number')
+            continue;
+        // A row with no coordinates is SKIPPED rather than stored as an empty vector: a zero-length
+        // vector scores against nothing, so persisting one would put a permanently unrankable row in
+        // the twin that looks like real data. (`includeVectors` is always requested below, so a
+        // missing `vector` here means the vendor genuinely did not return one.)
+        if (!Array.isArray(v.vector) || v.vector.length === 0)
+            continue;
+        vectors.push({
+            id: String(v.id),
+            // NOT `.map(Number)`: coercing here is what turned a non-numeric vendor coordinate into a
+            // silent 0 (via NaN -> JSON null -> Number(null)). The raw values are carried through and
+            // `mapVector` refuses anything unstorable, by id (§9 round 2).
+            vector: v.vector,
+            metadata: v.metadata !== null && typeof v.metadata === 'object' ? v.metadata : null,
+            data: typeof v.data === 'string' ? v.data : null,
+        });
+    }
+    return { nextCursor: typeof o.nextCursor === 'string' ? o.nextCursor : '', vectors };
+}
+/**
+ * Walk ONE namespace with `/range`, bounded by `limit`.
+ *
+ * The bound is the point: an unbounded walk of a production index is precisely the spend this
+ * connector's budget exists to stop, and an entrypoint that offered one would be inviting the
+ * caller to burn a whole allowance in a loop.
+ */
+export async function pullUpstashVectorRange(rawClient, opts = {}) {
+    const client = guardUpstashVectorClient(rawClient, upstashvectorBudgetOf(opts));
+    if (!client.range)
+        return [];
+    const namespace = opts.namespace ?? DEFAULT_NAMESPACE;
+    const limit = opts.limit ?? 100;
+    const pageSize = Math.max(1, Math.min(opts.pageSize ?? 50, limit));
+    const found = [];
+    let cursor = '';
+    // A bounded loop, not a `while (cursor !== '')`: a vendor that never returns an empty cursor must
+    // not be able to spin this forever, and the budget must not be the only thing that stops it.
+    for (let page = 0; page < 100 && found.length < limit; page++) {
+        const raw = await client.range({ cursor, limit: pageSize, includeMetadata: true, includeVectors: true, includeData: true }, { namespace });
+        const { nextCursor, vectors } = readRangePage(raw);
+        for (const v of vectors)
+            found.push({ ...v, namespace });
+        if (nextCursor === '' || vectors.length === 0)
+            break;
+        cursor = nextCursor;
+    }
+    return found.slice(0, limit);
+}
+/**
+ * Discover the namespaces that exist on the vendor. A client without `listNamespaces` observes
+ * only the default namespace, which is the honest floor rather than an invented list.
+ */
+export async function pullUpstashVectorNamespaces(rawClient, opts = {}) {
+    const client = guardUpstashVectorClient(rawClient, upstashvectorBudgetOf(opts));
+    if (!client.listNamespaces)
+        return [DEFAULT_NAMESPACE];
+    const names = await client.listNamespaces();
+    const out = Array.isArray(names) ? names.filter((n) => typeof n === 'string') : [];
+    return out.includes(DEFAULT_NAMESPACE) ? out : [DEFAULT_NAMESPACE, ...out];
+}
+/**
+ * D7 entry point: pull the current real state of an index and fold it into the twin via ONE
+ * one observation. Returns `{observed, deltasAppended}` — a re-pull of identical
+ * state appends ZERO deltas, which is what makes the pull idempotent.
+ */
+export async function syncUpstashVectorFromReal(rawClient, opts = {}) {
+    // Guard ONCE here and hand the guarded client down: the per-namespace loop is unbounded in
+    // namespace count, so this is the entrypoint that must be unable to run unbudgeted.
+    const client = guardUpstashVectorClient(rawClient, upstashvectorBudgetOf(opts));
+    const occurredAt = opts.occurredAt ?? new Date().toISOString();
+    const namespaces = opts.namespaces ?? await pullUpstashVectorNamespaces(client);
+    const resources = [];
+    for (const ns of namespaces) {
+        // The DEFAULT namespace ('') is not state — it always exists on every index and the twin's own
+        // store synthesizes it in `listNamespaces` rather than holding a subject for it. Minting one
+        // from the pull gave an observed subject the write handler could never produce, which is a
+        // shape a branch would behave differently on. (Shape parity, 2026-09-08.)
+        if (ns !== '')
+            resources.push(mapNamespace(ns));
+        const budgetOpts = {
+            ...(opts.limit !== undefined ? { limit: opts.limit } : {}),
+            ...(opts.pageSize !== undefined ? { pageSize: opts.pageSize } : {}),
+        };
+        for (const v of await pullUpstashVectorRange(client, { namespace: ns, ...budgetOpts })) {
+            resources.push(mapVector(v));
+        }
+    }
+    const result = ((__at) => observeResources(SERVICE, resources, { ...(opts.root !== undefined ? { root: opts.root } : {}), at: __at, batch: `obs:${SERVICE}:${__at}` }))(occurredAt);
+    return { observed: resources.length, deltasAppended: result.appended };
+}
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+/**
+ * An `UpstashVectorLikeClient` over the kernel's executor. At a REAL boundary the kernel sets the
+ * sealed credential over these headers (executor.ts); at the twin's own wire any credential is one.
+ *
+ * EVERY call is a POST, whatever the docs spell: `@upstash/vector`'s `HttpClient.request` hardcodes
+ * it, so a client that sent the documented method would be talking to a surface the real SDK never
+ * uses. Namespaces are a PATH SUFFIX, not a body field.
+ */
+export function upstashVectorClientOver(execute) {
+    const post = async (path, body) => {
+        const res = await execute({
+            method: 'POST', path,
+            headers: { accept: 'application/json', 'content-type': 'application/json', authorization: 'Bearer twin' },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+        let parsed = {};
+        try {
+            parsed = JSON.parse(res.body || '{}');
+        }
+        catch {
+            parsed = {};
+        }
+        if (res.status < 200 || res.status >= 300) {
+            throw new Error(`upstash vector POST ${path} refused: HTTP ${res.status} ${JSON.stringify(parsed).slice(0, 200)}`);
+        }
+        // UNWRAP `result`, because the real SDK does. Every Upstash Vector reply is `{result: …}` and
+        // `@upstash/vector`'s HttpClient hands the caller the INNER value; a client that returned the
+        // envelope would be a shape this connector's parsers have never seen, and they would quietly
+        // find no vectors rather than fail. (Shape parity caught exactly that, 2026-09-08.)
+        return parsed?.result !== undefined ? parsed.result : parsed;
+    };
+    return {
+        info: () => post('/info'),
+        listNamespaces: async () => {
+            const answered = await post('/list-namespaces');
+            return (Array.isArray(answered) ? answered : []).map((n) => String(n));
+        },
+        range: (args, opts) => post(opts?.namespace ? `/range/${encodeURIComponent(opts.namespace)}` : '/range', args),
+    };
+}
+/** The refresh adapter: Upstash Vector enumerates (`/list-namespaces`, then `/range` per
+ *  namespace), so the whole index comes back without the world having to say what it holds. */
+export async function syncUpstashVectorFromRemote(execute, opts = {}) {
+    // Guarded here as well as inside `syncUpstashVectorFromReal`: the guard is idempotent (an
+    // already-guarded client comes back unchanged), and stating it at every entrypoint is what the
+    // source tooth in upstashvector-budget.test.ts holds this connector to.
+    const client = guardUpstashVectorClient(upstashVectorClientOver(execute), upstashvectorBudgetOf(opts));
+    return syncUpstashVectorFromReal(client, {
+        ...(opts.root !== undefined ? { root: opts.root } : {}),
+        occurredAt: opts.occurredAt ?? new Date().toISOString(),
+    });
+}
+/**
+ * The perform adapter: an upsert and a delete cross; a namespace reset does too. Everything else a
+ * world records about its index — a query it ran, a count it took — is a READ at the vendor and has
+ * nothing to write.
+ */
+export async function performUpstashVectorAction(execute, action, _ctx) {
+    const op = action.operation ?? `${action.subject.type}.update`;
+    const fields = (action.fields ?? {});
+    // `ns`, not `namespace` — the store's own name for it, and the default namespace is the empty
+    // string, which is a PATH SUFFIX of nothing rather than a segment.
+    const nsName = typeof fields.ns === 'string' ? fields.ns : typeof fields.namespace === 'string' ? fields.namespace : '';
+    const ns = nsName === '' ? '' : `/${encodeURIComponent(nsName)}`;
+    const post = async (path, body) => {
+        const res = await execute({
+            method: 'POST', path,
+            headers: { accept: 'application/json', 'content-type': 'application/json', authorization: 'Bearer twin' },
+            body: JSON.stringify(body),
+        });
+        if (res.status < 200 || res.status >= 300)
+            throw new Error(`upstash vector POST ${path} refused: HTTP ${res.status} ${res.body.slice(0, 200)}`);
+        try {
+            return JSON.parse(res.body || '{}');
+        }
+        catch {
+            return {};
+        }
+    };
+    // READ THE FIELD NAMES THE STORE ACTUALLY USES. The subject is `vec:<namespace>:<id>` and its
+    // fields are `{ ns, vid, values, data, metadata }` — not `{ id, vector }`. The first version of
+    // this adapter guessed the latter and therefore sent NO vector, an id still carrying its `vec::`
+    // prefix, and `data: ''` — which asks the vendor to EMBED an empty string and is refused by an
+    // index with no embedding model. Nothing in the gates exercises a perform, so it passed them all.
+    const vid = typeof fields.vid === 'string' && fields.vid ? fields.vid : action.subject.id.replace(/^vec:[^:]*:/, '');
+    const values = Array.isArray(fields.values) ? fields.values : Array.isArray(fields.vector) ? fields.vector : null;
+    const data = typeof fields.data === 'string' && fields.data !== '' ? fields.data : null;
+    if (op === 'vector.upsert' || op === 'vector.update') {
+        const answered = await post(`/upsert${ns}`, {
+            id: vid,
+            // A vector OR data — never both, and never an empty `data`, which is not "no data" to this
+            // vendor but "embed the empty string".
+            ...(values === null ? {} : { vector: values }),
+            ...(values === null && data !== null ? { data } : {}),
+            ...(fields.metadata !== undefined && fields.metadata !== null ? { metadata: fields.metadata } : {}),
+        });
+        return { externalId: vid, data: answered };
+    }
+    if (op === 'vector.delete') {
+        return { externalId: vid, data: await post(`/delete${ns}`, { ids: [vid] }) };
+    }
+    return { externalId: action.subject.id, data: { performed: false, reason: `${op} is a read at Upstash Vector — there is nothing to write for it` } };
+}

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

@@ -0,0 +1,80 @@
+/** A filter that could not be parsed. The handler maps this to the vendor's 400 envelope. */
+export declare class FilterError extends Error {
+    constructor(message: string);
+}
+export type TokenKind = 'ident' | 'string' | 'number' | 'op' | 'word' | 'punct';
+export type Token = {
+    kind: TokenKind;
+    value: string;
+    pos: number;
+};
+/**
+ * Split a filter string into tokens.
+ *
+ * Identifiers carry their `.`/`[]` accessors as ONE token (`geography.coordinates.latitude`,
+ * `major_industries[0]`, `tags[#-1]`) because the path is resolved as a unit at evaluation time;
+ * splitting them would force the parser to re-join them and lose the distinction between the
+ * accessor dot and a decimal point.
+ */
+export declare function tokenizeFilter(input: string): Token[];
+export type FilterValue = string | number | boolean;
+export type ComparisonOp = '=' | '!=' | '<' | '>' | '<=' | '>=' | 'GLOB' | 'NOT GLOB' | 'CONTAINS' | 'NOT CONTAINS';
+export type FilterNode = {
+    kind: 'and';
+    left: FilterNode;
+    right: FilterNode;
+} | {
+    kind: 'or';
+    left: FilterNode;
+    right: FilterNode;
+} | {
+    kind: 'compare';
+    path: string;
+    op: ComparisonOp;
+    value: FilterValue;
+} | {
+    kind: 'in';
+    path: string;
+    negated: boolean;
+    values: FilterValue[];
+} | {
+    kind: 'hasField';
+    path: string;
+    negated: boolean;
+};
+/** Parse a filter string into an AST. Throws `FilterError` on anything malformed. */
+export declare function parseFilter(filter: string): FilterNode;
+/** One step of a metadata path: an object key, or an array subscript. */
+type PathStep = {
+    key: string;
+} | {
+    index: number;
+    fromEnd: boolean;
+};
+/**
+ * Split `geography.coordinates[0]` / `tags[#-1]` into steps.
+ *
+ * `[#-1]` is the docs' "index from the back using the `#` character with negative values": the
+ * `#` marks end-relative addressing and the value that follows is the offset, so `[#-1]` is the
+ * LAST element. A plain `[0]` is head-relative.
+ */
+export declare function parsePath(path: string): PathStep[];
+/** The sentinel for "this path is not present". Distinct from a stored `null`, which IS present. */
+export declare const MISSING: unique symbol;
+/** Resolve a metadata path. Returns `MISSING` when any step is absent. */
+export declare function resolvePath(metadata: unknown, path: string): unknown | typeof MISSING;
+/**
+ * SQLite-style GLOB: `*` any run, `?` one character, `[abc]` a class, `[^abc]` a negated class,
+ * `[a-z]` a range. Case-SENSITIVE (that is what distinguishes GLOB from LIKE).
+ *
+ * Implemented as a backtracking matcher rather than by translating to a RegExp: a translation has
+ * to escape every regex metacharacter that is ORDINARY in a glob (`.`, `+`, `(`, `$`, …), and
+ * missing one turns a filter into a different filter — a silent wrong-answer bug rather than an
+ * error. The docs' own example, `city GLOB '?[sz]*[^m-z]'`, exercises all four constructs.
+ */
+export declare function globMatch(pattern: string, subject: string): boolean;
+/** Evaluate a parsed filter against one vector's metadata. */
+export declare function evaluateFilter(node: FilterNode, metadata: unknown): boolean;
+/** Parse + evaluate in one step. Exported for the handler's single call site. */
+export declare function matchesFilter(filter: string, metadata: unknown): boolean;
+export {};