@volter/twin-upstashvector 0.1.0

package/src/upstashvector-filter.ts

@@ -0,0 +1,525 @@
+// UPSTASH VECTOR METADATA FILTERING — a REAL tokenizer, recursive-descent parser and evaluator for
+// the filter language documented at upstash.com/docs/vector/features/filtering.
+//
+// This is a genuine language implementation, not a substring match: `filter` strings arrive as
+// opaque text on `/query`, `/delete` and `/update`, and a twin that "supported filtering" by
+// checking `metadata[k] === v` for the one shape its own tests used would be exactly the fake
+// success this repo forbids. The grammar below is parsed to an AST and the AST is evaluated
+// against each candidate's metadata, so an expression the tests never anticipated still works and
+// a malformed one is REJECTED with a parse error rather than silently matching everything.
+//
+// ── GROUNDED (2026-08-19) ─────────────────────────────────────────────────────────────────────
+// upstash.com/docs/vector/features/filtering, quoted where it is quotable:
+//   • operators: `=`, `!=`, `<`, `>`, `<=`, `>=`, `GLOB`, `NOT GLOB`, `IN`, `NOT IN`, `CONTAINS`,
+//     `NOT CONTAINS`, `HAS FIELD`, `HAS NOT FIELD`, combined with `AND` / `OR`;
+//   • "Nested objects can be at arbitrary depths, so more than one `.` accessor can be used in the
+//     same identifier";
+//   • "individual array elements can also be filtered by referencing them with the `[]` accessor by
+//     their indexes", and "it is possible to index from the back using the `#` character with
+//     negative values" (`arr[#-1]` is the last element);
+//   • "The string literals can be either single or double quoted";
+//   • "Boolean literals are represented as `1` or `0`" — while the docs' own `!=` example uses
+//     `is_capital != true`, so BOTH spellings are accepted here (see `parseOperand`);
+//   • "`AND` will have higher precedence than `OR`" when no parentheses are given — which is why
+//     `parseOr` sits above `parseAnd` below rather than the two sharing one precedence level.
+//
+// ── WHAT IS DELIBERATELY NOT CLAIMED ──────────────────────────────────────────────────────────
+// Upstash does not publish the literal text of its parse errors, and this pack has no live index to
+// probe (unlike its sibling upstash, which live-probed every string). So `FilterError.message`
+// is TWIN-AUTHORED and says so; what is faithful — and what the capability manifest asserts — is
+// that a malformed filter is REJECTED with the vendor's documented `{error,status}` envelope at
+// HTTP 400 rather than being ignored. A filter that silently matched everything would turn a typo
+// into a data leak, which is the failure this module exists to prevent.
+
+/** A filter that could not be parsed. The handler maps this to the vendor's 400 envelope. */
+export class FilterError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'FilterError';
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// TOKENIZER
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+
+export type TokenKind = 'ident' | 'string' | 'number' | 'op' | 'word' | 'punct';
+export type Token = { kind: TokenKind; value: string; pos: number };
+
+const OPERATOR_CHARS = new Set(['=', '!', '<', '>']);
+/** Reserved words. Case-INSENSITIVE in the docs' examples (`and` and `AND` both appear). */
+const WORDS = new Set(['AND', 'OR', 'NOT', 'IN', 'GLOB', 'CONTAINS', 'HAS', 'FIELD']);
+
+/**
+ * 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 function tokenizeFilter(input: string): Token[] {
+  const tokens: Token[] = [];
+  let i = 0;
+  while (i < input.length) {
+    const c = input[i]!;
+    if (c === ' ' || c === '\t' || c === '\n' || c === '\r') { i++; continue; }
+    const pos = i;
+    if (c === '(' || c === ')' || c === ',') { tokens.push({ kind: 'punct', value: c, pos }); i++; continue; }
+    if (c === "'" || c === '"') {
+      // A quoted string. The closing quote must match the opening one, so an apostrophe inside a
+      // double-quoted literal is ordinary text.
+      const quote = c;
+      i++;
+      let out = '';
+      let closed = false;
+      while (i < input.length) {
+        const ch = input[i]!;
+        // NO BACKSLASH ESCAPE. An earlier draft treated `\x` as an escape for `x`; §9 round 1
+        // showed that is both undocumented by Upstash and a source of SILENT WRONG ANSWERS:
+        // with it, `path = 'C:\Users'` matched a vector whose stored path was `C:Users` and did
+        // NOT match the one holding `C:\Users` — a confidently wrong row at HTTP 200. Upstash's
+        // filter language is SQLite-family (`GLOB`, `IN`, `HAS FIELD`), and no member of that
+        // family gives backslash a special meaning inside a string literal. A backslash is an
+        // ordinary character; a quote is closed only by its own kind, which is what the two
+        // quote styles are for.
+        if (ch === quote) { closed = true; i++; break; }
+        out += ch;
+        i++;
+      }
+      if (!closed) throw new FilterError(`upstashvector: unterminated string literal starting at position ${pos} in filter`);
+      tokens.push({ kind: 'string', value: out, pos });
+      continue;
+    }
+    if (OPERATOR_CHARS.has(c)) {
+      const two = input.slice(i, i + 2);
+      if (two === '!=' || two === '<=' || two === '>=') { tokens.push({ kind: 'op', value: two, pos }); i += 2; continue; }
+      if (c === '=' || c === '<' || c === '>') { tokens.push({ kind: 'op', value: c, pos }); i++; continue; }
+      throw new FilterError(`upstashvector: unexpected character '${c}' at position ${pos} in filter (did you mean '!='?)`);
+    }
+    // A number: an optional sign is handled by the operand parser, not here, so that `a>-1` still
+    // tokenizes as `a` `>` `-1`.
+    if (/[0-9]/.test(c) || (c === '-' && /[0-9.]/.test(input[i + 1] ?? ''))) {
+      let out = c;
+      i++;
+      while (i < input.length && /[0-9._eE+-]/.test(input[i]!)) {
+        // Stop before an `e+`/`e-` that is not part of an exponent, so `a=1 e` does not swallow.
+        const ch = input[i]!;
+        if ((ch === '+' || ch === '-') && !/[eE]/.test(out[out.length - 1] ?? '')) break;
+        out += ch;
+        i++;
+      }
+      if (!Number.isFinite(Number(out))) throw new FilterError(`upstashvector: '${out}' at position ${pos} is not a valid number in filter`);
+      tokens.push({ kind: 'number', value: out, pos });
+      continue;
+    }
+    if (/[A-Za-z_]/.test(c)) {
+      let out = '';
+      while (i < input.length && /[A-Za-z0-9_.[\]#-]/.test(input[i]!)) {
+        // `-` is legal inside a bracket subscript (`[#-1]`) but is NOT an identifier character
+        // otherwise — otherwise `a-b` would read as one name and a typo would become a field.
+        if (input[i] === '-' && !out.includes('[')) break;
+        if (input[i] === '-' && out.lastIndexOf('[') < out.lastIndexOf(']')) break;
+        out += input[i]!;
+        i++;
+      }
+      tokens.push({ kind: WORDS.has(out.toUpperCase()) ? 'word' : 'ident', value: out, pos });
+      continue;
+    }
+    throw new FilterError(`upstashvector: unexpected character '${c}' at position ${pos} in filter`);
+  }
+  return tokens;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// AST
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+
+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 };
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// PARSER (recursive descent; AND binds tighter than OR, per the docs)
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+
+class Parser {
+  private at = 0;
+  constructor(private readonly tokens: Token[], private readonly source: string) {}
+
+  private peek(): Token | undefined { return this.tokens[this.at]; }
+  private next(): Token | undefined { return this.tokens[this.at++]; }
+  private isWord(word: string, offset = 0): boolean {
+    const t = this.tokens[this.at + offset];
+    return t !== undefined && t.kind === 'word' && t.value.toUpperCase() === word;
+  }
+  private expectWord(word: string): void {
+    if (!this.isWord(word)) throw new FilterError(`upstashvector: expected ${word} in filter '${this.source}'`);
+    this.at++;
+  }
+
+  parse(): FilterNode {
+    if (this.tokens.length === 0) throw new FilterError('upstashvector: empty filter expression');
+    const node = this.parseOr();
+    const rest = this.peek();
+    if (rest !== undefined) {
+      throw new FilterError(`upstashvector: unexpected '${rest.value}' at position ${rest.pos} in filter '${this.source}'`);
+    }
+    // Validate every metadata PATH eagerly, at parse time.
+    //
+    // §9 round 1 found the bug this closes: a path like `a[0` (an unterminated subscript)
+    // tokenizes and parses fine, and only `parsePath` — called from `resolvePath` DURING
+    // EVALUATION — rejects it. That made the failure DATA-DEPENDENT: with rows present the
+    // FilterError escaped as an internal HTTP 500, and against an empty namespace the evaluator
+    // was never reached at all, so the same malformed filter answered 200 `[]`. A filter is either
+    // well-formed or it is not; that cannot depend on how many vectors happen to be stored.
+    validatePaths(node);
+    return node;
+  }
+
+  /** OR binds LOOSEST — "AND will have higher precedence than OR" (docs). */
+  private parseOr(): FilterNode {
+    let left = this.parseAnd();
+    while (this.isWord('OR')) {
+      this.at++;
+      left = { kind: 'or', left, right: this.parseAnd() };
+    }
+    return left;
+  }
+
+  private parseAnd(): FilterNode {
+    let left = this.parseUnary();
+    while (this.isWord('AND')) {
+      this.at++;
+      left = { kind: 'and', left, right: this.parseUnary() };
+    }
+    return left;
+  }
+
+  private parseUnary(): FilterNode {
+    const t = this.peek();
+    if (t === undefined) throw new FilterError(`upstashvector: unexpected end of filter '${this.source}'`);
+    if (t.kind === 'punct' && t.value === '(') {
+      this.at++;
+      const inner = this.parseOr();
+      const close = this.next();
+      if (close === undefined || close.value !== ')') throw new FilterError(`upstashvector: unbalanced parenthesis in filter '${this.source}'`);
+      return inner;
+    }
+    // `HAS FIELD x` / `HAS NOT FIELD x` — the only prefix-form operators in the language.
+    if (this.isWord('HAS')) {
+      this.at++;
+      let negated = false;
+      if (this.isWord('NOT')) { this.at++; negated = true; }
+      this.expectWord('FIELD');
+      const ident = this.next();
+      if (ident === undefined || ident.kind !== 'ident') {
+        throw new FilterError(`upstashvector: HAS ${negated ? 'NOT ' : ''}FIELD needs a metadata key in filter '${this.source}'`);
+      }
+      return { kind: 'hasField', path: ident.value, negated };
+    }
+    return this.parseComparison();
+  }
+
+  private parseComparison(): FilterNode {
+    const ident = this.next();
+    if (ident === undefined || ident.kind !== 'ident') {
+      throw new FilterError(`upstashvector: expected a metadata key but found '${ident?.value ?? 'end of input'}' in filter '${this.source}'`);
+    }
+    const path = ident.value;
+    let negated = false;
+    if (this.isWord('NOT')) { this.at++; negated = true; }
+    const op = this.next();
+    if (op === undefined) throw new FilterError(`upstashvector: '${path}' has no operator in filter '${this.source}'`);
+
+    if (op.kind === 'word' && op.value.toUpperCase() === 'IN') {
+      return { kind: 'in', path, negated, values: this.parseList() };
+    }
+    if (op.kind === 'word' && op.value.toUpperCase() === 'GLOB') {
+      return { kind: 'compare', path, op: negated ? 'NOT GLOB' : 'GLOB', value: this.parseOperand() };
+    }
+    if (op.kind === 'word' && op.value.toUpperCase() === 'CONTAINS') {
+      return { kind: 'compare', path, op: negated ? 'NOT CONTAINS' : 'CONTAINS', value: this.parseOperand() };
+    }
+    if (negated) {
+      // `NOT` only prefixes IN / GLOB / CONTAINS; `a NOT = 1` is not the language.
+      throw new FilterError(`upstashvector: NOT must be followed by IN, GLOB or CONTAINS in filter '${this.source}'`);
+    }
+    if (op.kind !== 'op') {
+      throw new FilterError(`upstashvector: '${op.value}' is not a comparison operator in filter '${this.source}'`);
+    }
+    return { kind: 'compare', path, op: op.value as ComparisonOp, value: this.parseOperand() };
+  }
+
+  private parseList(): FilterValue[] {
+    const open = this.next();
+    if (open === undefined || open.value !== '(') throw new FilterError(`upstashvector: IN needs a parenthesised list in filter '${this.source}'`);
+    const values: FilterValue[] = [];
+    for (;;) {
+      const t = this.peek();
+      if (t === undefined) throw new FilterError(`upstashvector: unterminated IN list in filter '${this.source}'`);
+      if (t.kind === 'punct' && t.value === ')') { this.at++; break; }
+      values.push(this.parseOperand());
+      const sep = this.peek();
+      if (sep !== undefined && sep.kind === 'punct' && sep.value === ',') { this.at++; continue; }
+      if (sep !== undefined && sep.kind === 'punct' && sep.value === ')') { this.at++; break; }
+      throw new FilterError(`upstashvector: expected ',' or ')' in IN list in filter '${this.source}'`);
+    }
+    if (values.length === 0) throw new FilterError(`upstashvector: empty IN list in filter '${this.source}'`);
+    return values;
+  }
+
+  /**
+   * A literal operand.
+   *
+   * BOOLEANS: the docs say "Boolean literals are represented as `1` or `0`", but their own `!=`
+   * example is `is_capital != true`. Both are accepted; `1`/`0` stay NUMBERS (so `population > 0`
+   * still compares numerically) and are matched against a boolean field by `looseEquals`.
+   */
+  private parseOperand(): FilterValue {
+    const t = this.next();
+    if (t === undefined) throw new FilterError(`upstashvector: expected a value in filter '${this.source}'`);
+    if (t.kind === 'string') return t.value;
+    if (t.kind === 'number') return Number(t.value);
+    if (t.kind === 'ident' || t.kind === 'word') {
+      const lower = t.value.toLowerCase();
+      if (lower === 'true') return true;
+      if (lower === 'false') return false;
+      // A bare word is not a literal — an unquoted string is the single commonest filter typo, and
+      // matching it against the field name would silently compare a value to itself.
+      throw new FilterError(`upstashvector: '${t.value}' at position ${t.pos} is not a literal — string values must be quoted in filter '${this.source}'`);
+    }
+    throw new FilterError(`upstashvector: unexpected '${t.value}' where a value was expected in filter '${this.source}'`);
+  }
+}
+
+/**
+ * Walk the AST and parse every metadata path, so a malformed one is a PARSE error.
+ * See the note in `Parser.parse` for the data-dependent-status bug this closes.
+ */
+function validatePaths(node: FilterNode): void {
+  switch (node.kind) {
+    case 'and': case 'or':
+      validatePaths(node.left);
+      validatePaths(node.right);
+      return;
+    case 'compare': case 'in': case 'hasField':
+      parsePath(node.path); // throws FilterError on a malformed path
+  }
+}
+
+/** Parse a filter string into an AST. Throws `FilterError` on anything malformed. */
+export function parseFilter(filter: string): FilterNode {
+  return new Parser(tokenizeFilter(filter), filter).parse();
+}
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// PATH RESOLUTION
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+
+/** 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 function parsePath(path: string): PathStep[] {
+  const steps: PathStep[] = [];
+  let buf = '';
+  let i = 0;
+  const flush = () => { if (buf !== '') { steps.push({ key: buf }); buf = ''; } };
+  while (i < path.length) {
+    const c = path[i]!;
+    if (c === '.') { flush(); i++; continue; }
+    if (c === '[') {
+      flush();
+      const close = path.indexOf(']', i);
+      if (close === -1) throw new FilterError(`upstashvector: unterminated '[' in metadata path '${path}'`);
+      const raw = path.slice(i + 1, close);
+      const fromEnd = raw.startsWith('#');
+      const digits = fromEnd ? raw.slice(1) : raw;
+      // `Number('')` is 0, so a BARE `a[]` used to parse as `a[0]` — silently addressing the first
+      // element of an array the caller never named an index for. Require an explicit integer
+      // literal rather than trusting the numeric coercion.
+      if (!/^-?\d+$/.test(digits)) {
+        throw new FilterError(`upstashvector: '${raw}' is not an array index in metadata path '${path}'`);
+      }
+      const n = Number(digits);
+      if (!Number.isInteger(n)) throw new FilterError(`upstashvector: '${raw}' is not an array index in metadata path '${path}'`);
+      steps.push({ index: n, fromEnd });
+      i = close + 1;
+      continue;
+    }
+    buf += c;
+    i++;
+  }
+  flush();
+  if (steps.length === 0) throw new FilterError(`upstashvector: empty metadata path in filter`);
+  return steps;
+}
+
+/** The sentinel for "this path is not present". Distinct from a stored `null`, which IS present. */
+export const MISSING: unique symbol = Symbol('upstashvector.missing');
+
+/** Resolve a metadata path. Returns `MISSING` when any step is absent. */
+export function resolvePath(metadata: unknown, path: string): unknown | typeof MISSING {
+  let cur: unknown = metadata;
+  for (const step of parsePath(path)) {
+    if (cur === null || cur === undefined) return MISSING;
+    if ('key' in step) {
+      if (typeof cur !== 'object' || Array.isArray(cur)) return MISSING;
+      const rec = cur as Record<string, unknown>;
+      if (!Object.prototype.hasOwnProperty.call(rec, step.key)) return MISSING;
+      cur = rec[step.key];
+      continue;
+    }
+    if (!Array.isArray(cur)) return MISSING;
+    // `[#-1]` addresses from the end; `[0]` from the start. A negative head-relative index is not
+    // the documented spelling, so it simply misses rather than silently wrapping.
+    const idx = step.fromEnd ? cur.length + step.index : step.index;
+    if (!Number.isInteger(idx) || idx < 0 || idx >= cur.length) return MISSING;
+    cur = cur[idx];
+  }
+  return cur;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// GLOB
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 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 function globMatch(pattern: string, subject: string): boolean {
+  const walk = (p: number, s: number): boolean => {
+    if (p === pattern.length) return s === subject.length;
+    const pc = pattern[p]!;
+    if (pc === '*') {
+      // Collapse runs of `*` so `a**b` costs no more than `a*b`.
+      let q = p;
+      while (q < pattern.length && pattern[q] === '*') q++;
+      for (let k = s; k <= subject.length; k++) if (walk(q, k)) return true;
+      return false;
+    }
+    if (s === subject.length) return false;
+    if (pc === '?') return walk(p + 1, s + 1);
+    if (pc === '[') {
+      const close = classEnd(pattern, p);
+      if (close === -1) return pattern[p] === subject[s] && walk(p + 1, s + 1); // an unclosed '[' is a literal
+      const negated = pattern[p + 1] === '^';
+      const body = pattern.slice(p + 1 + (negated ? 1 : 0), close);
+      return inClass(body, subject[s]!) !== negated && walk(close + 1, s + 1);
+    }
+    return pc === subject[s] && walk(p + 1, s + 1);
+  };
+  return walk(0, 0);
+}
+
+/** Index of the `]` closing the class opened at `open`, or -1. A `]` FIRST in the class is literal. */
+function classEnd(pattern: string, open: number): number {
+  let i = open + 1;
+  if (pattern[i] === '^') i++;
+  if (pattern[i] === ']') i++; // a leading ']' is a literal member, not the terminator
+  for (; i < pattern.length; i++) if (pattern[i] === ']') return i;
+  return -1;
+}
+
+function inClass(body: string, ch: string): boolean {
+  for (let i = 0; i < body.length; i++) {
+    // A range needs a `-` with members on BOTH sides; a trailing `-` is a literal hyphen.
+    if (body[i + 1] === '-' && i + 2 < body.length) {
+      const lo = body[i]!;
+      const hi = body[i + 2]!;
+      if (ch >= lo && ch <= hi) return true;
+      i += 2;
+      continue;
+    }
+    if (body[i] === ch) return true;
+  }
+  return false;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// EVALUATOR
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Compare a stored metadata value with a filter literal for EQUALITY.
+ *
+ * `1`/`0` are the docs' own boolean spelling, so a numeric 1 matches a stored `true`. Everything
+ * else is compared by JS `===` after that coercion, so `'5'` (a string literal) does NOT equal a
+ * stored number 5 — a filter language that silently coerced across types would make
+ * `price = '10'` match a `price: 10` field and mask the caller's bug.
+ */
+function looseEquals(stored: unknown, literal: FilterValue): boolean {
+  if (typeof stored === 'boolean' && typeof literal === 'number') return stored === (literal === 1);
+  if (typeof stored === 'boolean' && typeof literal === 'boolean') return stored === literal;
+  return stored === literal;
+}
+
+/** Ordering comparison. Only like-typed operands are ordered; anything else simply does not match. */
+function ordered(stored: unknown, literal: FilterValue, op: '<' | '>' | '<=' | '>='): boolean {
+  if (typeof stored === 'number' && typeof literal === 'number') {
+    return op === '<' ? stored < literal : op === '>' ? stored > literal : op === '<=' ? stored <= literal : stored >= literal;
+  }
+  if (typeof stored === 'string' && typeof literal === 'string') {
+    return op === '<' ? stored < literal : op === '>' ? stored > literal : op === '<=' ? stored <= literal : stored >= literal;
+  }
+  return false;
+}
+
+/** Evaluate a parsed filter against one vector's metadata. */
+export function evaluateFilter(node: FilterNode, metadata: unknown): boolean {
+  switch (node.kind) {
+    case 'and': return evaluateFilter(node.left, metadata) && evaluateFilter(node.right, metadata);
+    case 'or': return evaluateFilter(node.left, metadata) || evaluateFilter(node.right, metadata);
+    case 'hasField': {
+      const present = resolvePath(metadata, node.path) !== MISSING;
+      return node.negated ? !present : present;
+    }
+    case 'in': {
+      const v = resolvePath(metadata, node.path);
+      // A MISSING field is in no list — and is also not "NOT IN" anything, because the vendor's
+      // HAS FIELD operator exists precisely so that absence is asked about explicitly. Treating
+      // absence as a NOT IN match would make `country NOT IN ('X')` select vectors with no
+      // `country` at all, which is the classic filter-language footgun.
+      if (v === MISSING) return false;
+      const hit = node.values.some((lit) => looseEquals(v, lit));
+      return node.negated ? !hit : hit;
+    }
+    case 'compare': {
+      const v = resolvePath(metadata, node.path);
+      if (v === MISSING) return false; // same rule as IN: absence never satisfies a comparison
+      switch (node.op) {
+        case '=': return looseEquals(v, node.value);
+        case '!=': return !looseEquals(v, node.value);
+        case '<': case '>': case '<=': case '>=': return ordered(v, node.value, node.op);
+        case 'GLOB': return typeof v === 'string' && typeof node.value === 'string' && globMatch(node.value, v);
+        case 'NOT GLOB': return typeof v === 'string' && typeof node.value === 'string' && !globMatch(node.value, v);
+        case 'CONTAINS': return Array.isArray(v) && v.some((el) => looseEquals(el, node.value));
+        case 'NOT CONTAINS': return Array.isArray(v) && !v.some((el) => looseEquals(el, node.value));
+      }
+    }
+  }
+}
+
+/** Parse + evaluate in one step. Exported for the handler's single call site. */
+export function matchesFilter(filter: string, metadata: unknown): boolean {
+  return evaluateFilter(parseFilter(filter), metadata);
+}

package/src/upstashvector-server.ts

@@ -0,0 +1,86 @@
+// upstashvector twin HTTP server — serve the Upstash Vector REST twin over HTTP so the real
+// `@upstash/vector` SDK (pointed at it with nothing but its own public `url` option) works
+// UNMODIFIED.
+//
+// ── THE INDEX IS CONFIGURED HERE, NOT DISCOVERED ──────────────────────────────────────────────
+// A real Upstash Vector index is created with a fixed `dimension` and `similarityFunction` and can
+// never change them. A twin has no creation step, so those become server options: pass them and the
+// index behaves exactly like one created that way (including the vendor's 422 on a mismatched
+// vector); omit `dimension` and the FIRST upsert locks one in, which is the convenient local
+// default. `similarityFunction` defaults to COSINE, the console's own default.
+//
+// FETCH-FIRST (runtime contract R12b): the surface is the plain `createUpstashVectorTwinFetch` and
+// the SERVER is one line of `Bun.serve` around it. This is a CUSTOM fetch, not the kernel adapter
+// (`createTwinFetchFromHandler`): replies carry ONLY the handler's own headers, and the clock is
+// an injectable seam.
+import { serveHttp } from '@volter/world-core';
+import { handleUpstashVectorTwinRequest } from './upstashvector-twin.ts';
+import { worldNow, statefulTwinManifest} from '@volter/world-core';
+import type { SimilarityFunction } from './upstashvector-store.ts';
+
+export type UpstashVectorServerOptions = {
+  root?: string;
+  port?: number;
+  readOnly?: boolean;
+  /** The token the twin demands. Omit to accept any non-empty credential (still 401s a missing one). */
+  token?: string;
+  /** The dimension this index enforces. Omit to let the first upsert lock one in. */
+  dimension?: number;
+  /** The metric this index ranks with. Defaults to COSINE. */
+  similarityFunction?: SimilarityFunction;
+  /** The injected clock. Returns the ISO instant this request "happens at". */
+  now?: () => string;
+};
+
+/** Options every Upstash Vector-twin HTTP surface needs, independent of who owns the socket. */
+export interface UpstashVectorTwinFetchOptions {
+  root?: string;
+  readOnly?: boolean;
+  /** The token the twin demands. Omit to accept any non-empty credential (still 401s a missing one). */
+  token?: string;
+  /** The dimension this index enforces. Omit to let the first upsert lock one in. */
+  dimension?: number;
+  /** The metric this index ranks with. Defaults to COSINE. */
+  similarityFunction?: SimilarityFunction;
+  /** The injected clock. Returns the ISO instant this request "happens at". */
+  now?: () => string;
+}
+
+export function createUpstashVectorTwinFetch(options: UpstashVectorTwinFetchOptions = {}): (request: Request) => Promise<Response> {
+  const readOnly = options.readOnly ?? false;
+  const now = options.now ?? (() => worldNow());
+  return async function upstashVectorTwinFetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    // GET /twin — the discovery manifest (education inside the twin).
+    if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') {
+      return Response.json(statefulTwinManifest({ vendor: 'upstashvector', twinOf: 'the Upstash Vector REST API', stores: 'namespaces and vectors, queried by a real scorer' }));
+    }
+    const body = request.method !== 'GET' && request.method !== 'HEAD' ? await request.text() : '';
+    const headers: Record<string, string> = {};
+    request.headers.forEach((value, key) => { headers[key.toLowerCase()] = value; });
+    const { status, body: out, headers: outHeaders } = await handleUpstashVectorTwinRequest({
+      method: request.method,
+      path: url.pathname + (url.search || ''),
+      body,
+      headers,
+      readOnly,
+      occurredAt: now(),
+      ...(options.root !== undefined ? { root: options.root } : {}),
+      ...(options.token !== undefined ? { token: options.token } : {}),
+      ...(options.dimension !== undefined ? { dimension: options.dimension } : {}),
+      ...(options.similarityFunction !== undefined ? { similarityFunction: options.similarityFunction } : {}),
+    });
+    // A null body means "no body at all" (HEAD, CORS preflight).
+    if (out === null) return new Response(null, { status, headers: { ...(outHeaders ?? {}) } });
+    return new Response(JSON.stringify(out), { status, headers: { ...(outHeaders ?? {}) } });
+  };
+}
+
+export async function createUpstashVectorTwinServer(options: UpstashVectorServerOptions = {}): Promise<{ port: number; stop: () => void }> {
+  const server = await serveHttp({
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    fetch: createUpstashVectorTwinFetch(options),
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}