experimental-a2 0.0.0

package/dist/log-redis.js

@@ -0,0 +1,711 @@
+import { t as A2Error } from "./errors-BJRMd-h6.js";
+import { t as retryableLazy } from "./retryable-lazy-DZWmHpii.js";
+import { n as SYSTEM_CLOCK, t as RANDOM_IDS } from "./log-yJbXUf72.js";
+//#region src/log-redis.ts
+/**
+* a2/log-redis — the push-native log backend, on Redis Streams.
+*
+* The stream IS the log: each event is a stream entry whose ID is its
+* dense a2 index (`${index}-0`), so `XRANGE` is the catch-up read and
+* `XREAD BLOCK` is a true blocking live feed — no polling anywhere.
+* 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 lease expiry come from the injected clock — the lease
+* stores its logical `expiresAt` and compares against `clock.now()`,
+* with a generous real-time `PX` purely as garbage collection — so
+* tests can time-travel against a real server.
+*
+* Works with any Redis-protocol server on a single instance or a
+* non-cluster provider (Upstash — durable by default — Redis, Valkey).
+* Cluster mode is out: the atomic scripts span keys. `ioredis` is an
+* optional peer dependency; pass `url`, or inject any client exposing
+* `call`/`duplicate`/`disconnect`.
+*/
+/** How long each blocking read waits before re-checking for close(). */
+const XREAD_BLOCK_MS = 1e4;
+/**
+* KEYS: log stream, counter, global id hash, session index.
+* ARGV: sessionId, nowMs, n, then per event:
+* id, type, payloadJson, causeJson (empty when no causal edge is known).
+* Returns ['ok', firstIndex] | ['dup', ...indexes] | ['partial', count]
+* | ['foreign', eventId].
+*/
+const APPEND_LUA = `
+local n = tonumber(ARGV[3])
+local dups = {}
+for i = 1, n do
+  local id = ARGV[3 + (i - 1) * 4 + 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' }
+  for i = 1, #dups do res[#res + 1] = dups[i] end
+  return res
+end
+if #dups > 0 then return { 'partial', tostring(#dups) } end
+local base = tonumber(redis.call('GET', KEYS[2]) or '0')
+for i = 1, n do
+  local id = ARGV[3 + (i - 1) * 4 + 1]
+  local typ = ARGV[3 + (i - 1) * 4 + 2]
+  local payload = ARGV[3 + (i - 1) * 4 + 3]
+  local cause = ARGV[3 + (i - 1) * 4 + 4]
+  local idx = base + i
+  redis.call('XADD', KEYS[1], tostring(idx) .. '-0',
+    'id', id, 'type', typ, 'payload', payload, 'created_at', ARGV[2],
+    'cause', cause)
+  redis.call('HSET', KEYS[3], id, cjson.encode({ ARGV[1], idx }))
+end
+redis.call('SET', KEYS[2], tostring(base + n))
+redis.call('ZADD', KEYS[4], 0, ARGV[1])
+return { 'ok', tostring(base + 1) }
+`;
+/** KEYS: counter, meta. ARGV: idx, value, field suffix. Returns 0|1. */
+const MARK_LUA = `
+local idx = tonumber(ARGV[1])
+local total = tonumber(redis.call('GET', KEYS[1]) or '0')
+if idx < 1 or idx > total then
+  return 0
+end
+local target = ARGV[1] .. ':' .. ARGV[3]
+if ARGV[3] ~= 'p' or redis.call('HEXISTS', KEYS[2], target) == 0 then
+  redis.call('HSET', KEYS[2], target, ARGV[2])
+end
+if ARGV[3] == 'p' then
+  local head = tonumber(redis.call('HGET', KEYS[2], '__head') or '1')
+  while head <= total and redis.call('HEXISTS', KEYS[2], tostring(head) .. ':p') == 1 do
+    head = head + 1
+  end
+  redis.call('HSET', KEYS[2], '__head', tostring(head))
+end
+return 1
+`;
+/** KEYS: counter, meta. ARGV: idx, attempt, error, maxFailures, nowMs. */
+const FAIL_ATTEMPT_LUA = `
+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
+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])
+if failures >= tonumber(ARGV[4]) then
+  redis.call('HSET', KEYS[2], field .. ':f', ARGV[5])
+  return { 'dead_lettered', tostring(failures) }
+end
+return { 'failed', tostring(failures) }
+`;
+/**
+* KEYS: log, counter, meta, lease.
+* ARGV: holder, nowMs, expiresAtMs, gcPxMs, maxIndex (-1 = unbounded).
+*/
+const CLAIM_NEXT_LUA = `
+local total = tonumber(redis.call('GET', KEYS[2]) or '0')
+local rawHead = redis.call('HGET', KEYS[3], '__head')
+local head = tonumber(rawHead or '1')
+while head <= total and redis.call('HEXISTS', KEYS[3], tostring(head) .. ':p') == 1 do
+  head = head + 1
+end
+if total > 0 or rawHead then
+  redis.call('HSET', KEYS[3], '__head', tostring(head))
+end
+if head > total then return { 'settled' } end
+local field = tostring(head)
+local maxIndex = tonumber(ARGV[5])
+if redis.call('HEXISTS', KEYS[3], field .. ':f') == 1 or
+   (maxIndex >= 0 and head > maxIndex) then
+  return { 'settled' }
+end
+
+local cur = redis.call('GET', KEYS[4])
+if cur then
+  local rec = cjson.decode(cur)
+  if rec[2] > tonumber(ARGV[2]) and rec[1] ~= ARGV[1] then
+    return { 'busy' }
+  end
+end
+local lease = cjson.encode({ ARGV[1], tonumber(ARGV[3]) })
+redis.call('SET', KEYS[4], lease, 'PX', ARGV[4])
+
+local failures = tonumber(redis.call('HGET', KEYS[3], field .. ':a') or '0')
+local dispatches = tonumber(redis.call('HGET', KEYS[3], field .. ':d') or '0')
+local attempt = dispatches + 1
+redis.call('HSETNX', KEYS[3], field .. ':fc', ARGV[2])
+redis.call('HSET', KEYS[3], field .. ':d', tostring(attempt), field .. ':lc', ARGV[2])
+local entries = redis.call('XRANGE', KEYS[1], field .. '-0', field .. '-0')
+if #entries == 0 then return { 'missing' } end
+return {
+  'claimed', tostring(attempt), tostring(failures),
+  redis.call('HGET', KEYS[3], field .. ':e') or false,
+  redis.call('HGET', KEYS[3], field .. ':fc') or false,
+  redis.call('HGET', KEYS[3], field .. ':lc') or false,
+  redis.call('HGET', KEYS[3], field .. ':lf') or false,
+  redis.call('HGET', KEYS[3], field .. ':lfa') or false,
+  entries[1]
+}
+`;
+/**
+* KEYS: log, counter, meta, lease.
+* ARGV: holder, nowMs, completedIndex, attempt, maxIndex (-1 = unbounded).
+*/
+const COMPLETE_AND_CLAIM_NEXT_LUA = `
+local total = tonumber(redis.call('GET', KEYS[2]) or '0')
+local completed = tonumber(ARGV[3])
+if completed < 1 or completed > total then return { 'missing' } end
+local completedField = ARGV[3]
+local completedDispatches = tonumber(redis.call('HGET', KEYS[3], completedField .. ':d') or '0')
+if redis.call('HEXISTS', KEYS[3], completedField .. ':p') == 1 or
+   completedDispatches ~= tonumber(ARGV[4]) then
+  return { 'superseded' }
+end
+redis.call('HSET', KEYS[3],
+  completedField .. ':p', ARGV[2],
+  completedField .. ':pa', ARGV[4])
+
+local head = tonumber(redis.call('HGET', KEYS[3], '__head') or '1')
+while head <= total and redis.call('HEXISTS', KEYS[3], tostring(head) .. ':p') == 1 do
+  head = head + 1
+end
+redis.call('HSET', KEYS[3], '__head', tostring(head))
+if head > total then return { 'settled' } end
+local field = tostring(head)
+local maxIndex = tonumber(ARGV[5])
+if redis.call('HEXISTS', KEYS[3], field .. ':f') == 1 or
+   (maxIndex >= 0 and head > maxIndex) then
+  return { 'settled' }
+end
+
+local cur = redis.call('GET', KEYS[4])
+if not cur then return { 'busy' } end
+local lease = cjson.decode(cur)
+if lease[1] ~= ARGV[1] or lease[2] <= tonumber(ARGV[2]) then
+  return { 'busy' }
+end
+
+local failures = tonumber(redis.call('HGET', KEYS[3], field .. ':a') or '0')
+local dispatches = tonumber(redis.call('HGET', KEYS[3], field .. ':d') or '0')
+local attempt = dispatches + 1
+redis.call('HSETNX', KEYS[3], field .. ':fc', ARGV[2])
+redis.call('HSET', KEYS[3], field .. ':d', tostring(attempt), field .. ':lc', ARGV[2])
+local entries = redis.call('XRANGE', KEYS[1], field .. '-0', field .. '-0')
+if #entries == 0 then return { 'missing' } end
+return {
+  'claimed', tostring(attempt), tostring(failures),
+  redis.call('HGET', KEYS[3], field .. ':e') or false,
+  redis.call('HGET', KEYS[3], field .. ':fc') or false,
+  redis.call('HGET', KEYS[3], field .. ':lc') or false,
+  redis.call('HGET', KEYS[3], field .. ':lf') or false,
+  redis.call('HGET', KEYS[3], field .. ':lfa') or false,
+  entries[1]
+}
+`;
+/**
+* KEYS: lease. ARGV: holder, nowMs, expiresAtMs, gcPxMs. Logical expiry is
+* the stored expiresAt vs now (exclusive: expiresAt <= now is free) —
+* the PX is garbage collection only, never the semantics.
+*/
+const LEASE_ACQUIRE_LUA = `
+local cur = redis.call('GET', KEYS[1])
+if cur then
+  local rec = cjson.decode(cur)
+  if rec[2] > tonumber(ARGV[2]) and rec[1] ~= ARGV[1] then return 0 end
+end
+local rec = cjson.encode({ ARGV[1], tonumber(ARGV[3]) })
+redis.call('SET', KEYS[1], rec, 'PX', ARGV[4])
+return 1
+`;
+/** KEYS: lease. ARGV: holder. Only the holder may release. */
+const LEASE_RELEASE_LUA = `
+local cur = redis.call('GET', KEYS[1])
+if cur and cjson.decode(cur)[1] == ARGV[1] then
+  redis.call('DEL', KEYS[1])
+end
+return 1
+`;
+/** 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: snapshot, log stream. Returns one atomic cache-plus-tail read. */
+const READ_STATE_LUA = `
+local snapshot = redis.call('GET', KEYS[1])
+local after = 0
+if snapshot then
+  after = tonumber(cjson.decode(snapshot)['index'])
+end
+local events = redis.call('XRANGE', KEYS[2], tostring(after + 1) .. '-0', '+')
+return { snapshot or '', events }
+`;
+const fieldMap = (fields) => {
+	const map = {};
+	for (let i = 0; i + 1 < fields.length; i += 2) map[fields[i]] = fields[i + 1];
+	return map;
+};
+const entryIndex = (entryId) => Number(entryId.slice(0, entryId.indexOf("-")));
+const toEvent = (sessionId, entry) => {
+	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) => JSON.stringify(value) ?? "null";
+const escapeGlob = (value) => value.replaceAll("\\", "\\\\").replaceAll("*", "\\*").replaceAll("?", "\\?").replaceAll("[", "\\[").replaceAll("]", "\\]");
+const toCause = (raw) => {
+	if (raw === "" || raw === void 0) return null;
+	const value = JSON.parse(raw);
+	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");
+	return {
+		index: Number(value.index),
+		attempt: Number(value.attempt)
+	};
+};
+const toClaimResult = (sessionId, reply) => {
+	const outcome = String(reply[0]);
+	if (outcome === "claimed") {
+		const entry = reply[8];
+		const event = toEvent(sessionId, entry);
+		const fields = fieldMap(entry[1]);
+		return {
+			outcome: "claimed",
+			event: Object.assign(event, {
+				cause: toCause(fields["cause"]),
+				processedAt: null,
+				processedByAttempt: null,
+				firstClaimedAt: reply[4] === null ? null : new Date(Number(reply[4])),
+				lastClaimedAt: reply[5] === null ? null : new Date(Number(reply[5])),
+				attemptCount: Number(reply[1]),
+				failureCount: Number(reply[2]),
+				lastFailedAt: reply[6] === null ? null : new Date(Number(reply[6])),
+				lastFailedAttempt: reply[7] === null ? null : Number(reply[7]),
+				lastError: reply[3] === null ? null : String(reply[3]),
+				failedAt: null
+			})
+		};
+	}
+	if (outcome === "busy" || outcome === "settled") return { outcome };
+	throw new TypeError(`claim referenced a missing event in session '${sessionId}'`);
+};
+const toHandoffResult = (sessionId, reply) => String(reply[0]) === "superseded" ? { outcome: "superseded" } : toClaimResult(sessionId, reply);
+const wrap = async (fn) => {
+	try {
+		return await fn();
+	} catch (err) {
+		if (err instanceof A2Error || err instanceof TypeError) throw err;
+		throw new A2Error("LOG_UNAVAILABLE", "redis log operation failed", { cause: err });
+	}
+};
+function redis(options = {}) {
+	const clock = options.clock ?? SYSTEM_CLOCK;
+	const generateId = options.ids ?? RANDOM_IDS;
+	const prefix = options.keyPrefix ?? "a2";
+	if (!options.client && !options.url) throw new TypeError("redis() needs a url or an injected client");
+	const logKey = (s) => `${prefix}:${s}:log`;
+	const countKey = (s) => `${prefix}:${s}:count`;
+	const metaKey = (s) => `${prefix}:${s}:meta`;
+	const leaseKey = (s) => `${prefix}:${s}:lease`;
+	const snapKey = (s, r) => `${prefix}:${s}:snap:${r}`;
+	const idsKey = `${prefix}:ids`;
+	const sessionsKey = `${prefix}:sessions`;
+	const connection = retryableLazy(async () => {
+		if (options.client) return options.client;
+		return new (await (import("ioredis").catch(() => {
+			throw new A2Error("LOG_NOT_CONFIGURED", "a2/log-redis with a url needs the 'ioredis' package (optional peer dependency) — install it, or inject a client");
+		}))).default(options.url);
+	});
+	const client = connection.get;
+	const evalScript = async (script, keys, args) => {
+		return (await client()).call("EVAL", script, keys.length, ...keys, ...args);
+	};
+	/** Every live-feed connection, so close() can sever them. */
+	const streamConnections = /* @__PURE__ */ new Set();
+	const ensureSessionIndex = retryableLazy(() => wrap(async () => {
+		const c = await client();
+		let cursor = "0";
+		const keyStart = `${prefix}:`;
+		const keyEnd = ":count";
+		do {
+			const reply = await c.call("SCAN", cursor, "MATCH", `${escapeGlob(prefix)}:*:count`, "COUNT", 200);
+			cursor = reply[0];
+			const ids = reply[1].filter((key) => key.startsWith(keyStart) && key.endsWith(keyEnd)).map((key) => key.slice(keyStart.length, -6));
+			if (ids.length > 0) await c.call("ZADD", sessionsKey, ...ids.flatMap((id) => [0, id]));
+		} while (cursor !== "0");
+	})).get;
+	/** XRANGE + meta merge — the raw read both `read` and dup-returns use. */
+	const readRange = async (sessionId, afterIndex) => {
+		const c = await client();
+		const entries = await c.call("XRANGE", logKey(sessionId), `${afterIndex + 1}-0`, "+");
+		if (entries.length === 0) return [];
+		const meta = fieldMap(await c.call("HGETALL", metaKey(sessionId)) ?? []);
+		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 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"]),
+				processedAt: processedAt === void 0 ? null : new Date(Number(processedAt)),
+				processedByAttempt: processedByAttempt === void 0 ? null : Number(processedByAttempt),
+				firstClaimedAt: firstClaimedAt === void 0 ? null : new Date(Number(firstClaimedAt)),
+				lastClaimedAt: lastClaimedAt === void 0 ? null : new Date(Number(lastClaimedAt)),
+				attemptCount: Number(meta[`${idx}:d`] ?? 0),
+				failureCount: Number(meta[`${idx}:a`] ?? 0),
+				lastFailedAt: lastFailedAt === void 0 ? null : new Date(Number(lastFailedAt)),
+				lastFailedAttempt: lastFailedAttempt === void 0 ? null : Number(lastFailedAttempt),
+				lastError: meta[`${idx}:e`] ?? null,
+				failedAt: failedAt === void 0 ? null : new Date(Number(failedAt))
+			});
+		});
+	};
+	return {
+		async append(sessionId, events) {
+			if (events.length === 0) return [];
+			return wrap(async () => {
+				const suppliedIds = events.filter((e) => e.id !== void 0).map((e) => e.id);
+				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
+				}));
+				const args = [
+					sessionId,
+					now,
+					withIds.length,
+					...withIds.flatMap((e) => [
+						e.id,
+						e.type,
+						json(e.payload),
+						e.cause ? json(e.cause) : ""
+					])
+				];
+				const reply = await evalScript(APPEND_LUA, [
+					logKey(sessionId),
+					countKey(sessionId),
+					idsKey,
+					sessionsKey
+				], args);
+				const [verdict] = reply;
+				if (verdict === "foreign") throw new A2Error("PARTIAL_DUPLICATE_BATCH", `event id '${reply[1]}' already exists in another session`);
+				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") {
+					const wanted = new Set(reply.slice(1).map(Number));
+					const min = Math.min(...wanted);
+					return (await readRange(sessionId, min - 1)).filter((r) => wanted.has(r.index));
+				}
+				const base = Number(reply[1]) - 1;
+				return 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,
+					processedAt: null,
+					processedByAttempt: null,
+					firstClaimedAt: null,
+					lastClaimedAt: null,
+					attemptCount: 0,
+					failureCount: 0,
+					lastFailedAt: null,
+					lastFailedAttempt: null,
+					lastError: null,
+					failedAt: null
+				}));
+			});
+		},
+		async read(sessionId, opts) {
+			return wrap(async () => {
+				const rows = await readRange(sessionId, opts?.afterIndex ?? 0);
+				return opts?.unprocessedOnly ? rows.filter((r) => r.processedAt === null) : rows;
+			});
+		},
+		async claimNext({ sessionId, holder, ttlMs, expiresAtMs, maxIndex }) {
+			return wrap(async () => {
+				const now = clock.now().getTime();
+				const expiresAt = expiresAtMs ?? now + ttlMs;
+				const effectiveTtlMs = Math.max(1, expiresAt - now);
+				const gcPx = Math.max(effectiveTtlMs * 10, 6e4);
+				const reply = await evalScript(CLAIM_NEXT_LUA, [
+					logKey(sessionId),
+					countKey(sessionId),
+					metaKey(sessionId),
+					leaseKey(sessionId)
+				], [
+					holder,
+					now,
+					expiresAt,
+					gcPx,
+					maxIndex ?? -1
+				]);
+				return toClaimResult(sessionId, reply);
+			});
+		},
+		async completeAndClaimNext({ sessionId, holder, completedIndex, attempt, maxIndex }) {
+			return wrap(async () => {
+				const reply = await evalScript(COMPLETE_AND_CLAIM_NEXT_LUA, [
+					logKey(sessionId),
+					countKey(sessionId),
+					metaKey(sessionId),
+					leaseKey(sessionId)
+				], [
+					holder,
+					clock.now().getTime(),
+					completedIndex,
+					attempt,
+					maxIndex ?? -1
+				]);
+				return toHandoffResult(sessionId, reply);
+			});
+		},
+		async markProcessed(sessionId, index) {
+			await wrap(async () => {
+				if (await evalScript(MARK_LUA, [countKey(sessionId), metaKey(sessionId)], [
+					index,
+					clock.now().getTime(),
+					"p"
+				]) === 0) throw new TypeError(`no event at index ${index} in session '${sessionId}'`);
+			});
+		},
+		async failAttempt({ sessionId, index, attempt, error, maxFailures }) {
+			return wrap(async () => {
+				const reply = await evalScript(FAIL_ATTEMPT_LUA, [countKey(sessionId), metaKey(sessionId)], [
+					index,
+					attempt,
+					error,
+					maxFailures,
+					clock.now().getTime()
+				]);
+				const outcome = reply[0];
+				if (outcome === "missing") throw new TypeError(`no event at index ${index} in session '${sessionId}'`);
+				return {
+					outcome,
+					failureCount: Number(reply[1])
+				};
+			});
+		},
+		async markFailed(sessionId, index) {
+			await wrap(async () => {
+				if (await evalScript(MARK_LUA, [countKey(sessionId), metaKey(sessionId)], [
+					index,
+					clock.now().getTime(),
+					"f"
+				]) === 0) throw new TypeError(`no event at index ${index} in session '${sessionId}'`);
+			});
+		},
+		async readState(sessionId, reducerName) {
+			return wrap(async () => {
+				const reply = await evalScript(READ_STATE_LUA, [snapKey(sessionId, reducerName), logKey(sessionId)], []);
+				const raw = reply[0];
+				const parsed = raw === "" ? null : JSON.parse(raw);
+				return {
+					snapshot: parsed ? {
+						index: parsed.index,
+						state: parsed.state
+					} : null,
+					events: reply[1].map((entry) => toEvent(sessionId, entry))
+				};
+			});
+		},
+		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()
+				})]);
+			});
+		},
+		inspect: {
+			async listSessions(inspectionOptions) {
+				return wrap(async () => {
+					await ensureSessionIndex();
+					const c = await client();
+					const minimum = inspectionOptions.cursor === void 0 ? `[${inspectionOptions.prefix}` : `(${inspectionOptions.cursor}`;
+					const candidates = await c.call("ZRANGEBYLEX", sessionsKey, minimum, "+", "LIMIT", 0, inspectionOptions.limit + 1);
+					const sessionIds = candidates.filter((id) => id.startsWith(inspectionOptions.prefix)).slice(0, inspectionOptions.limit);
+					return {
+						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
+							};
+						}))).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 listSnapshots(sessionId) {
+				return wrap(async () => {
+					const c = await client();
+					const start = `${prefix}:${sessionId}:snap:`;
+					let cursor = "0";
+					const keys = [];
+					do {
+						const reply = await c.call("SCAN", cursor, "MATCH", `${escapeGlob(start)}*`, "COUNT", 100);
+						cursor = reply[0];
+						keys.push(...reply[1].filter((key) => key.startsWith(start)));
+					} while (cursor !== "0");
+					return (await Promise.all(keys.map(async (key) => {
+						const raw = await c.call("GET", key);
+						if (raw === null) return null;
+						const parsed = JSON.parse(raw);
+						return {
+							reducerName: key.slice(start.length),
+							index: parsed.index,
+							updatedAt: new Date(parsed.updatedAt ?? 0)
+						};
+					}))).filter((snapshot) => snapshot !== null).toSorted((a, b) => a.reducerName.localeCompare(b.reducerName));
+				});
+			}
+		},
+		stream(sessionId, opts) {
+			const startAt = opts?.startAt ?? 0;
+			return { [Symbol.asyncIterator]() {
+				let last = startAt;
+				let buffer = [];
+				let closed = false;
+				let conn = null;
+				return {
+					async next() {
+						for (;;) {
+							if (closed) return {
+								value: void 0,
+								done: true
+							};
+							const row = buffer.shift();
+							if (row) {
+								last = row.index;
+								return {
+									value: row,
+									done: false
+								};
+							}
+							if (!conn) {
+								conn = (await client()).duplicate();
+								streamConnections.add(conn);
+							}
+							let reply;
+							try {
+								reply = await conn.call("XREAD", "BLOCK", XREAD_BLOCK_MS, "STREAMS", logKey(sessionId), `${last}-0`);
+							} catch (err) {
+								if (closed) return {
+									value: void 0,
+									done: true
+								};
+								throw new A2Error("LOG_UNAVAILABLE", "redis log operation failed", { cause: err });
+							}
+							if (reply === null) continue;
+							const [[, entries]] = reply;
+							buffer = entries.map((entry) => toEvent(sessionId, entry));
+						}
+					},
+					async return() {
+						closed = true;
+						if (conn) {
+							streamConnections.delete(conn);
+							conn.disconnect();
+						}
+						return {
+							value: void 0,
+							done: true
+						};
+					}
+				};
+			} };
+		},
+		lease: {
+			async acquire({ sessionId, holder, ttlMs, expiresAtMs }) {
+				return wrap(async () => {
+					const now = clock.now().getTime();
+					const expiresAt = expiresAtMs ?? now + ttlMs;
+					const effectiveTtlMs = Math.max(1, expiresAt - now);
+					const gcPx = Math.max(effectiveTtlMs * 10, 6e4);
+					return await evalScript(LEASE_ACQUIRE_LUA, [leaseKey(sessionId)], [
+						holder,
+						now,
+						expiresAt,
+						gcPx
+					]) === 1;
+				});
+			},
+			async release({ sessionId, holder }) {
+				await wrap(async () => {
+					await evalScript(LEASE_RELEASE_LUA, [leaseKey(sessionId)], [holder]);
+				});
+			}
+		},
+		async close() {
+			for (const conn of streamConnections) conn.disconnect();
+			streamConnections.clear();
+			const current = connection.peek();
+			if (!current) return;
+			(await current).disconnect();
+		}
+	};
+}
+//#endregion
+export { redis };