@cqrs-ddd/pipeline-idempotency 0.5.0

package/README.md

@@ -0,0 +1,39 @@
+# @cqrs-ddd/pipeline-idempotency
+
+Idempotency for `@cqrs-ddd/pipeline`: a command runs once per operation key, a duplicate
+gets the stored response, a key reused with another payload is refused, and with a
+replay scope a response is replayed only to a caller authorized under the same scope.
+Memory, Redis and PostgreSQL stores are included; `toHttpResponse()` from
+`@cqrs-ddd/pipeline-idempotency/http` turns a conflict into a 409 or 422 answer.
+
+**Documentation:** [guide](https://aristoteliss.github.io/ddd-cqrs/packages/pipeline-idempotency/) · [API reference](https://aristoteliss.github.io/ddd-cqrs/api/cqrs-ddd/pipeline-idempotency/) · [all packages](https://aristoteliss.github.io/ddd-cqrs/)
+
+## Installation
+
+```bash
+pnpm add @cqrs-ddd/pipeline-idempotency @cqrs-ddd/pipeline
+```
+
+Requires Node.js 22.12 or later. Published as an ES module; a CommonJS application loads
+it with `require()`.
+
+## Example
+
+```ts
+const pipeline = createPipeline({
+  behaviors: [new IdempotencyBehavior(new MemoryIdempotencyStore())],
+});
+
+export const charge = pipeline.wrap(
+  { name: 'charge', kind: 'command' },
+  idempotent({ keyFactory: (context) => (context.request as { key: string }).key }),
+)(async (input: { key: string; amount: number }) => payments.charge(input));
+```
+
+An idempotency key is an operation identity: partition it by tenant and principal, for
+example with `createPartitionedIdempotencyKeyFactory()`.
+
+## License
+
+Dual-licensed under **AGPLv3** and a **Commercial License**. See `LICENSE` and
+`COMMERCIAL_LICENSE.txt`.

package/dist/constants/tokens.d.ts

@@ -0,0 +1,3 @@
+/** Default time-to-live for an idempotency key: 24 hours, in milliseconds. */
+export declare const DEFAULT_IDEMPOTENCY_TTL_MS = 86400000;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/constants/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/constants/tokens.ts"],"names":[],"mappings":"AAEA,8EAA8E;AAC9E,eAAO,MAAM,0BAA0B,WAAa,CAAC"}

package/dist/constants/tokens.js

@@ -0,0 +1,4 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/** Default time-to-live for an idempotency key: 24 hours, in milliseconds. */
+export const DEFAULT_IDEMPOTENCY_TTL_MS = 86_400_000;
+//# sourceMappingURL=tokens.js.map

package/dist/constants/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../src/constants/tokens.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,8EAA8E;AAC9E,MAAM,CAAC,MAAM,0BAA0B,GAAG,UAAU,CAAC"}

package/dist/errors/idempotency-completion.error.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Which post-execution step failed.
+ *
+ * - `snapshot` — the handler's response could not be serialized into a replayable
+ *   record (a cycle, a function, an unsupported type).
+ * - `store`    — the record was serializable but the store rejected the write.
+ */
+export type IdempotencyFinalizationPhase = 'snapshot' | 'store';
+/**
+ * Raised when the business handler succeeded but the idempotency record could
+ * not be finalized.
+ *
+ * Retrying the request may repeat business side effects even though the caller
+ * received an error. Consumers can use {@link executionSucceeded} to distinguish this state from a
+ * handler failure and make an explicit retry/reconciliation decision, and
+ * {@link phase} to tell an unusable response apart from an unavailable store.
+ *
+ * In both phases the claim is deliberately retained until its TTL expires. The
+ * side effects have already happened, so releasing the key would let the very
+ * next retry repeat them immediately. Retention does not prevent all duplicates
+ * — it only prevents immediate reentry while the claim is still live.
+ */
+export declare class IdempotencyCompletionError extends Error {
+    readonly key: string;
+    readonly claimId: string;
+    readonly cause: unknown;
+    readonly phase: IdempotencyFinalizationPhase;
+    readonly name = "IdempotencyCompletionError";
+    readonly executionSucceeded: true;
+    constructor(key: string, claimId: string, cause: unknown, phase?: IdempotencyFinalizationPhase);
+}
+//# sourceMappingURL=idempotency-completion.error.d.ts.map

package/dist/errors/idempotency-completion.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency-completion.error.d.ts","sourceRoot":"","sources":["../../src/errors/idempotency-completion.error.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,MAAM,4BAA4B,GAAG,UAAU,GAAG,OAAO,CAAC;AAEhE;;;;;;;;;;;;;GAaG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;aAKjC,GAAG,EAAE,MAAM;aACX,OAAO,EAAE,MAAM;aACf,KAAK,EAAE,OAAO;aACd,KAAK,EAAE,4BAA4B;IAPrD,SAAkB,IAAI,gCAAgC;IACtD,QAAQ,CAAC,kBAAkB,OAAiB;IAE5C,YACkB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,OAAO,EACd,KAAK,GAAE,4BAAsC,EAO9D;CACF"}

package/dist/errors/idempotency-completion.error.js

@@ -0,0 +1,33 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/**
+ * Raised when the business handler succeeded but the idempotency record could
+ * not be finalized.
+ *
+ * Retrying the request may repeat business side effects even though the caller
+ * received an error. Consumers can use {@link executionSucceeded} to distinguish this state from a
+ * handler failure and make an explicit retry/reconciliation decision, and
+ * {@link phase} to tell an unusable response apart from an unavailable store.
+ *
+ * In both phases the claim is deliberately retained until its TTL expires. The
+ * side effects have already happened, so releasing the key would let the very
+ * next retry repeat them immediately. Retention does not prevent all duplicates
+ * — it only prevents immediate reentry while the claim is still live.
+ */
+export class IdempotencyCompletionError extends Error {
+    key;
+    claimId;
+    cause;
+    phase;
+    name = 'IdempotencyCompletionError';
+    executionSucceeded = true;
+    constructor(key, claimId, cause, phase = 'store') {
+        super(phase === 'snapshot'
+            ? `Handler execution succeeded, but its response for idempotency key "${key}" could not be serialized into a replayable record. The claim is retained until it expires so the side effects are not immediately repeated.`
+            : `Handler execution succeeded, but the idempotency record for key "${key}" could not be completed.`);
+        this.key = key;
+        this.claimId = claimId;
+        this.cause = cause;
+        this.phase = phase;
+    }
+}
+//# sourceMappingURL=idempotency-completion.error.js.map

package/dist/errors/idempotency-completion.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency-completion.error.js","sourceRoot":"","sources":["../../src/errors/idempotency-completion.error.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAWtE;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAKjC,GAAG;IACH,OAAO;IACP,KAAK;IACL,KAAK;IAPL,IAAI,GAAG,4BAA4B,CAAC;IAC7C,kBAAkB,GAAG,IAAa,CAAC;IAE5C,YACkB,GAAW,EACX,OAAe,EACf,KAAc,EACd,KAAK,GAAiC,OAAO;QAE7D,KAAK,CACH,KAAK,KAAK,UAAU;YAClB,CAAC,CAAC,sEAAsE,GAAG,8IAA8I;YACzN,CAAC,CAAC,oEAAoE,GAAG,2BAA2B,CACvG,CAAC;mBATc,GAAG;uBACH,OAAO;qBACP,KAAK;qBACL,KAAK;IAOvB,CAAC;CACF"}

package/dist/errors/idempotency-conflict.error.d.ts

@@ -0,0 +1,33 @@
+/** Why an idempotent request was rejected. */
+export type IdempotencyConflictReason = 'in_progress' | 'key_reuse' | 'replay_scope';
+/**
+ * Thrown by {@link IdempotencyBehavior} when a request cannot be served:
+ *
+ * - `in_progress` — an identical request is still running (`409 Conflict`);
+ * - `key_reuse` — the key was already used with a **different** payload
+ *   (`422 Unprocessable Entity`);
+ * - `replay_scope` — the stored response was authorized under a different scope
+ *   than the current caller's, or the record predates scope capture
+ *   (`409 Conflict`). The handler is not re-executed and the record is kept.
+ *
+ * `toHttpResponse` of `@cqrs-ddd/pipeline-idempotency/http` maps it to its HTTP status.
+ */
+export declare class IdempotencyConflictError extends Error {
+    /** The idempotency key in conflict. */
+    readonly key: string;
+    /** The request that was rejected, e.g. `CreateUserCommand`. */
+    readonly requestName: string;
+    /** Why the request was rejected. */
+    readonly reason: IdempotencyConflictReason;
+    /**
+     * Suggested HTTP status: `409` for `in_progress` and `replay_scope`, `422` for
+     * `key_reuse`.
+     */
+    readonly statusCode: number;
+    constructor(params: {
+        key: string;
+        requestName: string;
+        reason: IdempotencyConflictReason;
+    });
+}
+//# sourceMappingURL=idempotency-conflict.error.d.ts.map

package/dist/errors/idempotency-conflict.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency-conflict.error.d.ts","sourceRoot":"","sources":["../../src/errors/idempotency-conflict.error.ts"],"names":[],"mappings":"AAEA,8CAA8C;AAC9C,MAAM,MAAM,yBAAyB,GACjC,aAAa,GACb,WAAW,GACX,cAAc,CAAC;AA0BnB;;;;;;;;;;;GAWG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,uCAAuC;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,yBAAyB,CAAC;IAC3C;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,YAAY,MAAM,EAAE;QAClB,GAAG,EAAE,MAAM,CAAC;QACZ,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,yBAAyB,CAAC;KACnC,EAOA;CACF"}

package/dist/errors/idempotency-conflict.error.js

@@ -0,0 +1,48 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+function conflictMessage(params) {
+    switch (params.reason) {
+        case 'in_progress':
+            return (`A request with idempotency key "${params.key}" is already in ` +
+                `progress for ${params.requestName}`);
+        case 'replay_scope':
+            return (`Idempotency key "${params.key}" holds a ${params.requestName} response ` +
+                'authorized under a different scope than this caller; it cannot be replayed');
+        default:
+            return (`Idempotency key "${params.key}" was already used for ` +
+                `${params.requestName} with a different payload`);
+    }
+}
+/**
+ * Thrown by {@link IdempotencyBehavior} when a request cannot be served:
+ *
+ * - `in_progress` — an identical request is still running (`409 Conflict`);
+ * - `key_reuse` — the key was already used with a **different** payload
+ *   (`422 Unprocessable Entity`);
+ * - `replay_scope` — the stored response was authorized under a different scope
+ *   than the current caller's, or the record predates scope capture
+ *   (`409 Conflict`). The handler is not re-executed and the record is kept.
+ *
+ * `toHttpResponse` of `@cqrs-ddd/pipeline-idempotency/http` maps it to its HTTP status.
+ */
+export class IdempotencyConflictError extends Error {
+    /** The idempotency key in conflict. */
+    key;
+    /** The request that was rejected, e.g. `CreateUserCommand`. */
+    requestName;
+    /** Why the request was rejected. */
+    reason;
+    /**
+     * Suggested HTTP status: `409` for `in_progress` and `replay_scope`, `422` for
+     * `key_reuse`.
+     */
+    statusCode;
+    constructor(params) {
+        super(conflictMessage(params));
+        this.name = 'IdempotencyConflictError';
+        this.key = params.key;
+        this.requestName = params.requestName;
+        this.reason = params.reason;
+        this.statusCode = params.reason === 'key_reuse' ? 422 : 409;
+    }
+}
+//# sourceMappingURL=idempotency-conflict.error.js.map

package/dist/errors/idempotency-conflict.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency-conflict.error.js","sourceRoot":"","sources":["../../src/errors/idempotency-conflict.error.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAQtE,SAAS,eAAe,CAAC,MAIxB;IACC,QAAQ,MAAM,CAAC,MAAM,EAAE,CAAC;QACtB,KAAK,aAAa;YAChB,OAAO,CACL,mCAAmC,MAAM,CAAC,GAAG,kBAAkB;gBAC/D,gBAAgB,MAAM,CAAC,WAAW,EAAE,CACrC,CAAC;QACJ,KAAK,cAAc;YACjB,OAAO,CACL,oBAAoB,MAAM,CAAC,GAAG,aAAa,MAAM,CAAC,WAAW,YAAY;gBACzE,4EAA4E,CAC7E,CAAC;QACJ;YACE,OAAO,CACL,oBAAoB,MAAM,CAAC,GAAG,yBAAyB;gBACvD,GAAG,MAAM,CAAC,WAAW,2BAA2B,CACjD,CAAC;IACN,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IACjD,uCAAuC;IAC9B,GAAG,CAAS;IACrB,+DAA+D;IACtD,WAAW,CAAS;IAC7B,oCAAoC;IAC3B,MAAM,CAA4B;IAC3C;;;OAGG;IACM,UAAU,CAAS;IAE5B,YAAY,MAIX;QACC,KAAK,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;QACvC,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC;QACtB,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;QACtC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;IAC9D,CAAC;CACF"}

package/dist/errors/missing-partition.error.d.ts

@@ -0,0 +1,17 @@
+import { MissingPartitionError } from '@cqrs-ddd/pipeline';
+/** Which dimension of the idempotency key could not be resolved. */
+export type IdempotencyPartitionDimension = 'tenant' | 'principal' | 'operation';
+/**
+ * Raised before a key is claimed when a dimension required by
+ * {@link createPartitionedIdempotencyKeyFactory} cannot be resolved.
+ *
+ * Omitting a missing tenant or principal would
+ * merge isolation domains: every caller whose identity could not be resolved
+ * would share one deduplication namespace, so one caller's completed operation
+ * could be replayed to another, or suppress another's first execution.
+ */
+export declare class MissingIdempotencyPartitionError extends MissingPartitionError<IdempotencyPartitionDimension> {
+    readonly name = "MissingIdempotencyPartitionError";
+    constructor(requestName: string, dimension: IdempotencyPartitionDimension, remedy: string);
+}
+//# sourceMappingURL=missing-partition.error.d.ts.map

package/dist/errors/missing-partition.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"missing-partition.error.d.ts","sourceRoot":"","sources":["../../src/errors/missing-partition.error.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,oEAAoE;AACpE,MAAM,MAAM,6BAA6B,GACrC,QAAQ,GACR,WAAW,GACX,WAAW,CAAC;AAEhB;;;;;;;;GAQG;AACH,qBAAa,gCAAiC,SAAQ,qBAAqB,CAAC,6BAA6B,CAAC;IACxG,SAAkB,IAAI,sCAAsC;IAE5D,YACE,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,6BAA6B,EACxC,MAAM,EAAE,MAAM,EAGf;CACF"}

package/dist/errors/missing-partition.error.js

@@ -0,0 +1,18 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { MissingPartitionError } from '@cqrs-ddd/pipeline';
+/**
+ * Raised before a key is claimed when a dimension required by
+ * {@link createPartitionedIdempotencyKeyFactory} cannot be resolved.
+ *
+ * Omitting a missing tenant or principal would
+ * merge isolation domains: every caller whose identity could not be resolved
+ * would share one deduplication namespace, so one caller's completed operation
+ * could be replayed to another, or suppress another's first execution.
+ */
+export class MissingIdempotencyPartitionError extends MissingPartitionError {
+    name = 'MissingIdempotencyPartitionError';
+    constructor(requestName, dimension, remedy) {
+        super('Idempotency', requestName, dimension, remedy);
+    }
+}
+//# sourceMappingURL=missing-partition.error.js.map

package/dist/errors/missing-partition.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"missing-partition.error.js","sourceRoot":"","sources":["../../src/errors/missing-partition.error.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAQ3D;;;;;;;;GAQG;AACH,MAAM,OAAO,gCAAiC,SAAQ,qBAAoD;IACtF,IAAI,GAAG,kCAAkC,CAAC;IAE5D,YACE,WAAmB,EACnB,SAAwC,EACxC,MAAc;QAEd,KAAK,CAAC,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;IACvD,CAAC;CACF"}

package/dist/helpers/build-attributes.d.ts

@@ -0,0 +1,47 @@
+import { type IPipelineContext } from '@cqrs-ddd/pipeline';
+/**
+ * The idempotency decision of one execution as flat attributes:
+ * `idempotency.replayed` once `IdempotencyBehavior` decided whether to replay,
+ * and `idempotency.ownership_lost: true` only when the claim was lost while the
+ * handler ran. `{}` when the behavior did not run. The key is never included:
+ * it carries the tenant, the principal and the client's operation id.
+ *
+ * The result is plain data and needs no telemetry package: put it on a span, a
+ * log line, an audit record or a metric label (bounded values only).
+ *
+ * @param context - The pipeline execution, read after `IdempotencyBehavior` ran.
+ * @returns The attributes; empty when the behavior did not run.
+ *
+ * @example Span attributes
+ * With `AttributesBehavior` of `@cqrs-ddd/pipeline-opentelemetry`:
+ * ```ts
+ * createPipeline({
+ *   globalBehaviors: {
+ *     before: [TraceBehavior, [AttributesBehavior, { factories: [buildIdempotencyAttributes] }]],
+ *   },
+ * });
+ * ```
+ *
+ * @example Audit metadata
+ * `audit()` is declared outside `idempotent()`, so the record is built after its decision:
+ * ```ts
+ * @pipeline.wrap(
+ *   { kind: 'command' },
+ *   audit({ action: 'order.create', metadata: buildIdempotencyAttributes }),
+ *   idempotent({ keyFactory }),
+ * )
+ * ```
+ *
+ * @example A log line from a custom behavior, after the chain ran
+ * ```ts
+ * async handle(context: IPipelineContext, next: NextDelegate) {
+ *   try {
+ *     return await next();
+ *   } finally {
+ *     this.logger.log({ request: context.requestName, ...buildIdempotencyAttributes(context) });
+ *   }
+ * }
+ * ```
+ */
+export declare function buildIdempotencyAttributes(context: IPipelineContext): Record<string, boolean>;
+//# sourceMappingURL=build-attributes.d.ts.map

package/dist/helpers/build-attributes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-attributes.d.ts","sourceRoot":"","sources":["../../src/helpers/build-attributes.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,oBAAoB,CAAC;AAM5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,gBAAgB,GACxB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAYzB"}

package/dist/helpers/build-attributes.js

@@ -0,0 +1,59 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { getPipelineItem, hasPipelineItem, } from '@cqrs-ddd/pipeline';
+import { IDEMPOTENCY_OWNERSHIP_LOST_ITEM_TOKEN, IDEMPOTENCY_REPLAYED_ITEM_TOKEN, } from '../idempotency.behavior.js';
+/**
+ * The idempotency decision of one execution as flat attributes:
+ * `idempotency.replayed` once `IdempotencyBehavior` decided whether to replay,
+ * and `idempotency.ownership_lost: true` only when the claim was lost while the
+ * handler ran. `{}` when the behavior did not run. The key is never included:
+ * it carries the tenant, the principal and the client's operation id.
+ *
+ * The result is plain data and needs no telemetry package: put it on a span, a
+ * log line, an audit record or a metric label (bounded values only).
+ *
+ * @param context - The pipeline execution, read after `IdempotencyBehavior` ran.
+ * @returns The attributes; empty when the behavior did not run.
+ *
+ * @example Span attributes
+ * With `AttributesBehavior` of `@cqrs-ddd/pipeline-opentelemetry`:
+ * ```ts
+ * createPipeline({
+ *   globalBehaviors: {
+ *     before: [TraceBehavior, [AttributesBehavior, { factories: [buildIdempotencyAttributes] }]],
+ *   },
+ * });
+ * ```
+ *
+ * @example Audit metadata
+ * `audit()` is declared outside `idempotent()`, so the record is built after its decision:
+ * ```ts
+ * @pipeline.wrap(
+ *   { kind: 'command' },
+ *   audit({ action: 'order.create', metadata: buildIdempotencyAttributes }),
+ *   idempotent({ keyFactory }),
+ * )
+ * ```
+ *
+ * @example A log line from a custom behavior, after the chain ran
+ * ```ts
+ * async handle(context: IPipelineContext, next: NextDelegate) {
+ *   try {
+ *     return await next();
+ *   } finally {
+ *     this.logger.log({ request: context.requestName, ...buildIdempotencyAttributes(context) });
+ *   }
+ * }
+ * ```
+ */
+export function buildIdempotencyAttributes(context) {
+    const attributes = {};
+    if (hasPipelineItem(context, IDEMPOTENCY_REPLAYED_ITEM_TOKEN)) {
+        attributes['idempotency.replayed'] =
+            getPipelineItem(context, IDEMPOTENCY_REPLAYED_ITEM_TOKEN) === true;
+    }
+    if (getPipelineItem(context, IDEMPOTENCY_OWNERSHIP_LOST_ITEM_TOKEN) === true) {
+        attributes['idempotency.ownership_lost'] = true;
+    }
+    return attributes;
+}
+//# sourceMappingURL=build-attributes.js.map

package/dist/helpers/build-attributes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-attributes.js","sourceRoot":"","sources":["../../src/helpers/build-attributes.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EACL,eAAe,EACf,eAAe,GAEhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,qCAAqC,EACrC,+BAA+B,GAChC,MAAM,4BAA4B,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,UAAU,0BAA0B,CACxC,OAAyB;IAEzB,MAAM,UAAU,GAA4B,EAAE,CAAC;IAC/C,IAAI,eAAe,CAAC,OAAO,EAAE,+BAA+B,CAAC,EAAE,CAAC;QAC9D,UAAU,CAAC,sBAAsB,CAAC;YAChC,eAAe,CAAC,OAAO,EAAE,+BAA+B,CAAC,KAAK,IAAI,CAAC;IACvE,CAAC;IACD,IACE,eAAe,CAAC,OAAO,EAAE,qCAAqC,CAAC,KAAK,IAAI,EACxE,CAAC;QACD,UAAU,CAAC,4BAA4B,CAAC,GAAG,IAAI,CAAC;IAClD,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/helpers/fingerprint.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Produces a stable SHA-256 hex digest of an acyclic JSON-serializable value,
+ * with object keys sorted so semantically-equal payloads hash identically
+ * regardless of property order. Used to detect an idempotency key being reused
+ * with a different body.
+ */
+export declare function fingerprintValue(value: unknown): string;
+//# sourceMappingURL=fingerprint.d.ts.map

package/dist/helpers/fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../../src/helpers/fingerprint.ts"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEvD"}

package/dist/helpers/fingerprint.js

@@ -0,0 +1,13 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { createHash } from 'node:crypto';
+import { stableStringify } from '@cqrs-ddd/safe-stringify';
+/**
+ * Produces a stable SHA-256 hex digest of an acyclic JSON-serializable value,
+ * with object keys sorted so semantically-equal payloads hash identically
+ * regardless of property order. Used to detect an idempotency key being reused
+ * with a different body.
+ */
+export function fingerprintValue(value) {
+    return createHash('sha256').update(stableStringify(value)).digest('hex');
+}
+//# sourceMappingURL=fingerprint.js.map

package/dist/helpers/fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../../src/helpers/fingerprint.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC3E,CAAC"}

package/dist/helpers/idempotency.intent.d.ts

@@ -0,0 +1,31 @@
+import type { PipelineBehaviorTuple } from '@cqrs-ddd/pipeline';
+import { IdempotencyBehavior } from '../idempotency.behavior.js';
+import type { IdempotencyBehaviorOptions } from '../interfaces/idempotency-options.interface.js';
+export type IdempotencyIntentOptions = Omit<IdempotencyBehaviorOptions, 'keyFactory'> & ({
+    keyFactory: NonNullable<IdempotencyBehaviorOptions['keyFactory']>;
+    inheritModuleKey?: never;
+} | {
+    inheritModuleKey: true;
+    keyFactory?: never;
+});
+/**
+ * Returns an idempotency behavior entry for `pipeline.wrap()` or `createPipeline({ globalBehaviors })`.
+ * @param options A key factory and idempotency options, or `inheritModuleKey: true`
+ * when the behavior's constructor defaults supply the key factory. The inheritance marker is not
+ * forwarded to the behavior and does not validate module configuration.
+ * @returns The behavior class and options tuple.
+ * Keys must distinguish operations and any tenant/principal scope that changes
+ * the authorized response; a shared key can replay another caller's response.
+ * @example
+ * ```ts
+ * export const createUser = pipeline.wrap(
+ *   { name: 'createUser', kind: 'command' },
+ *   idempotent({ keyFactory: createUserKey, ttl: 86_400_000 }),
+ * )(users.create);
+ *
+ * // The key factory comes from the IdempotencyBehavior constructor defaults.
+ * const entry = idempotent({ inheritModuleKey: true });
+ * ```
+ */
+export declare function idempotent(options: IdempotencyIntentOptions): PipelineBehaviorTuple<IdempotencyBehavior, IdempotencyBehaviorOptions>;
+//# sourceMappingURL=idempotency.intent.d.ts.map

package/dist/helpers/idempotency.intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.intent.d.ts","sourceRoot":"","sources":["../../src/helpers/idempotency.intent.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,gDAAgD,CAAC;AAEjG,MAAM,MAAM,wBAAwB,GAAG,IAAI,CACzC,0BAA0B,EAC1B,YAAY,CACb,GACC,CACI;IACE,UAAU,EAAE,WAAW,CAAC,0BAA0B,CAAC,YAAY,CAAC,CAAC,CAAC;IAClE,gBAAgB,CAAC,EAAE,KAAK,CAAC;CAC1B,GACD;IAAE,gBAAgB,EAAE,IAAI,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAA;CAAE,CACjD,CAAC;AAEJ;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,wBAAwB,GAChC,qBAAqB,CAAC,mBAAmB,EAAE,0BAA0B,CAAC,CAGxE"}

package/dist/helpers/idempotency.intent.js

@@ -0,0 +1,26 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { IdempotencyBehavior } from '../idempotency.behavior.js';
+/**
+ * Returns an idempotency behavior entry for `pipeline.wrap()` or `createPipeline({ globalBehaviors })`.
+ * @param options A key factory and idempotency options, or `inheritModuleKey: true`
+ * when the behavior's constructor defaults supply the key factory. The inheritance marker is not
+ * forwarded to the behavior and does not validate module configuration.
+ * @returns The behavior class and options tuple.
+ * Keys must distinguish operations and any tenant/principal scope that changes
+ * the authorized response; a shared key can replay another caller's response.
+ * @example
+ * ```ts
+ * export const createUser = pipeline.wrap(
+ *   { name: 'createUser', kind: 'command' },
+ *   idempotent({ keyFactory: createUserKey, ttl: 86_400_000 }),
+ * )(users.create);
+ *
+ * // The key factory comes from the IdempotencyBehavior constructor defaults.
+ * const entry = idempotent({ inheritModuleKey: true });
+ * ```
+ */
+export function idempotent(options) {
+    const { inheritModuleKey: _inheritModuleKey, ...behaviorOptions } = options;
+    return [IdempotencyBehavior, behaviorOptions];
+}
+//# sourceMappingURL=idempotency.intent.js.map

package/dist/helpers/idempotency.intent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.intent.js","sourceRoot":"","sources":["../../src/helpers/idempotency.intent.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAGtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAejE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,UAAU,CACxB,OAAiC;IAEjC,MAAM,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,GAAG,eAAe,EAAE,GAAG,OAAO,CAAC;IAC5E,OAAO,CAAC,mBAAmB,EAAE,eAAe,CAAC,CAAC;AAChD,CAAC"}

package/dist/helpers/json-snapshot.d.ts

@@ -0,0 +1,6 @@
+import type { IdempotencyRecord, JsonValue } from '../interfaces/idempotency-record.interface.js';
+/** Convert a replay value to the representation shared by durable stores. */
+export declare function toJsonSnapshot(value: unknown): JsonValue | undefined;
+/** Clone a record with the same JSON boundary used by Redis and Postgres. */
+export declare function cloneIdempotencyRecord(record: IdempotencyRecord): IdempotencyRecord;
+//# sourceMappingURL=json-snapshot.d.ts.map

package/dist/helpers/json-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-snapshot.d.ts","sourceRoot":"","sources":["../../src/helpers/json-snapshot.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,iBAAiB,EACjB,SAAS,EACV,MAAM,+CAA+C,CAAC;AAEvD,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAUpE;AAED,6EAA6E;AAC7E,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,iBAAiB,GACxB,iBAAiB,CAQnB"}

package/dist/helpers/json-snapshot.js

@@ -0,0 +1,23 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { toStrictJsonValue } from '@cqrs-ddd/safe-stringify';
+/** Convert a replay value to the representation shared by durable stores. */
+export function toJsonSnapshot(value) {
+    if (value === undefined)
+        return undefined;
+    try {
+        return toStrictJsonValue(value);
+    }
+    catch {
+        throw new TypeError('Idempotency responses must be acyclic JSON-serializable values.');
+    }
+}
+/** Clone a record with the same JSON boundary used by Redis and Postgres. */
+export function cloneIdempotencyRecord(record) {
+    try {
+        return JSON.parse(JSON.stringify(record));
+    }
+    catch {
+        throw new TypeError('Idempotency records must contain only acyclic JSON-serializable values.');
+    }
+}
+//# sourceMappingURL=json-snapshot.js.map

package/dist/helpers/json-snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-snapshot.js","sourceRoot":"","sources":["../../src/helpers/json-snapshot.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAM7D,6EAA6E;AAC7E,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAE1C,IAAI,CAAC;QACH,OAAO,iBAAiB,CAAC,KAAK,CAAc,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,SAAS,CACjB,iEAAiE,CAClE,CAAC;IACJ,CAAC;AACH,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,sBAAsB,CACpC,MAAyB;IAEzB,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAsB,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,SAAS,CACjB,yEAAyE,CAC1E,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/helpers/partitioned-key.d.ts

@@ -0,0 +1,96 @@
+import { type IPipelineContext, type TenantPartitionOptions } from '@cqrs-ddd/pipeline';
+import type { IdempotencyKeyFactory } from '../interfaces/idempotency-options.interface.js';
+/**
+ * Resolves the principal performing an operation.
+ *
+ * Return one identifier, or several segments when the identity has more than one
+ * dimension — for example `['service', clientId]`, so a service and a user that
+ * share an id string never share a namespace. Read it from authenticated context,
+ * never from a request body field the caller controls.
+ */
+export type IdempotencyPrincipalFactory = (context: IPipelineContext) => string | readonly string[] | undefined;
+/**
+ * Resolves the identity of one operation within the principal's namespace: a
+ * client-supplied `Idempotency-Key`, or a business identifier the operation is
+ * deduplicated by.
+ */
+export type IdempotencyOperationFactory = (context: IPipelineContext) => string | undefined;
+/** Options for {@link createPartitionedIdempotencyKeyFactory}. */
+export interface PartitionedIdempotencyKeyOptions extends TenantPartitionOptions {
+    /** Who performs the operation. Required, and never defaulted. */
+    principal: IdempotencyPrincipalFactory;
+    /** Which operation this is, within that principal's namespace. */
+    operation: IdempotencyOperationFactory;
+    /**
+     * Name of the operation kind. Defaults to `context.requestName`; pass a stable
+     * value when the request class may be renamed without the operation changing.
+     */
+    action?: string;
+    /**
+     * Leading namespace segment. Change it only deliberately: a new namespace
+     * abandons every claim stored under the old one, so a completed operation can
+     * execute again until those records expire.
+     */
+    version?: string;
+    /**
+     * Behavior when the operation identity is absent.
+     *
+     * - `throw` — the request is rejected.
+     * - `skip` — no key is produced, so the request runs without deduplication.
+     *   Use this for an optional client `Idempotency-Key` header.
+     *
+     * A missing principal always throws: there is no safe namespace to fall back to.
+     *
+     * @default 'throw'
+     */
+    onMissingOperation?: 'throw' | 'skip';
+}
+/**
+ * Creates an {@link IdempotencyKeyFactory} whose keys partition by tenant,
+ * principal and operation, and fail closed when any of them is missing.
+ *
+ * Segments are escaped and joined with `joinKeySegments` from
+ * `@cqrs-ddd/safe-stringify`, so values
+ * containing the separator — email addresses, external subject claims, composite
+ * ids — cannot make two different operations collide on one key.
+ *
+ * The key is an operation identity. Do not fold permissions into it: a key that
+ * changed with permissions would let the same side effect run again. Bind replay
+ * to the caller's authorization with `replayScopeFactory` instead.
+ *
+ * The produced key is
+ * `[version:]<tenantId>:<principal…>:<action>:<operation>`, with the tenant
+ * segment omitted when `includeTenant` is `false`.
+ *
+ * @throws {MissingIdempotencyPartitionError} When the tenant or principal is
+ * absent, or the operation is absent and `onMissingOperation` is `'throw'`.
+ *
+ * @example Per authenticated principal, deduplicated by a business identifier
+ * ```ts
+ * const createOrderKey = createPartitionedIdempotencyKeyFactory({
+ *   version: 'v1',
+ *   action: 'order.create',
+ *   principal: (ctx) => ['user', ctx.items.get(CURRENT_USER_ID) as string],
+ *   operation: (ctx) => (ctx.request as CreateOrderCommand).externalRef,
+ * });
+ *
+ * class CreateOrderHandler {
+ *   @pipeline.wrap({ kind: 'command' }, [IdempotencyBehavior, { keyFactory: createOrderKey }])
+ *   async handle(command: CreateOrderCommand) {}
+ * }
+ * ```
+ *
+ * @example Optional client-supplied Idempotency-Key
+ * ```ts
+ * createPartitionedIdempotencyKeyFactory({
+ *   principal: readUserId,
+ *   operation: (ctx) => (ctx.request as PayCommand).idempotencyKey,
+ *   onMissingOperation: 'skip',
+ * });
+ * ```
+ */
+export declare function createPartitionedIdempotencyKeyFactory(options: PartitionedIdempotencyKeyOptions & {
+    onMissingOperation?: 'throw';
+}): (context: IPipelineContext) => string;
+export declare function createPartitionedIdempotencyKeyFactory(options: PartitionedIdempotencyKeyOptions): IdempotencyKeyFactory;
+//# sourceMappingURL=partitioned-key.d.ts.map

package/dist/helpers/partitioned-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"partitioned-key.d.ts","sourceRoot":"","sources":["../../src/helpers/partitioned-key.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAE5B,MAAM,oBAAoB,CAAC;AAG5B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gDAAgD,CAAC;AAE5F;;;;;;;GAOG;AACH,MAAM,MAAM,2BAA2B,GAAG,CACxC,OAAO,EAAE,gBAAgB,KACtB,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;AAE5C;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,GAAG,CACxC,OAAO,EAAE,gBAAgB,KACtB,MAAM,GAAG,SAAS,CAAC;AAExB,kEAAkE;AAClE,MAAM,WAAW,gCACf,SAAQ,sBAAsB;IAC9B,iEAAiE;IACjE,SAAS,EAAE,2BAA2B,CAAC;IAEvC,kEAAkE;IAClE,SAAS,EAAE,2BAA2B,CAAC;IAEvC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;;;;;;OAUG;IACH,kBAAkB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,sCAAsC,CACpD,OAAO,EAAE,gCAAgC,GAAG;IAAE,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAAE,GAC3E,CAAC,OAAO,EAAE,gBAAgB,KAAK,MAAM,CAAC;AACzC,wBAAgB,sCAAsC,CACpD,OAAO,EAAE,gCAAgC,GACxC,qBAAqB,CAAC"}