@volter/twin-upstashvector 0.1.0

package/dist/src/upstashvector-store.js

@@ -0,0 +1,883 @@
+// THE VECTOR INDEX CORE — a real, stateful Upstash Vector index folded out of the @volter/world-core
+// kernel action log. This is the file that makes this pack a twin rather than a stub: `/query`
+// returns the vectors `/upsert` actually wrote, RANKED BY A SCORE COMPUTED FROM THE STORED
+// COORDINATES with Upstash's own published normalization, a dimension mismatch is refused the way
+// the vendor refuses it, and metadata filtering runs a real parsed expression over real metadata.
+//
+// ── GROUNDED (2026-08-19) — see spec-sources.json ─────────────────────────────────────────────
+//   (a) upstash.com/docs/vector/api/endpoints/{upsert,query,fetch,range,delete,reset,info} — the
+//       request/response JSON of every endpoint, quoted in each method's docstring below;
+//   (b) upstash.com/docs/vector/features/{namespaces,filtering,similarityfunctions,metadata};
+//   (c) the ACTUALLY-INSTALLED `@upstash/vector@1.2.3` package's own compiled source
+//       (node_modules/@upstash/vector/dist/chunk-*.mjs — its HttpClient and every Command's
+//       endpoint construction), read read-only. This is where the SDK-shaped facts come from:
+//       every command is sent as **POST** regardless of the documented method, namespaces are a
+//       PATH SUFFIX, `reset({all:true})` is `reset?all`, and `queryMany` posts an ARRAY to
+//       `/query`.
+// Unlike its sibling `upstash`, this pack could NOT live-probe a real index (no account), so
+// error STRINGS that Upstash does not publish are twin-authored rather than verbatim. Exactly one
+// error message here is quoted from the vendor's own docs — the dimension mismatch — and it is
+// marked as such. The README's ## Coverage says which is which; nothing below claims a vendor
+// string it did not read.
+//
+// ── STATE LIVES IN THE KERNEL, NOT IN A MAP ───────────────────────────────────────────────────
+// Every vector is ONE kernel subject (`type:'vector'`, id `vec:<ns>:<id>`), written through
+// `applyTwinWrite` and read back through `projectResources`. Namespaces and the index's own
+// configuration are their own subject types. There is no side-store: kill the process, point a new
+// one at the same root, and `/query` still ranks the same vectors.
+//
+// ── THE SCORES ARE COMPUTED, NEVER FAKED ──────────────────────────────────────────────────────
+// `similarityScore` implements the three formulas Upstash publishes, verbatim, at
+// upstash.com/docs/vector/features/similarityfunctions:
+//     COSINE       (1 + cosine_similarity(v1, v2)) / 2
+//     EUCLIDEAN    1 / (1 + squared_distance(v1, v2))
+//     DOT_PRODUCT  (1 + dot_product(v1, v2)) / 2
+// so a caller can hand-check any ranking this twin produces with a calculator. That is the whole
+// point: a vector twin whose `score` was a counter, a random number, or an insertion-order rank
+// would let a broken retrieval pipeline pass its tests.
+import { applyTwinWrite, projectResources } from '@volter/world-core';
+import { FilterError, matchesFilter, parseFilter, evaluateFilter } from "./upstashvector-filter.js";
+export const SERVICE = 'upstashvector';
+/** The default namespace is named `""` (empty string) — upstash.com/docs/vector/features/namespaces. */
+export const DEFAULT_NAMESPACE = '';
+/** The three metrics an Upstash Vector index can be created with (`/info`.similarityFunction). */
+export const SIMILARITY_FUNCTIONS = ['COSINE', 'EUCLIDEAN', 'DOT_PRODUCT'];
+/** The `/info`.indexType values. This twin models DENSE only; see `UNSUPPORTED_SPARSE`. */
+export const DEFAULT_SIMILARITY = 'COSINE';
+/**
+ * A vendor-shaped API failure: a message and the HTTP status it is served with.
+ *
+ * The status codes are the ones upstash.com/docs/vector/api/get-started enumerates — 400 for
+ * "syntax/command errors", 401 for auth, 405 for an unsupported method — plus the 422 the upsert
+ * endpoint's own error example shows for a dimension mismatch.
+ */
+export class VectorApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'VectorApiError';
+    }
+}
+/** Thrown when a write is attempted against a read-only twin. Mapped to HTTP 405 by the handler. */
+export class ReadOnlyError extends Error {
+    constructor() {
+        super('read_only: this twin was started read-only; omit readOnly to accept writes');
+        this.name = 'ReadOnlyError';
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// THE MATH — real, deterministic, hand-checkable
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+/**
+ * Refuse to score vectors of different lengths.
+ *
+ * Every one of these functions is EXPORTED, so a consumer (or a reviewer) can call them directly,
+ * and a naive `for (i < a.length)` loop silently ignores b's extra coordinates — computing a
+ * confident number from a truncated overlap. `dotProduct([1,2], [1,2,3])` would answer 5 as though
+ * the third dimension did not exist. A wrong similarity is far worse than a thrown error, because
+ * it flows straight into a ranking that still looks plausible. (The request path never reaches
+ * here with a mismatch — `checkDimension` refuses it with the vendor's 422 first — so this guard
+ * exists for the direct-call surface.)
+ */
+function assertSameLength(a, b) {
+    if (a.length !== b.length) {
+        throw new VectorApiError(`upstashvector: cannot compare vectors of different dimensions (${a.length} vs ${b.length})`, 422);
+    }
+}
+/** Σ aᵢ·bᵢ. */
+export function dotProduct(a, b) {
+    assertSameLength(a, b);
+    let sum = 0;
+    for (let i = 0; i < a.length; i++)
+        sum += a[i] * b[i];
+    return sum;
+}
+/** Σ (aᵢ−bᵢ)² — the SQUARED euclidean distance, which is what the vendor's formula takes. */
+export function squaredDistance(a, b) {
+    assertSameLength(a, b);
+    let sum = 0;
+    for (let i = 0; i < a.length; i++) {
+        const d = a[i] - b[i];
+        sum += d * d;
+    }
+    return sum;
+}
+/**
+ * dot(a,b) / (‖a‖·‖b‖).
+ *
+ * ZERO-VECTOR EDGE (twin-defined, and the vendor does not document it): the true cosine of a
+ * zero-length vector is undefined — the denominator is 0. Returning the raw `0/0` would put a
+ * `NaN` into the score, which `JSON.stringify` renders as `null`, so a caller would receive a
+ * result row whose `score` key was null and no error anywhere. This returns 0 (a normalized score
+ * of exactly 0.5, "no information") instead, so the response stays well-typed. Documented in the
+ * README's ## Coverage as an unverified edge rather than presented as vendor behaviour.
+ */
+export function cosineSimilarity(a, b) {
+    assertSameLength(a, b);
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    const denom = Math.sqrt(na) * Math.sqrt(nb);
+    return denom === 0 ? 0 : dot / denom;
+}
+/**
+ * The NORMALIZED score Upstash returns, per metric. Quoted verbatim from
+ * upstash.com/docs/vector/features/similarityfunctions:
+ *   COSINE       "(1 + cosine_similarity(v1, v2)) / 2"
+ *   EUCLIDEAN    "1 / (1 + squared_distance(v1, v2))"
+ *   DOT_PRODUCT  "(1 + dot_product(v1, v2)) / 2"
+ * All three are monotonically increasing in similarity, so a higher score is always a better match.
+ */
+export function similarityScore(fn, a, b) {
+    switch (fn) {
+        case 'COSINE': return (1 + cosineSimilarity(a, b)) / 2;
+        case 'EUCLIDEAN': return 1 / (1 + squaredDistance(a, b));
+        case 'DOT_PRODUCT': return (1 + dotProduct(a, b)) / 2;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// SUBJECT IDS
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+/**
+ * A vector's kernel subject id.
+ *
+ * Both components are percent-encoded, which is what makes the join UNAMBIGUOUS: `encodeURIComponent`
+ * escapes `:` to `%3A`, so a namespace named `a` holding id `b:c` and a namespace named `a:b`
+ * holding id `c` produce different subject ids. A naive `vec:${ns}:${id}` would map both to
+ * `vec:a:b:c` — one vector silently overwriting the other, across namespaces, which is precisely
+ * the isolation namespaces exist to provide.
+ */
+export function vectorSubjectId(ns, vid) {
+    return `vec:${encodeKeyPart(ns, 'namespace')}:${encodeKeyPart(vid, 'vector id')}`;
+}
+/** A namespace's kernel subject id. */
+export function namespaceSubjectId(ns) {
+    return `ns:${encodeKeyPart(ns, 'namespace')}`;
+}
+/**
+ * Percent-encode one subject-key component, refusing what cannot be encoded.
+ *
+ * `encodeURIComponent` THROWS a raw `URIError` on an unpaired UTF-16 surrogate, and `JSON.parse`
+ * happily produces one from `"\ud800"` — so before this guard a lone surrogate in an id escaped as
+ * an unhandled `URIError`: a twin-attributed HTTP 500 on `/upsert`, and (worse) a raw throw out of
+ * `mapVector` on the connector's hot path, AFTER the vendor calls had already been paid for. §9
+ * round 1 found both.
+ *
+ * It is refused rather than repaired on purpose. The tempting fix — replacing the surrogate, or
+ * round-tripping through UTF-8 — maps DIFFERENT ids onto the SAME bytes (every lone surrogate
+ * becomes U+FFFD), which would silently merge two distinct vectors: a collision in the one place
+ * this module works hardest to make collisions impossible. A 400 is the honest answer.
+ *
+ * HONESTY: Upstash's own behaviour for a lone-surrogate id is UNVERIFIED (no live index to probe),
+ * so this status/message is the twin's own — see `upstashvector.errors.vendor_error_strings`.
+ */
+function encodeKeyPart(value, what) {
+    try {
+        return encodeURIComponent(value);
+    }
+    catch {
+        throw new VectorApiError(`upstashvector: ${what} contains an unpaired UTF-16 surrogate and cannot be addressed — refusing rather than lossily rewriting it (two different ids would collapse onto one)`, 400);
+    }
+}
+/** The single index-configuration subject. */
+export const CONFIG_SUBJECT_ID = 'config:index';
+/** The kernel subject types this twin writes. Mirrored by the conformance check. */
+export const UPSTASHVECTOR_RESOURCE_TYPES = ['vector', 'namespace', 'config'];
+/**
+ * A synchronous in-memory image of the whole index for the duration of ONE request.
+ *
+ * Seeded from `projectResources` (the kernel IS the source of truth); every mutation records what
+ * it touched, and `flush` writes exactly those subjects back. Nothing here outlives the request —
+ * no cache, no singleton, no state a later request could inherit.
+ */
+export class IndexSpace {
+    ctx;
+    rows = new Map(); // subjectId → row
+    namespaces = new Set();
+    touched = new Map();
+    /** subjectId → the last write ordinal seen, INCLUDING for subjects currently deleted. */
+    revs = new Map();
+    dimension;
+    similarity;
+    configDirty = false;
+    /** True when stored vectors disagree on length, so no dimension can be honestly inferred. */
+    mixedDimensions = false;
+    constructor(ctx) {
+        this.ctx = ctx;
+        let storedDimension = null;
+        let storedSimilarity = null;
+        for (const r of projectResources(SERVICE, ctx.root)) {
+            const rec = r;
+            if (r.type === 'config' && r.id === CONFIG_SUBJECT_ID) {
+                if (typeof rec._rev === 'number')
+                    this.revs.set(r.id, rec._rev);
+                if (typeof rec.dimension === 'number')
+                    storedDimension = rec.dimension;
+                if (typeof rec.similarity === 'string' && SIMILARITY_FUNCTIONS.includes(rec.similarity)) {
+                    storedSimilarity = rec.similarity;
+                }
+                continue;
+            }
+            if (r.type === 'namespace') {
+                if (typeof rec._rev === 'number')
+                    this.revs.set(r.id, rec._rev);
+                if (rec.gone !== true && typeof rec.name === 'string')
+                    this.namespaces.add(rec.name);
+                continue;
+            }
+            if (r.type !== 'vector')
+                continue;
+            // Record the ordinal FIRST, for deleted rows too: a vector that is later re-upserted must
+            // CONTINUE the sequence rather than restart it, or a same-millisecond rewrite of a value the
+            // subject ALREADY held would hash to an action that already exists and be dropped as a
+            // replay — the reply reporting success while state kept the old value. (The identical
+            // hazard `upstash-store.ts` documents at `KeyRow._rev`.)
+            if (typeof rec._rev === 'number')
+                this.revs.set(r.id, rec._rev);
+            if (rec.gone === true)
+                continue;
+            if (typeof rec.ns !== 'string' || typeof rec.vid !== 'string' || !Array.isArray(rec.values))
+                continue;
+            // REHYDRATION GUARD. Coordinates come back out of JSON, where a NaN was serialised as `null`
+            // and `Number(null)` is 0 — so a coercing read silently substitutes a real coordinate with
+            // zero, and a non-finite one poisons every score it touches into `"score": null` on the wire.
+            // §9 round 2 found both reachable through the connector. A row that cannot be read as a
+            // vector of finite numbers is treated as corrupt and excluded, exactly like the shape checks
+            // on the line above — it can then neither be ranked nor rank anything else wrongly.
+            const values = rec.values.map((n) => (typeof n === 'number' ? n : Number.NaN));
+            if (!values.every((n) => Number.isFinite(n) && Math.abs(n) <= FLOAT32_MAX))
+                continue;
+            this.rows.set(r.id, {
+                ns: rec.ns,
+                vid: rec.vid,
+                values,
+                metadata: rec.metadata !== null && typeof rec.metadata === 'object' ? rec.metadata : null,
+                data: typeof rec.data === 'string' && rec.data !== '' ? rec.data : null,
+                ...(typeof rec._rev === 'number' ? { _rev: rec._rev } : {}),
+            });
+        }
+        // The DEFAULT namespace always exists — `/info` lists it even on an empty index.
+        this.namespaces.add(DEFAULT_NAMESPACE);
+        // Server-supplied configuration is the index's creation-time setting and WINS over whatever a
+        // previous run inferred; otherwise the persisted value stands; otherwise the dimension stays
+        // open for the first upsert to lock in.
+        this.dimension = ctx.dimension ?? storedDimension;
+        this.similarity = ctx.similarityFunction ?? storedSimilarity ?? DEFAULT_SIMILARITY;
+        // INFER the dimension from the vectors themselves when nothing has declared one.
+        //
+        // The connector writes vectors but NOT the `config` subject (that gap is filed as
+        // upstashvector.connector.pull_index_configuration), so a freshly PULLED index used to sit at
+        // `dimension === null`. §9 round 1 showed how badly that degrades: `/info` reported
+        // `dimension: 0` while holding dim-3 vectors; `/query` with a dim-2 vector answered a silent
+        // `200 []` instead of the promised 422 (because `checkDimension` returns early on null and the
+        // ranker skips length-mismatched rows); and the next `/upsert` LOCKED IN the wrong dimension,
+        // permanently orphaning every pulled vector. Inferring here makes pulled state coherent with
+        // locally-written state on all three paths.
+        //
+        // Only adopted when every stored vector AGREES — a root holding mixed lengths (which the
+        // enforcement above prevents locally, but a pull could deliver) has no single honest answer,
+        // so it stays null rather than picking a winner and orphaning the rest. Inference is
+        // in-memory only: it deliberately does NOT set `configDirty`, so a READ never writes.
+        if (this.dimension === null && this.rows.size > 0) {
+            const lengths = new Set([...this.rows.values()].map((r) => r.values.length));
+            if (lengths.size === 1)
+                this.dimension = [...lengths][0];
+            else
+                this.mixedDimensions = true;
+        }
+        if (ctx.dimension !== undefined && ctx.dimension !== storedDimension)
+            this.configDirty = true;
+        if (ctx.similarityFunction !== undefined && ctx.similarityFunction !== storedSimilarity)
+            this.configDirty = true;
+    }
+    assertWritable() {
+        if (this.ctx.readOnly)
+            throw new ReadOnlyError();
+    }
+    /** The next write ordinal for a subject. Survives deletes — see the constructor's note. */
+    nextRev(subjectId) {
+        const next = (this.revs.get(subjectId) ?? 0) + 1;
+        this.revs.set(subjectId, next);
+        return next;
+    }
+    // ── configuration ──────────────────────────────────────────────────────────────────────────
+    /** The dimension this index enforces, or `null` while no upsert has locked one in yet. */
+    get indexDimension() { return this.dimension; }
+    get similarityFunction() { return this.similarity; }
+    /**
+     * Check a vector's length against the index, LOCKING the dimension in on the first upsert.
+     *
+     * The vendor's index has a dimension chosen at creation time and cannot change it. A local twin
+     * has no creation step, so the first upsert plays that role; from then on the check is exactly
+     * as strict as the vendor's, including the error, which is the ONE message in this pack quoted
+     * verbatim from the vendor's own docs (the /upsert endpoint's 422 example).
+     */
+    checkDimension(values, lockIn) {
+        if (this.dimension === null) {
+            if (!lockIn)
+                return; // a query against an index with nothing in it cannot mismatch
+            if (values.length === 0)
+                throw new VectorApiError('upstashvector: a vector must have at least one dimension', 422);
+            if (this.mixedDimensions) {
+                // The index already holds vectors of DIFFERENT lengths — a state only a pull can produce
+                // (local writes are dimension-checked). Letting this upsert lock a dimension in would pick
+                // an arbitrary winner and permanently orphan every vector of the other length: §9 round 2
+                // showed exactly that happening one request after the mixed pull, which is the round-1
+                // defect the "stay null" branch was supposed to prevent and did not. Refusing is what
+                // actually delivers the stated intent.
+                throw new VectorApiError('upstashvector: this index holds vectors of differing dimensions, so no dimension can be inferred — '
+                    + 'start the twin with an explicit dimension (--dimension N) rather than letting this write orphan the others', 422);
+            }
+            this.dimension = values.length;
+            this.configDirty = true;
+            return;
+        }
+        if (values.length !== this.dimension) {
+            // VERBATIM from upstash.com/docs/vector/api/endpoints/upsert's own 422 example:
+            //   {"error": "Invalid vector dimension: 2, expected: 256", "status": 422}
+            throw new VectorApiError(`Invalid vector dimension: ${values.length}, expected: ${this.dimension}`, 422);
+        }
+    }
+    // ── namespaces ─────────────────────────────────────────────────────────────────────────────
+    /** Every namespace that currently exists, default first then lexicographic (deterministic). */
+    listNamespaces() {
+        const rest = [...this.namespaces].filter((n) => n !== DEFAULT_NAMESPACE).sort();
+        return [DEFAULT_NAMESPACE, ...rest];
+    }
+    hasNamespace(ns) { return this.namespaces.has(ns); }
+    ensureNamespace(ns) {
+        if (this.namespaces.has(ns))
+            return;
+        this.namespaces.add(ns);
+        this.touched.set(namespaceSubjectId(ns), { kind: 'namespace', ns, operation: 'namespace.create', alive: true });
+    }
+    /**
+     * `POST|DELETE /delete-namespace/{ns}` — remove a namespace AND everything in it.
+     *
+     * Distinct from `/reset/{ns}`, which empties a namespace but leaves it existing. Keeping both
+     * behaviours distinct is why namespaces are tracked as their own kernel subject rather than
+     * derived from "does any vector mention this name" — a derived model would make the two
+     * endpoints indistinguishable, which would quietly drop a real part of the vendor's surface.
+     *
+     * TWIN-DEFINED (unverified): deleting the DEFAULT namespace is refused. The default namespace
+     * has no name to address and `/reset` already empties it, so a request to remove it is far more
+     * likely to be a bug than an intent. Stated in the README's ## Coverage.
+     */
+    deleteNamespace(ns) {
+        this.assertWritable();
+        if (ns === DEFAULT_NAMESPACE) {
+            throw new VectorApiError('upstashvector: the default namespace cannot be deleted — use /reset to empty it', 400);
+        }
+        if (!this.namespaces.has(ns)) {
+            throw new VectorApiError(`upstashvector: namespace '${ns}' not found`, 404);
+        }
+        for (const row of this.vectorsIn(ns))
+            this.removeVector(row.ns, row.vid, 'namespace.delete');
+        this.namespaces.delete(ns);
+        this.touched.set(namespaceSubjectId(ns), { kind: 'namespace', ns, operation: 'namespace.delete', alive: false });
+    }
+    // ── vectors ────────────────────────────────────────────────────────────────────────────────
+    /** Every live vector in one namespace, in a DETERMINISTIC order (id ascending). */
+    vectorsIn(ns) {
+        return [...this.rows.values()].filter((r) => r.ns === ns).sort((a, b) => (a.vid < b.vid ? -1 : a.vid > b.vid ? 1 : 0));
+    }
+    getVector(ns, vid) {
+        return this.rows.get(vectorSubjectId(ns, vid));
+    }
+    putVector(row, operation) {
+        this.assertWritable();
+        const sid = vectorSubjectId(row.ns, row.vid);
+        this.rows.set(sid, row);
+        this.touched.set(sid, { kind: 'vector', ns: row.ns, vid: row.vid, operation, row });
+    }
+    removeVector(ns, vid, operation) {
+        this.assertWritable();
+        const sid = vectorSubjectId(ns, vid);
+        this.rows.delete(sid);
+        this.touched.set(sid, { kind: 'vector', ns, vid, operation, row: null });
+    }
+    /**
+     * `POST /upsert[/{ns}]` — insert or REPLACE whole vectors.
+     *
+     * Upsert REPLACES: the vendor's `/update` endpoint exists precisely because `/upsert` does not
+     * merge, so an upsert without `metadata` clears any metadata the id previously had. Getting this
+     * backwards would make `/update`'s whole reason for existing invisible.
+     *
+     * Returns the vendor's `{"result": "Success"}` payload string.
+     */
+    upsert(ns, items) {
+        this.assertWritable();
+        if (items.length === 0)
+            throw new VectorApiError('upstashvector: upsert requires at least one vector', 400);
+        const parsed = items.map((raw) => this.readUpsertItem(raw));
+        // Validate the WHOLE batch before writing any of it, so a bad element cannot leave the index
+        // half-updated. (The vendor's own batching semantics are unverified; refusing atomically is
+        // the conservative direction — it can never produce a partial state a caller did not ask for.)
+        for (const item of parsed)
+            this.checkDimension(item.values, true);
+        this.ensureNamespace(ns);
+        for (const item of parsed) {
+            this.putVector({ ns, vid: item.vid, values: item.values, metadata: item.metadata, data: item.data }, 'vector.upsert');
+        }
+        return 'Success';
+    }
+    /** Read one `/upsert` element: `{id, vector, metadata?, data?}`. */
+    readUpsertItem(raw) {
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+            throw new VectorApiError('upstashvector: each upsert element must be an object with an id and a vector', 400);
+        }
+        const o = raw;
+        const vid = readId(o.id);
+        if (o.sparseVector !== undefined) {
+            // An honest refusal, not a silent drop: this twin models DENSE indexes only, and accepting a
+            // sparseVector while ignoring it would make a hybrid-index caller's recall look fine while
+            // half their signal vanished. See the manifest's sparse/hybrid todos.
+            throw new VectorApiError('upstashvector: this twin models DENSE indexes only — sparseVector is not supported (upstashvector.sparse.upsert is the filed gap)', 422);
+        }
+        if (o.vector === undefined) {
+            // `data` WITHOUT `vector` is the /upsert-data embedding path, which needs the index's own
+            // embedding model. See `unsupportedEmbedding`.
+            if (o.data !== undefined)
+                throw unsupportedEmbedding();
+            throw new VectorApiError('upstashvector: upsert element is missing its `vector`', 400);
+        }
+        return { vid, values: readVector(o.vector), metadata: readMetadata(o.metadata), data: readData(o.data) };
+    }
+    /**
+     * `POST /update[/{ns}]` — partially modify ONE existing vector.
+     *
+     * `metadataUpdateMode` (from the vendor's update endpoint): `OVERWRITE` (the default) replaces
+     * the metadata object wholesale; `PATCH` merges the supplied keys over what is there.
+     * Returns `{updated: 0|1}` — 0 when the id does not exist, which is a normal answer, not an error.
+     */
+    update(ns, raw) {
+        this.assertWritable();
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+            throw new VectorApiError('upstashvector: update requires an object with an id', 400);
+        }
+        const o = raw;
+        const vid = readId(o.id);
+        const existing = this.getVector(ns, vid);
+        if (existing === undefined)
+            return { updated: 0 };
+        const mode = o.metadataUpdateMode === undefined ? 'OVERWRITE' : String(o.metadataUpdateMode).toUpperCase();
+        if (mode !== 'OVERWRITE' && mode !== 'PATCH') {
+            throw new VectorApiError(`upstashvector: metadataUpdateMode must be OVERWRITE or PATCH, got '${String(o.metadataUpdateMode)}'`, 400);
+        }
+        let values = existing.values;
+        if (o.vector !== undefined) {
+            values = readVector(o.vector);
+            this.checkDimension(values, true);
+        }
+        let metadata = existing.metadata;
+        if (o.metadata !== undefined) {
+            const next = readMetadata(o.metadata);
+            metadata = mode === 'PATCH' && existing.metadata !== null && next !== null ? { ...existing.metadata, ...next } : next;
+        }
+        const data = o.data !== undefined ? readData(o.data) : existing.data;
+        this.putVector({ ns, vid, values, metadata, data }, 'vector.update');
+        return { updated: 1 };
+    }
+    /**
+     * `POST /query[/{ns}]` — rank the namespace's vectors against a query vector.
+     *
+     * The ORDER: score DESCENDING, ties broken by id ASCENDING. The tie-break is TWIN-DEFINED (the
+     * vendor does not specify one) and exists so a verify that seeds two equidistant vectors gets a
+     * reproducible answer instead of whatever the map iteration happened to yield.
+     */
+    query(ns, raw) {
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+            throw new VectorApiError('upstashvector: query requires an object body', 400);
+        }
+        const o = raw;
+        if (o.data !== undefined && o.vector === undefined)
+            throw unsupportedEmbedding();
+        if (o.sparseVector !== undefined) {
+            throw new VectorApiError('upstashvector: this twin models DENSE indexes only — sparseVector queries are not supported (upstashvector.sparse.query is the filed gap)', 422);
+        }
+        if (o.vector === undefined)
+            throw new VectorApiError('upstashvector: query is missing its `vector`', 400);
+        const values = readVector(o.vector);
+        this.checkDimension(values, false);
+        const topK = o.topK === undefined ? 10 : readPositiveInt(o.topK, 'topK');
+        const predicate = compileFilter(o.filter);
+        const scored = [];
+        for (const row of this.vectorsIn(ns)) {
+            if (predicate !== null && !evaluateFilter(predicate, row.metadata))
+                continue;
+            // A stored vector whose length disagrees with the query's cannot be scored — this can only
+            // happen against state written before the dimension was locked in, and skipping it is
+            // better than producing a score from a truncated overlap.
+            if (row.values.length !== values.length)
+                continue;
+            scored.push({ row, score: similarityScore(this.similarity, values, row.values) });
+        }
+        scored.sort((a, b) => (b.score - a.score) || (a.row.vid < b.row.vid ? -1 : a.row.vid > b.row.vid ? 1 : 0));
+        return scored.slice(0, topK).map(({ row, score }) => ({ id: row.vid, score, ...projection(row, o) }));
+    }
+    /**
+     * `POST /fetch[/{ns}]` — look vectors up BY ID (or by id prefix), unranked.
+     *
+     * By ids: "Array elements can be `null` if no such vector exists with the provided id" (the
+     * vendor's own fetch doc), and the result is positionally aligned with the request. By prefix:
+     * only the matches, so no nulls.
+     */
+    fetch(ns, raw) {
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+            throw new VectorApiError('upstashvector: fetch requires an object body', 400);
+        }
+        const o = raw;
+        if (o.ids !== undefined) {
+            if (!Array.isArray(o.ids))
+                throw new VectorApiError('upstashvector: fetch `ids` must be an array', 400);
+            return o.ids.map((raw2) => {
+                const row = this.getVector(ns, readId(raw2));
+                return row === undefined ? null : { id: row.vid, ...projection(row, o) };
+            });
+        }
+        if (typeof o.prefix === 'string') {
+            return this.vectorsIn(ns).filter((r) => r.vid.startsWith(o.prefix)).map((row) => ({ id: row.vid, ...projection(row, o) }));
+        }
+        throw new VectorApiError('upstashvector: fetch requires `ids` or `prefix`', 400);
+    }
+    /**
+     * `POST /range[/{ns}]` — paginate the namespace in id order.
+     *
+     * The cursor is a decimal OFFSET as a string (the vendor's own example advances `""` → `"2"`),
+     * and `nextCursor` is `""` when the walk is finished. Ordering is id-ascending, which is what
+     * makes the offset cursor stable across pages.
+     */
+    range(ns, raw) {
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+            throw new VectorApiError('upstashvector: range requires an object body', 400);
+        }
+        const o = raw;
+        const limit = o.limit === undefined ? 10 : readPositiveInt(o.limit, 'limit');
+        const cursorRaw = o.cursor === undefined || o.cursor === '' ? '0' : String(o.cursor);
+        if (!/^\d+$/.test(cursorRaw))
+            throw new VectorApiError(`upstashvector: '${cursorRaw}' is not a valid range cursor`, 400);
+        const start = Number(cursorRaw);
+        let all = this.vectorsIn(ns);
+        if (typeof o.prefix === 'string')
+            all = all.filter((r) => r.vid.startsWith(o.prefix));
+        const page = all.slice(start, start + limit);
+        const next = start + page.length;
+        return {
+            // `""` means "no more" — so the cursor only advances while there is genuinely another page.
+            nextCursor: next >= all.length ? '' : String(next),
+            vectors: page.map((row) => ({ id: row.vid, ...projection(row, o) })),
+        };
+    }
+    /**
+     * `POST|DELETE /delete[/{ns}]` — by ids, by id prefix, or by metadata filter.
+     *
+     * Returns `{deleted: N}`, the vendor's own shape, where N counts vectors that ACTUALLY existed —
+     * deleting an unknown id is not an error and contributes 0.
+     */
+    delete(ns, raw) {
+        this.assertWritable();
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+            throw new VectorApiError('upstashvector: delete requires an object body', 400);
+        }
+        const o = raw;
+        const victims = [];
+        if (o.ids !== undefined) {
+            if (!Array.isArray(o.ids))
+                throw new VectorApiError('upstashvector: delete `ids` must be an array', 400);
+            for (const rawId of o.ids) {
+                const row = this.getVector(ns, readId(rawId));
+                if (row !== undefined)
+                    victims.push(row);
+            }
+        }
+        else if (typeof o.prefix === 'string') {
+            victims.push(...this.vectorsIn(ns).filter((r) => r.vid.startsWith(o.prefix)));
+        }
+        else if (typeof o.filter === 'string') {
+            const predicate = compileFilter(o.filter);
+            if (predicate === null) {
+                // An EMPTY filter string on a DELETE is refused rather than interpreted.
+                //
+                // On `/query` an empty filter harmlessly means "no filter" (and is treated that way). The
+                // SAME reading on `/delete` would mean "match every vector" — i.e. silently wipe the
+                // namespace because a caller's template rendered to an empty string. A twin must never
+                // guess in that direction, so this is an explicit 400.
+                //
+                // (Before this guard the empty string reached `evaluateFilter(null, …)` and produced a
+                // raw TypeError surfaced as a 500 — safe in that it deleted nothing, but the wrong status
+                // and an internal-fault message. Found by self-probe during the §9 pass.)
+                throw new VectorApiError('upstashvector: `filter` is empty — refusing to guess between "no criteria" and "match everything" on a delete; pass ids, prefix, or a non-empty filter', 400);
+            }
+            victims.push(...this.vectorsIn(ns).filter((r) => evaluateFilter(predicate, r.metadata)));
+        }
+        else {
+            throw new VectorApiError('upstashvector: delete requires `ids`, `prefix` or `filter`', 400);
+        }
+        // Dedupe: the same id listed twice must count once, or `{deleted}` would over-report.
+        const seen = new Set();
+        let deleted = 0;
+        for (const row of victims) {
+            const sid = vectorSubjectId(row.ns, row.vid);
+            if (seen.has(sid))
+                continue;
+            seen.add(sid);
+            this.removeVector(row.ns, row.vid, 'vector.delete');
+            deleted++;
+        }
+        return { deleted };
+    }
+    /**
+     * `POST|DELETE /reset[/{ns}]` and `/reset?all` — empty a namespace (or every namespace).
+     *
+     * Emptying, NOT removing: the namespaces themselves survive a reset. `?all` is how the SDK's
+     * `reset({all:true})` spells it (`ResetCommand` appends the bare `?all` query flag).
+     */
+    reset(opts) {
+        this.assertWritable();
+        if (opts.all === true) {
+            for (const row of [...this.rows.values()])
+                this.removeVector(row.ns, row.vid, 'index.reset_all');
+            return 'Success';
+        }
+        const ns = opts.namespace ?? DEFAULT_NAMESPACE;
+        for (const row of this.vectorsIn(ns))
+            this.removeVector(row.ns, row.vid, 'index.reset');
+        return 'Success';
+    }
+    /**
+     * `GET|POST /info` — index-wide counts and configuration.
+     *
+     * Shape quoted from upstash.com/docs/vector/api/endpoints/info. `pendingVectorCount` is always 0
+     * here and that is HONEST rather than a stub: the vendor's pending count reflects vectors still
+     * being indexed asynchronously, and this twin's upsert is synchronous, so nothing is ever
+     * pending. `indexSize` is a byte estimate; the vendor's exact accounting is not published, so
+     * this reports a computed, deterministic size (see `estimateIndexSize`) rather than a constant.
+     */
+    info() {
+        const namespaces = {};
+        for (const ns of this.listNamespaces()) {
+            namespaces[ns] = { vectorCount: this.vectorsIn(ns).length, pendingVectorCount: 0 };
+        }
+        const dimension = this.dimension ?? 0;
+        return {
+            vectorCount: this.rows.size,
+            pendingVectorCount: 0,
+            indexSize: this.estimateIndexSize(),
+            dimension,
+            similarityFunction: this.similarity,
+            indexType: 'DENSE',
+            denseIndex: { dimension, similarityFunction: this.similarity },
+            namespaces,
+        };
+    }
+    /**
+     * `indexSize`, computed with the VENDOR'S OWN PUBLISHED FORMULA.
+     *
+     * upstash.com/docs/vector/help/faq states it verbatim: "Each dimension is estimated to be 4
+     * bytes, resulting in vector storage being calculated as vector count * dimension count * 4
+     * bytes", and adds that the storage charge combines that with metadata (up to 48 KB/vector) and
+     * data (up to 1 MB/vector). So this is `dimensions x 4` per vector plus the encoded size of its
+     * metadata and data — not a twin invention. (An earlier draft said the vendor published no
+     * accounting and also counted the id's bytes, which the formula does not include; both were
+     * corrected once the FAQ was found during the §9 pass.)
+     *
+     * It stays an ESTIMATE in the vendor's own sense of the word, and it is a real function of real
+     * state — it grows when you add vectors and shrinks when you delete them.
+     */
+    estimateIndexSize() {
+        let bytes = 0;
+        for (const row of this.rows.values()) {
+            bytes += row.values.length * 4;
+            if (row.metadata !== null)
+                bytes += Buffer.byteLength(JSON.stringify(row.metadata), 'utf8');
+            if (row.data !== null)
+                bytes += Buffer.byteLength(row.data, 'utf8');
+        }
+        return bytes;
+    }
+    /** Did this run write anything? */
+    get dirty() { return this.touched.size > 0 || this.configDirty; }
+    /**
+     * Write every touched subject back to the kernel action log.
+     *
+     * The kernel MERGES fields, so a delete writes EVERY field back to its "nothing here" value —
+     * leaving `values`/`metadata` behind would let a later re-upsert of the same id inherit a dead
+     * coordinate array if it ever wrote a partial field set.
+     */
+    async flush() {
+        for (const pending of this.touched.values()) {
+            if (pending.kind === 'vector') {
+                const sid = vectorSubjectId(pending.ns, pending.vid);
+                const row = pending.row;
+                await applyTwinWrite(SERVICE, {
+                    operation: pending.operation,
+                    subjectType: 'vector',
+                    subjectId: sid,
+                    fields: row === null
+                        ? { ns: pending.ns, vid: pending.vid, values: [], metadata: null, data: '', gone: true, _rev: this.nextRev(sid) }
+                        : { ns: row.ns, vid: row.vid, values: row.values, metadata: row.metadata, data: row.data ?? '', gone: false, _rev: this.nextRev(sid) },
+                    occurredAt: this.ctx.occurredAt,
+                    actor: { kind: 'agent' },
+                }, this.ctx.root);
+                continue;
+            }
+            if (pending.kind === 'namespace') {
+                const sid = namespaceSubjectId(pending.ns);
+                await applyTwinWrite(SERVICE, {
+                    operation: pending.operation,
+                    subjectType: 'namespace',
+                    subjectId: sid,
+                    fields: { name: pending.ns, gone: !pending.alive, _rev: this.nextRev(sid) },
+                    occurredAt: this.ctx.occurredAt,
+                    actor: { kind: 'agent' },
+                }, this.ctx.root);
+            }
+        }
+        // A READ-ONLY twin must append NOTHING, including this.
+        //
+        // §9 round 1 found the hole: `configDirty` is set by the CONSTRUCTOR whenever the server was
+        // started with a `dimension`/`similarityFunction` that differs from what the root already
+        // holds — and `flush()` runs after every successful command, including a plain `GET /info`.
+        // So `world-upstashvector serve --read-only --dimension 4` appended an `index.configure`
+        // action on a pure READ. The capability calls this "the pure-mirror mode a pulled index is
+        // served in", and a pure mirror does not write. Every other write path is stopped by
+        // `assertWritable()`; this one was not, because nothing calls it.
+        if (this.configDirty && !this.ctx.readOnly) {
+            await applyTwinWrite(SERVICE, {
+                operation: 'index.configure',
+                subjectType: 'config',
+                subjectId: CONFIG_SUBJECT_ID,
+                fields: { dimension: this.dimension, similarity: this.similarity, _rev: this.nextRev(CONFIG_SUBJECT_ID) },
+                occurredAt: this.ctx.occurredAt,
+                actor: { kind: 'agent' },
+            }, this.ctx.root);
+        }
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// HELPERS
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+/**
+ * The refusal for every surface that needs the index's own embedding model — `/upsert-data`,
+ * `/query-data`, `/resumable-query-data`.
+ *
+ * A twin cannot run an embedding model, so it cannot turn `data` into a vector. Failing here is
+ * the honest answer and matches how a real index CREATED WITHOUT an embedding model behaves; the
+ * alternative — hashing the text into a pseudo-vector — would return confident nonsense rankings
+ * that look exactly like a working retrieval pipeline. The routes are filed as manifest gaps.
+ */
+function unsupportedEmbedding() {
+    return new VectorApiError('upstashvector: this index has no embedding model — send a `vector` instead of `data` '
+        + '(this twin runs no embedding model; upstashvector.embedding.upsert_data is the filed gap)', 422);
+}
+/** Compile a filter once per request, or `null` when the request has no filter. */
+function compileFilter(raw) {
+    if (raw === undefined || raw === null || raw === '')
+        return null;
+    if (typeof raw !== 'string')
+        throw new VectorApiError('upstashvector: `filter` must be a string', 400);
+    try {
+        return parseFilter(raw);
+    }
+    catch (e) {
+        if (e instanceof FilterError)
+            throw new VectorApiError(e.message, 400);
+        throw e;
+    }
+}
+/** The optional response fields, gated by the request's `include*` flags. */
+function projection(row, o) {
+    const out = {};
+    // The vendor OMITS an absent key rather than sending null (its fetch example shows `{"id":"id-1"}`
+    // with no `metadata` at all), so a caller checking `'metadata' in result` gets the right answer.
+    if (o.includeVectors === true)
+        out.vector = row.values;
+    if (o.includeMetadata === true && row.metadata !== null)
+        out.metadata = row.metadata;
+    if (o.includeData === true && row.data !== null)
+        out.data = row.data;
+    return out;
+}
+/** A vector id. The vendor accepts strings and numbers; both are carried as strings. */
+function readId(raw) {
+    if (typeof raw === 'string') {
+        if (raw === '')
+            throw new VectorApiError('upstashvector: vector id must not be empty', 400);
+        return raw;
+    }
+    if (typeof raw === 'number' && Number.isFinite(raw))
+        return String(raw);
+    throw new VectorApiError('upstashvector: vector id must be a string or a number', 400);
+}
+/** A dense vector: an array of finite numbers. NaN/Infinity are refused, not stored. */
+function readVector(raw) {
+    if (!Array.isArray(raw))
+        throw new VectorApiError('upstashvector: `vector` must be an array of numbers', 400);
+    const out = [];
+    for (const n of raw) {
+        if (typeof n !== 'number' || !Number.isFinite(n)) {
+            // A non-finite coordinate poisons every score it touches (and `JSON.stringify(NaN)` is
+            // `null`), so it is refused at the boundary rather than stored and discovered at query time.
+            throw new VectorApiError('upstashvector: `vector` must contain only finite numbers', 400);
+        }
+        if (Math.abs(n) > FLOAT32_MAX) {
+            // Bounding coordinates to FLOAT32 is what keeps the arithmetic total.
+            //
+            // §9 round 1 showed the hole this closes: `[1e308, 1e308]` is a perfectly finite float64
+            // pair, but squaring it overflows to Infinity, so COSINE produced NaN and DOT_PRODUCT
+            // produced Infinity — both of which `JSON.stringify` renders as `"score": null`, and both of
+            // which make the `(b.score - a.score)` comparator fall through to the id tie-break, silently
+            // degrading the ranking to alphabetical order. No error anywhere.
+            //
+            // WHERE THE BOUND COMES FROM, and what is fact vs inference (§9 round 2 corrected an
+            // overstatement here — an earlier comment asserted "Upstash Vector stores float32" as a
+            // vendor fact):
+            //   FACT     — upstash.com/docs/vector/help/faq, verbatim: "Each dimension is estimated to be
+            //              4 bytes, resulting in vector storage being calculated as vector count *
+            //              dimension count * 4 bytes." That is a BILLING estimate; the FAQ says nothing
+            //              about numeric precision, and neither does the pricing page, the similarity
+            //              page, or the SDK's types (coordinates are plain `number[]`).
+            //   INFERENCE— four bytes per dimension is the width of a float32, so a coordinate outside
+            //              float32 range is very unlikely to be representable by the real service.
+            // The bound is therefore chosen, not quoted — and it is safe in the direction that matters:
+            // it refuses only values ~1e38 and above, which no embedding model produces, while making
+            // the arithmetic TOTAL. With every coordinate inside float32, no sum of squares — over the
+            // vendor's documented 5,000-dimension maximum or vastly beyond it — can leave float64 range,
+            // so "a score is always a finite number" becomes a property of the arithmetic rather than a
+            // hope. Confirming the real precision needs a live index (upstashvector.limits.coordinate_precision).
+            throw new VectorApiError(`upstashvector: coordinate ${n} exceeds the float32 range this index stores — a value this large is not representable and would overflow the similarity arithmetic`, 400);
+        }
+        out.push(n);
+    }
+    return out;
+}
+/** The largest magnitude a float32 coordinate can hold. See `readVector`. */
+const FLOAT32_MAX = 3.4028234663852886e38;
+function readMetadata(raw) {
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw !== 'object' || Array.isArray(raw))
+        throw new VectorApiError('upstashvector: `metadata` must be a JSON object', 400);
+    return raw;
+}
+function readData(raw) {
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw !== 'string')
+        throw new VectorApiError('upstashvector: `data` must be a string', 400);
+    return raw === '' ? null : raw;
+}
+function readPositiveInt(raw, field) {
+    const n = typeof raw === 'number' ? raw : Number(raw);
+    if (!Number.isInteger(n) || n <= 0)
+        throw new VectorApiError(`upstashvector: \`${field}\` must be a positive integer`, 400);
+    return n;
+}
+/** Re-exported so the handler can map a filter parse failure without importing the filter module. */
+export { matchesFilter };