experimental-a2 0.2.0 → 0.3.0

package/dist/log-redis.js

@@ -1,470 +1,37 @@
 import { t as A2Error } from "./errors-BJRMd-h6.js";
+import { n as NOTIFY_TIMINGS } from "./internal-gCd5qMry.js";
 import { t as retryableLazy } from "./retryable-lazy-DZWmHpii.js";
-import { t as idempotentReplay } from "./idempotent-replay-BMyHrP0L.js";
 import { n as SYSTEM_CLOCK, t as RANDOM_IDS } from "./log-yJbXUf72.js";
+import { t as defaultSleep } from "./log-polling-DZ1MiKLg.js";
+import { t as createRedisLogCore } from "./log-redis-core-CyJ5L8yR.js";
 //#region src/log-redis.ts
 /**
-* experimental-a2/log-redis — the push-native log backend, on Redis Streams.
+* experimental-a2/log-redis — the Redis-protocol log backend, on Redis
+* Streams. The storage semantics live in log-redis-core.ts (shared
+* with experimental-a2/log-redis-http); this module owns the connection and
+* the live feed.
 *
-* 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 claim expiry come from the injected clock so tests can
-* time-travel against a real server.
+* `stream()` is notify-driven: writes to watched sessions fire a
+* disposable PUBLISH wake-up (feeds hold a TTL'd presence marker the
+* write script checks, so unwatched sessions cost no wake-up), one
+* shared subscriber connection per backend serves every local feed,
+* and each wake triggers an `XRANGE` catch-up read. The notification
+* only decides when to read, never what — a lost one is healed by a
+* safety re-read (NOTIFY_TIMINGS), so delivery never depends on
+* pub/sub. Connections scale with processes (one command client plus
+* one subscriber), not with concurrent viewers.
 *
 * 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, metadata, pending, ready.
-* ARGV: sessionId, nowMs, n, then per event:
-* id, type, payloadJson, causeJson, lane, settled.
-* Returns ['empty', hasPending] | ['ok', firstIndex, hasPending] |
-* ['dup', hasPending, ...indexes] | ['partial', count] |
-* ['foreign', eventId].
-*/
-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 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 }
-`;
-/** 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: log, 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, indexes.
-*/
-const RENEW_CLAIMS_LUA = `
-local total = tonumber(redis.call('GET', KEYS[1]) or '0')
-local renewed = {}
-for i = 1, tonumber(ARGV[4]) do
-  local field = ARGV[4 + i]
-  local idx = tonumber(field)
-  local expires = tonumber(redis.call('HGET', KEYS[2], field .. ':ce') or '0')
-  if idx >= 1 and idx <= total and
-     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
-return renewed
-`;
-/**
-* KEYS: log, counter, ids, session index, meta, pending, ready.
-* ARGV: sessionId, nowMs, parent index, attempt, n, then per child:
-* id, type, payloadJson, lane, settled.
+* `call`/`duplicate`/`on`/`disconnect`.
 */
-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) }
-`;
-/** 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");
-	if (value.batchSize !== void 0 && (!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 === void 0 ? {} : { batchSize: Number(value.batchSize) }
-	};
-};
-const toClaimAvailableResult = (sessionId, reply) => {
-	const outcome = String(reply[0]);
-	if (outcome === "claimed") {
-		const count = Number(reply[1]);
-		const events = [];
-		for (let i = 0; i < count; i++) {
-			const offset = 2 + i * 10;
-			const entry = reply[offset + 9];
-			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 (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 ids = 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 pendingKey = (s) => `${prefix}:${s}:pending`;
-	const readyKey = (s) => `${prefix}:${s}:ready`;
-	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(() => {
@@ -472,381 +39,133 @@ function redis(options = {}) {
 		}))).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();
-	/** 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 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 === void 0 ? null : new Date(Number(processedAt)),
-				processedByAttempt: processedByAttempt === void 0 ? null : Number(processedByAttempt),
-				returnedEventIds: returnedEventIds === void 0 ? null : JSON.parse(returnedEventIds),
-				firstClaimedAt: firstClaimedAt === void 0 ? null : new Date(Number(firstClaimedAt)),
-				lastClaimedAt: lastClaimedAt === void 0 ? null : new Date(Number(lastClaimedAt)),
-				attemptCount: Number(meta[`${idx}:d`] ?? 0),
-				claimHolder: claimHolder ?? null,
-				claimExpiresAt: claimExpiresAt === void 0 ? null : new Date(Number(claimExpiresAt)),
-				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))
+	const notifyChannel = (sessionId) => `${prefix}:${sessionId}:notify`;
+	const core = createRedisLogCore({
+		call: async (command, ...args) => {
+			return (await client()).call(command, ...args);
+		},
+		clock,
+		ids,
+		keyPrefix: prefix,
+		notify: (sessionId, count) => {
+			client().then((c) => c.call("publish", notifyChannel(sessionId), count)).catch(() => {});
+		}
+	});
+	let severed = false;
+	let subscriber = null;
+	/** channel → parked-feed wake-ups, armed before each catch-up read. */
+	const wakers = /* @__PURE__ */ new Map();
+	/** channel → refcounted subscription held for each live iterator. */
+	const subscriptions = /* @__PURE__ */ new Map();
+	/**
+	* channel → last presence-marker refresh, throttling the SET.
+	* Deliberately real time (`Date.now()`), not the injected clock:
+	* the marker's PX expiry runs on server real time, and the throttle
+	* must tick with the TTL it refreshes or time-traveling tests would
+	* desync the two. Process-local and never stored, so the injected
+	* clock's every-stored-timestamp pledge is untouched.
+	*/
+	const watchedRefreshedAt = /* @__PURE__ */ new Map();
+	const getSubscriber = () => {
+		subscriber ??= (async () => {
+			const conn = (await client()).duplicate();
+			conn.on("message", (channel) => {
+				const set = wakers.get(channel);
+				if (!set) return;
+				for (const wake of set) wake();
 			});
+			return conn;
+		})();
+		return subscriber;
+	};
+	const acquireChannel = async (channel) => {
+		const existing = subscriptions.get(channel);
+		if (existing) {
+			existing.refs += 1;
+			try {
+				await existing.ready;
+			} catch (err) {
+				existing.refs -= 1;
+				throw err;
+			}
+			return;
+		}
+		const lease = {
+			refs: 1,
+			ready: getSubscriber().then((conn) => conn.call("subscribe", channel))
+		};
+		subscriptions.set(channel, lease);
+		try {
+			await lease.ready;
+		} catch (err) {
+			if (subscriptions.get(channel) === lease) subscriptions.delete(channel);
+			throw err;
+		}
+	};
+	const releaseChannel = (channel) => {
+		const lease = subscriptions.get(channel);
+		if (!lease) return;
+		lease.refs -= 1;
+		if (lease.refs > 0) return;
+		subscriptions.delete(channel);
+		watchedRefreshedAt.delete(channel);
+		getSubscriber().then((conn) => conn.call("unsubscribe", channel)).catch(() => {});
+	};
+	const armWaker = (channel) => {
+		let wake;
+		const wakeup = new Promise((resolve) => {
+			wake = resolve;
 		});
+		let set = wakers.get(channel);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			wakers.set(channel, set);
+		}
+		set.add(wake);
+		return {
+			wakeup,
+			wake,
+			disarm: () => {
+				set.delete(wake);
+				if (set.size === 0) wakers.delete(channel);
+			}
+		};
 	};
 	return {
-		async append(sessionId, events) {
-			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,
-					lane: e.lane ?? null,
-					settled: e.settled === true
-				}));
-				const args = [
-					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, [
-					logKey(sessionId),
-					countKey(sessionId),
-					idsKey,
-					sessionsKey,
-					metaKey(sessionId),
-					pendingKey(sessionId),
-					readyKey(sessionId)
-				], args);
-				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 === "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 hasPending = reply[1] === "1";
-					const wanted = new Set(reply.slice(2).map(Number));
-					const min = Math.min(...wanted);
-					const existing = (await readRange(sessionId, min - 1)).filter((row) => wanted.has(row.index));
-					return {
-						events: idempotentReplay(events, existing),
-						hasPending
-					};
-				}
-				const base = Number(reply[1]) - 1;
-				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 () => {
-				return await readRange(sessionId, opts?.afterIndex ?? 0);
-			});
-		},
-		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, [
-					logKey(sessionId),
-					countKey(sessionId),
-					metaKey(sessionId),
-					pendingKey(sessionId),
-					readyKey(sessionId)
-				], [
-					holder,
-					now,
-					expiresAt,
-					excluded.length,
-					...excluded
-				]);
-				return toClaimAvailableResult(sessionId, reply);
-			});
-		},
-		async renewClaims({ sessionId, holder, indexes, ttlMs, expiresAtMs }) {
-			return wrap(async () => {
-				const now = clock.now().getTime();
-				const expiresAt = expiresAtMs ?? now + ttlMs;
-				return (await evalScript(RENEW_CLAIMS_LUA, [countKey(sessionId), metaKey(sessionId)], [
-					holder,
-					now,
-					expiresAt,
-					indexes.length,
-					...indexes
-				])).map(Number);
-			});
-		},
-		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, [
-					logKey(sessionId),
-					countKey(sessionId),
-					idsKey,
-					sessionsKey,
-					metaKey(sessionId),
-					pendingKey(sessionId),
-					readyKey(sessionId)
-				], [
-					sessionId,
-					now,
-					index,
-					attempt,
-					events.length,
-					...events.flatMap((event) => [
-						event.id,
-						event.type,
-						json(event.payload),
-						event.lane ?? "",
-						event.settled === true ? "1" : "0"
-					])
-				]);
-				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;
-					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
-						}))
-					};
-				}
-				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()
-				]);
-				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 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 () => {
-					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));
-				});
-			}
-		},
+		append: core.append,
+		read: core.read,
+		claimAvailable: core.claimAvailable,
+		renewClaims: core.renewClaims,
+		completeAttempt: core.completeAttempt,
+		failAttempt: core.failAttempt,
+		readState: core.readState,
+		putSnapshot: core.putSnapshot,
+		inspect: core.inspect,
 		stream(sessionId, opts) {
 			const startAt = opts?.startAt ?? 0;
+			const channel = notifyChannel(sessionId);
 			return { [Symbol.asyncIterator]() {
 				let last = startAt;
 				let buffer = [];
 				let closed = false;
-				let conn = null;
+				let subscribed = false;
+				let pending = null;
+				let interrupt = null;
+				const release = () => {
+					if (!subscribed) return;
+					subscribed = false;
+					releaseChannel(channel);
+				};
 				return {
 					async next() {
 						for (;;) {
-							if (closed) return {
-								value: void 0,
-								done: true
-							};
+							if (closed) {
+								release();
+								return {
+									value: void 0,
+									done: true
+								};
+							}
 							const row = buffer.shift();
 							if (row) {
 								last = row.index;
@@ -855,31 +174,48 @@ function redis(options = {}) {
 									done: false
 								};
 							}
-							if (!conn) {
-								conn = (await client()).duplicate();
-								streamConnections.add(conn);
+							if (severed) {
+								release();
+								throw new A2Error("LOG_UNAVAILABLE", "the log was closed");
 							}
-							let reply;
+							const waker = armWaker(channel);
+							interrupt = waker.wake;
 							try {
-								reply = await conn.call("XREAD", "BLOCK", XREAD_BLOCK_MS, "STREAMS", logKey(sessionId), `${last}-0`);
+								if (!subscribed) {
+									await acquireChannel(channel);
+									subscribed = true;
+								}
+								const markedAt = watchedRefreshedAt.get(channel) ?? 0;
+								if (Date.now() - markedAt >= NOTIFY_TIMINGS.safetyReadMs) {
+									watchedRefreshedAt.set(channel, Date.now());
+									await core.markWatched(sessionId, NOTIFY_TIMINGS.safetyReadMs * 3);
+								}
+								buffer = await core.readEvents(sessionId, last);
+								if (buffer.length === 0 && !closed && !severed) {
+									pending = defaultSleep(NOTIFY_TIMINGS.safetyReadMs);
+									await Promise.race([waker.wakeup, pending.promise]);
+									pending.cancel();
+									pending = null;
+								}
 							} catch (err) {
+								release();
 								if (closed) return {
 									value: void 0,
 									done: true
 								};
+								if (err instanceof A2Error) throw err;
 								throw new A2Error("LOG_UNAVAILABLE", "redis log operation failed", { cause: err });
+							} finally {
+								waker.disarm();
+								interrupt = null;
 							}
-							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();
-						}
+						pending?.cancel();
+						interrupt?.();
+						release();
 						return {
 							value: void 0,
 							done: true
@@ -889,11 +225,12 @@ function redis(options = {}) {
 			} };
 		},
 		async close() {
-			for (const conn of streamConnections) conn.disconnect();
-			streamConnections.clear();
+			severed = true;
+			for (const set of wakers.values()) for (const wake of set) wake();
+			if (subscriber) (await subscriber.catch(() => null))?.disconnect();
 			const current = connection.peek();
 			if (!current) return;
-			(await current).disconnect();
+			(await current.catch(() => null))?.disconnect();
 		}
 	};
 }