@classytic/arc 2.25.0 → 2.28.0

package/dist/testing/cleanupStoreContract.mjs

@@ -0,0 +1,375 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+//#region src/testing/cleanupStoreContract.ts
+/**
+* Cleanup Run-Store Contract Suite
+*
+* `CleanupRunStore` is the durability substrate of the Data Cleanup Center: its
+* atomic guarantees are the only thing standing between a crash and a
+* *double-executed destructive operation*. The semantics are subtle —
+* conditional insert by `concurrencyKey`, EXCLUSIVE lease claim with crash
+* recovery, lease-guarded CAS, admission-guarded re-arm — and a plausible-looking
+* adapter can get them wrong in ways no ordinary test catches.
+*
+* Any implementation can import this suite and run it against a live instance.
+* Passing it IS the contract.
+*
+* @example
+* ```typescript
+* import { runCleanupRunStoreContract } from '@classytic/arc/testing/cleanup';
+* import { mongoCleanupRunStore } from '../src/cleanup/mongo-run-store.js';
+*
+* runCleanupRunStoreContract('mongoCleanupRunStore', async () => {
+*   const store = mongoCleanupRunStore(connection);
+*   return { store, teardown: async () => connection.dropCollection('cleanup_runs') };
+* });
+* ```
+*
+* Time is exercised through lease `expiresAt` values in the past/future rather
+* than a clock hook, so the suite works unmodified against a real database
+* comparing to wall-clock `now`.
+*
+* This module statically imports `vitest`. Only load it from test code — arc's
+* production bundle never references this subpath, so the import tree stays
+* clean under tree-shaking.
+*/
+const ACTOR = {
+	ref: "user:contract",
+	kind: "user"
+};
+function plan(recipeId) {
+	return {
+		recipeId,
+		parameters: {},
+		items: [{
+			resource: "orders",
+			estimated: 1
+		}],
+		retains: [],
+		blockers: [],
+		rebuildActions: [],
+		warnings: [],
+		estimatedTotal: 1,
+		confirmationPhrase: recipeId,
+		digest: `digest-${recipeId}`
+	};
+}
+/** A queued run. `concurrencyKey` is opt-in so key-free runs can be exercised. */
+function makeRun(id, overrides = {}) {
+	return {
+		id,
+		recipeId: "contract.recipe",
+		recipeVersion: "1",
+		status: "queued",
+		planDigest: `digest-${id}`,
+		sealedPlan: plan("contract.recipe"),
+		parameters: {},
+		actor: ACTOR,
+		requestedBy: ACTOR.ref,
+		reason: "contract suite",
+		operationId: `op-${id}`,
+		destructive: true,
+		attempt: 0,
+		progress: {
+			processed: 0,
+			steps: 0
+		},
+		cancelRequested: false,
+		queuedAt: /* @__PURE__ */ new Date(),
+		...overrides
+	};
+}
+const future = (ms = 6e4) => new Date(Date.now() + ms);
+const past = (ms = 6e4) => new Date(Date.now() - ms);
+function runCleanupRunStoreContract(name, setup) {
+	describe(`CleanupRunStore contract: ${name}`, () => {
+		let store;
+		let teardown;
+		let seq = 0;
+		const uid = (label) => `${label}-${Date.now()}-${seq++}`;
+		beforeAll(async () => {
+			const result = await setup();
+			store = result.store;
+			teardown = result.teardown;
+		});
+		afterAll(async () => {
+			if (teardown) await teardown();
+		});
+		describe("createIfPermitted — admission control", () => {
+			it("inserts a run and makes it readable", async () => {
+				const run = makeRun(uid("insert"), { concurrencyKey: void 0 });
+				expect(await store.createIfPermitted(run)).toEqual({ created: true });
+				const stored = await store.get(run.id);
+				expect(stored?.id).toBe(run.id);
+				expect(stored?.status).toBe("queued");
+			});
+			it("returns null from get() for an unknown id", async () => {
+				expect(await store.get(uid("missing"))).toBeNull();
+			});
+			it("refuses a second non-terminal run holding the same concurrencyKey", async () => {
+				const key = uid("key");
+				const first = makeRun(uid("first"), { concurrencyKey: key });
+				const second = makeRun(uid("second"), { concurrencyKey: key });
+				expect(await store.createIfPermitted(first)).toEqual({ created: true });
+				const result = await store.createIfPermitted(second);
+				expect(result.created).toBe(false);
+				if (result.created === false) expect(result.activeRunId).toBe(first.id);
+				expect(await store.get(second.id)).toBeNull();
+			});
+			it("admits the key again once the holder reaches a terminal status", async () => {
+				const key = uid("key-free");
+				const first = makeRun(uid("holder"), { concurrencyKey: key });
+				await store.createIfPermitted(first);
+				await store.compareAndTransition(first.id, ["queued"], "completed");
+				const next = makeRun(uid("next"), { concurrencyKey: key });
+				expect(await store.createIfPermitted(next)).toEqual({ created: true });
+			});
+			it("never serializes runs that carry no concurrencyKey", async () => {
+				const a = makeRun(uid("keyless-a"), { concurrencyKey: void 0 });
+				const b = makeRun(uid("keyless-b"), { concurrencyKey: void 0 });
+				expect(await store.createIfPermitted(a)).toEqual({ created: true });
+				expect(await store.createIfPermitted(b)).toEqual({ created: true });
+			});
+		});
+		describe("claim — exclusive worker lease", () => {
+			it("grants the lease on a queued run and counts the attempt", async () => {
+				const run = makeRun(uid("claim"), { concurrencyKey: void 0 });
+				await store.createIfPermitted(run);
+				const token = uid("token");
+				const claimed = await store.claim(run.id, {
+					token,
+					expiresAt: future()
+				});
+				expect(claimed).not.toBeNull();
+				expect(claimed?.leaseToken).toBe(token);
+				expect(claimed?.attempt).toBe(run.attempt + 1);
+			});
+			it("refuses a run whose lease is still live (another worker owns it)", async () => {
+				const run = makeRun(uid("owned"), { concurrencyKey: void 0 });
+				await store.createIfPermitted(run);
+				await store.claim(run.id, {
+					token: uid("owner"),
+					expiresAt: future()
+				});
+				await store.compareAndTransition(run.id, ["queued"], "running");
+				expect(await store.claim(run.id, {
+					token: uid("thief"),
+					expiresAt: future()
+				})).toBeNull();
+			});
+			it("recovers a running run whose lease EXPIRED (crash recovery)", async () => {
+				const run = makeRun(uid("crashed"), { concurrencyKey: void 0 });
+				await store.createIfPermitted(run);
+				await store.claim(run.id, {
+					token: uid("dead"),
+					expiresAt: past()
+				});
+				await store.compareAndTransition(run.id, ["queued"], "running");
+				const token = uid("recovered");
+				const reclaimed = await store.claim(run.id, {
+					token,
+					expiresAt: future()
+				});
+				expect(reclaimed).not.toBeNull();
+				expect(reclaimed?.leaseToken).toBe(token);
+			});
+			it("recovers a finalizing run whose lease expired", async () => {
+				const run = makeRun(uid("finalizing"), { concurrencyKey: void 0 });
+				await store.createIfPermitted(run);
+				await store.claim(run.id, {
+					token: uid("dead"),
+					expiresAt: past()
+				});
+				await store.compareAndTransition(run.id, ["queued"], "running");
+				await store.compareAndTransition(run.id, ["running"], "finalizing");
+				const reclaimed = await store.claim(run.id, {
+					token: uid("recovered"),
+					expiresAt: future()
+				});
+				expect(reclaimed).not.toBeNull();
+				expect(reclaimed?.status).toBe("finalizing");
+			});
+			it("refuses a terminal run", async () => {
+				const run = makeRun(uid("terminal"), { concurrencyKey: void 0 });
+				await store.createIfPermitted(run);
+				await store.compareAndTransition(run.id, ["queued"], "completed");
+				expect(await store.claim(run.id, {
+					token: uid("t"),
+					expiresAt: future()
+				})).toBeNull();
+			});
+			it("refuses an unknown run", async () => {
+				expect(await store.claim(uid("ghost"), {
+					token: "t",
+					expiresAt: future()
+				})).toBeNull();
+			});
+		});
+		describe("compareAndTransition — guarded status change", () => {
+			it("applies the status and the patch when the current status matches", async () => {
+				const run = makeRun(uid("cas"), { concurrencyKey: void 0 });
+				await store.createIfPermitted(run);
+				const started = /* @__PURE__ */ new Date();
+				const updated = await store.compareAndTransition(run.id, ["queued"], "running", { startedAt: started });
+				expect(updated?.status).toBe("running");
+				expect(updated?.startedAt?.getTime()).toBe(started.getTime());
+				expect((await store.get(run.id))?.status).toBe("running");
+			});
+			it("refuses when the current status is not in `expected`", async () => {
+				const run = makeRun(uid("wrong-state"), { concurrencyKey: void 0 });
+				await store.createIfPermitted(run);
+				expect(await store.compareAndTransition(run.id, ["running"], "completed")).toBeNull();
+				expect((await store.get(run.id))?.status).toBe("queued");
+			});
+			it("refuses a stale ex-owner's write (lease-token mismatch)", async () => {
+				const run = makeRun(uid("stale"), { concurrencyKey: void 0 });
+				await store.createIfPermitted(run);
+				await store.claim(run.id, {
+					token: uid("dead"),
+					expiresAt: past()
+				});
+				await store.compareAndTransition(run.id, ["queued"], "running");
+				const live = uid("live");
+				await store.claim(run.id, {
+					token: live,
+					expiresAt: future()
+				});
+				expect(await store.compareAndTransition(run.id, ["running"], "completed", { completedAt: /* @__PURE__ */ new Date() }, "a-stale-token")).toBeNull();
+				expect((await store.get(run.id))?.status).toBe("running");
+				expect((await store.compareAndTransition(run.id, ["running"], "completed", void 0, live))?.status).toBe("completed");
+			});
+		});
+		describe("requestCancel — durable cancellation flag", () => {
+			it("sets the flag with audit metadata WITHOUT changing status", async () => {
+				const run = makeRun(uid("cancel"), { concurrencyKey: void 0 });
+				await store.createIfPermitted(run);
+				await store.compareAndTransition(run.id, ["queued"], "running");
+				const requestedAt = /* @__PURE__ */ new Date();
+				await store.requestCancel(run.id, {
+					actor: ACTOR,
+					reason: "operator changed their mind",
+					requestedAt
+				});
+				const stored = await store.get(run.id);
+				expect(stored?.cancelRequested).toBe(true);
+				expect(stored?.cancelReason).toBe("operator changed their mind");
+				expect(stored?.cancelRequestedBy?.ref).toBe(ACTOR.ref);
+				expect(stored?.status).toBe("running");
+			});
+			it("is idempotent — the FIRST request's audit metadata wins", async () => {
+				const run = makeRun(uid("cancel-twice"), { concurrencyKey: void 0 });
+				await store.createIfPermitted(run);
+				await store.requestCancel(run.id, {
+					actor: ACTOR,
+					reason: "first",
+					requestedAt: /* @__PURE__ */ new Date()
+				});
+				await store.requestCancel(run.id, {
+					actor: {
+						ref: "user:other",
+						kind: "user"
+					},
+					reason: "second",
+					requestedAt: /* @__PURE__ */ new Date()
+				});
+				const stored = await store.get(run.id);
+				expect(stored?.cancelReason).toBe("first");
+				expect(stored?.cancelRequestedBy?.ref).toBe(ACTOR.ref);
+			});
+		});
+		describe("saveProgress — heartbeat + bounded summary", () => {
+			it("updates progress and extends the lease for the current owner", async () => {
+				const run = makeRun(uid("progress"), { concurrencyKey: void 0 });
+				await store.createIfPermitted(run);
+				const token = uid("owner");
+				await store.claim(run.id, {
+					token,
+					expiresAt: future(1e3)
+				});
+				const renewed = future(12e4);
+				await store.saveProgress(run.id, {
+					processed: 7,
+					steps: 2
+				}, {
+					token,
+					expiresAt: renewed
+				});
+				const stored = await store.get(run.id);
+				expect(stored?.progress.processed).toBe(7);
+				expect(stored?.progress.steps).toBe(2);
+				expect(stored?.leaseExpiresAt?.getTime()).toBe(renewed.getTime());
+			});
+			it("ignores a write from a stale ex-owner", async () => {
+				const run = makeRun(uid("progress-stale"), { concurrencyKey: void 0 });
+				await store.createIfPermitted(run);
+				const live = uid("live");
+				await store.claim(run.id, {
+					token: live,
+					expiresAt: future()
+				});
+				await store.saveProgress(run.id, {
+					processed: 5,
+					steps: 1
+				}, {
+					token: live,
+					expiresAt: future()
+				});
+				await store.saveProgress(run.id, {
+					processed: 999,
+					steps: 999
+				}, {
+					token: "a-stale-token",
+					expiresAt: future()
+				});
+				expect((await store.get(run.id))?.progress.processed).toBe(5);
+			});
+		});
+		describe("reArmIfPermitted — retry under the creation admission policy", () => {
+			it("re-queues a failed run and clears cancel + lease + finalization state", async () => {
+				const run = makeRun(uid("rearm"), { concurrencyKey: void 0 });
+				await store.createIfPermitted(run);
+				const token = uid("owner");
+				await store.claim(run.id, {
+					token,
+					expiresAt: future()
+				});
+				await store.compareAndTransition(run.id, ["queued"], "running", void 0, token);
+				await store.requestCancel(run.id, {
+					actor: ACTOR,
+					reason: "stop",
+					requestedAt: /* @__PURE__ */ new Date()
+				});
+				await store.compareAndTransition(run.id, ["running"], "failed", void 0, token);
+				const requeued = await store.reArmIfPermitted(run.id, {
+					queuedAt: /* @__PURE__ */ new Date(),
+					cancelRequested: false
+				});
+				expect(requeued?.status).toBe("queued");
+				expect(requeued?.cancelRequested).toBe(false);
+				expect(requeued?.leaseToken).toBeUndefined();
+				expect(requeued?.finalization).toBeUndefined();
+			});
+			it("re-queues a cancelled run", async () => {
+				const run = makeRun(uid("rearm-cancelled"), { concurrencyKey: void 0 });
+				await store.createIfPermitted(run);
+				await store.compareAndTransition(run.id, ["queued"], "cancelled");
+				expect((await store.reArmIfPermitted(run.id, { queuedAt: /* @__PURE__ */ new Date() }))?.status).toBe("queued");
+			});
+			it("refuses a run that is not in a terminal status", async () => {
+				const run = makeRun(uid("rearm-live"), { concurrencyKey: void 0 });
+				await store.createIfPermitted(run);
+				expect(await store.reArmIfPermitted(run.id, { queuedAt: /* @__PURE__ */ new Date() })).toBeNull();
+			});
+			it("refuses when another non-terminal run holds the same concurrencyKey", async () => {
+				const key = uid("rearm-key");
+				const failed = makeRun(uid("rearm-blocked"), { concurrencyKey: key });
+				await store.createIfPermitted(failed);
+				await store.compareAndTransition(failed.id, ["queued"], "failed");
+				const active = makeRun(uid("rearm-active"), { concurrencyKey: key });
+				expect(await store.createIfPermitted(active)).toEqual({ created: true });
+				expect(await store.reArmIfPermitted(failed.id, { queuedAt: /* @__PURE__ */ new Date() })).toBeNull();
+			});
+		});
+	});
+}
+//#endregion
+export { runCleanupRunStoreContract };

package/dist/testing/index.d.mts

@@ -1,7 +1,8 @@
 import { V as ResourceDefinition } from "../index-DPRH0Cme.mjs";
 import { c as AnyRecord } from "../types-Dmw-6Qeo.mjs";
-import { d as ArcModuleInput } from "../index-KUoxjIq1.mjs";
-import { n as preloadResourcesAsync, r as CreateAppOptions, t as preloadResources } from "../preloadResources-0oe-JSSS.mjs";
+import { n as ArcModuleInput } from "../types-Cu6vVJmh.mjs";
+import "../index-CZY4EGga.mjs";
+import { n as preloadResourcesAsync, r as CreateAppOptions, t as preloadResources } from "../preloadResources-CM4uUaFv.mjs";
 import { StorageContractSetup, StorageContractSetupResult, runStorageContract } from "./storageContract.mjs";
 import { FastifyInstance, FastifyServerOptions } from "fastify";
 import { Mock } from "vitest";

package/dist/testing/index.mjs

@@ -1,5 +1,7 @@
 import { t as CRUD_OPERATIONS } from "../constants-DNre0wRg.mjs";
-import { i as createApp, n as preloadResourcesAsync, p as getModuleExports, t as preloadResources } from "../preloadResources-DfyngIN9.mjs";
+import { n as createApp } from "../createApp-Du5G54TM.mjs";
+import { n as getModuleExports } from "../module-_-M7C5ES.mjs";
+import { n as preloadResourcesAsync, t as preloadResources } from "../preloadResources-DSY5HGpS.mjs";
 import { runStorageContract } from "./storageContract.mjs";
 import Fastify from "fastify";
 import { afterAll, describe, expect, it, vi } from "vitest";
@@ -1116,7 +1118,7 @@ function pickDefaultAuth(authMode, callerAuth) {
 	};
 }
 async function createTestApp(options = {}) {
-	const { createApp } = await import("../preloadResources-DfyngIN9.mjs").then((n) => n.a);
+	const { createApp } = await import("../createApp-Du5G54TM.mjs").then((n) => n.r);
 	const { resources = [], db = "in-memory", connectMongoose = false, authMode = "jwt", defaultOrgId, plugins, auth: callerAuth, ...appOptions } = options;
 	let dbHandle;
 	let dbUri;

package/dist/testing/outboxStoreContract.d.mts

@@ -0,0 +1,13 @@
+import { OutboxStore } from "@classytic/primitives/outbox";
+//#region src/testing/outboxStoreContract.d.ts
+interface OutboxStoreContractSetupResult {
+  store: OutboxStore;
+  /** Called once after the suite. */
+  teardown?: () => Promise<void>;
+  /** Empty the store between tests. Strongly recommended for isolation. */
+  reset?: () => Promise<void>;
+}
+type OutboxStoreContractSetup = () => Promise<OutboxStoreContractSetupResult>;
+declare function runOutboxStoreContract(name: string, setup: OutboxStoreContractSetup): void;
+//#endregion
+export { OutboxStoreContractSetup, OutboxStoreContractSetupResult, runOutboxStoreContract };

package/dist/testing/outboxStoreContract.mjs

@@ -0,0 +1,247 @@
+import { OutboxOwnershipError } from "@classytic/primitives/outbox";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+//#region src/testing/outboxStoreContract.ts
+let seq = 0;
+/** A minimal well-formed event. Ids are unique per call. */
+function event(type = "test.event") {
+	seq += 1;
+	return {
+		type,
+		payload: { n: seq },
+		meta: {
+			id: `evt-${Date.now()}-${seq}`,
+			occurredAt: (/* @__PURE__ */ new Date()).toISOString()
+		}
+	};
+}
+const idOf = (e) => e.meta.id;
+function runOutboxStoreContract(name, setup) {
+	describe(`OutboxStore contract: ${name}`, () => {
+		let store;
+		let teardown;
+		let reset;
+		beforeAll(async () => {
+			const result = await setup();
+			store = result.store;
+			teardown = result.teardown;
+			reset = result.reset;
+		});
+		afterAll(async () => {
+			if (teardown) await teardown();
+		});
+		/** Save n events, oldest first. */
+		async function seed(n, type) {
+			if (reset) await reset();
+			const events = [];
+			for (let i = 0; i < n; i++) {
+				const e = event(type);
+				await store.save(e);
+				events.push(e);
+			}
+			return events;
+		}
+		describe("save — rejects malformed events (invariant 1)", () => {
+			it("persists a well-formed event", async () => {
+				const [e] = await seed(1);
+				expect((await store.getPending(10)).map(idOf)).toContain(idOf(e));
+			});
+			it("THROWS rather than persisting an event with no `type`", async () => {
+				if (reset) await reset();
+				await expect(store.save({
+					payload: {},
+					meta: { id: "no-type" }
+				})).rejects.toThrow();
+				expect((await store.getPending(10)).length).toBe(0);
+			});
+			it("THROWS rather than persisting an event with no `meta.id`", async () => {
+				if (reset) await reset();
+				await expect(store.save({
+					type: "x",
+					payload: {},
+					meta: {}
+				})).rejects.toThrow();
+				expect((await store.getPending(10)).length).toBe(0);
+			});
+		});
+		describe("getPending", () => {
+			it("returns events FIFO (oldest first)", async () => {
+				const saved = await seed(3);
+				expect((await store.getPending(10)).slice(0, 3).map(idOf)).toEqual(saved.map(idOf));
+			});
+			it("honours the limit", async () => {
+				await seed(3);
+				expect((await store.getPending(2)).length).toBeLessThanOrEqual(2);
+			});
+			it("returns only well-formed events (invariant 6)", async () => {
+				await seed(2);
+				for (const e of await store.getPending(10)) {
+					expect(typeof e.type).toBe("string");
+					expect(e.type.length).toBeGreaterThan(0);
+					expect(idOf(e)).toBeTruthy();
+				}
+			});
+		});
+		describe("claimPending — exclusive lease (invariant 2)", () => {
+			it("claims pending events", async ({ skip }) => {
+				if (!store.claimPending) return skip();
+				await seed(2);
+				expect((await store.claimPending({
+					consumerId: "c1",
+					limit: 10
+				})).length).toBe(2);
+			});
+			it("two concurrent claimers NEVER receive the same event", async ({ skip }) => {
+				if (!store.claimPending) return skip();
+				await seed(6);
+				const [a, b] = await Promise.all([store.claimPending({
+					consumerId: "c1",
+					limit: 6
+				}), store.claimPending({
+					consumerId: "c2",
+					limit: 6
+				})]);
+				const idsA = a.map(idOf);
+				const idsB = b.map(idOf);
+				expect(idsA.filter((id) => idsB.includes(id))).toEqual([]);
+				expect(idsA.length + idsB.length).toBeLessThanOrEqual(6);
+			});
+			it("does not re-claim an event whose lease is still live", async ({ skip }) => {
+				if (!store.claimPending) return skip();
+				await seed(2);
+				await store.claimPending({
+					consumerId: "c1",
+					limit: 10,
+					leaseMs: 6e4
+				});
+				expect(await store.claimPending({
+					consumerId: "c2",
+					limit: 10
+				})).toEqual([]);
+			});
+			it("RECLAIMS an event whose lease expired (crashed worker)", async ({ skip }) => {
+				if (!store.claimPending) return skip();
+				await seed(1);
+				await store.claimPending({
+					consumerId: "dead",
+					limit: 10,
+					leaseMs: 0
+				});
+				expect((await store.claimPending({
+					consumerId: "c2",
+					limit: 10
+				})).length).toBe(1);
+			});
+			it("claims FIFO", async ({ skip }) => {
+				if (!store.claimPending) return skip();
+				const saved = await seed(3);
+				expect((await store.claimPending({
+					consumerId: "c1",
+					limit: 2
+				})).map(idOf)).toEqual(saved.slice(0, 2).map(idOf));
+			});
+		});
+		describe("acknowledge", () => {
+			it("removes the event from pending", async () => {
+				const [e] = await seed(1);
+				await store.acknowledge(idOf(e));
+				expect((await store.getPending(10)).map(idOf)).not.toContain(idOf(e));
+			});
+			it("is a NO-OP for an unknown id — never an ownership error (invariant 4)", async () => {
+				if (reset) await reset();
+				await expect(store.acknowledge("does-not-exist")).resolves.not.toThrow();
+			});
+			it("THROWS OutboxOwnershipError when consumerId is not the lease owner (invariant 3)", async ({ skip }) => {
+				if (!store.claimPending) return skip();
+				await seed(1);
+				const [claimed] = await store.claimPending({
+					consumerId: "owner",
+					limit: 1,
+					leaseMs: 6e4
+				});
+				if (!claimed) return skip();
+				await expect(store.acknowledge(idOf(claimed), { consumerId: "impostor" })).rejects.toBeInstanceOf(OutboxOwnershipError);
+			});
+			it("succeeds for the rightful lease owner", async ({ skip }) => {
+				if (!store.claimPending) return skip();
+				await seed(1);
+				const [claimed] = await store.claimPending({
+					consumerId: "owner",
+					limit: 1,
+					leaseMs: 6e4
+				});
+				if (!claimed) return skip();
+				await expect(store.acknowledge(idOf(claimed), { consumerId: "owner" })).resolves.not.toThrow();
+			});
+		});
+		describe("fail — deterministic lease + visibility (invariant 5)", () => {
+			it("makes the event re-claimable again (lease cleared)", async ({ skip }) => {
+				if (!store.fail || !store.claimPending) return skip();
+				await seed(1);
+				const [claimed] = await store.claimPending({
+					consumerId: "c1",
+					limit: 1,
+					leaseMs: 6e4
+				});
+				if (!claimed) return skip();
+				await store.fail(idOf(claimed), { message: "boom" });
+				expect((await store.claimPending({
+					consumerId: "c2",
+					limit: 10
+				})).map(idOf)).toContain(idOf(claimed));
+			});
+			it("THROWS OutboxOwnershipError on a consumerId mismatch (invariant 3)", async ({ skip }) => {
+				if (!store.fail || !store.claimPending) return skip();
+				await seed(1);
+				const [claimed] = await store.claimPending({
+					consumerId: "owner",
+					limit: 1,
+					leaseMs: 6e4
+				});
+				if (!claimed) return skip();
+				await expect(store.fail(idOf(claimed), { message: "boom" }, { consumerId: "impostor" })).rejects.toBeInstanceOf(OutboxOwnershipError);
+			});
+			it("honours `retryAt` — the event is NOT immediately re-claimable", async ({ skip }) => {
+				if (!store.fail || !store.claimPending) return skip();
+				await seed(1);
+				const [claimed] = await store.claimPending({
+					consumerId: "c1",
+					limit: 1,
+					leaseMs: 6e4
+				});
+				if (!claimed) return skip();
+				await store.fail(idOf(claimed), { message: "boom" }, { retryAt: new Date(Date.now() + 6e4) });
+				expect((await store.claimPending({
+					consumerId: "c2",
+					limit: 10
+				})).map(idOf)).not.toContain(idOf(claimed));
+			});
+			it("`deadLetter: true` removes it from the pending stream", async ({ skip }) => {
+				if (!store.fail) return skip();
+				const [e] = await seed(1);
+				await store.fail(idOf(e), { message: "fatal" }, { deadLetter: true });
+				expect((await store.getPending(10)).map(idOf)).not.toContain(idOf(e));
+			});
+		});
+		describe("getDeadLettered", () => {
+			it("returns dead-lettered events with their failure metadata", async ({ skip }) => {
+				if (!store.fail || !store.getDeadLettered) return skip();
+				const [e] = await seed(1);
+				await store.fail(idOf(e), { message: "fatal" }, { deadLetter: true });
+				const row = (await store.getDeadLettered(10)).find((d) => idOf(d.event) === idOf(e));
+				expect(row).toBeDefined();
+				expect(row?.error).toBeDefined();
+				expect(typeof row?.attempts).toBe("number");
+			});
+		});
+		describe("purge", () => {
+			it("NEVER removes pending events — delivered-only scope", async ({ skip }) => {
+				if (!store.purge) return skip();
+				await seed(2);
+				await store.purge(0);
+				expect((await store.getPending(10)).length).toBe(2);
+			});
+		});
+	});
+}
+//#endregion
+export { runOutboxStoreContract };