experimental-a2 0.20.0 → 0.21.1

package/src/store-memory.ts

@@ -11,6 +11,7 @@ import { A2Error, supersededAttemptError } from './errors.ts'
 import { idempotentReplay } from './idempotent-replay.ts'
 import { nullProtoRecord } from './internal.ts'
 import { CLEAR_EVENT_TYPE, sessionClearedError } from './session-clear.ts'
+import { idleLogCursor } from './store-codec.ts'
 import {
   RANDOM_IDS,
   SYSTEM_CLOCK,
@@ -19,8 +20,13 @@ import {
   type Clock,
   type Event,
   type EventCause,
+  type HeadDispatch,
+  type HeadEvent,
+  type HeadRef,
   type IdSource,
   type PresenceRow,
+  type StoreConsumer,
+  type StoredCursor,
   type StoredEvent,
   type StoreStateRead,
 } from './store.ts'
@@ -40,20 +46,32 @@ type Row = {
   sessionId: string
   createdAt: Date
   cause: EventCause | null
+}
+
+type Dispatch = Omit<HeadDispatch, 'consumer' | 'lane'>
+
+type Completion = { attempt: number; returnedEventIds: string[] }
+
+/**
+ * One (consumer, lane) record. A log cursor reads the whole log by type, a
+ * lane cursor queues its lane's events, and a concurrent cursor (lane null)
+ * covers one event.
+ */
+type Cursor = {
+  consumer: string
   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
+  kind: 'log' | 'lane' | 'event'
+  position: number
+  head: number | null
+  dispatch: Dispatch
+  /** Lane cursors: the lane's event indexes in log order. */
+  queue: number[]
+  /** Lane cursors: where the head sits in `queue`. */
+  queued: number
+  /** Completions by head index; a log cursor keeps only its latest. */
+  completions: Map<number, Completion>
+  /** Log cursors: the types it takes, null for every type. */
+  types: readonly string[] | null
 }
 
 type PresenceEntry = {
@@ -63,12 +81,6 @@ type PresenceEntry = {
   expiresAt: Date
 }
 
-type LaneQueue = { rows: Row[]; head: number }
-type SessionDispatch = {
-  ready: Map<number, Row>
-  lanes: Map<string, LaneQueue>
-}
-
 /** Contiguous rows; `reclaim` removes from the front below `clearIndex`. */
 type SessionLog = {
   rows: Row[]
@@ -83,6 +95,22 @@ const RECLAIM_BATCH = 256
 const headOf = (log: SessionLog | undefined): number =>
   log ? log.offset + log.rows.length : 0
 
+const freshDispatch = (): Dispatch => ({
+  firstClaimedAt: null,
+  lastClaimedAt: null,
+  attemptCount: 0,
+  claimHolder: null,
+  claimExpiresAt: null,
+  failureCount: 0,
+  lastFailedAt: null,
+  lastFailedAttempt: null,
+  lastError: null,
+  failedAt: null,
+})
+
+const date = (value: Date | null): Date | null =>
+  value ? new Date(value) : null
+
 const toStored = (row: Row): StoredEvent => ({
   id: row.id,
   type: row.type,
@@ -91,20 +119,6 @@ const toStored = (row: Row): StoredEvent => ({
   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 => ({
@@ -116,18 +130,95 @@ const toEvent = (row: Row): Event => ({
   createdAt: new Date(row.createdAt),
 })
 
+const toHead = (cursor: Cursor, row: Row): HeadEvent => ({
+  ...toStored(row),
+  consumer: cursor.consumer,
+  lane: cursor.lane,
+  firstClaimedAt: date(cursor.dispatch.firstClaimedAt),
+  lastClaimedAt: date(cursor.dispatch.lastClaimedAt),
+  attemptCount: cursor.dispatch.attemptCount,
+  claimHolder: cursor.dispatch.claimHolder,
+  claimExpiresAt: date(cursor.dispatch.claimExpiresAt),
+  failureCount: cursor.dispatch.failureCount,
+  lastFailedAt: date(cursor.dispatch.lastFailedAt),
+  lastFailedAttempt: cursor.dispatch.lastFailedAttempt,
+  lastError: cursor.dispatch.lastError,
+  failedAt: date(cursor.dispatch.failedAt),
+})
+
+const toCursor = (cursor: Cursor): StoredCursor => ({
+  consumer: cursor.consumer,
+  lane: cursor.lane,
+  position: cursor.position,
+  head: cursor.head,
+  firstClaimedAt: date(cursor.dispatch.firstClaimedAt),
+  lastClaimedAt: date(cursor.dispatch.lastClaimedAt),
+  attemptCount: cursor.dispatch.attemptCount,
+  claimHolder: cursor.dispatch.claimHolder,
+  claimExpiresAt: date(cursor.dispatch.claimExpiresAt),
+  failureCount: cursor.dispatch.failureCount,
+  lastFailedAt: date(cursor.dispatch.lastFailedAt),
+  lastFailedAttempt: cursor.dispatch.lastFailedAttempt,
+  lastError: cursor.dispatch.lastError,
+  failedAt: date(cursor.dispatch.failedAt),
+})
+
+const compareText = (a: string, b: string): number =>
+  a < b ? -1 : a > b ? 1 : 0
+
+/** Consumer, then lane, with concurrent cursors last by head. */
+const byCursor = (a: StoredCursor, b: StoredCursor): number =>
+  compareText(a.consumer, b.consumer) ||
+  (a.lane === null
+    ? b.lane === null
+      ? (a.head ?? 0) - (b.head ?? 0)
+      : 1
+    : b.lane === null
+      ? -1
+      : compareText(a.lane, b.lane))
+
+const cursorKey = (
+  consumer: string,
+  lane: string | null,
+  index: number,
+): string =>
+  lane === null ? `${consumer}\u0000#${index}` : `${consumer}\u0000L${lane}`
+
+const takes = (types: readonly string[] | null, type: string): boolean =>
+  type !== CLEAR_EVENT_TYPE && (types === null || types.includes(type))
+
+const byHead = (a: HeadEvent, b: HeadEvent): number =>
+  a.index - b.index || compareText(a.consumer, b.consumer)
+
 const snapshotKey = (sessionId: string, reducerName: string): string =>
   `${sessionId}\u0000${reducerName}`
 
-const eventPinKey = (sessionId: string, index: number): string =>
-  `${sessionId}\u0000${index}`
+const headPinKey = (sessionId: string, ref: HeadRef): string =>
+  `${sessionId}\u0000${cursorKey(ref.consumer, ref.lane, ref.index)}\u0000${ref.index}`
+
+/** Whether a cursor belongs to a consumer the caller serves; omitted, every one. */
+const servedBy = (
+  consumers: readonly StoreConsumer[] | undefined,
+): ((cursor: Cursor) => boolean) => {
+  if (!consumers) return () => true
+  const names = new Set(consumers.map((consumer) => consumer.name))
+  return (cursor) => names.has(cursor.consumer)
+}
+
+/** A cursor's current head. */
+const refOf = (cursor: Cursor): HeadRef => ({
+  consumer: cursor.consumer,
+  lane: cursor.lane,
+  index: cursor.head!,
+})
 
 export function memory(options: MemoryStoreOptions = {}): A2Store {
   const clock = options.clock ?? SYSTEM_CLOCK
   const generateId = options.ids ?? RANDOM_IDS
 
   const sessions = new Map<string, SessionLog>()
-  const dispatch = new Map<string, SessionDispatch>()
+  /** Session id → cursor key → cursor. */
+  const cursors = new Map<string, Map<string, Cursor>>()
   /** 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. */
@@ -187,14 +278,26 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
       : row
   }
 
+  const cursorsOf = (sessionId: string): Map<string, Cursor> => {
+    let map = cursors.get(sessionId)
+    if (!map) {
+      map = new Map()
+      cursors.set(sessionId, map)
+    }
+    return map
+  }
+
+  const cursorAt = (sessionId: string, ref: HeadRef): Cursor | undefined =>
+    cursors.get(sessionId)?.get(cursorKey(ref.consumer, ref.lane, ref.index))
+
   const checkpointKey = (
     sessionId: string,
     reducerName: string,
     index: number,
   ): string => `${snapshotKey(sessionId, reducerName)}\u0000${index}`
 
-  const releaseSnapshotPins = (sessionId: string, eventIndex: number): void => {
-    const pinKey = eventPinKey(sessionId, eventIndex)
+  const releaseSnapshotPins = (sessionId: string, ref: HeadRef): void => {
+    const pinKey = headPinKey(sessionId, ref)
     const checkpoints = snapshotPins.get(pinKey)
     if (!checkpoints) return
     for (const key of checkpoints) {
@@ -209,114 +312,114 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
     snapshotPins.delete(pinKey)
   }
 
-  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)
+  /** The next event after `after` that a log cursor takes, or null. */
+  const nextLogHead = (
+    sessionId: string,
+    after: number,
+    types: readonly string[] | null,
+  ): number | null => {
+    const log = sessions.get(sessionId)
+    if (!log) return null
+    for (
+      let offset = Math.max(0, after - log.offset);
+      offset < log.rows.length;
+      offset += 1
+    ) {
+      const row = log.rows[offset]!
+      if (takes(types, row.type)) return row.index
     }
-    queue.rows.push(row)
-    if (queue.rows.length === 1) state.ready.set(row.index, row)
+    return null
   }
 
-  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
+  /** Moves a cursor past its head: the next head starts with fresh bookkeeping. */
+  const advance = (sessionId: string, cursor: Cursor): void => {
+    const done = cursor.head!
+    releaseSnapshotPins(sessionId, refOf(cursor))
+    cursor.position = done
+    cursor.dispatch = freshDispatch()
+    if (cursor.kind === 'event') {
+      cursor.head = null
+    } else if (cursor.kind === 'lane') {
+      cursor.queued += 1
+      cursor.head = cursor.queue[cursor.queued] ?? null
+    } else {
+      cursor.head = nextLogHead(sessionId, done, cursor.types)
     }
-    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 = rowAt(sessionId, index)
-    if (!row) {
-      throw new TypeError(
-        `no event at index ${index} in session '${sessionId}'`,
-      )
+  const hasPending = (
+    sessionId: string,
+    consumers: readonly StoreConsumer[] | undefined,
+  ): boolean => {
+    const served = servedBy(consumers)
+    for (const cursor of cursors.get(sessionId)?.values() ?? []) {
+      if (
+        cursor.head !== null &&
+        cursor.dispatch.failedAt === null &&
+        served(cursor)
+      ) {
+        return true
+      }
     }
-    return row
+    return false
   }
 
-  const hasPending = (sessionId: string): boolean => {
-    const log = sessions.get(sessionId)
-    return (log?.rows ?? []).some(
-      (row) => row.index > log!.clearIndex && row.processedAt === null,
-    )
-  }
-
-  const appendResult = (sessionId: string, events: StoredEvent[]) => ({
-    events,
-    hasPending: hasPending(sessionId),
-  })
-
-  /** The attempt-currency fence shared by handler appends and clears. */
+  /** The attempt-currency fence shared by consumer appends and clears. */
   const assertCurrentCause = (sessionId: string, cause: EventCause): void => {
     if (cause.index <= clearIndexOf(sessionId)) {
       throw supersededAttemptError(sessionId, cause)
     }
-    const parent = find(sessionId, cause.index)
-    if (parent.attemptCount !== cause.attempt || parent.failedAt !== null) {
+    const cursor = cursorAt(sessionId, cause)
+    if (
+      !cursor ||
+      cursor.head !== cause.index ||
+      cursor.dispatch.attemptCount !== cause.attempt ||
+      cursor.dispatch.failedAt !== null
+    ) {
       throw supersededAttemptError(sessionId, cause)
     }
   }
 
+  const deadLetter = (sessionId: string, cursor: Cursor, now: Date): void => {
+    cursor.dispatch.failedAt = new Date(now)
+    releaseSnapshotPins(sessionId, refOf(cursor))
+  }
+
   const claim = ({
     sessionId,
-    row,
+    cursor,
     holder,
     now,
     expiresAt,
     maxFailures,
   }: {
     sessionId: string
-    row: Row
+    cursor: Cursor
     holder: string
     now: Date
     expiresAt: Date
     maxFailures: number | undefined
-  }): StoredEvent => {
+  }): HeadEvent => {
+    const dispatch = cursor.dispatch
+    const row = rowAt(sessionId, cursor.head!)!
     // A claim still held here lapsed: its attempt never finished.
-    if (row.claimHolder !== null) {
-      row.failureCount += 1
-      if (maxFailures !== undefined && row.failureCount >= maxFailures) {
+    if (dispatch.claimHolder !== null) {
+      dispatch.failureCount += 1
+      if (maxFailures !== undefined && dispatch.failureCount >= maxFailures) {
         // Advancing the attempt fences the lapsed one; nothing runs.
-        row.attemptCount += 1
-        row.failedAt = new Date(now)
-        row.claimHolder = null
-        row.claimExpiresAt = null
-        dispatchOf(sessionId).ready.delete(row.index)
-        releaseSnapshotPins(sessionId, row.index)
-        return toStored(row)
+        dispatch.attemptCount += 1
+        dispatch.claimHolder = null
+        dispatch.claimExpiresAt = null
+        deadLetter(sessionId, cursor, now)
+        return toHead(cursor, row)
       }
     }
-    row.attemptCount += 1
-    row.firstClaimedAt ??= new Date(now)
-    row.lastClaimedAt = new Date(now)
-    row.claimHolder = holder
-    row.claimExpiresAt = new Date(expiresAt)
-    return toStored(row)
+    dispatch.attemptCount += 1
+    dispatch.firstClaimedAt ??= new Date(now)
+    dispatch.lastClaimedAt = new Date(now)
+    dispatch.claimHolder = holder
+    dispatch.claimExpiresAt = new Date(expiresAt)
+    return toHead(cursor, row)
   }
 
   const checkBatchIds = (
@@ -347,10 +450,105 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
     return existing
   }
 
+  /** Records the types a declared log consumer takes on its cursor. */
+  const refreshLogTypes = (
+    sessionId: string,
+    consumers: readonly StoreConsumer[] | undefined,
+  ): void => {
+    const map = cursors.get(sessionId)
+    if (!map) return
+    for (const consumer of consumers ?? []) {
+      if (!consumer.log) continue
+      const cursor = map.get(cursorKey(consumer.name, consumer.log.lane, 0))
+      if (cursor?.kind === 'log') cursor.types = consumer.log.types
+    }
+  }
+
+  /** Starts the cursor work an inserted batch carries. */
+  const enqueue = (
+    sessionId: string,
+    rows: readonly Row[],
+    events: readonly AppendEvent[],
+    base: number,
+    consumers: readonly StoreConsumer[] | undefined,
+  ): void => {
+    const map = cursorsOf(sessionId)
+    rows.forEach((row, offset) => {
+      for (const target of events[offset]!.targets ?? []) {
+        const key = cursorKey(target.consumer, target.lane, row.index)
+        if (target.lane === null) {
+          map.set(key, {
+            consumer: target.consumer,
+            lane: null,
+            kind: 'event',
+            position: row.index - 1,
+            head: row.index,
+            dispatch: freshDispatch(),
+            queue: [],
+            queued: 0,
+            completions: new Map(),
+            types: null,
+          })
+          continue
+        }
+        let cursor = map.get(key)
+        if (!cursor) {
+          cursor = {
+            consumer: target.consumer,
+            lane: target.lane,
+            kind: 'lane',
+            position: clearIndexOf(sessionId),
+            head: null,
+            dispatch: freshDispatch(),
+            queue: [],
+            queued: 0,
+            completions: new Map(),
+            types: null,
+          }
+          map.set(key, cursor)
+        }
+        cursor.queue.push(row.index)
+        cursor.head ??= row.index
+      }
+    })
+    const clearIndex = clearIndexOf(sessionId)
+    for (const consumer of consumers ?? []) {
+      const log = consumer.log
+      if (!log) continue
+      const first = rows.find((row) => takes(log.types, row.type))
+      if (!first) continue
+      const key = cursorKey(consumer.name, log.lane, 0)
+      const cursor = map.get(key)
+      if (!cursor) {
+        const position = log.backfill ? clearIndex : base
+        map.set(key, {
+          consumer: consumer.name,
+          lane: log.lane,
+          kind: 'log',
+          position,
+          head: log.backfill
+            ? nextLogHead(sessionId, position, log.types)
+            : first.index,
+          dispatch: freshDispatch(),
+          queue: [],
+          queued: 0,
+          completions: new Map(),
+          types: log.types,
+        })
+      } else {
+        cursor.types = log.types
+        // Not `first`: a deployment that doesn't serve this consumer may
+        // have appended events it takes since it went idle.
+        cursor.head ??= nextLogHead(sessionId, cursor.position, log.types)
+      }
+    }
+  }
+
   const insert = (
     sessionId: string,
     events: readonly AppendEvent[],
     now: Date,
+    consumers: readonly StoreConsumer[] | undefined,
     cause?: EventCause,
   ): Row[] => {
     const log = logOf(sessionId)
@@ -367,20 +565,6 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
         : 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 (ownerOf(sessionId, row.id)) {
@@ -393,8 +577,8 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
     for (const row of inserted) {
       log.rows.push(row)
       byEventId.set(row.id, row)
-      enqueue(sessionId, row)
     }
+    enqueue(sessionId, inserted, events, base, consumers)
     return inserted
   }
 
@@ -462,9 +646,31 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
     }
   }
 
+  /** The dead-lettered head a redrive names, or undefined. */
+  const deadHeadOf = (
+    sessionId: string,
+    consumer: string,
+    index: number,
+  ): Cursor | undefined => {
+    if (index <= clearIndexOf(sessionId)) return undefined
+    for (const cursor of cursors.get(sessionId)?.values() ?? []) {
+      if (
+        cursor.consumer === consumer &&
+        cursor.head === index &&
+        cursor.dispatch.failedAt !== null
+      ) {
+        return cursor
+      }
+    }
+    return undefined
+  }
+
   return {
     async append(sessionId, events, appendOptions) {
-      if (events.length === 0) return appendResult(sessionId, [])
+      const consumers = appendOptions?.consumers
+      if (events.length === 0) {
+        return { events: [], hasPending: hasPending(sessionId, consumers) }
+      }
 
       // Batch-scoped idempotency (a2-implementation.md §3): all ids
       // already present → lost-ack retry, return the original rows;
@@ -472,10 +678,10 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
       const existing = checkBatchIds(sessionId, events)
       if (existing.length > 0) {
         if (existing.length === events.length) {
-          return appendResult(
-            sessionId,
-            idempotentReplay(events, existing.map(toStored)),
-          )
+          return {
+            events: idempotentReplay(events, existing.map(toStored)),
+            hasPending: hasPending(sessionId, consumers),
+          }
         }
         throw new A2Error(
           'PARTIAL_DUPLICATE_BATCH',
@@ -489,16 +695,18 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
           `scheduled work from event ${originIndex} was cleared in session '${sessionId}'`,
         )
       }
-      // Attempt-currency fence: a fresh handler append commits only while
-      // its causal attempt is still the parent's latest (store.ts `append`).
+      // Attempt-currency fence: a fresh consumer append commits only while
+      // its causal attempt still owns the cursor's head (store.ts `append`).
       for (const event of events) {
         if (event.cause) assertCurrentCause(sessionId, event.cause)
       }
 
-      const now = clock.now()
-      const inserted = insert(sessionId, events, now)
+      const inserted = insert(sessionId, events, clock.now(), consumers)
       notifyStreams(sessionId, inserted)
-      return appendResult(sessionId, inserted.map(toStored))
+      return {
+        events: inserted.map(toStored),
+        hasPending: hasPending(sessionId, consumers),
+      }
     },
 
     async clear({ sessionId, ifLastIndex, cause }) {
@@ -517,12 +725,25 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
       }
       const [marker] = insert(
         sessionId,
-        [{ type: CLEAR_EVENT_TYPE, payload: null, settled: true }],
+        [{ type: CLEAR_EVENT_TYPE, payload: null }],
         clock.now(),
+        undefined,
       )
       logOf(sessionId).clearIndex = marker!.index
-      // Every row is at or below the marker, so no dispatch state survives.
-      dispatch.delete(sessionId)
+      // Every event is at or below the marker: no head survives, and log
+      // cursors count from the marker.
+      const map = cursors.get(sessionId)
+      for (const [key, cursor] of map ?? []) {
+        if (cursor.head !== null) releaseSnapshotPins(sessionId, refOf(cursor))
+        if (cursor.kind !== 'log') {
+          map!.delete(key)
+          continue
+        }
+        cursor.position = marker!.index
+        cursor.head = null
+        cursor.dispatch = freshDispatch()
+        cursor.completions.clear()
+      }
       notifyStreams(sessionId, [marker!])
       return { cleared: true, index: marker!.index, clearIndex: marker!.index }
     },
@@ -540,7 +761,6 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
       for (const row of removed) {
         // A reused id belongs to its new row now.
         if (byEventId.get(row.id) === row) byEventId.delete(row.id)
-        releaseSnapshotPins(sessionId, row.index)
       }
       const done = log.offset === log.clearIndex - 1
       // Writes below the marker are dropped, so one sweep at the end suffices.
@@ -548,6 +768,49 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
       return { deleted: removed.length, done }
     },
 
+    async wakeLog({ sessionId, consumer }) {
+      const { log } = consumer
+      const key = cursorKey(consumer.name, log.lane, 0)
+      const head = headOf(sessions.get(sessionId))
+      let cursor = cursors.get(sessionId)?.get(key)
+      if (!cursor) {
+        const marker = clearIndexOf(sessionId)
+        if (head === marker) {
+          return {
+            cursor: idleLogCursor(consumer.name, log.lane, marker),
+            head,
+          }
+        }
+        const position = log.backfill ? marker : head
+        cursor = {
+          consumer: consumer.name,
+          lane: log.lane,
+          kind: 'log',
+          position,
+          head: log.backfill
+            ? nextLogHead(sessionId, position, log.types)
+            : null,
+          dispatch: freshDispatch(),
+          queue: [],
+          queued: 0,
+          completions: new Map(),
+          types: log.types,
+        }
+        cursorsOf(sessionId).set(key, cursor)
+      } else {
+        cursor.types = log.types
+        cursor.head ??= nextLogHead(sessionId, cursor.position, log.types)
+      }
+      return { cursor: toCursor(cursor), head }
+    },
+
+    async cursors(sessionId) {
+      return [...(cursors.get(sessionId)?.values() ?? [])]
+        .filter((cursor) => cursor.kind !== 'event' || cursor.head !== null)
+        .map(toCursor)
+        .toSorted(byCursor)
+    },
+
     async read(sessionId, opts) {
       const log = sessions.get(sessionId)
       if (!log) return []
@@ -569,46 +832,64 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
       holder,
       ttlMs,
       expiresAtMs,
-      excludeIndexes,
+      exclude,
+      consumers,
       maxFailures,
+      through,
     }) {
+      refreshLogTypes(sessionId, consumers)
       const claimedAt = clock.now()
       const now = claimedAt.getTime()
       const expiresAt = new Date(expiresAtMs ?? now + ttlMs)
-      const excluded = new Set(excludeIndexes ?? [])
-      const eligible: Row[] = []
+      const excluded = new Set(
+        (exclude ?? []).map((ref) =>
+          cursorKey(ref.consumer, ref.lane, ref.index),
+        ),
+      )
+      const served = servedBy(consumers)
+      const eligible: Cursor[] = []
       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)
-          }
+      for (const [key, cursor] of cursors.get(sessionId) ?? []) {
+        if (
+          cursor.head === null ||
+          (through !== undefined && cursor.head > through) ||
+          cursor.dispatch.failedAt !== null ||
+          !served(cursor) ||
+          excluded.has(key)
+        ) {
+          continue
+        }
+        const expiry = cursor.dispatch.claimExpiresAt
+        if (expiry && expiry.getTime() > now) {
+          if (!retryAt || expiry < retryAt) retryAt = new Date(expiry)
           continue
         }
-        eligible.push(row)
+        eligible.push(cursor)
       }
 
       if (eligible.length === 0) {
         return retryAt ? { outcome: 'busy', retryAt } : { outcome: 'settled' }
       }
-      eligible.sort((a, b) => a.index - b.index)
       const clearIndex = clearIndexOf(sessionId)
-      return {
-        outcome: 'claimed',
-        events: eligible.map((row) => {
-          const claimed = claim({
+      const claimed = eligible
+        .map((cursor) => {
+          const head = claim({
             sessionId,
-            row,
+            cursor,
             holder,
             now: claimedAt,
             expiresAt,
             maxFailures,
           })
-          if (clearIndex > 0) claimed.clearIndex = clearIndex
-          return claimed
-        }),
+          if (clearIndex > 0) head.clearIndex = clearIndex
+          return head
+        })
+        .toSorted(byHead)
+      return {
+        outcome: 'claimed',
+        events: claimed,
+        head: headOf(sessions.get(sessionId)),
       }
     },
 
@@ -616,48 +897,69 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
       const now = clock.now()
       const expiresAt = new Date(expiresAtMs ?? now.getTime() + ttlMs)
       const clearIndex = clearIndexOf(sessionId)
-      const renewed: number[] = []
-      const superseded: number[] = []
-      for (const { index, attempt } of claims.toSorted(
-        (a, b) => a.index - b.index,
-      )) {
-        if (index <= clearIndex) {
-          superseded.push(index)
+      const renewed: HeadRef[] = []
+      const superseded: HeadRef[] = []
+      const ordered = claims.toSorted(
+        (a, b) => a.index - b.index || compareText(a.consumer, b.consumer),
+      )
+      for (const { attempt, ...ref } of ordered) {
+        if (ref.index <= clearIndex) {
+          superseded.push(ref)
           continue
         }
-        const row = rowAt(sessionId, index)
-        if (!row) continue
-        if (row.attemptCount > attempt) {
-          superseded.push(row.index)
+        const cursor = cursorAt(sessionId, ref)
+        if (!cursor) continue
+        const dispatch = cursor.dispatch
+        // An event the cursor has not reached yet holds no claim to renew.
+        if (cursor.head !== ref.index && cursor.position < ref.index) continue
+        if (cursor.head !== ref.index || dispatch.attemptCount > attempt) {
+          superseded.push(ref)
           continue
         }
         if (
-          row.processedAt === null &&
-          row.failedAt === null &&
-          row.claimHolder === holder &&
-          row.claimExpiresAt !== null &&
-          row.claimExpiresAt > now
+          dispatch.failedAt === null &&
+          dispatch.claimHolder === holder &&
+          dispatch.claimExpiresAt !== null &&
+          dispatch.claimExpiresAt > now
         ) {
-          row.claimExpiresAt = new Date(expiresAt)
-          renewed.push(row.index)
+          dispatch.claimExpiresAt = new Date(expiresAt)
+          renewed.push(ref)
         }
       }
       return { renewed, superseded }
     },
 
-    async completeAttempt({ sessionId, index, attempt, events }) {
+    async completeAttempt({
+      sessionId,
+      consumer,
+      lane,
+      index,
+      attempt,
+      events,
+      consumers,
+    }) {
       if (index <= clearIndexOf(sessionId)) return { outcome: 'superseded' }
-      const parent = find(sessionId, index)
-      const cause = { index, attempt }
-      if (parent.processedAt !== null) {
-        if (parent.processedByAttempt !== attempt) {
+      const ref = { consumer, lane, index }
+      const cursor = cursorAt(sessionId, ref)
+      if (!cursor) {
+        if (!rowAt(sessionId, index)) {
+          throw new TypeError(
+            `no event at index ${index} in session '${sessionId}'`,
+          )
+        }
+        return { outcome: 'superseded' }
+      }
+      refreshLogTypes(sessionId, consumers)
+
+      if (cursor.head !== index) {
+        const completion = cursor.completions.get(index)
+        if (!completion || completion.attempt !== attempt) {
           return { outcome: 'superseded' }
         }
         const requestedIds = events.map((event) => event.id)
         if (
-          parent.returnedEventIds === null ||
-          parent.returnedEventIds.length !== requestedIds.length ||
-          parent.returnedEventIds.some(
+          completion.returnedEventIds.length !== requestedIds.length ||
+          completion.returnedEventIds.some(
             (id, offset) => id !== requestedIds[offset],
           )
         ) {
@@ -671,7 +973,10 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
           existing.length !== events.length ||
           existing.some(
             (row) =>
-              row.cause?.index !== index || row.cause.attempt !== attempt,
+              row.cause?.consumer !== consumer ||
+              row.cause.lane !== lane ||
+              row.cause.index !== index ||
+              row.cause.attempt !== attempt,
           )
         ) {
           throw new A2Error(
@@ -681,13 +986,17 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
         }
         return {
           outcome: 'completed',
-          events: idempotentReplay(events, existing.map(toStored)),
+          events:
+            events.length === 0
+              ? []
+              : idempotentReplay(events, existing.map(toStored)),
         }
       }
+      const dispatch = cursor.dispatch
       if (
-        parent.attemptCount !== attempt ||
-        parent.failedAt !== null ||
-        parent.claimHolder === null
+        dispatch.attemptCount !== attempt ||
+        dispatch.failedAt !== null ||
+        dispatch.claimHolder === null
       ) {
         return { outcome: 'superseded' }
       }
@@ -699,21 +1008,26 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
           '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)
-      releaseSnapshotPins(sessionId, index)
+      const inserted = insert(sessionId, events, clock.now(), consumers, {
+        consumer,
+        lane,
+        index,
+        attempt,
+      })
+      if (cursor.kind === 'log') cursor.completions.clear()
+      cursor.completions.set(index, {
+        attempt,
+        returnedEventIds: events.map((event) => event.id),
+      })
+      advance(sessionId, cursor)
       notifyStreams(sessionId, inserted)
       return { outcome: 'completed', events: inserted.map(toStored) }
     },
 
     async failAttempt({
       sessionId,
+      consumer,
+      lane,
       index,
       attempt,
       error,
@@ -723,76 +1037,88 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
       if (index <= clearIndexOf(sessionId)) {
         return { outcome: 'superseded', failureCount: 0 }
       }
-      const row = find(sessionId, index)
+      const cursor = cursorAt(sessionId, { consumer, lane, index })
+      if (!cursor) {
+        if (!rowAt(sessionId, index)) {
+          throw new TypeError(
+            `no event at index ${index} in session '${sessionId}'`,
+          )
+        }
+        return { outcome: 'superseded', failureCount: 0 }
+      }
+      const dispatch = cursor.dispatch
       if (
-        row.processedAt ||
-        row.attemptCount !== attempt ||
-        (row.claimHolder === null && row.lastFailedAttempt !== attempt)
+        cursor.head !== index ||
+        dispatch.attemptCount !== attempt ||
+        (dispatch.claimHolder === null &&
+          dispatch.lastFailedAttempt !== attempt)
       ) {
-        return { outcome: 'superseded', failureCount: row.failureCount }
+        return {
+          outcome: 'superseded',
+          failureCount: cursor.head === index ? dispatch.failureCount : 0,
+        }
       }
-      if (row.lastFailedAttempt === attempt && row.claimHolder === null) {
+      if (
+        dispatch.lastFailedAttempt === attempt &&
+        dispatch.claimHolder === null
+      ) {
         return {
-          outcome: row.failedAt ? 'dead_lettered' : 'failed',
-          failureCount: row.failureCount,
+          outcome: dispatch.failedAt ? 'dead_lettered' : 'failed',
+          failureCount: dispatch.failureCount,
         }
       }
-      if (row.failedAt) {
-        return { outcome: 'dead_lettered', failureCount: row.failureCount }
+      if (dispatch.failedAt) {
+        return { outcome: 'dead_lettered', failureCount: dispatch.failureCount }
       }
-      row.failureCount += 1
-      row.lastError = error
+      dispatch.failureCount += 1
+      dispatch.lastError = error
       const failedAt = clock.now()
-      row.lastFailedAt = new Date(failedAt)
-      row.lastFailedAttempt = attempt
-      row.claimHolder = null
-      row.claimExpiresAt =
-        retryAfterMs === undefined || row.failureCount >= maxFailures
+      dispatch.lastFailedAt = new Date(failedAt)
+      dispatch.lastFailedAttempt = attempt
+      dispatch.claimHolder = null
+      dispatch.claimExpiresAt =
+        retryAfterMs === undefined || dispatch.failureCount >= maxFailures
           ? null
           : new Date(failedAt.getTime() + retryAfterMs)
-      if (row.failureCount >= maxFailures) {
-        row.failedAt = new Date(failedAt)
-        dispatchOf(sessionId).ready.delete(row.index)
-        releaseSnapshotPins(sessionId, index)
+      if (dispatch.failureCount >= maxFailures) {
+        deadLetter(sessionId, cursor, failedAt)
         return {
           outcome: 'dead_lettered',
-          failureCount: row.failureCount,
+          failureCount: dispatch.failureCount,
         }
       }
-      return { outcome: 'failed', failureCount: row.failureCount }
+      return { outcome: 'failed', failureCount: dispatch.failureCount }
     },
 
     async deadLetters(sessionId) {
-      const log = sessions.get(sessionId)
-      return (log?.rows ?? [])
-        .filter(
-          (row) =>
-            row.index > log!.clearIndex &&
-            row.processedAt === null &&
-            row.failedAt !== null,
-        )
-        .map(toStored)
+      const clearIndex = clearIndexOf(sessionId)
+      const dead: HeadEvent[] = []
+      for (const cursor of cursors.get(sessionId)?.values() ?? []) {
+        if (
+          cursor.head === null ||
+          cursor.head <= clearIndex ||
+          cursor.dispatch.failedAt === null
+        ) {
+          continue
+        }
+        dead.push(toHead(cursor, rowAt(sessionId, cursor.head)!))
+      }
+      return dead.toSorted(byHead)
     },
 
-    async redrive({ sessionId, index, action }) {
-      const row =
-        index > clearIndexOf(sessionId) ? rowAt(sessionId, index) : undefined
-      if (!row || row.processedAt !== null || row.failedAt === null) {
-        return { redriven: false, hasPending: hasPending(sessionId) }
+    async redrive({ sessionId, consumer, index, action, consumers }) {
+      const cursor = deadHeadOf(sessionId, consumer, index)
+      if (!cursor) {
+        return { redriven: false, hasPending: hasPending(sessionId, consumers) }
       }
+      refreshLogTypes(sessionId, consumers)
       if (action === 'skip') {
-        row.processedAt = clock.now()
-        settle(sessionId, row)
+        advance(sessionId, cursor)
       } else {
-        row.failedAt = null
-        row.failureCount = 0
-        const state = dispatchOf(sessionId)
-        const queue = row.lane === null ? undefined : state.lanes.get(row.lane)
-        if (row.lane === null || queue?.rows[queue.head] === row) {
-          state.ready.set(row.index, row)
-        }
+        cursor.dispatch.failedAt = null
+        cursor.dispatch.failureCount = 0
       }
-      return { redriven: true, hasPending: hasPending(sessionId) }
+      return { redriven: true, hasPending: hasPending(sessionId, consumers) }
     },
 
     async readState(sessionId, reducerName, stateOptions) {
@@ -821,17 +1147,17 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
       for (const write of writes.toSorted((a, b) => a.index - b.index)) {
         if (write.index < clearIndex) continue
         const checkpoint = checkpointKey(sessionId, reducerName, write.index)
-        for (const eventIndex of write.pinEventIndexes ?? []) {
-          const event = rowAt(sessionId, eventIndex)
+        for (const pin of write.pins ?? []) {
+          const cursor = cursorAt(sessionId, pin)
           if (
-            !event ||
-            event.index <= clearIndex ||
-            event.processedAt !== null ||
-            event.failedAt !== null
+            !cursor ||
+            pin.index <= clearIndex ||
+            cursor.head !== pin.index ||
+            cursor.dispatch.failedAt !== null
           ) {
             continue
           }
-          const pinKey = eventPinKey(sessionId, eventIndex)
+          const pinKey = headPinKey(sessionId, pin)
           let pinned = snapshotPins.get(pinKey)
           if (!pinned) {
             pinned = new Set()