@volter/twin-upstash 0.1.0

package/dist/src/upstash-capabilities.js

@@ -0,0 +1,1286 @@
+// upstash capability manifest — the EXPECTED REAL-PRODUCT SURFACE (the target), authored
+// top-down from what the Upstash Redis REST API actually does, NOT from what this twin has built.
+//
+// GROUNDED (2026-08-19) three ways, all read-only — see spec-sources.json:
+//   (a) upstash.com/docs/redis/features/restapi + the Redis-compatibility and billing pages;
+//   (b) the ACTUALLY-INSTALLED `@upstash/redis@1.35.7` and `@upstash/ratelimit@2.0.8` package
+//       sources (their compiled command builders, HTTP client, and Lua scripts);
+//   (c) LIVE PROBES of a real ephemeral Upstash database — where every literal error string, HTTP
+//       status and base64 rule asserted below came from.
+// The DENOMINATOR is enumerated from Redis's own command GROUPS as Upstash supports them (string,
+// bitmap, hash, list, set, sorted-set, hyperloglog, geo, stream, JSON, pub/sub, scripting, generic,
+// server, transactions, connection) crossed with the REST protocol's own surface — so whole command
+// families this twin has not built (bitmaps, geo, HyperLogLog, RedisJSON, consumer groups, pub/sub)
+// appear as `todo`s rather than being quietly left out of the count.
+//
+// `verify()` (required to count as done) is ground truth: every API verify drives the REAL
+// `handleUpstashRedisTwinRequest` over a FRESH temp root with a PINNED clock, and asserts VALUES —
+// never a bare status code. Nothing here is a mock.
+//
+// TIME IS INJECTED: TTL/window/stream-id time is measured against the request's own `occurredAt`
+// (or `createUpstashRedisTwinServer({ now })`), which reproduces every TIME-DEPENDENT SEMANTIC —
+// lazy expiry, TTL arithmetic, window rollover, monotonic stream ids — exactly and deterministically
+// rather than racing a real clock. Every entry below is either done or todo.
+//
+// (Upstash Redis is an API-first vendor — docs/contributing/architecture.md C1b: an integrator CALLS this product from
+// code and the Upstash console is a config/metrics dashboard, not where the work happens — so this
+// pack ships NO mirror and there are no UI capabilities. See README ## Coverage § No UI mirror.)
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { checkCapabilities, verifyBoundary } from '@volter/world-tooling';
+import { handleUpstashRedisTwinRequest } from "./upstash-twin.js";
+import { checkUpstashRedisConformance } from "./upstash-conformance.js";
+import { syncUpstashRedisFromReal, pullUpstashRedisKeys, pullUpstashRedisScan } from "./upstash-connector.js";
+/** The pinned clock every verify runs against, so ids, TTLs and stream ids are deterministic. */
+const AT = '2026-01-01T00:00:00.000Z';
+const AT_MS = Date.parse(AT);
+/** A later instant, for the verifies that need the clock to ADVANCE (expiry, window rollover). */
+const laterAt = (ms) => new Date(AT_MS + ms).toISOString();
+const AUTH = { authorization: 'Bearer twin-capability-token' };
+async function withRoot(steps) {
+    const root = mkdtempSync(join(tmpdir(), 'upstash-cap-'));
+    const raw = (req) => handleUpstashRedisTwinRequest({
+        method: req.method ?? 'POST',
+        path: req.path ?? '/',
+        root,
+        occurredAt: req.at ?? AT,
+        headers: req.headers === undefined ? AUTH : req.headers,
+        ...(req.body !== undefined ? { body: req.body } : {}),
+        ...(req.readOnly !== undefined ? { readOnly: req.readOnly } : {}),
+        ...(req.token !== undefined ? { token: req.token } : {}),
+    });
+    const run = (async (argv, opts = {}) => {
+        const res = await raw({
+            body: JSON.stringify(argv.map((x) => (typeof x === 'number' ? x : String(x)))),
+            ...(opts.at !== undefined ? { at: opts.at } : {}),
+            ...(opts.headers !== undefined ? { headers: opts.headers } : {}),
+        });
+        const body = (res.body ?? {});
+        return { status: res.status, result: body.result, error: body.error, ...(res.headers ? { headers: res.headers } : {}) };
+    });
+    run.raw = raw;
+    run.root = root;
+    try {
+        return await verifyBoundary('upstash.withRoot', () => steps(run, root));
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+/** The three real single-region @upstash/ratelimit scripts, read out of the installed package. */
+const RATELIMIT_FIXED_WINDOW = `
+  local key           = KEYS[1]
+  local dynamicLimitKey = KEYS[2]  -- optional: key for dynamic limit in redis
+  local tokens        = tonumber(ARGV[1])  -- default limit
+  local window        = ARGV[2]
+  local incrementBy   = ARGV[3] -- increment rate per request at a given value, default is 1
+
+  -- Check for dynamic limit
+  local effectiveLimit = tokens
+  if dynamicLimitKey ~= "" then
+    local dynamicLimit = redis.call("GET", dynamicLimitKey)
+    if dynamicLimit then
+      effectiveLimit = tonumber(dynamicLimit)
+    end
+  end
+
+  local r = redis.call("INCRBY", key, incrementBy)
+  if r == tonumber(incrementBy) then
+  -- The first time this key is set, the value will be equal to incrementBy.
+  -- So we only need the expire command once
+  redis.call("PEXPIRE", key, window)
+  end
+
+  return {r, effectiveLimit}
+`;
+const RATELIMIT_SLIDING_WINDOW = `
+  local currentKey  = KEYS[1]           -- identifier including prefixes
+  local previousKey = KEYS[2]           -- key of the previous bucket
+  local dynamicLimitKey = KEYS[3]       -- optional: key for dynamic limit in redis
+  local tokens      = tonumber(ARGV[1]) -- default tokens per window
+  local now         = ARGV[2]           -- current timestamp in milliseconds
+  local window      = ARGV[3]           -- interval in milliseconds
+  local incrementBy = tonumber(ARGV[4]) -- increment rate per request at a given value, default is 1
+
+  -- Check for dynamic limit
+  local effectiveLimit = tokens
+  if dynamicLimitKey ~= "" then
+    local dynamicLimit = redis.call("GET", dynamicLimitKey)
+    if dynamicLimit then
+      effectiveLimit = tonumber(dynamicLimit)
+    end
+  end
+
+  local requestsInCurrentWindow = redis.call("GET", currentKey)
+  if requestsInCurrentWindow == false then
+    requestsInCurrentWindow = 0
+  end
+
+  local requestsInPreviousWindow = redis.call("GET", previousKey)
+  if requestsInPreviousWindow == false then
+    requestsInPreviousWindow = 0
+  end
+  local percentageInCurrent = ( now % window ) / window
+  -- weighted requests to consider from the previous window
+  requestsInPreviousWindow = math.floor(( 1 - percentageInCurrent ) * requestsInPreviousWindow)
+
+  -- Only check limit if not refunding (negative rate)
+  if incrementBy > 0 and requestsInPreviousWindow + requestsInCurrentWindow >= effectiveLimit then
+    return {-1, effectiveLimit}
+  end
+
+  local newValue = redis.call("INCRBY", currentKey, incrementBy)
+  if newValue == incrementBy then
+    -- The first time this key is set, the value will be equal to incrementBy.
+    -- So we only need the expire command once
+    redis.call("PEXPIRE", currentKey, window * 2 + 1000) -- Enough time to overlap with a new window + 1 second
+  end
+  return {effectiveLimit - ( newValue + requestsInPreviousWindow ), effectiveLimit}
+`;
+const RATELIMIT_TOKEN_BUCKET = `
+  local key         = KEYS[1]           -- identifier including prefixes
+  local dynamicLimitKey = KEYS[2]       -- optional: key for dynamic limit in redis
+  local maxTokens   = tonumber(ARGV[1]) -- default maximum number of tokens
+  local interval    = tonumber(ARGV[2]) -- size of the window in milliseconds
+  local refillRate  = tonumber(ARGV[3]) -- how many tokens are refilled after each interval
+  local now         = tonumber(ARGV[4]) -- current timestamp in milliseconds
+  local incrementBy = tonumber(ARGV[5]) -- how many tokens to consume, default is 1
+
+  -- Check for dynamic limit
+  local effectiveLimit = maxTokens
+  if dynamicLimitKey ~= "" then
+    local dynamicLimit = redis.call("GET", dynamicLimitKey)
+    if dynamicLimit then
+      effectiveLimit = tonumber(dynamicLimit)
+    end
+  end
+
+  local bucket = redis.call("HMGET", key, "refilledAt", "tokens")
+
+  local refilledAt
+  local tokens
+
+  if bucket[1] == false then
+    refilledAt = now
+    tokens = effectiveLimit
+  else
+    refilledAt = tonumber(bucket[1])
+    tokens = tonumber(bucket[2])
+  end
+
+  if now >= refilledAt + interval then
+    local numRefills = math.floor((now - refilledAt) / interval)
+    tokens = math.min(effectiveLimit, tokens + numRefills * refillRate)
+
+    refilledAt = refilledAt + numRefills * interval
+  end
+
+  -- Only reject if tokens are 0 and we're consuming (not refunding)
+  if tokens == 0 and incrementBy > 0 then
+    return {-1, refilledAt + interval, effectiveLimit}
+  end
+
+  local remaining = tokens - incrementBy
+  local expireAt = math.ceil(((effectiveLimit - remaining) / refillRate)) * interval
+
+  redis.call("HSET", key, "refilledAt", refilledAt, "tokens", remaining)
+
+  if (expireAt > 0) then
+    redis.call("PEXPIRE", key, expireAt)
+  end
+  return {remaining, refilledAt + interval, effectiveLimit}
+`;
+/** dub's own compare-and-delete lock release (apps/web/lib/upstash/redis-lock.ts), verbatim. */
+const DUB_RELEASE_LOCK = `
+if redis.call("get", KEYS[1]) == ARGV[1] then
+  return redis.call("del", KEYS[1])
+else
+  return 0
+end`;
+// ── a counting fake for the connector verifies (never a network client) ────────────────────────
+function fakeRedisClient(data) {
+    const calls = [];
+    const client = {
+        type: async (k) => { calls.push(`type:${k}`); return data[k]?.type ?? 'none'; },
+        get: async (k) => { calls.push(`get:${k}`); return data[k]?.value ?? null; },
+        hgetall: async (k) => { calls.push(`hgetall:${k}`); return (data[k]?.value ?? null); },
+        smembers: async (k) => { calls.push(`smembers:${k}`); return (data[k]?.value ?? []); },
+        lrange: async (k) => { calls.push(`lrange:${k}`); return (data[k]?.value ?? []); },
+        zrange: async (k) => { calls.push(`zrange:${k}`); return (data[k]?.value ?? []); },
+        ttl: async (k) => { calls.push(`ttl:${k}`); return data[k]?.ttl ?? -1; },
+        scan: async (cursor) => { calls.push(`scan:${cursor}`); return ['0', Object.keys(data)]; },
+    };
+    return { client, calls };
+}
+const done = (id, area, title, dimension, tier, verify) => ({ id, area, title, dimension, tier, expected: 'done', verify });
+const todo = (id, area, title, dimension, tier) => ({ id, area, title, dimension, tier, expected: 'todo' });
+export const UPSTASH_CAPABILITIES = [
+    // ── REST PROTOCOL (the surface that makes this Upstash rather than Redis) ───────────────────
+    done('upstash.protocol.post_root_command', 'protocol', 'POST / with the whole command as a JSON array body -> {"result":…} (the documented "POST Command in Body" form)', 'api', 'core', () => withRoot(async (r) => {
+        const set = await r(['SET', 'p:a', 'one']);
+        const get = await r(['GET', 'p:a']);
+        return set.status === 200 && set.result === 'OK' && get.status === 200 && get.result === 'one';
+    })),
+    done('upstash.protocol.pipeline', 'protocol', 'POST /pipeline runs an array of command arrays IN ORDER and answers a positionally-aligned array of {result}/{error} objects (the endpoint the SDK\'s default auto-pipelining always uses)', 'api', 'core', () => withRoot(async (r) => {
+        const res = await r.raw({ path: '/pipeline', body: JSON.stringify([['SET', 'pl:k', 'v'], ['GET', 'pl:k'], ['INCR', 'pl:n']]) });
+        const items = res.body;
+        return res.status === 200 && Array.isArray(items) && items.length === 3
+            && items[0].result === 'OK' && items[1].result === 'v' && items[2].result === 1;
+    })),
+    done('upstash.protocol.pipeline_error_is_per_item', 'protocol', 'a RUNTIME failure inside a pipeline is reported per-item at HTTP 200 and does NOT abort the rest (LIVE-PROBED: the commands after it still apply)', 'api', 'core', () => withRoot(async (r) => {
+        await r(['SET', 'pe:s', 'abc']);
+        const res = await r.raw({ path: '/pipeline', body: JSON.stringify([['INCR', 'pe:s'], ['SET', 'pe:after', 'written']]) });
+        const items = res.body;
+        const after = await r(['GET', 'pe:after']);
+        return res.status === 200 && items[0].error === 'ERR value is not an integer or out of range'
+            && items[1].result === 'OK' && after.result === 'written';
+    })),
+    done('upstash.protocol.pipeline_rejects_malformed', 'protocol', 'an EMPTY pipeline -> 400 "ERR empty pipeline request"; a 1-D array -> 400 naming the index; an UNAVAILABLE command anywhere -> 400 with the whole batch discarded (nothing applied)', 'api', 'common', () => withRoot(async (r) => {
+        const empty = await r.raw({ path: '/pipeline', body: '[]' });
+        const flat = await r.raw({ path: '/pipeline', body: JSON.stringify(['SET', 'x', '1']) });
+        const bad = await r.raw({ path: '/pipeline', body: JSON.stringify([['SET', 'pm:ok', '1'], ['NOTACMD', 'x']]) });
+        const applied = await r(['GET', 'pm:ok']);
+        return empty.body.error === 'ERR empty pipeline request'
+            && empty.status === 400
+            && flat.body.error === 'ERR failed to parse pipeline command at index 0'
+            && bad.status === 400
+            && bad.body.error.startsWith("ERR Command is not available: 'NOTACMD'")
+            && applied.result === null; // the batch was discarded BEFORE execution
+    })),
+    done('upstash.protocol.multi_exec', 'protocol', 'POST /multi-exec runs the batch as a transaction and answers the same {result}/{error} array shape', 'api', 'core', () => withRoot(async (r) => {
+        const res = await r.raw({ path: '/multi-exec', body: JSON.stringify([['INCR', 'tx:n'], ['INCR', 'tx:n'], ['GET', 'tx:n']]) });
+        const items = res.body;
+        return res.status === 200 && items.length === 3 && items[0].result === 1 && items[1].result === 2 && items[2].result === '2';
+    })),
+    done('upstash.protocol.multi_exec_runtime_error_does_not_roll_back', 'protocol', 'a RUNTIME error inside /multi-exec is per-item at HTTP 200 and the later commands STILL APPLY — Upstash\'s documented "all commands will be executed … same semantics with Redis", NOT a rollback (LIVE-PROBED)', 'api', 'common', () => withRoot(async (r) => {
+        await r(['SET', 'tx:s', 'abc']);
+        const res = await r.raw({ path: '/multi-exec', body: JSON.stringify([['INCR', 'tx:s'], ['SET', 'tx:after', 'applied']]) });
+        const items = res.body;
+        const after = await r(['GET', 'tx:after']);
+        return res.status === 200 && items[0].error === 'ERR value is not an integer or out of range' && after.result === 'applied';
+    })),
+    done('upstash.protocol.multi_exec_execabort', 'protocol', 'a QUEUE-TIME fault discards the whole transaction pre-execution: a bad arity -> 400 EXECABORT naming the command, an unavailable command -> 400 "… at index N, discarding transaction", and nothing is applied', 'api', 'common', () => withRoot(async (r) => {
+        const arity = await r.raw({ path: '/multi-exec', body: JSON.stringify([['SET', 'ea:k', 'v'], ['GET']]) });
+        const unknown = await r.raw({ path: '/multi-exec', body: JSON.stringify([['SET', 'ea:k2', 'v'], ['NOTACMD']]) });
+        const k = await r(['GET', 'ea:k']);
+        const k2 = await r(['GET', 'ea:k2']);
+        return arity.status === 400
+            && arity.body.error === "EXECABORT Transaction discarded because of previous errors: ['GET': ERR wrong number of arguments for 'get' command]"
+            && unknown.status === 400
+            && unknown.body.error.endsWith('at index 1, discarding transaction')
+            && k.result === null && k2.result === null;
+    })),
+    done('upstash.protocol.path_style_get', 'protocol', 'GET /{COMMAND}/{arg}/… executes the command with percent-decoded args and a case-insensitive command name', 'api', 'core', () => withRoot(async (r) => {
+        const set = await r.raw({ method: 'GET', path: '/SET/ps:k/hello%20world' });
+        const get = await r.raw({ method: 'GET', path: '/get/ps:k' });
+        return set.status === 200 && set.body.result === 'OK'
+            && get.body.result === 'hello world';
+    })),
+    done('upstash.protocol.path_style_body_and_query', 'protocol', 'POST /set/{key} appends the RAW BODY as the command\'s last argument and turns query parameters into trailing option tokens (POST /set/k?EX=100 ⇒ SET k <body> EX 100)', 'api', 'common', () => withRoot(async (r) => {
+        const set = await r.raw({ method: 'POST', path: '/set/pb:k?EX=100', body: 'body-value' });
+        const get = await r(['GET', 'pb:k']);
+        const ttl = await r(['TTL', 'pb:k']);
+        return set.status === 200 && get.result === 'body-value' && ttl.result === 100;
+    })),
+    done('upstash.protocol.base64_encoding', 'protocol', 'Upstash-Encoding: base64 encodes every STRING in the result recursively at any array depth, leaving integers/null/empty arrays untouched (the SDK\'s DEFAULT, so a wrong answer here breaks every consumer)', 'api', 'core', () => withRoot(async (r) => {
+        const h = { ...AUTH, 'upstash-encoding': 'base64' };
+        await r(['SET', 'b64:s', 'hello']);
+        await r(['RPUSH', 'b64:l', 'two', 'three']);
+        await r(['SET', 'b64:n', '5']);
+        const s = await r(['GET', 'b64:s'], { headers: h });
+        const l = await r(['LRANGE', 'b64:l', '0', '-1'], { headers: h });
+        const n = await r(['INCR', 'b64:n'], { headers: h });
+        const nil = await r(['GET', 'b64:missing'], { headers: h });
+        return s.result === Buffer.from('hello').toString('base64')
+            && JSON.stringify(l.result) === JSON.stringify([Buffer.from('two').toString('base64'), Buffer.from('three').toString('base64')])
+            && n.result === 6 // an integer reply is NOT encoded
+            && nil.result === null;
+    })),
+    done('upstash.protocol.base64_ok_exemption', 'protocol', 'the base64 exemption is scoped to the simple-STATUS reply OK: SET answers a raw "OK", but a BULK STRING whose value is "OK" is encoded ("T0s="), and PING\'s status "PONG" IS encoded — the distinction the docs under-specify and the SDK\'s decoder silently mangles if a twin gets it wrong', 'api', 'common', () => withRoot(async (r) => {
+        const h = { ...AUTH, 'upstash-encoding': 'base64' };
+        const set = await r(['SET', 'okv', 'OK'], { headers: h });
+        const get = await r(['GET', 'okv'], { headers: h });
+        const ping = await r(['PING'], { headers: h });
+        return set.result === 'OK' && get.result === 'T0s=' && ping.result === Buffer.from('PONG').toString('base64');
+    })),
+    done('upstash.protocol.encoding_header_validated', 'protocol', 'an Upstash-Encoding value other than the exact lowercase "base64" -> 400 with the offending value quoted (LIVE-PROBED: the header is case-SENSITIVE, so "BASE64" is rejected)', 'api', 'niche', () => withRoot(async (r) => {
+        const bad = await r(['PING'], { headers: { ...AUTH, 'upstash-encoding': 'BASE64' } });
+        const hex = await r(['PING'], { headers: { ...AUTH, 'upstash-encoding': 'hex' } });
+        return bad.status === 400 && bad.error === 'ERR invalid Upstash-Encoding header: "BASE64"'
+            && hex.status === 400 && hex.error === 'ERR invalid Upstash-Encoding header: "hex"';
+    })),
+    done('upstash.protocol.command_error_is_http_400', 'protocol', 'a command-level failure answers HTTP 400 with {"error":…}, NOT 200 — which is what makes the SDK take its `!res.ok` branch and append its ", command was: […]" suffix to the thrown UpstashError', 'api', 'core', () => withRoot(async (r) => {
+        await r(['SET', 'e:s', 'abc']);
+        const bad = await r(['INCR', 'e:s']);
+        const ok = await r(['GET', 'e:s']);
+        return bad.status === 400 && bad.error === 'ERR value is not an integer or out of range' && bad.result === undefined
+            && ok.status === 200;
+    })),
+    done('upstash.protocol.sync_token_header', 'protocol', 'every 2xx carries an `upstash-sync-token` response header that ADVANCES on a write and is echoed back on a read; a garbage token degrades to "0" instead of erroring (the SDK sends a stale one by design — a documented off-by-one — so this must be permissive)', 'api', 'niche', () => withRoot(async (r) => {
+        const write = await r(['SET', 'st:k', 'v'], { headers: { ...AUTH, 'upstash-sync-token': '5' } });
+        const read = await r(['GET', 'st:k'], { headers: { ...AUTH, 'upstash-sync-token': '5' } });
+        const garbage = await r(['GET', 'st:k'], { headers: { ...AUTH, 'upstash-sync-token': 'zzz!!' } });
+        const absent = await r(['GET', 'st:k']);
+        return write.headers?.['upstash-sync-token'] === '6'
+            && read.headers?.['upstash-sync-token'] === '5'
+            && garbage.status === 200 && garbage.headers?.['upstash-sync-token'] === '0'
+            && absent.headers?.['upstash-sync-token'] === '0';
+    })),
+    done('upstash.protocol.method_and_cors', 'protocol', 'OPTIONS is a CORS preflight answering 200 with an empty body and the echoed origin (NOT the 405 the docs\' method list implies), while a genuinely disallowed method (DELETE) answers 405 with no body at all', 'api', 'niche', () => withRoot(async (r) => {
+        const preflight = await r.raw({ method: 'OPTIONS', path: '/', headers: { origin: 'https://app.example.test', 'access-control-request-headers': 'authorization' } });
+        const disallowed = await r.raw({ method: 'DELETE', path: '/get/k' });
+        return preflight.status === 200 && preflight.body === null
+            && preflight.headers?.['access-control-allow-origin'] === 'https://app.example.test'
+            && disallowed.status === 405 && disallowed.body === null;
+    })),
+    done('upstash.protocol.malformed_body_errors', 'protocol', 'the body-parse errors, verbatim: no body -> "EOF", a non-array -> "expected JSON array" (both WITHOUT an ERR prefix), [] -> "ERR empty command", a null arg -> "ERR null args are not supported", an object arg -> the vendor\'s json.Delim message', 'api', 'niche', () => withRoot(async (r) => {
+        const eof = await r.raw({ body: '' });
+        const notArray = await r.raw({ body: '{"not":"array"}' });
+        const empty = await r.raw({ body: '[]' });
+        const nullArg = await r.raw({ body: JSON.stringify(['set', 'k', null]) });
+        const objArg = await r.raw({ body: JSON.stringify(['set', 'k', { a: 1 }]) });
+        const err = (x) => x.body.error;
+        return err(eof) === 'EOF' && err(notArray) === 'expected JSON array' && err(empty) === 'ERR empty command'
+            && err(nullArg) === 'ERR null args are not supported'
+            && err(objArg) === 'ERR unsupported arg type: "{": json.Delim'
+            && [eof, notArray, empty, nullArg, objArg].every((x) => x.status === 400);
+    })),
+    done('upstash.protocol.max_request_size', 'protocol', 'a body above the documented 10 MB limit -> HTTP 413 with the vendor\'s max-request-size message (a status the REST docs do not even list — LIVE-PROBED)', 'api', 'niche', () => withRoot(async (r) => {
+        const huge = await r.raw({ body: `["SET","big","${'x'.repeat(10_485_800)}"]` });
+        return huge.status === 413 && huge.body.error.startsWith('ERR max request size exceeded. Limit: 10485760 bytes');
+    })),
+    done('upstash.protocol.json_arg_coercion', 'protocol', 'JSON numbers and booleans are accepted as command arguments and stringified (["setex","k",60,"v"] works) — the SDK emits TTL values as JSON numbers, so refusing them would break `set(k,v,{ex:60})`', 'api', 'common', () => withRoot(async (r) => {
+        const res = await r.raw({ body: JSON.stringify(['setex', 'ja:k', 60, 'v']) });
+        const ttl = await r(['TTL', 'ja:k']);
+        const bool = await r.raw({ body: JSON.stringify(['set', 'ja:b', true]) });
+        const got = await r(['GET', 'ja:b']);
+        return res.status === 200 && ttl.result === 60 && bool.status === 200 && got.result === 'true';
+    })),
+    // ── AUTH ────────────────────────────────────────────────────────────────────────────────────
+    done('upstash.auth.missing_token_401', 'auth', 'a missing/blank credential -> HTTP 401 with the vendor\'s LITERAL body: "WRONGPASS invalid or missing auth token. See https://docs.upstash.com/redis/troubleshooting/http_unauthorized for details." — and NO upstash-sync-token header', 'api', 'core', () => withRoot(async (r) => {
+        const none = await r.raw({ body: JSON.stringify(['PING']), headers: {} });
+        const blank = await r.raw({ body: JSON.stringify(['PING']), headers: { authorization: 'Bearer ' } });
+        const expected = 'WRONGPASS invalid or missing auth token. See https://docs.upstash.com/redis/troubleshooting/http_unauthorized for details.';
+        return none.status === 401 && none.body.error === expected
+            && blank.status === 401 && blank.body.error === expected
+            && none.headers?.['upstash-sync-token'] === undefined;
+    })),
+    done('upstash.auth.bearer_and_bare_header', 'auth', 'both `Authorization: Bearer <token>` (documented) and a BARE `Authorization: <token>` (undocumented but LIVE-PROBED as accepted) are honoured', 'api', 'core', () => withRoot(async (r) => {
+        const bearer = await r.raw({ body: JSON.stringify(['SET', 'a:k', 'v']), headers: { authorization: 'Bearer some-token' } });
+        const bare = await r.raw({ body: JSON.stringify(['GET', 'a:k']), headers: { authorization: 'some-token' } });
+        return bearer.status === 200 && bare.status === 200 && bare.body.result === 'v';
+    })),
+    done('upstash.auth.query_token_wins', 'auth', 'the documented `?_token=` query parameter authenticates, is NOT passed through as a command argument, and OVERRIDES a bogus Authorization header (LIVE-PROBED precedence)', 'api', 'common', () => withRoot(async (r) => {
+        const set = await r.raw({ method: 'GET', path: '/set/qt:k/qv?_token=any-token', headers: {} });
+        const overridden = await r.raw({ method: 'GET', path: '/get/qt:k?_token=any-token', headers: { authorization: 'Bearer bogus' } });
+        return set.status === 200 && overridden.status === 200 && overridden.body.result === 'qv';
+    })),
+    done('upstash.auth.configured_token_enforced', 'auth', 'when the twin is started with an explicit token, a DIFFERENT credential is refused with the same 401 while the right one succeeds — so a world can model a real credential rather than accepting anything', 'api', 'common', () => withRoot(async (r) => {
+        const wrong = await r.raw({ body: JSON.stringify(['PING']), headers: { authorization: 'Bearer nope' }, token: 'the-real-token' });
+        const right = await r.raw({ body: JSON.stringify(['PING']), headers: { authorization: 'Bearer the-real-token' }, token: 'the-real-token' });
+        return wrong.status === 401 && right.status === 200 && right.body.result === 'PONG';
+    })),
+    // ── STRINGS ─────────────────────────────────────────────────────────────────────────────────
+    done('upstash.strings.set_get', 'strings', 'SET/GET round-trip the exact bytes; GET of a missing key -> nil', 'api', 'core', () => withRoot(async (r) => {
+        await r(['SET', 's:k', '{"json":"payload"}']);
+        const got = await r(['GET', 's:k']);
+        const missing = await r(['GET', 's:none']);
+        return got.result === '{"json":"payload"}' && missing.result === null && missing.status === 200;
+    })),
+    done('upstash.strings.set_expiry_options', 'strings', 'SET … EX/PX/EXAT/PXAT set a TTL and KEEPTTL preserves one across an overwrite (a plain SET CLEARS it); option tokens are parsed case-insensitively, which the SDK requires since it emits `keepTtl` in camelCase', 'api', 'core', () => withRoot(async (r) => {
+        await r(['SET', 's:ex', 'v', 'EX', '100']);
+        const ex = await r(['TTL', 's:ex']);
+        await r(['SET', 's:px', 'v', 'px', '5000']);
+        const px = await r(['PTTL', 's:px']);
+        await r(['SET', 's:ex', 'v2', 'keepTtl']);
+        const kept = await r(['TTL', 's:ex']);
+        await r(['SET', 's:ex', 'v3']);
+        const cleared = await r(['TTL', 's:ex']);
+        return ex.result === 100 && px.result === 5000 && kept.result === 100 && cleared.result === -1;
+    })),
+    done('upstash.strings.set_nx_returns_nil', 'strings', 'SET … NX on an EXISTING key answers nil (NOT "OK") and leaves the value alone; XX on a MISSING key does the same — the branch every distributed lock and dedupe guard in the real consumer depends on', 'api', 'core', () => withRoot(async (r) => {
+        const first = await r(['SET', 's:lock', 'a', 'NX', 'EX', '60']);
+        const second = await r(['SET', 's:lock', 'b', 'NX', 'EX', '60']);
+        const value = await r(['GET', 's:lock']);
+        const xxMissing = await r(['SET', 's:absent', 'z', 'XX']);
+        return first.result === 'OK' && second.result === null && value.result === 'a' && xxMissing.result === null;
+    })),
+    done('upstash.strings.set_get_option', 'strings', 'SET … GET answers the PREVIOUS value (nil when there was none) while still applying the write, and raises WRONGTYPE when the old key held a non-string', 'api', 'niche', () => withRoot(async (r) => {
+        const firstWrite = await r(['SET', 's:g', 'one', 'GET']);
+        const secondWrite = await r(['SET', 's:g', 'two', 'GET']);
+        const now = await r(['GET', 's:g']);
+        await r(['RPUSH', 's:gl', 'x']);
+        const wrong = await r(['SET', 's:gl', 'y', 'GET']);
+        return firstWrite.result === null && secondWrite.result === 'one' && now.result === 'two'
+            && wrong.status === 400 && wrong.error === 'WRONGTYPE Operation against a key holding the wrong kind of value';
+    })),
+    done('upstash.strings.setex_setnx_getset_getdel', 'strings', 'SETEX/PSETEX set value+TTL atomically, SETNX answers 0/1, GETSET returns the old value, and GETDEL consumes the key in one round trip', 'api', 'common', () => withRoot(async (r) => {
+        await r(['SETEX', 's:e', '30', 'v']);
+        const ttl = await r(['TTL', 's:e']);
+        const nx1 = await r(['SETNX', 's:n', 'first']);
+        const nx2 = await r(['SETNX', 's:n', 'second']);
+        const gs = await r(['GETSET', 's:n', 'third']);
+        const gd = await r(['GETDEL', 's:n']);
+        const after = await r(['GET', 's:n']);
+        return ttl.result === 30 && nx1.result === 1 && nx2.result === 0 && gs.result === 'first' && gd.result === 'third' && after.result === null;
+    })),
+    done('upstash.strings.mget_mset', 'strings', 'MGET answers a positionally-aligned array with nil in the holes (never a compacted list), and MSET writes every pair', 'api', 'core', () => withRoot(async (r) => {
+        await r(['MSET', 'm:a', '1', 'm:c', '3']);
+        const got = await r(['MGET', 'm:a', 'm:b', 'm:c']);
+        return JSON.stringify(got.result) === JSON.stringify(['1', null, '3']);
+    })),
+    done('upstash.strings.append_strlen_getex', 'strings', 'APPEND concatenates and returns the new length, STRLEN measures it, and GETEX reads the value while (re)setting or clearing its TTL', 'api', 'niche', () => withRoot(async (r) => {
+        const a1 = await r(['APPEND', 's:ap', 'foo']);
+        const a2 = await r(['APPEND', 's:ap', 'bar']);
+        const len = await r(['STRLEN', 's:ap']);
+        const gx = await r(['GETEX', 's:ap', 'EX', '50']);
+        const ttl = await r(['TTL', 's:ap']);
+        const persisted = await r(['GETEX', 's:ap', 'PERSIST']);
+        const noTtl = await r(['TTL', 's:ap']);
+        return a1.result === 3 && a2.result === 6 && len.result === 6 && gx.result === 'foobar' && ttl.result === 50 && persisted.result === 'foobar' && noTtl.result === -1;
+    })),
+    // ── COUNTERS ────────────────────────────────────────────────────────────────────────────────
+    done('upstash.counters.incr_decr', 'counters', 'INCR/DECR/INCRBY/DECRBY treat a missing key as 0 and answer the NEW integer value', 'api', 'core', () => withRoot(async (r) => {
+        const i1 = await r(['INCR', 'c:n']);
+        const i2 = await r(['INCRBY', 'c:n', '9']);
+        const d1 = await r(['DECR', 'c:n']);
+        const d2 = await r(['DECRBY', 'c:n', '4']);
+        const stored = await r(['GET', 'c:n']);
+        return i1.result === 1 && i2.result === 10 && d1.result === 9 && d2.result === 5 && stored.result === '5';
+    })),
+    done('upstash.counters.non_integer_error', 'counters', 'INCR against a non-numeric string -> 400 "ERR value is not an integer or out of range" (the live server\'s wording, which differs from the docs\' own stale "not an int" example), and the value is UNCHANGED', 'api', 'core', () => withRoot(async (r) => {
+        await r(['SET', 'c:s', 'abc']);
+        const bad = await r(['INCR', 'c:s']);
+        const unchanged = await r(['GET', 'c:s']);
+        return bad.status === 400 && bad.error === 'ERR value is not an integer or out of range' && unchanged.result === 'abc';
+    })),
+    done('upstash.counters.incr_preserves_ttl', 'counters', 'INCR does NOT clear an existing TTL — the exact semantic @upstash/ratelimit\'s fixed-window script relies on (it arms PEXPIRE once on the first increment and every later one must leave the deadline alone, or the window would never close)', 'api', 'core', () => withRoot(async (r) => {
+        await r(['SET', 'c:t', '1', 'EX', '60']);
+        await r(['INCR', 'c:t']);
+        await r(['INCRBY', 'c:t', '5']);
+        const ttl = await r(['TTL', 'c:t']);
+        const value = await r(['GET', 'c:t']);
+        return ttl.result === 60 && value.result === '7';
+    })),
+    done('upstash.counters.incrbyfloat', 'counters', 'INCRBYFLOAT and HINCRBYFLOAT answer a bulk STRING, reject a non-float, and REFUSE a result that would be NaN or Infinity with Redis\'s own "ERR increment would produce NaN or Infinity" — the guard §9 round 2 found missing on these two paths, where the twin was answering 200 and then persisting the literal "NaN" into a key its own next INCRBYFLOAT could no longer read', 'api', 'common', () => withRoot(async (r) => {
+        const f = await r(['INCRBYFLOAT', 'c:f', '1.5']);
+        const f2 = await r(['INCRBYFLOAT', 'c:f', '2.25']);
+        const bad = await r(['INCRBYFLOAT', 'c:f', 'nope']);
+        // The NaN/Infinity guard, on BOTH float-increment paths, and on both routes to it.
+        const toInf = await r(['INCRBYFLOAT', 'c:f', 'inf']);
+        const overflow = await r(['INCRBYFLOAT', 'c:big', '1e308']);
+        const overflow2 = await r(['INCRBYFLOAT', 'c:big', '1e308']);
+        const hashInf = await r(['HINCRBYFLOAT', 'c:h', 'fld', 'inf']);
+        // …and the key is UNCHANGED by every refusal, not left holding a poisoned value.
+        const intact = await r(['GET', 'c:f']);
+        const hashAbsent = await r(['EXISTS', 'c:h']);
+        const NAN_ERR = 'ERR increment would produce NaN or Infinity';
+        return f.result === '1.5' && f2.result === '3.75'
+            && bad.status === 400 && bad.error === 'ERR value is not a valid float'
+            && toInf.status === 400 && toInf.error === NAN_ERR
+            && overflow.result === '1e+308' && overflow2.status === 400 && overflow2.error === NAN_ERR
+            && hashInf.status === 400 && hashInf.error === NAN_ERR
+            && intact.result === '3.75' && hashAbsent.result === 0;
+    })),
+    // ── KEYSPACE / TTL ──────────────────────────────────────────────────────────────────────────
+    done('upstash.keyspace.del_exists', 'keyspace', 'DEL removes N keys and answers how many EXISTED; EXISTS counts them (both variadic)', 'api', 'core', () => withRoot(async (r) => {
+        await r(['MSET', 'k:a', '1', 'k:b', '2']);
+        const exists = await r(['EXISTS', 'k:a', 'k:b', 'k:missing']);
+        const del = await r(['DEL', 'k:a', 'k:missing']);
+        const after = await r(['EXISTS', 'k:a']);
+        return exists.result === 2 && del.result === 1 && after.result === 0;
+    })),
+    done('upstash.keyspace.expire_ttl_persist', 'keyspace', 'EXPIRE/PEXPIRE/EXPIREAT/PEXPIREAT set a deadline (0 on a missing key), TTL/PTTL report it (-1 no TTL, -2 no key), PERSIST clears it', 'api', 'core', () => withRoot(async (r) => {
+        await r(['SET', 'k:t', 'v']);
+        const noTtl = await r(['TTL', 'k:t']);
+        const set = await r(['EXPIRE', 'k:t', '120']);
+        const ttl = await r(['TTL', 'k:t']);
+        const missing = await r(['EXPIRE', 'k:none', '10']);
+        const gone = await r(['TTL', 'k:none']);
+        const persist = await r(['PERSIST', 'k:t']);
+        const cleared = await r(['TTL', 'k:t']);
+        return noTtl.result === -1 && set.result === 1 && ttl.result === 120 && missing.result === 0 && gone.result === -2 && persist.result === 1 && cleared.result === -1;
+    })),
+    done('upstash.keyspace.lazy_expiry', 'keyspace', 'once the request clock passes a key\'s deadline the key stops existing for EVERY read path at once — GET, EXISTS, TTL, TYPE, KEYS and DBSIZE all agree — and a past deadline passed to EXPIRE deletes the key immediately', 'api', 'core', () => withRoot(async (r) => {
+        await r(['SET', 'x:soon', 'v', 'EX', '10']);
+        await r(['SET', 'x:stay', 'v']);
+        const before = await r(['GET', 'x:soon']);
+        const at = laterAt(11_000);
+        const [get, exists, ttl, type, keys, dbsize] = await Promise.all([
+            r(['GET', 'x:soon'], { at }), r(['EXISTS', 'x:soon'], { at }), r(['TTL', 'x:soon'], { at }),
+            r(['TYPE', 'x:soon'], { at }), r(['KEYS', 'x:*'], { at }), r(['DBSIZE'], { at }),
+        ]);
+        const past = await r(['EXPIRE', 'x:stay', '-1']);
+        const stayGone = await r(['EXISTS', 'x:stay']);
+        return before.result === 'v' && get.result === null && exists.result === 0 && ttl.result === -2
+            && type.result === 'none' && JSON.stringify(keys.result) === JSON.stringify(['x:stay']) && dbsize.result === 1
+            && past.result === 1 && stayGone.result === 0;
+    })),
+    done('upstash.keyspace.past_deadline_within_one_request', 'keyspace', 'a deadline set INTO THE PAST takes effect immediately — even for the rest of the SAME pipeline. §9 round 2 found expiry being applied only when the request snapshot was built, so SET k v PXAT 1 stayed readable for every later command in that batch and TTL answered a huge negative number real Redis can never return; expiry is now re-checked on every read', 'api', 'common', () => withRoot(async (r) => {
+        // ONE batch: the write and every read that follows it are in the same request.
+        const res = await r.raw({ path: '/pipeline', body: JSON.stringify([
+                ['SET', 'past', 'v', 'PXAT', '1'],
+                ['GET', 'past'], ['EXISTS', 'past'], ['TTL', 'past'], ['TYPE', 'past'], ['DBSIZE'],
+                ['SET', 'live', 'v'], ['GETEX', 'live', 'EXAT', '1'], ['GET', 'live'], ['EXISTS', 'live'],
+            ]) });
+        const items = res.body.map((i) => i.result);
+        // GET nil, EXISTS 0, TTL -2 (never a large negative), TYPE none, DBSIZE 0 — all within the batch.
+        return res.status === 200
+            && items[1] === null && items[2] === 0 && items[3] === -2 && items[4] === 'none' && items[5] === 0
+            && items[8] === null && items[9] === 0;
+    })),
+    done('upstash.keyspace.type_and_wrongtype', 'keyspace', 'TYPE names each of the six value types (and "none" for a missing key), and a command aimed at the wrong type raises the vendor\'s literal WRONGTYPE error', 'api', 'core', () => withRoot(async (r) => {
+        await r(['SET', 't:s', 'v']);
+        await r(['RPUSH', 't:l', 'a']);
+        await r(['SADD', 't:se', 'a']);
+        await r(['HSET', 't:h', 'f', 'v']);
+        await r(['ZADD', 't:z', '1', 'a']);
+        await r(['XADD', 't:x', '*', 'f', 'v']);
+        const types = await Promise.all(['t:s', 't:l', 't:se', 't:h', 't:z', 't:x', 't:none'].map((k) => r(['TYPE', k])));
+        const wrong = await r(['GET', 't:l']);
+        const wrong2 = await r(['SADD', 't:s', 'x']);
+        return JSON.stringify(types.map((t) => t.result)) === JSON.stringify(['string', 'list', 'set', 'hash', 'zset', 'stream', 'none'])
+            && wrong.status === 400 && wrong.error === 'WRONGTYPE Operation against a key holding the wrong kind of value'
+            && wrong2.status === 400 && wrong2.error === 'WRONGTYPE Operation against a key holding the wrong kind of value';
+    })),
+    done('upstash.keyspace.rename', 'keyspace', 'RENAME moves the value AND its TTL and answers OK; renaming a missing key -> 400 "ERR no such key"; RENAMENX refuses to clobber an existing destination', 'api', 'common', () => withRoot(async (r) => {
+        await r(['SET', 'r:old', 'v', 'EX', '90']);
+        const ok = await r(['RENAME', 'r:old', 'r:new']);
+        const value = await r(['GET', 'r:new']);
+        const ttl = await r(['TTL', 'r:new']);
+        const oldGone = await r(['EXISTS', 'r:old']);
+        const missing = await r(['RENAME', 'r:nope', 'r:x']);
+        await r(['SET', 'r:taken', 'other']);
+        const nx = await r(['RENAMENX', 'r:new', 'r:taken']);
+        return ok.result === 'OK' && value.result === 'v' && ttl.result === 90 && oldGone.result === 0
+            && missing.status === 400 && missing.error === 'ERR no such key' && nx.result === 0;
+    })),
+    done('upstash.keyspace.keys_and_dbsize', 'keyspace', 'KEYS applies Redis GLOB matching (*, ?, [abc]) and DBSIZE counts live keys — and neither ever leaks the twin\'s internal EVAL script-cache entries into the keyspace', 'api', 'common', () => withRoot(async (r) => {
+        await r(['MSET', 'user:1', 'a', 'user:2', 'b', 'other:1', 'c']);
+        await r(['EVAL', 'return 1', '0']); // populates the internal script cache
+        const star = await r(['KEYS', 'user:*']);
+        const single = await r(['KEYS', 'user:?']);
+        const cls = await r(['KEYS', '[ou]ther:1']);
+        const size = await r(['DBSIZE']);
+        const all = await r(['KEYS', '*']);
+        return JSON.stringify(star.result) === JSON.stringify(['user:1', 'user:2'])
+            && JSON.stringify(single.result) === JSON.stringify(['user:1', 'user:2'])
+            && JSON.stringify(cls.result) === JSON.stringify(['other:1'])
+            && size.result === 3 && all.result.length === 3;
+    })),
+    done('upstash.keyspace.scan', 'keyspace', 'SCAN answers the two-element [cursor, keys] tuple the SDK destructures, honours MATCH/COUNT/TYPE, and terminates by returning cursor "0" after covering every key exactly once', 'api', 'common', () => withRoot(async (r) => {
+        await r(['MSET', 'sc:1', 'a', 'sc:2', 'b', 'sc:3', 'c', 'sc:4', 'd']);
+        await r(['RPUSH', 'sc:list', 'x']);
+        const seen = [];
+        let cursor = '0';
+        let guard = 0;
+        do {
+            const page = await r(['SCAN', cursor, 'MATCH', 'sc:*', 'COUNT', '2']);
+            const [next, keys] = page.result;
+            seen.push(...keys);
+            cursor = next;
+        } while (cursor !== '0' && ++guard < 20);
+        const typed = await r(['SCAN', '0', 'MATCH', 'sc:*', 'COUNT', '100', 'TYPE', 'list']);
+        return seen.sort().join(',') === 'sc:1,sc:2,sc:3,sc:4,sc:list'
+            && JSON.stringify(typed.result[1]) === JSON.stringify(['sc:list']);
+    })),
+    done('upstash.keyspace.scan_survives_mutation', 'keyspace', 'DIRTY-STATE: SCAN honours Redis\'s ONE cursor guarantee — a key present for the WHOLE iteration is returned at least once even as other keys are DELETED between pages. The §9 round-1 refutation killed the first design (an index into a sorted list, which shifts left under the cursor when a lower-sorted key goes, silently skipping a survivor); the cursor is now a position in a stable KEY-DERIVED order, so no key\'s position moves when a different key does', 'api', 'core', () => withRoot(async (r) => {
+        const names = Array.from({ length: 12 }, (_, i) => `walk:${i}`);
+        await r(['MSET', ...names.flatMap((n) => [n, '1'])]);
+        const seen = new Set();
+        let cursor = '0';
+        let deleted = 0;
+        let guard = 0;
+        do {
+            const page = await r(['SCAN', cursor, 'COUNT', '3']);
+            const [next, keys] = page.result;
+            keys.forEach((k) => seen.add(k));
+            // Mutate BETWEEN pages — the whole point. A fresh-keyspace scan cannot see this class.
+            if (deleted < 4) {
+                await r(['DEL', names[deleted]]);
+                deleted++;
+            }
+            cursor = next;
+        } while (cursor !== '0' && ++guard < 60);
+        // Every key that was present for the entire scan must have been returned.
+        const survivors = names.slice(4);
+        return cursor === '0' && survivors.every((n) => seen.has(n));
+    })),
+    done('upstash.keyspace.flushdb', 'keyspace', 'FLUSHDB empties the whole keyspace and answers OK; DBSIZE then reads 0', 'api', 'niche', () => withRoot(async (r) => {
+        await r(['MSET', 'f:a', '1', 'f:b', '2']);
+        const flush = await r(['FLUSHDB']);
+        const size = await r(['DBSIZE']);
+        const gone = await r(['GET', 'f:a']);
+        return flush.result === 'OK' && size.result === 0 && gone.result === null;
+    })),
+    done('upstash.keyspace.dirty_state_delete_recreate', 'keyspace', 'DIRTY-STATE: a key deleted and RECREATED carries none of its former life — no stale TTL, no stale type, no resurrected members — and an emptied collection (last member removed) genuinely stops existing rather than lingering as an empty husk', 'api', 'core', () => withRoot(async (r) => {
+        // Build up real state first: this verify is worthless from a fresh key.
+        await r(['SET', 'd:k', 'first', 'EX', '60']);
+        await r(['DEL', 'd:k']);
+        await r(['RPUSH', 'd:k', 'now-a-list']); // recreated as a DIFFERENT type
+        const type = await r(['TYPE', 'd:k']);
+        const ttl = await r(['TTL', 'd:k']); // must be -1, not the old 60
+        // An emptied collection must vanish, not linger — otherwise a later SET would WRONGTYPE.
+        await r(['SADD', 'd:s', 'only']);
+        await r(['SREM', 'd:s', 'only']);
+        const emptied = await r(['EXISTS', 'd:s']);
+        const reuse = await r(['SET', 'd:s', 'plain-string-now']);
+        await r(['HSET', 'd:h', 'f', 'v']);
+        await r(['HDEL', 'd:h', 'f']);
+        const hashGone = await r(['EXISTS', 'd:h']);
+        return type.result === 'list' && ttl.result === -1 && emptied.result === 0 && reuse.result === 'OK' && hashGone.result === 0;
+    })),
+    done('upstash.keyspace.no_internal_namespace_collision', 'keyspace', 'a caller\'s key can never collide with the twin\'s own internals: the EVAL script cache lives in a SEPARATE kernel subject type, so a key named like a cache entry stays a normal, listable key and is NOT executable as a script (§9 self-audit found the earlier magic-prefix design hid such a key from KEYS/SCAN/DBSIZE and let EVALSHA run it)', 'api', 'core', () => withRoot(async (r) => {
+        const sneaky = ' twin:script:deadbeef'; // a legal Redis key — a leading space is fine
+        await r(['SET', sneaky, 'return 999']);
+        const keys = await r(['KEYS', '*']);
+        const size = await r(['DBSIZE']);
+        const readable = await r(['GET', sneaky]);
+        const asScript = await r(['EVALSHA', 'deadbeef', '0']);
+        // …and the REAL cache still works, in its own namespace, without becoming a key.
+        const load = await r(['SCRIPT', 'LOAD', 'return 7']);
+        const ran = await r(['EVALSHA', load.result, '0']);
+        const sizeAfter = await r(['DBSIZE']);
+        return JSON.stringify(keys.result) === JSON.stringify([sneaky]) && size.result === 1
+            && readable.result === 'return 999'
+            && asScript.status === 400 && asScript.error === 'NOSCRIPT No matching script. Please use EVAL.'
+            && ran.result === 7 && sizeAfter.result === 1;
+    })),
+    done('upstash.keyspace.reply_and_state_never_disagree', 'keyspace', 'DIRTY-STATE: writing a key back to a value it ALREADY HELD sticks — the reply and the stored state can never disagree. The kernel dedupes actions by (content + occurredAt millisecond), so a pinned-clock sequence that returns a key to an earlier value used to be silently dropped as a replay: the command answered the new value while the projection kept the old one. Every write now carries a per-key ordinal, so no write can be mistaken for a replay', 'api', 'core', () => withRoot(async (r) => {
+        // (a) the shape that found it: a ZADD INCR walk that lands back on a score it held before.
+        await r(['ZADD', 'w', '10', 'm']);
+        const steps = [
+            [['ZADD', 'w', 'INCR', '5', 'm'], '15'],
+            [['ZADD', 'w', 'XX', 'INCR', '5', 'm'], '20'],
+            [['ZADD', 'w', 'GT', 'INCR', '5', 'm'], '25'],
+            [['ZADD', 'w', 'LT', 'INCR', '-5', 'm'], '20'], // back to a score already seen at this instant
+        ];
+        for (const [argv, expected] of steps) {
+            const reply = await r(argv);
+            const stored = await r(['ZSCORE', 'w', 'm']);
+            // THE assertion: what the command SAID and what the twin KEPT must be the same thing.
+            if (reply.result !== expected || stored.result !== expected)
+                return false;
+        }
+        // (b) the plain-string shape of the same hazard, and (c) delete-then-recreate-identical.
+        await r(['SET', 'k', 'a']);
+        await r(['SET', 'k', 'b']);
+        await r(['SET', 'k', 'a']);
+        const back = await r(['GET', 'k']);
+        await r(['DEL', 'k']);
+        await r(['SET', 'k', 'a']);
+        const recreated = await r(['GET', 'k']);
+        return back.result === 'a' && recreated.result === 'a';
+    })),
+    done('upstash.keyspace.persistence_across_restart', 'keyspace', 'state is the KERNEL ACTION LOG, not process memory: a value written through one handler invocation is readable by a completely independent one pointed at the same root — which is what makes this a twin rather than a mock', 'api', 'core', () => withRoot(async (r, root) => {
+        await r(['SET', 'persist:k', 'survives']);
+        await r(['HSET', 'persist:h', 'f', 'hv']);
+        // A brand-new call with no shared in-process state whatsoever — only the root on disk.
+        const fresh = await handleUpstashRedisTwinRequest({ method: 'POST', path: '/', headers: AUTH, root, occurredAt: AT, body: JSON.stringify(['GET', 'persist:k']) });
+        const freshHash = await handleUpstashRedisTwinRequest({ method: 'POST', path: '/', headers: AUTH, root, occurredAt: AT, body: JSON.stringify(['HGET', 'persist:h', 'f']) });
+        return fresh.body.result === 'survives' && freshHash.body.result === 'hv';
+    })),
+    // ── HASHES ──────────────────────────────────────────────────────────────────────────────────
+    done('upstash.hashes.set_get', 'hashes', 'HSET answers how many fields were NEW (0 on an overwrite), HGET reads one field, and a missing field/key answers nil', 'api', 'core', () => withRoot(async (r) => {
+        const first = await r(['HSET', 'h:k', 'a', '1', 'b', '2']);
+        const overwrite = await r(['HSET', 'h:k', 'a', '9']);
+        const got = await r(['HGET', 'h:k', 'a']);
+        const missingField = await r(['HGET', 'h:k', 'zz']);
+        const missingKey = await r(['HGET', 'h:none', 'a']);
+        return first.result === 2 && overwrite.result === 0 && got.result === '9' && missingField.result === null && missingKey.result === null;
+    })),
+    done('upstash.hashes.getall_mget_keys_vals', 'hashes', 'HGETALL answers the FLAT [field, value, …] array the SDK folds into an object, HMGET answers positional nils for absent fields, and HKEYS/HVALS/HLEN agree with it', 'api', 'core', () => withRoot(async (r) => {
+        await r(['HSET', 'h:m', 'x', '1', 'y', '2']);
+        const all = await r(['HGETALL', 'h:m']);
+        const mget = await r(['HMGET', 'h:m', 'x', 'nope', 'y']);
+        const keys = await r(['HKEYS', 'h:m']);
+        const vals = await r(['HVALS', 'h:m']);
+        const len = await r(['HLEN', 'h:m']);
+        return JSON.stringify(all.result) === JSON.stringify(['x', '1', 'y', '2'])
+            && JSON.stringify(mget.result) === JSON.stringify(['1', null, '2'])
+            && JSON.stringify(keys.result) === JSON.stringify(['x', 'y'])
+            && JSON.stringify(vals.result) === JSON.stringify(['1', '2']) && len.result === 2;
+    })),
+    done('upstash.hashes.del_exists_incrby', 'hashes', 'HDEL answers how many fields it removed and DROPS the key once the last one goes, HEXISTS reports membership, and HINCRBY/HINCRBYFLOAT do arithmetic on a field (rejecting a non-numeric one)', 'api', 'common', () => withRoot(async (r) => {
+        await r(['HSET', 'h:d', 'a', '1', 'b', 'notanum']);
+        const exists = await r(['HEXISTS', 'h:d', 'a']);
+        const inc = await r(['HINCRBY', 'h:d', 'a', '4']);
+        const incFloat = await r(['HINCRBYFLOAT', 'h:d', 'c', '2.5']);
+        const bad = await r(['HINCRBY', 'h:d', 'b', '1']);
+        const del = await r(['HDEL', 'h:d', 'a', 'b', 'c', 'missing']);
+        const keyGone = await r(['EXISTS', 'h:d']);
+        return exists.result === 1 && inc.result === 5 && incFloat.result === '2.5'
+            && bad.status === 400 && bad.error === 'ERR value is not an integer or out of range'
+            && del.result === 3 && keyGone.result === 0;
+    })),
+    // ── SETS ────────────────────────────────────────────────────────────────────────────────────
+    done('upstash.sets.add_members', 'sets', 'SADD answers how many members were NEW (deduping silently), SMEMBERS lists them and SCARD counts them', 'api', 'core', () => withRoot(async (r) => {
+        const first = await r(['SADD', 'se:k', 'a', 'b']);
+        const dup = await r(['SADD', 'se:k', 'b', 'c']);
+        const members = await r(['SMEMBERS', 'se:k']);
+        const card = await r(['SCARD', 'se:k']);
+        return first.result === 2 && dup.result === 1 && members.result.sort().join(',') === 'a,b,c' && card.result === 3;
+    })),
+    done('upstash.sets.membership', 'sets', 'SISMEMBER answers 0/1 and SMISMEMBER answers a positionally-aligned 0/1 array — the batch form a real consumer uses to check many ids in one round trip', 'api', 'core', () => withRoot(async (r) => {
+        await r(['SADD', 'se:m', 'x', 'y']);
+        const yes = await r(['SISMEMBER', 'se:m', 'x']);
+        const no = await r(['SISMEMBER', 'se:m', 'zz']);
+        const batch = await r(['SMISMEMBER', 'se:m', 'x', 'zz', 'y']);
+        return yes.result === 1 && no.result === 0 && JSON.stringify(batch.result) === JSON.stringify([1, 0, 1]);
+    })),
+    done('upstash.sets.remove', 'sets', 'SREM answers how many members it actually removed and the key disappears once the set is empty', 'api', 'common', () => withRoot(async (r) => {
+        await r(['SADD', 'se:r', 'a', 'b']);
+        const some = await r(['SREM', 'se:r', 'a', 'never-there']);
+        const rest = await r(['SREM', 'se:r', 'b']);
+        const gone = await r(['EXISTS', 'se:r']);
+        return some.result === 1 && rest.result === 1 && gone.result === 0;
+    })),
+    // ── SORTED SETS ─────────────────────────────────────────────────────────────────────────────
+    done('upstash.sorted_sets.add_and_range', 'sorted_sets', 'ZADD answers how many members were NEW, ZRANGE walks in (score, member) order, WITHSCORES interleaves scores as bulk strings, and REV reverses', 'api', 'core', () => withRoot(async (r) => {
+        const add = await r(['ZADD', 'z:k', '2', 'b', '1', 'a', '3', 'c']);
+        const range = await r(['ZRANGE', 'z:k', '0', '-1']);
+        const scores = await r(['ZRANGE', 'z:k', '0', '-1', 'WITHSCORES']);
+        const _rev = await r(['ZREVRANGE', 'z:k', '0', '-1']);
+        const slice = await r(['ZRANGE', 'z:k', '1', '1']);
+        return add.result === 3
+            && JSON.stringify(range.result) === JSON.stringify(['a', 'b', 'c'])
+            && JSON.stringify(scores.result) === JSON.stringify(['a', '1', 'b', '2', 'c', '3'])
+            && JSON.stringify(_rev.result) === JSON.stringify(['c', 'b', 'a'])
+            && JSON.stringify(slice.result) === JSON.stringify(['b']);
+    })),
+    done('upstash.sorted_sets.add_flags', 'sorted_sets', 'ZADD NX/XX/GT/LT/CH behave as Redis specifies (NX never updates, XX never inserts, GT/LT only move a score in one direction, CH counts CHANGED rather than added), and NX+XX together is refused', 'api', 'common', () => withRoot(async (r) => {
+        await r(['ZADD', 'z:f', '5', 'm']);
+        await r(['ZADD', 'z:f', 'NX', '1', 'm']);
+        const afterNx = await r(['ZSCORE', 'z:f', 'm']);
+        const xxMissing = await r(['ZADD', 'z:f', 'XX', '1', 'absent']);
+        await r(['ZADD', 'z:f', 'GT', '3', 'm']); // 3 < 5 → no move
+        const afterGt = await r(['ZSCORE', 'z:f', 'm']);
+        await r(['ZADD', 'z:f', 'GT', '9', 'm']); // 9 > 5 → moves
+        const afterGt2 = await r(['ZSCORE', 'z:f', 'm']);
+        const ch = await r(['ZADD', 'z:f', 'CH', '9', 'm', '1', 'fresh']);
+        const conflict = await r(['ZADD', 'z:f', 'NX', 'XX', '1', 'q']);
+        return afterNx.result === '5' && xxMissing.result === 0 && afterGt.result === '5' && afterGt2.result === '9'
+            && ch.result === 1 && conflict.status === 400 && conflict.error === 'ERR XX and NX options at the same time are not compatible';
+    })),
+    done('upstash.sorted_sets.score_ops', 'sorted_sets', 'ZSCORE answers a bulk string (nil when absent), ZINCRBY moves a score and RE-SORTS the set, ZCARD counts, and ZRANK/ZREVRANK report position', 'api', 'core', () => withRoot(async (r) => {
+        await r(['ZADD', 'z:s', '1', 'a', '2', 'b']);
+        const score = await r(['ZSCORE', 'z:s', 'b']);
+        const absent = await r(['ZSCORE', 'z:s', 'zz']);
+        const inc = await r(['ZINCRBY', 'z:s', '5', 'a']);
+        const order = await r(['ZRANGE', 'z:s', '0', '-1']);
+        const rank = await r(['ZRANK', 'z:s', 'a']);
+        const revRank = await r(['ZREVRANK', 'z:s', 'a']);
+        const card = await r(['ZCARD', 'z:s']);
+        return score.result === '2' && absent.result === null && inc.result === '6'
+            && JSON.stringify(order.result) === JSON.stringify(['b', 'a']) && rank.result === 1 && revRank.result === 0 && card.result === 2;
+    })),
+    done('upstash.sorted_sets.range_by_score', 'sorted_sets', 'ZRANGEBYSCORE honours inclusive, EXCLUSIVE "(" and infinite bounds plus LIMIT offset/count; ZCOUNT agrees with it; ZREMRANGEBYSCORE removes exactly that window', 'api', 'common', () => withRoot(async (r) => {
+        await r(['ZADD', 'z:r', '1', 'a', '2', 'b', '3', 'c', '4', 'd']);
+        const inclusive = await r(['ZRANGEBYSCORE', 'z:r', '2', '3']);
+        const exclusive = await r(['ZRANGEBYSCORE', 'z:r', '(2', '(4']);
+        const infinite = await r(['ZRANGEBYSCORE', 'z:r', '-inf', '+inf']);
+        const limited = await r(['ZRANGEBYSCORE', 'z:r', '-inf', '+inf', 'LIMIT', '1', '2']);
+        const count = await r(['ZCOUNT', 'z:r', '2', '3']);
+        const removed = await r(['ZREMRANGEBYSCORE', 'z:r', '1', '2']);
+        const left = await r(['ZRANGE', 'z:r', '0', '-1']);
+        return JSON.stringify(inclusive.result) === JSON.stringify(['b', 'c'])
+            && JSON.stringify(exclusive.result) === JSON.stringify(['c'])
+            && infinite.result.length === 4
+            && JSON.stringify(limited.result) === JSON.stringify(['b', 'c'])
+            && count.result === 2 && removed.result === 2 && JSON.stringify(left.result) === JSON.stringify(['c', 'd']);
+    })),
+    done('upstash.sorted_sets.infinite_scores_persist', 'sorted_sets', 'DIRTY-STATE: a ±inf score SURVIVES the kernel round-trip and still sorts and ranges correctly on a LATER request — the §9 round-1 refutation, where an in-memory +inf was JSON-serialised to null and came back as the literal bulk string "null", so ZRANGEBYSCORE key 0 100 returned an infinite-scored member', 'api', 'common', () => withRoot(async (r) => {
+        await r(['ZADD', 'zi', '+inf', 'top', '-inf', 'bottom', '1.5', 'mid']);
+        // EVERY assertion below is a SEPARATE request, so each one reads through the persisted form.
+        const top = await r(['ZSCORE', 'zi', 'top']);
+        const bottom = await r(['ZSCORE', 'zi', 'bottom']);
+        const mid = await r(['ZSCORE', 'zi', 'mid']);
+        const window = await r(['ZRANGEBYSCORE', 'zi', '0', '100']); // must NOT contain the infinities
+        const everything = await r(['ZRANGEBYSCORE', 'zi', '-inf', '+inf']);
+        const ordered = await r(['ZRANGE', 'zi', '0', '-1', 'WITHSCORES']);
+        // …and inf + -inf is Redis's NaN refusal, not a NaN score written to disk. (The SAME guard
+        // on the string/hash float paths is proven separately by upstash.counters.incrbyfloat —
+        // §9 round 2 found it present here but missing there.)
+        const nan = await r(['ZADD', 'zi', 'INCR', '-inf', 'top']);
+        return top.result === 'inf' && bottom.result === '-inf' && mid.result === '1.5'
+            && JSON.stringify(window.result) === JSON.stringify(['mid'])
+            && JSON.stringify(everything.result) === JSON.stringify(['bottom', 'mid', 'top'])
+            && JSON.stringify(ordered.result) === JSON.stringify(['bottom', '-inf', 'mid', '1.5', 'top', 'inf'])
+            && nan.status === 400 && nan.error === 'ERR resulting score is not a number (NaN)';
+    })),
+    done('upstash.sorted_sets.xx_creates_no_key', 'sorted_sets', 'ZADD … XX against a MISSING key adds nothing AND creates no key — no empty husk for EXISTS/TYPE/DBSIZE/KEYS to report and no phantom type to make a later LPUSH on that name raise WRONGTYPE (the §9 round-1 refutation of "XX never inserts", which held at the member level but not the key level)', 'api', 'common', () => withRoot(async (r) => {
+        const added = await r(['ZADD', 'ghost', 'XX', '1', 'm']);
+        const exists = await r(['EXISTS', 'ghost']);
+        const size = await r(['DBSIZE']);
+        const type = await r(['TYPE', 'ghost']);
+        // The name must still be FREE — a husk would make this WRONGTYPE.
+        const reuse = await r(['LPUSH', 'ghost', 'x']);
+        // …while NX on a missing key still creates, which is what NX means.
+        const nx = await r(['ZADD', 'fresh', 'NX', '1', 'm']);
+        return added.result === 0 && exists.result === 0 && size.result === 0 && type.result === 'none'
+            && reuse.result === 1 && nx.result === 1;
+    })),
+    done('upstash.sorted_sets.gt_lt_incr_returns_nil', 'sorted_sets', 'ZADD … GT|LT with INCR answers NIL when it REFUSES the move (Redis\'s ZADD_OUT_NOP), not the unchanged score — the distinction a "only move this watermark forward" caller branches on, exactly as it branches on SET NX', 'api', 'niche', () => withRoot(async (r) => {
+        await r(['ZADD', 'w', '10', 'm']);
+        const refusedGt = await r(['ZADD', 'w', 'GT', 'INCR', '-5', 'm']);
+        const refusedLt = await r(['ZADD', 'w', 'LT', 'INCR', '5', 'm']);
+        const allowed = await r(['ZADD', 'w', 'GT', 'INCR', '5', 'm']);
+        const refusedNx = await r(['ZADD', 'w', 'NX', 'INCR', '5', 'm']);
+        const finalScore = await r(['ZSCORE', 'w', 'm']);
+        return refusedGt.result === null && refusedLt.result === null && allowed.result === '15'
+            && refusedNx.result === null && finalScore.result === '15';
+    })),
+    done('upstash.sorted_sets.remove', 'sorted_sets', 'ZREM answers how many members it removed and ZREMRANGEBYRANK removes by position; the key vanishes once empty', 'api', 'niche', () => withRoot(async (r) => {
+        await r(['ZADD', 'z:d', '1', 'a', '2', 'b', '3', 'c']);
+        const rem = await r(['ZREM', 'z:d', 'a', 'not-there']);
+        const byRank = await r(['ZREMRANGEBYRANK', 'z:d', '0', '0']);
+        const left = await r(['ZRANGE', 'z:d', '0', '-1']);
+        const removeRest = await r(['ZREM', 'z:d', 'c']);
+        const gone = await r(['EXISTS', 'z:d']);
+        return rem.result === 1 && byRank.result === 1 && JSON.stringify(left.result) === JSON.stringify(['c']) && removeRest.result === 1 && gone.result === 0;
+    })),
+    done('upstash.sorted_sets.range_bylex_refused', 'sorted_sets', 'ZRANGE … BYLEX is REFUSED BY NAME rather than silently answered as if it were BYSCORE — an unmodeled option must fail loudly, never return a plausible-looking wrong ordering', 'api', 'niche', () => withRoot(async (r) => {
+        await r(['ZADD', 'z:lex', '0', 'a', '0', 'b']);
+        const res = await r(['ZRANGE', 'z:lex', '[a', '[b', 'BYLEX']);
+        return res.status === 400 && res.error.includes('BYLEX is not modeled by this twin');
+    })),
+    // ── LISTS ───────────────────────────────────────────────────────────────────────────────────
+    done('upstash.lists.push_and_range', 'lists', 'LPUSH inserts each element at the head IN TURN (so `LPUSH k a b` leaves [b, a]) while RPUSH appends; both answer the new length, and LRANGE handles negative indices', 'api', 'core', () => withRoot(async (r) => {
+        const lp = await r(['LPUSH', 'l:k', 'a', 'b']);
+        const rp = await r(['RPUSH', 'l:k', 'c']);
+        const all = await r(['LRANGE', 'l:k', '0', '-1']);
+        const tail = await r(['LRANGE', 'l:k', '-2', '-1']);
+        const len = await r(['LLEN', 'l:k']);
+        return lp.result === 2 && rp.result === 3
+            && JSON.stringify(all.result) === JSON.stringify(['b', 'a', 'c'])
+            && JSON.stringify(tail.result) === JSON.stringify(['a', 'c']) && len.result === 3;
+    })),
+    done('upstash.lists.pop', 'lists', 'LPOP/RPOP answer a single element (nil on an empty list) and, with a COUNT, an ARRAY — the batched form a real consumer drains a work queue with; the key disappears once drained', 'api', 'core', () => withRoot(async (r) => {
+        await r(['RPUSH', 'l:p', 'a', 'b', 'c', 'd']);
+        const one = await r(['LPOP', 'l:p']);
+        const batch = await r(['LPOP', 'l:p', '2']);
+        const last = await r(['RPOP', 'l:p']);
+        const empty = await r(['LPOP', 'l:p']);
+        const gone = await r(['EXISTS', 'l:p']);
+        return one.result === 'a' && JSON.stringify(batch.result) === JSON.stringify(['b', 'c'])
+            && last.result === 'd' && empty.result === null && gone.result === 0;
+    })),
+    done('upstash.lists.index_set_trim_rem', 'lists', 'LINDEX reads by position (negatives from the end), LSET overwrites one (400 "ERR index out of range" past the end, "ERR no such key" on a missing list), LTRIM keeps a window, LREM removes N occurrences honouring the sign of count', 'api', 'common', () => withRoot(async (r) => {
+        await r(['RPUSH', 'l:i', 'a', 'b', 'a', 'c', 'a']);
+        const first = await r(['LINDEX', 'l:i', '0']);
+        const fromEnd = await r(['LINDEX', 'l:i', '-1']);
+        const remTwo = await r(['LREM', 'l:i', '2', 'a']);
+        const afterRem = await r(['LRANGE', 'l:i', '0', '-1']);
+        const set = await r(['LSET', 'l:i', '0', 'B']);
+        const oob = await r(['LSET', 'l:i', '99', 'x']);
+        const missing = await r(['LSET', 'l:none', '0', 'x']);
+        await r(['LTRIM', 'l:i', '0', '0']);
+        const trimmed = await r(['LRANGE', 'l:i', '0', '-1']);
+        return first.result === 'a' && fromEnd.result === 'a' && remTwo.result === 2
+            && JSON.stringify(afterRem.result) === JSON.stringify(['b', 'c', 'a'])
+            && set.result === 'OK' && oob.status === 400 && oob.error === 'ERR index out of range'
+            && missing.status === 400 && missing.error === 'ERR no such key'
+            && JSON.stringify(trimmed.result) === JSON.stringify(['B']);
+    })),
+    // ── STREAMS ─────────────────────────────────────────────────────────────────────────────────
+    done('upstash.streams.add_and_read', 'streams', 'XADD with `*` mints a MONOTONIC <ms>-<seq> id off the injected clock (sequence incrementing within one millisecond), XLEN counts, and XRANGE answers [id, [field, value, …]] pairs with -/+ bounds and COUNT', 'api', 'common', () => withRoot(async (r) => {
+        const a = await r(['XADD', 'x:s', '*', 'f', '1']);
+        const b = await r(['XADD', 'x:s', '*', 'f', '2']);
+        const c = await r(['XADD', 'x:s', '*', 'f', '3'], { at: laterAt(1000) });
+        const len = await r(['XLEN', 'x:s']);
+        const all = await r(['XRANGE', 'x:s', '-', '+']);
+        const limited = await r(['XRANGE', 'x:s', '-', '+', 'COUNT', '1']);
+        const rows = all.result;
+        return a.result === `${AT_MS}-0` && b.result === `${AT_MS}-1` && c.result === `${AT_MS + 1000}-0`
+            && len.result === 3 && rows.length === 3
+            && JSON.stringify(rows[0]) === JSON.stringify([`${AT_MS}-0`, ['f', '1']])
+            && limited.result.length === 1;
+    })),
+    done('upstash.streams.explicit_id_and_reverse', 'streams', 'an EXPLICIT XADD id is accepted only if it is greater than the stream top (else the vendor\'s "equal or smaller" error), XREVRANGE takes its bounds reversed (`+ -`), and XDEL removes by id', 'api', 'niche', () => withRoot(async (r) => {
+        await r(['XADD', 'x:e', '100-1', 'a', '1']);
+        const ok = await r(['XADD', 'x:e', '100-2', 'a', '2']);
+        const tooSmall = await r(['XADD', 'x:e', '100-1', 'a', '3']);
+        const _rev = await r(['XREVRANGE', 'x:e', '+', '-']);
+        const del = await r(['XDEL', 'x:e', '100-1', 'never-existed-0']);
+        const left = await r(['XLEN', 'x:e']);
+        return ok.result === '100-2'
+            && tooSmall.status === 400 && tooSmall.error === 'ERR The ID specified in XADD is equal or smaller than the target stream top item'
+            && JSON.stringify(_rev.result[0][0]) === JSON.stringify('100-2')
+            && del.result === 1 && left.result === 1;
+    })),
+    done('upstash.streams.id_monotonic_across_delete', 'streams', 'DIRTY-STATE: a stream id that was used and then XDEL\'d stays REFUSED forever — Redis retains last_id past a delete, so ids never go backwards (§9 round 1 found the entries-only comparison re-accepting 5-5 after XDEL st 5-5, which would let two different entries share an id over the stream\'s lifetime)', 'api', 'niche', () => withRoot(async (r) => {
+        await r(['XADD', 'sid', '5-5', 'f', 'v1']);
+        await r(['XDEL', 'sid', '5-5']);
+        const empty = await r(['XLEN', 'sid']);
+        const reused = await r(['XADD', 'sid', '5-5', 'f', 'v2']);
+        const smaller = await r(['XADD', 'sid', '5-4', 'f', 'v3']);
+        const greater = await r(['XADD', 'sid', '5-6', 'f', 'v4']);
+        return empty.result === 0
+            && reused.status === 400 && reused.error === 'ERR The ID specified in XADD is equal or smaller than the target stream top item'
+            && smaller.status === 400 && greater.result === '5-6';
+    })),
+    done('upstash.streams.trim_refused', 'streams', 'XADD … MAXLEN/MINID is REFUSED BY NAME rather than accepted-and-ignored — accepting a trim option and not trimming would be a silent fake success that lets a caller\'s stream grow without bound', 'api', 'niche', () => withRoot(async (r) => {
+        const res = await r(['XADD', 'x:t', 'MAXLEN', '10', '*', 'f', 'v']);
+        return res.status === 400 && res.error.includes('MAXLEN trimming is not modeled by this twin');
+    })),
+    // ── SCRIPTING (the heart of the pack) ───────────────────────────────────────────────────────
+    done('upstash.scripting.eval', 'scripting', 'EVAL parses and EXECUTES caller-supplied Lua against the real command core: KEYS/ARGV are bound, `redis.call` re-enters the twin, and the returned Lua value is converted by Redis\'s own rules (number truncated to an integer, table to an array reply)', 'api', 'core', () => withRoot(async (r) => {
+        const echo = await r(['EVAL', 'return {KEYS[1], ARGV[1], 7.9}', '1', 'thekey', 'thearg']);
+        const write = await r(['EVAL', 'redis.call("SET", KEYS[1], ARGV[1]) return redis.call("GET", KEYS[1])', '1', 'ev:k', 'written-by-lua']);
+        const visible = await r(['GET', 'ev:k']);
+        return JSON.stringify(echo.result) === JSON.stringify(['thekey', 'thearg', 7])
+            && write.result === 'written-by-lua' && visible.result === 'written-by-lua';
+    })),
+    done('upstash.scripting.evalsha_noscript_contract', 'scripting', 'EVALSHA of an uncached sha -> the LITERAL "NOSCRIPT No matching script. Please use EVAL." — the exact string @upstash/ratelimit\'s safeEval greps for to decide to retry with EVAL; after an EVAL or SCRIPT LOAD the same sha resolves', 'api', 'core', () => withRoot(async (r) => {
+        const miss = await r(['EVALSHA', 'a'.repeat(40), '0']);
+        const load = await r(['SCRIPT', 'LOAD', 'return 42']);
+        const sha = load.result;
+        const hit = await r(['EVALSHA', sha, '0']);
+        const evalThenSha = await r(['EVAL', 'return 99', '0']);
+        const exists = await r(['SCRIPT', 'EXISTS', sha, 'b'.repeat(40)]);
+        return miss.status === 400 && miss.error === 'NOSCRIPT No matching script. Please use EVAL.'
+            && /^[0-9a-f]{40}$/.test(sha) && hit.result === 42 && evalThenSha.result === 99
+            && JSON.stringify(exists.result) === JSON.stringify([1, 0]);
+    })),
+    done('upstash.scripting.ratelimit_fixed_window', 'scripting', 'the REAL @upstash/ratelimit fixed-window script runs verbatim: the counter increments, PEXPIRE is armed EXACTLY ONCE on the first call (later increments must not reset the window), and the {count, limit} table comes back as an array reply', 'api', 'core', () => withRoot(async (r) => {
+        const call = (at) => r(['EVAL', RATELIMIT_FIXED_WINDOW, '2', 'rl:fw:u1', '', '3', '60000', '1'], at ? { at } : {});
+        const one = await call();
+        const two = await call();
+        const ttlAfterTwo = await r(['PTTL', 'rl:fw:u1']);
+        // The window must NOT be re-armed by the second increment: at +30s the deadline is 30s away.
+        const later = await r(['PTTL', 'rl:fw:u1'], { at: laterAt(30_000) });
+        const three = await call();
+        const four = await call();
+        return JSON.stringify(one.result) === JSON.stringify([1, 3])
+            && JSON.stringify(two.result) === JSON.stringify([2, 3])
+            && JSON.stringify(three.result) === JSON.stringify([3, 3])
+            && JSON.stringify(four.result) === JSON.stringify([4, 3]) // the SDK compares 4 > 3 and denies
+            && ttlAfterTwo.result === 60_000 && later.result === 30_000;
+    })),
+    done('upstash.scripting.ratelimit_sliding_window', 'scripting', 'the REAL @upstash/ratelimit sliding-window script runs verbatim and genuinely ENFORCES: it returns the remaining allowance while under the limit and the sentinel -1 once the weighted previous+current count reaches it — exercising Lua float math, `%`, math.floor and the nil→false conversion of a missing GET', 'api', 'core', () => withRoot(async (r) => {
+        const call = () => r(['EVAL', RATELIMIT_SLIDING_WINDOW, '3', 'rl:sw:cur', 'rl:sw:prev', '', '2', '30000', '60000', '1']);
+        const one = await call();
+        const two = await call();
+        const three = await call();
+        // A different identifier is untouched — the script keys per identifier and so must the twin.
+        const other = await r(['EVAL', RATELIMIT_SLIDING_WINDOW, '3', 'rl:sw:other', 'rl:sw:otherprev', '', '2', '30000', '60000', '1']);
+        return JSON.stringify(one.result) === JSON.stringify([1, 2])
+            && JSON.stringify(two.result) === JSON.stringify([0, 2])
+            && JSON.stringify(three.result) === JSON.stringify([-1, 2])
+            && JSON.stringify(other.result) === JSON.stringify([1, 2]);
+    })),
+    done('upstash.scripting.ratelimit_token_bucket', 'scripting', 'the REAL @upstash/ratelimit token-bucket script runs verbatim: it drains the bucket to the -1 sentinel and REFILLS as its `now` argument advances — exercising HMGET\'s per-field false conversion, HSET from Lua, math.min/math.ceil and multi-value table returns', 'api', 'common', () => withRoot(async (r) => {
+        const call = (now) => r(['EVAL', RATELIMIT_TOKEN_BUCKET, '2', 'rl:tb:u1', '', '2', '10000', '1', now, '1']);
+        const one = await call('0');
+        const two = await call('0');
+        const denied = await call('0');
+        const refilled = await call('20000');
+        const bucket = await r(['HGETALL', 'rl:tb:u1']);
+        return JSON.stringify(one.result) === JSON.stringify([1, 10000, 2])
+            && JSON.stringify(two.result) === JSON.stringify([0, 10000, 2])
+            && JSON.stringify(denied.result) === JSON.stringify([-1, 10000, 2])
+            && JSON.stringify(refilled.result) === JSON.stringify([1, 30000, 2])
+            && bucket.result.includes('refilledAt');
+    })),
+    done('upstash.scripting.compare_and_delete_lock', 'scripting', 'the real consumer\'s own compare-and-delete lock-release script (dub, lib/upstash/redis-lock.ts) runs verbatim: it deletes ONLY when the token matches and answers 0 otherwise — the Lua `==` between a GET result and an ARGV string', 'api', 'core', () => withRoot(async (r) => {
+        await r(['SET', 'lk:a', 'my-token']);
+        const wrong = await r(['EVAL', DUB_RELEASE_LOCK, '1', 'lk:a', 'other-token']);
+        const stillThere = await r(['GET', 'lk:a']);
+        const right = await r(['EVAL', DUB_RELEASE_LOCK, '1', 'lk:a', 'my-token']);
+        const gone = await r(['GET', 'lk:a']);
+        return wrong.result === 0 && stillThere.result === 'my-token' && right.result === 1 && gone.result === null;
+    })),
+    done('upstash.scripting.atomicity', 'scripting', 'a script is ONE indivisible unit: one that raises part-way leaves NOTHING behind, even for the writes it had already made — the property that makes a Lua rate limiter safe under concurrency', 'api', 'core', () => withRoot(async (r) => {
+        const failed = await r(['EVAL', 'redis.call("SET", KEYS[1], "half-written") redis.call("INCR", KEYS[1]) return 1', '1', 'atomic:k']);
+        const nothing = await r(['GET', 'atomic:k']);
+        const succeeded = await r(['EVAL', 'redis.call("SET", KEYS[1], "committed") return redis.call("GET", KEYS[1])', '1', 'atomic:k']);
+        const committed = await r(['GET', 'atomic:k']);
+        return failed.status === 400 && failed.error === 'ERR value is not an integer or out of range'
+            && nothing.result === null && succeeded.result === 'committed' && committed.result === 'committed';
+    })),
+    done('upstash.scripting.lua_semantics', 'scripting', 'the interpreter follows LUA, not JavaScript: `==` does NOT coerce across types ("3" ~= 3), only nil/false are falsy (0 and "" are TRUE), a nil bulk reply becomes `false`, `%` takes the sign of the divisor, and `#t` is the array length', 'api', 'common', () => withRoot(async (r) => {
+        const strictEq = await r(['EVAL', 'if "3" == 3 then return "coerced" else return "strict" end', '0']);
+        const zeroTruthy = await r(['EVAL', 'if 0 then return "truthy" else return "falsy" end', '0']);
+        const nilIsFalse = await r(['EVAL', 'local v = redis.call("GET", KEYS[1]) if v == false then return "false" else return "other" end', '1', 'nope']);
+        const modulo = await r(['EVAL', 'return tostring(-1 % 3)', '0']);
+        const length = await r(['EVAL', 'return #{10,20,30}', '0']);
+        return strictEq.result === 'strict' && zeroTruthy.result === 'truthy' && nilIsFalse.result === 'false'
+            && modulo.result === '2' && length.result === 3;
+    })),
+    done('upstash.scripting.unsupported_fails_loudly', 'scripting', 'a script using something outside the documented Lua SUBSET (cjson, goto, metatables, Lua string PATTERNS) is REFUSED by name at 400 — never quietly mis-evaluated and never a fake success', 'api', 'core', () => withRoot(async (r) => {
+        const cjson = await r(['EVAL', 'return cjson.encode({1,2})', '0']);
+        const goTo = await r(['EVAL', 'local x = 1 goto done', '0']);
+        const meta = await r(['EVAL', 'return setmetatable({}, {})', '0']);
+        const pattern = await r(['EVAL', 'return string.gsub("abc", "%a", "z")', '0']);
+        const all = [cjson, goTo, meta, pattern];
+        return all.every((x) => x.status === 400 && typeof x.error === 'string')
+            && cjson.error.includes("unsupported Lua library 'cjson'")
+            && goTo.error.includes("unsupported Lua construct 'goto'")
+            && meta.error.includes("unsupported Lua library 'setmetatable'")
+            && pattern.error.includes('Lua PATTERN');
+    })),
+    done('upstash.scripting.eval_ro_rejects_writes', 'scripting', 'EVAL_RO/EVALSHA_RO refuse a write command from inside the script, naming it — while the same script under plain EVAL succeeds', 'api', 'niche', () => withRoot(async (r) => {
+        const script = 'redis.call("SET", KEYS[1], "x") return 1';
+        const ro = await r(['EVAL_RO', script, '1', 'ro:k']);
+        const notWritten = await r(['GET', 'ro:k']);
+        const rw = await r(['EVAL', script, '1', 'ro:k']);
+        return ro.status === 400 && ro.error.includes('Write commands are not allowed from read-only scripts.') && notWritten.result === null && rw.result === 1;
+    })),
+    done('upstash.scripting.script_flush', 'scripting', 'SCRIPT FLUSH empties the cache so a previously-working EVALSHA goes back to answering NOSCRIPT', 'api', 'niche', () => withRoot(async (r) => {
+        const load = await r(['SCRIPT', 'LOAD', 'return 5']);
+        const sha = load.result;
+        const before = await r(['EVALSHA', sha, '0']);
+        await r(['SCRIPT', 'FLUSH']);
+        const after = await r(['EVALSHA', sha, '0']);
+        return before.result === 5 && after.status === 400 && after.error === 'NOSCRIPT No matching script. Please use EVAL.';
+    })),
+    // ── ERRORS ──────────────────────────────────────────────────────────────────────────────────
+    done('upstash.errors.unavailable_command', 'errors', 'an unknown command answers UPSTASH\'s message, not stock Redis\'s: "ERR Command is not available: \'FOO\'. See https://upstash.com/docs/redis/overall/rediscompatibility for details", with the name UPPER-CASED whichever form it arrived in', 'api', 'core', () => withRoot(async (r) => {
+        const body = await r(['notacommand', 'x']);
+        const path = await r.raw({ method: 'GET', path: '/notacommand/x' });
+        const expected = "ERR Command is not available: 'NOTACOMMAND'. See https://upstash.com/docs/redis/overall/rediscompatibility for details";
+        return body.status === 400 && body.error === expected
+            && path.status === 400 && path.body.error === expected;
+    })),
+    done('upstash.errors.rest_restricted_commands', 'errors', 'connection/transaction/pub-sub CONTROL commands that make no sense over stateless HTTP (AUTH, MULTI, WATCH, SUBSCRIBE, CLIENT) answer the vendor\'s "is not allowed in REST or it has a special context path" refusal, with the command name upper-cased in double quotes', 'api', 'common', () => withRoot(async (r) => {
+        const results = await Promise.all([['AUTH', 'x'], ['MULTI'], ['WATCH', 'k'], ['SUBSCRIBE', 'c'], ['CLIENT', 'LIST']].map((c) => r(c)));
+        return results.every((x, i) => x.status === 400 && x.error === `ERR Command "${['AUTH', 'MULTI', 'WATCH', 'SUBSCRIBE', 'CLIENT'][i]}" is not allowed in REST or it has a special context path`);
+    })),
+    done('upstash.errors.select_only_db_zero', 'errors', 'SELECT 0 succeeds but any other database answers "ERR Only 0th database is supported! Selected DB: N" — Upstash serves exactly one logical database and says so by number', 'api', 'niche', () => withRoot(async (r) => {
+        const zero = await r(['SELECT', '0']);
+        const one = await r(['SELECT', '1']);
+        return zero.result === 'OK' && one.status === 400 && one.error === 'ERR Only 0th database is supported! Selected DB: 1';
+    })),
+    done('upstash.errors.arity_and_syntax', 'errors', 'a wrong argument count answers "ERR wrong number of arguments for \'<cmd>\' command" and an unrecognised option token answers "ERR syntax error"', 'api', 'core', () => withRoot(async (r) => {
+        const tooFew = await r(['GET']);
+        const tooMany = await r(['GET', 'a', 'b']);
+        const syntax = await r(['SET', 'k', 'v', 'BOGUS']);
+        return tooFew.status === 400 && tooFew.error === "ERR wrong number of arguments for 'get' command"
+            && tooMany.status === 400 && tooMany.error === "ERR wrong number of arguments for 'get' command"
+            && syntax.status === 400 && syntax.error === 'ERR syntax error';
+    })),
+    // ── SAFETY ──────────────────────────────────────────────────────────────────────────────────
+    done('upstash.safety.read_only_mode', 'safety', 'a twin started read-only serves every READ but refuses every WRITE with 405 — including a write attempted from inside an EVAL script, which must not be a back door around the flag', 'api', 'core', () => withRoot(async (r) => {
+        await r(['SET', 'ro:seed', 'value']);
+        const read = await r.raw({ body: JSON.stringify(['GET', 'ro:seed']), readOnly: true });
+        const write = await r.raw({ body: JSON.stringify(['SET', 'ro:seed', 'changed']), readOnly: true });
+        const viaScript = await r.raw({ body: JSON.stringify(['EVAL', 'return redis.call("SET", KEYS[1], "sneaky")', '1', 'ro:seed']), readOnly: true });
+        const unchanged = await r(['GET', 'ro:seed']);
+        return read.status === 200 && read.body.result === 'value'
+            && write.status === 405 && viaScript.status === 405 && unchanged.result === 'value';
+    })),
+    done('upstash.safety.read_only_serves_every_read', 'safety', 'a read-only twin serves EVERY read, including the ones that look like writes: EVAL_RO, EVALSHA_RO and SCRIPT EXISTS all answer 200 — while SCRIPT LOAD/FLUSH, plain EVAL and a write attempted from inside EVAL_RO are all still refused (§9 round 1 found the first three answering 405, because script CACHING is a write and SCRIPT was classified write-wholesale)', 'api', 'core', () => withRoot(async (r) => {
+        await r(['SET', 'ro:k', 'v']);
+        const load = await r(['SCRIPT', 'LOAD', 'return redis.call("GET", KEYS[1])']);
+        const sha = load.result;
+        const ro = (body) => r.raw({ body: JSON.stringify(body), readOnly: true });
+        const [evalRo, shaRo, exists] = await Promise.all([
+            ro(['EVAL_RO', 'return redis.call("GET", KEYS[1])', '1', 'ro:k']),
+            ro(['EVALSHA_RO', sha, '1', 'ro:k']),
+            ro(['SCRIPT', 'EXISTS', sha]),
+        ]);
+        const reads = [evalRo, shaRo, exists].every((x) => x.status === 200);
+        const readValues = evalRo.body.result === 'v' && shaRo.body.result === 'v';
+        // …and every WRITE disguise is still refused.
+        const writes = await Promise.all([
+            ro(['SET', 'ro:k', 'changed']),
+            ro(['EVAL', 'return 1', '0']),
+            ro(['SCRIPT', 'LOAD', 'return 2']),
+            ro(['SCRIPT', 'FLUSH']),
+            ro(['EVAL_RO', 'return redis.call("SET", KEYS[1], "sneaky")', '1', 'ro:k']),
+        ]);
+        const unchanged = await r(['GET', 'ro:k']);
+        return reads && readValues && writes.every((x) => x.status === 405 || x.status === 400) && unchanged.result === 'v';
+    })),
+    // ── CONNECTOR ───────────────────────────────────────────────────────────────────────────────
+    done('upstash.connector.pull', 'connector', 'the connector pulls NAMED keys of every type from an INJECTED client and folds them into the twin, where they read back exactly as locally-written ones do (a real SDK client is structurally assignable; the pack imports no SDK and holds no token)', 'connector', 'core', () => withRoot(async (r, root) => {
+        const { client, calls } = fakeRedisClient({
+            'pulled:str': { type: 'string', value: 'from-vendor', ttl: 120 },
+            'pulled:hash': { type: 'hash', value: { a: '1', b: '2' } },
+            'pulled:set': { type: 'set', value: ['x', 'y'] },
+        });
+        const result = await syncUpstashRedisFromReal(client, {
+            root, occurredAt: AT,
+            keys: [{ key: 'pulled:str' }, { key: 'pulled:hash' }, { key: 'pulled:set' }, { key: 'pulled:missing' }],
+        });
+        const str = await r(['GET', 'pulled:str']);
+        const ttl = await r(['TTL', 'pulled:str']);
+        const hash = await r(['HGETALL', 'pulled:hash']);
+        const set = await r(['SISMEMBER', 'pulled:set', 'x']);
+        const missing = await r(['EXISTS', 'pulled:missing']);
+        return result.observed === 3 && result.deltasAppended > 0
+            && str.result === 'from-vendor' && ttl.result === 120
+            && JSON.stringify(hash.result) === JSON.stringify(['a', '1', 'b', '2'])
+            && set.result === 1 && missing.result === 0 // a key the vendor lacks is SKIPPED, never invented
+            && calls.includes('type:pulled:str');
+    })),
+    done('upstash.connector.refuses_unencodable_type', 'connector', 'a pulled key whose type the connector cannot faithfully encode (a STREAM) is REFUSED BY NAME, naming the filed todo — never coerced into a JSON string and stored under the real type, which §9 round 2 found producing a key that looked real and then threw a raw TypeError out of the request handler on every read', 'connector', 'common', () => {
+        const { client } = fakeRedisClient({ 'st:1': { type: 'stream', value: [['1-0', { f: 'v' }]] } });
+        return verifyBoundary('upstash.connector.refuses_unencodable_type', async () => {
+            let refused = '';
+            try {
+                await pullUpstashRedisKeys(client, [{ key: 'st:1' }]);
+            }
+            catch (e) {
+                refused = e.message;
+            }
+            return refused.includes("cannot pull key of type 'stream'") && refused.includes('upstash.connector.pull_streams');
+        });
+    }),
+    done('upstash.connector.pull_idempotent', 'connector', 'a re-pull of IDENTICAL vendor state appends ZERO new deltas (shadow-diff dedup), so a scheduled sync does not grow the log without bound — while a CHANGED value does append', 'connector', 'core', () => withRoot(async (r, root) => {
+        const first = fakeRedisClient({ 'idem:k': { type: 'string', value: 'v1' } });
+        const a = await syncUpstashRedisFromReal(first.client, { root, occurredAt: AT, keys: [{ key: 'idem:k' }] });
+        const b = await syncUpstashRedisFromReal(first.client, { root, occurredAt: AT, keys: [{ key: 'idem:k' }] });
+        const changed = fakeRedisClient({ 'idem:k': { type: 'string', value: 'v2' } });
+        const c = await syncUpstashRedisFromReal(changed.client, { root, occurredAt: AT, keys: [{ key: 'idem:k' }] });
+        const now = await r(['GET', 'idem:k']);
+        return a.deltasAppended > 0 && b.deltasAppended === 0 && c.deltasAppended > 0 && now.result === 'v2';
+    })),
+    done('upstash.connector.scan_is_bounded', 'connector', 'the SCAN-based discovery path is HARD-BOUNDED by an explicit limit rather than looping until the vendor says stop — an unbounded walk of a production keyspace is exactly the burst the rate budget exists to prevent', 'connector', 'common', () => {
+        const { client, calls } = fakeRedisClient(Object.fromEntries(Array.from({ length: 40 }, (_, i) => [`walk:${i}`, { type: 'string', value: String(i) }])));
+        return verifyBoundary('upstash.connector.scan_is_bounded', async () => {
+            const found = await pullUpstashRedisScan(client, { limit: 5, pageSize: 50 });
+            return found.length === 5 && calls.some((c) => c.startsWith('scan:'));
+        });
+    }),
+    done('upstash.connector.rate_budget_fail_closed', 'connector', 'the client-side rate budget REFUSES a call past the ceiling BEFORE it reaches the vendor: after N calls the injected fake recorded exactly N, and the next attempt throws with the count UNCHANGED (the count is the proof — "it threw" is not)', 'connector', 'core', async () => {
+        const { mkdtempSync: mk, rmSync: rm } = await import('node:fs');
+        const ledgerRoot = mk(join(tmpdir(), 'upstash-budget-'));
+        try {
+            return await verifyBoundary('upstash.connector.rate_budget_fail_closed', async () => {
+                const { guardUpstashRedisClient, UPSTASH_BUDGET_CEILING, UPSTASH_CALL_WEIGHTS } = await import("./upstash-budget.js");
+                let vendorCalls = 0;
+                const raw = { get: async () => { vendorCalls++; return 'v'; } };
+                // A frozen injected clock, so the rolling window cannot slide underneath the assertion, and
+                // an isolated ledger path, so this never spends against the operator's real ~/.volter file.
+                const guarded = guardUpstashRedisClient(raw, { budgetOptions: { root: ledgerRoot, now: () => 1_800_000_000_000 } });
+                const allowed = Math.floor(UPSTASH_BUDGET_CEILING / UPSTASH_CALL_WEIGHTS.other);
+                for (let i = 0; i < allowed; i++)
+                    await guarded.get('k');
+                if (vendorCalls !== allowed)
+                    return false;
+                let refused = false;
+                try {
+                    await guarded.get('k');
+                }
+                catch {
+                    refused = true;
+                }
+                // THE assertion: the count did not move, so nothing reached the vendor.
+                return refused && vendorCalls === allowed;
+            });
+        }
+        finally {
+            rm(ledgerRoot, { recursive: true, force: true });
+        }
+    }),
+    // ── CONFORMANCE ─────────────────────────────────────────────────────────────────────────────
+    done('upstash.conformance.endpoint_probe', 'conformance', 'the conformance check ISSUES REAL REQUESTS against every endpoint its inventory claims (not a constant-vs-constant snapshot comparison) and requires each to answer as declared — so a dead handler fails it', 'api', 'common', async () => {
+        const report = await checkUpstashRedisConformance();
+        return report.ok && report.violations.length === 0 && report.endpointsChecked >= 6 && report.resourceTypesChecked === 2;
+    }),
+    // ══ TODOS — real vendor surface this twin has NOT reached ═══════════════════════════════════
+    // Enumerated top-down from Redis's own command groups as Upstash supports them, so a whole
+    // missing family shows in the denominator rather than being quietly left out.
+    // RedisJSON — a first-class Upstash feature with its own command family.
+    todo('upstash.json.set_get', 'json', 'JSON.SET / JSON.GET — store and read a JSON document at a path (RedisJSON, supported by Upstash)', 'api', 'common'),
+    todo('upstash.json.mutate', 'json', 'JSON.NUMINCRBY / JSON.STRAPPEND / JSON.DEL / JSON.TOGGLE — in-place mutation at a JSONPath', 'api', 'common'),
+    todo('upstash.json.arrays', 'json', 'JSON.ARRAPPEND / JSON.ARRINSERT / JSON.ARRPOP / JSON.ARRTRIM / JSON.ARRLEN — array operations inside a document', 'api', 'niche'),
+    todo('upstash.json.type_and_objkeys', 'json', 'JSON.TYPE / JSON.OBJKEYS / JSON.OBJLEN / JSON.RESP — document introspection', 'api', 'niche'),
+    // Bitmaps.
+    todo('upstash.bitmaps.setbit_getbit', 'bitmaps', 'SETBIT / GETBIT — single-bit addressing inside a string value', 'api', 'common'),
+    todo('upstash.bitmaps.bitcount_bitpos', 'bitmaps', 'BITCOUNT / BITPOS with BYTE|BIT ranges — population counts over a bitmap', 'api', 'common'),
+    todo('upstash.bitmaps.bitop_bitfield', 'bitmaps', 'BITOP (AND/OR/XOR/NOT) and BITFIELD\'s typed sub-command language', 'api', 'niche'),
+    // HyperLogLog.
+    todo('upstash.hyperloglog.pfadd_pfcount', 'hyperloglog', 'PFADD / PFCOUNT — probabilistic cardinality estimation with the real HLL error bound', 'api', 'common'),
+    todo('upstash.hyperloglog.pfmerge', 'hyperloglog', 'PFMERGE — union of HyperLogLog registers into a destination key', 'api', 'niche'),
+    // Geo.
+    todo('upstash.geo.add_pos_dist', 'geo', 'GEOADD / GEOPOS / GEODIST / GEOHASH — geospatial members over a sorted set', 'api', 'niche'),
+    todo('upstash.geo.search', 'geo', 'GEOSEARCH / GEOSEARCHSTORE (and the deprecated GEORADIUS family) — radius and box queries', 'api', 'niche'),
+    // Pub/Sub + the two SSE endpoints, which are a genuinely different transport.
+    todo('upstash.pubsub.publish', 'pubsub', 'PUBLISH — deliver a message to a channel and answer the subscriber count (the twin currently has no channel registry)', 'api', 'common'),
+    todo('upstash.pubsub.subscribe_sse', 'pubsub', 'POST /subscribe/{channel} with Accept: text/event-stream — the documented SSE subscription endpoint (`data: message,chat,hello` frames)', 'api', 'common'),
+    todo('upstash.pubsub.monitor_sse', 'pubsub', 'POST /monitor with Accept: text/event-stream — the documented command-firehose SSE endpoint', 'api', 'niche'),
+    todo('upstash.pubsub.pattern_channels', 'pubsub', 'PSUBSCRIBE pattern channels and the PUBSUB CHANNELS/NUMSUB/NUMPAT introspection sub-commands', 'api', 'niche'),
+    // Streams beyond the five commands the consumer uses.
+    todo('upstash.streams.consumer_groups', 'streams', 'XGROUP CREATE/DESTROY/SETID, XREADGROUP, XACK, XPENDING — the consumer-group half of streams', 'api', 'common'),
+    todo('upstash.streams.claim', 'streams', 'XCLAIM / XAUTOCLAIM — reassigning a pending entry from a dead consumer', 'api', 'niche'),
+    todo('upstash.streams.xread', 'streams', 'XREAD (non-blocking) across multiple streams with per-stream last-id cursors', 'api', 'common'),
+    todo('upstash.streams.trim', 'streams', 'XTRIM, and XADD\'s MAXLEN/MINID trimming with ~ and LIMIT (currently REFUSED by name rather than silently ignored — see upstash.streams.trim_refused)', 'api', 'common'),
+    todo('upstash.streams.xinfo', 'streams', 'XINFO STREAM/GROUPS/CONSUMERS — stream introspection', 'api', 'niche'),
+    // Search (RediSearch) — a documented Upstash family this twin does not model at all.
+    todo('upstash.search.index_and_query', 'search', 'FT.CREATE / FT.SEARCH / FT.AGGREGATE / FT.INFO / FT.DROPINDEX / FT.ALTER / FT.EXPLAIN — the RediSearch index and query family Upstash documents', 'api', 'common'),
+    // Set algebra.
+    todo('upstash.sets.algebra', 'sets', 'SINTER / SUNION / SDIFF and their *STORE variants — set algebra across keys', 'api', 'common'),
+    todo('upstash.sets.move_and_random', 'sets', 'SMOVE, and SPOP/SRANDMEMBER with genuine randomness (this twin takes deterministically from the front — see upstash.sets.spop_deterministic)', 'api', 'niche'),
+    todo('upstash.sorted_sets.blocking_pop', 'sorted_sets', 'BZPOPMIN / BZPOPMAX / BZMPOP — the blocking sorted-set pops', 'api', 'niche'),
+    todo('upstash.hashes.field_ops', 'hashes', 'HSTRLEN — the per-field length accessor', 'api', 'niche'),
+    todo('upstash.keyspace.expiretime', 'keyspace', 'EXPIRETIME / PEXPIRETIME — reading a key\'s ABSOLUTE expiry deadline rather than its remaining TTL', 'api', 'niche'),
+    todo('upstash.keyspace.conditional_delete', 'keyspace', 'DELEX — conditional delete (delete only when the key still holds an expected state)', 'api', 'niche'),
+    todo('upstash.server.replication_wait', 'server', 'WAIT / WAITAOF — blocking until N replicas (or the AOF) have acknowledged a write', 'api', 'niche'),
+    todo('upstash.server.digest', 'server', 'DIGEST — the dataset digest Upstash exposes for comparing databases', 'api', 'niche'),
+    todo('upstash.auth.acl', 'auth', 'the ACL family (ACL WHOAMI / LIST / GETUSER / SETUSER …) Upstash documents under Server', 'api', 'niche'),
+    todo('upstash.scripting.script_kill', 'scripting', 'SCRIPT KILL — terminating a long-running script (documented Upstash surface; this twin runs scripts to completion under a step ceiling instead)', 'api', 'niche'),
+    todo('upstash.sets.sscan', 'sets', 'SSCAN — cursor iteration over a large set', 'api', 'niche'),
+    todo('upstash.sets.spop_deterministic', 'sets', 'SPOP/SRANDMEMBER currently return the FRONT of insertion order rather than a random member, so a verify can assert them; real random selection is the gap', 'api', 'niche'),
+    // Sorted-set surface beyond what is built.
+    todo('upstash.sorted_sets.range_bylex', 'sorted_sets', 'ZRANGEBYLEX / ZREVRANGEBYLEX / ZREMRANGEBYLEX and ZRANGE … BYLEX — lexicographic ranges over equal-score members (currently REFUSED by name)', 'api', 'common'),
+    todo('upstash.sorted_sets.store_and_algebra', 'sorted_sets', 'ZUNIONSTORE / ZINTERSTORE / ZDIFFSTORE / ZRANGESTORE with WEIGHTS and AGGREGATE', 'api', 'common'),
+    todo('upstash.sorted_sets.pop_and_random', 'sorted_sets', 'ZPOPMIN / ZPOPMAX / ZMPOP / ZRANDMEMBER — pop-by-rank and random sampling', 'api', 'niche'),
+    todo('upstash.sorted_sets.mscore_and_scan', 'sorted_sets', 'ZMSCORE (batch score lookup) and ZSCAN (cursor iteration)', 'api', 'niche'),
+    // List surface beyond what is built.
+    todo('upstash.lists.move', 'lists', 'LMOVE / RPOPLPUSH / LMPOP — moving elements between lists atomically', 'api', 'common'),
+    todo('upstash.lists.insert_and_pos', 'lists', 'LINSERT BEFORE|AFTER and LPOS with RANK/COUNT/MAXLEN', 'api', 'niche'),
+    todo('upstash.lists.blocking', 'lists', 'BLPOP / BRPOP / BLMOVE — blocking pops (the REST docs call these unsupported, but a live probe found BLPOP answering on redis 8.2, so the vendor\'s true position needs re-grounding before modeling)', 'api', 'niche'),
+    // Hash surface beyond what is built.
+    todo('upstash.hashes.hscan', 'hashes', 'HSCAN — cursor iteration over a large hash, with MATCH/COUNT/NOVALUES', 'api', 'common'),
+    todo('upstash.hashes.field_ttl', 'hashes', 'HEXPIRE / HPEXPIRE / HTTL / HPERSIST — per-FIELD expiry (Redis 7.4), distinct from the key-level TTL this twin models', 'api', 'niche'),
+    todo('upstash.hashes.randfield', 'hashes', 'HRANDFIELD with COUNT and WITHVALUES', 'api', 'niche'),
+    // String surface beyond what is built.
+    todo('upstash.strings.ranges', 'strings', 'GETRANGE / SETRANGE / SUBSTR — substring read and in-place overwrite at an offset', 'api', 'niche'),
+    todo('upstash.counters.int64_range', 'counters', 'full 64-bit integer range: Redis counters are int64, but this twin\'s arithmetic is JavaScript doubles, so it refuses beyond 2^53-1 — with the vendor\'s "value is not an integer or out of range" for an out-of-range ARGUMENT, and its "increment or decrement would overflow" when an in-range increment would cross the ceiling (§9 rounds 1 and 2). Loud rather than lossy — a silently wrong big integer would be far worse — but the ceiling is the twin\'s, not Upstash\'s', 'api', 'niche'),
+    todo('upstash.strings.lcs', 'strings', 'LCS with LEN/IDX/MINMATCHLEN — longest common subsequence between two string keys', 'api', 'niche'),
+    // Generic keyspace surface beyond what is built.
+    todo('upstash.keyspace.expire_conditions', 'keyspace', 'EXPIRE/PEXPIRE/EXPIREAT with the NX|XX|GT|LT condition flags (currently REFUSED by name rather than silently ignored)', 'api', 'common'),
+    todo('upstash.keyspace.copy', 'keyspace', 'COPY source destination [REPLACE] — duplicating a key of any type', 'api', 'niche'),
+    todo('upstash.keyspace.dump_restore', 'keyspace', 'DUMP / RESTORE — the serialized-value format, which is a real binary encoding this twin does not produce', 'api', 'niche'),
+    todo('upstash.keyspace.object_introspection', 'keyspace', 'OBJECT ENCODING / REFCOUNT / IDLETIME / FREQ — internal representation introspection', 'api', 'niche'),
+    todo('upstash.keyspace.scan_cursor_shape', 'keyspace', 'the cursor\'s exact SHAPE: Redis returns a reverse-binary index into its hash table (a large opaque number that reflects real rehashing). This twin returns a stable key-derived position, which DOES honour the present-throughout guarantee (proven by upstash.keyspace.scan_survives_mutation) and is additionally reproducible — but the numbers themselves are not the vendor\'s, so a caller that inspected or persisted a cursor across implementations would see different values', 'api', 'niche'),
+    todo('upstash.keyspace.randomkey_deterministic', 'keyspace', 'RANDOMKEY currently answers the FIRST key in sorted order so a verify can assert it; genuine random selection is the gap', 'api', 'niche'),
+    // Server / connection surface.
+    todo('upstash.server.info', 'server', 'INFO — the whole report as one \\r\\n-separated bulk string, including Upstash-specific fields (upstash_version, total_keys, max_ops_per_sec)', 'api', 'common'),
+    todo('upstash.server.config_and_command', 'server', 'CONFIG GET/SET and COMMAND / COMMAND DOCS / COMMAND COUNT introspection', 'api', 'niche'),
+    todo('upstash.server.time_and_lastsave', 'server', 'TIME / LASTSAVE / BGSAVE — server-clock and persistence introspection commands', 'api', 'niche'),
+    todo('upstash.server.dbsize_per_type_stats', 'server', 'MEMORY USAGE and the per-type keyspace statistics INFO reports', 'api', 'niche'),
+    // Scripting surface beyond what is built.
+    todo('upstash.scripting.functions', 'scripting', 'FUNCTION LOAD/DUMP/FLUSH/LIST and FCALL — Redis 7 Functions, a separate mechanism from EVAL', 'api', 'niche'),
+    todo('upstash.scripting.lua_libraries', 'scripting', 'the cjson / cmsgpack / bit / struct Lua libraries real Redis exposes to scripts (currently REFUSED by name — see upstash.scripting.unsupported_fails_loudly)', 'api', 'common'),
+    todo('upstash.scripting.lua_patterns', 'scripting', 'Lua PATTERN matching in string.find/gsub/match/gmatch — a distinct language from JS regex, currently refused rather than mistranslated', 'api', 'niche'),
+    todo('upstash.scripting.metatables_and_coroutines', 'scripting', 'setmetatable/getmetatable, pcall/xpcall and coroutines inside a script', 'api', 'niche'),
+    todo('upstash.scripting.multiregion_ratelimit_scripts', 'scripting', '@upstash/ratelimit\'s MULTI-REGION scripts (hash-based fixed/sliding window with per-request-id fields and generic-for loops) — the single-region three are proven; the multi-region pair is not yet exercised', 'api', 'niche'),
+    // Protocol surface beyond what is built.
+    todo('upstash.protocol.resp2_format', 'protocol', 'Upstash-Response-Format: resp2 — raw RESP2 bytes as application/octet-stream instead of JSON (and its documented rejection when combined with /multi-exec)', 'api', 'niche'),
+    todo('upstash.protocol.read_your_writes_semantics', 'protocol', 'REAL read-your-writes: the sync token as a replication watermark a read region actually waits on. This twin echoes/advances a counter permissively because it has no replicas', 'api', 'common'),
+    todo('upstash.protocol.telemetry_headers', 'protocol', 'recording the Upstash-Telemetry-Sdk/-Platform/-Runtime headers so a world can assert which client version spoke to it (currently accepted and ignored, as the real server does)', 'api', 'niche'),
+    todo('upstash.protocol.auto_pipeline_exclusions', 'protocol', 'asserting the SDK\'s EXCLUDE_COMMANDS set arrives at POST / rather than /pipeline — both endpoints work, but the routing split itself is not pinned by a verify', 'api', 'niche'),
+    // Quotas and auth surface.
+    todo('upstash.quotas.daily_request_limit', 'quotas', 'ERR max daily request limit exceeded — the documented daily-quota refusal (Upstash publishes the error string but NO figure, and the grounding pass could not trigger it, so its HTTP status is unverified)', 'api', 'niche'),
+    todo('upstash.quotas.monthly_request_limit', 'quotas', 'ERR max requests limit exceeded — the monthly-quota refusal (500K commands/month on the free tier; status unverified for the same reason)', 'api', 'niche'),
+    todo('upstash.quotas.record_and_key_size', 'quotas', 'ERR max key size exceeded / ERR max single record size exceeded — the per-key and per-record size ceilings (100 MB records on Free/PAYG)', 'api', 'niche'),
+    todo('upstash.quotas.concurrent_connections', 'quotas', 'ERR max concurrent connections exceeded — the per-plan connection ceiling', 'api', 'niche'),
+    todo('upstash.auth.read_only_token', 'auth', 'Upstash\'s READ-ONLY token: reads allowed, writes and SCAN/KEYS refused. The rejection status and error string could not be observed (the grounding database exposed only one token), so modeling them would be a guess', 'api', 'common'),
+    // Connector surface.
+    todo('upstash.connector.push', 'connector', 'push locally-written keys back to a real Upstash database — deliberately not built: a blind write-back to a production cache is destructive, and the safe design (an explicit key allowlist plus a dry-run diff) has not been settled', 'connector', 'common'),
+    todo('upstash.connector.pull_by_scan', 'connector', 'a full connector sync driven by SCAN discovery rather than caller-named keys (pullUpstashRedisScan finds the handles today, but wiring it into syncUpstashRedisFromReal would make an unbounded production walk one call away)', 'connector', 'common'),
+    todo('upstash.connector.pull_streams', 'connector', 'pulling STREAM keys — the connector maps string/hash/set/list/zset today and skips streams, since XRANGE over a large stream is unbounded', 'connector', 'niche'),
+    todo('upstash.connector.fixtures', 'connector', 'seed a small library of realistic keyspace fixtures (a session cache, a rate-limit window, a leaderboard) for eval worlds', 'connector', 'niche'),
+];
+export const UPSTASH_AREAS = [
+    'protocol', 'auth', 'strings', 'counters', 'keyspace', 'hashes', 'sets', 'sorted_sets', 'lists',
+    'streams', 'scripting', 'json', 'search', 'bitmaps', 'hyperloglog', 'geo', 'pubsub', 'server', 'quotas',
+    'errors', 'safety', 'connector', 'conformance',
+];
+export async function upstashCapabilities() {
+    return checkCapabilities('upstash', UPSTASH_CAPABILITIES);
+}