experimental-a2 0.16.1 → 0.17.0

package/dist/store-postgres.js

@@ -1,12 +1,12 @@
-import { t as A2Error } from "./errors-DCk6ch5n.js";
-import { h as nullProtoRecord, r as NOTIFY_TIMINGS } from "./internal-Dq2qYxou.js";
-import { n as pollingStream, t as defaultSleep } from "./store-polling-CmxUbV93.js";
+import { i as A2Error, r as sessionClearedError, s as supersededAttemptError, t as CLEAR_EVENT_TYPE } from "./session-clear-DGI4jTQ5.js";
+import { g as nullProtoRecord, r as NOTIFY_TIMINGS } from "./internal-CbVvEwad.js";
+import { n as pollingStream, t as defaultSleep } from "./store-polling-4_y8lETm.js";
 import { r as platformWaitUntil } from "./platform-B4TnJtWu.js";
 import { t as retryableLazy } from "./retryable-lazy-DZWmHpii.js";
-import { t as idempotentReplay } from "./idempotent-replay-DVOlyYbx.js";
+import { t as idempotentReplay } from "./idempotent-replay-JdgMQRRm.js";
 import { n as SYSTEM_CLOCK, t as RANDOM_IDS } from "./store-N8PXxDAS.js";
 import { t as decodeReturnedEventIds } from "./store-codec-DTG0Ftek.js";
-import { t as pollPresence } from "./store-presence-polling-C7-XZyW9.js";
+import { t as pollPresence } from "./store-presence-polling-Q1C-k2dd.js";
 import { createHash } from "node:crypto";
 //#region src/postgres-notifications.ts
 const postgresNotificationChannel = ({ kind, sessionId }) => `a2_${kind}_${createHash("md5").update(sessionId).digest("hex")}`;
@@ -232,11 +232,14 @@ function postgresNotificationScope(load) {
 				let stopped = false;
 				let after = startAfter;
 				let buffer = [];
+				let position = 0;
 				let version = 0;
 				let waiting;
 				let lease;
 				const stop = () => {
 					stopped = true;
+					buffer = [];
+					position = 0;
 					waiting?.cancel();
 					lease?.stop();
 					state.stops.delete(stop);
@@ -262,20 +265,28 @@ function postgresNotificationScope(load) {
 									done: true,
 									value: void 0
 								};
-								const row = buffer.shift();
+								const row = buffer[position];
 								if (row) {
 									after = row.index;
+									buffer[position] = void 0;
+									position += 1;
+									if (position === buffer.length) {
+										buffer = [];
+										position = 0;
+									}
 									return {
 										done: false,
 										value: row
 									};
 								}
 								const before = version;
-								buffer = await read(after);
+								const rows = await read(after);
 								if (stopped || state.closed) return {
 									done: true,
 									value: void 0
 								};
+								buffer = rows;
+								position = 0;
 								if (buffer.length || before !== version) continue;
 								waiting = defaultSleep(NOTIFY_TIMINGS.safetyReadMs);
 								await waiting.promise;
@@ -563,6 +574,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,
@@ -575,6 +591,14 @@ create table if not exists a2_presence (
 );
 `;
 const asNumber = (value) => Number(value);
+/**
+* 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) => `coalesce((select clear_index from a2_clears where session_id = ${session}), 0)`;
+const RECLAIM_BATCH = 256;
 const toDate = (ms) => ms === null || ms === void 0 ? null : new Date(asNumber(ms));
 const toCause = (raw) => {
 	if (raw === null || raw === void 0) return null;
@@ -755,17 +779,23 @@ function postgres(options = {}) {
            "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
@@ -776,6 +806,7 @@ function postgres(options = {}) {
                  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"
@@ -787,7 +818,7 @@ function postgres(options = {}) {
        )
        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
@@ -795,12 +826,15 @@ function postgres(options = {}) {
        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
@@ -814,6 +848,8 @@ function postgres(options = {}) {
 		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) read.snapshot = {
 					index: asNumber(row["snapshot_index"]),
@@ -854,12 +890,66 @@ function postgres(options = {}) {
 			}
 		});
 	};
+	/**
+	* 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 }) => {
+		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;
+		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 }) => {
+		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 }) => {
+		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 = {
-		async append(sessionId, events) {
+		async append(sessionId, events, appendOptions) {
 			if (events.length === 0) return wrap(async () => {
 				const { rows } = await (await client()).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 {
 					events: [],
@@ -868,28 +958,41 @@ function postgres(options = {}) {
 			});
 			return wrap(() => withTx(async (query) => {
 				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 suppliedIds = events.filter((e) => e.id !== void 0).map((e) => e.id);
 				if (new Set(suppliedIds).size !== suppliedIds.length) throw new A2Error("PARTIAL_DUPLICATE_BATCH", "batch contains the same event id more than once");
 				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);
 						if (foreign) throw new A2Error("PARTIAL_DUPLICATE_BATCH", `event id '${String(foreign["event_id"])}' already exists in another session`);
 						if (existing.length === events.length) return {
 							events: idempotentReplay(events, existing.map(toStored)),
-							hasPending: existing[0]?.["session_has_pending"] === true
+							hasPending: sessionHasPending
 						};
 						throw new A2Error("PARTIAL_DUPLICATE_BATCH", `batch mixes ${existing.length} already-appended and ${events.length - existing.length} fresh events`);
 					}
 				}
+				const originIndex = appendOptions?.originIndex;
+				if (originIndex !== void 0 && 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);
 				const causeIndexes = [...new Set(events.filter((e) => e.cause !== void 0).map((e) => e.cause.index))];
 				if (causeIndexes.length > 0) {
 					const { rows: parents } = await query(`select idx, attempt_count, failed_at from a2_events
@@ -900,45 +1003,30 @@ function postgres(options = {}) {
 						if (!e.cause) continue;
 						const parent = byIndex.get(e.cause.index);
 						if (!parent) throw new TypeError(`no event at index ${e.cause.index} in session '${sessionId}'`);
-						if (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}'`);
+						if (asNumber(parent["attempt_count"]) !== e.cause.attempt || parent["failed_at"] !== null) 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 = [];
 				for (let i = 0; i < events.length; i += 1) {
 					const e = events[i];
 					const id = e.id ?? generateId();
 					const index = base + 1 + i;
-					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
-               )`, [
-						sessionId,
-						index,
-						e.type,
-						jsonb(e.payload),
-						id,
-						now,
-						e.cause ? jsonb(e.cause) : null,
-						e.lane ?? null,
-						e.settled ? now : null
-					]);
+					await insertEvent({
+						query,
+						row: {
+							sessionId,
+							index,
+							type: e.type,
+							payload: e.payload,
+							id,
+							createdAt: now,
+							cause: e.cause ?? null,
+							lane: e.lane ?? null,
+							processedAt: e.settled ? now : null
+						},
+						clearIndex
+					});
 					inserted.push({
 						id,
 						type: e.type,
@@ -965,7 +1053,7 @@ function postgres(options = {}) {
 				}
 				return {
 					events: inserted,
-					hasPending: maxRows[0]?.["session_has_pending"] === true || events.some((event) => event.settled !== true)
+					hasPending: sessionHasPending || events.some((event) => event.settled !== true)
 				};
 			}));
 		},
@@ -982,6 +1070,7 @@ function postgres(options = {}) {
 					params.push(opts.throughIndex);
 					conditions.push(`idx <= $${params.length}`);
 				}
+				conditions.push(`idx >= ${clearIndexOf("$1")}`);
 				const { rows } = await c.query(`select * from a2_events where ${conditions.join(" and ")} order by idx`, params);
 				return rows.map(toStored);
 			});
@@ -1000,6 +1089,7 @@ function postgres(options = {}) {
 					params.push(opts.throughIndex);
 					conditions.push(`idx <= $${params.length}`);
 				}
+				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`, params);
 				return rows.map(toEvent);
@@ -1008,6 +1098,7 @@ function postgres(options = {}) {
 		async claimAvailable({ sessionId, holder, ttlMs, expiresAtMs, excludeIndexes = [] }) {
 			return wrap(() => withTx(async (query) => {
 				const now = clock.now().getTime();
+				const expiresAt = expiresAtMs ?? now + ttlMs;
 				const { rows } = await query(`with eligible as materialized (
                select event.idx
                  from a2_events event
@@ -1015,6 +1106,7 @@ function postgres(options = {}) {
                   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
@@ -1027,16 +1119,21 @@ function postgres(options = {}) {
                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,
-					expiresAtMs ?? now + ttlMs,
+					expiresAt,
 					[...excludeIndexes]
 				]);
 				if (rows.length > 0) return {
 					outcome: "claimed",
-					events: rows.map(toStored).toSorted((a, b) => a.index - b.index)
+					events: rows.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)
 				};
 				const { rows: activeRows } = await query(`select min(claim_expires_at) as retry_at
                from a2_events
@@ -1044,6 +1141,7 @@ function postgres(options = {}) {
                 and processed_at is null
                 and failed_at is null
                 and lane_ready
+                and idx > ${clearIndexOf("$1")}
                 and claim_expires_at > $2`, [sessionId, now]);
 				const retryAt = activeRows[0]?.["retry_at"];
 				return retryAt === null || retryAt === void 0 ? { outcome: "settled" } : {
@@ -1072,6 +1170,7 @@ function postgres(options = {}) {
                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
@@ -1079,11 +1178,13 @@ function postgres(options = {}) {
                 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,
 					indexes,
@@ -1096,7 +1197,7 @@ function postgres(options = {}) {
 				for (const row of rows) {
 					const index = asNumber(row["idx"]);
 					if (row["renewed"] === true) renewed.push(index);
-					else if (asNumber(row["attempt_count"]) > (attempts.get(index) ?? 0)) superseded.push(index);
+					else if (row["cleared"] === true || row["attempt_count"] !== null && asNumber(row["attempt_count"]) > (attempts.get(index) ?? 0)) superseded.push(index);
 				}
 				return {
 					renewed: renewed.toSorted((a, b) => a - b),
@@ -1106,11 +1207,23 @@ function postgres(options = {}) {
 		},
 		async completeAttempt({ sessionId, index, attempt, events }) {
 			return wrap(() => withTx(async (query) => {
-				const { rows: parentRows } = await query(`select * from a2_events
-              where session_id = $1 and idx = $2
-              for update`, [sessionId, index]);
-				const parent = parentRows[0];
-				if (!parent) throw new TypeError(`no event at index ${index} in session '${sessionId}'`);
+				const { rows: parentRows } = await query(`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]);
+				if (index <= asNumber(parentRows[0]?.["clear_index"])) return { outcome: "superseded" };
+				const parent = parentRows[0]?.["idx"] == null ? void 0 : parentRows[0];
+				if (!parent) {
+					if (await clearedAt({
+						query,
+						sessionId,
+						index
+					})) return { outcome: "superseded" };
+					throw new TypeError(`no event at index ${index} in session '${sessionId}'`);
+				}
 				const ids = events.map((event) => event.id);
 				if (new Set(ids).size !== ids.length) throw new A2Error("PARTIAL_DUPLICATE_BATCH", "returned event batch contains the same event id more than once");
 				if (parent["processed_at"] !== null) {
@@ -1125,6 +1238,11 @@ function postgres(options = {}) {
                 where event_id = any($1::text[])`, [ids]);
 					const byId = new Map(existing.map((row) => [row["event_id"], 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;
 						return !row || row["session_id"] !== sessionId || cause?.index !== index || cause.attempt !== attempt;
@@ -1136,42 +1254,44 @@ function postgres(options = {}) {
 				}
 				if (asNumber(parent["attempt_count"]) !== attempt || parent["claim_holder"] === null || parent["claim_holder"] === void 0 || parent["failed_at"] !== null) return { outcome: "superseded" };
 				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]);
-					if (existing.length > 0) throw new A2Error("PARTIAL_DUPLICATE_BATCH", "returned event batch contains an already-appended event id");
+					if ((await liveOwnersOf({
+						query,
+						sessionId,
+						clearIndex,
+						ids
+					})).length > 0) throw new A2Error("PARTIAL_DUPLICATE_BATCH", "returned event batch contains an already-appended event id");
 				}
-				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 = [];
 				for (let offset = 0; offset < events.length; offset += 1) {
 					const event = events[offset];
-					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 *`, [
-						sessionId,
-						base + offset + 1,
-						event.type,
-						jsonb(event.payload),
-						event.id,
-						now,
-						jsonb({
-							index,
-							attempt
-						}),
-						event.lane ?? null,
-						event.settled ? now : null
-					]);
-					inserted.push(toStored(rows[0]));
+					const childIndex = base + offset + 1;
+					const row = await insertEvent({
+						query,
+						row: {
+							sessionId,
+							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
                processed_at = $1,
@@ -1203,8 +1323,13 @@ function postgres(options = {}) {
                   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
@@ -1216,6 +1341,7 @@ function postgres(options = {}) {
 				const { rows } = await query(`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
@@ -1239,6 +1365,7 @@ function postgres(options = {}) {
              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
@@ -1269,7 +1396,21 @@ function postgres(options = {}) {
 					clock.now().getTime()
 				]);
 				const row = rows[0];
-				if (!row || row["outcome"] === "missing") throw new TypeError(`no event at index ${index} in session '${sessionId}'`);
+				if (row?.["outcome"] === "cleared") return {
+					outcome: "superseded",
+					failureCount: 0
+				};
+				if (!row || row["outcome"] === "missing") {
+					if (await clearedAt({
+						query,
+						sessionId,
+						index
+					})) return {
+						outcome: "superseded",
+						failureCount: 0
+					};
+					throw new TypeError(`no event at index ${index} in session '${sessionId}'`);
+				}
 				if (row["outcome"] === "dead_lettered") {
 					await query(`delete from a2_snapshot_pins
                 where session_id = $1 and event_index = $2`, [sessionId, index]);
@@ -1300,17 +1441,32 @@ function postgres(options = {}) {
 		},
 		async putSnapshots(sessionId, reducerName, writes) {
 			await wrap(() => withTx(async (query) => {
-				const normalized = [...new Map(writes.map((write) => [write.index, write])).values()].toSorted((a, b) => a.index - b.index);
-				if (normalized.length === 0) return;
+				const requested = [...new Map(writes.map((write) => [write.index, write])).values()].toSorted((a, b) => a.index - b.index);
+				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"]);
+				const normalized = requested.filter((write) => write.index >= clearIndex);
+				if (normalized.length === 0) return;
+				const currentHead = headRows[0]?.["up_to_index"] == null ? void 0 : headRows[0];
 				const requestedPins = normalized.flatMap((write) => (write.pinEventIndexes ?? []).map((eventIndex) => ({
 					eventIndex,
 					snapshotIndex: write.index
 				})));
 				if (requestedPins.length > 0) {
 					const { rows: events } = await query(`select idx, processed_at, failed_at from a2_events
-                where session_id = $1 and idx = any($2::bigint[])
-                for update`, [sessionId, [...new Set(requestedPins.map((pin) => pin.eventIndex))]]);
+                where session_id = $1 and idx = any($2::bigint[]) and idx > $3
+                for update`, [
+						sessionId,
+						[...new Set(requestedPins.map((pin) => pin.eventIndex))],
+						clearIndex
+					]);
 					const unfinished = new Set(events.filter((row) => row["processed_at"] === null && row["failed_at"] === null).map((row) => asNumber(row["idx"])));
 					const accepted = requestedPins.filter((pin) => unfinished.has(pin.eventIndex));
 					if (accepted.length > 0) await query(`insert into a2_snapshot_pins
@@ -1326,10 +1482,6 @@ function postgres(options = {}) {
 						jsonb(accepted)
 					]);
 				}
-				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 || latestWrite.index >= asNumber(currentHead["up_to_index"]);
 				const advancesHead = !currentHead || latestWrite.index > asNumber(currentHead["up_to_index"]);
@@ -1343,7 +1495,7 @@ function postgres(options = {}) {
 				]);
 				const pinned = new Set(pinRows.map((row) => asNumber(row["up_to_index"])));
 				const historical = /* @__PURE__ */ new Map();
-				if (advancesHead && currentHead && pinned.has(asNumber(currentHead["up_to_index"]))) {
+				if (advancesHead && currentHead && asNumber(currentHead["up_to_index"]) >= clearIndex && pinned.has(asNumber(currentHead["up_to_index"]))) {
 					const index = asNumber(currentHead["up_to_index"]);
 					historical.set(index, {
 						index,
@@ -1476,6 +1628,7 @@ function postgres(options = {}) {
 				const { rows } = await (await client()).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]);
 				return rows.map(toEvent);
 			});
@@ -1489,6 +1642,144 @@ function postgres(options = {}) {
 			});
 			return pollingStream(readAfter, opts?.startAfter !== void 0 ? { startAfter: opts.startAfter } : {});
 		},
+		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 !== void 0 && clearIndex === ifLastIndex + 1) return {
+					cleared: true,
+					index: head,
+					clearIndex
+				};
+				if (ifLastIndex !== void 0 && 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
+				});
+				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) => {
+				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;