experimental-a2 0.4.0 → 0.5.0

package/src/store-redis-core.ts

@@ -0,0 +1,1494 @@
+/**
+ * The shared Redis store core — every operation except `stream` and
+ * `close`, expressed over one injected `call` function so both
+ * transports reuse it: `store-redis` (Redis protocol via `ioredis`) and
+ * `store-redis-http` (provider REST APIs).
+ *
+ * The stream IS the store: each event is a stream entry whose ID is its
+ * dense a2 index (`${index}-0`), so `XRANGE` is the catch-up read.
+ * Mutable drain/failure bookkeeping lives in a side hash (stream
+ * entries are immutable); every write path is one atomic Lua script.
+ * The conformance suite in test/conformance is the executable
+ * contract, run against a real spawned `redis-server`.
+ *
+ * Timestamps and claim expiry come from the injected clock so tests
+ * can time-travel against a real server. Cluster mode is out: the
+ * atomic scripts span keys.
+ */
+
+import type { PresencePatch } from './contract.ts'
+import { A2Error } from './errors.ts'
+import { idempotentReplay } from './idempotent-replay.ts'
+import { nullProtoRecord } from './internal.ts'
+import { decodeReturnedEventIds } from './store-codec.ts'
+import type {
+  A2Store,
+  A2StoreInspection,
+  Clock,
+  CompleteAttemptResult,
+  Event,
+  EventCause,
+  IdSource,
+  StoreClaimAvailableResult,
+  PresenceRow,
+  StoredEvent,
+} from './store.ts'
+
+/** Issues any Redis command; the seam both transports implement. */
+export type RedisCall = (
+  command: string,
+  ...args: Array<string | number>
+) => Promise<unknown>
+
+export type RedisStoreCoreOptions = {
+  call: RedisCall
+  clock: Clock
+  ids: IdSource
+  keyPrefix: string
+  /**
+   * Disposable wake-up fired after a write appends new events to a
+   * watched session — `count` is the session's new event count. The
+   * watched check runs inside the write script, so unwatched sessions
+   * cost no wake-up command at all. Losing one is harmless: live
+   * feeds re-read on a safety cadence, so notifications only affect
+   * latency, never delivery.
+   */
+  notify?: (sessionId: string, count: number) => void
+}
+
+export type RedisStoreCore = Omit<
+  A2Store,
+  'stream' | 'inspect' | 'presence'
+> & {
+  inspect: A2StoreInspection
+  /**
+   * The storage half of the presence capability, shared by both
+   * transports. `set` returns the applied patch — null when every
+   * field lost the LWW race — so a push-capable transport broadcasts
+   * exactly what `read` now reflects; delivery is its business.
+   */
+  presence: {
+    set(
+      ns: string,
+      participant: string,
+      values: Record<string, unknown | null>,
+      meta: { seen: number; at: Date; ttlMs: number },
+    ): Promise<PresencePatch | null>
+    read(ns: string): Promise<PresenceRow[]>
+  }
+  /** XRANGE + meta merge — the full-row catch-up read. */
+  readRange(
+    sessionId: string,
+    afterIndex: number,
+    throughIndex?: number,
+  ): Promise<StoredEvent[]>
+  /** XRANGE only — the light catch-up read live feeds use. */
+  readEvents(sessionId: string, afterIndex: number): Promise<Event[]>
+  /**
+   * Declare the session watched for `ttlMs` — writes publish wake-ups
+   * only while this presence marker lives. Live feeds refresh it
+   * ahead of expiry; an expired marker degrades latency to the safety
+   * cadence, never delivery.
+   */
+  markWatched(sessionId: string, ttlMs: number): Promise<void>
+}
+
+const READ_PAGE_SIZE = 256
+
+// ── Lua scripts (each runs atomically) ───────────────────────────────
+
+/**
+ * KEYS: store stream, counter, global id hash, session index, metadata,
+ * pending, ready, watched.
+ * ARGV: sessionId, nowMs, n, then per event:
+ * id, type, payloadJson, causeJson, lane, settled.
+ * Returns ['empty', hasPending] | ['ok', firstIndex, hasPending, watched] |
+ * ['dup', hasPending, ...indexes] | ['partial', count] |
+ * ['foreign', eventId] | ['no_parent', idx] | ['superseded', idx].
+ */
+const APPEND_LUA = `
+local function lane_field(lane, suffix)
+  return '__lane:' .. tostring(string.len(lane)) .. ':' .. lane .. ':' .. suffix
+end
+local function enqueue(field, idx, lane)
+  redis.call('ZADD', KEYS[6], idx, field)
+  if lane == '' then
+    redis.call('ZADD', KEYS[7], idx, field)
+    return
+  end
+  local tail_key = lane_field(lane, 'tail')
+  local tail = redis.call('HGET', KEYS[5], tail_key)
+  if tail then
+    redis.call('HSET', KEYS[5], tail .. ':next', field)
+  else
+    redis.call('HSET', KEYS[5], lane_field(lane, 'head'), field)
+    redis.call('ZADD', KEYS[7], idx, field)
+  end
+  redis.call('HSET', KEYS[5], tail_key, field)
+end
+local n = tonumber(ARGV[3])
+local base = tonumber(redis.call('GET', KEYS[2]) or '0')
+local has_pending = redis.call('ZCARD', KEYS[6]) > 0 and '1' or '0'
+if n == 0 then return { 'empty', has_pending } end
+local dups = {}
+for i = 1, n do
+  local id = ARGV[3 + (i - 1) * 6 + 1]
+  local existing = redis.call('HGET', KEYS[3], id)
+  if existing then
+    local rec = cjson.decode(existing)
+    if rec[1] ~= ARGV[1] then return { 'foreign', id } end
+    dups[#dups + 1] = tostring(rec[2])
+  end
+end
+if #dups == n then
+  local res = { 'dup', has_pending }
+  for i = 1, #dups do res[#res + 1] = dups[i] end
+  return res
+end
+if #dups > 0 then return { 'partial', tostring(#dups) } end
+for i = 1, n do
+  local cause = ARGV[3 + (i - 1) * 6 + 4]
+  if cause ~= '' then
+    local parsed = cjson.decode(cause)
+    local pidx = tonumber(parsed.index)
+    if pidx < 1 or pidx > base then
+      return { 'no_parent', tostring(parsed.index) }
+    end
+    local field = tostring(pidx)
+    local dispatches = tonumber(redis.call('HGET', KEYS[5], field .. ':d') or '0')
+    if dispatches ~= tonumber(parsed.attempt) or
+       redis.call('HEXISTS', KEYS[5], field .. ':f') == 1 then
+      return { 'superseded', field }
+    end
+  end
+end
+for i = 1, n do
+  local id = ARGV[3 + (i - 1) * 6 + 1]
+  local typ = ARGV[3 + (i - 1) * 6 + 2]
+  local payload = ARGV[3 + (i - 1) * 6 + 3]
+  local cause = ARGV[3 + (i - 1) * 6 + 4]
+  local lane = ARGV[3 + (i - 1) * 6 + 5]
+  local settled = ARGV[3 + (i - 1) * 6 + 6]
+  local idx = base + i
+  redis.call('XADD', KEYS[1], tostring(idx) .. '-0',
+    'id', id, 'type', typ, 'payload', payload, 'created_at', ARGV[2],
+    'cause', cause, 'lane', lane)
+  redis.call('HSET', KEYS[3], id, cjson.encode({ ARGV[1], idx }))
+  redis.call('HSET', KEYS[5], tostring(idx) .. ':l', lane)
+  if settled == '1' then
+    redis.call('HSET', KEYS[5], tostring(idx) .. ':p', ARGV[2])
+  else
+    enqueue(tostring(idx), idx, lane)
+  end
+end
+redis.call('SET', KEYS[2], tostring(base + n))
+redis.call('ZADD', KEYS[4], 0, ARGV[1])
+has_pending = redis.call('ZCARD', KEYS[6]) > 0 and '1' or '0'
+return { 'ok', tostring(base + 1), has_pending,
+  tostring(redis.call('EXISTS', KEYS[8])) }
+`
+
+/** KEYS: counter, meta, pending, ready. ARGV: idx, attempt, error, maxFailures, nowMs. */
+const FAIL_ATTEMPT_LUA = `
+local function lane_field(lane, suffix)
+  return '__lane:' .. tostring(string.len(lane)) .. ':' .. lane .. ':' .. suffix
+end
+local function settle(field)
+  redis.call('ZREM', KEYS[3], field)
+  redis.call('ZREM', KEYS[4], field)
+  local lane = redis.call('HGET', KEYS[2], field .. ':l') or ''
+  if lane == '' then return end
+  local head_key = lane_field(lane, 'head')
+  if redis.call('HGET', KEYS[2], head_key) ~= field then return end
+  local next_field = redis.call('HGET', KEYS[2], field .. ':next')
+  while next_field and redis.call('HEXISTS', KEYS[2], next_field .. ':p') == 1 do
+    next_field = redis.call('HGET', KEYS[2], next_field .. ':next')
+  end
+  if next_field then
+    redis.call('HSET', KEYS[2], head_key, next_field)
+    if redis.call('HEXISTS', KEYS[2], next_field .. ':f') == 0 then
+      redis.call('ZADD', KEYS[4], tonumber(next_field), next_field)
+    end
+  else
+    redis.call('HDEL', KEYS[2], head_key, lane_field(lane, 'tail'))
+  end
+end
+local idx = tonumber(ARGV[1])
+if idx < 1 or idx > tonumber(redis.call('GET', KEYS[1]) or '0') then
+  return { 'missing', '0' }
+end
+local field = ARGV[1]
+local failures = tonumber(redis.call('HGET', KEYS[2], field .. ':a') or '0')
+local dispatches = tonumber(redis.call('HGET', KEYS[2], field .. ':d') or '0')
+if redis.call('HEXISTS', KEYS[2], field .. ':p') == 1 or dispatches ~= tonumber(ARGV[2]) then
+  return { 'superseded', tostring(failures) }
+end
+if redis.call('HEXISTS', KEYS[2], field .. ':f') == 1 then
+  return { 'dead_lettered', tostring(failures) }
+end
+if redis.call('HEXISTS', KEYS[2], field .. ':lfa') == 1 and
+   tonumber(redis.call('HGET', KEYS[2], field .. ':lfa')) == tonumber(ARGV[2]) and
+   redis.call('HEXISTS', KEYS[2], field .. ':ch') == 0 then
+  return { 'failed', tostring(failures) }
+end
+if redis.call('HEXISTS', KEYS[2], field .. ':ch') == 0 then
+  return { 'superseded', tostring(failures) }
+end
+failures = redis.call('HINCRBY', KEYS[2], field .. ':a', 1)
+redis.call('HSET', KEYS[2],
+  field .. ':e', ARGV[3],
+  field .. ':lf', ARGV[5],
+  field .. ':lfa', ARGV[2])
+redis.call('HDEL', KEYS[2], field .. ':ch', field .. ':ce')
+if failures >= tonumber(ARGV[4]) then
+  redis.call('HSET', KEYS[2], field .. ':f', ARGV[5])
+  redis.call('ZREM', KEYS[4], field)
+  return { 'dead_lettered', tostring(failures) }
+end
+return { 'failed', tostring(failures) }
+`
+
+/**
+ * KEYS: store, counter, meta, pending, ready.
+ * ARGV: holder, nowMs, expiresAtMs, excludedCount, excluded indexes.
+ */
+const CLAIM_AVAILABLE_LUA = `
+if redis.call('ZCARD', KEYS[4]) == 0 then return { 'settled' } end
+local ready = redis.call('ZRANGE', KEYS[5], 0, -1)
+local excluded = {}
+for i = 1, tonumber(ARGV[4]) do excluded[ARGV[4 + i]] = true end
+local claimed = {}
+local retry_at = nil
+for _, field in ipairs(ready) do
+  if not excluded[field] then
+    local expires = tonumber(redis.call('HGET', KEYS[3], field .. ':ce') or '0')
+    if expires > tonumber(ARGV[2]) then
+      if not retry_at or expires < retry_at then retry_at = expires end
+    else
+      local entries = redis.call('XRANGE', KEYS[1], field .. '-0', field .. '-0')
+      if #entries == 0 then return { 'missing', field } end
+      local attempt = redis.call('HINCRBY', KEYS[3], field .. ':d', 1)
+      redis.call('HSETNX', KEYS[3], field .. ':fc', ARGV[2])
+      redis.call('HSET', KEYS[3],
+        field .. ':lc', ARGV[2],
+        field .. ':ch', ARGV[1],
+        field .. ':ce', ARGV[3])
+      claimed[#claimed + 1] = {
+        tostring(attempt),
+        redis.call('HGET', KEYS[3], field .. ':a') or '0',
+        redis.call('HGET', KEYS[3], field .. ':e') or false,
+        redis.call('HGET', KEYS[3], field .. ':fc') or false,
+        ARGV[2],
+        redis.call('HGET', KEYS[3], field .. ':lf') or false,
+        redis.call('HGET', KEYS[3], field .. ':lfa') or false,
+        ARGV[1],
+        ARGV[3],
+        entries[1]
+      }
+    end
+  end
+end
+if #claimed > 0 then
+  local result = { 'claimed', tostring(#claimed) }
+  for _, claim in ipairs(claimed) do
+    for _, value in ipairs(claim) do result[#result + 1] = value end
+  end
+  return result
+end
+if retry_at then return { 'busy', tostring(retry_at) } end
+return { 'settled' }
+`
+
+/**
+ * KEYS: counter, meta.
+ * ARGV: holder, nowMs, expiresAtMs, n, then per claim: index, attempt.
+ * Returns [renewedCount, ...renewed, ...superseded].
+ */
+const RENEW_CLAIMS_LUA = `
+local total = tonumber(redis.call('GET', KEYS[1]) or '0')
+local renewed = {}
+local superseded = {}
+for i = 1, tonumber(ARGV[4]) do
+  local field = ARGV[4 + (i - 1) * 2 + 1]
+  local attempt = tonumber(ARGV[4 + (i - 1) * 2 + 2])
+  local idx = tonumber(field)
+  if idx >= 1 and idx <= total then
+    local dispatches = tonumber(redis.call('HGET', KEYS[2], field .. ':d') or '0')
+    if dispatches > attempt then
+      superseded[#superseded + 1] = field
+    else
+      local expires = tonumber(redis.call('HGET', KEYS[2], field .. ':ce') or '0')
+      if tonumber(ARGV[3]) > tonumber(ARGV[2]) and
+         redis.call('HEXISTS', KEYS[2], field .. ':p') == 0 and
+         redis.call('HEXISTS', KEYS[2], field .. ':f') == 0 and
+         redis.call('HGET', KEYS[2], field .. ':ch') == ARGV[1] and
+         expires > tonumber(ARGV[2]) then
+        redis.call('HSET', KEYS[2], field .. ':ce', ARGV[3])
+        renewed[#renewed + 1] = field
+      end
+    end
+  end
+end
+local result = { tostring(#renewed) }
+for i = 1, #renewed do result[#result + 1] = renewed[i] end
+for i = 1, #superseded do result[#result + 1] = superseded[i] end
+return result
+`
+
+/**
+ * KEYS: store, counter, ids, session index, meta, pending, ready, watched.
+ * ARGV: sessionId, nowMs, parent index, attempt, n, then per child:
+ * id, type, payloadJson, lane, settled.
+ */
+const COMPLETE_ATTEMPT_LUA = `
+local function lane_field(lane, suffix)
+  return '__lane:' .. tostring(string.len(lane)) .. ':' .. lane .. ':' .. suffix
+end
+local function settle(field)
+  redis.call('ZREM', KEYS[6], field)
+  redis.call('ZREM', KEYS[7], field)
+  local lane = redis.call('HGET', KEYS[5], field .. ':l') or ''
+  if lane == '' then return end
+  local head_key = lane_field(lane, 'head')
+  if redis.call('HGET', KEYS[5], head_key) ~= field then return end
+  local next_field = redis.call('HGET', KEYS[5], field .. ':next')
+  while next_field and redis.call('HEXISTS', KEYS[5], next_field .. ':p') == 1 do
+    next_field = redis.call('HGET', KEYS[5], next_field .. ':next')
+  end
+  if next_field then
+    redis.call('HSET', KEYS[5], head_key, next_field)
+    if redis.call('HEXISTS', KEYS[5], next_field .. ':f') == 0 then
+      redis.call('ZADD', KEYS[7], tonumber(next_field), next_field)
+    end
+  else
+    redis.call('HDEL', KEYS[5], head_key, lane_field(lane, 'tail'))
+  end
+end
+local function enqueue(field, idx, lane)
+  redis.call('ZADD', KEYS[6], idx, field)
+  if lane == '' then
+    redis.call('ZADD', KEYS[7], idx, field)
+    return
+  end
+  local tail_key = lane_field(lane, 'tail')
+  local tail = redis.call('HGET', KEYS[5], tail_key)
+  if tail then
+    redis.call('HSET', KEYS[5], tail .. ':next', field)
+  else
+    redis.call('HSET', KEYS[5], lane_field(lane, 'head'), field)
+    redis.call('ZADD', KEYS[7], idx, field)
+  end
+  redis.call('HSET', KEYS[5], tail_key, field)
+end
+local parent = ARGV[3]
+local attempt = tonumber(ARGV[4])
+local n = tonumber(ARGV[5])
+local total = tonumber(redis.call('GET', KEYS[2]) or '0')
+if tonumber(parent) < 1 or tonumber(parent) > total then return { 'missing' } end
+local dispatches = tonumber(redis.call('HGET', KEYS[5], parent .. ':d') or '0')
+local processed = redis.call('HGET', KEYS[5], parent .. ':p')
+local processed_attempt = tonumber(redis.call('HGET', KEYS[5], parent .. ':pa') or '0')
+if processed then
+  if processed_attempt ~= attempt then return { 'superseded' } end
+  local raw_recorded_ids = redis.call('HGET', KEYS[5], parent .. ':ri')
+  if not raw_recorded_ids then return { 'partial' } end
+  local recorded_ids = cjson.decode(raw_recorded_ids)
+  if #recorded_ids ~= n then return { 'partial' } end
+  local indexes = {}
+  for i = 1, n do
+    local id = ARGV[5 + (i - 1) * 5 + 1]
+    if recorded_ids[i] ~= id then return { 'partial' } end
+    local existing = redis.call('HGET', KEYS[3], id)
+    if not existing then return { 'partial' } end
+    local rec = cjson.decode(existing)
+    if rec[1] ~= ARGV[1] then return { 'partial' } end
+    local entries = redis.call('XRANGE', KEYS[1], tostring(rec[2]) .. '-0', tostring(rec[2]) .. '-0')
+    if #entries == 0 then return { 'partial' } end
+    local values = entries[1][2]
+    local cause = nil
+    for j = 1, #values, 2 do
+      if values[j] == 'cause' then cause = values[j + 1] break end
+    end
+    if not cause or cause == '' then return { 'partial' } end
+    local decoded = cjson.decode(cause)
+    if tonumber(decoded['index']) ~= tonumber(parent) or
+       tonumber(decoded['attempt']) ~= attempt then return { 'partial' } end
+    indexes[#indexes + 1] = tostring(rec[2])
+  end
+  local result = { 'duplicate' }
+  for _, idx in ipairs(indexes) do result[#result + 1] = idx end
+  return result
+end
+if dispatches ~= attempt then return { 'superseded' } end
+if redis.call('HEXISTS', KEYS[5], parent .. ':ch') == 0 or
+   redis.call('HEXISTS', KEYS[5], parent .. ':f') == 1 or
+   tonumber(redis.call('HGET', KEYS[5], parent .. ':lfa') or '0') == attempt then
+  return { 'superseded' }
+end
+for i = 1, n do
+  local id = ARGV[5 + (i - 1) * 5 + 1]
+  if redis.call('HEXISTS', KEYS[3], id) == 1 then return { 'partial' } end
+end
+local returned_ids = {}
+for i = 1, n do returned_ids[i] = ARGV[5 + (i - 1) * 5 + 1] end
+local returned_json = '[]'
+if n > 0 then returned_json = cjson.encode(returned_ids) end
+redis.call('HSET', KEYS[5],
+  parent .. ':p', ARGV[2],
+  parent .. ':pa', ARGV[4],
+  parent .. ':ri', returned_json)
+redis.call('HDEL', KEYS[5], parent .. ':ch', parent .. ':ce')
+settle(parent)
+local cause = cjson.encode({ index = tonumber(parent), attempt = attempt })
+for i = 1, n do
+  local id = ARGV[5 + (i - 1) * 5 + 1]
+  local typ = ARGV[5 + (i - 1) * 5 + 2]
+  local payload = ARGV[5 + (i - 1) * 5 + 3]
+  local lane = ARGV[5 + (i - 1) * 5 + 4]
+  local settled = ARGV[5 + (i - 1) * 5 + 5]
+  local idx = total + i
+  redis.call('XADD', KEYS[1], tostring(idx) .. '-0',
+    'id', id, 'type', typ, 'payload', payload, 'created_at', ARGV[2],
+    'cause', cause, 'lane', lane)
+  redis.call('HSET', KEYS[3], id, cjson.encode({ ARGV[1], idx }))
+  redis.call('HSET', KEYS[5], tostring(idx) .. ':l', lane)
+  if settled == '1' then
+    redis.call('HSET', KEYS[5], tostring(idx) .. ':p', ARGV[2])
+  else
+    enqueue(tostring(idx), idx, lane)
+  end
+end
+redis.call('SET', KEYS[2], tostring(total + n))
+redis.call('ZADD', KEYS[4], 0, ARGV[1])
+return { 'ok', tostring(total + 1),
+  tostring(redis.call('EXISTS', KEYS[8])) }
+`
+
+/** KEYS: snapshot. ARGV: upToIndex, json. Guarded: never move backward. */
+const PUT_SNAPSHOT_LUA = `
+local cur = redis.call('GET', KEYS[1])
+if cur and tonumber(cjson.decode(cur)['index']) >= tonumber(ARGV[1]) then
+  return 0
+end
+redis.call('SET', KEYS[1], ARGV[2])
+return 1
+`
+
+/**
+ * KEYS: presence hash. ARGV: atMs, ttlMs, n, then per entry:
+ * hashField, valueJson ('' deletes). Field-wise LWW by the sender's
+ * `at`: a stored entry with a strictly newer stamp survives; ties go
+ * to the incoming write (memory-tier parity). Returns the applied
+ * 1-based entry positions. The whole-key PEXPIRE is the coarse bound,
+ * sound because core sends one uniform ttlMs; the per-entry `e` stamp
+ * is the fine bound (the injected storage clock at the applied set
+ * plus ttlMs — never the sender stamp), pruned on read against the
+ * same clock.
+ */
+const PRESENCE_SET_LUA = `
+local at = tonumber(ARGV[1])
+local applied = {}
+for i = 1, tonumber(ARGV[3]) do
+  local field = ARGV[3 + (i - 1) * 2 + 1]
+  local value = ARGV[3 + (i - 1) * 2 + 2]
+  local existing = redis.call('HGET', KEYS[1], field)
+  if not existing or tonumber(cjson.decode(existing)['a']) <= at then
+    if value == '' then
+      redis.call('HDEL', KEYS[1], field)
+    else
+      redis.call('HSET', KEYS[1], field, value)
+    end
+    applied[#applied + 1] = tostring(i)
+  end
+end
+if #applied > 0 then redis.call('PEXPIRE', KEYS[1], ARGV[2]) end
+return applied
+`
+
+/**
+ * KEYS: presence hash. ARGV: nowMs (the injected clock, so tests can
+ * time-travel expiry against a real server). Returns the live
+ * [field, value, ...] pairs; entries at or past their fine-bound
+ * expiry are HDELed in the same atomic step, so a stale reader can
+ * never sweep a concurrently refreshed field.
+ */
+const PRESENCE_READ_LUA = `
+local now = tonumber(ARGV[1])
+local rows = redis.call('HGETALL', KEYS[1])
+local live = {}
+for i = 1, #rows, 2 do
+  if tonumber(cjson.decode(rows[i + 1])['e']) <= now then
+    redis.call('HDEL', KEYS[1], rows[i])
+  else
+    live[#live + 1] = rows[i]
+    live[#live + 1] = rows[i + 1]
+  end
+end
+return live
+`
+
+/** KEYS: snapshot, event counter. Returns one atomic cache-plus-frontier read. */
+const READ_STATE_LUA = `
+local snapshot = redis.call('GET', KEYS[1])
+local frontier = redis.call('GET', KEYS[2]) or '0'
+return { snapshot or '', frontier }
+`
+
+// ── wire helpers ─────────────────────────────────────────────────────
+
+type StreamEntry = [id: string, fields: string[]]
+
+const fieldMap = (fields: string[]): Record<string, string> => {
+  const map: Record<string, string> = {}
+  for (let i = 0; i + 1 < fields.length; i += 2) {
+    map[fields[i]!] = fields[i + 1]!
+  }
+  return map
+}
+
+const STORED_EVENT_META_SUFFIXES = [
+  'p',
+  'pa',
+  'ri',
+  'ch',
+  'ce',
+  'f',
+  'fc',
+  'lc',
+  'lf',
+  'lfa',
+  'd',
+  'a',
+  'e',
+] as const
+
+const entryIndex = (entryId: string): number =>
+  Number(entryId.slice(0, entryId.indexOf('-')))
+
+const toEvent = (sessionId: string, entry: StreamEntry): Event => {
+  const fields = fieldMap(entry[1])
+  return {
+    id: fields['id']!,
+    type: fields['type']!,
+    payload: JSON.parse(fields['payload']!),
+    index: entryIndex(entry[0]),
+    sessionId,
+    createdAt: new Date(Number(fields['created_at'])),
+  }
+}
+
+const json = (value: unknown): string => JSON.stringify(value) ?? 'null'
+
+const escapeGlob = (value: string): string =>
+  value
+    .replaceAll('\\', '\\\\')
+    .replaceAll('*', '\\*')
+    .replaceAll('?', '\\?')
+    .replaceAll('[', '\\[')
+    .replaceAll(']', '\\]')
+
+const toCause = (raw: string | undefined): EventCause | null => {
+  if (raw === '' || raw === undefined) return null
+  const value = JSON.parse(raw) as {
+    index?: unknown
+    attempt?: unknown
+    batchSize?: unknown
+  }
+  if (
+    !Number.isInteger(value.index) ||
+    Number(value.index) < 1 ||
+    !Number.isInteger(value.attempt) ||
+    Number(value.attempt) < 1
+  ) {
+    throw new TypeError('stored event has an invalid cause')
+  }
+  if (
+    value.batchSize !== undefined &&
+    (!Number.isInteger(value.batchSize) || Number(value.batchSize) < 1)
+  ) {
+    throw new TypeError('stored event has an invalid cause')
+  }
+  return {
+    index: Number(value.index),
+    attempt: Number(value.attempt),
+    ...(value.batchSize === undefined
+      ? {}
+      : { batchSize: Number(value.batchSize) }),
+  }
+}
+
+const toClaimAvailableResult = (
+  sessionId: string,
+  reply: unknown[],
+): StoreClaimAvailableResult => {
+  const outcome = String(reply[0])
+  if (outcome === 'claimed') {
+    const count = Number(reply[1])
+    const events: StoredEvent[] = []
+    for (let i = 0; i < count; i++) {
+      const offset = 2 + i * 10
+      const entry = reply[offset + 9] as StreamEntry
+      const event = toEvent(sessionId, entry)
+      const fields = fieldMap(entry[1])
+      events.push(
+        Object.assign(event, {
+          cause: toCause(fields['cause']),
+          lane: fields['lane'] === '' ? null : fields['lane']!,
+          processedAt: null,
+          processedByAttempt: null,
+          returnedEventIds: null,
+          firstClaimedAt:
+            reply[offset + 3] === null
+              ? null
+              : new Date(Number(reply[offset + 3])),
+          lastClaimedAt: new Date(Number(reply[offset + 4])),
+          attemptCount: Number(reply[offset]),
+          claimHolder: String(reply[offset + 7]),
+          claimExpiresAt: new Date(Number(reply[offset + 8])),
+          failureCount: Number(reply[offset + 1]),
+          lastFailedAt:
+            reply[offset + 5] === null
+              ? null
+              : new Date(Number(reply[offset + 5])),
+          lastFailedAttempt:
+            reply[offset + 6] === null ? null : Number(reply[offset + 6]),
+          lastError:
+            reply[offset + 2] === null ? null : String(reply[offset + 2]),
+          failedAt: null,
+        }),
+      )
+    }
+    return {
+      outcome: 'claimed',
+      events,
+    }
+  }
+  if (outcome === 'busy') {
+    return { outcome, retryAt: new Date(Number(reply[1])) }
+  }
+  if (outcome === 'settled') return { outcome }
+  throw new TypeError(
+    `claim referenced a missing event in session '${sessionId}'`,
+  )
+}
+
+const wrap = async <T>(fn: () => Promise<T>): Promise<T> => {
+  try {
+    return await fn()
+  } catch (err) {
+    if (err instanceof A2Error || err instanceof TypeError) throw err
+    throw new A2Error('STORE_UNAVAILABLE', 'redis store operation failed', {
+      cause: err,
+    })
+  }
+}
+
+export function createRedisStoreCore(
+  options: RedisStoreCoreOptions,
+): RedisStoreCore {
+  const { call, clock, notify } = options
+  const generateId = options.ids
+  const prefix = options.keyPrefix
+
+  const storeKey = (s: string): string => `${prefix}:${s}:log`
+  const countKey = (s: string): string => `${prefix}:${s}:count`
+  const metaKey = (s: string): string => `${prefix}:${s}:meta`
+  const pendingKey = (s: string): string => `${prefix}:${s}:pending`
+  const readyKey = (s: string): string => `${prefix}:${s}:ready`
+  const snapKey = (s: string, r: string): string => `${prefix}:${s}:snap:${r}`
+  const watchedKey = (s: string): string => `${prefix}:${s}:watched`
+  const presenceKey = (s: string): string => `${prefix}:${s}:presence`
+  const idsKey = `${prefix}:ids`
+  const sessionsKey = `${prefix}:sessions`
+
+  const evalScript = (
+    script: string,
+    keys: string[],
+    args: Array<string | number>,
+  ): Promise<unknown> => call('EVAL', script, keys.length, ...keys, ...args)
+
+  const readFrontier = async (sessionId: string): Promise<number> => {
+    const frontier = Number((await call('GET', countKey(sessionId))) ?? 0)
+    if (!Number.isSafeInteger(frontier) || frontier < 0) {
+      throw new A2Error(
+        'STORE_UNAVAILABLE',
+        `redis event count for session '${sessionId}' is invalid`,
+      )
+    }
+    return frontier
+  }
+
+  const readRangePage = async (
+    sessionId: string,
+    afterIndex: number,
+    throughIndex: number,
+    limit: number,
+  ): Promise<StoredEvent[]> => {
+    if (throughIndex <= afterIndex) return []
+    const entries = (await call(
+      'XRANGE',
+      storeKey(sessionId),
+      `${afterIndex + 1}-0`,
+      `${throughIndex}-0`,
+      'COUNT',
+      limit,
+    )) as StreamEntry[]
+    if (entries.length === 0) return []
+
+    const metaFields = entries.flatMap((entry) => {
+      const index = entryIndex(entry[0])
+      return STORED_EVENT_META_SUFFIXES.map((suffix) => `${index}:${suffix}`)
+    })
+    const metaValues =
+      ((await call('HMGET', metaKey(sessionId), ...metaFields)) as Array<
+        string | null
+      > | null) ?? []
+    const meta: Record<string, string> = {}
+    for (let i = 0; i < metaFields.length; i += 1) {
+      const value = metaValues[i]
+      if (value !== null && value !== undefined) {
+        meta[metaFields[i]!] = value
+      }
+    }
+    return entries.map((entry) => {
+      const event = toEvent(sessionId, entry)
+      const idx = event.index
+      const fields = fieldMap(entry[1])
+      const processedAt = meta[`${idx}:p`]
+      const processedByAttempt = meta[`${idx}:pa`]
+      const returnedEventIds = meta[`${idx}:ri`]
+      const claimHolder = meta[`${idx}:ch`]
+      const claimExpiresAt = meta[`${idx}:ce`]
+      const failedAt = meta[`${idx}:f`]
+      const firstClaimedAt = meta[`${idx}:fc`]
+      const lastClaimedAt = meta[`${idx}:lc`]
+      const lastFailedAt = meta[`${idx}:lf`]
+      const lastFailedAttempt = meta[`${idx}:lfa`]
+      return Object.assign(event, {
+        cause: toCause(fields['cause']),
+        lane: fields['lane'] === '' ? null : fields['lane']!,
+        processedAt:
+          processedAt === undefined ? null : new Date(Number(processedAt)),
+        processedByAttempt:
+          processedByAttempt === undefined ? null : Number(processedByAttempt),
+        returnedEventIds:
+          returnedEventIds === undefined
+            ? null
+            : decodeReturnedEventIds(returnedEventIds),
+        firstClaimedAt:
+          firstClaimedAt === undefined
+            ? null
+            : new Date(Number(firstClaimedAt)),
+        lastClaimedAt:
+          lastClaimedAt === undefined ? null : new Date(Number(lastClaimedAt)),
+        attemptCount: Number(meta[`${idx}:d`] ?? 0),
+        claimHolder: claimHolder ?? null,
+        claimExpiresAt:
+          claimExpiresAt === undefined
+            ? null
+            : new Date(Number(claimExpiresAt)),
+        failureCount: Number(meta[`${idx}:a`] ?? 0),
+        lastFailedAt:
+          lastFailedAt === undefined ? null : new Date(Number(lastFailedAt)),
+        lastFailedAttempt:
+          lastFailedAttempt === undefined ? null : Number(lastFailedAttempt),
+        lastError: meta[`${idx}:e`] ?? null,
+        failedAt: failedAt === undefined ? null : new Date(Number(failedAt)),
+      })
+    })
+  }
+
+  const readEventRange = async (
+    sessionId: string,
+    afterIndex: number,
+    throughIndex: number,
+  ): Promise<Event[]> => {
+    if (throughIndex <= afterIndex) return []
+    const events: Event[] = []
+    let nextIndex = afterIndex + 1
+    while (nextIndex <= throughIndex) {
+      // oxlint-disable-next-line no-await-in-loop -- each page advances the dense frozen range
+      const entries = (await call(
+        'XRANGE',
+        storeKey(sessionId),
+        `${nextIndex}-0`,
+        `${throughIndex}-0`,
+        'COUNT',
+        READ_PAGE_SIZE,
+      )) as StreamEntry[]
+      if (entries.length === 0) {
+        throw new A2Error(
+          'STORE_UNAVAILABLE',
+          `redis event range for session '${sessionId}' ended before index ${throughIndex}`,
+        )
+      }
+      for (let position = 0; position < entries.length; position += 1) {
+        const index = entryIndex(entries[position]![0])
+        if (index !== nextIndex + position || index > throughIndex) {
+          throw new A2Error(
+            'STORE_UNAVAILABLE',
+            `redis event range for session '${sessionId}' is not contiguous`,
+          )
+        }
+      }
+      events.push(...entries.map((entry) => toEvent(sessionId, entry)))
+      nextIndex = events.at(-1)!.index + 1
+    }
+    return events
+  }
+
+  /** Bounded XRANGE pages restore the full-read contract on capped providers. */
+  const readRange = async (
+    sessionId: string,
+    afterIndex: number,
+    throughIndex?: number,
+  ): Promise<StoredEvent[]> => {
+    if (throughIndex !== undefined && throughIndex <= afterIndex) return []
+    const currentFrontier = await readFrontier(sessionId)
+    const frontier = Math.min(throughIndex ?? currentFrontier, currentFrontier)
+    if (frontier <= afterIndex) return []
+
+    const rows: StoredEvent[] = []
+    let nextIndex = afterIndex + 1
+    while (nextIndex <= frontier) {
+      // oxlint-disable-next-line no-await-in-loop -- each page advances the dense frozen range
+      const page = await readRangePage(
+        sessionId,
+        nextIndex - 1,
+        frontier,
+        READ_PAGE_SIZE,
+      )
+      if (page.length === 0) {
+        throw new A2Error(
+          'STORE_UNAVAILABLE',
+          `redis event range for session '${sessionId}' ended before index ${frontier}`,
+        )
+      }
+      for (let position = 0; position < page.length; position += 1) {
+        if (page[position]!.index !== nextIndex + position) {
+          throw new A2Error(
+            'STORE_UNAVAILABLE',
+            `redis event range for session '${sessionId}' is not contiguous`,
+          )
+        }
+      }
+      const lastIndex = page.at(-1)!.index
+      if (lastIndex < nextIndex || lastIndex > frontier) {
+        throw new A2Error(
+          'STORE_UNAVAILABLE',
+          `redis event range for session '${sessionId}' did not advance`,
+        )
+      }
+      rows.push(...page)
+      nextIndex = lastIndex + 1
+    }
+    return rows
+  }
+
+  return {
+    async append(sessionId, events) {
+      return wrap(async () => {
+        const supplied = events.filter((e) => e.id !== undefined)
+        const suppliedIds = supplied.map((e) => e.id as string)
+        if (new Set(suppliedIds).size !== suppliedIds.length) {
+          throw new A2Error(
+            'PARTIAL_DUPLICATE_BATCH',
+            'batch contains the same event id more than once',
+          )
+        }
+        const now = clock.now().getTime()
+        const withIds = events.map((e) => ({
+          id: e.id ?? generateId(),
+          type: e.type,
+          payload: e.payload,
+          cause: e.cause ? { ...e.cause } : null,
+          lane: e.lane ?? null,
+          settled: e.settled === true,
+        }))
+        const args: Array<string | number> = [
+          sessionId,
+          now,
+          withIds.length,
+          ...withIds.flatMap((e) => [
+            e.id,
+            e.type,
+            json(e.payload),
+            e.cause ? json(e.cause) : '',
+            e.lane ?? '',
+            e.settled ? '1' : '0',
+          ]),
+        ]
+        const reply = (await evalScript(
+          APPEND_LUA,
+          [
+            storeKey(sessionId),
+            countKey(sessionId),
+            idsKey,
+            sessionsKey,
+            metaKey(sessionId),
+            pendingKey(sessionId),
+            readyKey(sessionId),
+            watchedKey(sessionId),
+          ],
+          args,
+        )) as string[]
+
+        const [verdict] = reply
+        if (verdict === 'empty') {
+          return { events: [], hasPending: reply[1] === '1' }
+        }
+        if (verdict === 'foreign') {
+          throw new A2Error(
+            'PARTIAL_DUPLICATE_BATCH',
+            `event id '${reply[1]}' already exists in another session`,
+          )
+        }
+        if (verdict === 'no_parent') {
+          throw new TypeError(
+            `no event at index ${reply[1]} in session '${sessionId}'`,
+          )
+        }
+        if (verdict === 'superseded') {
+          throw new A2Error(
+            'SUPERSEDED_ATTEMPT',
+            `a newer attempt owns event ${reply[1]} in session '${sessionId}'`,
+          )
+        }
+        if (verdict === 'partial') {
+          throw new A2Error(
+            'PARTIAL_DUPLICATE_BATCH',
+            `batch mixes ${reply[1]} already-appended and ${events.length - Number(reply[1])} fresh events`,
+          )
+        }
+        if (verdict === 'dup') {
+          // A retry of a committed batch whose ack was lost — return
+          // the original rows, ordered by index like every adapter.
+          const hasPending = reply[1] === '1'
+          const wanted = new Set(reply.slice(2).map(Number))
+          const min = Math.min(...wanted)
+          const rows = await readRange(sessionId, min - 1)
+          const existing = rows.filter((row) => wanted.has(row.index))
+          return {
+            events: idempotentReplay(events, existing),
+            hasPending,
+          }
+        }
+        const base = Number(reply[1]) - 1
+        if (reply[3] === '1') notify?.(sessionId, base + withIds.length)
+        return {
+          events: withIds.map((e, i) => ({
+            id: e.id,
+            type: e.type,
+            payload: structuredClone(e.payload),
+            index: base + 1 + i,
+            sessionId,
+            createdAt: new Date(now),
+            cause: e.cause,
+            lane: e.lane,
+            processedAt: e.settled ? new Date(now) : null,
+            processedByAttempt: null,
+            returnedEventIds: null,
+            firstClaimedAt: null,
+            lastClaimedAt: null,
+            attemptCount: 0,
+            claimHolder: null,
+            claimExpiresAt: null,
+            failureCount: 0,
+            lastFailedAt: null,
+            lastFailedAttempt: null,
+            lastError: null,
+            failedAt: null,
+          })),
+          hasPending: reply[2] === '1',
+        }
+      })
+    },
+
+    async read(sessionId, opts) {
+      return wrap(async () => {
+        const rows = await readRange(
+          sessionId,
+          opts?.afterIndex ?? 0,
+          opts?.throughIndex,
+        )
+        return rows
+      })
+    },
+
+    async claimAvailable({
+      sessionId,
+      holder,
+      ttlMs,
+      expiresAtMs,
+      excludeIndexes,
+    }) {
+      return wrap(async () => {
+        const now = clock.now().getTime()
+        const expiresAt = expiresAtMs ?? now + ttlMs
+        const excluded = excludeIndexes ?? []
+        const reply = (await evalScript(
+          CLAIM_AVAILABLE_LUA,
+          [
+            storeKey(sessionId),
+            countKey(sessionId),
+            metaKey(sessionId),
+            pendingKey(sessionId),
+            readyKey(sessionId),
+          ],
+          [holder, now, expiresAt, excluded.length, ...excluded],
+        )) as unknown[]
+        return toClaimAvailableResult(sessionId, reply)
+      })
+    },
+
+    async renewClaims({ sessionId, holder, claims, ttlMs, expiresAtMs }) {
+      return wrap(async () => {
+        const now = clock.now().getTime()
+        const expiresAt = expiresAtMs ?? now + ttlMs
+        const reply = (await evalScript(
+          RENEW_CLAIMS_LUA,
+          [countKey(sessionId), metaKey(sessionId)],
+          [
+            holder,
+            now,
+            expiresAt,
+            claims.length,
+            ...claims.flatMap((claim) => [claim.index, claim.attempt]),
+          ],
+        )) as string[]
+        const renewedCount = Number(reply[0])
+        const values = reply.slice(1).map(Number)
+        return {
+          renewed: values.slice(0, renewedCount).toSorted((a, b) => a - b),
+          superseded: values.slice(renewedCount).toSorted((a, b) => a - b),
+        }
+      })
+    },
+
+    async completeAttempt({ sessionId, index, attempt, events }) {
+      return wrap(async () => {
+        const ids = events.map((event) => event.id)
+        if (new Set(ids).size !== ids.length) {
+          throw new A2Error(
+            'PARTIAL_DUPLICATE_BATCH',
+            'batch contains the same event id more than once',
+          )
+        }
+        const now = clock.now().getTime()
+        const reply = (await evalScript(
+          COMPLETE_ATTEMPT_LUA,
+          [
+            storeKey(sessionId),
+            countKey(sessionId),
+            idsKey,
+            sessionsKey,
+            metaKey(sessionId),
+            pendingKey(sessionId),
+            readyKey(sessionId),
+            watchedKey(sessionId),
+          ],
+          [
+            sessionId,
+            now,
+            index,
+            attempt,
+            events.length,
+            ...events.flatMap((event) => [
+              event.id,
+              event.type,
+              json(event.payload),
+              event.lane ?? '',
+              event.settled === true ? '1' : '0',
+            ]),
+          ],
+        )) as string[]
+        const outcome = reply[0]
+        if (outcome === 'missing') {
+          throw new TypeError(
+            `no event at index ${index} in session '${sessionId}'`,
+          )
+        }
+        if (outcome === 'partial') {
+          throw new A2Error(
+            'PARTIAL_DUPLICATE_BATCH',
+            'returned event ids do not match the completed attempt',
+          )
+        }
+        if (outcome === 'superseded') return { outcome }
+
+        const cause = { index, attempt }
+        if (outcome === 'ok') {
+          const base = Number(reply[1]) - 1
+          if (events.length > 0 && reply[2] === '1') {
+            notify?.(sessionId, base + events.length)
+          }
+          return {
+            outcome: 'completed',
+            events: events.map((event, i) => ({
+              id: event.id,
+              type: event.type,
+              payload: structuredClone(event.payload),
+              index: base + 1 + i,
+              sessionId,
+              createdAt: new Date(now),
+              cause,
+              lane: event.lane ?? null,
+              processedAt: event.settled === true ? new Date(now) : null,
+              processedByAttempt: null,
+              returnedEventIds: null,
+              firstClaimedAt: null,
+              lastClaimedAt: null,
+              attemptCount: 0,
+              claimHolder: null,
+              claimExpiresAt: null,
+              failureCount: 0,
+              lastFailedAt: null,
+              lastFailedAttempt: null,
+              lastError: null,
+              failedAt: null,
+            })),
+          } satisfies CompleteAttemptResult
+        }
+        if (outcome === 'duplicate') {
+          if (events.length === 0) {
+            return { outcome: 'completed', events: [] }
+          }
+          const wanted = new Set(reply.slice(1).map(Number))
+          const min = Math.min(...wanted)
+          const rows = await readRange(sessionId, min - 1)
+          const byIndex = new Map(rows.map((row) => [row.index, row]))
+          const existing = reply
+            .slice(1)
+            .map((value) => byIndex.get(Number(value))!)
+          return {
+            outcome: 'completed',
+            events: idempotentReplay(events, existing),
+          }
+        }
+        throw new TypeError(`unexpected completion outcome '${outcome}'`)
+      })
+    },
+
+    async failAttempt({ sessionId, index, attempt, error, maxFailures }) {
+      return wrap(async () => {
+        const reply = (await evalScript(
+          FAIL_ATTEMPT_LUA,
+          [
+            countKey(sessionId),
+            metaKey(sessionId),
+            pendingKey(sessionId),
+            readyKey(sessionId),
+          ],
+          [index, attempt, error, maxFailures, clock.now().getTime()],
+        )) as string[]
+        const outcome = reply[0]
+        if (outcome === 'missing') {
+          throw new TypeError(
+            `no event at index ${index} in session '${sessionId}'`,
+          )
+        }
+        return {
+          outcome: outcome as 'failed' | 'dead_lettered' | 'superseded',
+          failureCount: Number(reply[1]),
+        }
+      })
+    },
+
+    async readState(sessionId, reducerName) {
+      return wrap(async () => {
+        const reply = (await evalScript(
+          READ_STATE_LUA,
+          [snapKey(sessionId, reducerName), countKey(sessionId)],
+          [],
+        )) as [string, string]
+        const raw = reply[0]
+        const parsed =
+          raw === ''
+            ? null
+            : (JSON.parse(raw) as { index: number; state: unknown })
+        const frontier = Number(reply[1])
+        if (
+          !Number.isSafeInteger(frontier) ||
+          frontier < 0 ||
+          (parsed !== null &&
+            (!Number.isSafeInteger(parsed.index) || parsed.index < 0))
+        ) {
+          throw new A2Error(
+            'STORE_UNAVAILABLE',
+            `redis state frontier for session '${sessionId}' is invalid`,
+          )
+        }
+        const events = await readEventRange(
+          sessionId,
+          parsed?.index ?? 0,
+          frontier,
+        )
+        return {
+          snapshot: parsed
+            ? { index: parsed.index, state: parsed.state }
+            : null,
+          events,
+        }
+      })
+    },
+
+    async putSnapshot(sessionId, reducerName, index, state) {
+      await wrap(async () => {
+        await evalScript(
+          PUT_SNAPSHOT_LUA,
+          [snapKey(sessionId, reducerName)],
+          [index, json({ index, state, updatedAt: clock.now().getTime() })],
+        )
+      })
+    },
+
+    presence: {
+      async set(ns, participant, values, meta) {
+        return wrap(async () => {
+          const entries = Object.entries(values)
+          if (entries.length === 0) return null
+          const atMs = meta.at.getTime()
+          // Expiry anchors on the injected storage clock — the sender's
+          // `a` stamp orders writes, the `e` stamp bounds their
+          // lifetime, and the two clocks never mix.
+          const expiresAtMs = clock.now().getTime() + meta.ttlMs
+          // The hash field is JSON `[participant, field]`: both are
+          // caller strings, so no separator character is
+          // collision-safe — the JSON array is.
+          const applied = (await evalScript(
+            PRESENCE_SET_LUA,
+            [presenceKey(ns)],
+            [
+              atMs,
+              meta.ttlMs,
+              entries.length,
+              ...entries.flatMap(([field, value]) => [
+                JSON.stringify([participant, field]),
+                value === null
+                  ? ''
+                  : json({
+                      v: value,
+                      s: meta.seen,
+                      a: atMs,
+                      e: expiresAtMs,
+                    }),
+              ]),
+            ],
+          )) as string[]
+          if (applied.length === 0) return null
+          // Field-keyed and caller-named — null-prototype, like every
+          // presence map (see `nullProtoRecord`).
+          const appliedValues: Record<string, unknown> = nullProtoRecord()
+          for (const position of applied) {
+            const [field, value] = entries[Number(position) - 1]!
+            appliedValues[field] = structuredClone(value)
+          }
+          return {
+            participant,
+            values: appliedValues,
+            seen: meta.seen,
+            at: new Date(atMs),
+          }
+        })
+      },
+
+      async read(ns) {
+        return wrap(async () => {
+          const reply = (await evalScript(
+            PRESENCE_READ_LUA,
+            [presenceKey(ns)],
+            [clock.now().getTime()],
+          )) as string[]
+          const rows: PresenceRow[] = []
+          for (let i = 0; i + 1 < reply.length; i += 2) {
+            const [participant, field] = JSON.parse(reply[i]!) as [
+              string,
+              string,
+            ]
+            const entry = JSON.parse(reply[i + 1]!) as {
+              v: unknown
+              s: number
+              a: number
+              e: number
+            }
+            rows.push({
+              participant,
+              field,
+              value: entry.v,
+              seen: entry.s,
+              at: new Date(entry.a),
+              expiresAt: new Date(entry.e),
+            })
+          }
+          return rows
+        })
+      },
+    },
+
+    inspect: {
+      async listSessions(inspectionOptions) {
+        return wrap(async () => {
+          const minimum =
+            inspectionOptions.cursor === undefined
+              ? `[${inspectionOptions.prefix}`
+              : `(${inspectionOptions.cursor}`
+          const candidates = (await call(
+            'ZRANGEBYLEX',
+            sessionsKey,
+            minimum,
+            '+',
+            'LIMIT',
+            0,
+            inspectionOptions.limit + 1,
+          )) as string[]
+          const sessionIds = candidates
+            .filter((id) => id.startsWith(inspectionOptions.prefix))
+            .slice(0, inspectionOptions.limit)
+
+          const sessions = await Promise.all(
+            sessionIds.map(async (sessionId) => {
+              const rows = await readRange(sessionId, 0)
+              const first = rows[0]!
+              let updatedAt = first.createdAt
+              let pendingCount = 0
+              let failedCount = 0
+              let attemptCount = 0
+              let failureCount = 0
+              for (const row of rows) {
+                attemptCount += row.attemptCount
+                failureCount += row.failureCount
+                if (row.processedAt === null && row.failedAt === null) {
+                  pendingCount += 1
+                }
+                if (row.failedAt !== null) failedCount += 1
+                for (const timestamp of [
+                  row.createdAt,
+                  row.firstClaimedAt,
+                  row.lastClaimedAt,
+                  row.lastFailedAt,
+                  row.processedAt,
+                  row.failedAt,
+                ]) {
+                  if (timestamp && timestamp > updatedAt) updatedAt = timestamp
+                }
+              }
+              return {
+                sessionId,
+                eventCount: rows.length,
+                pendingCount,
+                failedCount,
+                attemptCount,
+                failureCount,
+                firstEventAt: first.createdAt,
+                updatedAt,
+              }
+            }),
+          )
+          return {
+            sessions: sessions.toSorted((a, b) =>
+              a.sessionId.localeCompare(b.sessionId),
+            ),
+            cursor:
+              candidates.length > inspectionOptions.limit &&
+              candidates[inspectionOptions.limit]?.startsWith(
+                inspectionOptions.prefix,
+              )
+                ? (sessionIds.at(-1) ?? null)
+                : null,
+          }
+        })
+      },
+      async readEvents(sessionId, pageOptions) {
+        return wrap(async () => {
+          const currentFrontier = await readFrontier(sessionId)
+          const throughIndex = Math.min(
+            pageOptions.throughIndex ?? currentFrontier,
+            currentFrontier,
+          )
+          const events = await readRangePage(
+            sessionId,
+            pageOptions.afterIndex,
+            throughIndex,
+            pageOptions.limit,
+          )
+          if (throughIndex > pageOptions.afterIndex && events.length === 0) {
+            throw new A2Error(
+              'STORE_UNAVAILABLE',
+              `redis event range for session '${sessionId}' ended before index ${throughIndex}`,
+            )
+          }
+          for (let position = 0; position < events.length; position += 1) {
+            if (
+              events[position]!.index !==
+              pageOptions.afterIndex + position + 1
+            ) {
+              throw new A2Error(
+                'STORE_UNAVAILABLE',
+                `redis event range for session '${sessionId}' is not contiguous`,
+              )
+            }
+          }
+          return { events, throughIndex }
+        })
+      },
+      async listSnapshots(sessionId) {
+        return wrap(async () => {
+          const start = `${prefix}:${sessionId}:snap:`
+          let cursor = '0'
+          const keys: string[] = []
+          do {
+            // oxlint-disable-next-line no-await-in-loop -- each SCAN cursor comes from the prior reply
+            const reply = (await call(
+              'SCAN',
+              cursor,
+              'MATCH',
+              `${escapeGlob(start)}*`,
+              'COUNT',
+              100,
+            )) as [string, string[]]
+            cursor = reply[0]
+            keys.push(...reply[1].filter((key) => key.startsWith(start)))
+          } while (cursor !== '0')
+          const snapshots = await Promise.all(
+            keys.map(async (key) => {
+              const raw = (await call('GET', key)) as string | null
+              if (raw === null) return null
+              const parsed = JSON.parse(raw) as {
+                index: number
+                updatedAt?: number
+              }
+              return {
+                reducerName: key.slice(start.length),
+                index: parsed.index,
+                updatedAt: new Date(parsed.updatedAt ?? 0),
+              }
+            }),
+          )
+          return snapshots
+            .filter((snapshot) => snapshot !== null)
+            .toSorted((a, b) => a.reducerName.localeCompare(b.reducerName))
+        })
+      },
+    },
+
+    async readRange(sessionId, afterIndex, throughIndex) {
+      return wrap(() => readRange(sessionId, afterIndex, throughIndex))
+    },
+
+    async readEvents(sessionId, afterIndex) {
+      return wrap(async () => {
+        const entries = (await call(
+          'XRANGE',
+          storeKey(sessionId),
+          `${afterIndex + 1}-0`,
+          '+',
+        )) as StreamEntry[]
+        return entries.map((entry) => toEvent(sessionId, entry))
+      })
+    },
+
+    async markWatched(sessionId, ttlMs) {
+      await wrap(() => call('SET', watchedKey(sessionId), '1', 'PX', ttlMs))
+    },
+  }
+}