@ddd-ts/event-sourcing-firestore 0.0.46 → 0.0.48

package/dist/firestore.projected-stream.storage-layer.d.ts

@@ -27,5 +27,7 @@ export declare class FirestoreProjectedStreamStorageLayer implements ProjectedSt
     get(cursor: Cursor): Promise<ISerializedFact | undefined>;
     getCursor(savedChange: ISerializedSavedChange): Promise<Cursor | undefined>;
     slice(projectedStream: ProjectedStream, shard: string, startAfter?: Cursor, endAt?: Cursor, limit?: number): Promise<ISerializedFact[]>;
+    firstAtOrAfter(projectedStream: ProjectedStream, shard: string, from: MicrosecondTimestamp): Promise<ISerializedFact | undefined>;
+    latest(projectedStream: ProjectedStream, shard: string): Promise<ISerializedFact | undefined>;
 }
 //# sourceMappingURL=firestore.projected-stream.storage-layer.d.ts.map

package/dist/firestore.projected-stream.storage-layer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"firestore.projected-stream.storage-layer.d.ts","sourceRoot":"","sources":["../src/firestore.projected-stream.storage-layer.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,UAAU,EACV,eAAe,EACf,KAAK,2BAA2B,EAChC,YAAY,EACb,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EACL,MAAM,EACN,SAAS,EAET,SAAS,EACV,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAC;AAE7D,qBAAa,yBAAyB;IACpC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU;CAM7C;AAED,qBAAa,2BAA2B;IACtC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY;CAOjD;AAED,qBAAa,oCACX,YAAW,2BAA2B;IAGpC,OAAO,CAAC,QAAQ,CAAC,SAAS;aACV,SAAS;gBADR,SAAS,EAAE,SAAS,EACrB,SAAS,mDAAyB;IAG7C,IAAI,CACT,eAAe,EAAE,eAAe,EAChC,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,MAAM,EACnB,KAAK,CAAC,EAAE,MAAM;;;;;;;;;;IA2CT,sBAAsB,CAAC,YAAY,EAAE,oBAAoB;IAM1D,GAAG,CAAC,MAAM,EAAE,MAAM;IAkBlB,SAAS,CACb,WAAW,EAAE,sBAAsB,GAClC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAcxB,KAAK,CACT,eAAe,EAAE,eAAe,EAChC,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,MAAM,EACnB,KAAK,CAAC,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,MAAM;CAiDjB"}
+{"version":3,"file":"firestore.projected-stream.storage-layer.d.ts","sourceRoot":"","sources":["../src/firestore.projected-stream.storage-layer.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,UAAU,EACV,eAAe,EACf,KAAK,2BAA2B,EAChC,YAAY,EACb,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAEL,MAAM,EACN,SAAS,EAET,SAAS,EACV,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAC;AAE7D,qBAAa,yBAAyB;IACpC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU;CAM7C;AAED,qBAAa,2BAA2B;IACtC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY;CAOjD;AAED,qBAAa,oCACX,YAAW,2BAA2B;IAGpC,OAAO,CAAC,QAAQ,CAAC,SAAS;aACV,SAAS;gBADR,SAAS,EAAE,SAAS,EACrB,SAAS,mDAAyB;IAG7C,IAAI,CACT,eAAe,EAAE,eAAe,EAChC,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,MAAM,EACnB,KAAK,CAAC,EAAE,MAAM;;;;;;;;;;IAoDT,sBAAsB,CAAC,YAAY,EAAE,oBAAoB;IAM1D,GAAG,CAAC,MAAM,EAAE,MAAM;IAkBlB,SAAS,CACb,WAAW,EAAE,sBAAsB,GAClC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAcxB,KAAK,CACT,eAAe,EAAE,eAAe,EAChC,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,MAAM,EACnB,KAAK,CAAC,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,MAAM;IA2DV,cAAc,CAClB,eAAe,EAAE,eAAe,EAChC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;IAoCjC,MAAM,CACV,eAAe,EAAE,eAAe,EAChC,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;CAmCxC"}

package/dist/firestore.projected-stream.storage-layer.js

@@ -22,20 +22,20 @@ var FirestoreProjectedStreamStorageLayer = class {
 		this.converter = converter;
 	}
 	async *read(projectedStream, shard, startAfter, endAt) {
-		let query = this.firestore.collectionGroup("events").orderBy("occurredAt").orderBy("revision");
+		let query = this.firestore.collectionGroup("events").orderBy("occurredAt").orderBy("revision").orderBy(firebase_admin_firestore.FieldPath.documentId());
 		const filters = projectedStream.sources.map((source) => {
 			if (source instanceof _ddd_ts_core.LakeSource) return new FirestoreLakeSourceFilter().filter(shard, source);
 			if (source instanceof _ddd_ts_core.StreamSource) return new FirestoreStreamSourceFilter().filter(shard, source);
 			throw new Error("Unknown source type");
 		});
 		query = query.where(firebase_admin_firestore.Filter.or(...filters));
-		if (startAfter) {
+		if (startAfter && !startAfter.isMin()) {
 			const ts = this.microsecondToTimestamp(startAfter.occurredAt);
-			query = query.startAfter(ts, startAfter.revision);
+			query = query.startAfter(ts, startAfter.revision, this.firestore.doc(startAfter.ref));
 		}
-		if (endAt) {
+		if (endAt && !endAt.isMax()) {
 			const ts = this.microsecondToTimestamp(endAt.occurredAt);
-			query = query.endAt(ts, endAt.revision);
+			query = query.endAt(ts, endAt.revision, this.firestore.doc(endAt.ref));
 		}
 		for await (const doc of query.stream()) {
 			const data = this.converter.fromFirestore(doc);
@@ -83,20 +83,20 @@ var FirestoreProjectedStreamStorageLayer = class {
 		});
 	}
 	async slice(projectedStream, shard, startAfter, endAt, limit) {
-		let query = this.firestore.collectionGroup("events").orderBy("occurredAt").orderBy("revision");
+		let query = this.firestore.collectionGroup("events").orderBy("occurredAt").orderBy("revision").orderBy(firebase_admin_firestore.FieldPath.documentId());
 		const filters = projectedStream.sources.map((source) => {
 			if (source instanceof _ddd_ts_core.LakeSource) return new FirestoreLakeSourceFilter().filter(shard, source);
 			if (source instanceof _ddd_ts_core.StreamSource) return new FirestoreStreamSourceFilter().filter(shard, source);
 			throw new Error("Unknown source type");
 		});
 		query = query.where(firebase_admin_firestore.Filter.or(...filters));
-		if (startAfter) {
+		if (startAfter && !startAfter.isMin()) {
 			const ts = this.microsecondToTimestamp(startAfter.occurredAt);
-			query = query.startAfter(ts, startAfter.revision);
+			query = query.startAfter(ts, startAfter.revision, this.firestore.doc(startAfter.ref));
 		}
-		if (endAt) {
+		if (endAt && !endAt.isMax()) {
 			const ts = this.microsecondToTimestamp(endAt.occurredAt);
-			query = query.endAt(ts, endAt.revision);
+			query = query.endAt(ts, endAt.revision, this.firestore.doc(endAt.ref));
 		}
 		if (limit) query = query.limit(limit);
 		return (await query.get()).docs.map((doc) => {
@@ -113,6 +113,51 @@ var FirestoreProjectedStreamStorageLayer = class {
 			};
 		});
 	}
+	async firstAtOrAfter(projectedStream, shard, from) {
+		const ts = this.microsecondToTimestamp(from);
+		let query = this.firestore.collectionGroup("events").orderBy("occurredAt").orderBy("revision").orderBy(firebase_admin_firestore.FieldPath.documentId());
+		const filters = projectedStream.sources.map((source) => {
+			if (source instanceof _ddd_ts_core.LakeSource) return new FirestoreLakeSourceFilter().filter(shard, source);
+			if (source instanceof _ddd_ts_core.StreamSource) return new FirestoreStreamSourceFilter().filter(shard, source);
+			throw new Error("Unknown source type");
+		});
+		query = query.where(firebase_admin_firestore.Filter.or(...filters)).startAt(ts).limit(1);
+		const doc = (await query.get()).docs[0];
+		if (!doc) return void 0;
+		const data = this.converter.fromFirestore(doc);
+		return {
+			id: data.eventId,
+			ref: doc.ref.path,
+			revision: data.revision,
+			name: data.name,
+			$name: data.name,
+			payload: data.payload,
+			occurredAt: data.occurredAt,
+			version: data.version ?? 1
+		};
+	}
+	async latest(projectedStream, shard) {
+		let query = this.firestore.collectionGroup("events").orderBy("occurredAt", "desc").orderBy("revision", "desc").orderBy(firebase_admin_firestore.FieldPath.documentId(), "desc").limit(1);
+		const filters = projectedStream.sources.map((source) => {
+			if (source instanceof _ddd_ts_core.LakeSource) return new FirestoreLakeSourceFilter().filter(shard, source);
+			if (source instanceof _ddd_ts_core.StreamSource) return new FirestoreStreamSourceFilter().filter(shard, source);
+			throw new Error("Unknown source type");
+		});
+		query = query.where(firebase_admin_firestore.Filter.or(...filters));
+		const doc = (await query.get()).docs[0];
+		if (!doc) return void 0;
+		const data = this.converter.fromFirestore(doc);
+		return {
+			id: data.eventId,
+			ref: doc.ref.path,
+			revision: data.revision,
+			name: data.name,
+			$name: data.name,
+			payload: data.payload,
+			occurredAt: data.occurredAt,
+			version: data.version ?? 1
+		};
+	}
 };
 
 //#endregion

package/dist/firestore.projected-stream.storage-layer.mjs

@@ -1,6 +1,6 @@
 import { LakeSource, StreamSource } from "@ddd-ts/core";
 import { DefaultConverter } from "@ddd-ts/store-firestore";
-import { Filter, Timestamp } from "firebase-admin/firestore";
+import { FieldPath, Filter, Timestamp } from "firebase-admin/firestore";
 import { MicrosecondTimestamp } from "@ddd-ts/shape";
 import { Cursor as Cursor$1 } from "@ddd-ts/core/dist/components/cursor";
 
@@ -21,20 +21,20 @@ var FirestoreProjectedStreamStorageLayer = class {
 		this.converter = converter;
 	}
 	async *read(projectedStream, shard, startAfter, endAt) {
-		let query = this.firestore.collectionGroup("events").orderBy("occurredAt").orderBy("revision");
+		let query = this.firestore.collectionGroup("events").orderBy("occurredAt").orderBy("revision").orderBy(FieldPath.documentId());
 		const filters = projectedStream.sources.map((source) => {
 			if (source instanceof LakeSource) return new FirestoreLakeSourceFilter().filter(shard, source);
 			if (source instanceof StreamSource) return new FirestoreStreamSourceFilter().filter(shard, source);
 			throw new Error("Unknown source type");
 		});
 		query = query.where(Filter.or(...filters));
-		if (startAfter) {
+		if (startAfter && !startAfter.isMin()) {
 			const ts = this.microsecondToTimestamp(startAfter.occurredAt);
-			query = query.startAfter(ts, startAfter.revision);
+			query = query.startAfter(ts, startAfter.revision, this.firestore.doc(startAfter.ref));
 		}
-		if (endAt) {
+		if (endAt && !endAt.isMax()) {
 			const ts = this.microsecondToTimestamp(endAt.occurredAt);
-			query = query.endAt(ts, endAt.revision);
+			query = query.endAt(ts, endAt.revision, this.firestore.doc(endAt.ref));
 		}
 		for await (const doc of query.stream()) {
 			const data = this.converter.fromFirestore(doc);
@@ -82,20 +82,20 @@ var FirestoreProjectedStreamStorageLayer = class {
 		});
 	}
 	async slice(projectedStream, shard, startAfter, endAt, limit) {
-		let query = this.firestore.collectionGroup("events").orderBy("occurredAt").orderBy("revision");
+		let query = this.firestore.collectionGroup("events").orderBy("occurredAt").orderBy("revision").orderBy(FieldPath.documentId());
 		const filters = projectedStream.sources.map((source) => {
 			if (source instanceof LakeSource) return new FirestoreLakeSourceFilter().filter(shard, source);
 			if (source instanceof StreamSource) return new FirestoreStreamSourceFilter().filter(shard, source);
 			throw new Error("Unknown source type");
 		});
 		query = query.where(Filter.or(...filters));
-		if (startAfter) {
+		if (startAfter && !startAfter.isMin()) {
 			const ts = this.microsecondToTimestamp(startAfter.occurredAt);
-			query = query.startAfter(ts, startAfter.revision);
+			query = query.startAfter(ts, startAfter.revision, this.firestore.doc(startAfter.ref));
 		}
-		if (endAt) {
+		if (endAt && !endAt.isMax()) {
 			const ts = this.microsecondToTimestamp(endAt.occurredAt);
-			query = query.endAt(ts, endAt.revision);
+			query = query.endAt(ts, endAt.revision, this.firestore.doc(endAt.ref));
 		}
 		if (limit) query = query.limit(limit);
 		return (await query.get()).docs.map((doc) => {
@@ -112,6 +112,51 @@ var FirestoreProjectedStreamStorageLayer = class {
 			};
 		});
 	}
+	async firstAtOrAfter(projectedStream, shard, from) {
+		const ts = this.microsecondToTimestamp(from);
+		let query = this.firestore.collectionGroup("events").orderBy("occurredAt").orderBy("revision").orderBy(FieldPath.documentId());
+		const filters = projectedStream.sources.map((source) => {
+			if (source instanceof LakeSource) return new FirestoreLakeSourceFilter().filter(shard, source);
+			if (source instanceof StreamSource) return new FirestoreStreamSourceFilter().filter(shard, source);
+			throw new Error("Unknown source type");
+		});
+		query = query.where(Filter.or(...filters)).startAt(ts).limit(1);
+		const doc = (await query.get()).docs[0];
+		if (!doc) return void 0;
+		const data = this.converter.fromFirestore(doc);
+		return {
+			id: data.eventId,
+			ref: doc.ref.path,
+			revision: data.revision,
+			name: data.name,
+			$name: data.name,
+			payload: data.payload,
+			occurredAt: data.occurredAt,
+			version: data.version ?? 1
+		};
+	}
+	async latest(projectedStream, shard) {
+		let query = this.firestore.collectionGroup("events").orderBy("occurredAt", "desc").orderBy("revision", "desc").orderBy(FieldPath.documentId(), "desc").limit(1);
+		const filters = projectedStream.sources.map((source) => {
+			if (source instanceof LakeSource) return new FirestoreLakeSourceFilter().filter(shard, source);
+			if (source instanceof StreamSource) return new FirestoreStreamSourceFilter().filter(shard, source);
+			throw new Error("Unknown source type");
+		});
+		query = query.where(Filter.or(...filters));
+		const doc = (await query.get()).docs[0];
+		if (!doc) return void 0;
+		const data = this.converter.fromFirestore(doc);
+		return {
+			id: data.eventId,
+			ref: doc.ref.path,
+			revision: data.revision,
+			name: data.name,
+			$name: data.name,
+			payload: data.payload,
+			occurredAt: data.occurredAt,
+			version: data.version ?? 1
+		};
+	}
 };
 
 //#endregion

package/dist/projection/cases/replay-api.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=replay-api.spec.d.ts.map

package/dist/projection/cases/replay-api.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-api.spec.d.ts","sourceRoot":"","sources":["../../../src/projection/cases/replay-api.spec.ts"],"names":[],"mappings":""}

package/dist/projection/cases/tiedcursor.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tiedcursor.spec.d.ts.map

package/dist/projection/cases/tiedcursor.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tiedcursor.spec.d.ts","sourceRoot":"","sources":["../../../src/projection/cases/tiedcursor.spec.ts"],"names":[],"mappings":""}

package/dist/projection/firestore.projector.d.ts

@@ -1,4 +1,4 @@
-import { CheckpointId, Cursor, ESProjection, EventId, type IEsEvent, type IFact, type ISavedChange, Lock, ProjectedStreamReader, type Serialized } from "@ddd-ts/core";
+import { CheckpointId, Cursor, ESProjection, EventId, type IEsEvent, type IFact, type ISavedChange, Lock, ProjectedStream, ProjectedStreamReader, type Serialized } from "@ddd-ts/core";
 import { Mapping, MicrosecondTimestamp } from "@ddd-ts/shape";
 import { DefaultConverter, FirestoreTransaction } from "@ddd-ts/store-firestore";
 import { Firestore, WriteBatch } from "firebase-admin/firestore";
@@ -18,6 +18,23 @@ interface FirestoreProjectorConfig {
     enqueue: {
         batchSize: number;
     };
+    /**
+     * Controls retention of processed queue tasks.
+     *
+     * - `false` (default): never delete processed tasks. Preserves the queue
+     *   as a durable audit trail for replay diagnostics.
+     * - `{ olderThan }`: delete processed tasks older than `olderThan` after
+     *   each successful event handling.
+     */
+    cleanup?: false | {
+        olderThan: MicrosecondTimestamp;
+    };
+    /**
+     * Optional pre-handle filter. Returning `false` causes `handle()` to
+     * return without enqueuing or processing the event. Useful for feature
+     * flags or per-shard gating without subclassing the projector.
+     */
+    shouldHandle?: (event: ISavedChange<IEsEvent>) => Promise<boolean> | boolean;
     logger?: ProjectorLogger;
     /** @deprecated Use `logger.error` instead */
     onProcessError: (error: Error) => void;
@@ -40,11 +57,53 @@ export declare class FirestoreProjector {
     handle(savedChange: ISavedChange<IEsEvent>): Promise<void>;
     private handleOne;
     private getCursor;
-    private attempt;
-    private getQueueHead;
+    attempt(source: ProjectedStream, checkpointId: CheckpointId, target: Cursor): Promise<readonly ["DEFERRED", any] | readonly ["OK", "Target event already processed"] | readonly ["FAILURE", any] | readonly ["OK", "Target event processed successfully"]>;
+    getQueueHead(checkpointId: CheckpointId): Promise<Cursor | undefined>;
     private readSourceStream;
-    private enqueue;
-    private enqueueOne;
+    enqueue(source: ProjectedStream, head: Cursor | undefined, checkpointId: CheckpointId, target: Cursor): Promise<readonly ["OK", "Tasks enqueued successfully"] | readonly ["DEFERRED", any]>;
+    enqueueOne(checkpointId: CheckpointId, target: Cursor): Promise<readonly ["OK", "Tasks enqueued successfully"] | readonly ["DEFERRED", any]>;
+    /**
+     * Enqueue all source events between the current queue head (exclusive)
+     * and `until` (inclusive). Defaults to Cursor.MAX, i.e. "to the end of
+     * the stream".
+     */
+    enqueueUpTo(checkpointId: CheckpointId, until?: Cursor): Promise<readonly ["OK", "Tasks enqueued successfully"] | readonly ["DEFERRED", any]>;
+    /**
+     * Enqueue a single event by cursor. With `idempotent: true`, deletes any
+     * existing queued doc with the same eventId before re-creating, so a
+     * re-trigger after a partial replay doesn't fail with ALREADY_EXISTS.
+     */
+    enqueueCursor(checkpointId: CheckpointId, cursor: Cursor, opts?: {
+        idempotent?: boolean;
+    }): Promise<readonly ["OK", "Tasks enqueued successfully"] | readonly ["DEFERRED", any]>;
+    /**
+     * Drain the queue to completion: repeatedly call attempt() with the
+     * current head as target until no unprocessed tasks remain. Yields to
+     * the event loop between iterations.
+     */
+    dequeue(checkpointId: CheckpointId): Promise<void>;
+    /**
+     * Enqueue + drain in a loop until both phases are quiet. New events
+     * arriving mid-drain are picked up by the next enqueueUpTo cycle.
+     */
+    catchup(checkpointId: CheckpointId, opts?: {
+        deadlineMs?: number;
+    }): Promise<void>;
+    /**
+     * Replay a checkpoint. Blocks the queue head, wipes existing tasks
+     * (except the blocker), seeds the start cursor, unblocks, and runs
+     * catchup forward. Concurrent listen() calls are safe — events
+     * arriving mid-replay are coalesced or re-enqueued by catchup.
+     *
+     * Provide either `from` (a Cursor) or `fromDate` (a wall-clock Date).
+     * If neither is given, replays from the first event in the stream.
+     */
+    play(checkpointId: CheckpointId, opts?: {
+        from?: Cursor;
+        fromDate?: Date;
+    }): Promise<void>;
+    playFrom(checkpointId: CheckpointId, fromDate: Date): Promise<void>;
+    private resolvePlayStart;
     private checkIsProcessed;
     private getUnprocessed;
     private claimTasks;
@@ -58,6 +117,7 @@ export declare class FirestoreQueueStore {
     db: Firestore;
     converter: DefaultConverter<FirebaseFirestore.DocumentData>;
     collection: FirebaseFirestore.CollectionReference;
+    static readonly BLOCKER_EVENT_ID: EventId;
     constructor(db: Firestore);
     private timestampToMicroseconds;
     private microsecondsToTimestamp;
@@ -82,8 +142,13 @@ export declare class FirestoreQueueStore {
         batchWriter?: WriteBatch;
     }): Promise<void>;
     getTailCursor(id: CheckpointId): Promise<Cursor | undefined>;
-    cleanup(id: CheckpointId): Promise<void>;
-    flush(id: CheckpointId): Promise<void>;
+    cleanup(id: CheckpointId, olderThan?: MicrosecondTimestamp): Promise<void>;
+    flush(id: CheckpointId, opts?: {
+        except?: EventId[];
+    }): Promise<void>;
+    hasUnprocessed(checkpointId: CheckpointId): Promise<boolean>;
+    block(checkpointId: CheckpointId, blockerId?: EventId): Promise<void>;
+    unblock(checkpointId: CheckpointId, blockerId?: EventId): Promise<void>;
     /**
      * This method adds a fake processed event to the queue.
      * It is useful for initializing the tail cursor of a new projection, at the
@@ -105,16 +170,17 @@ declare const Task_base: import("@ddd-ts/shape").IDict<{
     readonly revision: NumberConstructor;
     readonly attempts: NumberConstructor;
     readonly processed: BooleanConstructor;
-    /** @deprecated */ readonly claimer: import("@ddd-ts/shape").IOptional<StringConstructor, typeof import("@ddd-ts/shape").Empty>;
+    readonly claimer: import("@ddd-ts/shape").IOptional<StringConstructor, typeof import("@ddd-ts/shape").Empty>;
     /** @deprecated */ readonly claimedAt: import("@ddd-ts/shape").IOptional<typeof MicrosecondTimestamp, typeof import("@ddd-ts/shape").Empty>;
     readonly claimsMetadata: Mapping<[{
         claimedAt: typeof MicrosecondTimestamp;
         processedAt: import("@ddd-ts/shape").IOptional<typeof MicrosecondTimestamp, typeof import("@ddd-ts/shape").Empty>;
     }], typeof import("@ddd-ts/shape").Empty>;
-    readonly claimIds: [StringConstructor];
+    /** @deprecated */ readonly claimIds: [StringConstructor];
     readonly lock: typeof Lock;
     readonly skipAfter: NumberConstructor;
     readonly remaining: NumberConstructor;
+    readonly hasRemaining: BooleanConstructor;
     readonly isolateAfter: NumberConstructor;
     readonly claimTimeout: NumberConstructor;
     readonly lastUpdateTime: import("@ddd-ts/shape").IOptional<typeof MicrosecondTimestamp, typeof import("@ddd-ts/shape").Empty>;
@@ -128,12 +194,11 @@ export declare class Task<Stored extends boolean> extends Task_base {
         skipAfter: number;
         isolateAfter: number;
     }): Task<false>;
-    get currentClaimId(): string | undefined;
     get isProcessing(): boolean;
     get isProcessed(): boolean;
     get shouldSkip(): boolean;
     get shouldIsolate(): boolean;
-    checkTimeout(): void;
+    hasTimedOut(): boolean | undefined;
     static deserializeWithLastUpdateTime(data: Omit<Serialized<Task<true>>, "lastUpdateTime">, timestamp?: MicrosecondTimestamp): Task<true>;
     static batch(tasks: Task<true>[]): Task<true>[];
 }

package/dist/projection/firestore.projector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"firestore.projector.d.ts","sourceRoot":"","sources":["../../src/projection/firestore.projector.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"firestore.projector.d.ts","sourceRoot":"","sources":["../../src/projection/firestore.projector.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,MAAM,EACN,YAAY,EACZ,OAAO,EACP,KAAK,QAAQ,EACb,KAAK,KAAK,EACV,KAAK,YAAY,EACjB,IAAI,EACJ,eAAe,EACf,qBAAqB,EACrB,KAAK,UAAU,EAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAmB,MAAM,eAAe,CAAC;AAC/E,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACrB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAEL,SAAS,EAET,UAAU,EACX,MAAM,0BAA0B,CAAC;AAmBlC,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAChE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACjE;AASD,UAAU,wBAAwB;IAChC,KAAK,EAAE;QACL,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,OAAO,EAAE;QACP,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,KAAK,GAAG;QAAE,SAAS,EAAE,oBAAoB,CAAA;KAAE,CAAC;IACtD;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAC7E,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,6CAA6C;IAC7C,cAAc,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACvC,6CAA6C;IAC7C,cAAc,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACxC;AAED,qBAAa,kBAAkB;aAIX,UAAU,EAAE,YAAY,CAAC,QAAQ,CAAC;aAClC,MAAM,EAAE,qBAAqB,CAAC,QAAQ,CAAC;aACvC,KAAK,EAAE,mBAAmB;IACnC,MAAM,EAAE,wBAAwB;IANzC,QAAQ,UAAQ;gBAGE,UAAU,EAAE,YAAY,CAAC,QAAQ,CAAC,EAClC,MAAM,EAAE,qBAAqB,CAAC,QAAQ,CAAC,EACvC,KAAK,EAAE,mBAAmB,EACnC,MAAM,GAAE,wBAUd;IAGH,OAAO,KAAK,MAAM,GAEjB;IAEM,OAAO;IAwBd,OAAO,CAAC,qBAAqB,CAGf;IACd,OAAO,CAAC,eAAe,CAAkC;IAMzD,OAAO,CAAC,cAAc,CAGR;IAEd,OAAO,CAAC,mBAAmB;IASrB,MAAM,CAAC,WAAW,EAAE,YAAY,CAAC,QAAQ,CAAC;YAmHlC,SAAS;YAwDT,SAAS;IAKjB,OAAO,CACX,MAAM,EAAE,eAAe,EACvB,YAAY,EAAE,YAAY,EAC1B,MAAM,EAAE,MAAM;IA8DV,YAAY,CAAC,YAAY,EAAE,YAAY;YAK/B,gBAAgB;IAaxB,OAAO,CACX,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,YAAY,EAAE,YAAY,EAC1B,MAAM,EAAE,MAAM;IAoCV,UAAU,CAAC,YAAY,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM;IAkB3D;;;;OAIG;IACG,WAAW,CAAC,YAAY,EAAE,YAAY,EAAE,KAAK,GAAE,MAAmB;IAMxE;;;;OAIG;IACG,aAAa,CACjB,YAAY,EAAE,YAAY,EAC1B,MAAM,EAAE,MAAM,EACd,IAAI,GAAE;QAAE,UAAU,CAAC,EAAE,OAAO,CAAA;KAAO;IAQrC;;;;OAIG;IACG,OAAO,CAAC,YAAY,EAAE,YAAY;IAUxC;;;OAGG;IACG,OAAO,CACX,YAAY,EAAE,YAAY,EAC1B,IAAI,GAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAO;IAgBpC;;;;;;;;OAQG;IACG,IAAI,CACR,YAAY,EAAE,YAAY,EAC1B,IAAI,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,IAAI,CAAA;KAAO;IAsBzC,QAAQ,CAAC,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI;YAI3C,gBAAgB;YAsBhB,gBAAgB;YAKhB,cAAc;YAKd,UAAU;YAcV,aAAa;YA+Db,kBAAkB;CAyBjC;AAED,qBAAa,oBAAqB,SAAQ,KAAK;;CAK9C;AAED,qBAAa,mBAAmB;IASX,EAAE,EAAE,SAAS;IARhC,SAAS,mDAA0B;IACnC,UAAU,EAAE,iBAAiB,CAAC,mBAAmB,CAAC;IAKlD,MAAM,CAAC,QAAQ,CAAC,gBAAgB,UAA4B;gBAEzC,EAAE,EAAE,SAAS;IAMhC,OAAO,CAAC,uBAAuB;IAO/B,OAAO,CAAC,uBAAuB;IAQzB,OAAO,CAAC,YAAY,EAAE,YAAY,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE;IA0BxD,KAAK,CACT,YAAY,EAAE,YAAY,EAC1B,OAAO,EAAE,SAAS,EAClB,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE;IAmCf,IAAI,CAAC,YAAY,EAAE,YAAY;IA0B/B,WAAW,CAAC,YAAY,EAAE,YAAY;IAmCtC,OAAO,CACX,YAAY,EAAE,YAAY,EAC1B,OAAO,EAAE,SAAS,GACjB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IAiBlB,OAAO,CAAC,YAAY,EAAE,YAAY,EAAE,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE;IAmB7D;;;;;OAKG;IACG,WAAW,CAAC,YAAY,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM;IAgB5D,UAAU,CAAC,EAAE,EAAE,YAAY;IAI3B,KAAK,CAAC,EAAE,EAAE,YAAY;IAItB,MAAM,CAAC,EAAE,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO;IAInC,SAAS,CACb,SAAS,EAAE,SAAS,EACpB,EAAE,EAAE,YAAY,EAChB,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,GAAE;QACP,WAAW,CAAC,EAAE,oBAAoB,CAAC;QACnC,WAAW,CAAC,EAAE,UAAU,CAAC;KACrB;IA6BF,aAAa,CAAC,EAAE,EAAE,YAAY;IA2B9B,OAAO,CACX,EAAE,EAAE,YAAY,EAChB,SAAS,GAAE,oBAAwD;IA6B/D,KAAK,CAAC,EAAE,EAAE,YAAY,EAAE,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,OAAO,EAAE,CAAA;KAAO;IAWzD,cAAc,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;IAS5D,KAAK,CACT,YAAY,EAAE,YAAY,EAC1B,SAAS,GAAE,OAA8C;IA+BrD,OAAO,CACX,YAAY,EAAE,YAAY,EAC1B,SAAS,GAAE,OAA8C;IAK3D;;;;;;;;;OASG;IACG,IAAI,CAAC,YAAY,EAAE,YAAY;CAwCtC;AAED,qBAAa,SAAU,SAAQ,OAAO;CAAG;;;;;;;;;IAavC,kBAAkB;;;;;IAOlB,kBAAkB;;;;;;;;;AAnBpB,qBAAa,IAAI,CAAC,MAAM,SAAS,OAAO,CAAE,SAAQ,SA2BhD;IACQ,cAAc,EAAE,MAAM,SAAS,IAAI,GACvC,oBAAoB,GACpB,SAAS,CAAC;IAEd,IAAI,MAAM,WAOT;IAED,MAAM,CAAC,GAAG,CACR,IAAI,EAAE,KAAK,EACX,MAAM,EAAE;QACN,IAAI,EAAE,IAAI,CAAC;QACX,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;KACtB,GACA,IAAI,CAAC,KAAK,CAAC;IAuBd,IAAI,YAAY,YAEf;IAED,IAAI,WAAW,YAEd;IAED,IAAI,UAAU,YAEb;IAED,IAAI,aAAa,YAEhB;IAED,WAAW;IAaX,MAAM,CAAC,6BAA6B,CAClC,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,gBAAgB,CAAC,EACpD,SAAS,CAAC,EAAE,oBAAoB,GAC/B,IAAI,CAAC,IAAI,CAAC;IAab,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE;CA0DjC"}

package/dist/projection/firestore.projector.js

@@ -71,6 +71,9 @@ var FirestoreProjector = class {
 		for (const eventId of eventIds) pending.delete(eventId.serialize());
 	}
 	async handle(savedChange) {
+		if (this.config.shouldHandle) {
+			if (!await this.config.shouldHandle(savedChange)) return;
+		}
 		const key = this.projection.getCheckpointId(savedChange).serialize();
 		const cursor = await this.getCursor(savedChange);
 		if (!cursor) throw new Error(`Cursor not found for event ${savedChange.id.serialize()}`);
@@ -170,7 +173,7 @@ var FirestoreProjector = class {
 				continue;
 			}
 			if (status === Status.SUCCESS) {
-				await this.queue.cleanup(checkpointId);
+				if (this.config.cleanup) await this.queue.cleanup(checkpointId, this.config.cleanup.olderThan);
 				const durationMs = Date.now() - startedAt;
 				this.logger.info(`processed: Checkpoint<${checkpointKey}> caught up to Event<${eventId}> in ${durationMs}ms`, {
 					checkpointId: checkpointKey,
@@ -254,6 +257,90 @@ var FirestoreProjector = class {
 		if (status === Status.SUCCESS) this.prunePendingCursors(checkpointId, [task.id]);
 		return result;
 	}
+	/**
+	* Enqueue all source events between the current queue head (exclusive)
+	* and `until` (inclusive). Defaults to Cursor.MAX, i.e. "to the end of
+	* the stream".
+	*/
+	async enqueueUpTo(checkpointId, until = _ddd_ts_core.Cursor.MAX) {
+		const source = this.projection.getSource();
+		const head = await this.getQueueHead(checkpointId);
+		return this.enqueue(source, head, checkpointId, until);
+	}
+	/**
+	* Enqueue a single event by cursor. With `idempotent: true`, deletes any
+	* existing queued doc with the same eventId before re-creating, so a
+	* re-trigger after a partial replay doesn't fail with ALREADY_EXISTS.
+	*/
+	async enqueueCursor(checkpointId, cursor, opts = {}) {
+		if (opts.idempotent) await this.queue.queued(checkpointId, cursor.eventId).delete();
+		return this.enqueueOne(checkpointId, cursor);
+	}
+	/**
+	* Drain the queue to completion: repeatedly call attempt() with the
+	* current head as target until no unprocessed tasks remain. Yields to
+	* the event loop between iterations.
+	*/
+	async dequeue(checkpointId) {
+		const source = this.projection.getSource();
+		while (await this.queue.hasUnprocessed(checkpointId)) {
+			const head = await this.getQueueHead(checkpointId);
+			if (!head) return;
+			await this.attempt(source, checkpointId, head);
+			await wait(10);
+		}
+	}
+	/**
+	* Enqueue + drain in a loop until both phases are quiet. New events
+	* arriving mid-drain are picked up by the next enqueueUpTo cycle.
+	*/
+	async catchup(checkpointId, opts = {}) {
+		const deadline = opts.deadlineMs ? Date.now() + opts.deadlineMs : void 0;
+		while (true) {
+			await this.enqueueUpTo(checkpointId);
+			if (!await this.queue.hasUnprocessed(checkpointId)) return;
+			await this.dequeue(checkpointId);
+			if (deadline !== void 0 && Date.now() > deadline) throw new Error(`catchup: deadline of ${opts.deadlineMs}ms exceeded for checkpoint ${checkpointId.serialize()}`);
+		}
+	}
+	/**
+	* Replay a checkpoint. Blocks the queue head, wipes existing tasks
+	* (except the blocker), seeds the start cursor, unblocks, and runs
+	* catchup forward. Concurrent listen() calls are safe — events
+	* arriving mid-replay are coalesced or re-enqueued by catchup.
+	*
+	* Provide either `from` (a Cursor) or `fromDate` (a wall-clock Date).
+	* If neither is given, replays from the first event in the stream.
+	*/
+	async play(checkpointId, opts = {}) {
+		const start = await this.resolvePlayStart(checkpointId, opts);
+		if (!start) throw new Error(`play: no events found for checkpoint ${checkpointId.serialize()}`);
+		await this.queue.block(checkpointId);
+		try {
+			await this.queue.flush(checkpointId, { except: [FirestoreQueueStore.BLOCKER_EVENT_ID] });
+			await this.enqueueCursor(checkpointId, start, { idempotent: true });
+		} finally {
+			await this.queue.unblock(checkpointId);
+		}
+		await this.catchup(checkpointId);
+	}
+	async playFrom(checkpointId, fromDate) {
+		return this.play(checkpointId, { fromDate });
+	}
+	async resolvePlayStart(checkpointId, opts) {
+		if (opts.from) return opts.from;
+		const source = this.projection.getSource();
+		const shard = checkpointId.shard();
+		if (opts.fromDate) {
+			const fromMicros = _ddd_ts_shape.MicrosecondTimestamp.deserialize(opts.fromDate);
+			const fact = await this.reader.firstAtOrAfter(source, shard, fromMicros);
+			if (!fact) return void 0;
+			return _ddd_ts_core.Cursor.from(fact);
+		}
+		const fact = await this.reader.first(source, shard);
+		if (!fact) return void 0;
+		return _ddd_ts_core.Cursor.from(fact);
+	}
 	async checkIsProcessed(checkpointId, cursor) {
 		return await this.queue.isProcessed(checkpointId, cursor);
 	}
@@ -301,7 +388,7 @@ var FirestoreProjector = class {
 		for (const event of events) {
 			const task = claimedTasksMap.get(event.id.serialize());
 			if (!task) throw new Error(`Task not found for event ${event.id.serialize()} in claimer ${claimer.serialize()}`);
-			if (task.claimIds?.[0] !== claimer.serialize()) throw new Error(`Task ${task.id.serialize()} claimer mismatch: expected ${claimer.serialize()}, found ${task.claimIds?.[0]}`);
+			if (task.claimer !== claimer.serialize()) throw new Error(`Task ${task.id.serialize()} claimer mismatch: expected ${claimer.serialize()}, found ${task.claimer}`);
 		}
 	}
 };
@@ -311,9 +398,10 @@ var AlreadyEnqueuedError = class extends Error {
 		this.name = "AlreadyEnqueuedError";
 	}
 };
-var FirestoreQueueStore = class {
+var FirestoreQueueStore = class FirestoreQueueStore {
 	converter = new _ddd_ts_store_firestore.DefaultConverter();
 	collection;
+	static BLOCKER_EVENT_ID = new _ddd_ts_core.EventId("_blocker_");
 	constructor(db) {
 		this.db = db;
 		this.collection = db.collection("checkpoints");
@@ -331,8 +419,8 @@ var FirestoreQueueStore = class {
 		for (const task of tasks) {
 			const ref = this.queued(checkpointId, task.id);
 			batch.create(ref, {
-				ref: this.db.doc(task.cursor.ref),
-				...this.converter.toFirestore(task.serialize())
+				...this.converter.toFirestore(task.serialize()),
+				ref: task.cursor.ref
 			});
 		}
 		try {
@@ -346,21 +434,22 @@ var FirestoreQueueStore = class {
 	async claim(checkpointId, claimer, tasks) {
 		const batch = this.collection.firestore.batch();
 		for (const task of tasks) {
-			if (task.claimIds.length > 0) throw new Error(`Task ${task.id.serialize()} is already claimed by ${task.claimIds.join(", ")}`);
+			if (task.claimer !== void 0) throw new Error(`Task ${task.id.serialize()} is already claimed by ${task.claimer}`);
 			const ref = this.queued(checkpointId, task.id);
 			batch.update(ref, {
 				claimer: claimer.serialize(),
 				claimedAt: firebase_admin_firestore.FieldValue.serverTimestamp(),
 				[`claimsMetadata.${claimer.serialize()}`]: { claimedAt: firebase_admin_firestore.FieldValue.serverTimestamp() },
 				claimIds: firebase_admin_firestore.FieldValue.arrayUnion(claimer.serialize()),
-				attempts: firebase_admin_firestore.FieldValue.increment(1),
-				remaining: firebase_admin_firestore.FieldValue.increment(-1)
+				attempts: task.attempts + 1,
+				remaining: task.remaining - 1,
+				hasRemaining: task.remaining > 1
 			}, { lastUpdateTime: this.microsecondsToTimestamp(task.lastUpdateTime) });
 		}
 		await batch.commit();
 	}
 	async head(checkpointId) {
-		const headDoc = (await this.queue(checkpointId).orderBy("occurredAt", "desc").orderBy("revision", "desc").limit(1).get()).docs[0];
+		const headDoc = (await this.queue(checkpointId).orderBy("occurredAt", "desc").orderBy("revision", "desc").orderBy("ref", "desc").limit(1).get()).docs[0];
 		if (!headDoc) return;
 		const headData = this.converter.fromFirestoreSnapshot(headDoc);
 		if (!headData) return;
@@ -372,37 +461,27 @@ var FirestoreQueueStore = class {
 		}) : void 0;
 	}
 	async unprocessed(checkpointId) {
-		const tasks = (await this.queue(checkpointId).where("processed", "==", false).where("remaining", ">", 0).orderBy("occurredAt", "asc").orderBy("revision", "asc").limit(100).get()).docs.map((doc) => {
+		const tasks = (await this.queue(checkpointId).where("processed", "==", false).where("hasRemaining", "==", true).orderBy("occurredAt", "asc").orderBy("revision", "asc").orderBy("ref", "asc").limit(100).get()).docs.map((doc) => {
 			const data = this.converter.fromFirestoreSnapshot(doc);
 			const timestamp = doc.updateTime ? this.timestampToMicroseconds(doc.updateTime) : void 0;
 			return Task.deserializeWithLastUpdateTime(data, timestamp);
 		});
-		const expiredTasks = [];
-		for (const task of tasks) {
-			const originalClaimIds = task.claimIds;
-			task.checkTimeout();
-			if (originalClaimIds.length > task.claimIds.length) expiredTasks.push(task);
-		}
-		if (expiredTasks.length > 0) {
-			const batch = this.collection.firestore.batch();
-			for (const task of expiredTasks) {
-				const ref = this.queued(checkpointId, task.id);
-				batch.update(ref, {
-					claimer: firebase_admin_firestore.FieldValue.delete(),
-					claimedAt: firebase_admin_firestore.FieldValue.delete(),
-					claimIds: task.claimIds
-				}, { lastUpdateTime: this.microsecondsToTimestamp(task.lastUpdateTime) });
-			}
-			await batch.commit();
+		const expiredTasks = tasks.filter((task) => task.hasTimedOut());
+		if (expiredTasks.length === 0) return tasks;
+		await this.unclaim(checkpointId, expiredTasks);
+		for (const task of expiredTasks) {
+			task.claimIds = task.claimIds.filter((id) => id !== task.claimer);
+			task.claimer = void 0;
+			task.claimedAt = void 0;
 		}
 		return tasks;
 	}
 	async claimed(checkpointId, claimer) {
-		return (await this.queue(checkpointId).where("claimIds", "array-contains", claimer.serialize()).orderBy("occurredAt", "asc").orderBy("revision", "asc").get()).docs.map((doc) => {
+		return (await this.queue(checkpointId).where("claimer", "==", claimer.serialize()).orderBy("occurredAt", "asc").orderBy("revision", "asc").orderBy("ref", "asc").get()).docs.map((doc) => {
 			const data = this.converter.fromFirestoreSnapshot(doc);
 			const timestamp = doc.updateTime ? this.timestampToMicroseconds(doc.updateTime) : void 0;
 			return Task.deserializeWithLastUpdateTime(data, timestamp);
-		}).filter((task) => task.claimIds[0] === claimer.serialize());
+		});
 	}
 	async unclaim(checkpointId, tasks) {
 		const batch = this.collection.firestore.batch();
@@ -411,7 +490,7 @@ var FirestoreQueueStore = class {
 			batch.update(ref, {
 				claimer: firebase_admin_firestore.FieldValue.delete(),
 				claimedAt: firebase_admin_firestore.FieldValue.delete(),
-				claimIds: firebase_admin_firestore.FieldValue.arrayRemove(task.currentClaimId)
+				claimIds: firebase_admin_firestore.FieldValue.arrayRemove(task.claimer)
 			}, { lastUpdateTime: this.microsecondsToTimestamp(task.lastUpdateTime) });
 		}
 		await batch.commit();
@@ -461,7 +540,7 @@ var FirestoreQueueStore = class {
 		})));
 	}
 	async getTailCursor(id) {
-		const tailDoc = (await this.queue(id).where("remaining", ">", 0).orderBy("occurredAt", "asc").orderBy("revision", "asc").limit(1).get()).docs[0];
+		const tailDoc = (await this.queue(id).where("hasRemaining", "==", true).orderBy("occurredAt", "asc").orderBy("revision", "asc").orderBy("ref", "asc").limit(1).get()).docs[0];
 		if (!tailDoc) return;
 		const tailData = this.converter.fromFirestoreSnapshot(tailDoc);
 		if (!tailData) return;
@@ -472,9 +551,9 @@ var FirestoreQueueStore = class {
 			eventId: tailData.id
 		}) : void 0;
 	}
-	async cleanup(id) {
-		const aMonthAgo = _ddd_ts_shape.MicrosecondTimestamp.now().sub(_ddd_ts_shape.MicrosecondTimestamp.WEEK.mult(4));
-		const query = this.queue(id).where("remaining", ">", 0).where("occurredAt", "<", aMonthAgo.serialize()).orderBy("occurredAt", "asc").orderBy("revision", "asc");
+	async cleanup(id, olderThan = _ddd_ts_shape.MicrosecondTimestamp.WEEK.mult(4)) {
+		const threshold = _ddd_ts_shape.MicrosecondTimestamp.now().sub(olderThan);
+		const query = this.queue(id).where("hasRemaining", "==", true).where("occurredAt", "<", threshold.serialize()).orderBy("occurredAt", "asc").orderBy("revision", "asc").orderBy("ref", "asc");
 		const TRAIL = 1;
 		const snapshot = await query.get();
 		if (snapshot.size < TRAIL) return;
@@ -486,12 +565,50 @@ var FirestoreQueueStore = class {
 		for (const queued of cleaning) batch.delete(queued.ref);
 		await batch.commit();
 	}
-	async flush(id) {
+	async flush(id, opts = {}) {
+		const exclude = new Set((opts.except ?? []).map((e) => e.serialize()));
 		const stream = this.queue(id).stream();
 		const writer = this.collection.firestore.bulkWriter();
-		for await (const queued of stream) writer.delete(queued.ref);
+		for await (const queued of stream) {
+			if (exclude.has(queued.id)) continue;
+			writer.delete(queued.ref);
+		}
 		await writer.close();
 	}
+	async hasUnprocessed(checkpointId) {
+		return !(await this.queue(checkpointId).where("processed", "==", false).where("hasRemaining", "==", true).limit(1).get()).empty;
+	}
+	async block(checkpointId, blockerId = FirestoreQueueStore.BLOCKER_EVENT_ID) {
+		const task = new Task({
+			id: blockerId,
+			ref: _ddd_ts_core.Cursor.MAX.ref,
+			occurredAt: _ddd_ts_core.Cursor.MAX.occurredAt,
+			revision: _ddd_ts_core.Cursor.MAX.revision,
+			attempts: 0,
+			processed: true,
+			claimer: void 0,
+			claimedAt: void 0,
+			claimsMetadata: {},
+			claimIds: [],
+			lock: new _ddd_ts_core.Lock({}),
+			remaining: 1,
+			claimTimeout: 0,
+			skipAfter: 0,
+			isolateAfter: 0,
+			lastUpdateTime: void 0,
+			hasRemaining: true
+		});
+		await this.queued(checkpointId, blockerId).delete();
+		const serialized = task.serialize();
+		const converted = this.converter.toFirestore(serialized);
+		await this.queued(checkpointId, blockerId).create({
+			...converted,
+			ref: _ddd_ts_core.Cursor.MAX.ref
+		});
+	}
+	async unblock(checkpointId, blockerId = FirestoreQueueStore.BLOCKER_EVENT_ID) {
+		await this.queued(checkpointId, blockerId).delete();
+	}
 	/**
 	* This method adds a fake processed event to the queue.
 	* It is useful for initializing the tail cursor of a new projection, at the
@@ -525,7 +642,8 @@ var FirestoreQueueStore = class {
 			claimTimeout: 0,
 			skipAfter: 0,
 			isolateAfter: 0,
-			lastUpdateTime: void 0
+			lastUpdateTime: void 0,
+			hasRemaining: true
 		});
 		try {
 			const serialized = task.serialize();
@@ -554,6 +672,7 @@ var Task = class Task extends (0, _ddd_ts_shape.Shape)({
 	lock: _ddd_ts_core.Lock,
 	skipAfter: Number,
 	remaining: Number,
+	hasRemaining: Boolean,
 	isolateAfter: Number,
 	claimTimeout: Number,
 	lastUpdateTime: (0, _ddd_ts_shape.Optional)(_ddd_ts_shape.MicrosecondTimestamp)
@@ -580,17 +699,15 @@ var Task = class Task extends (0, _ddd_ts_shape.Shape)({
 			skipAfter: config.skipAfter,
 			isolateAfter: config.isolateAfter,
 			remaining: config.skipAfter,
+			hasRemaining: config.skipAfter > 0,
 			ref: fact.ref,
 			revision: fact.revision,
 			occurredAt: fact.occurredAt,
 			lastUpdateTime: void 0
 		});
 	}
-	get currentClaimId() {
-		return this.claimIds.at(-1);
-	}
 	get isProcessing() {
-		return this.currentClaimId !== void 0;
+		return this.claimer !== void 0;
 	}
 	get isProcessed() {
 		return !!this.processed;
@@ -601,19 +718,19 @@ var Task = class Task extends (0, _ddd_ts_shape.Shape)({
 	get shouldIsolate() {
 		return this.attempts > this.isolateAfter;
 	}
-	checkTimeout() {
-		const claimer = this.currentClaimId;
-		if (!claimer) return;
-		const claimInfo = this.claimsMetadata[claimer];
+	hasTimedOut() {
+		if (!this.claimer) return;
+		const claimInfo = this.claimsMetadata[this.claimer];
 		if (!claimInfo || !claimInfo.claimedAt) return;
-		if (_ddd_ts_shape.MicrosecondTimestamp.now().micros - claimInfo.claimedAt.micros > BigInt(this.claimTimeout) * 1000n) this.claimIds = this.claimIds.filter((id) => id !== claimer);
+		return _ddd_ts_shape.MicrosecondTimestamp.now().micros - claimInfo.claimedAt.micros > BigInt(this.claimTimeout) * 1000n;
 	}
 	static deserializeWithLastUpdateTime(data, timestamp) {
 		return Task.deserialize({
 			...data,
 			lastUpdateTime: timestamp,
 			claimIds: data.claimIds || [],
-			claimsMetadata: data.claimsMetadata || {}
+			claimsMetadata: data.claimsMetadata || {},
+			hasRemaining: data.hasRemaining ?? data.remaining > 0
 		});
 	}
 	static batch(tasks) {

package/dist/projection/firestore.projector.mjs

@@ -70,6 +70,9 @@ var FirestoreProjector = class {
 		for (const eventId of eventIds) pending.delete(eventId.serialize());
 	}
 	async handle(savedChange) {
+		if (this.config.shouldHandle) {
+			if (!await this.config.shouldHandle(savedChange)) return;
+		}
 		const key = this.projection.getCheckpointId(savedChange).serialize();
 		const cursor = await this.getCursor(savedChange);
 		if (!cursor) throw new Error(`Cursor not found for event ${savedChange.id.serialize()}`);
@@ -169,7 +172,7 @@ var FirestoreProjector = class {
 				continue;
 			}
 			if (status === Status.SUCCESS) {
-				await this.queue.cleanup(checkpointId);
+				if (this.config.cleanup) await this.queue.cleanup(checkpointId, this.config.cleanup.olderThan);
 				const durationMs = Date.now() - startedAt;
 				this.logger.info(`processed: Checkpoint<${checkpointKey}> caught up to Event<${eventId}> in ${durationMs}ms`, {
 					checkpointId: checkpointKey,
@@ -253,6 +256,90 @@ var FirestoreProjector = class {
 		if (status === Status.SUCCESS) this.prunePendingCursors(checkpointId, [task.id]);
 		return result;
 	}
+	/**
+	* Enqueue all source events between the current queue head (exclusive)
+	* and `until` (inclusive). Defaults to Cursor.MAX, i.e. "to the end of
+	* the stream".
+	*/
+	async enqueueUpTo(checkpointId, until = Cursor.MAX) {
+		const source = this.projection.getSource();
+		const head = await this.getQueueHead(checkpointId);
+		return this.enqueue(source, head, checkpointId, until);
+	}
+	/**
+	* Enqueue a single event by cursor. With `idempotent: true`, deletes any
+	* existing queued doc with the same eventId before re-creating, so a
+	* re-trigger after a partial replay doesn't fail with ALREADY_EXISTS.
+	*/
+	async enqueueCursor(checkpointId, cursor, opts = {}) {
+		if (opts.idempotent) await this.queue.queued(checkpointId, cursor.eventId).delete();
+		return this.enqueueOne(checkpointId, cursor);
+	}
+	/**
+	* Drain the queue to completion: repeatedly call attempt() with the
+	* current head as target until no unprocessed tasks remain. Yields to
+	* the event loop between iterations.
+	*/
+	async dequeue(checkpointId) {
+		const source = this.projection.getSource();
+		while (await this.queue.hasUnprocessed(checkpointId)) {
+			const head = await this.getQueueHead(checkpointId);
+			if (!head) return;
+			await this.attempt(source, checkpointId, head);
+			await wait(10);
+		}
+	}
+	/**
+	* Enqueue + drain in a loop until both phases are quiet. New events
+	* arriving mid-drain are picked up by the next enqueueUpTo cycle.
+	*/
+	async catchup(checkpointId, opts = {}) {
+		const deadline = opts.deadlineMs ? Date.now() + opts.deadlineMs : void 0;
+		while (true) {
+			await this.enqueueUpTo(checkpointId);
+			if (!await this.queue.hasUnprocessed(checkpointId)) return;
+			await this.dequeue(checkpointId);
+			if (deadline !== void 0 && Date.now() > deadline) throw new Error(`catchup: deadline of ${opts.deadlineMs}ms exceeded for checkpoint ${checkpointId.serialize()}`);
+		}
+	}
+	/**
+	* Replay a checkpoint. Blocks the queue head, wipes existing tasks
+	* (except the blocker), seeds the start cursor, unblocks, and runs
+	* catchup forward. Concurrent listen() calls are safe — events
+	* arriving mid-replay are coalesced or re-enqueued by catchup.
+	*
+	* Provide either `from` (a Cursor) or `fromDate` (a wall-clock Date).
+	* If neither is given, replays from the first event in the stream.
+	*/
+	async play(checkpointId, opts = {}) {
+		const start = await this.resolvePlayStart(checkpointId, opts);
+		if (!start) throw new Error(`play: no events found for checkpoint ${checkpointId.serialize()}`);
+		await this.queue.block(checkpointId);
+		try {
+			await this.queue.flush(checkpointId, { except: [FirestoreQueueStore.BLOCKER_EVENT_ID] });
+			await this.enqueueCursor(checkpointId, start, { idempotent: true });
+		} finally {
+			await this.queue.unblock(checkpointId);
+		}
+		await this.catchup(checkpointId);
+	}
+	async playFrom(checkpointId, fromDate) {
+		return this.play(checkpointId, { fromDate });
+	}
+	async resolvePlayStart(checkpointId, opts) {
+		if (opts.from) return opts.from;
+		const source = this.projection.getSource();
+		const shard = checkpointId.shard();
+		if (opts.fromDate) {
+			const fromMicros = MicrosecondTimestamp.deserialize(opts.fromDate);
+			const fact = await this.reader.firstAtOrAfter(source, shard, fromMicros);
+			if (!fact) return void 0;
+			return Cursor.from(fact);
+		}
+		const fact = await this.reader.first(source, shard);
+		if (!fact) return void 0;
+		return Cursor.from(fact);
+	}
 	async checkIsProcessed(checkpointId, cursor) {
 		return await this.queue.isProcessed(checkpointId, cursor);
 	}
@@ -300,7 +387,7 @@ var FirestoreProjector = class {
 		for (const event of events) {
 			const task = claimedTasksMap.get(event.id.serialize());
 			if (!task) throw new Error(`Task not found for event ${event.id.serialize()} in claimer ${claimer.serialize()}`);
-			if (task.claimIds?.[0] !== claimer.serialize()) throw new Error(`Task ${task.id.serialize()} claimer mismatch: expected ${claimer.serialize()}, found ${task.claimIds?.[0]}`);
+			if (task.claimer !== claimer.serialize()) throw new Error(`Task ${task.id.serialize()} claimer mismatch: expected ${claimer.serialize()}, found ${task.claimer}`);
 		}
 	}
 };
@@ -310,9 +397,10 @@ var AlreadyEnqueuedError = class extends Error {
 		this.name = "AlreadyEnqueuedError";
 	}
 };
-var FirestoreQueueStore = class {
+var FirestoreQueueStore = class FirestoreQueueStore {
 	converter = new DefaultConverter();
 	collection;
+	static BLOCKER_EVENT_ID = new EventId("_blocker_");
 	constructor(db) {
 		this.db = db;
 		this.collection = db.collection("checkpoints");
@@ -330,8 +418,8 @@ var FirestoreQueueStore = class {
 		for (const task of tasks) {
 			const ref = this.queued(checkpointId, task.id);
 			batch.create(ref, {
-				ref: this.db.doc(task.cursor.ref),
-				...this.converter.toFirestore(task.serialize())
+				...this.converter.toFirestore(task.serialize()),
+				ref: task.cursor.ref
 			});
 		}
 		try {
@@ -345,21 +433,22 @@ var FirestoreQueueStore = class {
 	async claim(checkpointId, claimer, tasks) {
 		const batch = this.collection.firestore.batch();
 		for (const task of tasks) {
-			if (task.claimIds.length > 0) throw new Error(`Task ${task.id.serialize()} is already claimed by ${task.claimIds.join(", ")}`);
+			if (task.claimer !== void 0) throw new Error(`Task ${task.id.serialize()} is already claimed by ${task.claimer}`);
 			const ref = this.queued(checkpointId, task.id);
 			batch.update(ref, {
 				claimer: claimer.serialize(),
 				claimedAt: FieldValue.serverTimestamp(),
 				[`claimsMetadata.${claimer.serialize()}`]: { claimedAt: FieldValue.serverTimestamp() },
 				claimIds: FieldValue.arrayUnion(claimer.serialize()),
-				attempts: FieldValue.increment(1),
-				remaining: FieldValue.increment(-1)
+				attempts: task.attempts + 1,
+				remaining: task.remaining - 1,
+				hasRemaining: task.remaining > 1
 			}, { lastUpdateTime: this.microsecondsToTimestamp(task.lastUpdateTime) });
 		}
 		await batch.commit();
 	}
 	async head(checkpointId) {
-		const headDoc = (await this.queue(checkpointId).orderBy("occurredAt", "desc").orderBy("revision", "desc").limit(1).get()).docs[0];
+		const headDoc = (await this.queue(checkpointId).orderBy("occurredAt", "desc").orderBy("revision", "desc").orderBy("ref", "desc").limit(1).get()).docs[0];
 		if (!headDoc) return;
 		const headData = this.converter.fromFirestoreSnapshot(headDoc);
 		if (!headData) return;
@@ -371,37 +460,27 @@ var FirestoreQueueStore = class {
 		}) : void 0;
 	}
 	async unprocessed(checkpointId) {
-		const tasks = (await this.queue(checkpointId).where("processed", "==", false).where("remaining", ">", 0).orderBy("occurredAt", "asc").orderBy("revision", "asc").limit(100).get()).docs.map((doc) => {
+		const tasks = (await this.queue(checkpointId).where("processed", "==", false).where("hasRemaining", "==", true).orderBy("occurredAt", "asc").orderBy("revision", "asc").orderBy("ref", "asc").limit(100).get()).docs.map((doc) => {
 			const data = this.converter.fromFirestoreSnapshot(doc);
 			const timestamp = doc.updateTime ? this.timestampToMicroseconds(doc.updateTime) : void 0;
 			return Task.deserializeWithLastUpdateTime(data, timestamp);
 		});
-		const expiredTasks = [];
-		for (const task of tasks) {
-			const originalClaimIds = task.claimIds;
-			task.checkTimeout();
-			if (originalClaimIds.length > task.claimIds.length) expiredTasks.push(task);
-		}
-		if (expiredTasks.length > 0) {
-			const batch = this.collection.firestore.batch();
-			for (const task of expiredTasks) {
-				const ref = this.queued(checkpointId, task.id);
-				batch.update(ref, {
-					claimer: FieldValue.delete(),
-					claimedAt: FieldValue.delete(),
-					claimIds: task.claimIds
-				}, { lastUpdateTime: this.microsecondsToTimestamp(task.lastUpdateTime) });
-			}
-			await batch.commit();
+		const expiredTasks = tasks.filter((task) => task.hasTimedOut());
+		if (expiredTasks.length === 0) return tasks;
+		await this.unclaim(checkpointId, expiredTasks);
+		for (const task of expiredTasks) {
+			task.claimIds = task.claimIds.filter((id) => id !== task.claimer);
+			task.claimer = void 0;
+			task.claimedAt = void 0;
 		}
 		return tasks;
 	}
 	async claimed(checkpointId, claimer) {
-		return (await this.queue(checkpointId).where("claimIds", "array-contains", claimer.serialize()).orderBy("occurredAt", "asc").orderBy("revision", "asc").get()).docs.map((doc) => {
+		return (await this.queue(checkpointId).where("claimer", "==", claimer.serialize()).orderBy("occurredAt", "asc").orderBy("revision", "asc").orderBy("ref", "asc").get()).docs.map((doc) => {
 			const data = this.converter.fromFirestoreSnapshot(doc);
 			const timestamp = doc.updateTime ? this.timestampToMicroseconds(doc.updateTime) : void 0;
 			return Task.deserializeWithLastUpdateTime(data, timestamp);
-		}).filter((task) => task.claimIds[0] === claimer.serialize());
+		});
 	}
 	async unclaim(checkpointId, tasks) {
 		const batch = this.collection.firestore.batch();
@@ -410,7 +489,7 @@ var FirestoreQueueStore = class {
 			batch.update(ref, {
 				claimer: FieldValue.delete(),
 				claimedAt: FieldValue.delete(),
-				claimIds: FieldValue.arrayRemove(task.currentClaimId)
+				claimIds: FieldValue.arrayRemove(task.claimer)
 			}, { lastUpdateTime: this.microsecondsToTimestamp(task.lastUpdateTime) });
 		}
 		await batch.commit();
@@ -460,7 +539,7 @@ var FirestoreQueueStore = class {
 		})));
 	}
 	async getTailCursor(id) {
-		const tailDoc = (await this.queue(id).where("remaining", ">", 0).orderBy("occurredAt", "asc").orderBy("revision", "asc").limit(1).get()).docs[0];
+		const tailDoc = (await this.queue(id).where("hasRemaining", "==", true).orderBy("occurredAt", "asc").orderBy("revision", "asc").orderBy("ref", "asc").limit(1).get()).docs[0];
 		if (!tailDoc) return;
 		const tailData = this.converter.fromFirestoreSnapshot(tailDoc);
 		if (!tailData) return;
@@ -471,9 +550,9 @@ var FirestoreQueueStore = class {
 			eventId: tailData.id
 		}) : void 0;
 	}
-	async cleanup(id) {
-		const aMonthAgo = MicrosecondTimestamp.now().sub(MicrosecondTimestamp.WEEK.mult(4));
-		const query = this.queue(id).where("remaining", ">", 0).where("occurredAt", "<", aMonthAgo.serialize()).orderBy("occurredAt", "asc").orderBy("revision", "asc");
+	async cleanup(id, olderThan = MicrosecondTimestamp.WEEK.mult(4)) {
+		const threshold = MicrosecondTimestamp.now().sub(olderThan);
+		const query = this.queue(id).where("hasRemaining", "==", true).where("occurredAt", "<", threshold.serialize()).orderBy("occurredAt", "asc").orderBy("revision", "asc").orderBy("ref", "asc");
 		const TRAIL = 1;
 		const snapshot = await query.get();
 		if (snapshot.size < TRAIL) return;
@@ -485,12 +564,50 @@ var FirestoreQueueStore = class {
 		for (const queued of cleaning) batch.delete(queued.ref);
 		await batch.commit();
 	}
-	async flush(id) {
+	async flush(id, opts = {}) {
+		const exclude = new Set((opts.except ?? []).map((e) => e.serialize()));
 		const stream = this.queue(id).stream();
 		const writer = this.collection.firestore.bulkWriter();
-		for await (const queued of stream) writer.delete(queued.ref);
+		for await (const queued of stream) {
+			if (exclude.has(queued.id)) continue;
+			writer.delete(queued.ref);
+		}
 		await writer.close();
 	}
+	async hasUnprocessed(checkpointId) {
+		return !(await this.queue(checkpointId).where("processed", "==", false).where("hasRemaining", "==", true).limit(1).get()).empty;
+	}
+	async block(checkpointId, blockerId = FirestoreQueueStore.BLOCKER_EVENT_ID) {
+		const task = new Task({
+			id: blockerId,
+			ref: Cursor.MAX.ref,
+			occurredAt: Cursor.MAX.occurredAt,
+			revision: Cursor.MAX.revision,
+			attempts: 0,
+			processed: true,
+			claimer: void 0,
+			claimedAt: void 0,
+			claimsMetadata: {},
+			claimIds: [],
+			lock: new Lock({}),
+			remaining: 1,
+			claimTimeout: 0,
+			skipAfter: 0,
+			isolateAfter: 0,
+			lastUpdateTime: void 0,
+			hasRemaining: true
+		});
+		await this.queued(checkpointId, blockerId).delete();
+		const serialized = task.serialize();
+		const converted = this.converter.toFirestore(serialized);
+		await this.queued(checkpointId, blockerId).create({
+			...converted,
+			ref: Cursor.MAX.ref
+		});
+	}
+	async unblock(checkpointId, blockerId = FirestoreQueueStore.BLOCKER_EVENT_ID) {
+		await this.queued(checkpointId, blockerId).delete();
+	}
 	/**
 	* This method adds a fake processed event to the queue.
 	* It is useful for initializing the tail cursor of a new projection, at the
@@ -524,7 +641,8 @@ var FirestoreQueueStore = class {
 			claimTimeout: 0,
 			skipAfter: 0,
 			isolateAfter: 0,
-			lastUpdateTime: void 0
+			lastUpdateTime: void 0,
+			hasRemaining: true
 		});
 		try {
 			const serialized = task.serialize();
@@ -553,6 +671,7 @@ var Task = class Task extends Shape({
 	lock: Lock,
 	skipAfter: Number,
 	remaining: Number,
+	hasRemaining: Boolean,
 	isolateAfter: Number,
 	claimTimeout: Number,
 	lastUpdateTime: Optional(MicrosecondTimestamp)
@@ -579,17 +698,15 @@ var Task = class Task extends Shape({
 			skipAfter: config.skipAfter,
 			isolateAfter: config.isolateAfter,
 			remaining: config.skipAfter,
+			hasRemaining: config.skipAfter > 0,
 			ref: fact.ref,
 			revision: fact.revision,
 			occurredAt: fact.occurredAt,
 			lastUpdateTime: void 0
 		});
 	}
-	get currentClaimId() {
-		return this.claimIds.at(-1);
-	}
 	get isProcessing() {
-		return this.currentClaimId !== void 0;
+		return this.claimer !== void 0;
 	}
 	get isProcessed() {
 		return !!this.processed;
@@ -600,19 +717,19 @@ var Task = class Task extends Shape({
 	get shouldIsolate() {
 		return this.attempts > this.isolateAfter;
 	}
-	checkTimeout() {
-		const claimer = this.currentClaimId;
-		if (!claimer) return;
-		const claimInfo = this.claimsMetadata[claimer];
+	hasTimedOut() {
+		if (!this.claimer) return;
+		const claimInfo = this.claimsMetadata[this.claimer];
 		if (!claimInfo || !claimInfo.claimedAt) return;
-		if (MicrosecondTimestamp.now().micros - claimInfo.claimedAt.micros > BigInt(this.claimTimeout) * 1000n) this.claimIds = this.claimIds.filter((id) => id !== claimer);
+		return MicrosecondTimestamp.now().micros - claimInfo.claimedAt.micros > BigInt(this.claimTimeout) * 1000n;
 	}
 	static deserializeWithLastUpdateTime(data, timestamp) {
 		return Task.deserialize({
 			...data,
 			lastUpdateTime: timestamp,
 			claimIds: data.claimIds || [],
-			claimsMetadata: data.claimsMetadata || {}
+			claimsMetadata: data.claimsMetadata || {},
+			hasRemaining: data.hasRemaining ?? data.remaining > 0
 		});
 	}
 	static batch(tasks) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ddd-ts/event-sourcing-firestore",
-  "version": "0.0.46",
+  "version": "0.0.48",
   "types": "dist/index.d.ts",
   "license": "MIT",
   "repository": {
@@ -10,19 +10,19 @@
     "dist"
   ],
   "dependencies": {
-    "@ddd-ts/core": "0.0.46",
-    "@ddd-ts/shape": "0.0.46",
-    "@ddd-ts/store-firestore": "0.0.46",
-    "@ddd-ts/traits": "0.0.46",
-    "@ddd-ts/types": "0.0.46",
+    "@ddd-ts/core": "0.0.48",
+    "@ddd-ts/shape": "0.0.48",
+    "@ddd-ts/store-firestore": "0.0.48",
+    "@ddd-ts/traits": "0.0.48",
+    "@ddd-ts/types": "0.0.48",
     "@opentelemetry/api": "1.6.0",
     "firebase-admin": "^13.2.0"
   },
   "devDependencies": {
-    "@ddd-ts/shape": "0.0.46",
-    "@ddd-ts/tests": "0.0.46",
-    "@ddd-ts/tools": "0.0.46",
-    "@ddd-ts/types": "0.0.46",
+    "@ddd-ts/shape": "0.0.48",
+    "@ddd-ts/tests": "0.0.48",
+    "@ddd-ts/tools": "0.0.48",
+    "@ddd-ts/types": "0.0.48",
     "@types/jest": "^29.5.1"
   },
   "exports": {