@classytic/repo-core 0.28.0 → 0.30.0

package/dist/testing/idempotency-conformance.mjs

@@ -0,0 +1,315 @@
+import { completeClaim, decideClaim, identityKey, runIdempotent } from "../idempotency/index.mjs";
+import { describe, it } from "vitest";
+//#region src/testing/idempotency-conformance.ts
+/**
+* `runIdempotencyStoreConformance` — the contract every `IdempotencyClaimStore` passes.
+* Mirrors `runLockAdapterConformance`: a kit runs it against its real backend, and passing it
+* is what "implements the store" means.
+*
+*     describe('mongokit/idempotency conformance', () => {
+*       runIdempotencyStoreConformance({ createStore: () => createIdempotencyStore(model) });
+*     });
+*
+* The concurrency cases are the ones that matter — a store built from read-then-write passes
+* everything else and double-executes in production.
+*/
+const T0 = /* @__PURE__ */ new Date("2026-01-01T00:00:00.000Z");
+const LEASE_MS = 3e4;
+let seq = 0;
+const freshIdentity = (over = {}) => ({
+	operation: "conformance.op",
+	key: `key-${Date.now().toString(36)}-${++seq}`,
+	scope: { organizationId: "org-1" },
+	...over
+});
+function mint(identity, leaseToken, now = T0) {
+	const decision = decideClaim(null, {
+		identity,
+		requestFingerprint: "fp-1",
+		now,
+		leaseToken,
+		leaseMs: LEASE_MS
+	});
+	if (decision.outcome !== "claimed") throw new Error("unreachable");
+	return decision.claim;
+}
+function check(condition, message) {
+	if (!condition) throw new Error(`[IdempotencyClaimStore contract] ${message}`);
+}
+const sameInstant = (a, b) => a instanceof Date && a.getTime() === b.getTime();
+/** The contract's cases, runner-agnostic — each `run` throws on failure. */
+function idempotencyStoreCases(harness) {
+	return [
+		["get of an unknown identity is null", async (store) => {
+			check(await store.get(freshIdentity()) === null, "get must return null for an identity never inserted");
+		}],
+		["insert round-trips every field, Dates as Dates", async (store) => {
+			const identity = freshIdentity();
+			const claim = mint(identity, "lease-a");
+			check(await store.insert(claim), "first insert must win");
+			const got = await store.get(identity);
+			check(got !== null, "inserted claim must be readable");
+			check(identityKey(got.identity) === identityKey(identity), "identity must round-trip");
+			check(got.requestFingerprint === "fp-1", "requestFingerprint must round-trip");
+			check(got.state === "in_flight", "state must round-trip");
+			check(got.leaseToken === "lease-a", "leaseToken must round-trip");
+			check(got.attempts === 1, "attempts must round-trip");
+			check(sameInstant(got.leaseExpiresAt, claim.leaseExpiresAt), "leaseExpiresAt must come back as the same Date");
+			check(sameInstant(got.createdAt, claim.createdAt), "createdAt must come back as the same Date");
+		}],
+		["a second insert of one identity loses and changes nothing", async (store) => {
+			const identity = freshIdentity();
+			check(await store.insert(mint(identity, "lease-a")), "first insert must win");
+			check(!await store.insert(mint(identity, "lease-b")), "second insert must return false");
+			check((await store.get(identity))?.leaseToken === "lease-a", "the loser must not overwrite the winner");
+		}],
+		["CONCURRENT inserts of one identity: exactly one wins", async (store) => {
+			const identity = freshIdentity();
+			const results = await Promise.all(Array.from({ length: 12 }, (_, i) => store.insert(mint(identity, `lease-${i}`))));
+			check(results.filter(Boolean).length === 1, `exactly one insert must win, got ${results.filter(Boolean).length}`);
+		}],
+		["operation and scope are part of the identity; scope key order is not", async (store) => {
+			const base = freshIdentity({ scope: {
+				organizationId: "org-1",
+				registerId: "r1"
+			} });
+			check(await store.insert(mint(base, "lease-a")), "base insert must win");
+			check(await store.insert(mint({
+				...base,
+				operation: "other.op"
+			}, "lease-b")), "another operation with the same key is a different claim");
+			check(await store.insert(mint({
+				...base,
+				scope: {
+					organizationId: "org-2",
+					registerId: "r1"
+				}
+			}, "lease-c")), "another scope is a different claim");
+			const reordered = {
+				...base,
+				scope: {
+					registerId: "r1",
+					organizationId: "org-1"
+				}
+			};
+			check(!await store.insert(mint(reordered, "lease-d")), "scope key order must not make a new identity");
+		}],
+		["swap requires the current lease token", async (store) => {
+			const identity = freshIdentity();
+			const claim = mint(identity, "lease-a");
+			await store.insert(claim);
+			const renewed = {
+				...claim,
+				leaseExpiresAt: new Date(T0.getTime() + 2 * LEASE_MS)
+			};
+			check(!await store.swap(identity, "lease-wrong", renewed), "swap with a foreign token must lose");
+			check(await store.swap(identity, "lease-a", renewed), "swap with the owning token must win");
+			check(sameInstant((await store.get(identity))?.leaseExpiresAt, renewed.leaseExpiresAt), "swap must store `next`");
+		}],
+		["CONCURRENT swaps from one token: exactly one wins", async (store) => {
+			const identity = freshIdentity();
+			await store.insert(mint(identity, "lease-old"));
+			const takeovers = Array.from({ length: 12 }, (_, i) => ({
+				...mint(identity, `lease-new-${i}`),
+				attempts: 2
+			}));
+			const results = await Promise.all(takeovers.map((next) => store.swap(identity, "lease-old", next)));
+			check(results.filter(Boolean).length === 1, `exactly one takeover must win, got ${results.filter(Boolean).length}`);
+		}],
+		["a terminal claim cannot be swapped or released, and replays its result", async (store) => {
+			const identity = freshIdentity();
+			const claim = mint(identity, "lease-a");
+			await store.insert(claim);
+			const value = {
+				orderNumber: "ORD-1",
+				lines: [{
+					sku: "a",
+					qty: 2
+				}]
+			};
+			const done = completeClaim(claim, {
+				leaseToken: "lease-a",
+				now: T0,
+				result: {
+					status: "succeeded",
+					value
+				}
+			});
+			check(await store.swap(identity, "lease-a", done), "completion must win");
+			check(!await store.swap(identity, "lease-a", done), "a terminal claim must refuse swap");
+			check(!await store.release(identity, "lease-a"), "a terminal claim must refuse release");
+			const got = await store.get(identity);
+			check(got?.state === "succeeded", "terminal state must round-trip");
+			check(JSON.stringify(got.result) === JSON.stringify({
+				status: "succeeded",
+				value
+			}), "the stored value must replay exactly");
+		}],
+		["a failed result round-trips its code, message and status", async (store) => {
+			const identity = freshIdentity();
+			const claim = mint(identity, "lease-a");
+			await store.insert(claim);
+			const error = {
+				code: "OUT_OF_STOCK",
+				message: "no units",
+				status: 409
+			};
+			await store.swap(identity, "lease-a", completeClaim(claim, {
+				leaseToken: "lease-a",
+				now: T0,
+				result: {
+					status: "failed",
+					error
+				}
+			}));
+			const got = await store.get(identity);
+			check(got?.state === "failed", "failed state must round-trip");
+			check(JSON.stringify(got.result) === JSON.stringify({
+				status: "failed",
+				error
+			}), "the stored failure must replay exactly");
+		}],
+		["context, progress and lastError round-trip", async (store) => {
+			const identity = freshIdentity();
+			const claim = {
+				...mint(identity, "lease-a"),
+				context: {
+					orderNumber: "ORD-1",
+					amount: 500
+				}
+			};
+			await store.insert(claim);
+			const next = {
+				...claim,
+				progress: { gatewayRefundId: "g1" },
+				lastError: "timeout"
+			};
+			check(await store.swap(identity, "lease-a", next), "swap must win");
+			const got = await store.get(identity);
+			check(JSON.stringify(got?.context) === JSON.stringify({
+				orderNumber: "ORD-1",
+				amount: 500
+			}), "context must round-trip");
+			check(got?.progress?.["gatewayRefundId"] === "g1", "progress must round-trip");
+			check(got?.lastError === "timeout", "lastError must round-trip");
+		}],
+		["listLapsed returns only lapsed in-flight claims of the operation, oldest first", async (store) => {
+			const operation = `conformance.sweep.${++seq}`;
+			const at = (ms) => new Date(T0.getTime() + ms);
+			const lapsedOld = {
+				...mint(freshIdentity({ operation }), "l1"),
+				leaseExpiresAt: at(-2e3)
+			};
+			const lapsedNew = {
+				...mint(freshIdentity({ operation }), "l2"),
+				leaseExpiresAt: at(-1e3)
+			};
+			const live = {
+				...mint(freshIdentity({ operation }), "l3"),
+				leaseExpiresAt: at(6e4)
+			};
+			const otherOp = {
+				...mint(freshIdentity({ operation: `${operation}.other` }), "l4"),
+				leaseExpiresAt: at(-5e3)
+			};
+			const doneClaim = {
+				...mint(freshIdentity({ operation }), "l5"),
+				leaseExpiresAt: at(-9e3)
+			};
+			for (const c of [
+				lapsedNew,
+				live,
+				otherOp,
+				lapsedOld,
+				doneClaim
+			]) await store.insert(c);
+			await store.swap(doneClaim.identity, "l5", completeClaim(doneClaim, {
+				leaseToken: "l5",
+				now: T0,
+				result: {
+					status: "succeeded",
+					value: 1
+				}
+			}));
+			const found = await store.listLapsed(operation, T0, 10);
+			check(JSON.stringify(found.map((c) => c.leaseToken)) === JSON.stringify(["l1", "l2"]), `expected [l1, l2] (lapsed, in flight, this operation, oldest first), got ${JSON.stringify(found.map((c) => c.leaseToken))}`);
+			check((await store.listLapsed(operation, T0, 1)).length === 1, "limit must be honoured");
+		}],
+		["release frees only the owner's in-flight claim", async (store) => {
+			const identity = freshIdentity();
+			await store.insert(mint(identity, "lease-a"));
+			check(!await store.release(identity, "lease-wrong"), "release with a foreign token must lose");
+			check(await store.release(identity, "lease-a"), "release with the owning token must win");
+			check(await store.get(identity) === null, "a released identity reads as never claimed");
+			check(await store.insert(mint(identity, "lease-b")), "a released identity can be claimed again");
+		}],
+		["a recovery point survives a crash and is handed to the takeover", async (store) => {
+			const identity = freshIdentity();
+			const crash = /* @__PURE__ */ new Error("process died after the order was written");
+			await runIdempotent({
+				store,
+				identity,
+				requestFingerprint: "fp-1",
+				now: () => T0,
+				leaseMs: LEASE_MS,
+				execute: async ({ checkpoint }) => {
+					await checkpoint({ orderNumber: "ORD-9" });
+					throw crash;
+				}
+			}).then(() => check(false, "the crashed attempt must not report success"), (error) => check(error === crash, "the crash must surface unchanged"));
+			const stored = await store.get(identity);
+			check(stored?.state === "in_flight", "a failure after a recovery point must KEEP the claim, not release it");
+			check(stored.progress?.["orderNumber"] === "ORD-9", "the recovery point must be stored");
+			let resumedFrom;
+			const later = new Date(T0.getTime() + LEASE_MS);
+			const second = await runIdempotent({
+				store,
+				identity,
+				requestFingerprint: "fp-1",
+				now: () => later,
+				execute: async ({ progress, attempt }) => {
+					resumedFrom = {
+						progress,
+						attempt
+					};
+					return { orderNumber: progress?.["orderNumber"] };
+				}
+			});
+			check(JSON.stringify(resumedFrom) === JSON.stringify({
+				progress: { orderNumber: "ORD-9" },
+				attempt: 2
+			}), `the takeover must resume from the recovery point, got ${JSON.stringify(resumedFrom)}`);
+			check(second.outcome === "executed", "the takeover completes the command");
+		}],
+		["runIdempotent over this store executes ONCE under concurrent retries", async (store) => {
+			const identity = freshIdentity();
+			let executions = 0;
+			const attempt = () => runIdempotent({
+				store,
+				identity,
+				requestFingerprint: "fp-1",
+				execute: async () => {
+					executions++;
+					await new Promise((resolve) => setTimeout(resolve, 20));
+					return { orderNumber: "ORD-1" };
+				}
+			});
+			const runs = await Promise.all(Array.from({ length: 8 }, attempt));
+			const again = await attempt();
+			check(executions === 1, `execute must run exactly once, ran ${executions}`);
+			check(runs.filter((r) => r.outcome === "executed").length === 1, "exactly one run reports executed");
+			check(again.outcome === "replayed" && again.value.orderNumber === "ORD-1", "a later retry replays the stored value");
+		}]
+	].map(([name, body]) => ({
+		name,
+		run: async () => body(await harness.createStore())
+	}));
+}
+/** Register every contract case as a vitest test against `harness.createStore()`. */
+function runIdempotencyStoreConformance(harness) {
+	describe("IdempotencyClaimStore contract", () => {
+		for (const c of idempotencyStoreCases(harness)) it(c.name, c.run);
+	});
+}
+//#endregion
+export { idempotencyStoreCases, runIdempotencyStoreConformance };

package/dist/testing/index.d.mts

@@ -1,7 +1,11 @@
 import { AggregateOpsSupport } from "../repository/capabilities.mjs";
+import { ChangeLogConformanceHarness, changeLogStoreCases, runChangeLogStoreConformance } from "./change-log-conformance.mjs";
+import { CommandStreamConformanceHarness, commandStreamStoreCases, runCommandStreamStoreConformance } from "./command-stream-conformance.mjs";
 import { ConformanceContext, ConformanceDoc, ConformanceFeatures, ConformanceHarness } from "./types.mjs";
 import { runStandardRepoConformance } from "./conformance.mjs";
+import { IdempotencyConformanceHarness, idempotencyStoreCases, runIdempotencyStoreConformance } from "./idempotency-conformance.mjs";
 import { LockConformanceHarness, runLockAdapterConformance } from "./lock-conformance.mjs";
 import { PurgeConformanceContext, PurgeConformanceHarness, runPurgeConformance } from "./purge-conformance.mjs";
+import { QUERY_GRAMMAR_DOCS, QUERY_GRAMMAR_FILTER_CASES, QUERY_GRAMMAR_PAGING_CASES, QUERY_GRAMMAR_REFUSED, QueryGrammarCaseOptions, QueryGrammarConformanceOptions, QueryGrammarHarness, QueryGrammarParsed, runQueryGrammarConformance } from "./query-grammar-conformance.mjs";
 import { UsageConformanceHarness, runUsageStoreContract } from "./usage-conformance.mjs";
-export { type AggregateOpsSupport, type ConformanceContext, type ConformanceDoc, type ConformanceFeatures, type ConformanceHarness, type LockConformanceHarness, type PurgeConformanceContext, type PurgeConformanceHarness, type UsageConformanceHarness, runLockAdapterConformance, runPurgeConformance, runStandardRepoConformance, runUsageStoreContract };
+export { type AggregateOpsSupport, type ChangeLogConformanceHarness, type CommandStreamConformanceHarness, type ConformanceContext, type ConformanceDoc, type ConformanceFeatures, type ConformanceHarness, type IdempotencyConformanceHarness, type LockConformanceHarness, type PurgeConformanceContext, type PurgeConformanceHarness, QUERY_GRAMMAR_DOCS, QUERY_GRAMMAR_FILTER_CASES, QUERY_GRAMMAR_PAGING_CASES, QUERY_GRAMMAR_REFUSED, type QueryGrammarCaseOptions, type QueryGrammarConformanceOptions, type QueryGrammarHarness, type QueryGrammarParsed, type UsageConformanceHarness, changeLogStoreCases, commandStreamStoreCases, idempotencyStoreCases, runChangeLogStoreConformance, runCommandStreamStoreConformance, runIdempotencyStoreConformance, runLockAdapterConformance, runPurgeConformance, runQueryGrammarConformance, runStandardRepoConformance, runUsageStoreContract };

package/dist/testing/index.mjs

@@ -1,5 +1,9 @@
+import { changeLogStoreCases, runChangeLogStoreConformance } from "./change-log-conformance.mjs";
+import { commandStreamStoreCases, runCommandStreamStoreConformance } from "./command-stream-conformance.mjs";
 import { runStandardRepoConformance } from "./conformance.mjs";
+import { idempotencyStoreCases, runIdempotencyStoreConformance } from "./idempotency-conformance.mjs";
 import { runLockAdapterConformance } from "./lock-conformance.mjs";
 import { runPurgeConformance } from "./purge-conformance.mjs";
+import { QUERY_GRAMMAR_DOCS, QUERY_GRAMMAR_FILTER_CASES, QUERY_GRAMMAR_PAGING_CASES, QUERY_GRAMMAR_REFUSED, runQueryGrammarConformance } from "./query-grammar-conformance.mjs";
 import { runUsageStoreContract } from "./usage-conformance.mjs";
-export { runLockAdapterConformance, runPurgeConformance, runStandardRepoConformance, runUsageStoreContract };
+export { QUERY_GRAMMAR_DOCS, QUERY_GRAMMAR_FILTER_CASES, QUERY_GRAMMAR_PAGING_CASES, QUERY_GRAMMAR_REFUSED, changeLogStoreCases, commandStreamStoreCases, idempotencyStoreCases, runChangeLogStoreConformance, runCommandStreamStoreConformance, runIdempotencyStoreConformance, runLockAdapterConformance, runPurgeConformance, runQueryGrammarConformance, runStandardRepoConformance, runUsageStoreContract };

package/dist/testing/query-grammar-conformance.d.mts

@@ -0,0 +1,60 @@
+//#region src/testing/query-grammar-conformance.d.ts
+/**
+ * `runQueryGrammarConformance` — every list-query parser reads a URL the same way.
+ *
+ * Cases are SEMANTIC: each parser's output is evaluated against one fixture set and must select
+ * the same rows (or refuse the same input with a 400). A parser passes by agreeing on RESULTS,
+ * so its emitted shape (Filter IR, Mongo record, a custom dialect) is free.
+ */
+interface QueryGrammarCaseOptions {
+  readonly maxLimit: number;
+  readonly defaultLimit: number;
+  readonly allowedFilterFields?: readonly string[];
+  readonly allowedSortFields?: readonly string[];
+}
+/** What a harness returns for one parsed query. */
+interface QueryGrammarParsed {
+  /** True when the parsed filter selects `doc`. */
+  matches(doc: Readonly<Record<string, unknown>>): boolean;
+  readonly limit: number;
+  readonly page?: number | undefined;
+  readonly after?: string | undefined;
+  readonly sort?: Readonly<Record<string, 1 | -1>> | undefined;
+}
+interface QueryGrammarHarness {
+  /** Parse a raw query string exactly as the kit receives one in production. Throw to refuse. */
+  parse(query: string, options: QueryGrammarCaseOptions): QueryGrammarParsed;
+}
+/** The fixture every case runs against: nulls, missing fields, codes, dates, and text metacharacters. */
+declare const QUERY_GRAMMAR_DOCS: readonly Readonly<Record<string, unknown>>[];
+interface FilterCase {
+  readonly query: string;
+  readonly ids: readonly string[];
+  readonly options?: Partial<QueryGrammarCaseOptions>;
+}
+declare const QUERY_GRAMMAR_FILTER_CASES: readonly FilterCase[];
+declare const QUERY_GRAMMAR_REFUSED: readonly {
+  query: string;
+  options?: Partial<QueryGrammarCaseOptions>;
+}[];
+declare const QUERY_GRAMMAR_PAGING_CASES: readonly {
+  query: string;
+  expect: {
+    limit: number;
+    page?: number;
+    after?: string;
+    sort?: Record<string, 1 | -1>;
+  };
+}[];
+/** Register the suite for one parser. */
+interface QueryGrammarConformanceOptions {
+  /**
+   * Operators this backend cannot execute (e.g. `regex` on SQLite without REGEXP). A case using
+   * one must be REFUSED with a 400 — the kit's parser declares them out, it never fails at query
+   * time.
+   */
+  readonly unsupportedOperators?: readonly string[];
+}
+declare function runQueryGrammarConformance(name: string, harness: QueryGrammarHarness, conformance?: QueryGrammarConformanceOptions): void;
+//#endregion
+export { QUERY_GRAMMAR_DOCS, QUERY_GRAMMAR_FILTER_CASES, QUERY_GRAMMAR_PAGING_CASES, QUERY_GRAMMAR_REFUSED, QueryGrammarCaseOptions, QueryGrammarConformanceOptions, QueryGrammarHarness, QueryGrammarParsed, runQueryGrammarConformance };