@volter/twin-upstash 0.1.0

package/dist/src/upstash-store.js

@@ -0,0 +1,1663 @@
+// THE REDIS COMMAND CORE — a real, stateful Redis data model folded out of the @volter/world-core kernel
+// action log. This is the file that makes this pack a twin rather than a stub: `GET` returns what
+// `SET` actually wrote, `INCR` on a non-numeric string raises the vendor's own
+// "ERR value is not an integer or out of range", `LPUSH` against a string raises `WRONGTYPE`, and
+// a key with a TTL stops existing once the request clock passes its deadline.
+//
+// GROUNDED (2026-08-19) against three independent sources, all cross-checked — see spec-sources.json:
+//   (a) upstash.com/docs/redis/features/restapi (the REST protocol page);
+//   (b) the ACTUALLY-INSTALLED `@upstash/redis@1.35.7` package's own compiled source
+//       (node_modules/@upstash/redis/chunk-TBGBPMGD.mjs — its HttpClient, Command, Pipeline and
+//       per-command argument builders), read read-only;
+//   (c) LIVE PROBES of a real ephemeral Upstash database (`upstash.com/start-redis`), which is where
+//       every literal error string, HTTP status and base64 rule below comes from. Where the docs and
+//       the live server disagreed, the live server won (e.g. the docs' "value is not an int" is
+//       really "value is not an integer").
+//
+// ── STATE LIVES IN THE KERNEL, NOT IN A MAP ───────────────────────────────────────────────────
+// Every Redis key is ONE kernel subject (`type:'key'`, id `key:<name>`), written through
+// `applyTwinWrite` and read back through `projectResources`. There is no side-store: kill the
+// process, point a new one at the same root, and `GET` still answers.
+//
+// ── THE CLOCK IS INJECTED, NEVER READ FROM THE WALL ───────────────────────────────────────────
+// TTLs need a clock, and this repo forbids `Date.now()` inside twin behaviour (a verify must be
+// bit-reproducible). So expiry is computed against the CURRENT REQUEST'S `occurredAt` — the same
+// timestamp the kernel stamps the action with. A verify pins `occurredAt` and gets deterministic
+// TTL arithmetic; to test EXPIRY it issues the next request with a LATER pinned `occurredAt`, which
+// is a clock advance expressed as data. `createUpstashRedisTwinServer({ now })` exposes the same
+// seam over HTTP for a test that drives the real SDK.
+//
+// Expiration is LAZY, exactly like Redis: an expired key is not erased by a sweep, it simply stops
+// being visible to every read and is overwritten by the next write. `DBSIZE`, `KEYS`, `SCAN`,
+// `EXISTS`, `TTL` and `TYPE` all agree with `GET` about which keys are alive at a given instant.
+//
+// ── ONE REQUEST = ONE SYNCHRONOUS RUN OVER A KEYSPACE SNAPSHOT ────────────────────────────────
+// `execRedisRun` folds the action log ONCE into a `KeySpace` (a plain synchronous map), executes
+// every command in the request against it, then flushes the keys that were actually touched back
+// into the kernel. Two things fall out of that shape and both matter:
+//   • `EVAL` becomes possible at all. `redis.call` is SYNCHRONOUS in Lua and cannot await a kernel
+//     append; because the command core is synchronous over the snapshot, a script's calls run
+//     inline and its writes are visible to its own later reads — which @upstash/ratelimit's scripts
+//     depend on (`if r == tonumber(incrementBy)` branches on the result of its own INCRBY).
+//   • A script is ATOMIC. Its writes only reach the log at flush time, so a script that raises
+//     part-way leaves nothing behind.
+// The DISCLOSED cost: within one request, N writes to the same key collapse into ONE kernel action
+// carrying the final value, so the action log records the request's net effect rather than every
+// intermediate. State is identical either way; only the granularity of the audit trail differs.
+//
+// ── COMMANDS BY REDIS'S TABLE ─────────────────────────────────────────────────────────────────
+// Every command is named by its id in Redis's command table (spec/commands, derived into
+// generated/surface.gen.json): a container's subcommand by both words (`SCRIPT LOAD`). Its arity is the
+// table's (`arity`: the argument count with the name, negative for "at least"), refused with Redis's own
+// "wrong number of arguments". A command the table has but this twin does not serve is the gap, and it
+// answers as Upstash answers a command it does not know — as does a command the table does not have:
+// `ERR Command is not available: 'FOO'. See https://upstash.com/docs/redis/overall/rediscompatibility
+// for details` (live-probed; the compatibility page lists what Upstash serves). `upstashRedisOwners`
+// counts the two. Nothing here ever invents a success for an operation it does not implement.
+import { createHash } from 'node:crypto';
+import { applyTwinWrite, projectResources } from '@volter/world-core';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { luaScriptSha1, LuaError, LuaTable, runLua } from "./upstash-lua.js";
+export const SERVICE = 'upstash';
+/**
+ * A Redis SIMPLE STATUS reply, kept distinct from a bulk string.
+ *
+ * This is not pedantry — it is required for `Upstash-Encoding: base64` fidelity. LIVE-PROBED rule:
+ * with that header on, Upstash base64-encodes every string in `result` at any array depth EXCEPT
+ * the simple-status reply `OK`, which is passed through raw. `PING`'s status `PONG` IS encoded
+ * (`UE9ORw==`), and so is a BULK STRING whose value happens to be `OK` (`GET okkey` → `T0s=`). So
+ * the exemption is scoped to the status reply `OK` specifically, and a twin that exempted any
+ * string equal to `"OK"` would send raw bytes for `GET okkey`. Hence this wrapper.
+ */
+export class RedisStatus {
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+}
+const OK = new RedisStatus('OK');
+/** A command-level failure. `message` is the vendor's literal error string. Maps to HTTP 400. */
+export class RedisCommandError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RedisCommandError';
+    }
+}
+/** Thrown when a write is attempted against a read-only twin. Mapped to HTTP 405 by the handler. */
+export class ReadOnlyError extends Error {
+    constructor() {
+        super('read_only: this twin was started read-only; omit readOnly to accept writes');
+        this.name = 'ReadOnlyError';
+    }
+}
+export const KEY_TYPES = ['string', 'list', 'set', 'hash', 'zset', 'stream'];
+/** The subject-id prefix of a context's database. */
+const scopeOf = (ctx) => (ctx.database === undefined ? '' : `db:${ctx.database}:`);
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ERROR STRINGS — every one of these is LIVE-PROBED off a real Upstash database, byte for byte.
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+const WRONGTYPE = 'WRONGTYPE Operation against a key holding the wrong kind of value';
+const NOT_INT = 'ERR value is not an integer or out of range';
+const NOT_FLOAT = 'ERR value is not a valid float';
+const SYNTAX = 'ERR syntax error';
+const NO_SUCH_KEY = 'ERR no such key';
+const NOSCRIPT = 'NOSCRIPT No matching script. Please use EVAL.';
+/** Upstash's own unavailable-command message — NOT stock Redis's "unknown command". LIVE-PROBED. */
+export function unavailableCommand(name) {
+    return `ERR Command is not available: '${name.toUpperCase()}'. See https://upstash.com/docs/redis/overall/rediscompatibility for details`;
+}
+/** Commands the REST layer refuses outright — LIVE-PROBED message, name upper-cased in quotes. */
+export function restRestricted(name) {
+    return `ERR Command "${name.toUpperCase()}" is not allowed in REST or it has a special context path`;
+}
+export function wrongArity(name) {
+    return `ERR wrong number of arguments for '${name.toLowerCase()}' command`;
+}
+/**
+ * Commands the REST surface rejects even though Redis has them: connection/transaction/pub-sub
+ * control that has no meaning over stateless HTTP. LIVE-PROBED (`AUTH`, `MULTI`, `WATCH`,
+ * `SUBSCRIBE`, `CLIENT` all answered the `not allowed in REST` message).
+ */
+export const REST_RESTRICTED_COMMANDS = new Set([
+    'AUTH', 'MULTI', 'EXEC', 'DISCARD', 'WATCH', 'UNWATCH', 'HELLO', 'RESET',
+    'SUBSCRIBE', 'UNSUBSCRIBE', 'PSUBSCRIBE', 'PUNSUBSCRIBE', 'CLIENT', 'MONITOR',
+]);
+/**
+ * The commands this twin serves, each with the most arguments (after the name) its own parsing takes,
+ * `-1` for no bound: `[min, max]`, where `min` is the table's arity (checked equal for every entry) and
+ * `max` is what the command itself refuses past, with the same "wrong number of arguments". One table for
+ * both callers, `execOne` and `commandShapeError` (which lets `/multi-exec` reject a malformed batch at
+ * QUEUE time, as Redis's `EXECABORT` does). SCRIPT is a container: its subcommands are the table's ids.
+ */
+export const SERVED_COMMANDS = {
+    PING: [0, 1], ECHO: [1, 1], DBSIZE: [0, 0], TYPE: [1, 1], FLUSHDB: [0, 1], FLUSHALL: [0, 1],
+    KEYS: [1, 1], RANDOMKEY: [0, 0], SCAN: [1, -1], SELECT: [1, 1],
+    EXISTS: [1, -1], TOUCH: [1, -1], DEL: [1, -1], UNLINK: [1, -1],
+    EXPIRE: [2, -1], PEXPIRE: [2, -1], EXPIREAT: [2, -1], PEXPIREAT: [2, -1],
+    TTL: [1, 1], PTTL: [1, 1], PERSIST: [1, 1], RENAME: [2, 2], RENAMENX: [2, 2],
+    GET: [1, 1], GETDEL: [1, 1], GETSET: [2, 2], GETEX: [1, 3], SET: [2, -1], SETNX: [2, 2],
+    SETEX: [3, 3], PSETEX: [3, 3], MGET: [1, -1], MSET: [2, -1], MSETNX: [2, -1],
+    APPEND: [2, 2], STRLEN: [1, 1],
+    INCR: [1, 1], DECR: [1, 1], INCRBY: [2, 2], DECRBY: [2, 2], INCRBYFLOAT: [2, 2],
+    HSET: [3, -1], HMSET: [3, -1], HSETNX: [3, 3], HGET: [2, 2], HMGET: [2, -1], HGETALL: [1, 1],
+    HKEYS: [1, 1], HVALS: [1, 1], HLEN: [1, 1], HEXISTS: [2, 2], HDEL: [2, -1],
+    HINCRBY: [3, 3], HINCRBYFLOAT: [3, 3],
+    SADD: [2, -1], SREM: [2, -1], SMEMBERS: [1, 1], SCARD: [1, 1], SISMEMBER: [2, 2],
+    SMISMEMBER: [2, -1], SPOP: [1, 2], SRANDMEMBER: [1, 2],
+    LPUSH: [2, -1], RPUSH: [2, -1], LPOP: [1, 2], RPOP: [1, 2], LLEN: [1, 1], LINDEX: [2, 2],
+    LSET: [3, 3], LRANGE: [3, 3], LTRIM: [3, 3], LREM: [3, 3],
+    ZADD: [3, -1], ZINCRBY: [3, 3], ZSCORE: [2, 2], ZCARD: [1, 1], ZCOUNT: [3, 3],
+    ZRANK: [2, 3], ZREVRANK: [2, 3], ZREM: [2, -1], ZREMRANGEBYSCORE: [3, 3], ZREMRANGEBYRANK: [3, 3],
+    ZRANGE: [3, -1], ZREVRANGE: [3, -1], ZRANGEBYSCORE: [3, -1], ZREVRANGEBYSCORE: [3, -1],
+    XADD: [4, -1], XLEN: [1, 1], XRANGE: [3, -1], XREVRANGE: [3, -1], XDEL: [2, -1],
+    SCRIPT: [1, -1], EVAL: [2, -1], EVAL_RO: [2, -1], EVALSHA: [2, -1], EVALSHA_RO: [2, -1],
+};
+/** Commands that mutate state — refused by a read-only twin and inside `EVAL_RO`/`EVALSHA_RO`. */
+const WRITE_COMMANDS = new Set([
+    'SET', 'SETEX', 'PSETEX', 'SETNX', 'MSET', 'MSETNX', 'GETSET', 'GETDEL', 'GETEX', 'APPEND',
+    'DEL', 'UNLINK', 'INCR', 'DECR', 'INCRBY', 'DECRBY', 'INCRBYFLOAT',
+    'EXPIRE', 'PEXPIRE', 'EXPIREAT', 'PEXPIREAT', 'PERSIST', 'RENAME', 'RENAMENX',
+    'FLUSHDB', 'FLUSHALL', 'HSET', 'HSETNX', 'HMSET', 'HDEL', 'HINCRBY', 'HINCRBYFLOAT',
+    'SADD', 'SREM', 'SPOP', 'LPUSH', 'RPUSH', 'LPOP', 'RPOP', 'LREM', 'LSET', 'LTRIM',
+    'ZADD', 'ZINCRBY', 'ZREM', 'ZREMRANGEBYSCORE', 'ZREMRANGEBYRANK', 'XADD', 'XDEL',
+    // NB: 'SCRIPT' is deliberately ABSENT — it is classified per SUBCOMMAND below, because
+    // `SCRIPT EXISTS` is a pure read and a read-only twin must serve every read (§9 round 1 found
+    // it answering 405). Likewise `EVAL_RO`/`EVALSHA_RO` are reads by definition.
+    'EVAL', 'EVALSHA',
+]);
+/**
+ * Does this command MUTATE? Takes the whole argv, not just the name, because two commands are
+ * only writes for some of their subcommands. A read-only twin and `EVAL_RO` both key off this,
+ * and getting it wrong in either direction is a bug: too broad refuses legitimate reads (§9 round
+ * 1), too narrow lets a write through a read-only twin.
+ */
+export function isWriteCommand(name, args) {
+    const cmd = name.toUpperCase();
+    if (cmd === 'SCRIPT') {
+        // FAIL SAFE when the caller gave no subcommand. §9 round 2: with `args` defaulting to `[]`,
+        // `isWriteCommand('SCRIPT')` answered FALSE — so a consumer building their own read-only gate
+        // on this exported function would classify `SCRIPT LOAD` as a read. An unknown subcommand is
+        // treated as a write for the same reason: the cost of being wrong is asymmetric.
+        if (args === undefined || args.length === 0)
+            return true;
+        const sub = String(args[0]).toUpperCase();
+        return sub !== 'EXISTS'; // EXISTS is the only read subcommand this twin serves
+    }
+    return WRITE_COMMANDS.has(cmd);
+}
+/**
+ * QUEUE-TIME validation: is this command well-formed enough for Redis to accept it into a MULTI?
+ * Returns the vendor's error string, or `null` when the command is fine. Only structural faults
+ * live here (unknown command, REST-restricted command, wrong arity) — a WRONGTYPE or a bad integer
+ * is a RUNTIME error, which (LIVE-PROBED) does NOT abort a transaction.
+ */
+export function commandShapeError(argv) {
+    if (argv.length === 0)
+        return 'ERR empty command';
+    const raw = argv[0];
+    if (typeof raw !== 'string')
+        return unavailableCommand(String(raw));
+    const name = raw.toUpperCase();
+    if (REST_RESTRICTED_COMMANDS.has(name))
+        return restRestricted(name);
+    const id = commandId(argv.map(String));
+    // the gap: a command of Redis's table this twin does not serve answers as Upstash answers an unknown one
+    if (id !== undefined && !SERVED_IDS.has(id))
+        return unavailableCommand(name);
+    if (id !== undefined && wrongTableArity(TABLE.get(id).arity, argv.length))
+        return wrongArity(name);
+    const arity = SERVED_COMMANDS[name];
+    if (!arity)
+        return unavailableCommand(name);
+    const n = argv.length - 1;
+    if (n < arity[0] || (arity[1] !== -1 && n > arity[1]))
+        return wrongArity(name);
+    return null;
+}
+/** Redis's command table (spec/commands at redis 8.4.7), by id. */
+const TABLE = new Map(surface.commands.map((c) => [c.id, c]));
+/** The table id a command line names: a container's subcommand (`SCRIPT LOAD`) when the table has it. */
+export function commandId(argv) {
+    const name = argv[0].toUpperCase();
+    const sub = argv.length > 1 ? `${name} ${argv[1].toUpperCase()}` : undefined;
+    if (sub !== undefined && TABLE.has(sub))
+        return sub;
+    return TABLE.has(name) ? name : undefined;
+}
+/** Redis's arity rule: `arity` counts the name; a negative one is a minimum. */
+const wrongTableArity = (arity, argc) => (arity >= 0 ? argc !== arity : argc < -arity);
+/** The table ids this twin serves: every served command, and the SCRIPT subcommands `execOne` answers. */
+const SERVED_IDS = new Set([...Object.keys(SERVED_COMMANDS).filter((c) => TABLE.has(c)), 'SCRIPT LOAD', 'SCRIPT EXISTS', 'SCRIPT FLUSH']);
+/** Per id of Redis's table, who answers it: the command core (`handler`) or the gap. */
+export function upstashRedisOwners() {
+    return Object.fromEntries(surface.commands.map((c) => [c.id, SERVED_IDS.has(c.id) ? 'handler' : 'gap']));
+}
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// THE KEYSPACE SNAPSHOT
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+/**
+ * A synchronous, in-memory image of the keyspace for the duration of ONE request.
+ *
+ * Seeded from `projectResources` (the kernel IS the source of truth); every mutation records the
+ * key name in `touched`, and `flushKeySpace` writes exactly those keys back. Nothing here outlives
+ * the request — there is no cache, no singleton, no state that a later request could inherit.
+ */
+class KeySpace {
+    ctx;
+    nowMs;
+    rows = new Map();
+    touched = new Map(); // key → the operation label to record
+    scripts = new Map(); // sha1 → script source (a SEPARATE namespace)
+    touchedScripts = new Map();
+    /** name → the last write ordinal seen, INCLUDING for keys currently deleted or expired. */
+    revs = new Map();
+    constructor(ctx, nowMs) {
+        this.ctx = ctx;
+        this.nowMs = nowMs;
+        const scriptPrefix = `${scopeOf(ctx)}script:`;
+        const keyPrefix = `${scopeOf(ctx)}key:`;
+        for (const r of projectResources(SERVICE, ctx.root)) {
+            if (r.type === 'script' && r.id.startsWith(scriptPrefix)) {
+                const rec = r;
+                if (rec.gone !== true && typeof rec.body === 'string')
+                    this.scripts.set(r.id.slice(scriptPrefix.length), rec.body);
+                continue;
+            }
+            if (r.type !== 'key' || !r.id.startsWith(keyPrefix))
+                continue;
+            const rec = r;
+            // Record the ordinal FIRST, for deleted and expired rows too: a key that is later recreated
+            // must CONTINUE the sequence rather than restart it, or the collision could simply recur.
+            if (typeof rec._rev === 'number')
+                this.revs.set(r.id.slice(keyPrefix.length), rec._rev);
+            if (rec.gone === true)
+                continue;
+            const pexpireAt = typeof rec.pexpire_at === 'number' ? rec.pexpire_at : null;
+            // Redis's `keyIsExpired` is `now > when`, so a key is still ALIVE at exactly its deadline
+            // (§9 round 1: the twin was one millisecond early). EXPIRE's own immediate-delete path below
+            // deliberately keeps `<=`, matching Redis's `when <= mstime()` there.
+            if (pexpireAt !== null && pexpireAt < nowMs)
+                continue; // lazily expired — invisible to every read
+            const name = r.id.slice(keyPrefix.length);
+            this.rows.set(name, {
+                name,
+                kind: rec.kind,
+                v: rec.v,
+                pexpireAt,
+                ...(typeof rec.last_id === 'string' && rec.last_id !== '' ? { lastId: rec.last_id } : {}),
+                ...(typeof rec._rev === 'number' ? { _rev: rec._rev } : {}),
+            });
+        }
+    }
+    /**
+     * Is this row expired AS OF NOW? Checked on every read, not merely when the snapshot was built.
+     *
+     * §9 round 2: a deadline set INTO THE PAST inside a batch (`SET k v PXAT 1`, `GETEX k EXAT 1`)
+     * stayed visible for the rest of that batch, and `TTL` answered a huge negative number that real
+     * Redis can never return. Filtering only at construction time made the twin disagree with itself
+     * within one request; re-checking here makes every read path agree at every instant.
+     */
+    live(row) {
+        if (!row)
+            return undefined;
+        return row.pexpireAt !== null && row.pexpireAt < this.nowMs ? undefined : row;
+    }
+    all() { return [...this.rows.values()].filter((r) => this.live(r) !== undefined); }
+    // ── the EVAL script cache ────────────────────────────────────────────────────────────────
+    // Kept in its OWN kernel subject type ('script'), NOT under a magic key prefix in the keyspace.
+    // An earlier draft stored it as a key named ` twin:script:<sha>` and filtered that prefix out of
+    // KEYS/SCAN/DBSIZE, which was a real collision bug: a caller who wrote a key with that exact name
+    // (a legal Redis key — a leading space is fine) had it silently vanish from every listing AND
+    // became able to run it as a script via EVALSHA. Separate subject types make the collision
+    // impossible rather than filtered, so no keyspace command needs to know scripts exist.
+    scriptFor(sha) { return this.scripts.get(sha); }
+    hasScript(sha) { return this.scripts.has(sha); }
+    putScript(sha, body) {
+        if (this.ctx.readOnly)
+            throw new ReadOnlyError();
+        this.scripts.set(sha, body);
+        this.touchedScripts.set(sha, 'script.load');
+    }
+    flushScripts() {
+        if (this.ctx.readOnly)
+            throw new ReadOnlyError();
+        for (const sha of [...this.scripts.keys()]) {
+            this.scripts.delete(sha);
+            this.touchedScripts.set(sha, 'script.flush');
+        }
+    }
+    pendingScriptWrites() {
+        return [...this.touchedScripts.entries()].map(([sha, operation]) => ({ sha, operation, body: this.scripts.get(sha) ?? null }));
+    }
+    get(name) { return this.live(this.rows.get(name)); }
+    put(row, operation) {
+        if (this.ctx.readOnly)
+            throw new ReadOnlyError();
+        this.rows.set(row.name, row);
+        this.touched.set(row.name, operation);
+    }
+    remove(name, operation) {
+        if (this.ctx.readOnly)
+            throw new ReadOnlyError();
+        this.rows.delete(name);
+        this.touched.set(name, operation);
+    }
+    /** A point-in-time copy, so a failed script can be rolled back to exactly where it started. */
+    snapshot() {
+        return { rows: new Map(this.rows), touched: new Map(this.touched), scripts: new Map(this.scripts), touchedScripts: new Map(this.touchedScripts) };
+    }
+    restore(s) {
+        this.rows.clear();
+        for (const [k, v] of s.rows)
+            this.rows.set(k, v);
+        this.touched.clear();
+        for (const [k, v] of s.touched)
+            this.touched.set(k, v);
+        this.scripts.clear();
+        for (const [k, v] of s.scripts)
+            this.scripts.set(k, v);
+        this.touchedScripts.clear();
+        for (const [k, v] of s.touchedScripts)
+            this.touchedScripts.set(k, v);
+    }
+    pendingWrites() {
+        return [...this.touched.entries()].map(([name, operation]) => ({ name, operation, row: this.rows.get(name) ?? null }));
+    }
+    /** The next write ordinal for a key — see `KeyRow._rev`. Survives deletes and expiry. */
+    nextRev(name) {
+        const next = (this.revs.get(name) ?? 0) + 1;
+        this.revs.set(name, next);
+        return next;
+    }
+    /** Did this run write anything? Used to decide whether the sync token advances. */
+    get dirty() { return this.touched.size > 0 || this.touchedScripts.size > 0; }
+}
+/** A database's live keys as they stand at `ctx.occurredAt`: what a backup of it holds (the Developer API lane's
+ *  backups, ../api/src/semantics/backups.ts). */
+export function keyspaceImage(ctx) {
+    return new KeySpace(ctx, Date.parse(ctx.occurredAt)).all().map((r) => ({ name: r.name, kind: r.kind, v: r.v, pexpireAt: r.pexpireAt, ...(r.lastId ? { lastId: r.lastId } : {}) }));
+}
+/** Replace a database's keys with a backup's: every live key is deleted, then the image's keys are written ("All
+ *  existing data in the target database will be deleted before the restore operation begins",
+ *  https://upstash.com/docs/redis/features/backup). */
+export async function restoreKeyspace(image, ctx) {
+    const space = new KeySpace(ctx, Date.parse(ctx.occurredAt));
+    for (const r of space.all())
+        space.remove(r.name, 'key.restore');
+    for (const k of image)
+        space.put({ name: k.name, kind: k.kind, v: k.v, pexpireAt: k.pexpireAt, ...(k.lastId ? { lastId: k.lastId } : {}) }, 'key.restore');
+    await flushKeySpace(space);
+}
+async function flushKeySpace(space) {
+    for (const { name, operation, row } of space.pendingWrites()) {
+        await applyTwinWrite(SERVICE, {
+            operation,
+            subjectType: 'key',
+            subjectId: `${scopeOf(space.ctx)}key:${name}`,
+            // The kernel MERGES fields, so a delete must write EVERY field back to its "nothing here"
+            // value — leaving `v`/`pexpire_at` behind would let a later recreate inherit a dead value
+            // or a dead TTL.
+            fields: row === null
+                ? { name, kind: 'string', v: '', pexpire_at: null, last_id: '', gone: true, _rev: space.nextRev(name) }
+                : { name, kind: row.kind, v: row.v, pexpire_at: row.pexpireAt, last_id: row.lastId ?? '', gone: false, _rev: space.nextRev(name) },
+            occurredAt: space.ctx.occurredAt,
+            actor: { kind: 'agent' },
+        }, space.ctx.root);
+    }
+    for (const { sha, operation, body } of space.pendingScriptWrites()) {
+        await applyTwinWrite(SERVICE, {
+            operation,
+            subjectType: 'script',
+            subjectId: `${scopeOf(space.ctx)}script:${sha}`,
+            fields: body === null ? { sha, body: '', gone: true } : { sha, body, gone: false },
+            occurredAt: space.ctx.occurredAt,
+            actor: { kind: 'agent' },
+        }, space.ctx.root);
+    }
+}
+// ── typed value accessors (each asserts the key's type first) ─────────────────────────────────
+function expectType(row, kind) {
+    if (row && row.kind !== kind)
+        throw new RedisCommandError(WRONGTYPE);
+}
+const asString = (row) => { expectType(row, 'string'); expectShape(row, typeof row?.v === 'string'); return row ? row.v : undefined; };
+/**
+ * Every accessor below asserts the STORED SHAPE, not just the declared type.
+ *
+ * §9 round 2: a connector-pulled stream was stored with `kind:'stream'` but a JSON STRING body,
+ * so `asStream`'s `.map` threw a raw `TypeError` that escaped `handleUpstashRedisTwinRequest`
+ * entirely (it only catches `RedisCommandError`/`ReadOnlyError`) and surfaced as an unhandled
+ * rejection instead of any HTTP response. A twin must fail like the vendor even when its own
+ * stored state is wrong.
+ */
+function expectShape(row, ok) {
+    if (row && !ok)
+        throw new RedisCommandError(`ERR twin: key '${row.name}' is stored as ${row.kind} but its value is malformed — the state it was written from is not usable`);
+}
+const asList = (row) => { expectType(row, 'list'); expectShape(row, Array.isArray(row?.v)); return row ? [...row.v] : []; };
+const asSet = (row) => { expectType(row, 'set'); expectShape(row, Array.isArray(row?.v)); return row ? [...row.v] : []; };
+const asHash = (row) => { expectType(row, 'hash'); expectShape(row, Array.isArray(row?.v)); return row ? row.v.map(([f, v]) => [f, v]) : []; };
+const asZSet = (row) => {
+    expectType(row, 'zset');
+    expectShape(row, Array.isArray(row?.v));
+    // Tolerates a raw number too, so a connector-pulled or hand-written row still loads.
+    return row ? row.v.map(([m, sc]) => [m, typeof sc === 'number' ? sc : toFloat(sc)]) : [];
+};
+/** Serialize for the kernel. The inverse of `asZSet` — see `StoredZSet`. */
+const storeZSet = (pairs) => pairs.map(([m, sc]) => [m, fmtScore(sc)]);
+const asStream = (row) => { expectType(row, 'stream'); expectShape(row, Array.isArray(row?.v)); return row ? row.v.map(([id, f]) => [id, f.map(([x, y]) => [x, y])]) : []; };
+// ── numeric parsing (Redis's exact acceptance rules) ──────────────────────────────────────────
+function toInt(raw) {
+    if (raw !== raw.trim() || !/^[+-]?\d+$/.test(raw))
+        throw new RedisCommandError(NOT_INT);
+    const n = Number(raw);
+    if (!Number.isSafeInteger(n))
+        throw new RedisCommandError(NOT_INT);
+    return n;
+}
+function toFloat(raw) {
+    if (raw !== raw.trim() || raw === '')
+        throw new RedisCommandError(NOT_FLOAT);
+    if (/^[+-]?inf(inity)?$/i.test(raw))
+        return raw.startsWith('-') ? Number.NEGATIVE_INFINITY : Number.POSITIVE_INFINITY;
+    const n = Number(raw);
+    if (!Number.isFinite(n))
+        throw new RedisCommandError(NOT_FLOAT);
+    return n;
+}
+/**
+ * Redis's float-increment guard. `t_string.c` and `t_hash.c` both do
+ * `if (isnan(value) || isinf(value)) addReplyError(c,"increment would produce NaN or Infinity")`.
+ *
+ * §9 round 2 found this missing on the string and hash paths (it had only been added to the sorted
+ * set): `INCRBYFLOAT f inf` answered 200 with "inf", `INCRBYFLOAT f -inf` then persisted the
+ * literal "NaN", and the very next `INCRBYFLOAT f 1` answered "not a valid float" — the twin had
+ * written a value it could no longer read. A fake success that poisons its own key.
+ */
+function guardFloatResult(next) {
+    if (Number.isNaN(next) || !Number.isFinite(next))
+        throw new RedisCommandError('ERR increment would produce NaN or Infinity');
+    return next;
+}
+/** Redis renders a score as a bulk string; infinities spell out. */
+function fmtScore(n) {
+    if (n === Number.POSITIVE_INFINITY)
+        return 'inf';
+    if (n === Number.NEGATIVE_INFINITY)
+        return '-inf';
+    return String(n);
+}
+/** Redis sorts a zset by (score, then member lexicographically). */
+function sortZSet(pairs) {
+    return [...pairs].sort((a, b) => (a[1] - b[1]) || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+}
+/** Redis's start/stop index normalisation (negatives count from the end, ends clamp). */
+function normalizeRange(startRaw, stopRaw, length) {
+    let start = startRaw < 0 ? length + startRaw : startRaw;
+    let stop = stopRaw < 0 ? length + stopRaw : stopRaw;
+    if (start < 0)
+        start = 0;
+    if (stop >= length)
+        stop = length - 1;
+    return [start, stop];
+}
+/** Redis glob-style key matching (`*`, `?`, `[abc]`, `[a-c]`, `[^a]`, `\` escape). */
+export function globMatch(pattern, subject) {
+    let re = '';
+    const esc = (c) => c.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    for (let i = 0; i < pattern.length; i++) {
+        const c = pattern[i];
+        if (c === '\\' && i + 1 < pattern.length) {
+            re += esc(pattern[++i]);
+            continue;
+        }
+        if (c === '*') {
+            re += '[\\s\\S]*';
+            continue;
+        }
+        if (c === '?') {
+            re += '[\\s\\S]';
+            continue;
+        }
+        if (c === '[') {
+            const close = pattern.indexOf(']', i + 1);
+            if (close < 0) {
+                re += '\\[';
+                continue;
+            }
+            let cls = pattern.slice(i + 1, close);
+            const negate = cls.startsWith('^');
+            if (negate)
+                cls = cls.slice(1);
+            re += `[${negate ? '^' : ''}${cls.replace(/\\/g, '\\\\')}]`;
+            i = close;
+            continue;
+        }
+        re += esc(c);
+    }
+    return new RegExp(`^${re}$`).test(subject);
+}
+// ── TTL option parsing, shared by SET and GETEX ────────────────────────────────────────────────
+function ttlFromToken(token, value, nowMs, cmd) {
+    const n = toInt(value);
+    if (token === 'ex') {
+        if (n <= 0)
+            throw new RedisCommandError(`ERR invalid expire time in '${cmd}' command`);
+        return nowMs + n * 1000;
+    }
+    if (token === 'px') {
+        if (n <= 0)
+            throw new RedisCommandError(`ERR invalid expire time in '${cmd}' command`);
+        return nowMs + n;
+    }
+    if (token === 'exat')
+        return n * 1000;
+    return n; // pxat
+}
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// COMMAND DISPATCH — fully synchronous over the snapshot (see the file header for why).
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+function execOne(space, argv) {
+    const shapeError = commandShapeError(argv);
+    if (shapeError !== null)
+        throw new RedisCommandError(shapeError);
+    const name = argv[0].toUpperCase();
+    const a = argv.slice(1);
+    const nowMs = space.nowMs;
+    if (space.ctx.readOnly && isWriteCommand(name, a))
+        throw new ReadOnlyError();
+    switch (name) {
+        // ── connection / server ──────────────────────────────────────────────────────────────────
+        case 'PING': return a.length === 0 ? new RedisStatus('PONG') : a[0];
+        case 'ECHO': return a[0];
+        case 'DBSIZE': return visibleKeys(space).length;
+        case 'TYPE': {
+            const r = space.get(a[0]);
+            return new RedisStatus(r ? r.kind : 'none');
+        }
+        case 'SELECT': {
+            const db = toInt(a[0]);
+            // LIVE-PROBED: Upstash serves exactly one logical database and says so by number.
+            if (db !== 0)
+                throw new RedisCommandError(`ERR Only 0th database is supported! Selected DB: ${db}`);
+            return OK;
+        }
+        case 'FLUSHDB':
+        case 'FLUSHALL': {
+            for (const r of space.all())
+                space.remove(r.name, 'key.flush');
+            return OK;
+        }
+        case 'KEYS': return visibleKeys(space).filter((k) => globMatch(a[0], k)).sort();
+        case 'RANDOMKEY': {
+            // DETERMINISTIC by design: a twin that returned a genuinely random key could not be verified
+            // offline. Disclosed in the manifest (`upstash.keyspace.randomkey_deterministic`).
+            const keys = visibleKeys(space).sort();
+            return keys.length === 0 ? null : keys[0];
+        }
+        case 'SCAN': {
+            const cursor = toInt(a[0]);
+            if (cursor < 0)
+                throw new RedisCommandError('ERR invalid cursor');
+            let match = null;
+            let count = 10;
+            let typeFilter = null;
+            for (let i = 1; i < a.length; i++) {
+                const tok = a[i].toLowerCase();
+                if (tok === 'match') {
+                    if (i + 1 >= a.length)
+                        throw new RedisCommandError(SYNTAX);
+                    match = a[++i];
+                    continue;
+                }
+                if (tok === 'count') {
+                    if (i + 1 >= a.length)
+                        throw new RedisCommandError(SYNTAX);
+                    count = toInt(a[++i]);
+                    if (count < 1)
+                        throw new RedisCommandError(SYNTAX);
+                    continue;
+                }
+                if (tok === 'type') {
+                    if (i + 1 >= a.length)
+                        throw new RedisCommandError(SYNTAX);
+                    typeFilter = a[++i].toLowerCase();
+                    continue;
+                }
+                throw new RedisCommandError(SYNTAX);
+            }
+            // THE CURSOR CONTRACT. Redis's only guarantee is: 0 starts, a returned 0 ends, and a key
+            // present for the WHOLE iteration is returned at least once (keys added or removed mid-scan
+            // may or may not appear). §9 round 1 refuted the first design, an INDEX into a sorted list:
+            // deleting a lower-sorted key shifts the list left under the cursor and a key that was
+            // present throughout is skipped entirely —
+            //     MSET a1..a5 ; SCAN 0 COUNT 2 → ["2",[a1,a2]] ; DEL a1 ; SCAN 2 COUNT 2 → ["4",[a4,a5]]
+            // and a3 is never returned. That breaks the entire contract.
+            //
+            // So the cursor is now a POSITION IN A STABLE KEY-DERIVED ORDER, not a position in a list:
+            // each key gets a fixed 32-bit value from its own name, and the cursor is the next such value
+            // to resume from. A key's position therefore never moves when a DIFFERENT key is added or
+            // removed, which is precisely what makes the guarantee hold. This mirrors what real Redis
+            // does (its cursor is a reverse-binary index into hash buckets, and a key's bucket is derived
+            // from the key too) while staying reproducible, which the real one is not.
+            const all = visibleKeys(space)
+                .filter((k) => typeFilter === null || space.get(k).kind === typeFilter)
+                .map((k) => ({ k, c: scanCursorFor(k) }))
+                .sort((x, y) => (x.c - y.c) || (x.k < y.k ? -1 : x.k > y.k ? 1 : 0));
+            const from = all.filter((e) => e.c >= cursor);
+            let take = from.slice(0, Math.max(1, count));
+            // Never split a group of keys sharing a cursor value across pages: the resume point is a
+            // cursor VALUE, so a key left behind in a half-emitted group could never be reached again.
+            if (take.length > 0 && take.length < from.length) {
+                const lastC = take[take.length - 1].c;
+                take = from.filter((e) => e.c <= lastC);
+            }
+            const remaining = from.length - take.length;
+            const next = remaining === 0 ? 0 : take[take.length - 1].c + 1;
+            return [String(next), take.map((e) => e.k).filter((k) => match === null || globMatch(match, k))];
+        }
+        // ── generic keyspace ─────────────────────────────────────────────────────────────────────
+        case 'EXISTS':
+        case 'TOUCH': {
+            let n = 0;
+            for (const k of a)
+                if (space.get(k))
+                    n++;
+            return n;
+        }
+        case 'DEL':
+        case 'UNLINK': {
+            let n = 0;
+            for (const k of a)
+                if (space.get(k)) {
+                    space.remove(k, 'key.del');
+                    n++;
+                }
+            return n;
+        }
+        case 'EXPIRE':
+        case 'PEXPIRE':
+        case 'EXPIREAT':
+        case 'PEXPIREAT': {
+            const row = space.get(a[0]);
+            const n = toInt(a[1]);
+            // Redis 7.0's options (redis.io/docs/latest/commands/expire/, "Options"): NX sets only a key with no expiry, XX
+            // only one with an expiry, GT only a later deadline, LT only an earlier one, a key with no expiry counting as
+            // one that never expires; NX with any other, and GT with LT, are refused
+            const opts = new Set(a.slice(2).map((o) => { const u = o.toUpperCase(); if (!['NX', 'XX', 'GT', 'LT'].includes(u))
+                throw new RedisCommandError(`ERR Unsupported option ${o}`); return u; }));
+            if (opts.has('NX') && (opts.has('XX') || opts.has('GT') || opts.has('LT')))
+                throw new RedisCommandError('ERR NX and XX, GT or LT options at the same time are not compatible');
+            if (opts.has('GT') && opts.has('LT'))
+                throw new RedisCommandError('ERR GT and LT options at the same time are not compatible');
+            if (!row)
+                return 0;
+            const at = name === 'EXPIRE' ? nowMs + n * 1000
+                : name === 'PEXPIRE' ? nowMs + n
+                    : name === 'EXPIREAT' ? n * 1000
+                        : n;
+            if (opts.has('NX') && row.pexpireAt !== null)
+                return 0;
+            if (opts.has('XX') && row.pexpireAt === null)
+                return 0;
+            if (opts.has('GT') && (row.pexpireAt === null || at <= row.pexpireAt))
+                return 0;
+            if (opts.has('LT') && row.pexpireAt !== null && at >= row.pexpireAt)
+                return 0;
+            // A deadline already in the past DELETES the key, exactly as Redis does.
+            if (at <= nowMs) {
+                space.remove(a[0], 'key.expire_now');
+                return 1;
+            }
+            space.put({ ...row, pexpireAt: at }, 'key.expire');
+            return 1;
+        }
+        case 'TTL':
+        case 'PTTL': {
+            const row = space.get(a[0]);
+            if (!row)
+                return -2;
+            if (row.pexpireAt === null)
+                return -1;
+            const remainingMs = row.pexpireAt - nowMs;
+            // Redis computes `(ttl+500)/1000` in integer arithmetic — round HALF-UP, not ceil. With ceil,
+            // a key set `EX 10` and read 600ms later still reported 10 where the vendor says 9 (§9 round
+            // 1); every earlier verify happened to land on an exact second boundary, where they agree.
+            return name === 'TTL' ? Math.round(remainingMs / 1000) : remainingMs;
+        }
+        case 'PERSIST': {
+            const row = space.get(a[0]);
+            if (!row || row.pexpireAt === null)
+                return 0;
+            space.put({ ...row, pexpireAt: null }, 'key.persist');
+            return 1;
+        }
+        case 'RENAME':
+        case 'RENAMENX': {
+            const row = space.get(a[0]);
+            if (!row)
+                throw new RedisCommandError(NO_SUCH_KEY);
+            if (a[0] === a[1])
+                return name === 'RENAME' ? OK : 0;
+            if (name === 'RENAMENX' && space.get(a[1]))
+                return 0;
+            space.put({ ...row, name: a[1] }, 'key.rename');
+            space.remove(a[0], 'key.rename_src');
+            return name === 'RENAME' ? OK : 1;
+        }
+        // ── strings ──────────────────────────────────────────────────────────────────────────────
+        case 'GET': {
+            const v = asString(space.get(a[0]));
+            return v === undefined ? null : v;
+        }
+        case 'GETDEL': {
+            const row = space.get(a[0]);
+            const v = asString(row);
+            if (row)
+                space.remove(a[0], 'string.getdel');
+            return v === undefined ? null : v;
+        }
+        case 'GETSET': {
+            const old = asString(space.get(a[0]));
+            space.put({ name: a[0], kind: 'string', v: a[1], pexpireAt: null }, 'string.getset');
+            return old === undefined ? null : old;
+        }
+        case 'GETEX': {
+            const row = space.get(a[0]);
+            const v = asString(row);
+            if (!row)
+                return null;
+            if (a.length === 1)
+                return v ?? null;
+            const tok = a[1].toLowerCase();
+            if (tok === 'persist') {
+                space.put({ ...row, pexpireAt: null }, 'string.getex');
+                return v ?? null;
+            }
+            if (!['ex', 'px', 'exat', 'pxat'].includes(tok) || a.length < 3)
+                throw new RedisCommandError(SYNTAX);
+            space.put({ ...row, pexpireAt: ttlFromToken(tok, a[2], nowMs, 'getex') }, 'string.getex');
+            return v ?? null;
+        }
+        case 'SET': {
+            const [key, value] = [a[0], a[1]];
+            let nx = false;
+            let xx = false;
+            let get = false;
+            let keepTtl = false;
+            let pexpireAt = null;
+            for (let i = 2; i < a.length; i++) {
+                // Case-INSENSITIVE by necessity: the official SDK emits the TTL/flag tokens lowercase and
+                // pushes `keepTtl` in literal camelCase (`pkg/commands/set.ts`), which the real server
+                // accepts. A case-sensitive parser here would reject the vendor's own client.
+                const tok = a[i].toLowerCase();
+                if (tok === 'nx') {
+                    nx = true;
+                    continue;
+                }
+                if (tok === 'xx') {
+                    xx = true;
+                    continue;
+                }
+                if (tok === 'get') {
+                    get = true;
+                    continue;
+                }
+                if (tok === 'keepttl') {
+                    keepTtl = true;
+                    continue;
+                }
+                if (['ex', 'px', 'exat', 'pxat'].includes(tok)) {
+                    if (i + 1 >= a.length)
+                        throw new RedisCommandError(SYNTAX);
+                    pexpireAt = ttlFromToken(tok, a[++i], nowMs, 'set');
+                    continue;
+                }
+                throw new RedisCommandError(SYNTAX);
+            }
+            if (nx && xx)
+                throw new RedisCommandError(SYNTAX);
+            const existing = space.get(key);
+            if (get && existing && existing.kind !== 'string')
+                throw new RedisCommandError(WRONGTYPE);
+            const old = existing?.kind === 'string' ? existing.v : undefined;
+            // THE `null` RETURN THAT MATTERS: a failed NX/XX answers nil, NOT "OK". dub branches on
+            // `res === null` in a dozen lock/dedupe paths (lib/upstash/redis-lock.ts, track-lead.ts,
+            // track-sale.ts, …), so getting this wrong turns every distributed lock into a no-op.
+            if (nx && existing)
+                return get ? (old ?? null) : null;
+            if (xx && !existing)
+                return get ? (old ?? null) : null;
+            space.put({ name: key, kind: 'string', v: value, pexpireAt: keepTtl ? (existing?.pexpireAt ?? null) : pexpireAt }, 'string.set');
+            return get ? (old ?? null) : OK;
+        }
+        case 'SETNX': {
+            if (space.get(a[0]))
+                return 0;
+            space.put({ name: a[0], kind: 'string', v: a[1], pexpireAt: null }, 'string.setnx');
+            return 1;
+        }
+        case 'SETEX':
+        case 'PSETEX': {
+            const n = toInt(a[1]);
+            if (n <= 0)
+                throw new RedisCommandError(`ERR invalid expire time in '${name.toLowerCase()}' command`);
+            space.put({ name: a[0], kind: 'string', v: a[2], pexpireAt: nowMs + (name === 'SETEX' ? n * 1000 : n) }, 'string.setex');
+            return OK;
+        }
+        case 'MGET': return a.map((k) => { const r = space.get(k); return r && r.kind === 'string' ? r.v : null; });
+        case 'MSET':
+        case 'MSETNX': {
+            if (a.length % 2 !== 0)
+                throw new RedisCommandError(wrongArity(name));
+            if (name === 'MSETNX') {
+                for (let i = 0; i < a.length; i += 2)
+                    if (space.get(a[i]))
+                        return 0;
+            }
+            for (let i = 0; i < a.length; i += 2)
+                space.put({ name: a[i], kind: 'string', v: a[i + 1], pexpireAt: null }, 'string.mset');
+            return name === 'MSET' ? OK : 1;
+        }
+        case 'APPEND': {
+            const row = space.get(a[0]);
+            const next = (asString(row) ?? '') + a[1];
+            space.put({ name: a[0], kind: 'string', v: next, pexpireAt: row?.pexpireAt ?? null }, 'string.append');
+            return next.length;
+        }
+        case 'STRLEN': return (asString(space.get(a[0])) ?? '').length;
+        case 'INCR':
+        case 'DECR':
+        case 'INCRBY':
+        case 'DECRBY': {
+            const by = name === 'INCR' ? 1 : name === 'DECR' ? -1 : toInt(a[1]) * (name === 'DECRBY' ? -1 : 1);
+            const row = space.get(a[0]);
+            const current = asString(row);
+            const next = (current === undefined ? 0 : toInt(current)) + by;
+            if (!Number.isSafeInteger(next))
+                throw new RedisCommandError('ERR increment or decrement would overflow');
+            // INCR PRESERVES the key's TTL (real Redis semantics). This is exactly what makes
+            // @upstash/ratelimit's fixed-window script correct: the PEXPIRE is armed on the first
+            // increment and every later INCRBY must leave it alone, or the window would never close.
+            space.put({ name: a[0], kind: 'string', v: String(next), pexpireAt: row?.pexpireAt ?? null }, 'string.incr');
+            return next;
+        }
+        case 'INCRBYFLOAT': {
+            const row = space.get(a[0]);
+            const current = asString(row);
+            const text = fmtScore(guardFloatResult((current === undefined ? 0 : toFloat(current)) + toFloat(a[1])));
+            space.put({ name: a[0], kind: 'string', v: text, pexpireAt: row?.pexpireAt ?? null }, 'string.incrbyfloat');
+            return text;
+        }
+        // ── hashes ───────────────────────────────────────────────────────────────────────────────
+        case 'HSET':
+        case 'HMSET': {
+            if ((a.length - 1) % 2 !== 0)
+                throw new RedisCommandError(wrongArity(name));
+            const row = space.get(a[0]);
+            const pairs = asHash(row);
+            let added = 0;
+            for (let i = 1; i < a.length; i += 2) {
+                const idx = pairs.findIndex(([f]) => f === a[i]);
+                if (idx < 0) {
+                    pairs.push([a[i], a[i + 1]]);
+                    added++;
+                }
+                else
+                    pairs[idx] = [a[i], a[i + 1]];
+            }
+            space.put({ name: a[0], kind: 'hash', v: pairs, pexpireAt: row?.pexpireAt ?? null }, 'hash.set');
+            return name === 'HMSET' ? OK : added;
+        }
+        case 'HSETNX': {
+            const row = space.get(a[0]);
+            const pairs = asHash(row);
+            if (pairs.some(([f]) => f === a[1]))
+                return 0;
+            pairs.push([a[1], a[2]]);
+            space.put({ name: a[0], kind: 'hash', v: pairs, pexpireAt: row?.pexpireAt ?? null }, 'hash.setnx');
+            return 1;
+        }
+        case 'HGET': {
+            const p = asHash(space.get(a[0])).find(([f]) => f === a[1]);
+            return p ? p[1] : null;
+        }
+        case 'HMGET': {
+            const pairs = asHash(space.get(a[0]));
+            return a.slice(1).map((f) => pairs.find(([k]) => k === f)?.[1] ?? null);
+        }
+        case 'HGETALL': return asHash(space.get(a[0])).flat();
+        case 'HKEYS': return asHash(space.get(a[0])).map(([f]) => f);
+        case 'HVALS': return asHash(space.get(a[0])).map(([, v]) => v);
+        case 'HLEN': return asHash(space.get(a[0])).length;
+        case 'HEXISTS': return asHash(space.get(a[0])).some(([f]) => f === a[1]) ? 1 : 0;
+        case 'HDEL': {
+            const row = space.get(a[0]);
+            const pairs = asHash(row);
+            const doomed = a.slice(1);
+            const kept = pairs.filter(([f]) => !doomed.includes(f));
+            if (row) {
+                if (kept.length === 0)
+                    space.remove(a[0], 'hash.del_empty'); // Redis drops an emptied key
+                else
+                    space.put({ ...row, kind: 'hash', v: kept }, 'hash.del');
+            }
+            return pairs.length - kept.length;
+        }
+        case 'HINCRBY':
+        case 'HINCRBYFLOAT': {
+            const isFloat = name === 'HINCRBYFLOAT';
+            const row = space.get(a[0]);
+            const pairs = asHash(row);
+            const idx = pairs.findIndex(([f]) => f === a[1]);
+            const current = idx < 0 ? undefined : pairs[idx][1];
+            const base = current === undefined ? 0 : (isFloat ? toFloat(current) : toInt(current));
+            const next = isFloat ? guardFloatResult(base + toFloat(a[2])) : base + toInt(a[2]);
+            const text = isFloat ? fmtScore(next) : String(next);
+            if (idx < 0)
+                pairs.push([a[1], text]);
+            else
+                pairs[idx] = [a[1], text];
+            space.put({ name: a[0], kind: 'hash', v: pairs, pexpireAt: row?.pexpireAt ?? null }, 'hash.incrby');
+            return isFloat ? text : next;
+        }
+        // ── sets ─────────────────────────────────────────────────────────────────────────────────
+        case 'SADD': {
+            const row = space.get(a[0]);
+            const members = asSet(row);
+            let added = 0;
+            for (const m of a.slice(1))
+                if (!members.includes(m)) {
+                    members.push(m);
+                    added++;
+                }
+            space.put({ name: a[0], kind: 'set', v: members, pexpireAt: row?.pexpireAt ?? null }, 'set.add');
+            return added;
+        }
+        case 'SREM': {
+            const row = space.get(a[0]);
+            const members = asSet(row);
+            const doomed = a.slice(1);
+            const kept = members.filter((m) => !doomed.includes(m));
+            if (row) {
+                if (kept.length === 0)
+                    space.remove(a[0], 'set.rem_empty');
+                else
+                    space.put({ ...row, kind: 'set', v: kept }, 'set.rem');
+            }
+            return members.length - kept.length;
+        }
+        case 'SMEMBERS': return asSet(space.get(a[0]));
+        case 'SCARD': return asSet(space.get(a[0])).length;
+        case 'SISMEMBER': return asSet(space.get(a[0])).includes(a[1]) ? 1 : 0;
+        case 'SMISMEMBER': {
+            const members = asSet(space.get(a[0]));
+            return a.slice(1).map((m) => (members.includes(m) ? 1 : 0));
+        }
+        case 'SRANDMEMBER':
+        case 'SPOP': {
+            const row = space.get(a[0]);
+            const members = asSet(row);
+            const count = a.length >= 2 ? toInt(a[1]) : null;
+            // SPOP's count must be positive; SRANDMEMBER's may be negative, and then "the command is allowed to return the
+            // same element multiple times", |count| of them (redis.io/docs/latest/commands/srandmember/)
+            if (name === 'SPOP' && count !== null && count < 0)
+                throw new RedisCommandError('ERR value is out of range, must be positive');
+            if (name === 'SRANDMEMBER' && count !== null && count < 0)
+                return members.length === 0 ? [] : Array.from({ length: -count }, (_, i) => members[i % members.length]);
+            // DETERMINISTIC: takes from the FRONT of insertion order rather than at random, for the same
+            // reason RANDOMKEY does. Disclosed (`upstash.sets.spop_deterministic`).
+            const taken = members.slice(0, count === null ? 1 : Math.max(0, count));
+            if (name === 'SPOP' && taken.length > 0) {
+                const kept = members.slice(taken.length);
+                if (kept.length === 0)
+                    space.remove(a[0], 'set.pop_empty');
+                else
+                    space.put({ ...row, kind: 'set', v: kept }, 'set.pop');
+            }
+            return count === null ? (taken[0] ?? null) : taken;
+        }
+        // ── lists ────────────────────────────────────────────────────────────────────────────────
+        case 'LPUSH':
+        case 'RPUSH': {
+            const row = space.get(a[0]);
+            const items = asList(row);
+            // LPUSH inserts each element at the head IN TURN, so `LPUSH k a b` leaves [b, a].
+            if (name === 'LPUSH')
+                for (const v of a.slice(1))
+                    items.unshift(v);
+            else
+                items.push(...a.slice(1));
+            space.put({ name: a[0], kind: 'list', v: items, pexpireAt: row?.pexpireAt ?? null }, 'list.push');
+            return items.length;
+        }
+        case 'LPOP':
+        case 'RPOP': {
+            const row = space.get(a[0]);
+            const items = asList(row);
+            const count = a.length >= 2 ? toInt(a[1]) : null;
+            if (count !== null && count < 0)
+                throw new RedisCommandError('ERR value is out of range, must be positive');
+            if (items.length === 0)
+                return null;
+            const n = count === null ? 1 : count;
+            const taken = name === 'LPOP' ? items.splice(0, n) : items.splice(Math.max(0, items.length - n)).reverse();
+            if (items.length === 0)
+                space.remove(a[0], 'list.pop_empty');
+            else
+                space.put({ ...row, kind: 'list', v: items }, 'list.pop');
+            return count === null ? (taken[0] ?? null) : taken;
+        }
+        case 'LLEN': return asList(space.get(a[0])).length;
+        case 'LINDEX': {
+            const items = asList(space.get(a[0]));
+            const i = toInt(a[1]);
+            return items[i < 0 ? items.length + i : i] ?? null;
+        }
+        case 'LSET': {
+            const row = space.get(a[0]);
+            if (!row)
+                throw new RedisCommandError(NO_SUCH_KEY);
+            const items = asList(row);
+            const raw = toInt(a[1]);
+            const i = raw < 0 ? items.length + raw : raw;
+            if (i < 0 || i >= items.length)
+                throw new RedisCommandError('ERR index out of range');
+            items[i] = a[2];
+            space.put({ ...row, kind: 'list', v: items }, 'list.set');
+            return OK;
+        }
+        case 'LRANGE': {
+            const items = asList(space.get(a[0]));
+            const [start, stop] = normalizeRange(toInt(a[1]), toInt(a[2]), items.length);
+            return start > stop ? [] : items.slice(start, stop + 1);
+        }
+        case 'LTRIM': {
+            const row = space.get(a[0]);
+            const items = asList(row);
+            if (!row)
+                return OK;
+            const [start, stop] = normalizeRange(toInt(a[1]), toInt(a[2]), items.length);
+            const kept = start > stop ? [] : items.slice(start, stop + 1);
+            if (kept.length === 0)
+                space.remove(a[0], 'list.trim_empty');
+            else
+                space.put({ ...row, kind: 'list', v: kept }, 'list.trim');
+            return OK;
+        }
+        case 'LREM': {
+            const row = space.get(a[0]);
+            const items = asList(row);
+            const count = toInt(a[1]);
+            const target = a[2];
+            const limit = Math.abs(count);
+            const source = count < 0 ? [...items].reverse() : items;
+            const kept = [];
+            let removed = 0;
+            for (const item of source) {
+                if (item === target && (limit === 0 || removed < limit)) {
+                    removed++;
+                    continue;
+                }
+                kept.push(item);
+            }
+            const result = count < 0 ? kept.reverse() : kept;
+            if (row) {
+                if (result.length === 0)
+                    space.remove(a[0], 'list.rem_empty');
+                else
+                    space.put({ ...row, kind: 'list', v: result }, 'list.rem');
+            }
+            return removed;
+        }
+        // ── sorted sets ──────────────────────────────────────────────────────────────────────────
+        case 'ZADD': return zadd(space, a);
+        case 'ZINCRBY': {
+            const row = space.get(a[0]);
+            const pairs = asZSet(row);
+            const by = toFloat(a[1]);
+            const idx = pairs.findIndex(([m]) => m === a[2]);
+            const next = (idx < 0 ? 0 : pairs[idx][1]) + by;
+            if (Number.isNaN(next))
+                throw new RedisCommandError('ERR resulting score is not a number (NaN)');
+            if (idx < 0)
+                pairs.push([a[2], next]);
+            else
+                pairs[idx] = [a[2], next];
+            space.put({ name: a[0], kind: 'zset', v: storeZSet(sortZSet(pairs)), pexpireAt: row?.pexpireAt ?? null }, 'zset.incrby');
+            return fmtScore(next);
+        }
+        case 'ZSCORE': {
+            const p = asZSet(space.get(a[0])).find(([m]) => m === a[1]);
+            return p ? fmtScore(p[1]) : null;
+        }
+        case 'ZCARD': return asZSet(space.get(a[0])).length;
+        case 'ZCOUNT': {
+            const lo = parseScoreBound(a[1]);
+            const hi = parseScoreBound(a[2]);
+            return asZSet(space.get(a[0])).filter(([, s]) => inScoreRange(s, lo, hi)).length;
+        }
+        case 'ZRANK':
+        case 'ZREVRANK': {
+            const sorted = sortZSet(asZSet(space.get(a[0])));
+            const ordered = name === 'ZREVRANK' ? [...sorted].reverse() : sorted;
+            const i = ordered.findIndex(([m]) => m === a[1]);
+            // WITHSCORE (Redis 7.2): the rank and the member's score
+            if (a.length === 3 && a[2].toUpperCase() !== 'WITHSCORE')
+                throw new RedisCommandError(SYNTAX);
+            if (a.length === 3)
+                return i < 0 ? null : [i, fmtScore(ordered[i][1])];
+            return i < 0 ? null : i;
+        }
+        case 'ZREM': {
+            const row = space.get(a[0]);
+            const pairs = asZSet(row);
+            const doomed = a.slice(1);
+            const kept = pairs.filter(([m]) => !doomed.includes(m));
+            if (row) {
+                if (kept.length === 0)
+                    space.remove(a[0], 'zset.rem_empty');
+                else
+                    space.put({ ...row, kind: 'zset', v: storeZSet(kept) }, 'zset.rem');
+            }
+            return pairs.length - kept.length;
+        }
+        case 'ZREMRANGEBYSCORE': {
+            const row = space.get(a[0]);
+            const pairs = asZSet(row);
+            const lo = parseScoreBound(a[1]);
+            const hi = parseScoreBound(a[2]);
+            const kept = pairs.filter(([, s]) => !inScoreRange(s, lo, hi));
+            if (row) {
+                if (kept.length === 0)
+                    space.remove(a[0], 'zset.remrange_empty');
+                else
+                    space.put({ ...row, kind: 'zset', v: storeZSet(kept) }, 'zset.remrange');
+            }
+            return pairs.length - kept.length;
+        }
+        case 'ZREMRANGEBYRANK': {
+            const row = space.get(a[0]);
+            const sorted = sortZSet(asZSet(row));
+            const [start, stop] = normalizeRange(toInt(a[1]), toInt(a[2]), sorted.length);
+            const doomed = start > stop ? [] : sorted.slice(start, stop + 1).map(([m]) => m);
+            const kept = sorted.filter(([m]) => !doomed.includes(m));
+            if (row) {
+                if (kept.length === 0)
+                    space.remove(a[0], 'zset.remrank_empty');
+                else
+                    space.put({ ...row, kind: 'zset', v: storeZSet(kept) }, 'zset.remrank');
+            }
+            return doomed.length;
+        }
+        case 'ZRANGE':
+        case 'ZREVRANGE':
+        case 'ZRANGEBYSCORE':
+        case 'ZREVRANGEBYSCORE': return zrange(space, name, a);
+        // ── streams (dub's lib/upstash/redis-streams client uses exactly these five) ──────────────
+        case 'XADD': return xadd(space, a, nowMs);
+        case 'XLEN': return asStream(space.get(a[0])).length;
+        case 'XRANGE':
+        case 'XREVRANGE': {
+            const entries = asStream(space.get(a[0]));
+            const _rev = name === 'XREVRANGE';
+            // XREVRANGE takes its bounds in REVERSE order (`XREVRANGE key + -`).
+            const [startRaw, endRaw] = _rev ? [a[2], a[1]] : [a[1], a[2]];
+            let count = null;
+            if (a.length >= 5) {
+                if (a[3].toLowerCase() !== 'count')
+                    throw new RedisCommandError(SYNTAX);
+                count = toInt(a[4]);
+            }
+            else if (a.length === 4)
+                throw new RedisCommandError(SYNTAX);
+            const lo = parseStreamBound(startRaw, 'min');
+            const hi = parseStreamBound(endRaw, 'max');
+            // a bound prefixed `(` is exclusive (XRANGE: "Exclusive ranges", redis.io/docs/latest/commands/xrange)
+            const loOpen = startRaw.startsWith('(');
+            const hiOpen = endRaw.startsWith('(');
+            let selected = entries.filter(([id]) => {
+                const fromLo = compareStreamIds(id, lo);
+                const toHi = compareStreamIds(id, hi);
+                return (loOpen ? fromLo > 0 : fromLo >= 0) && (hiOpen ? toHi < 0 : toHi <= 0);
+            });
+            if (_rev)
+                selected = selected.reverse();
+            if (count !== null)
+                selected = selected.slice(0, Math.max(0, count));
+            return selected.map(([id, fields]) => [id, fields.flat()]);
+        }
+        case 'XDEL': {
+            const row = space.get(a[0]);
+            const entries = asStream(row);
+            const doomed = a.slice(1);
+            const kept = entries.filter(([id]) => !doomed.includes(id));
+            if (row)
+                space.put({ ...row, kind: 'stream', v: kept }, 'stream.del');
+            return entries.length - kept.length;
+        }
+        // ── scripting ────────────────────────────────────────────────────────────────────────────
+        case 'SCRIPT': {
+            const sub = a[0].toUpperCase();
+            if (sub === 'LOAD') {
+                if (a.length !== 2)
+                    throw new RedisCommandError(wrongArity('script'));
+                return storeScript(space, a[1]);
+            }
+            if (sub === 'EXISTS')
+                return a.slice(1).map((sha) => (space.hasScript(sha.toLowerCase()) ? 1 : 0));
+            if (sub === 'FLUSH') {
+                space.flushScripts();
+                return OK;
+            }
+            throw new RedisCommandError(`ERR Unknown SCRIPT subcommand or wrong number of arguments for '${a[0]}'`);
+        }
+        case 'EVAL':
+        case 'EVAL_RO':
+        case 'EVALSHA':
+        case 'EVALSHA_RO': {
+            const bySha = name.startsWith('EVALSHA');
+            let script;
+            if (bySha) {
+                const found = space.scriptFor(a[0].toLowerCase());
+                // THE `NOSCRIPT` CONTRACT: @upstash/ratelimit ALWAYS tries EVALSHA first and only falls back
+                // to EVAL when the error text contains "NOSCRIPT" (its `safeEval`, src/hash.ts). Answering
+                // anything else here — above all a fake success — breaks every rate limiter pointed at this
+                // twin, silently. This is the single most load-bearing error string in the pack.
+                if (found === undefined)
+                    throw new RedisCommandError(NOSCRIPT);
+                script = found;
+            }
+            else {
+                script = a[0];
+                // Caching is a WRITE, so a read-only twin must not attempt it — otherwise `EVAL_RO`, which
+                // is a read by definition, would 405 on the cache rather than on anything it does (§9
+                // round 1). The cost is that a read-only twin cannot serve a later EVALSHA for this
+                // script, which is the correct read-only outcome rather than a silent write.
+                if (!space.ctx.readOnly)
+                    storeScript(space, script);
+            }
+            const numKeys = toInt(a[1]);
+            if (numKeys < 0)
+                throw new RedisCommandError("ERR Number of keys can't be negative");
+            if (numKeys > a.length - 2)
+                throw new RedisCommandError("ERR Number of keys can't be greater than number of args");
+            return evalScript(space, script, a.slice(2, 2 + numKeys), a.slice(2 + numKeys), name.endsWith('_RO'));
+        }
+        default:
+            // Unreachable: `commandShapeError` above already rejected anything not in SERVED_COMMANDS.
+            throw new RedisCommandError(unavailableCommand(name));
+    }
+}
+/**
+ * A key's fixed position in SCAN's iteration order: the low 31 bits of its own SHA-1.
+ *
+ * Deriving it from the KEY NAME is the whole point — the position is a property of the key, so
+ * adding or deleting any OTHER key cannot move it, and a key present for the whole scan is
+ * therefore returned exactly once. `+1` keeps every value strictly positive so that cursor 0
+ * unambiguously means "start"/"done" and can never also mean "resume at the first key".
+ */
+function scanCursorFor(key) {
+    return (Number.parseInt(createHash('sha1').update(key).digest('hex').slice(0, 8), 16) >>> 1) + 1;
+}
+/** Live key names, with the internal script-cache keys filtered out of the keyspace entirely. */
+/** Every live key name. No filtering: the script cache lives in a different subject type entirely,
+ *  so there is no internal name for a caller's key to collide with or be hidden by. */
+function visibleKeys(space) {
+    return space.all().map((r) => r.name);
+}
+function parseScoreBound(raw) {
+    const exclusive = raw.startsWith('(');
+    return { value: toFloat(exclusive ? raw.slice(1) : raw), exclusive };
+}
+function inScoreRange(score, lo, hi) {
+    return (lo.exclusive ? score > lo.value : score >= lo.value) && (hi.exclusive ? score < hi.value : score <= hi.value);
+}
+function zadd(space, a) {
+    let nx = false;
+    let xx = false;
+    let gt = false;
+    let lt = false;
+    let ch = false;
+    let incr = false;
+    let i = 1;
+    for (; i < a.length; i++) {
+        const tok = a[i].toLowerCase();
+        if (tok === 'nx') {
+            nx = true;
+            continue;
+        }
+        if (tok === 'xx') {
+            xx = true;
+            continue;
+        }
+        if (tok === 'gt') {
+            gt = true;
+            continue;
+        }
+        if (tok === 'lt') {
+            lt = true;
+            continue;
+        }
+        if (tok === 'ch') {
+            ch = true;
+            continue;
+        }
+        if (tok === 'incr') {
+            incr = true;
+            continue;
+        }
+        break;
+    }
+    if (nx && xx)
+        throw new RedisCommandError('ERR XX and NX options at the same time are not compatible');
+    if ((nx && (gt || lt)) || (gt && lt))
+        throw new RedisCommandError('ERR GT, LT, and/or NX options at the same time are not compatible');
+    const rest = a.slice(i);
+    if (rest.length === 0 || rest.length % 2 !== 0)
+        throw new RedisCommandError(SYNTAX);
+    if (incr && rest.length !== 2)
+        throw new RedisCommandError('ERR INCR option supports a single increment-element pair');
+    const row = space.get(a[0]);
+    const pairs = asZSet(row);
+    let added = 0;
+    let changed = 0;
+    let incrResult = null;
+    for (let j = 0; j < rest.length; j += 2) {
+        const score = toFloat(rest[j]);
+        const member = rest[j + 1];
+        const idx = pairs.findIndex(([m]) => m === member);
+        if (idx < 0) {
+            if (xx) {
+                incrResult = null;
+                continue;
+            }
+            pairs.push([member, score]);
+            added++;
+            changed++;
+            incrResult = score;
+            continue;
+        }
+        if (nx) {
+            incrResult = null;
+            continue;
+        }
+        const current = pairs[idx][1];
+        const next = incr ? current + score : score;
+        // Redis refuses a score that computes to NaN (e.g. +inf added to -inf) by name.
+        if (Number.isNaN(next))
+            throw new RedisCommandError('ERR resulting score is not a number (NaN)');
+        // A GT/LT that REFUSES the move answers nil under INCR — real Redis marks ZADD_OUT_NOP and
+        // replies null, which is how a caller distinguishes "applied" from "refused" (the same
+        // distinction `SET … NX` relies on). Answering the current score would silently read as success.
+        if ((gt && next <= current) || (lt && next >= current)) {
+            incrResult = null;
+            continue;
+        }
+        if (next !== current)
+            changed++;
+        pairs[idx] = [member, next];
+        incrResult = next;
+    }
+    // THE HUSK GUARD (§9 round 1): `ZADD missing XX 1 m` adds nothing, and real Redis creates no key
+    // at all. An unconditional write here materialised an EMPTY zset that EXISTS/TYPE/DBSIZE/KEYS all
+    // reported and that made a later LPUSH on the same name raise WRONGTYPE. Only write when there is
+    // something to write, or when the key already existed.
+    if (pairs.length > 0 || row !== undefined) {
+        space.put({ name: a[0], kind: 'zset', v: storeZSet(sortZSet(pairs)), pexpireAt: row?.pexpireAt ?? null }, 'zset.add');
+    }
+    if (incr)
+        return incrResult === null ? null : fmtScore(incrResult);
+    return ch ? changed : added;
+}
+function zrange(space, name, a) {
+    let byScore = name === 'ZRANGEBYSCORE' || name === 'ZREVRANGEBYSCORE';
+    let _rev = name === 'ZREVRANGE' || name === 'ZREVRANGEBYSCORE';
+    let withScores = false;
+    let limit = null;
+    for (let i = 3; i < a.length; i++) {
+        const tok = a[i].toLowerCase();
+        if (tok === 'withscores') {
+            withScores = true;
+            continue;
+        }
+        if (tok === 'byscore') {
+            byScore = true;
+            continue;
+        }
+        if (tok === 'rev') {
+            _rev = true;
+            continue;
+        }
+        // Refused BY NAME rather than quietly treated as BYSCORE — a wrong ordering returned as a
+        // success is exactly the fake success this pack forbids. Filed as a todo in the manifest.
+        if (tok === 'bylex')
+            throw new RedisCommandError('ERR twin: ZRANGE BYLEX is not modeled by this twin (upstash.sorted_sets.range_bylex is a filed todo)');
+        if (tok === 'limit') {
+            if (i + 2 >= a.length)
+                throw new RedisCommandError(SYNTAX);
+            limit = { offset: toInt(a[++i]), count: toInt(a[++i]) };
+            continue;
+        }
+        throw new RedisCommandError(SYNTAX);
+    }
+    if (limit && !byScore)
+        throw new RedisCommandError('ERR syntax error, LIMIT is only supported in combination with either BYSCORE or BYLEX');
+    const sorted = sortZSet(asZSet(space.get(a[0])));
+    let selected;
+    if (byScore) {
+        // The REV byscore forms take (max, min); the forward forms take (min, max).
+        const [loRaw, hiRaw] = _rev ? [a[2], a[1]] : [a[1], a[2]];
+        const lo = parseScoreBound(loRaw);
+        const hi = parseScoreBound(hiRaw);
+        selected = sorted.filter(([, s]) => inScoreRange(s, lo, hi));
+        if (_rev)
+            selected = selected.reverse();
+        if (limit)
+            selected = limit.count < 0 ? selected.slice(limit.offset) : selected.slice(limit.offset, limit.offset + limit.count);
+    }
+    else {
+        const ordered = _rev ? [...sorted].reverse() : sorted;
+        const [start, stop] = normalizeRange(toInt(a[1]), toInt(a[2]), ordered.length);
+        selected = start > stop ? [] : ordered.slice(start, stop + 1);
+    }
+    return withScores ? selected.flatMap(([m, s]) => [m, fmtScore(s)]) : selected.map(([m]) => m);
+}
+// ── streams ────────────────────────────────────────────────────────────────────────────────────
+function compareStreamIds(left, right) {
+    const [lms = 0, lseq = 0] = left.split('-').map(Number);
+    const [rms = 0, rseq = 0] = right.split('-').map(Number);
+    if (lms !== rms)
+        return lms < rms ? -1 : 1;
+    return lseq === rseq ? 0 : lseq < rseq ? -1 : 1;
+}
+function parseStreamBound(raw, side) {
+    if (raw === '-')
+        return '0-0';
+    if (raw === '+')
+        return `${Number.MAX_SAFE_INTEGER}-${Number.MAX_SAFE_INTEGER}`;
+    const bare = raw.startsWith('(') ? raw.slice(1) : raw;
+    if (!/^\d+(-\d+)?$/.test(bare))
+        throw new RedisCommandError('ERR Invalid stream ID specified as stream command argument');
+    return bare.includes('-') ? bare : `${bare}-${side === 'min' ? 0 : Number.MAX_SAFE_INTEGER}`;
+}
+function xadd(space, a, nowMs) {
+    let i = 1;
+    let noMkStream = false;
+    for (; i < a.length; i++) {
+        const tok = a[i].toLowerCase();
+        if (tok === 'nomkstream') {
+            noMkStream = true;
+            continue;
+        }
+        // Accepting a trim option and silently NOT trimming would be a fake success, so it is refused.
+        if (tok === 'maxlen' || tok === 'minid')
+            throw new RedisCommandError(`ERR twin: XADD ${tok.toUpperCase()} trimming is not modeled by this twin (upstash.streams.trim is a filed todo)`);
+        break;
+    }
+    const row = space.get(a[0]);
+    if (!row && noMkStream)
+        return null;
+    const entries = asStream(row);
+    const idSpec = a[i];
+    const fields = a.slice(i + 1);
+    if (fields.length === 0 || fields.length % 2 !== 0)
+        throw new RedisCommandError(wrongArity('xadd'));
+    let id;
+    if (idSpec === '*') {
+        // The id's ms part is the REQUEST CLOCK (`occurredAt`), never `Date.now()`. Two entries added
+        // in the same pinned millisecond get sequence 0, 1, 2 … exactly as Redis does — which is what
+        // makes a stream verify reproducible.
+        const [lastMs = 0, lastSeq = 0] = (row?.lastId ?? '0-0').split('-').map(Number);
+        id = nowMs > lastMs ? `${nowMs}-0` : `${lastMs}-${lastSeq + 1}`;
+    }
+    else {
+        id = idSpec.includes('-') ? idSpec : `${idSpec}-0`;
+        if (!/^\d+-\d+$/.test(id))
+            throw new RedisCommandError('ERR Invalid stream ID specified as stream command argument');
+        // Compare against the RETAINED last-id, not merely the last surviving entry: Redis keeps
+        // `last_id` past an XDEL, so an id that was used and then deleted stays refused forever. §9
+        // round 1 found the entries-only comparison re-accepting `5-5` after `XDEL st 5-5`.
+        const top = row?.lastId ?? (entries.length > 0 ? entries[entries.length - 1][0] : '0-0');
+        if (compareStreamIds(id, top) <= 0) {
+            throw new RedisCommandError('ERR The ID specified in XADD is equal or smaller than the target stream top item');
+        }
+    }
+    const pairs = [];
+    for (let j = 0; j < fields.length; j += 2)
+        pairs.push([fields[j], fields[j + 1]]);
+    entries.push([id, pairs]);
+    space.put({ name: a[0], kind: 'stream', v: entries, pexpireAt: row?.pexpireAt ?? null, lastId: id }, 'stream.add');
+    return id;
+}
+// ── the script cache ───────────────────────────────────────────────────────────────────────────
+//
+// Real Redis keeps the EVAL script cache in server memory (a restart or `SCRIPT FLUSH` empties it).
+// This twin persists it in the kernel under its OWN subject type ('script'), so EVALSHA keeps
+// working across a twin restart. Two things follow, and both are deliberate:
+//   • A DISCLOSED divergence from the vendor — strictly more forgiving, never less — which is what
+//     lets a persistent world's rate limiters survive a restart without a NOSCRIPT round trip.
+//   • ZERO collision surface with the keyspace. An earlier draft stored scripts as keys under a
+//     magic ` twin:script:<sha>` prefix and filtered that prefix out of KEYS/SCAN/DBSIZE; a caller
+//     who wrote a key with that exact name (perfectly legal — Redis keys may begin with a space)
+//     had it silently disappear from every listing and could then execute it via EVALSHA. Separate
+//     subject types make that impossible instead of merely filtered.
+function storeScript(space, script) {
+    const sha = luaScriptSha1(script);
+    if (!space.hasScript(sha))
+        space.putScript(sha, script);
+    return sha;
+}
+// ── Lua ↔ Redis value conversion (real Redis's rules — see the Lua module header) ─────────────
+function redisToLua(v) {
+    if (v === null)
+        return false; // nil bulk reply → Lua `false`
+    if (typeof v === 'number' || typeof v === 'string')
+        return v;
+    if (v instanceof RedisStatus) {
+        const t = new LuaTable();
+        t.set('ok', v.value); // status reply → Lua table {ok=…}
+        return t;
+    }
+    return LuaTable.fromArray(v.map(redisToLua));
+}
+function luaToRedis(v) {
+    if (v === null || v === false)
+        return null;
+    if (v === true)
+        return 1; // Lua `true` → integer 1
+    if (typeof v === 'number')
+        return Math.trunc(v); // Lua number → integer, TRUNCATED toward zero
+    if (typeof v === 'string')
+        return v;
+    if (v instanceof LuaTable) {
+        const err = v.get('err');
+        if (typeof err === 'string')
+            throw new RedisCommandError(err);
+        const ok = v.get('ok');
+        if (typeof ok === 'string')
+            return new RedisStatus(ok);
+        const out = [];
+        for (let i = 1;; i++) {
+            const item = v.get(i);
+            if (item === null)
+                break; // an array reply STOPS at the first nil
+            out.push(luaToRedis(item));
+        }
+        return out;
+    }
+    throw new RedisCommandError('ERR twin: script returned a function value, which has no Redis representation');
+}
+/**
+ * Run a Lua script over this twin's real command core, ATOMICALLY.
+ *
+ * `redis.call` re-enters `execOne` on the SAME `KeySpace`, so a script's writes are visible to its
+ * own later reads — which every @upstash/ratelimit script depends on — and there is no second,
+ * script-only implementation of `INCRBY` to drift from the real one. A script that raises part-way
+ * is rolled back to the snapshot taken before it started, which is what "a script is one indivisible
+ * unit" means.
+ */
+function evalScript(space, script, keys, args, readOnly) {
+    const before = space.snapshot();
+    try {
+        const result = runLua(script, {
+            keys,
+            argv: args,
+            call: (callArgs, line) => {
+                const cmd = String(callArgs[0] ?? '').toUpperCase();
+                // Redis's refusal, as EVAL_RO's page prints it (redis.io/docs/latest/commands/eval_ro/): the script by its SHA1
+                // and the line of the call
+                if (readOnly && isWriteCommand(cmd, callArgs.slice(1)))
+                    throw new RedisCommandError(`ERR Error running script (call to ${luaScriptSha1(script)}): @user_script:${line}: @user_script: ${line}: Write commands are not allowed from read-only scripts.`);
+                return redisToLua(execOne(space, callArgs));
+            },
+        });
+        return luaToRedis(result);
+    }
+    catch (e) {
+        space.restore(before); // atomicity: a failed script leaves NOTHING behind
+        if (e instanceof RedisCommandError || e instanceof ReadOnlyError)
+            throw e;
+        if (e instanceof LuaError)
+            throw new RedisCommandError(`ERR Error running script: ${e.message}`);
+        throw e;
+    }
+}
+/**
+ * Execute a whole request's worth of commands against one root, then flush.
+ *
+ * Each element comes back as `{result}` or `{error}` — the exact per-command envelope Upstash's
+ * `/pipeline` and `/multi-exec` endpoints return and the SDK's `Pipeline.exec` destructures.
+ *
+ * RUNTIME ERRORS DO NOT ABORT — not in a pipeline and (LIVE-PROBED, contrary to the intuition that
+ * a "transaction" rolls back) NOT in `/multi-exec` either: Upstash's own docs say "all commands
+ * will be executed. Upstash Redis will not stop the processing of commands. This is to provide same
+ * semantics with Redis when there are errors inside a transaction." A probe of the real service
+ * confirmed a `SET` after a failing `INCR` in a `/multi-exec` batch is applied. Structural faults —
+ * an unavailable command or a bad arity — are QUEUE-time and DO discard the whole batch, but the
+ * caller (`upstash-twin.ts`) rejects those before this function is ever reached.
+ */
+export async function execRedisRun(commands, ctx) {
+    const nowMs = Date.parse(ctx.occurredAt);
+    if (!Number.isFinite(nowMs))
+        throw new RedisCommandError(`ERR twin: unparseable occurredAt '${ctx.occurredAt}'`);
+    const space = new KeySpace(ctx, nowMs);
+    const items = [];
+    for (const argv of commands) {
+        try {
+            items.push({ result: execOne(space, argv) });
+        }
+        catch (e) {
+            if (e instanceof ReadOnlyError)
+                throw e; // surfaces as HTTP 405 for the whole request
+            if (e instanceof RedisCommandError) {
+                items.push({ error: e.message });
+                continue;
+            }
+            throw e;
+        }
+    }
+    const wrote = space.dirty;
+    await flushKeySpace(space);
+    return { items, wrote };
+}