@classytic/primitives 0.18.0 → 0.20.0

package/dist/event-infra.d.mts

@@ -1,5 +1,4 @@
 import { DomainEvent, EventHandler, EventTransport, PublishManyResult } from "./events.mjs";
-import { OutboxAcknowledgeOptions, OutboxStore, OutboxWriteOptions } from "./outbox.mjs";
 
 //#region src/events/event-infra.d.ts
 /** Minimal error-only logger — assignable from `console`, pino, fastify.log. */
@@ -86,37 +85,5 @@ declare class InProcessEventBus implements EventTransport {
 }
 /** Factory form of {@link InProcessEventBus} for hosts that prefer functions. */
 declare function createInProcessBus(options?: InProcessEventBusOptions): InProcessEventBus;
-/**
- * In-memory {@link OutboxStore} for tests and local dev. Not for production —
- * hosts wire arc's `MongoOutboxStore`, a mongokit repo via
- * `repositoryAsOutboxStore`, or any durable implementation.
- *
- * Implements the required trio (`save` / `getPending` / `acknowledge`) plus
- * optional `purge`. Lease-based methods (`claimPending` / `fail` /
- * `getDeadLettered`) are intentionally omitted — single-process tests don't
- * need them, and kernels only call `save()` themselves. `all()` / `clear()`
- * are test-inspection helpers (not part of the contract).
- */
-declare class MemoryOutboxStore implements OutboxStore {
-  /**
-   * Deliberately NOT transactional — and saying so is the point.
-   *
-   * This store pushes onto an in-process array, which no database transaction
-   * can roll back. If a caller's Mongo write aborts after `save`, the event
-   * SURVIVES here and describes something that never happened. Declaring
-   * `false` lets a caller that needs real atomicity (`@classytic/access`) refuse
-   * at boot instead of silently inheriting a ghost-event path.
-   */
-  readonly transactionalSave = false;
-  private events;
-  save(event: DomainEvent, _options?: OutboxWriteOptions): Promise<void>;
-  getPending(limit: number): Promise<DomainEvent[]>;
-  acknowledge(eventId: string, _options?: OutboxAcknowledgeOptions): Promise<void>;
-  purge(olderThanMs: number): Promise<number>;
-  /** Every saved event (acknowledged or not) — test inspection helper. */
-  all(): ReadonlyArray<DomainEvent>;
-  /** Reset the store — test helper. */
-  clear(): void;
-}
 //#endregion
-export { ErrorLogger, InProcessEventBus, InProcessEventBusOptions, MemoryOutboxStore, createInProcessBus };
+export { ErrorLogger, InProcessEventBus, InProcessEventBusOptions, createInProcessBus };

package/dist/event-infra.mjs

@@ -78,52 +78,22 @@ function createInProcessBus(options) {
 	return new InProcessEventBus(options);
 }
 /**
-* In-memory {@link OutboxStore} for tests and local dev. Not for production —
-* hosts wire arc's `MongoOutboxStore`, a mongokit repo via
-* `repositoryAsOutboxStore`, or any durable implementation.
+* `MemoryOutboxStore` does NOT live here. It is exported from exactly one
+* place: `@classytic/primitives/memory-outbox`.
 *
-* Implements the required trio (`save` / `getPending` / `acknowledge`) plus
-* optional `purge`. Lease-based methods (`claimPending` / `fail` /
-* `getDeadLettered`) are intentionally omitted — single-process tests don't
-* need them, and kernels only call `save()` themselves. `all()` / `clear()`
-* are test-inspection helpers (not part of the contract).
+* This module used to also export it — first as a second, MINIMAL
+* implementation (save / getPending / acknowledge / purge, no leases, no
+* retry, no dead-lettering, no dedupe, no validation), then briefly as a
+* back-compat re-export. Both are gone.
+*
+* The re-export was tempting: seven kernels imported it from here, and one
+* line would have spared seven rebuilds. It was still the wrong call. Two live
+* import paths for one class means new code picks either, the migration stays
+* permanently half-done, and the next person has to learn which path is
+* "real". The cost of the move is seven rebuilds; paying it once is cheaper
+* than carrying a shim forever.
+*
+* This subpath is the in-process BUS. The outbox is its own subpath.
 */
-var MemoryOutboxStore = class {
-	/**
-	* Deliberately NOT transactional — and saying so is the point.
-	*
-	* This store pushes onto an in-process array, which no database transaction
-	* can roll back. If a caller's Mongo write aborts after `save`, the event
-	* SURVIVES here and describes something that never happened. Declaring
-	* `false` lets a caller that needs real atomicity (`@classytic/access`) refuse
-	* at boot instead of silently inheriting a ghost-event path.
-	*/
-	transactionalSave = false;
-	events = [];
-	async save(event, _options) {
-		this.events.push({ event });
-	}
-	async getPending(limit) {
-		return this.events.filter((e) => !e.acknowledgedAt).slice(0, limit).map((e) => e.event);
-	}
-	async acknowledge(eventId, _options) {
-		const entry = this.events.find((e) => e.event.meta.id === eventId);
-		if (entry) entry.acknowledgedAt = /* @__PURE__ */ new Date();
-	}
-	async purge(olderThanMs) {
-		const cutoff = Date.now() - olderThanMs;
-		const before = this.events.length;
-		this.events = this.events.filter((e) => !e.acknowledgedAt || e.acknowledgedAt.getTime() >= cutoff);
-		return before - this.events.length;
-	}
-	/** Every saved event (acknowledged or not) — test inspection helper. */
-	all() {
-		return this.events.map((e) => e.event);
-	}
-	/** Reset the store — test helper. */
-	clear() {
-		this.events = [];
-	}
-};
 //#endregion
-export { InProcessEventBus, MemoryOutboxStore, createInProcessBus };
+export { InProcessEventBus, createInProcessBus };

package/dist/idempotency.d.mts

@@ -0,0 +1,253 @@
+//#region src/workflow/idempotency.d.ts
+/**
+ * Idempotency claim + lease — the CONTRACT, not the store.
+ *
+ * ## Why this exists
+ *
+ * Every module that accepts a command needs to answer the same three-part
+ * question when a key arrives: *have I seen this, am I still working on it, or
+ * is this the first time?* Three kernels already answer it, incompatibly:
+ *
+ * | package | states | lease | replay |
+ * |---|---|---|---|
+ * | `@classytic/cart` | `in_flight` / `succeeded` / `failed` | yes — token + expiry | inline or pointer |
+ * | `@classytic/catalog` (offers) | `pending` / `completed` | **no** | serialized string |
+ * | `@classytic/contract` (amendments) | implicit — `claimedAt` + `attempts` | partial | none |
+ *
+ * Only the first models the crash window. The second cannot distinguish "still
+ * running" from "crashed mid-write", so a retry either blocks forever on a dead
+ * `pending` row or re-applies the mutation — and neither outcome errors. The
+ * third has no state at all.
+ *
+ * Left alone, every spine module that accepts a command invents a fourth shape.
+ * This module is the shared vocabulary: types plus PURE state functions. It
+ * owns no collection, no index, no driver — the adapter that persists a claim
+ * is the caller's.
+ *
+ * ## The three-valued outcome is the point
+ *
+ * {@link ClaimOutcome} is `claimed | replayed | in_flight`, and **`in_flight` is
+ * not a failure.** A concurrent attempt holding a live lease means the answer is
+ * *not yet known*, exactly like a provider timeout: the work may be about to
+ * succeed. Mapping it onto an error licenses the caller to retry the mutation,
+ * and if the first attempt lands that is a double-apply — the same asymmetry
+ * that makes `unknown` a required payment outcome. The correct handling is to
+ * wait out {@link InFlightDecision.retryAfterMs} and ask again, never to
+ * re-execute.
+ *
+ * ## Two identifiers that must not be confused
+ *
+ * - **`key`** — caller-supplied, STABLE across retries of one logical command.
+ *   Derive it deterministically; a random fallback defeats deduplication while
+ *   looking correctly wired.
+ * - **`leaseToken`** — minted fresh per ATTEMPT, and deliberately random. It
+ *   answers "am I still the attempt that owns this claim?", so two attempts
+ *   must never mint the same one. Deriving it would make a takeover
+ *   indistinguishable from the attempt it replaced.
+ */
+/** Default crash-window lease, matching `@classytic/cart`'s proven 30s. */
+declare const DEFAULT_LEASE_MS = 30000;
+/**
+ * Persisted state of a claim.
+ *
+ * `failed` is TERMINAL and replayable: a command that failed deterministically
+ * must fail the same way on retry, or the caller learns a different answer to
+ * the same question. It is not a licence to re-execute.
+ */
+type ClaimState = 'in_flight' | 'succeeded' | 'failed';
+/**
+ * What a claim attempt is allowed to do next.
+ *
+ * - `claimed` — this attempt owns the claim; EXECUTE the command.
+ * - `replayed` — a terminal record exists; RETURN its stored result, execute nothing.
+ * - `in_flight` — another live attempt owns it; WAIT and re-ask. **Not a failure.**
+ */
+type ClaimOutcome = 'claimed' | 'replayed' | 'in_flight';
+/** The stored outcome of a completed command — replayed verbatim to retries. */
+type ClaimResult<TValue = unknown> = {
+  readonly status: 'succeeded';
+  readonly value: TValue;
+} | {
+  readonly status: 'failed';
+  readonly error: ClaimError;
+};
+/**
+ * A replayable failure. `code` is a CLOSED host vocabulary, never a raw vendor
+ * string — this value is persisted and returned to callers.
+ */
+interface ClaimError {
+  readonly code: string;
+  readonly message: string;
+}
+/**
+ * The composite identity of a claim.
+ *
+ * `key` alone is not the identity. Two different operations must never share a
+ * key, and a key issued for one aggregate/actor must not satisfy a command
+ * against another — so the operation and any scoping segments are part of what
+ * the unique index covers. `@classytic/cart` learned this as
+ * `(organizationId, cartRef, operation, actorRef, idempotencyKey)`.
+ */
+interface IdempotencyIdentity {
+  /** The command this key was issued for — `'checkout.finalize'`, `'purchase.pay'`. */
+  readonly operation: string;
+  /** Caller-supplied key, stable across retries of the SAME logical command. */
+  readonly key: string;
+  /** Scoping segments — organizationId, aggregate ref, actor ref. */
+  readonly scope?: Readonly<Record<string, string>>;
+}
+/**
+ * A claim record. The adapter persists exactly these fields (plus whatever it
+ * needs for TTL), with a unique index over {@link IdempotencyIdentity}.
+ */
+interface IdempotencyClaim<TValue = unknown> {
+  readonly identity: IdempotencyIdentity;
+  /**
+   * Digest of the request body this key was first used with. A retry that
+   * presents the same key with a DIFFERENT body is not a retry — see
+   * {@link decideClaim}.
+   */
+  readonly requestFingerprint: string;
+  readonly state: ClaimState;
+  /** Which ATTEMPT currently owns the claim. Rotates on takeover. */
+  readonly leaseToken: string;
+  /** After this instant the lease is dead and another attempt may take over. */
+  readonly leaseExpiresAt: Date;
+  readonly createdAt: Date;
+  /** Set when `state` becomes terminal. */
+  readonly completedAt?: Date;
+  /** Present iff `state` is terminal. Absent on `in_flight`. */
+  readonly result?: ClaimResult<TValue>;
+  /** Monotonic attempt counter — each successful takeover increments it. */
+  readonly attempts: number;
+}
+type IdempotencyErrorCode = /** Same key, different request body. Never a retry — two commands sharing one key. */'FINGERPRINT_MISMATCH' /** A terminal claim carrying no stored result. Unreplayable; must not answer "ok". */ | 'MISSING_REPLAY' /** The attempt no longer owns the lease — another attempt took over. */ | 'LEASE_LOST' /** Completing / renewing a claim that already reached a terminal state. */ | 'ALREADY_TERMINAL' /** Malformed input (empty key, non-positive lease, invalid instant). */ | 'INVALID_CLAIM';
+declare class IdempotencyError extends Error {
+  readonly name = "IdempotencyError";
+  readonly code: IdempotencyErrorCode;
+  constructor(code: IdempotencyErrorCode, message: string);
+}
+/**
+ * The deterministic string form of an identity — safe as a single unique-index
+ * key when a compound index is not available.
+ *
+ * Built with canonical JSON rather than `join(':')`: a delimiter-joined
+ * composite lets `{ ref: 'a:b', actor: 'c' }` and `{ ref: 'a', actor: 'b:c' }`
+ * produce the SAME key, which silently makes one caller's claim satisfy
+ * another's command.
+ */
+declare function identityKey(identity: IdempotencyIdentity): string;
+/** True when two identities address the same claim. */
+declare function sameIdentity(a: IdempotencyIdentity, b: IdempotencyIdentity): boolean;
+/**
+ * Fingerprint a request body — `sha256(canonicalJson(body))`.
+ *
+ * Deterministic and key-order independent, so a client that reserializes its
+ * body does not read as a different request. Use the WHOLE body that decides
+ * the mutation; fingerprinting a subset means two genuinely different commands
+ * share a fingerprint and one silently replays the other's result.
+ */
+declare function fingerprintRequest(body: unknown): string;
+/**
+ * Mint a lease token for ONE attempt.
+ *
+ * Random on purpose — see the module docblock. This is the one identifier in
+ * the idempotency contract that must NOT be derived.
+ */
+declare function newLeaseToken(): string;
+/** Has the crash-window lease lapsed at `now`? Expiry is exclusive of `now`. */
+declare function isLeaseExpired(claim: IdempotencyClaim<unknown>, now: Date): boolean;
+/** Does `leaseToken` still own this claim at `now`? */
+declare function holdsLease(claim: IdempotencyClaim<unknown>, leaseToken: string, now: Date): boolean;
+interface ClaimRequest {
+  readonly identity: IdempotencyIdentity;
+  readonly requestFingerprint: string;
+  /** Injected clock — no ambient `new Date()`, so the crash window is testable. */
+  readonly now: Date;
+  /** Injected token for THIS attempt — see {@link newLeaseToken}. */
+  readonly leaseToken: string;
+  /** Crash-window length. Default {@link DEFAULT_LEASE_MS}. */
+  readonly leaseMs?: number;
+}
+/** This attempt owns the claim and must EXECUTE the command. */
+interface ClaimedDecision<TValue> {
+  readonly outcome: 'claimed';
+  readonly claim: IdempotencyClaim<TValue>;
+  /**
+   * Present when this claim took over a lapsed lease — the dead attempt's
+   * token. Persist the takeover as a CONDITIONAL update on that token so two
+   * simultaneous takeovers cannot both win.
+   */
+  readonly tookOverFrom?: string;
+}
+/** A terminal record exists: RETURN its result, execute nothing. */
+interface ReplayedDecision<TValue> {
+  readonly outcome: 'replayed';
+  readonly claim: IdempotencyClaim<TValue>;
+  readonly result: ClaimResult<TValue>;
+}
+/**
+ * Another attempt holds a live lease. **Not a failure** — the answer is not yet
+ * known. Wait `retryAfterMs` and re-ask; never re-execute.
+ */
+interface InFlightDecision<TValue> {
+  readonly outcome: 'in_flight';
+  readonly claim: IdempotencyClaim<TValue>;
+  /** How long until the incumbent's lease lapses. Always > 0. */
+  readonly retryAfterMs: number;
+}
+type ClaimDecision<TValue = unknown> = ClaimedDecision<TValue> | ReplayedDecision<TValue> | InFlightDecision<TValue>;
+/**
+ * The whole state machine, as one pure function.
+ *
+ * | stored state | lease | decision |
+ * |---|---|---|
+ * | (none) | — | `claimed` — fresh claim |
+ * | `in_flight` | live | `in_flight` — wait, do NOT execute |
+ * | `in_flight` | lapsed | `claimed` — takeover, `tookOverFrom` set |
+ * | `succeeded` / `failed` | — | `replayed` — return the stored result |
+ *
+ * Two conditions throw rather than returning a decision, because both mean the
+ * question itself was wrong:
+ *
+ * - **`FINGERPRINT_MISMATCH`** — the same key with a different body. That is
+ *   two commands, not one retried command; answering either way is wrong.
+ *   Surface it as a 4xx (Stripe returns 400 here), never as a fresh claim.
+ * - **`MISSING_REPLAY`** — a terminal record with no stored result. There is
+ *   nothing to replay, and inventing an empty success is precisely the silent
+ *   permissive default this codebase keeps getting bitten by.
+ */
+declare function decideClaim<TValue = unknown>(existing: IdempotencyClaim<TValue> | null | undefined, request: ClaimRequest): ClaimDecision<TValue>;
+/**
+ * Extend a live lease — for a command that legitimately outruns the crash
+ * window. Throws `LEASE_LOST` when the caller no longer owns the claim, so a
+ * superseded attempt cannot silently keep working and then write its result
+ * over the winner's.
+ */
+declare function renewLease<TValue>(claim: IdempotencyClaim<TValue>, input: {
+  readonly leaseToken: string;
+  readonly now: Date;
+  readonly leaseMs?: number;
+}): IdempotencyClaim<TValue>;
+/**
+ * Move a claim to a terminal state with the result retries will replay.
+ *
+ * The lease check is the important part: an attempt whose lease lapsed and was
+ * taken over must NOT write its result. Without it, the slow attempt's answer
+ * overwrites the takeover's, and every subsequent retry replays an outcome that
+ * does not match what was actually applied.
+ */
+declare function completeClaim<TValue>(claim: IdempotencyClaim<TValue>, input: {
+  readonly leaseToken: string;
+  readonly now: Date;
+  readonly result: ClaimResult<TValue>;
+}): IdempotencyClaim<TValue>;
+/**
+ * Narrowing helper for the one outcome callers keep getting wrong.
+ *
+ * `in_flight` is neither success nor failure. Route it to a 409 + `Retry-After`
+ * (or an internal wait), never to the command's error path.
+ */
+declare function isInFlight<TValue>(decision: ClaimDecision<TValue>): decision is InFlightDecision<TValue>;
+//#endregion
+export { ClaimDecision, ClaimError, ClaimOutcome, ClaimRequest, ClaimResult, ClaimState, ClaimedDecision, DEFAULT_LEASE_MS, IdempotencyClaim, IdempotencyError, IdempotencyErrorCode, IdempotencyIdentity, InFlightDecision, ReplayedDecision, completeClaim, decideClaim, fingerprintRequest, holdsLease, identityKey, isInFlight, isLeaseExpired, newLeaseToken, renewLease, sameIdentity };

package/dist/idempotency.mjs

@@ -0,0 +1,226 @@
+import { canonicalDigest, canonicalJson } from "./canonical.mjs";
+//#region src/workflow/idempotency.ts
+/**
+* Idempotency claim + lease — the CONTRACT, not the store.
+*
+* ## Why this exists
+*
+* Every module that accepts a command needs to answer the same three-part
+* question when a key arrives: *have I seen this, am I still working on it, or
+* is this the first time?* Three kernels already answer it, incompatibly:
+*
+* | package | states | lease | replay |
+* |---|---|---|---|
+* | `@classytic/cart` | `in_flight` / `succeeded` / `failed` | yes — token + expiry | inline or pointer |
+* | `@classytic/catalog` (offers) | `pending` / `completed` | **no** | serialized string |
+* | `@classytic/contract` (amendments) | implicit — `claimedAt` + `attempts` | partial | none |
+*
+* Only the first models the crash window. The second cannot distinguish "still
+* running" from "crashed mid-write", so a retry either blocks forever on a dead
+* `pending` row or re-applies the mutation — and neither outcome errors. The
+* third has no state at all.
+*
+* Left alone, every spine module that accepts a command invents a fourth shape.
+* This module is the shared vocabulary: types plus PURE state functions. It
+* owns no collection, no index, no driver — the adapter that persists a claim
+* is the caller's.
+*
+* ## The three-valued outcome is the point
+*
+* {@link ClaimOutcome} is `claimed | replayed | in_flight`, and **`in_flight` is
+* not a failure.** A concurrent attempt holding a live lease means the answer is
+* *not yet known*, exactly like a provider timeout: the work may be about to
+* succeed. Mapping it onto an error licenses the caller to retry the mutation,
+* and if the first attempt lands that is a double-apply — the same asymmetry
+* that makes `unknown` a required payment outcome. The correct handling is to
+* wait out {@link InFlightDecision.retryAfterMs} and ask again, never to
+* re-execute.
+*
+* ## Two identifiers that must not be confused
+*
+* - **`key`** — caller-supplied, STABLE across retries of one logical command.
+*   Derive it deterministically; a random fallback defeats deduplication while
+*   looking correctly wired.
+* - **`leaseToken`** — minted fresh per ATTEMPT, and deliberately random. It
+*   answers "am I still the attempt that owns this claim?", so two attempts
+*   must never mint the same one. Deriving it would make a takeover
+*   indistinguishable from the attempt it replaced.
+*/
+/** Default crash-window lease, matching `@classytic/cart`'s proven 30s. */
+const DEFAULT_LEASE_MS = 3e4;
+var IdempotencyError = class extends Error {
+	name = "IdempotencyError";
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+/**
+* The deterministic string form of an identity — safe as a single unique-index
+* key when a compound index is not available.
+*
+* Built with canonical JSON rather than `join(':')`: a delimiter-joined
+* composite lets `{ ref: 'a:b', actor: 'c' }` and `{ ref: 'a', actor: 'b:c' }`
+* produce the SAME key, which silently makes one caller's claim satisfy
+* another's command.
+*/
+function identityKey(identity) {
+	assertNonEmpty(identity.operation, "identity.operation");
+	assertNonEmpty(identity.key, "identity.key");
+	return canonicalJson({
+		operation: identity.operation,
+		key: identity.key,
+		scope: identity.scope ?? {}
+	});
+}
+/** True when two identities address the same claim. */
+function sameIdentity(a, b) {
+	return identityKey(a) === identityKey(b);
+}
+/**
+* Fingerprint a request body — `sha256(canonicalJson(body))`.
+*
+* Deterministic and key-order independent, so a client that reserializes its
+* body does not read as a different request. Use the WHOLE body that decides
+* the mutation; fingerprinting a subset means two genuinely different commands
+* share a fingerprint and one silently replays the other's result.
+*/
+function fingerprintRequest(body) {
+	return canonicalDigest(body);
+}
+/**
+* Mint a lease token for ONE attempt.
+*
+* Random on purpose — see the module docblock. This is the one identifier in
+* the idempotency contract that must NOT be derived.
+*/
+function newLeaseToken() {
+	const c = globalThis.crypto;
+	if (typeof c?.randomUUID === "function") return c.randomUUID();
+	return `lease_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 12)}`;
+}
+/** Has the crash-window lease lapsed at `now`? Expiry is exclusive of `now`. */
+function isLeaseExpired(claim, now) {
+	return now.getTime() >= claim.leaseExpiresAt.getTime();
+}
+/** Does `leaseToken` still own this claim at `now`? */
+function holdsLease(claim, leaseToken, now) {
+	return claim.leaseToken === leaseToken && !isLeaseExpired(claim, now);
+}
+/**
+* The whole state machine, as one pure function.
+*
+* | stored state | lease | decision |
+* |---|---|---|
+* | (none) | — | `claimed` — fresh claim |
+* | `in_flight` | live | `in_flight` — wait, do NOT execute |
+* | `in_flight` | lapsed | `claimed` — takeover, `tookOverFrom` set |
+* | `succeeded` / `failed` | — | `replayed` — return the stored result |
+*
+* Two conditions throw rather than returning a decision, because both mean the
+* question itself was wrong:
+*
+* - **`FINGERPRINT_MISMATCH`** — the same key with a different body. That is
+*   two commands, not one retried command; answering either way is wrong.
+*   Surface it as a 4xx (Stripe returns 400 here), never as a fresh claim.
+* - **`MISSING_REPLAY`** — a terminal record with no stored result. There is
+*   nothing to replay, and inventing an empty success is precisely the silent
+*   permissive default this codebase keeps getting bitten by.
+*/
+function decideClaim(existing, request) {
+	assertNonEmpty(request.requestFingerprint, "request.requestFingerprint");
+	assertNonEmpty(request.leaseToken, "request.leaseToken");
+	assertInstant(request.now, "request.now");
+	const leaseMs = request.leaseMs ?? 3e4;
+	if (!Number.isFinite(leaseMs) || leaseMs <= 0) throw new IdempotencyError("INVALID_CLAIM", `leaseMs must be a positive number of milliseconds, got ${String(request.leaseMs)} — a zero or negative lease is instantly expired, so every concurrent attempt takes over and executes.`);
+	if (existing == null) return {
+		outcome: "claimed",
+		claim: mintClaim(request, leaseMs, 1)
+	};
+	if (existing.requestFingerprint !== request.requestFingerprint) throw new IdempotencyError("FINGERPRINT_MISMATCH", `Idempotency key '${existing.identity.key}' was first used with a different request body (stored ${existing.requestFingerprint.slice(0, 12)}…, presented ${request.requestFingerprint.slice(0, 12)}…). Two distinct commands are sharing one key — replaying the first would return the wrong result, and claiming afresh would apply the second under a key already spent.`);
+	if (existing.state === "succeeded" || existing.state === "failed") {
+		if (existing.result === void 0) throw new IdempotencyError("MISSING_REPLAY", `Claim '${existing.identity.key}' is terminal (${existing.state}) but stores no result, so the retry cannot be answered. Reporting success here would fabricate an outcome that was never observed.`);
+		return {
+			outcome: "replayed",
+			claim: existing,
+			result: existing.result
+		};
+	}
+	if (!isLeaseExpired(existing, request.now)) return {
+		outcome: "in_flight",
+		claim: existing,
+		retryAfterMs: existing.leaseExpiresAt.getTime() - request.now.getTime()
+	};
+	return {
+		outcome: "claimed",
+		claim: {
+			...mintClaim(request, leaseMs, existing.attempts + 1),
+			createdAt: existing.createdAt
+		},
+		tookOverFrom: existing.leaseToken
+	};
+}
+function mintClaim(request, leaseMs, attempts) {
+	identityKey(request.identity);
+	return {
+		identity: request.identity,
+		requestFingerprint: request.requestFingerprint,
+		state: "in_flight",
+		leaseToken: request.leaseToken,
+		leaseExpiresAt: new Date(request.now.getTime() + leaseMs),
+		createdAt: request.now,
+		attempts
+	};
+}
+/**
+* Extend a live lease — for a command that legitimately outruns the crash
+* window. Throws `LEASE_LOST` when the caller no longer owns the claim, so a
+* superseded attempt cannot silently keep working and then write its result
+* over the winner's.
+*/
+function renewLease(claim, input) {
+	assertInstant(input.now, "now");
+	if (claim.state !== "in_flight") throw new IdempotencyError("ALREADY_TERMINAL", `cannot renew a ${claim.state} claim`);
+	if (!holdsLease(claim, input.leaseToken, input.now)) throw new IdempotencyError("LEASE_LOST", `lease token does not own this claim at ${input.now.toISOString()} (expired or taken over) — continuing would let two attempts believe they are the live one.`);
+	return {
+		...claim,
+		leaseExpiresAt: new Date(input.now.getTime() + (input.leaseMs ?? 3e4))
+	};
+}
+/**
+* Move a claim to a terminal state with the result retries will replay.
+*
+* The lease check is the important part: an attempt whose lease lapsed and was
+* taken over must NOT write its result. Without it, the slow attempt's answer
+* overwrites the takeover's, and every subsequent retry replays an outcome that
+* does not match what was actually applied.
+*/
+function completeClaim(claim, input) {
+	assertInstant(input.now, "now");
+	if (claim.state !== "in_flight") throw new IdempotencyError("ALREADY_TERMINAL", `claim is already ${claim.state}; completing it again would replace a result that retries may already have replayed.`);
+	if (claim.leaseToken !== input.leaseToken) throw new IdempotencyError("LEASE_LOST", "lease token does not own this claim — another attempt took it over, and writing this result would overwrite theirs.");
+	return {
+		...claim,
+		state: input.result.status,
+		result: input.result,
+		completedAt: input.now
+	};
+}
+/**
+* Narrowing helper for the one outcome callers keep getting wrong.
+*
+* `in_flight` is neither success nor failure. Route it to a 409 + `Retry-After`
+* (or an internal wait), never to the command's error path.
+*/
+function isInFlight(decision) {
+	return decision.outcome === "in_flight";
+}
+function assertNonEmpty(value, label) {
+	if (typeof value !== "string" || value.length === 0) throw new IdempotencyError("INVALID_CLAIM", `${label} must be a non-empty string, got ${String(value)}`);
+}
+function assertInstant(value, label) {
+	if (!(value instanceof Date) || !Number.isFinite(value.getTime())) throw new IdempotencyError("INVALID_CLAIM", `${label} must be a valid Date, got ${String(value)}`);
+}
+//#endregion
+export { DEFAULT_LEASE_MS, IdempotencyError, completeClaim, decideClaim, fingerprintRequest, holdsLease, identityKey, isInFlight, isLeaseExpired, newLeaseToken, renewLease, sameIdentity };

package/dist/memory-outbox.d.mts

@@ -0,0 +1,64 @@
+import { DeadLetteredEvent, DomainEvent } from "./events.mjs";
+import { OutboxAcknowledgeOptions, OutboxClaimOptions, OutboxErrorInfo, OutboxFailOptions, OutboxStatus, OutboxStore, OutboxWriteOptions } from "./outbox.mjs";
+
+//#region src/events/memory-outbox.d.ts
+interface MemoryEntry {
+  event: DomainEvent;
+  status: "pending" | "delivered" | "dead_letter";
+  attempts: number;
+  visibleAt: number;
+  leaseOwner: string | null;
+  leaseExpiresAt: number;
+  deliveredAt: number | null;
+  firstFailedAt: number | null;
+  lastFailedAt: number | null;
+  lastError: OutboxErrorInfo | null;
+  dedupeKey?: string;
+  /**
+   * When the row was written. Distinct from `visibleAt`, which retries push forward —
+   * `oldestPendingAgeMs` must answer "how long has this gone undelivered", and reading
+   * it off a field that every retry resets would make a permanently-failing row look
+   * permanently fresh.
+   */
+  createdAt: number;
+}
+declare class MemoryOutboxStore implements OutboxStore {
+  private readonly entries;
+  private readonly seenDedupeKeys;
+  /**
+   * Drop every entry (including delivered / failed / dead-lettered rows) and
+   * the dedupe-key memory.
+   *
+   * For tests only — it is the in-memory analogue of truncating the table, and
+   * exists so a suite can isolate cases against ONE store instance (the
+   * `reset` hook of `runOutboxStoreContract`). Not part of `OutboxStore`; a
+   * production store must never expose this.
+   */
+  clear(): void;
+  /**
+   * For tests only — every stored event regardless of status, in insertion
+   * order. The in-memory analogue of `SELECT * FROM outbox`, used by the
+   * `/event-infra` contract test to assert what a `purge` left behind. Not part
+   * of `OutboxStore`; a production store must never expose this.
+   */
+  all(): DomainEvent[];
+  save(event: DomainEvent, options?: OutboxWriteOptions): Promise<void>;
+  getPending(limit: number): Promise<DomainEvent[]>;
+  claimPending(options?: OutboxClaimOptions): Promise<DomainEvent[]>;
+  acknowledge(eventId: string, options?: OutboxAcknowledgeOptions): Promise<void>;
+  fail(eventId: string, error: OutboxErrorInfo, options?: OutboxFailOptions): Promise<void>;
+  getDeadLettered(limit: number): Promise<DeadLetteredEvent[]>;
+  purge(olderThanMs: number): Promise<number>;
+  /**
+   * Re-drive one dead-lettered row. Scoped to `dead_letter`: a row that is merely
+   * backing off must keep its attempt count, and the id alone cannot tell the two apart.
+   */
+  requeue(eventId: string): Promise<boolean>;
+  countByStatus(status: OutboxStatus): Promise<number>;
+  /** Age of the oldest PENDING row — see `MemoryEntry.createdAt` for why not `visibleAt`. */
+  oldestPendingAgeMs(): Promise<number | null>;
+  /** Test helper: inspect entry by id */
+  _getEntry(eventId: string): Readonly<MemoryEntry> | undefined;
+}
+//#endregion
+export { MemoryOutboxStore };