@volter/world-core 3.0.38 → 3.0.40

package/src/redis/engine.ts

@@ -66,7 +66,12 @@ export class RedisStatus {
 export const OK = new RedisStatus('OK');
 
 /** The JSON projection of a RESP reply — what Upstash puts in `{"result": …}`. */
-export type RedisValue = null | number | string | RedisStatus | RedisValue[];
+// Redis integers are signed 64-bit on RESP; JSON clients read them as JSON numbers.
+export class RedisInteger {
+  constructor(readonly integer: string) {}
+}
+const integerReply = (n: bigint): number | RedisInteger => n >= -9007199254740991n && n <= 9007199254740991n ? Number(n) : new RedisInteger(String(n));
+export type RedisValue = null | number | string | RedisStatus | RedisInteger | RedisValue[];
 
 /** A command-level failure. `message` is the vendor's literal error string. Maps to HTTP 400. */
 export class RedisCommandError extends Error {
@@ -111,8 +116,8 @@ export type KeyRow = {
   kind: KeyType;
   /** string → string; list/set → string[]; hash → [f,v][]; zset → [member,score][]; stream → [id,[f,v][]][] */
   v: string | string[] | HashPairs | ZSetPairs | StreamEntries;
-  /** Absolute expiry deadline in epoch ms, or null for "no TTL". */
-  pexpireAt: number | null;
+  /** Exact absolute expiry deadline in epoch ms, persisted as decimal digits, or null for "no TTL". */
+  pexpireAt: string | null;
   /** Stream only: the last id this stream minted, so `*` stays monotonic. */
   lastId?: string;
   /** Stream only: its consumer groups and counters, as the dialect that serves them keeps them (the redis pack's XGROUP). */
@@ -223,6 +228,7 @@ export const SERVED_COMMANDS: Record<string, [number, number]> = {
   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],
+  LPOS: [2, -1], RPOPLPUSH: [2, 2], ZPOPMIN: [1, 2], XTRIM: [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],
 };
@@ -234,7 +240,7 @@ const WRITE_COMMANDS = new Set([
   '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',
+  'RPOPLPUSH', 'ZPOPMIN', 'XTRIM', '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.
@@ -335,7 +341,7 @@ function patchImage(image: KeyspaceImage, changed: readonly TwinResource[], remo
       name,
       kind: rec.kind as KeyType,
       v: rec.v as KeyRow['v'],
-      pexpireAt: typeof rec.pexpire_at === 'number' ? rec.pexpire_at : null,
+      pexpireAt: typeof rec.pexpire_at === 'string' || typeof rec.pexpire_at === 'number' ? String(rec.pexpire_at) : null,
       ...(typeof rec.last_id === 'string' && rec.last_id !== '' ? { lastId: rec.last_id } : {}),
       ...(typeof rec._rev === 'number' ? { _rev: rec._rev } : {}),
       ...(rec.meta !== undefined && rec.meta !== null ? { meta: rec.meta } : {}),
@@ -378,7 +384,7 @@ export class KeySpace {
    */
   private live(row: KeyRow | undefined): KeyRow | undefined {
     if (!row) return undefined;
-    return row.pexpireAt !== null && row.pexpireAt < this.nowMs ? undefined : row;
+    return row.pexpireAt !== null && BigInt(row.pexpireAt) < BigInt(this.nowMs) ? undefined : row;
   }
   all(): KeyRow[] { return [...this.rows.values()].filter((r) => this.live(r) !== undefined); }
   // ── the EVAL script cache ────────────────────────────────────────────────────────────────
@@ -445,7 +451,7 @@ export class KeySpace {
 }
 
 /** One key as a backup holds it: its name, type, value, deadline and a stream's last id. */
-export type KeyImage = { name: string; kind: string; v: unknown; pexpireAt: number | null; lastId?: string };
+export type KeyImage = { name: string; kind: string; v: unknown; pexpireAt: string | null; lastId?: string };
 
 /** 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). */
@@ -535,12 +541,28 @@ export const storeZSet = (pairs: ZSetPairs): StoredZSet => pairs.map(([m, sc]) =
 export const asStream = (row: KeyRow | undefined): StreamEntries => { expectType(row, STREAM); expectShape(row, Array.isArray(row?.v)); return row ? (row.v as StreamEntries).map(([id, f]) => [id, f.map(([field, value]) => [field, value] as [string, string])] as [string, HashPairs]) : []; };
 
 // ── numeric parsing (Redis's exact acceptance rules) ──────────────────────────────────────────
-export function toInt(raw: string): number {
-  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);
+// source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/util.c "Convert a string into a long long."
+export function integerArgument(raw: string, message = NOT_INT, unsigned = false): bigint {
+  // source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/util.c "strtoull() is used instead."
+  if (unsigned) {
+    const canonical = /^(0|[1-9]\d*|-[1-9]\d*)$/.test(raw);
+    if (!canonical && !/^[ \t\r\n\v\f]*[+-]?\d+$/.test(raw)) throw new RedisCommandError(message);
+    const n = BigInt(raw.trim());
+    if (n > 18446744073709551615n || n < -18446744073709551615n || canonical && n < 0n) throw new RedisCommandError(message);
+    return BigInt.asUintN(64, n);
+  }
+  if (!/^(0|[1-9]\d*|-[1-9]\d*)$/.test(raw)) throw new RedisCommandError(message);
+  const n = BigInt(raw); if (n < -9223372036854775808n || n > 9223372036854775807n) throw new RedisCommandError(message);
   return n;
 }
+// Collection positions/counts are bounded by their actual arrays, not by Number.MAX_SAFE_INTEGER.
+export const commandInteger = (raw: string, message = NOT_INT): number => Number(integerArgument(raw, message));
+export const toInt = commandInteger;
+export const unsignedArgument = (raw: string, message: string): bigint => integerArgument(raw, message, true);
+// source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/object.c "value is out of range, must be positive"
+export function positiveInteger(raw: string, message = 'ERR value is out of range, must be positive'): number {
+  const n = integerArgument(raw, message); if (n < 0) throw new RedisCommandError(message); return Number(n);
+}
 export function toFloat(raw: string): number {
   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;
@@ -606,12 +628,13 @@ export function globMatch(pattern: string, subject: string): boolean {
 }
 
 // ── TTL option parsing, shared by SET and GETEX ────────────────────────────────────────────────
-function ttlFromToken(token: string, value: string, nowMs: number, cmd: string): number {
-  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
+function ttlFromToken(token: string, value: string, nowMs: number, cmd: string): string {
+  const n = integerArgument(value);
+  const millis = token === 'ex' || token === 'exat' ? n * 1000n : n;
+  const at = token === 'ex' || token === 'px' ? BigInt(Math.trunc(nowMs)) + millis : millis;
+  // source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/t_string.c "Overflow detected."
+  if (n <= 0n || millis > 9223372036854775807n || at > 9223372036854775807n) throw new RedisCommandError(`ERR invalid expire time in '${cmd}' command`);
+  return String(at);
 }
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────
@@ -630,6 +653,46 @@ export function execOne(space: KeySpace, argv: string[]): RedisValue {
 
   switch (name) {
     // ── connection / server ──────────────────────────────────────────────────────────────────
+    // https://redis.io/docs/latest/commands/rpoplpush/: atomically moves the last element to the destination's head.
+    case 'RPOPLPUSH': {
+      const sourceRow = space.get(a[0]!); const source = asList(sourceRow); asList(space.get(a[1]!));
+      const value = source.pop(); if (value === undefined) return null;
+      // source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/t_list.c "listTypePush(dstobj,value,where);"
+      // A rotation rewrites the existing list, including a singleton, without deleting its key or expiry.
+      if (a[0] === a[1]) { source.unshift(value); space.put({ ...sourceRow!, v: source }, 'list.move'); return value; }
+      if (source.length) space.put({ ...space.get(a[0]!)!, v: source }, 'list.move'); else space.remove(a[0]!, 'list.move');
+      const dest = space.get(a[1]!); const values = asList(dest); values.unshift(value);
+      space.put({ name: a[1]!, kind: 'list', v: values, pexpireAt: dest?.pexpireAt ?? null }, 'list.move'); return value;
+    }
+    // https://redis.io/docs/latest/commands/lpos/: rank, count and maxlen apply to matching positions.
+    case 'LPOS': {
+      const values = asList(space.get(a[0]!)); let rank = 1, count: number | undefined, max = values.length;
+      // source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/t_list.c "COUNT can't be negative"
+      for (let i = 2; i < a.length; i += 2) {
+        const option = a[i]!.toUpperCase(); if (!['RANK', 'COUNT', 'MAXLEN'].includes(option) || i + 1 >= a.length) throw new RedisCommandError(SYNTAX);
+        let value: number; try { value = commandInteger(a[i + 1]!); } catch (error) { if (option === 'RANK') throw error; throw new RedisCommandError(`ERR ${option} can't be negative`); }
+        if (option === 'RANK') { if (a[i + 1] === '-9223372036854775808') throw new RedisCommandError('ERR value is out of range, value must between -9223372036854775807 and 9223372036854775807'); if (value === 0) throw new RedisCommandError("ERR RANK can't be zero: use 1 to start from the first match, 2 from the second ... or use negative to start from the end of the list"); rank = value; }
+        else { if (value < 0) throw new RedisCommandError(`ERR ${option} can't be negative`); if (option === 'COUNT') count = value; else max = value || values.length; }
+      }
+      const matches = Array.from({ length: values.length }, (_, i) => i); if (rank < 0) matches.reverse();
+      const hits = matches.slice(0, max).filter((i) => values[i] === a[1]).slice(Math.abs(rank) - 1);
+      return count === undefined ? hits[0] ?? null : hits.slice(0, count === 0 ? undefined : count);
+    }
+    // https://redis.io/docs/latest/commands/zpopmin/: lowest score first; ties by member.
+    case 'ZPOPMIN': {
+      const row = space.get(a[0]!); const pairs = sortZSet(asZSet(row)); let count = 1;
+      // source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/object.c "value is out of range, must be positive"
+      try { if (a[1] !== undefined) count = commandInteger(a[1]); } catch { throw new RedisCommandError('ERR value is out of range, must be positive'); }
+      if (count < 0) throw new RedisCommandError('ERR value is out of range, must be positive');
+      const popped = pairs.splice(0, count);
+      if (popped.length) { if (pairs.length) space.put({ ...row!, v: storeZSet(sortZSet(pairs)) }, 'zset.pop'); else space.remove(a[0]!, 'zset.pop'); }
+      return popped.flatMap(([m, score]) => [m, fmtScore(score)]);
+    }
+    // https://redis.io/docs/latest/commands/xtrim/: exact trimming also satisfies the approximate upper bound.
+    case 'XTRIM': {
+      const row = space.get(a[0]!); const entries = asStream(row); const spec = trimSpec(a, 1); if (spec.next !== a.length) throw new RedisCommandError(SYNTAX);
+      const kept = trimEntries(entries, spec); if (row && kept.length !== entries.length) space.put({ ...row, v: kept }, 'stream.trim'); return entries.length - kept.length;
+    }
     case 'PING': return a.length === 0 ? new RedisStatus('PONG') : a[0]!;
     case 'ECHO': return a[0]!;
     case 'DBSIZE': return visibleKeys(space).length;
@@ -646,8 +709,8 @@ export function execOne(space: KeySpace, argv: string[]): RedisValue {
       return keys.length === 0 ? null : keys[0]!;
     }
     case 'SCAN': {
-      const cursor = toInt(a[0]!);
-      if (cursor < 0) throw new RedisCommandError('ERR invalid cursor');
+      // SCAN uses Redis's unsigned cursor parser, unlike signed COUNT.
+      const cursor = Number(unsignedArgument(a[0]!, 'ERR invalid cursor'));
       let match: string | null = null;
       let count = 10;
       let typeFilter: string | null = null;
@@ -694,36 +757,36 @@ export function execOne(space: KeySpace, argv: string[]): RedisValue {
     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]!);
+      const n = integerArgument(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');
+      // source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/expire.c "overflow by either unit conversion or basetime addition."
+      const millis = name === 'EXPIRE' || name === 'EXPIREAT' ? n * 1000n : n;
+      const deadline = name === 'EXPIRE' || name === 'PEXPIRE' ? BigInt(Math.trunc(nowMs)) + millis : millis;
+      if (millis < -9223372036854775808n || millis > 9223372036854775807n || deadline > 9223372036854775807n) throw new RedisCommandError(`ERR invalid expire time in '${name.toLowerCase()}' command`);
       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;
+      if (opts.has('GT') && (row.pexpireAt === null || deadline <= BigInt(row.pexpireAt))) return 0;
+      if (opts.has('LT') && row.pexpireAt !== null && deadline >= BigInt(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');
+      if (deadline <= BigInt(nowMs)) { space.remove(a[0]!, 'key.expire_now'); return 1; }
+      space.put({ ...row, pexpireAt: String(deadline) }, '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;
+      const remainingMs = BigInt(row.pexpireAt) - BigInt(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;
+      return integerReply(name === 'TTL' ? (remainingMs + 500n) / 1000n : remainingMs);
     }
     case 'PERSIST': {
       const row = space.get(a[0]!);
@@ -731,6 +794,7 @@ export function execOne(space: KeySpace, argv: string[]): RedisValue {
       space.put({ ...row, pexpireAt: null }, 'key.persist');
       return 1;
     }
+    // source: https://redis.io/docs/latest/commands/expire/ "the associated time to live is transferred to the new key name"
     case 'RENAME': case 'RENAMENX': {
       const row = space.get(a[0]!);
       if (!row) throw new RedisCommandError(NO_SUCH_KEY);
@@ -749,6 +813,7 @@ export function execOne(space: KeySpace, argv: string[]): RedisValue {
       if (row) space.remove(a[0]!, 'string.getdel');
       return v === undefined ? null : v;
     }
+    // source: https://redis.io/docs/latest/commands/getset/ "Any previous time to live associated with the key is discarded"
     case 'GETSET': {
       const old = asString(space.get(a[0]!));
       space.put({ name: a[0]!, kind: 'string', v: a[1]!, pexpireAt: null }, 'string.getset');
@@ -772,7 +837,7 @@ export function execOne(space: KeySpace, argv: string[]): RedisValue {
       let get = false;
       let keepTtl = false;
       let expiryFlag: string | null = null;
-      let pexpireAt: number | null = null;
+      let pexpireAt: string | null = 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
@@ -801,6 +866,7 @@ export function execOne(space: KeySpace, argv: string[]): RedisValue {
       // 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;
+      // source: https://redis.io/docs/latest/commands/set/ "Retain the time to live associated with the key"
       space.put({ name: key, kind: 'string', v: value, pexpireAt: keepTtl ? (existing?.pexpireAt ?? null) : pexpireAt }, 'string.set');
       return get ? (old ?? null) : OK;
     }
@@ -810,9 +876,8 @@ export function execOne(space: KeySpace, argv: string[]): RedisValue {
       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');
+      const pexpireAt = ttlFromToken(name === 'SETEX' ? 'ex' : 'px', a[1]!, nowMs, name.toLowerCase());
+      space.put({ name: a[0]!, kind: 'string', v: a[2]!, pexpireAt }, 'string.setex');
       return OK;
     }
     case 'MGET': return a.map((k) => { const r = space.get(k); return r && r.kind === 'string' ? (r.v as string) : null; });
@@ -830,16 +895,16 @@ export function execOne(space: KeySpace, argv: string[]): RedisValue {
     }
     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 by = name === 'INCR' ? 1n : name === 'DECR' ? -1n : integerArgument(a[1]!) * (name === 'DECRBY' ? -1n : 1n);
       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');
+      const next = (current === undefined ? 0n : integerArgument(current)) + by;
+      if (next < -9223372036854775808n || next > 9223372036854775807n) 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;
+      return integerReply(next);
     }
     case 'INCRBYFLOAT': {
       const row = space.get(a[0]!);
@@ -894,13 +959,14 @@ export function execOne(space: KeySpace, argv: string[]): RedisValue {
       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]!);
-      if (!isFloat && !Number.isSafeInteger(next)) throw new RedisCommandError('ERR increment or decrement would overflow');
-      const text = isFloat ? fmtScore(next) : String(next);
+      const by = isFloat ? toFloat(a[2]!) : integerArgument(a[2]!);
+      const base = current === undefined ? (isFloat ? 0 : 0n) : isFloat ? toFloat(current) : integerArgument(current, 'ERR hash value is not an integer');
+      const next = isFloat ? guardFloatResult((base as number) + (by as number)) : (base as bigint) + (by as bigint);
+      if (!isFloat && ((next as bigint) < -9223372036854775808n || (next as bigint) > 9223372036854775807n)) throw new RedisCommandError('ERR increment or decrement would overflow');
+      const text = isFloat ? fmtScore(next as number) : 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;
+      return isFloat ? text : integerReply(next as bigint);
     }
 
     // ── sets ─────────────────────────────────────────────────────────────────────────────────
@@ -957,10 +1023,9 @@ export function execOne(space: KeySpace, argv: string[]): RedisValue {
       return items.length;
     }
     case 'LPOP': case 'RPOP': {
+      const count = a.length >= 2 ? positiveInteger(a[1]!) : null;
       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();
@@ -989,8 +1054,8 @@ export function execOne(space: KeySpace, argv: string[]): RedisValue {
     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);
+      if (!row) return OK;
       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');
@@ -1126,6 +1191,10 @@ export function execOne(space: KeySpace, argv: string[]): RedisValue {
       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': {
+      // source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/eval.c "Get the number of arguments that are keys"
+      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");
       const bySha = name.startsWith('EVALSHA');
       let script: string;
       if (bySha) {
@@ -1144,9 +1213,6 @@ export function execOne(space: KeySpace, argv: string[]): RedisValue {
         // 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'));
     }
 
@@ -1280,7 +1346,7 @@ export function zrange(space: KeySpace, name: string, a: string[]): RedisValue {
     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);
+    if (limit) selected = limit.offset < 0 ? [] : 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);
@@ -1291,56 +1357,94 @@ export function zrange(space: KeySpace, name: string, a: string[]): RedisValue {
 
 // ── streams ────────────────────────────────────────────────────────────────────────────────────
 export function compareStreamIds(left: string, right: string): number {
-  const [lms = 0, lseq = 0] = left.split('-').map(Number);
-  const [rms = 0, rseq = 0] = right.split('-').map(Number);
+  const [lms = 0n, lseq = 0n] = left.split('-').map(BigInt);
+  const [rms = 0n, rseq = 0n] = right.split('-').map(BigInt);
   if (lms !== rms) return lms < rms ? -1 : 1;
   return lseq === rseq ? 0 : lseq < rseq ? -1 : 1;
 }
 export function parseStreamBound(raw: string, side: 'min' | 'max'): string {
   if (raw === '-') return '0-0';
-  if (raw === '+') return `${Number.MAX_SAFE_INTEGER}-${Number.MAX_SAFE_INTEGER}`;
+  if (raw === '+') return '18446744073709551615-18446744073709551615';
   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}`;
+  return bare.includes('-') ? bare : `${bare}-${side === 'min' ? '0' : '18446744073709551615'}`;
+}
+// source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/util.c "strtoull() is used instead."
+// Stream components are uint64; Redis's fallback also accepts a leading plus or zeroes.
+function streamArgument(raw: string, wildcard = false): string {
+  const at = raw.indexOf('-'); const ms = at < 0 ? raw : raw.slice(0, at), seq = at < 0 ? '0' : raw.slice(at + 1);
+  const part = (v: string): string => String(unsignedArgument(v, 'ERR Invalid stream ID specified as stream command argument'));
+  return `${part(ms)}-${wildcard && seq === '*' ? '*' : part(seq)}`;
+}
+// source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/t_stream.c "The LIMIT argument must be >= 0."
+// MAXLEN/MINID use a strict unsigned threshold; LIMIT is allowed only with approximate trimming.
+function trimSpec(a: string[], start: number): { strategy: string; threshold: string; limit: number; next: number } {
+  let i = start; const strategy = a[i++]!.toUpperCase(); if (!['MAXLEN', 'MINID'].includes(strategy)) throw new RedisCommandError(SYNTAX);
+  const approximate = a[i] === '~'; if (['~', '='].includes(a[i] ?? '')) i++;
+  if (i >= a.length) throw new RedisCommandError(SYNTAX); let threshold = a[i++]!;
+  if (strategy === 'MAXLEN') { if (commandInteger(threshold) < 0) throw new RedisCommandError('ERR The MAXLEN argument must be >= 0.'); }
+  else threshold = streamArgument(threshold);
+  let limit = Infinity;
+  if (a[i]?.toUpperCase() === 'LIMIT') {
+    if (i + 1 >= a.length) throw new RedisCommandError(SYNTAX); i++; limit = commandInteger(a[i++]!);
+    if (limit < 0) throw new RedisCommandError('ERR The LIMIT argument must be >= 0.');
+    // source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/t_stream.c "syntax error, LIMIT cannot be used without the special ~ option"
+    if (!approximate) throw new RedisCommandError('ERR syntax error, LIMIT cannot be used without the special ~ option');
+    if (limit === 0) limit = Infinity;
+  }
+  return { strategy, threshold, limit, next: i };
+}
+function trimEntries(entries: StreamEntries, spec: ReturnType<typeof trimSpec>): StreamEntries {
+  const remove = spec.strategy === 'MAXLEN' ? Math.max(0, entries.length - Number(spec.threshold)) : entries.filter(([id]) => compareStreamIds(id, parseStreamBound(spec.threshold, 'min')) < 0).length;
+  return entries.slice(Math.min(remove, spec.limit));
 }
 function xadd(space: KeySpace, a: string[], nowMs: number): RedisValue {
   let i = 1;
   let noMkStream = false;
+  let trim: ReturnType<typeof trimSpec> | undefined;
   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(space.ctx.dialect.unmodeled(`XADD ${tok.toUpperCase()} trimming`));
+    if (tok === 'maxlen' || tok === 'minid') { if (trim) throw new RedisCommandError('ERR syntax error, MAXLEN and MINID options at the same time are not compatible'); trim = trimSpec(a, i); i = trim.next - 1; continue; }
     break;
   }
   const row = space.get(a[0]!);
   if (!row && noMkStream) return null;
   const entries = asStream(row);
-  const idSpec = a[i]!;
+  if (row?.lastId === '18446744073709551615-18446744073709551615') throw new RedisCommandError('ERR The stream has exhausted the last possible ID, unable to add more items');
+  const rawId = a[i]; if (rawId === undefined) throw new RedisCommandError(wrongArity('xadd'));
   const fields = a.slice(i + 1);
   if (fields.length === 0 || fields.length % 2 !== 0) throw new RedisCommandError(wrongArity('xadd'));
+  const idSpec = rawId === '*' ? rawId : streamArgument(rawId, true);
   let id: string;
   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}`;
+    const [lastMs = 0n, lastSeq = 0n] = (row?.lastId ?? '0-0').split('-').map(BigInt);
+    id = BigInt(nowMs) > lastMs ? `${nowMs}-0` : `${lastMs}-${lastSeq + 1n}`;
+  } else if (/^(0|[1-9]\d*)-\*$/.test(idSpec) && BigInt(idSpec.split('-')[0]!) <= 18446744073709551615n) {
+    const ms = BigInt(idSpec.split('-')[0]!); const [lastMs = 0n, lastSeq = 0n] = (row?.lastId ?? '0-0').split('-').map(BigInt);
+    if (ms < lastMs) throw new RedisCommandError('ERR The ID specified in XADD is equal or smaller than the target stream top item');
+    id = `${ms}-${ms === lastMs ? lastSeq + 1n : 0n}`;
   } else {
     id = idSpec.includes('-') ? idSpec : `${idSpec}-0`;
-    if (!/^\d+-\d+$/.test(id)) throw new RedisCommandError('ERR Invalid stream ID specified as stream command argument');
+    if (!/^(0|[1-9]\d*)-(0|[1-9]\d*)$/.test(id) || id.split('-').some((v) => BigInt(v) > 18446744073709551615n)) 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`.
+    if (id === '0-0') throw new RedisCommandError('ERR The ID specified in XADD must be greater than 0-0');
     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');
     }
   }
+  if (id === '0-0') throw new RedisCommandError('ERR The ID specified in XADD must be greater than 0-0');
+  if (id.split('-').some((v) => BigInt(v) > 18446744073709551615n)) throw new RedisCommandError('ERR The stream has exhausted the last possible ID, unable to add more items');
   const pairs: HashPairs = [];
   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');
+  space.put({ name: a[0]!, kind: STREAM, v: trim ? trimEntries(entries, trim) : entries, pexpireAt: row?.pexpireAt ?? null, lastId: id }, 'stream.add');
   return id;
 }
 
@@ -1366,6 +1470,7 @@ function storeScript(space: KeySpace, script: string): string {
 function redisToLua(v: RedisValue): LuaValue {
   if (v === null) return false;                        // nil bulk reply → Lua `false`
   if (typeof v === 'number' || typeof v === 'string') return v;
+  if (v instanceof RedisInteger) return Number(v.integer);
   if (v instanceof RedisStatus) {
     const t = new LuaTable();
     t.set('ok', v.value);                              // status reply → Lua table {ok=…}
@@ -1447,7 +1552,7 @@ export type RunItem = { result: RedisValue } | { error: string };
  * 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: string[][], ctx: RedisContext): Promise<{ items: RunItem[]; wrote: boolean }> {
+export async function execRedisRun(commands: string[][], ctx: RedisContext): Promise<{ items: RunItem[]; wrote: boolean; instant: number }> {
   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);
@@ -1463,6 +1568,6 @@ export async function execRedisRun(commands: string[][], ctx: RedisContext): Pro
   }
   const wrote = space.dirty;
   await (space.ctx.dialect.storage?.flush(space) ?? flushKeySpace(space));
-  return { items, wrote };
+  return { items, wrote, instant: nowMs };
 }
 

package/src/redis/frames.ts

@@ -0,0 +1,53 @@
+import { exactInteger } from '../exact-json.ts';
+// RESP frame parsing and RESP2 replies, shared by the Redis stream and journey tooling.
+// https://redis.io/docs/latest/develop/reference/protocol-spec/
+import { RedisInteger, RedisStatus, type RedisValue } from './engine.ts';
+export const binaryText = (b: Uint8Array): string => Array.from(b, (n) => String.fromCharCode(n)).join('');
+export const binaryBytes = (s: string): Uint8Array => Uint8Array.from(s, (c) => c.charCodeAt(0));
+export type Frame = { value: any; end: number; error?: boolean; type: string };
+export function readResp(s: string, start = 0): Frame | undefined {
+  const e = s.indexOf('\r\n', start); if (e < 0) return undefined;
+  const tag = s[start]!, head = s.slice(start + 1, e); let at = e + 2;
+  if (tag === '+' || tag === '-') return { type: tag, value: head, end: at, ...(tag === '-' ? { error: true } : {}) };
+  if (tag === ':') return { type: tag, value: exactInteger(head), end: at };
+  if (tag === '_') return { type: tag, value: null, end: at };
+  if (tag === '#') return { type: tag, value: head === 't', end: at };
+  if (tag === ',') return { type: tag, value: Number(head), end: at };
+  const n = Number(head); if (!Number.isSafeInteger(n) || n < -1) throw new Error('Protocol error: invalid length');
+  if (tag === '$' || tag === '!') { if (n === -1) return { type: tag, value: null, end: at }; if (s.length < at + n + 2) return undefined; if (s.slice(at + n, at + n + 2) !== '\r\n') throw new Error('Protocol error: invalid bulk terminator'); return { type: tag, value: s.slice(at, at + n), end: at + n + 2, ...(tag === '!' ? { error: true } : {}) }; }
+  if (['*', '%', '~', '>'].includes(tag)) { if (n === -1) return { type: tag, value: null, end: at }; const out: any[] = []; for (let i = 0; i < n * (tag === '%' ? 2 : 1); i++) { const f = readResp(s, at); if (!f) return undefined; out.push(f.error ? { error: f.value } : f.value); at = f.end; } return { type: tag, value: tag === '%' ? Object.fromEntries(Array.from({ length: n }, (_, i) => [out[i * 2], out[i * 2 + 1]])) : out, end: at }; }
+  throw new Error('Protocol error: invalid type');
+}
+export function respReply(value: RedisValue | { error: string } | Record<string, any>): string {
+  if (value instanceof RedisInteger || typeof value === 'object' && value !== null && 'integer' in value) return `:${value.integer}\r\n`;
+  if (value === null) return '$-1\r\n';
+  if (value instanceof RedisStatus || typeof value === 'object' && !Array.isArray(value) && 'value' in value) return `+${String(value.value).replace(/[\r\n]/g, ' ')}\r\n`;
+  if (typeof value === 'object' && !Array.isArray(value) && 'error' in value) return `-${String(value.error).trim().replace(/[\r\n]/g, ' ')}\r\n`;
+  if (Array.isArray(value)) return `*${value.length}\r\n${value.map((x) => respReply(x)).join('')}`;
+  if (typeof value === 'object') return respReply(Object.entries(value).flat());
+  if (typeof value === 'number') return Number.isInteger(value) ? `:${value}\r\n` : respReply(String(value));
+  const s = String(value); return `$${s.length}\r\n${s}\r\n`;
+}
+export const commandFrame = (command: string[]): Uint8Array => {
+  const args = command.map((s) => binaryText(new TextEncoder().encode(s)));
+  return binaryBytes(`*${args.length}\r\n${args.map((s) => `$${s.length}\r\n${s}\r\n`).join('')}`);
+};
+export function inlineCommand(line: string): string[] {
+  const words: string[] = []; let word = '', quote = '', active = false;
+  for (let i = 0; i < line.length; i++) { const c = line[i]!;
+    if (c === '\\' && quote) { const next = line[++i]!; if (next === 'x' && /^[0-9a-f]{2}$/i.test(line.slice(i + 1, i + 3))) { word += String.fromCharCode(parseInt(line.slice(i + 1, i + 3), 16)); i += 2; } else word += ({ n: '\n', r: '\r', t: '\t' } as any)[next] ?? next; }
+    else if (quote) { if (c === quote) quote = ''; else word += c; }
+    else if (c === '"' || c === "'") { quote = c; active = true; }
+    else if (/\s/.test(c)) { if (active) { words.push(word); word = ''; active = false; } }
+    else { word += c; active = true; }
+  }
+  if (quote) throw new Error('Protocol error: unbalanced quotes in request'); if (active) words.push(word); return words;
+}
+
+/** Carry RESP integer/status tags across an internal JSON request without losing int64 bytes. */
+export function wireValue(value: any): any {
+  if (value instanceof RedisInteger) return { integer: value.integer };
+  if (Array.isArray(value)) return value.map(wireValue);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, wireValue(item)]));
+  return value;
+}

package/src/redis/index.ts

@@ -4,3 +4,9 @@
 // docs/contributing/architecture.md, "Other wires: lanes, headers and line protocols".
 export * from './engine.ts';
 export * from './lua.ts';
+export * from './resp2.ts';
+export * from './json.ts';
+export * from './member-storage.ts';
+export * from './lua-libs.ts';
+export * from './frames.ts';
+export * from './stream.ts';

package/src/redis/json.ts

@@ -0,0 +1,13 @@
+// JSON envelopes for Redis replies. Integer replies carry decimal digits until the wire writes them;
+// converting them to a Number here would round values outside JavaScript's safe integer range.
+import { RedisInteger } from './engine.ts';
+
+/** Serialize a JSON reply envelope, including nested exact Redis integer numeric tokens. */
+export function jsonReply(value: unknown): string {
+  if (value instanceof RedisInteger) return value.integer;
+  if (Array.isArray(value)) return `[${value.map((item) => jsonReply(item)).join(',')}]`;
+  if (value !== null && typeof value === 'object') {
+    return `{${Object.entries(value).filter(([, item]) => item !== undefined).map(([key, item]) => `${JSON.stringify(key)}:${jsonReply(item)}`).join(',')}}`;
+  }
+  return JSON.stringify(value) ?? 'null';
+}