@cosmicdrift/kumiko-types 0.163.2 → 0.164.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.163.2",
+  "version": "0.164.0",
   "description": "Framework-Type-Definitions für Kumiko — FeatureDefinition, BootCheck-Types und die reinen Engine-Types, ohne Runtime-Code. Erlaubt Downstream-Konsumenten, gegen die Type-Contracts zu bauen, ohne das ganze Framework-Package zu importieren.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/src/event-store-errors.ts

@@ -15,6 +15,25 @@ export class VersionConflictError extends Error {
   }
 }
 
+// Thrown when append() collides on the partial unique index over
+// metadata.idempotencyKey (tenant-scoped). Distinct from VersionConflictError:
+// a version conflict means two writers raced the same predecessor; this
+// means the same idempotency key was used twice, which is a caller-side
+// retry that must have already appended once. Callers that set
+// idempotencyKey should treat this as "already applied" rather than retry.
+export class IdempotentAppendConflictError extends Error {
+  public readonly tenantId: string;
+  public readonly idempotencyKey: string;
+  constructor(tenantId: string, idempotencyKey: string) {
+    super(
+      `Idempotency conflict on tenant ${tenantId}: an event with idempotencyKey "${idempotencyKey}" was already appended.`,
+    );
+    this.name = "IdempotentAppendConflictError";
+    this.tenantId = tenantId;
+    this.idempotencyKey = idempotencyKey;
+  }
+}
+
 // Thrown when ctx.appendEvent targets an archived stream. Archived aggregates
 // are read-only — restoreStream() makes them writable again. The archive
 // state is not carried on the events themselves; it lives on the sparse

package/src/event-store-types.ts

@@ -12,6 +12,14 @@ export type EventMetadata = {
   // set to event.id when an MSP-apply runs ctx.appendEvent. Together with
   // correlationId forms a causation DAG across aggregate streams.
   readonly causationId?: string;
+  // Opt-in second line of defense against duplicate appends when the
+  // Redis-backed HTTP idempotency guard (pipeline/idempotency.ts) misses a
+  // retry window (Redis unreachable, TTL race). Callers that want a hard
+  // per-event uniqueness guarantee set a stable key derived from the
+  // triggering request; the event-store enforces it via a tenant-scoped
+  // partial unique index and throws IdempotentAppendConflictError on a
+  // repeat. Unset by default — no uniqueness constraint applies.
+  readonly idempotencyKey?: string;
   // Marten-conform free key/value space for app-specific metadata that
   // doesn't deserve its own EventMetadata field. Examples: A/B-test bucket,
   // feature-flag snapshot, geo-region, client SDK version. Persisted into