@classytic/arc 2.25.0 → 2.30.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 { V as ResourceDefinition } from "../index-Q5gzEIWY.mjs";
+import { l as AnyRecord, r as PermissionCheck } from "../types-ChvvVNP8.mjs";
+import { n as ArcModuleInput } from "../types-D_n8L6VY.mjs";
+import "../index-CCzVR-N3.mjs";
+import { n as preloadResourcesAsync, r as CreateAppOptions, t as preloadResources } from "../preloadResources-DCfa2egz.mjs";
 import { StorageContractSetup, StorageContractSetupResult, runStorageContract } from "./storageContract.mjs";
 import { FastifyInstance, FastifyServerOptions } from "fastify";
 import { Mock } from "vitest";
@@ -71,6 +72,34 @@ interface ArcAssertion {
 }
 declare function expectArc(response: ArcResponseLike): ArcAssertion;
 //#endregion
+//#region src/testing/authorizationConformance.d.ts
+/** One surface's observed enforcement: the HTTP status + the filter arc passed the repo. */
+interface SurfaceObservation {
+  /** HTTP status the surface returned (200 = allowed, 401/403 = denied). */
+  status: number;
+  /** The filter arc handed the repository for this surface (undefined if never reached). */
+  filter: AnyRecord | undefined;
+}
+/** Result of {@link runAuthorizationConformance} — one observation per surface. */
+interface AuthorizationConformance {
+  /** `GET /confs` — the CRUD list surface. */
+  list: SurfaceObservation;
+  /** `GET /confs/aggregations/tally` — the aggregation surface. */
+  aggregation: SurfaceObservation;
+  /** Close the throwaway app. Always call (e.g. in `finally`). */
+  close(): Promise<void>;
+}
+/**
+ * Boot a one-resource app gated by `permission` on both list + an aggregation,
+ * hit both surfaces anonymously, and report what arc enforced on each.
+ */
+declare function runAuthorizationConformance(opts: {
+  /** The permission under test — applied to `list` and the aggregation alike. */
+  permission: PermissionCheck;
+  /** Rows the mock repo returns for list (aggregation returns a count). */
+  rows?: AnyRecord[];
+}): Promise<AuthorizationConformance>;
+//#endregion
 //#region src/testing/authSession.d.ts
 /**
  * A concrete auth session — headers ready to drop into `app.inject`.
@@ -621,4 +650,4 @@ declare function createTestApp(options?: CreateTestAppOptions): Promise<TestAppC
  */
 declare function createMinimalTestApp(options?: FastifyServerOptions): FastifyInstance;
 //#endregion
-export { type ArcAssertion, type ArcResponseLike, type AuthMode, type AuthResponse, type BetterAuthTestHelpers, type BetterAuthTestHelpersOptions, type BetterAuthTestUser, type BootModuleAppOptions, type BootModulesInput, type CreateOrgInput, type CreateTestAppOptions, type DbMode, type FixtureDestroyer, type FixtureFactory, type FixtureRegistration, HttpTestHarness, type HttpTestHarnessOptions, type MockRepository, type ModuleTestApp, type OrgResponse, type RoleConfig, type SetupBetterAuthTestAppInput, type SetupBetterAuthTestAppResult, type SignInInput, type SignUpInput, type StorageContractSetup, type StorageContractSetupResult, type TestAppContext, type TestAuthProvider, type TestAuthSession, type TestDatabase, type TestDatabaseFactory, type TestFixtures, type TestkitContext, bootModuleApp, createBetterAuthProvider, createBetterAuthTestHelpers, createCustomAuthProvider, createDataFactory, createHttpTestHarness, createJwtAuthProvider, createMinimalTestApp, createMockController, createMockReply, createMockRepository, createMockRequest, createMockUser, createSpy, createTestApp, createTestFixtures, createTestTimer, expectArc, mongoMemoryDatabase, preloadResources, preloadResourcesAsync, runStorageContract, safeParseBody, setupBetterAuthTestApp, waitFor };
+export { type ArcAssertion, type ArcResponseLike, type AuthMode, type AuthResponse, type AuthorizationConformance, type BetterAuthTestHelpers, type BetterAuthTestHelpersOptions, type BetterAuthTestUser, type BootModuleAppOptions, type BootModulesInput, type CreateOrgInput, type CreateTestAppOptions, type DbMode, type FixtureDestroyer, type FixtureFactory, type FixtureRegistration, HttpTestHarness, type HttpTestHarnessOptions, type MockRepository, type ModuleTestApp, type OrgResponse, type RoleConfig, type SetupBetterAuthTestAppInput, type SetupBetterAuthTestAppResult, type SignInInput, type SignUpInput, type StorageContractSetup, type StorageContractSetupResult, type SurfaceObservation, type TestAppContext, type TestAuthProvider, type TestAuthSession, type TestDatabase, type TestDatabaseFactory, type TestFixtures, type TestkitContext, bootModuleApp, createBetterAuthProvider, createBetterAuthTestHelpers, createCustomAuthProvider, createDataFactory, createHttpTestHarness, createJwtAuthProvider, createMinimalTestApp, createMockController, createMockReply, createMockRepository, createMockRequest, createMockUser, createSpy, createTestApp, createTestFixtures, createTestTimer, expectArc, mongoMemoryDatabase, preloadResources, preloadResourcesAsync, runAuthorizationConformance, runStorageContract, safeParseBody, setupBetterAuthTestApp, waitFor };