experimental-a2 0.16.1 → 0.18.0

package/src/store-memory.ts

@@ -7,9 +7,10 @@
  */
 
 import type { PresencePatch } from './contract.ts'
-import { A2Error } from './errors.ts'
+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 {
   RANDOM_IDS,
   SYSTEM_CLOCK,
@@ -68,6 +69,20 @@ type SessionDispatch = {
   lanes: Map<string, LaneQueue>
 }
 
+/** Contiguous rows; `reclaim` removes from the front below `clearIndex`. */
+type SessionLog = {
+  rows: Row[]
+  /** Index of the event before `rows[0]`. */
+  offset: number
+  /** Latest clear marker, or 0. */
+  clearIndex: number
+}
+
+const RECLAIM_BATCH = 256
+
+const headOf = (log: SessionLog | undefined): number =>
+  log ? log.offset + log.rows.length : 0
+
 const toStored = (row: Row): StoredEvent => ({
   id: row.id,
   type: row.type,
@@ -111,7 +126,7 @@ 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 sessions = new Map<string, SessionLog>()
   const dispatch = new Map<string, SessionDispatch>()
   /** Global unique index on event ids, like the SQL schema's. */
   const byEventId = new Map<string, Row>()
@@ -145,13 +160,31 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
     }
   }
 
-  const rowsOf = (sessionId: string): Row[] => {
-    let rows = sessions.get(sessionId)
-    if (!rows) {
-      rows = []
-      sessions.set(sessionId, rows)
+  const logOf = (sessionId: string): SessionLog => {
+    let log = sessions.get(sessionId)
+    if (!log) {
+      log = { rows: [], offset: 0, clearIndex: 0 }
+      sessions.set(sessionId, log)
     }
-    return rows
+    return log
+  }
+
+  const rowAt = (sessionId: string, index: number): Row | undefined => {
+    const log = sessions.get(sessionId)
+    return log && index > log.offset
+      ? log.rows[index - log.offset - 1]
+      : undefined
+  }
+
+  const clearIndexOf = (sessionId: string): number =>
+    sessions.get(sessionId)?.clearIndex ?? 0
+
+  /** The row owning `id`, ignoring this session's rows below its clear. */
+  const ownerOf = (sessionId: string, id: string): Row | undefined => {
+    const row = byEventId.get(id)
+    return row?.sessionId === sessionId && row.index < clearIndexOf(sessionId)
+      ? undefined
+      : row
   }
 
   const checkpointKey = (
@@ -217,7 +250,7 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
   }
 
   const find = (sessionId: string, index: number): Row => {
-    const row = sessions.get(sessionId)?.[index - 1]
+    const row = rowAt(sessionId, index)
     if (!row) {
       throw new TypeError(
         `no event at index ${index} in session '${sessionId}'`,
@@ -226,13 +259,29 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
     return row
   }
 
+  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: (sessions.get(sessionId) ?? []).some(
-      (row) => row.processedAt === null,
-    ),
+    hasPending: hasPending(sessionId),
   })
 
+  /** The attempt-currency fence shared by handler 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) {
+      throw supersededAttemptError(sessionId, cause)
+    }
+  }
+
   const claim = (
     row: Row,
     holder: string,
@@ -263,7 +312,7 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
       )
     }
     const existing = supplied
-      .map((candidate) => byEventId.get(candidate.id))
+      .map((candidate) => ownerOf(sessionId, candidate.id))
       .filter((row): row is Row => row !== undefined)
     const foreign = existing.find((row) => row.sessionId !== sessionId)
     if (foreign) {
@@ -281,8 +330,8 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
     now: Date,
     cause?: EventCause,
   ): Row[] => {
-    const rows = rowsOf(sessionId)
-    const base = rows.length === 0 ? 0 : rows[rows.length - 1]!.index
+    const log = logOf(sessionId)
+    const base = headOf(log)
     const inserted = events.map((candidate, offset): Row => ({
       id: candidate.id ?? generateId(),
       type: candidate.type,
@@ -311,7 +360,7 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
       failedAt: null,
     }))
     for (const row of inserted) {
-      if (byEventId.has(row.id)) {
+      if (ownerOf(sessionId, row.id)) {
         throw new A2Error(
           'PARTIAL_DUPLICATE_BATCH',
           `event id '${row.id}' already exists`,
@@ -319,13 +368,31 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
       }
     }
     for (const row of inserted) {
-      rows.push(row)
+      log.rows.push(row)
       byEventId.set(row.id, row)
       enqueue(sessionId, row)
     }
     return inserted
   }
 
+  /** Every cached fold of this session below its clear, head or historical. */
+  const dropCheckpointsBelow = (
+    sessionId: string,
+    clearIndex: number,
+  ): void => {
+    const prefix = `${sessionId}\u0000`
+    for (const [key, snapshot] of snapshots) {
+      if (!key.startsWith(prefix) || snapshot.index >= clearIndex) continue
+      snapshots.delete(key)
+      snapshotPinCounts.delete(`${key}\u0000${snapshot.index}`)
+    }
+    for (const [key, snapshot] of historicalSnapshots) {
+      if (!key.startsWith(prefix) || snapshot.index >= clearIndex) continue
+      historicalSnapshots.delete(key)
+      snapshotPinCounts.delete(key)
+    }
+  }
+
   const readStateOf = (
     sessionId: string,
     reducerName: string,
@@ -333,8 +400,10 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
     snapshotThroughIndex?: number,
   ): StoreStateRead => {
     const key = snapshotKey(sessionId, reducerName)
+    const clearIndex = clearIndexOf(sessionId)
     const snapshotFrontier = snapshotThroughIndex ?? throughIndex
-    const head = snapshots.get(key)
+    const stored = snapshots.get(key)
+    const head = stored && stored.index >= clearIndex ? stored : undefined
     let candidate =
       head && (snapshotFrontier === undefined || head.index <= snapshotFrontier)
         ? head
@@ -344,6 +413,7 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
       for (const [historicalKey, snapshot] of historicalSnapshots) {
         if (
           historicalKey.startsWith(prefix) &&
+          snapshot.index >= clearIndex &&
           snapshot.index <= snapshotFrontier &&
           (!candidate || snapshot.index > candidate.index)
         ) {
@@ -354,22 +424,23 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
     const snapshot = candidate
       ? { index: candidate.index, state: structuredClone(candidate.state) }
       : null
-    const afterIndex = snapshot?.index ?? 0
+    const afterIndex = Math.max(snapshot?.index ?? 0, clearIndex - 1)
     return {
       headIndex: head?.index ?? null,
       snapshot,
-      events: (sessions.get(sessionId) ?? [])
+      events: (sessions.get(sessionId)?.rows ?? [])
         .filter(
           (row) =>
             row.index > afterIndex &&
             (throughIndex === undefined || row.index <= throughIndex),
         )
         .map(toEvent),
+      ...(clearIndex > 0 ? { clearIndex } : {}),
     }
   }
 
   return {
-    async append(sessionId, events) {
+    async append(sessionId, events, appendOptions) {
       if (events.length === 0) return appendResult(sessionId, [])
 
       // Batch-scoped idempotency (a2-implementation.md §3): all ids
@@ -389,26 +460,16 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
         )
       }
 
+      const originIndex = appendOptions?.originIndex
+      if (originIndex !== undefined && originIndex <= clearIndexOf(sessionId)) {
+        throw sessionClearedError(
+          `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`).
-      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}'`,
-          )
-        }
+        if (event.cause) assertCurrentCause(sessionId, event.cause)
       }
 
       const now = clock.now()
@@ -417,11 +478,67 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
       return appendResult(sessionId, inserted.map(toStored))
     },
 
+    async clear({ sessionId, ifLastIndex, cause }) {
+      if (cause) assertCurrentCause(sessionId, cause)
+      const log = sessions.get(sessionId)
+      const head = headOf(log)
+      const clearIndex = log?.clearIndex ?? 0
+      if (ifLastIndex !== undefined && clearIndex === ifLastIndex + 1) {
+        return { cleared: true, index: head, clearIndex }
+      }
+      if (ifLastIndex !== undefined && ifLastIndex !== head) {
+        return { cleared: false, index: head, clearIndex }
+      }
+      if (head === 0 || clearIndex === head) {
+        return { cleared: true, index: head, clearIndex }
+      }
+      const [marker] = insert(
+        sessionId,
+        [{ type: CLEAR_EVENT_TYPE, payload: null, settled: true }],
+        clock.now(),
+      )
+      logOf(sessionId).clearIndex = marker!.index
+      // Every row is at or below the marker, so no dispatch state survives.
+      dispatch.delete(sessionId)
+      notifyStreams(sessionId, [marker!])
+      return { cleared: true, index: marker!.index, clearIndex: marker!.index }
+    },
+
+    async reclaim(sessionId) {
+      const log = sessions.get(sessionId)
+      if (!log || log.offset >= log.clearIndex - 1) {
+        return { deleted: 0, done: true }
+      }
+      const removed = log.rows.splice(
+        0,
+        Math.min(RECLAIM_BATCH, log.clearIndex - 1 - log.offset),
+      )
+      log.offset += removed.length
+      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.
+      if (done) dropCheckpointsBelow(sessionId, log.clearIndex)
+      return { deleted: removed.length, done }
+    },
+
     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)
+      const log = sessions.get(sessionId)
+      if (!log) return []
+      const head = headOf(log)
+      const after = Math.max(
+        opts?.afterIndex ?? 0,
+        log.clearIndex - 1,
+        log.offset,
+      )
+      const through = Math.min(opts?.throughIndex ?? head, head)
+      if (through <= after) return []
+      return log.rows
+        .slice(after - log.offset, through - log.offset)
+        .map(toStored)
     },
 
     async claimAvailable({
@@ -453,21 +570,32 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
         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) => claim(row, holder, claimedAt, expiresAt)),
+        events: eligible.map((row) => {
+          const claimed = claim(row, holder, claimedAt, expiresAt)
+          if (clearIndex > 0) claimed.clearIndex = clearIndex
+          return claimed
+        }),
       }
     },
 
     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 clearIndex = clearIndexOf(sessionId)
       const renewed: number[] = []
       const superseded: number[] = []
-      for (const row of sessions.get(sessionId) ?? []) {
-        const attempt = requested.get(row.index)
-        if (attempt === undefined) continue
+      for (const { index, attempt } of claims.toSorted(
+        (a, b) => a.index - b.index,
+      )) {
+        if (index <= clearIndex) {
+          superseded.push(index)
+          continue
+        }
+        const row = rowAt(sessionId, index)
+        if (!row) continue
         if (row.attemptCount > attempt) {
           superseded.push(row.index)
           continue
@@ -487,6 +615,7 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
     },
 
     async completeAttempt({ sessionId, index, attempt, events }) {
+      if (index <= clearIndexOf(sessionId)) return { outcome: 'superseded' }
       const parent = find(sessionId, index)
       const cause = { index, attempt }
       if (parent.processedAt !== null) {
@@ -553,6 +682,9 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
     },
 
     async failAttempt({ sessionId, index, attempt, error, maxFailures }) {
+      if (index <= clearIndexOf(sessionId)) {
+        return { outcome: 'superseded', failureCount: 0 }
+      }
       const row = find(sessionId, index)
       if (
         row.processedAt ||
@@ -589,6 +721,39 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
       return { outcome: 'failed', failureCount: row.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)
+    },
+
+    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) }
+      }
+      if (action === 'skip') {
+        row.processedAt = clock.now()
+        settle(sessionId, row)
+      } 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)
+        }
+      }
+      return { redriven: true, hasPending: hasPending(sessionId) }
+    },
+
     async readState(sessionId, reducerName, stateOptions) {
       return readStateOf(
         sessionId,
@@ -611,11 +776,18 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
 
     async putSnapshots(sessionId, reducerName, writes) {
       const key = snapshotKey(sessionId, reducerName)
+      const clearIndex = clearIndexOf(sessionId)
       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 = sessions.get(sessionId)?.[eventIndex - 1]
-          if (!event || event.processedAt !== null || event.failedAt !== null) {
+          const event = rowAt(sessionId, eventIndex)
+          if (
+            !event ||
+            event.index <= clearIndex ||
+            event.processedAt !== null ||
+            event.failedAt !== null
+          ) {
             continue
           }
           const pinKey = eventPinKey(sessionId, eventIndex)
@@ -635,7 +807,11 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
 
         const current = snapshots.get(key)
         if (!current || write.index >= current.index) {
-          if (current && write.index > current.index) {
+          if (
+            current &&
+            write.index > current.index &&
+            current.index >= clearIndex
+          ) {
             const currentCheckpoint = checkpointKey(
               sessionId,
               reducerName,
@@ -769,13 +945,11 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
       const startAfter = opts?.startAfter ?? 0
       return {
         [Symbol.asyncIterator](): AsyncIterator<Event> {
-          let last = startAfter
-          const buffer: Row[] = []
+          let last = Math.max(startAfter, clearIndexOf(sessionId) - 1)
           let wake: (() => void) | null = null
           let closed = false
 
-          const onRow = (row: Row): void => {
-            buffer.push(row)
+          const onRow = (): void => {
             wake?.()
           }
           let subs = streamSubscribers.get(sessionId)
@@ -784,37 +958,40 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
             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 => {
+          const stop = (): void => {
+            if (closed) return
+            closed = true
             subs.delete(onRow)
             if (subs.size === 0) streamSubscribers.delete(sessionId)
+            wake?.()
           }
 
           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 }
+              try {
+                for (;;) {
+                  if (closed) return { value: undefined, done: true }
+                  const log = sessions.get(sessionId)
+                  // Rows reclaimed behind a running stream are skipped.
+                  const row = log?.rows[Math.max(0, last - log.offset)]
+                  if (row) {
+                    const value = toStored(row)
+                    last = row.index
+                    return { value, done: false }
+                  }
+                  // oxlint-disable-next-line no-await-in-loop -- wait-for-wake
+                  await new Promise<void>((resolve) => {
+                    wake = resolve
+                  })
+                  wake = null
                 }
-                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
+              } catch (error) {
+                stop()
+                throw error
               }
             },
             async return(): Promise<IteratorResult<Event>> {
-              closed = true
-              unsubscribe()
-              wake?.()
+              stop()
               return { value: undefined, done: true }
             },
           }

package/src/store-polling.ts

@@ -66,7 +66,8 @@ export function pollingStream(
   return {
     [Symbol.asyncIterator](): AsyncIterator<Event> {
       let last = startAfter
-      let buffer: Event[] = []
+      let buffer: Array<Event | undefined> = []
+      let position = 0
       let closed = false
       let pending: Sleeper | null = null
       let interval = floor()
@@ -83,18 +84,29 @@ export function pollingStream(
           for (;;) {
             if (closed) return { value: undefined, done: true }
             try {
-              // oxlint-disable-next-line no-await-in-loop -- poll loop
-              if (buffer.length === 0) buffer = await readAfter(last)
+              if (position === buffer.length) {
+                // oxlint-disable-next-line no-await-in-loop -- poll loop
+                const rows = await readAfter(last)
+                if (closed) return { value: undefined, done: true }
+                buffer = rows
+                position = 0
+              }
             } catch (error) {
               if (closed) return { value: undefined, done: true }
               throw error
             }
             if (closed) return { value: undefined, done: true }
-            const row = buffer.shift()
+            const row = buffer[position]
             if (row) {
               // Activity: tighten back to the floor.
               activity.activate()
               last = row.index
+              buffer[position] = undefined
+              position += 1
+              if (position === buffer.length) {
+                buffer = []
+                position = 0
+              }
               return { value: row, done: false }
             }
             // Empty poll: wait, then back off toward the idle ceiling.
@@ -111,6 +123,8 @@ export function pollingStream(
         },
         async return(): Promise<IteratorResult<Event>> {
           closed = true
+          buffer = []
+          position = 0
           pending?.cancel()
           return { value: undefined, done: true }
         },