experimental-a2 0.4.0 → 0.5.0

package/src/store-memory.ts

@@ -0,0 +1,788 @@
+/**
+ * experimental-a2/store-memory — in-memory store backend (the test default).
+ *
+ * Implements the A2Store interface with zero dependencies. See
+ * specs/a2-implementation.md §3 for the contract; the conformance suite
+ * in test/conformance is the executable version of it.
+ */
+
+import type { PresencePatch } from './contract.ts'
+import { A2Error } from './errors.ts'
+import { idempotentReplay } from './idempotent-replay.ts'
+import { nullProtoRecord } from './internal.ts'
+import {
+  RANDOM_IDS,
+  SYSTEM_CLOCK,
+  type A2Store,
+  type AppendEvent,
+  type Clock,
+  type Event,
+  type EventCause,
+  type IdSource,
+  type PresenceRow,
+  type StoredEvent,
+  type StoredSessionSummary,
+  type StoreStateRead,
+} from './store.ts'
+
+export type MemoryStoreOptions = {
+  /** Injectable clock — every stored timestamp comes from here. */
+  clock?: Clock
+  /** Injectable id source for generated event ids. */
+  ids?: IdSource
+}
+
+type Row = {
+  id: string
+  type: string
+  payload: unknown
+  index: number
+  sessionId: string
+  createdAt: Date
+  cause: EventCause | null
+  lane: string | null
+  processedAt: Date | null
+  processedByAttempt: number | null
+  returnedEventIds: string[] | null
+  firstClaimedAt: Date | null
+  lastClaimedAt: Date | null
+  attemptCount: number
+  claimHolder: string | null
+  claimExpiresAt: Date | null
+  failureCount: number
+  lastFailedAt: Date | null
+  lastFailedAttempt: number | null
+  lastError: string | null
+  failedAt: Date | null
+}
+
+type PresenceEntry = {
+  value: unknown
+  seen: number
+  at: Date
+  expiresAt: Date
+}
+
+type LaneQueue = { rows: Row[]; head: number }
+type SessionDispatch = {
+  ready: Map<number, Row>
+  lanes: Map<string, LaneQueue>
+}
+
+const toStored = (row: Row): StoredEvent => ({
+  id: row.id,
+  type: row.type,
+  payload: structuredClone(row.payload),
+  index: row.index,
+  sessionId: row.sessionId,
+  createdAt: new Date(row.createdAt),
+  cause: row.cause ? { ...row.cause } : null,
+  lane: row.lane,
+  processedAt: row.processedAt ? new Date(row.processedAt) : null,
+  processedByAttempt: row.processedByAttempt,
+  returnedEventIds: row.returnedEventIds ? [...row.returnedEventIds] : null,
+  firstClaimedAt: row.firstClaimedAt ? new Date(row.firstClaimedAt) : null,
+  lastClaimedAt: row.lastClaimedAt ? new Date(row.lastClaimedAt) : null,
+  attemptCount: row.attemptCount,
+  claimHolder: row.claimHolder,
+  claimExpiresAt: row.claimExpiresAt ? new Date(row.claimExpiresAt) : null,
+  failureCount: row.failureCount,
+  lastFailedAt: row.lastFailedAt ? new Date(row.lastFailedAt) : null,
+  lastFailedAttempt: row.lastFailedAttempt,
+  lastError: row.lastError,
+  failedAt: row.failedAt ? new Date(row.failedAt) : null,
+})
+
+const toEvent = (row: Row): Event => ({
+  id: row.id,
+  type: row.type,
+  payload: structuredClone(row.payload),
+  index: row.index,
+  sessionId: row.sessionId,
+  createdAt: new Date(row.createdAt),
+})
+
+export function memory(options: MemoryStoreOptions = {}): A2Store {
+  const clock = options.clock ?? SYSTEM_CLOCK
+  const generateId = options.ids ?? RANDOM_IDS
+
+  const sessions = new Map<string, Row[]>()
+  const dispatch = new Map<string, SessionDispatch>()
+  /** Global unique index on event ids, like the SQL schema's. */
+  const byEventId = new Map<string, Row>()
+  /** Keyed by `${sessionId}\u0000${reducerName}` — a pure cache. */
+  const snapshots = new Map<
+    string,
+    { index: number; state: unknown; updatedAt: Date }
+  >()
+  const streamSubscribers = new Map<string, Set<(row: Row) => void>>()
+  /** ns → participant → field → latest surviving write. */
+  const presenceRows = new Map<
+    string,
+    Map<string, Map<string, PresenceEntry>>
+  >()
+  const presenceSubscribers = new Map<
+    string,
+    Set<(patch: PresencePatch) => void>
+  >()
+
+  const notifyStreams = (sessionId: string, rows: Row[]): void => {
+    const subs = streamSubscribers.get(sessionId)
+    if (!subs) return
+    for (const listener of subs) {
+      for (const row of rows) listener(row)
+    }
+  }
+
+  const rowsOf = (sessionId: string): Row[] => {
+    let rows = sessions.get(sessionId)
+    if (!rows) {
+      rows = []
+      sessions.set(sessionId, rows)
+    }
+    return rows
+  }
+
+  const dispatchOf = (sessionId: string): SessionDispatch => {
+    let state = dispatch.get(sessionId)
+    if (!state) {
+      state = { ready: new Map(), lanes: new Map() }
+      dispatch.set(sessionId, state)
+    }
+    return state
+  }
+
+  const enqueue = (sessionId: string, row: Row): void => {
+    if (row.processedAt !== null) return
+    const state = dispatchOf(sessionId)
+    if (row.lane === null) {
+      state.ready.set(row.index, row)
+      return
+    }
+    let queue = state.lanes.get(row.lane)
+    if (!queue) {
+      queue = { rows: [], head: 0 }
+      state.lanes.set(row.lane, queue)
+    }
+    queue.rows.push(row)
+    if (queue.rows.length === 1) state.ready.set(row.index, row)
+  }
+
+  const settle = (sessionId: string, row: Row): void => {
+    const state = dispatchOf(sessionId)
+    state.ready.delete(row.index)
+    if (row.lane === null) return
+    const queue = state.lanes.get(row.lane)!
+    if (queue.rows[queue.head] !== row) return
+    queue.head += 1
+    if (queue.head === queue.rows.length) {
+      state.lanes.delete(row.lane)
+      return
+    }
+    const next = queue.rows[queue.head]!
+    if (next.failedAt === null) state.ready.set(next.index, next)
+  }
+
+  const find = (sessionId: string, index: number): Row => {
+    const row = sessions.get(sessionId)?.[index - 1]
+    if (!row) {
+      throw new TypeError(
+        `no event at index ${index} in session '${sessionId}'`,
+      )
+    }
+    return row
+  }
+
+  const appendResult = (sessionId: string, events: StoredEvent[]) => ({
+    events,
+    hasPending: (sessions.get(sessionId) ?? []).some(
+      (row) => row.processedAt === null,
+    ),
+  })
+
+  const claim = (
+    row: Row,
+    holder: string,
+    now: Date,
+    expiresAt: Date,
+  ): StoredEvent => {
+    row.attemptCount += 1
+    row.firstClaimedAt ??= new Date(now)
+    row.lastClaimedAt = new Date(now)
+    row.claimHolder = holder
+    row.claimExpiresAt = new Date(expiresAt)
+    return toStored(row)
+  }
+
+  const checkBatchIds = (
+    sessionId: string,
+    events: readonly (AppendEvent & { id?: string })[],
+  ): Row[] => {
+    const supplied = events.filter(
+      (candidate): candidate is AppendEvent & { id: string } =>
+        candidate.id !== undefined,
+    )
+    const suppliedIds = new Set(supplied.map((candidate) => candidate.id))
+    if (suppliedIds.size !== supplied.length) {
+      throw new A2Error(
+        'PARTIAL_DUPLICATE_BATCH',
+        'batch contains the same event id more than once',
+      )
+    }
+    const existing = supplied
+      .map((candidate) => byEventId.get(candidate.id))
+      .filter((row): row is Row => row !== undefined)
+    const foreign = existing.find((row) => row.sessionId !== sessionId)
+    if (foreign) {
+      throw new A2Error(
+        'PARTIAL_DUPLICATE_BATCH',
+        `event id '${foreign.id}' already exists in another session`,
+      )
+    }
+    return existing
+  }
+
+  const insert = (
+    sessionId: string,
+    events: readonly AppendEvent[],
+    now: Date,
+    cause?: EventCause,
+  ): Row[] => {
+    const rows = rowsOf(sessionId)
+    const base = rows.length === 0 ? 0 : rows[rows.length - 1]!.index
+    const inserted = events.map((candidate, offset): Row => ({
+      id: candidate.id ?? generateId(),
+      type: candidate.type,
+      payload: structuredClone(candidate.payload),
+      index: base + 1 + offset,
+      sessionId,
+      createdAt: new Date(now),
+      cause: cause
+        ? { ...cause }
+        : candidate.cause
+          ? { ...candidate.cause }
+          : null,
+      lane: candidate.lane ?? null,
+      processedAt: candidate.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,
+    }))
+    for (const row of inserted) {
+      if (byEventId.has(row.id)) {
+        throw new A2Error(
+          'PARTIAL_DUPLICATE_BATCH',
+          `event id '${row.id}' already exists`,
+        )
+      }
+    }
+    for (const row of inserted) {
+      rows.push(row)
+      byEventId.set(row.id, row)
+      enqueue(sessionId, row)
+    }
+    return inserted
+  }
+
+  const readStateOf = (
+    sessionId: string,
+    reducerName: string,
+  ): StoreStateRead => {
+    const snap = snapshots.get(`${sessionId}\u0000${reducerName}`)
+    const snapshot = snap
+      ? { index: snap.index, state: structuredClone(snap.state) }
+      : null
+    const afterIndex = snapshot?.index ?? 0
+    return {
+      snapshot,
+      events: (sessions.get(sessionId) ?? [])
+        .filter((row) => row.index > afterIndex)
+        .map(toEvent),
+    }
+  }
+
+  return {
+    async append(sessionId, events) {
+      if (events.length === 0) return appendResult(sessionId, [])
+
+      // Batch-scoped idempotency (a2-implementation.md §3): all ids
+      // already present → lost-ack retry, return the original rows;
+      // some present → the caller mixed sent and fresh events.
+      const existing = checkBatchIds(sessionId, events)
+      if (existing.length > 0) {
+        if (existing.length === events.length) {
+          return appendResult(
+            sessionId,
+            idempotentReplay(events, existing.map(toStored)),
+          )
+        }
+        throw new A2Error(
+          'PARTIAL_DUPLICATE_BATCH',
+          `batch mixes ${existing.length} already-appended and ${events.length - existing.length} fresh events`,
+        )
+      }
+
+      // Attempt-currency fence: a fresh handler append commits only while
+      // its causal attempt is still the parent's latest (store.ts `append`).
+      const rows = sessions.get(sessionId) ?? []
+      for (const event of events) {
+        if (!event.cause) continue
+        const parent = rows[event.cause.index - 1]
+        if (!parent) {
+          throw new TypeError(
+            `no event at index ${event.cause.index} in session '${sessionId}'`,
+          )
+        }
+        if (
+          parent.attemptCount !== event.cause.attempt ||
+          parent.failedAt !== null
+        ) {
+          throw new A2Error(
+            'SUPERSEDED_ATTEMPT',
+            `attempt ${event.cause.attempt} no longer owns event ${event.cause.index} in session '${sessionId}'`,
+          )
+        }
+      }
+
+      const now = clock.now()
+      const inserted = insert(sessionId, events, now)
+      notifyStreams(sessionId, inserted)
+      return appendResult(sessionId, inserted.map(toStored))
+    },
+
+    async read(sessionId, opts) {
+      const rows = sessions.get(sessionId) ?? []
+      const start = Math.max(0, opts?.afterIndex ?? 0)
+      const end = Math.max(0, opts?.throughIndex ?? rows.length)
+      return rows.slice(start, end).map(toStored)
+    },
+
+    async claimAvailable({
+      sessionId,
+      holder,
+      ttlMs,
+      expiresAtMs,
+      excludeIndexes,
+    }) {
+      const claimedAt = clock.now()
+      const now = claimedAt.getTime()
+      const expiresAt = new Date(expiresAtMs ?? now + ttlMs)
+      const excluded = new Set(excludeIndexes ?? [])
+      const eligible: Row[] = []
+      let retryAt: Date | null = null
+
+      for (const row of dispatchOf(sessionId).ready.values()) {
+        if (row.failedAt !== null || excluded.has(row.index)) continue
+        if (row.claimExpiresAt && row.claimExpiresAt.getTime() > now) {
+          if (!retryAt || row.claimExpiresAt < retryAt) {
+            retryAt = new Date(row.claimExpiresAt)
+          }
+          continue
+        }
+        eligible.push(row)
+      }
+
+      if (eligible.length === 0) {
+        return retryAt ? { outcome: 'busy', retryAt } : { outcome: 'settled' }
+      }
+      eligible.sort((a, b) => a.index - b.index)
+      return {
+        outcome: 'claimed',
+        events: eligible.map((row) => claim(row, holder, claimedAt, expiresAt)),
+      }
+    },
+
+    async renewClaims({ sessionId, holder, claims, ttlMs, expiresAtMs }) {
+      const now = clock.now()
+      const expiresAt = new Date(expiresAtMs ?? now.getTime() + ttlMs)
+      const requested = new Map(claims.map((c) => [c.index, c.attempt]))
+      const renewed: number[] = []
+      const superseded: number[] = []
+      for (const row of sessions.get(sessionId) ?? []) {
+        const attempt = requested.get(row.index)
+        if (attempt === undefined) continue
+        if (row.attemptCount > attempt) {
+          superseded.push(row.index)
+          continue
+        }
+        if (
+          row.processedAt === null &&
+          row.failedAt === null &&
+          row.claimHolder === holder &&
+          row.claimExpiresAt !== null &&
+          row.claimExpiresAt > now
+        ) {
+          row.claimExpiresAt = new Date(expiresAt)
+          renewed.push(row.index)
+        }
+      }
+      return { renewed, superseded }
+    },
+
+    async completeAttempt({ sessionId, index, attempt, events }) {
+      const parent = find(sessionId, index)
+      const cause = { index, attempt }
+      if (parent.processedAt !== null) {
+        if (parent.processedByAttempt !== attempt) {
+          return { outcome: 'superseded' }
+        }
+        const requestedIds = events.map((event) => event.id)
+        if (
+          parent.returnedEventIds === null ||
+          parent.returnedEventIds.length !== requestedIds.length ||
+          parent.returnedEventIds.some(
+            (id, offset) => id !== requestedIds[offset],
+          )
+        ) {
+          throw new A2Error(
+            'PARTIAL_DUPLICATE_BATCH',
+            'completed attempt does not match the returned event batch',
+          )
+        }
+        const existing = checkBatchIds(sessionId, events)
+        if (
+          existing.length !== events.length ||
+          existing.some(
+            (row) =>
+              row.cause?.index !== index || row.cause.attempt !== attempt,
+          )
+        ) {
+          throw new A2Error(
+            'PARTIAL_DUPLICATE_BATCH',
+            'completed attempt does not match the returned event batch',
+          )
+        }
+        return {
+          outcome: 'completed',
+          events: idempotentReplay(events, existing.map(toStored)),
+        }
+      }
+      if (
+        parent.attemptCount !== attempt ||
+        parent.failedAt !== null ||
+        parent.claimHolder === null
+      ) {
+        return { outcome: 'superseded' }
+      }
+
+      const existing = checkBatchIds(sessionId, events)
+      if (existing.length > 0) {
+        throw new A2Error(
+          'PARTIAL_DUPLICATE_BATCH',
+          'returned event batch contains already-appended ids',
+        )
+      }
+      const now = clock.now()
+      const inserted = insert(sessionId, events, now, cause)
+      parent.processedAt = new Date(now)
+      parent.processedByAttempt = attempt
+      parent.returnedEventIds = events.map((event) => event.id)
+      parent.claimHolder = null
+      parent.claimExpiresAt = null
+      settle(sessionId, parent)
+      notifyStreams(sessionId, inserted)
+      return { outcome: 'completed', events: inserted.map(toStored) }
+    },
+
+    async failAttempt({ sessionId, index, attempt, error, maxFailures }) {
+      const row = find(sessionId, index)
+      if (
+        row.processedAt ||
+        row.attemptCount !== attempt ||
+        (row.claimHolder === null && row.lastFailedAttempt !== attempt)
+      ) {
+        return { outcome: 'superseded', failureCount: row.failureCount }
+      }
+      if (row.lastFailedAttempt === attempt && row.claimHolder === null) {
+        return {
+          outcome: row.failedAt ? 'dead_lettered' : 'failed',
+          failureCount: row.failureCount,
+        }
+      }
+      if (row.failedAt) {
+        return { outcome: 'dead_lettered', failureCount: row.failureCount }
+      }
+      row.failureCount += 1
+      row.lastError = error
+      const failedAt = clock.now()
+      row.lastFailedAt = new Date(failedAt)
+      row.lastFailedAttempt = attempt
+      row.claimHolder = null
+      row.claimExpiresAt = null
+      if (row.failureCount >= maxFailures) {
+        row.failedAt = new Date(failedAt)
+        dispatchOf(sessionId).ready.delete(row.index)
+        return {
+          outcome: 'dead_lettered',
+          failureCount: row.failureCount,
+        }
+      }
+      return { outcome: 'failed', failureCount: row.failureCount }
+    },
+
+    async readState(sessionId, reducerName) {
+      return readStateOf(sessionId, reducerName)
+    },
+
+    async readStates(sessionIds, reducerName) {
+      return sessionIds.map((sessionId) => readStateOf(sessionId, reducerName))
+    },
+
+    async putSnapshot(sessionId, reducerName, index, state) {
+      const key = `${sessionId}\u0000${reducerName}`
+      const existing = snapshots.get(key)
+      // Guarded upsert: a slower concurrent writer must never clobber a
+      // further-along snapshot. A lost race costs a few refolded events
+      // next read — never correctness.
+      if (existing && existing.index >= index) return
+      snapshots.set(key, {
+        index,
+        state: structuredClone(state),
+        updatedAt: clock.now(),
+      })
+    },
+
+    presence: {
+      async set(ns, participant, values, meta) {
+        let participants = presenceRows.get(ns)
+        if (!participants) {
+          participants = new Map()
+          presenceRows.set(ns, participants)
+        }
+        let fields = participants.get(participant)
+        if (!fields) {
+          fields = new Map()
+          participants.set(participant, fields)
+        }
+
+        // Expiry anchors on the storage's own clock — the sender's
+        // `at` orders writes but never extends or shortens a lifetime.
+        const expiresAtMs = clock.now().getTime() + meta.ttlMs
+        // Field-keyed and caller-named — null-prototype, like every
+        // presence map (see `nullProtoRecord`).
+        const applied: Record<string, unknown> = nullProtoRecord()
+        let appliedCount = 0
+        for (const [field, value] of Object.entries(values)) {
+          // Field-wise LWW by `at`; ties go to the incoming write, so
+          // same-stamp sets keep set-then-read intuition.
+          const existing = fields.get(field)
+          if (existing && existing.at > meta.at) continue
+          if (value === null) {
+            fields.delete(field)
+          } else {
+            fields.set(field, {
+              value: structuredClone(value),
+              seen: meta.seen,
+              at: new Date(meta.at),
+              expiresAt: new Date(expiresAtMs),
+            })
+          }
+          applied[field] = structuredClone(value)
+          appliedCount += 1
+        }
+        if (fields.size === 0) participants.delete(participant)
+        if (participants.size === 0) presenceRows.delete(ns)
+
+        // Only applied fields broadcast — a losing write repaints nothing,
+        // so subscribers stay consistent with what read() returns.
+        if (appliedCount === 0) return
+        const subs = presenceSubscribers.get(ns)
+        if (!subs) return
+        const patch: PresencePatch = {
+          participant,
+          values: applied,
+          seen: meta.seen,
+          at: new Date(meta.at),
+        }
+        for (const listener of subs) listener(patch)
+      },
+
+      async read(ns) {
+        const participants = presenceRows.get(ns)
+        if (!participants) return []
+        const now = clock.now()
+        const rows: PresenceRow[] = []
+        for (const [participant, fields] of participants) {
+          for (const [field, entry] of fields) {
+            // Expiry is enforced lazily on read — no timers; a silent
+            // participant's rows vanish the next time anyone looks.
+            if (entry.expiresAt <= now) {
+              fields.delete(field)
+              continue
+            }
+            rows.push({
+              participant,
+              field,
+              value: structuredClone(entry.value),
+              seen: entry.seen,
+              at: new Date(entry.at),
+              expiresAt: new Date(entry.expiresAt),
+            })
+          }
+          if (fields.size === 0) participants.delete(participant)
+        }
+        if (participants.size === 0) presenceRows.delete(ns)
+        return rows
+      },
+
+      subscribe(ns, onPatch) {
+        let subs = presenceSubscribers.get(ns)
+        if (!subs) {
+          subs = new Set()
+          presenceSubscribers.set(ns, subs)
+        }
+        subs.add(onPatch)
+        return () => {
+          subs.delete(onPatch)
+          if (subs.size === 0) presenceSubscribers.delete(ns)
+        }
+      },
+    },
+
+    inspect: {
+      async listSessions(inspectionOptions) {
+        const ids = [...sessions.keys()]
+          .filter(
+            (sessionId) =>
+              sessionId.startsWith(inspectionOptions.prefix) &&
+              (inspectionOptions.cursor === undefined ||
+                sessionId > inspectionOptions.cursor),
+          )
+          .toSorted()
+        const visible = ids.slice(0, inspectionOptions.limit)
+        const summaries = visible.map((sessionId): StoredSessionSummary => {
+          const rows = sessions.get(sessionId)!
+          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: new Date(first.createdAt),
+            updatedAt: new Date(updatedAt),
+          }
+        })
+        return {
+          sessions: summaries,
+          cursor: ids.length > visible.length ? (visible.at(-1) ?? null) : null,
+        }
+      },
+      async readEvents(sessionId, pageOptions) {
+        const rows = sessions.get(sessionId) ?? []
+        const throughIndex = Math.min(
+          pageOptions.throughIndex ?? rows.length,
+          rows.length,
+        )
+        return {
+          events: rows
+            .slice(pageOptions.afterIndex, throughIndex)
+            .slice(0, pageOptions.limit)
+            .map(toStored),
+          throughIndex,
+        }
+      },
+      async listSnapshots(sessionId) {
+        const prefix = `${sessionId}\u0000`
+        return [...snapshots.entries()]
+          .filter(([key]) => key.startsWith(prefix))
+          .map(([key, snapshot]) => ({
+            reducerName: key.slice(prefix.length),
+            index: snapshot.index,
+            updatedAt: new Date(snapshot.updatedAt),
+          }))
+          .toSorted((a, b) => a.reducerName.localeCompare(b.reducerName))
+      },
+    },
+
+    stream(sessionId, opts) {
+      const startAfter = opts?.startAfter ?? 0
+      return {
+        [Symbol.asyncIterator](): AsyncIterator<Event> {
+          let last = startAfter
+          const buffer: Row[] = []
+          let wake: (() => void) | null = null
+          let closed = false
+
+          const onRow = (row: Row): void => {
+            buffer.push(row)
+            wake?.()
+          }
+          let subs = streamSubscribers.get(sessionId)
+          if (!subs) {
+            subs = new Set()
+            streamSubscribers.set(sessionId, subs)
+          }
+          subs.add(onRow)
+          // Seed with history — synchronously, in the same tick as the
+          // subscription, so nothing can slip between the two.
+          const existing = sessions.get(sessionId) ?? []
+          buffer.unshift(...existing.filter((row) => row.index > startAfter))
+
+          const unsubscribe = (): void => {
+            subs.delete(onRow)
+            if (subs.size === 0) streamSubscribers.delete(sessionId)
+          }
+
+          return {
+            async next(): Promise<IteratorResult<Event>> {
+              for (;;) {
+                while (buffer.length > 0) {
+                  const row = buffer.shift()!
+                  if (row.index <= last) continue
+                  last = row.index
+                  return { value: toStored(row), done: false }
+                }
+                if (closed) return { value: undefined, done: true }
+                // oxlint-disable-next-line no-await-in-loop -- wait-for-wake
+                await new Promise<void>((resolve) => {
+                  wake = resolve
+                })
+                wake = null
+              }
+            },
+            async return(): Promise<IteratorResult<Event>> {
+              closed = true
+              unsubscribe()
+              wake?.()
+              return { value: undefined, done: true }
+            },
+          }
+        },
+      }
+    },
+  }
+}