experimental-a2 0.16.1 → 0.18.0

package/src/store-postgres.ts

@@ -16,8 +16,9 @@
  * assignment.
  */
 
-import { A2Error } from './errors.ts'
+import { A2Error, supersededAttemptError } from './errors.ts'
 import { idempotentReplay } from './idempotent-replay.ts'
+import { CLEAR_EVENT_TYPE, sessionClearedError } from './session-clear.ts'
 import { decodeReturnedEventIds } from './store-codec.ts'
 import { pollingStream, defaultSleep, type Sleeper } from './store-polling.ts'
 import { NOTIFY_TIMINGS, nullProtoRecord } from './internal.ts'
@@ -159,6 +160,11 @@ create table if not exists a2_snapshot_pins (
 create index if not exists a2_snapshot_pins_checkpoint
   on a2_snapshot_pins (session_id, reducer_name, up_to_index);
 
+create table if not exists a2_clears (
+  session_id  text   primary key,
+  clear_index bigint not null
+);
+
 create table if not exists a2_presence (
   ns          text   not null,
   participant text   not null,
@@ -173,6 +179,17 @@ create table if not exists a2_presence (
 
 const asNumber = (value: unknown): number => Number(value) // bigint columns arrive as strings
 
+/**
+ * The session's latest clear marker, or 0, as a primary-key subquery. Read
+ * it in a statement that runs after the operation's lock: a statement's
+ * snapshot starts with the statement, so one that waited for the lock could
+ * miss a clear that committed meanwhile.
+ */
+const clearIndexOf = (session: string): string =>
+  `coalesce((select clear_index from a2_clears where session_id = ${session}), 0)`
+
+const RECLAIM_BATCH = 256
+
 const toDate = (ms: unknown): Date | null =>
   ms === null || ms === undefined ? null : new Date(asNumber(ms))
 
@@ -440,17 +457,23 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
            "throughIndex" bigint,
            "snapshotThroughIndex" bigint
          )
+       ), bounded as materialized (
+         select request.*, coalesce(clears.clear_index, 0) as clear_index
+           from request
+           left join a2_clears clears on clears.session_id = request."sessionId"
        ), selected as materialized (
          select request.position,
                 request."sessionId" as session_id,
                 request."throughIndex" as through_index,
+                request.clear_index,
                 head.up_to_index as head_index,
                 candidate.up_to_index as snapshot_index,
                 candidate.state as snapshot_state
-           from request
+           from bounded request
            left join a2_snapshots head
              on head.session_id = request."sessionId"
             and head.reducer_name = $2
+            and head.up_to_index >= request.clear_index
            left join lateral (
              select up_to_index, state from (
                select head.up_to_index, head.state
@@ -461,6 +484,7 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
                  from a2_snapshot_history history
                 where history.session_id = request."sessionId"
                   and history.reducer_name = $2
+                  and history.up_to_index >= request.clear_index
                   and (
                     request."snapshotThroughIndex" is null
                     or history.up_to_index <= request."snapshotThroughIndex"
@@ -472,7 +496,7 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
        )
        select selected.position, 0 as row_order, selected.session_id,
               selected.head_index, selected.snapshot_index,
-              selected.snapshot_state,
+              selected.snapshot_state, selected.clear_index,
               null::bigint as idx, null::text as event_type,
               null::jsonb as payload, null::text as event_id,
               null::bigint as created_at
@@ -480,12 +504,15 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
        union all
        select selected.position, 1 as row_order, event.session_id,
               selected.head_index, null::bigint as snapshot_index,
-              null::jsonb as snapshot_state,
+              null::jsonb as snapshot_state, selected.clear_index,
               event.idx, event.event_type, event.payload,
               event.event_id, event.created_at
          from selected
          join a2_events event on event.session_id = selected.session_id
-        where event.idx > coalesce(selected.snapshot_index, 0)
+        where event.idx > greatest(
+                coalesce(selected.snapshot_index, 0),
+                selected.clear_index - 1
+              )
           and (
             selected.through_index is null
             or event.idx <= selected.through_index
@@ -501,6 +528,8 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
     for (const row of rows) {
       const read = reads[asNumber(row['position'])]!
       if (row['row_order'] === 0 || row['row_order'] === '0') {
+        const clearIndex = asNumber(row['clear_index'])
+        if (clearIndex > 0) read.clearIndex = clearIndex
         read.headIndex =
           row['head_index'] === null ? null : asNumber(row['head_index'])
         if (row['snapshot_index'] !== null) {
@@ -552,8 +581,126 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
     })
   }
 
+  type Query = PostgresConnection['query']
+
+  /**
+   * The rows owning `ids`. This session's rows below its clear marker do
+   * not own their ids: they are deleted here so the ids can be reused.
+   */
+  const liveOwnersOf = async ({
+    query,
+    sessionId,
+    clearIndex,
+    ids,
+  }: {
+    query: Query
+    sessionId: string
+    clearIndex: number
+    ids: readonly string[]
+  }): Promise<Record<string, unknown>[]> => {
+    if (ids.length === 0) return []
+    const { rows } = await query(
+      'select * from a2_events where event_id = any($1::text[]) order by idx',
+      [ids],
+    )
+    const stale = rows.filter(
+      (row) =>
+        row['session_id'] === sessionId && asNumber(row['idx']) < clearIndex,
+    )
+    if (stale.length === 0) return rows
+    // Never wait on a stale row: cleared work holding it may itself be
+    // waiting for the session lock this append holds.
+    const { rows: deleted } = await query(
+      `with stale as materialized (
+         select idx from a2_events
+          where session_id = $1 and event_id = any($2::text[])
+          order by idx
+          for update skip locked
+       )
+       delete from a2_events event using stale
+        where event.session_id = $1 and event.idx = stale.idx
+        returning event.idx`,
+      [sessionId, stale.map((row) => row['event_id'])],
+    )
+    if (deleted.length < stale.length) {
+      throw new A2Error(
+        'STORE_UNAVAILABLE',
+        `an event id being reused is still held by cleared work in session '${sessionId}'`,
+      )
+    }
+    return rows.filter((row) => !stale.includes(row))
+  }
+
+  /** Whether `index` is at or below the boundary, read in a fresh statement. */
+  const clearedAt = async ({
+    query,
+    sessionId,
+    index,
+  }: {
+    query: Query
+    sessionId: string
+    index: number
+  }): Promise<boolean> => {
+    const { rows } = await query(
+      `select ${clearIndexOf('$1')} as clear_index`,
+      [sessionId],
+    )
+    return index <= asNumber(rows[0]?.['clear_index'])
+  }
+
+  /** Insert one event; its lane is ready unless an unfinished lane event of this lifetime precedes it. */
+  const insertEvent = async ({
+    query,
+    row,
+    clearIndex,
+    returning = false,
+  }: {
+    query: Query
+    row: {
+      sessionId: string
+      index: number
+      type: string
+      payload: unknown
+      id: string
+      createdAt: number
+      cause: EventCause | null
+      lane: string | null
+      processedAt: number | null
+    }
+    clearIndex: number
+    returning?: boolean
+  }): Promise<Record<string, unknown> | undefined> => {
+    const { rows } = await query(
+      `insert into a2_events
+         (session_id, idx, event_type, payload, event_id, created_at,
+          cause, lane, lane_ready, processed_at)
+       values (
+         $1, $2, $3, $4::jsonb, $5, $6, $7::jsonb, $8,
+         $8::text is null or not exists (
+           select 1 from a2_events
+            where session_id = $1 and lane = $8 and processed_at is null
+              and idx > $10
+         ),
+         $9
+       )${returning ? ' returning *' : ''}`,
+      [
+        row.sessionId,
+        row.index,
+        row.type,
+        jsonb(row.payload),
+        row.id,
+        row.createdAt,
+        row.cause ? jsonb(row.cause) : null,
+        row.lane,
+        row.processedAt,
+        clearIndex,
+      ],
+    )
+    return rows[0]
+  }
+
   const store: PostgresStore = {
-    async append(sessionId, events) {
+    async append(sessionId, events, appendOptions) {
       if (events.length === 0) {
         return wrap(async () => {
           const c = await client()
@@ -561,6 +708,7 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
             `select exists(
                select 1 from a2_events
                where session_id = $1 and processed_at is null
+                 and idx > ${clearIndexOf('$1')}
              ) as has_pending`,
             [sessionId],
           )
@@ -575,6 +723,23 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
           // Serialize appends per session — index assignment must not
           // race across writers. Transaction-scoped, self-releasing.
           await query('select pg_advisory_xact_lock(hashtext($1))', [sessionId])
+          const { rows: statusRows } = await query(
+            `select coalesce(max(idx), 0) as max,
+                    ${clearIndexOf('$1')} as clear_index,
+                    exists(
+                      select 1 from a2_events pending
+                      where pending.session_id = $1
+                        and pending.processed_at is null
+                        and pending.idx > ${clearIndexOf('$1')}
+                    ) as session_has_pending
+               from a2_events
+              where session_id = $1`,
+            [sessionId],
+          )
+          const base = asNumber(statusRows[0]?.['max'])
+          const clearIndex = asNumber(statusRows[0]?.['clear_index'])
+          const sessionHasPending =
+            statusRows[0]?.['session_has_pending'] === true
 
           const supplied = events.filter((e) => e.id !== undefined)
           const suppliedIds = supplied.map((e) => e.id as string)
@@ -585,18 +750,12 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
             )
           }
           if (suppliedIds.length > 0) {
-            const { rows: existing } = await query(
-              `select stored.*,
-                      exists(
-                        select 1 from a2_events pending
-                        where pending.session_id = $2
-                          and pending.processed_at is null
-                      ) as session_has_pending
-                 from a2_events stored
-                where stored.event_id = any($1)
-                order by stored.idx`,
-              [suppliedIds, sessionId],
-            )
+            const existing = await liveOwnersOf({
+              query,
+              sessionId,
+              clearIndex,
+              ids: suppliedIds,
+            })
             if (existing.length > 0) {
               const foreign = existing.find(
                 (row) => row['session_id'] !== sessionId,
@@ -610,7 +769,7 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
               if (existing.length === events.length) {
                 return {
                   events: idempotentReplay(events, existing.map(toStored)),
-                  hasPending: existing[0]?.['session_has_pending'] === true,
+                  hasPending: sessionHasPending,
                 }
               }
               throw new A2Error(
@@ -620,6 +779,16 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
             }
           }
 
+          const originIndex = appendOptions?.originIndex
+          if (originIndex !== undefined && originIndex <= clearIndex) {
+            throw sessionClearedError(
+              `scheduled work from event ${originIndex} was cleared in session '${sessionId}'`,
+            )
+          }
+          for (const e of events) {
+            if (e.cause && e.cause.index <= clearIndex)
+              throw supersededAttemptError(sessionId, e.cause)
+          }
           // Attempt-currency fence: a fresh handler append commits only
           // while its causal attempt is still the parent's latest
           // (store.ts `append`). `for update` serializes this read against
@@ -654,26 +823,11 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
                 asNumber(parent['attempt_count']) !== e.cause.attempt ||
                 parent['failed_at'] !== null
               ) {
-                throw new A2Error(
-                  'SUPERSEDED_ATTEMPT',
-                  `attempt ${e.cause.attempt} no longer owns event ${e.cause.index} in session '${sessionId}'`,
-                )
+                throw supersededAttemptError(sessionId, e.cause)
               }
             }
           }
 
-          const { rows: maxRows } = await query(
-            `select coalesce(max(idx), 0) as max,
-                    exists(
-                      select 1 from a2_events pending
-                      where pending.session_id = $1
-                        and pending.processed_at is null
-                    ) as session_has_pending
-               from a2_events
-              where session_id = $1`,
-            [sessionId],
-          )
-          const base = asNumber(maxRows[0]?.['max'])
           const now = clock.now().getTime()
           const inserted: StoredEvent[] = []
           for (let i = 0; i < events.length; i += 1) {
@@ -681,30 +835,21 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
             const id = e.id ?? generateId()
             const index = base + 1 + i
             // oxlint-disable-next-line no-await-in-loop -- one tx, ordered inserts
-            await query(
-              `insert into a2_events
-                 (session_id, idx, event_type, payload, event_id, created_at,
-                  cause, lane, lane_ready, processed_at)
-               values (
-                 $1, $2, $3, $4::jsonb, $5, $6, $7::jsonb, $8,
-                 $8::text is null or not exists (
-                   select 1 from a2_events
-                    where session_id = $1 and lane = $8 and processed_at is null
-                 ),
-                 $9
-               )`,
-              [
+            await insertEvent({
+              query,
+              row: {
                 sessionId,
                 index,
-                e.type,
-                jsonb(e.payload),
+                type: e.type,
+                payload: e.payload,
                 id,
-                now,
-                e.cause ? jsonb(e.cause) : null,
-                e.lane ?? null,
-                e.settled ? now : null,
-              ],
-            )
+                createdAt: now,
+                cause: e.cause ?? null,
+                lane: e.lane ?? null,
+                processedAt: e.settled ? now : null,
+              },
+              clearIndex,
+            })
             inserted.push({
               id,
               type: e.type,
@@ -732,7 +877,7 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
           return {
             events: inserted,
             hasPending:
-              maxRows[0]?.['session_has_pending'] === true ||
+              sessionHasPending ||
               events.some((event) => event.settled !== true),
           }
         }),
@@ -752,6 +897,8 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
           params.push(opts.throughIndex)
           conditions.push(`idx <= $${params.length}`)
         }
+        // Reads start at the latest clear marker.
+        conditions.push(`idx >= ${clearIndexOf('$1')}`)
         const { rows } = await c.query(
           `select * from a2_events where ${conditions.join(' and ')} order by idx`,
           params,
@@ -778,6 +925,8 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
           params.push(opts.throughIndex)
           conditions.push(`idx <= $${params.length}`)
         }
+        // Reads start at the latest clear marker.
+        conditions.push(`idx >= ${clearIndexOf('$1')}`)
         const { rows } = await c.query(
           `select session_id, idx, event_id, event_type, payload, created_at
              from a2_events where ${conditions.join(' and ')} order by idx`,
@@ -806,6 +955,7 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
                   and event.processed_at is null
                   and event.failed_at is null
                   and event.lane_ready
+                  and event.idx > ${clearIndexOf('$1')}
                   and (event.claim_expires_at is null or event.claim_expires_at <= $2)
                   and not (event.idx = any($5::bigint[]))
                 for update of event
@@ -818,12 +968,17 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
                claim_expires_at = $4
              from eligible
              where claimed.session_id = $1 and claimed.idx = eligible.idx
-             returning claimed.*`,
+             returning claimed.*, ${clearIndexOf('$1')} as clear_index`,
             [sessionId, now, holder, expiresAt, [...excludeIndexes]],
           )
           if (rows.length > 0) {
             const events = rows
-              .map(toStored)
+              .map((row) => {
+                const stored = toStored(row)
+                const clearIndex = asNumber(row['clear_index'])
+                if (clearIndex > 0) stored.clearIndex = clearIndex
+                return stored
+              })
               .toSorted((a, b) => a.index - b.index)
             return { outcome: 'claimed', events }
           }
@@ -834,6 +989,7 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
                 and processed_at is null
                 and failed_at is null
                 and lane_ready
+                and idx > ${clearIndexOf('$1')}
                 and claim_expires_at > $2`,
             [sessionId, now],
           )
@@ -865,6 +1021,7 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
                from listed
               where event.session_id = $2
                 and event.idx = listed.idx
+                and event.idx > ${clearIndexOf('$2')}
                 and event.attempt_count = listed.attempt
                 and event.processed_at is null
                 and event.failed_at is null
@@ -872,11 +1029,13 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
                 and event.claim_expires_at > $5
               returning event.idx
            )
-           select event.idx, event.attempt_count,
-                  exists(select 1 from renewed where renewed.idx = event.idx)
-                    as renewed
-             from a2_events event
-            where event.session_id = $2 and event.idx = any($3::bigint[])`,
+           select listed.idx, event.attempt_count,
+                  exists(select 1 from renewed where renewed.idx = listed.idx)
+                    as renewed,
+                  listed.idx <= ${clearIndexOf('$2')} as cleared
+             from listed
+             left join a2_events event
+               on event.session_id = $2 and event.idx = listed.idx`,
           [
             expiresAt,
             sessionId,
@@ -892,7 +1051,9 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
           const index = asNumber(row['idx'])
           if (row['renewed'] === true) renewed.push(index)
           else if (
-            asNumber(row['attempt_count']) > (attempts.get(index) ?? 0)
+            row['cleared'] === true ||
+            (row['attempt_count'] !== null &&
+              asNumber(row['attempt_count']) > (attempts.get(index) ?? 0))
           ) {
             superseded.push(index)
           }
@@ -908,13 +1069,23 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
       return wrap(() =>
         withTx(async (query) => {
           const { rows: parentRows } = await query(
-            `select * from a2_events
-              where session_id = $1 and idx = $2
-              for update`,
+            `select boundary.clear_index, parent.*
+               from (select ${clearIndexOf('$1')} as clear_index) boundary
+               left join lateral (
+                 select * from a2_events
+                  where session_id = $1 and idx = $2 and idx > boundary.clear_index
+                  for update
+               ) parent on true`,
             [sessionId, index],
           )
-          const parent = parentRows[0]
+          if (index <= asNumber(parentRows[0]?.['clear_index']))
+            return { outcome: 'superseded' }
+          const parent =
+            parentRows[0]?.['idx'] == null ? undefined : parentRows[0]
           if (!parent) {
+            // Deleted while this statement waited for its lock, after a clear.
+            if (await clearedAt({ query, sessionId, index }))
+              return { outcome: 'superseded' }
             throw new TypeError(
               `no event at index ${index} in session '${sessionId}'`,
             )
@@ -957,6 +1128,11 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
               existing.map((row) => [row['event_id'] as string, row]),
             )
             const ordered = ids.map((id) => byId.get(id))
+            if (
+              ordered.some((row) => !row) &&
+              (await clearedAt({ query, sessionId, index }))
+            )
+              return { outcome: 'superseded' }
             if (
               ordered.some((row) => {
                 const cause = row ? toCause(row['cause']) : null
@@ -990,12 +1166,23 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
             return { outcome: 'superseded' }
           }
 
+          // The parent lock came first; only a statement after the session
+          // lock sees every clear that committed while this one waited.
           await query('select pg_advisory_xact_lock(hashtext($1))', [sessionId])
+          const { rows: maxRows } = await query(
+            `select coalesce(max(idx), 0) as max, ${clearIndexOf('$1')} as clear_index
+               from a2_events where session_id = $1`,
+            [sessionId],
+          )
+          const clearIndex = asNumber(maxRows[0]?.['clear_index'])
+          if (index <= clearIndex) return { outcome: 'superseded' }
           if (ids.length > 0) {
-            const { rows: existing } = await query(
-              'select event_id from a2_events where event_id = any($1::text[])',
-              [ids],
-            )
+            const existing = await liveOwnersOf({
+              query,
+              sessionId,
+              clearIndex,
+              ids,
+            })
             if (existing.length > 0) {
               throw new A2Error(
                 'PARTIAL_DUPLICATE_BATCH',
@@ -1004,10 +1191,6 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
             }
           }
 
-          const { rows: maxRows } = await query(
-            'select coalesce(max(idx), 0) as max from a2_events where session_id = $1',
-            [sessionId],
-          )
           const base = asNumber(maxRows[0]?.['max'])
           const now = clock.now().getTime()
           const inserted: StoredEvent[] = []
@@ -1015,32 +1198,23 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
             const event = events[offset]!
             const childIndex = base + offset + 1
             // oxlint-disable-next-line no-await-in-loop -- one tx, ordered inserts
-            const { rows } = await query(
-              `insert into a2_events
-                 (session_id, idx, event_type, payload, event_id, created_at,
-                  cause, lane, lane_ready, processed_at)
-               values (
-                 $1, $2, $3, $4::jsonb, $5, $6, $7::jsonb, $8,
-                 $8::text is null or not exists (
-                   select 1 from a2_events
-                    where session_id = $1 and lane = $8 and processed_at is null
-                 ),
-                 $9
-               )
-               returning *`,
-              [
+            const row = await insertEvent({
+              query,
+              row: {
                 sessionId,
-                childIndex,
-                event.type,
-                jsonb(event.payload),
-                event.id,
-                now,
-                jsonb({ index, attempt }),
-                event.lane ?? null,
-                event.settled ? now : null,
-              ],
-            )
-            inserted.push(toStored(rows[0]!))
+                index: childIndex,
+                type: event.type,
+                payload: event.payload,
+                id: event.id,
+                createdAt: now,
+                cause: { index, attempt },
+                lane: event.lane ?? null,
+                processedAt: event.settled ? now : null,
+              },
+              clearIndex,
+              returning: true,
+            })
+            inserted.push(toStored(row!))
           }
           await query(
             `update a2_events set
@@ -1077,9 +1251,10 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
                   and idx = (
                     select idx from a2_events
                      where session_id = $1 and lane = $2 and processed_at is null
+                       and idx > $3
                      order by idx limit 1
                   )`,
-              [sessionId, parentLane],
+              [sessionId, parentLane, clearIndex],
             )
           }
           return { outcome: 'completed', events: inserted }
@@ -1094,6 +1269,7 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
             `with current as materialized (
              select e.* from a2_events e
              where e.session_id = $1 and e.idx = $2
+               and e.idx > ${clearIndexOf('$1')}
              for update of e
            ), updated as (
              update a2_events e set
@@ -1117,6 +1293,7 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
              returning e.failure_count, e.failed_at
            )
            select case
+             when $2 <= ${clearIndexOf('$1')} then 'cleared'
              when not exists (select 1 from current) then 'missing'
              when exists (
                select 1 from updated where failed_at is not null
@@ -1149,7 +1326,13 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
             ],
           )
           const row = rows[0]
+          if (row?.['outcome'] === 'cleared') {
+            return { outcome: 'superseded', failureCount: 0 }
+          }
           if (!row || row['outcome'] === 'missing') {
+            // Deleted while this statement waited for its lock, after a clear.
+            if (await clearedAt({ query, sessionId, index }))
+              return { outcome: 'superseded', failureCount: 0 }
             throw new TypeError(
               `no event at index ${index} in session '${sessionId}'`,
             )
@@ -1181,6 +1364,86 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
       )
     },
 
+    async deadLetters(sessionId) {
+      return wrap(async () => {
+        const c = await client()
+        const { rows } = await c.query(
+          `select * from a2_events
+            where session_id = $1
+              and processed_at is null
+              and failed_at is not null
+              and idx > ${clearIndexOf('$1')}
+            order by idx`,
+          [sessionId],
+        )
+        return rows.map(toStored)
+      })
+    },
+
+    async redrive({ sessionId, index, action }) {
+      return wrap(() =>
+        withTx(async (query) => {
+          // Lane promotion must see every append that committed before it,
+          // so a skip takes the session lock first, in append's order. The
+          // row lock serializes both actions with claims and handler appends.
+          if (action === 'skip') {
+            await query('select pg_advisory_xact_lock(hashtext($1))', [
+              sessionId,
+            ])
+          }
+          const { rows } = await query(
+            `select lane from a2_events
+              where session_id = $1 and idx = $2
+                and idx > ${clearIndexOf('$1')}
+                and processed_at is null
+                and failed_at is not null
+              for update`,
+            [sessionId, index],
+          )
+          const row = rows[0]
+          if (row && action === 'retry') {
+            await query(
+              `update a2_events set failed_at = null, failure_count = 0
+                where session_id = $1 and idx = $2`,
+              [sessionId, index],
+            )
+          } else if (row) {
+            await query(
+              `update a2_events set processed_at = $3, lane_ready = false
+                where session_id = $1 and idx = $2`,
+              [sessionId, index, clock.now().getTime()],
+            )
+            const lane = (row['lane'] as string | null) ?? null
+            if (lane !== null) {
+              await query(
+                `update a2_events set lane_ready = true
+                  where session_id = $1
+                    and idx = (
+                      select idx from a2_events
+                       where session_id = $1 and lane = $2 and processed_at is null
+                         and idx > ${clearIndexOf('$1')}
+                       order by idx limit 1
+                    )`,
+                [sessionId, lane],
+              )
+            }
+          }
+          const { rows: status } = await query(
+            `select exists(
+               select 1 from a2_events
+               where session_id = $1 and processed_at is null
+                 and idx > ${clearIndexOf('$1')}
+             ) as has_pending`,
+            [sessionId],
+          )
+          return {
+            redriven: row !== undefined,
+            hasPending: status[0]?.['has_pending'] === true,
+          }
+        }),
+      )
+    },
+
     async readState(sessionId, reducerName, stateOptions) {
       return wrap(
         async () =>
@@ -1212,15 +1475,33 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
     async putSnapshots(sessionId, reducerName, writes) {
       await wrap(() =>
         withTx(async (query) => {
-          const normalized = [
+          const requested = [
             ...new Map(writes.map((write) => [write.index, write])).values(),
           ].toSorted((a, b) => a.index - b.index)
-          if (normalized.length === 0) return
+          if (requested.length === 0) return
 
           await query(
             'select pg_advisory_xact_lock(hashtext($1), hashtext($2))',
             [sessionId, reducerName],
           )
+          const { rows: headRows } = await query(
+            `select boundary.clear_index, head.up_to_index, head.state, head.updated_at
+               from (select ${clearIndexOf('$1')} as clear_index) boundary
+               left join lateral (
+                 select up_to_index, state, updated_at from a2_snapshots
+                  where session_id = $1 and reducer_name = $2
+                  for update
+               ) head on true`,
+            [sessionId, reducerName],
+          )
+          const clearIndex = asNumber(headRows[0]?.['clear_index'])
+          // A fold from before the latest clear describes a lifetime that is gone.
+          const normalized = requested.filter(
+            (write) => write.index >= clearIndex,
+          )
+          if (normalized.length === 0) return
+          const currentHead =
+            headRows[0]?.['up_to_index'] == null ? undefined : headRows[0]
 
           const requestedPins = normalized.flatMap((write) =>
             (write.pinEventIndexes ?? []).map((eventIndex) => ({
@@ -1234,9 +1515,9 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
             ]
             const { rows: events } = await query(
               `select idx, processed_at, failed_at from a2_events
-                where session_id = $1 and idx = any($2::bigint[])
+                where session_id = $1 and idx = any($2::bigint[]) and idx > $3
                 for update`,
-              [sessionId, eventIndexes],
+              [sessionId, eventIndexes, clearIndex],
             )
             const unfinished = new Set(
               events
@@ -1264,13 +1545,6 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
             }
           }
 
-          const { rows: headRows } = await query(
-            `select up_to_index, state, updated_at from a2_snapshots
-              where session_id = $1 and reducer_name = $2
-              for update`,
-            [sessionId, reducerName],
-          )
-          const currentHead = headRows[0]
           const latestWrite = normalized.at(-1)!
           const writesHead =
             !currentHead ||
@@ -1303,6 +1577,7 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
           if (
             advancesHead &&
             currentHead &&
+            asNumber(currentHead['up_to_index']) >= clearIndex &&
             pinned.has(asNumber(currentHead['up_to_index']))
           ) {
             const index = asNumber(currentHead['up_to_index'])
@@ -1467,10 +1742,12 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
       const readAfter = (afterIndex: number): Promise<Event[]> =>
         wrap(async () => {
           const c = await client()
+          // A cursor below the latest marker resumes at it.
           const { rows } = await c.query(
             `select session_id, idx, event_type, payload, event_id, created_at
                from a2_events
               where session_id = $1 and idx > $2
+                and idx >= ${clearIndexOf('$1')}
               order by idx`,
             [sessionId, afterIndex],
           )
@@ -1488,6 +1765,156 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
       )
     },
 
+    async clear({ sessionId, ifLastIndex, cause }) {
+      return wrap(() =>
+        withTx(async (query) => {
+          await query('select pg_advisory_xact_lock(hashtext($1))', [sessionId])
+          const { rows: headRows } = await query(
+            `select coalesce(max(idx), 0) as head,
+                    ${clearIndexOf('$1')} as clear_index
+               from a2_events where session_id = $1`,
+            [sessionId],
+          )
+          const head = asNumber(headRows[0]?.['head'])
+          const clearIndex = asNumber(headRows[0]?.['clear_index'])
+          if (cause) {
+            if (cause.index <= clearIndex)
+              throw supersededAttemptError(sessionId, cause)
+            const { rows: parents } = await query(
+              `select attempt_count, failed_at from a2_events
+                where session_id = $1 and idx = $2
+                for update`,
+              [sessionId, cause.index],
+            )
+            const parent = parents[0]
+            if (!parent) {
+              throw new TypeError(
+                `no event at index ${cause.index} in session '${sessionId}'`,
+              )
+            }
+            if (
+              asNumber(parent['attempt_count']) !== cause.attempt ||
+              parent['failed_at'] !== null
+            ) {
+              throw supersededAttemptError(sessionId, cause)
+            }
+          }
+          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 = head + 1
+          const now = clock.now().getTime()
+          await insertEvent({
+            query,
+            row: {
+              sessionId,
+              index: marker,
+              type: CLEAR_EVENT_TYPE,
+              payload: null,
+              id: generateId(),
+              createdAt: now,
+              cause: null,
+              lane: null,
+              processedAt: now,
+            },
+            clearIndex,
+          })
+          // Releasing a clearing handler's claim makes a claim waiting on its
+          // row skip it once this commits, instead of re-running the handler.
+          await query(
+            `with released as (
+               update a2_events
+                  set lane_ready = false, claim_holder = null, claim_expires_at = null
+                where session_id = $1 and idx = $3
+             )
+             insert into a2_clears (session_id, clear_index) values ($1, $2)
+             on conflict (session_id) do update set clear_index = excluded.clear_index`,
+            [sessionId, marker, cause?.index ?? null],
+          )
+          return { cleared: true, index: marker, clearIndex: marker }
+        }),
+      )
+    },
+
+    async reclaim(sessionId) {
+      return wrap(() =>
+        withTx(async (query) => {
+          // Rows other work holds are skipped, never waited on, so deletion
+          // cannot join a deadlock; a later batch takes them.
+          const { rows } = await query(
+            `with boundary as materialized (
+               select ${clearIndexOf('$1')} as clear_index
+             ), batch as materialized (
+               select idx from a2_events
+                where session_id = $1
+                  and idx < (select clear_index from boundary)
+                order by idx
+                limit $2
+                for update skip locked
+             ), deleted as (
+               delete from a2_events event using batch
+                where event.session_id = $1 and event.idx = batch.idx
+                returning event.idx
+             ), pins as (
+               delete from a2_snapshot_pins pin using deleted
+                where pin.session_id = $1 and pin.event_index = deleted.idx
+             )
+             select (select count(*) from deleted) as deleted,
+                    (select clear_index from boundary) as clear_index`,
+            [sessionId, RECLAIM_BATCH],
+          )
+          const deleted = asNumber(rows[0]?.['deleted'])
+          const clearIndex = asNumber(rows[0]?.['clear_index'])
+          if (clearIndex === 0) return { deleted: 0, done: true }
+          if (deleted > 0) return { deleted, done: false }
+          const { rows: remaining } = await query(
+            'select 1 from a2_events where session_id = $1 and idx < $2 limit 1',
+            [sessionId, clearIndex],
+          )
+          if (remaining.length > 0) return { deleted: 0, done: false }
+          const { rows: swept } = await query(
+            `with pins as materialized (
+               select ctid from a2_snapshot_pins
+                where session_id = $1 and up_to_index < $2
+                for update skip locked
+             ), history as materialized (
+               select ctid from a2_snapshot_history
+                where session_id = $1 and up_to_index < $2
+                for update skip locked
+             ), heads as materialized (
+               select ctid from a2_snapshots
+                where session_id = $1 and up_to_index < $2
+                for update skip locked
+             ), gone_pins as (
+               delete from a2_snapshot_pins target using pins where target.ctid = pins.ctid
+             ), gone_history as (
+               delete from a2_snapshot_history target using history
+                where target.ctid = history.ctid
+             ), gone_heads as (
+               delete from a2_snapshots target using heads where target.ctid = heads.ctid
+             )
+             select (select count(*) from a2_snapshot_pins
+                      where session_id = $1 and up_to_index < $2)
+                  + (select count(*) from a2_snapshot_history
+                      where session_id = $1 and up_to_index < $2)
+                  + (select count(*) from a2_snapshots
+                      where session_id = $1 and up_to_index < $2)
+                  - (select count(*) from pins)
+                  - (select count(*) from history)
+                  - (select count(*) from heads) as skipped`,
+            [sessionId, clearIndex],
+          )
+          return { deleted: 0, done: asNumber(swept[0]?.['skipped']) === 0 }
+        }),
+      )
+    },
+
     async close() {
       if (closed) return
       closed = true