@cosmicdrift/kumiko-framework 0.163.3 → 0.164.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.163.3",
+  "version": "0.164.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -182,7 +182,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.163.3",
+    "@cosmicdrift/kumiko-types": "0.164.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.12.18",
@@ -198,7 +198,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.163.3",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.164.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/db/pg-error.ts

@@ -3,7 +3,7 @@
 // unwrap both layers so callers don't have to know which layer produced the
 // error. Used by the event-store to distinguish a unique-violation on the
 // aggregate-version index (optimistic-concurrency conflict) from the one on
-// the request-id idempotency index (replay signal).
+// the idempotency-key index (caller-side replay signal).
 
 export type PgErrorInfo = {
   readonly code: string | undefined;

package/src/db/queries/event-store.ts

@@ -6,6 +6,20 @@ export async function notifyPgChannel(db: AnyDb, channel: string): Promise<void>
   await asRawClient(db).unsafe(`SELECT pg_notify($1, '')`, [channel]);
 }
 
+// Tenant-scoped partial unique index over metadata.idempotencyKey.
+// Expression index straight on the jsonb column — no dedicated key column,
+// so it needs no INSERT-path change and covers admin-api's raw appends too
+// (same metadata jsonb). CREATE ... IF NOT EXISTS makes this safe to call
+// on every boot, same "ensure" pattern as ensureSnapshotVersionColumn: heals
+// installs that predate the index without a table rebuild.
+export async function ensureIdempotencyKeyIndex(db: AnyDb): Promise<void> {
+  await asRawClient(db).unsafe(
+    `CREATE UNIQUE INDEX IF NOT EXISTS "events_idempotency_uq" ON "kumiko_events" ` +
+      `("tenant_id", (("metadata"->>'idempotencyKey'))) ` +
+      `WHERE "metadata"->>'idempotencyKey' IS NOT NULL`,
+  );
+}
+
 export type SubsequentEventInsertParams = {
   readonly aggregateId: string;
   readonly aggregateType: string;

package/src/event-store/__tests__/event-store.integration.test.ts

@@ -6,6 +6,7 @@ import { generateId as uuid } from "../../utils";
 import {
   append,
   createEventsTable,
+  IdempotentAppendConflictError,
   loadAggregate,
   loadAggregateAsOf,
   loadAllEventsByType,
@@ -93,6 +94,129 @@ describe("event-store: append + load", () => {
   });
 });
 
+describe("event-store: idempotency-key conflict", () => {
+  test("second append with a reused idempotencyKey (new aggregate+version) throws IdempotentAppendConflictError", async () => {
+    const first = uuid();
+    const second = uuid();
+    const key = uuid();
+
+    await append(testDb.db, {
+      aggregateId: first,
+      aggregateType: "task",
+      tenantId: tenantA,
+      expectedVersion: 0,
+      type: "task.created",
+      payload: { title: "Orig" },
+      metadata: { userId: userA, idempotencyKey: key },
+    });
+
+    // A retried command that re-runs after the Redis idempotency guard
+    // missed its window: different aggregate, fresh expectedVersion=0 — the
+    // aggregate-version unique index has nothing to say about this pair, so
+    // only the idempotency-key index catches the duplicate.
+    await expect(
+      append(testDb.db, {
+        aggregateId: second,
+        aggregateType: "task",
+        tenantId: tenantA,
+        expectedVersion: 0,
+        type: "task.created",
+        payload: { title: "Retry" },
+        metadata: { userId: userA, idempotencyKey: key },
+      }),
+    ).rejects.toThrow(IdempotentAppendConflictError);
+
+    const events = await loadAggregate(testDb.db, second, tenantA);
+    expect(events).toHaveLength(0);
+  });
+
+  test("subsequent-event append (expectedVersion > 0) also enforces the idempotency key", async () => {
+    const aggregateId = uuid();
+    const key = uuid();
+
+    await append(testDb.db, {
+      aggregateId,
+      aggregateType: "task",
+      tenantId: tenantA,
+      expectedVersion: 0,
+      type: "task.created",
+      payload: { title: "Orig" },
+      metadata: { userId: userA },
+    });
+
+    await append(testDb.db, {
+      aggregateId,
+      aggregateType: "task",
+      tenantId: tenantA,
+      expectedVersion: 1,
+      type: "task.updated",
+      payload: { title: "V2" },
+      metadata: { userId: userA, idempotencyKey: key },
+    });
+
+    // Retry of the v2 update: goes through insertSubsequentEventRow's raw
+    // INSERT ... SELECT ... WHERE EXISTS path, not insertFirstEvent — the
+    // idempotency index must catch it there too.
+    await expect(
+      append(testDb.db, {
+        aggregateId,
+        aggregateType: "task",
+        tenantId: tenantA,
+        expectedVersion: 2,
+        type: "task.updated",
+        payload: { title: "V3-retry" },
+        metadata: { userId: userA, idempotencyKey: key },
+      }),
+    ).rejects.toThrow(IdempotentAppendConflictError);
+
+    const events = await loadAggregate(testDb.db, aggregateId, tenantA);
+    expect(events).toHaveLength(2);
+  });
+
+  test("same idempotencyKey on a different tenant does not conflict", async () => {
+    const key = uuid();
+
+    const a = await append(testDb.db, {
+      aggregateId: uuid(),
+      aggregateType: "task",
+      tenantId: tenantA,
+      expectedVersion: 0,
+      type: "task.created",
+      payload: {},
+      metadata: { userId: userA, idempotencyKey: key },
+    });
+    const b = await append(testDb.db, {
+      aggregateId: uuid(),
+      aggregateType: "task",
+      tenantId: tenantB,
+      expectedVersion: 0,
+      type: "task.created",
+      payload: {},
+      metadata: { userId: userA, idempotencyKey: key },
+    });
+
+    expect(a.version).toBe(1);
+    expect(b.version).toBe(1);
+  });
+
+  test("omitting idempotencyKey allows unlimited appends, unchanged from before", async () => {
+    const events = await Promise.all(
+      Array.from({ length: 3 }, () =>
+        append(testDb.db, {
+          aggregateId: uuid(),
+          aggregateType: "task",
+          tenantId: tenantA,
+          expectedVersion: 0,
+          type: "task.created",
+          payload: {},
+          metadata: { userId: userA },
+        }),
+      ),
+    );
+    expect(events).toHaveLength(3);
+  });
+});
+
 describe("event-store: optimistic concurrency", () => {
   test("wrong expectedVersion throws VersionConflictError (no write)", async () => {
     const aggregateId = uuid();

package/src/event-store/event-store.ts

@@ -1,7 +1,7 @@
 import type { EventMetadata, StoredEvent } from "@cosmicdrift/kumiko-types/event-store-types";
 import { encryptEventPayloadPii } from "../crypto/event-pii";
 import type { DbRunner } from "../db";
-import { isUniqueViolation } from "../db/pg-error";
+import { constraintOf, isUniqueViolation } from "../db/pg-error";
 import {
   insertSubsequentEventRow,
   notifyPgChannel,
@@ -13,7 +13,7 @@ import {
 import { insertOne, selectMany } from "../db/query";
 import type { TenantId } from "../engine/types";
 import { isStreamArchived } from "./archive";
-import { VersionConflictError } from "./errors";
+import { IdempotentAppendConflictError, VersionConflictError } from "./errors";
 import { eventsTable } from "./events-schema";
 import { toStoredEvent } from "./row-to-stored-event";
 
@@ -91,10 +91,15 @@ export async function append(db: DbRunner, event: EventToAppend): Promise<Stored
     return buildStoredEvent(toStore, newVersion, eventVersion, row);
   } catch (e) {
     if (isUniqueViolation(e)) {
-      // Only constraint left on the events table: events_aggregate_version_uq
-      // on (tenant_id, aggregate_id, version). A unique violation here always
-      // means a concurrent writer in the same tenant won the race to the
-      // next version — retry-able conflict.
+      // Two unique constraints on this table: events_aggregate_version_uq
+      // (tenant_id, aggregate_id, version) — a concurrent writer won the
+      // race to the next version — and events_idempotency_uq (tenant_id,
+      // metadata->>'idempotencyKey') — the caller reused an idempotency key.
+      // constraintOf() tells them apart; unknown/renamed constraint falls
+      // back to VersionConflictError, the pre-existing behaviour.
+      if (constraintOf(e) === "events_idempotency_uq" && event.metadata.idempotencyKey) {
+        throw new IdempotentAppendConflictError(event.tenantId, event.metadata.idempotencyKey);
+      }
       throw new VersionConflictError(event.aggregateId, event.expectedVersion);
     }
     throw e;

package/src/event-store/events-schema.ts

@@ -12,6 +12,7 @@ import {
   uniqueIndex,
   uuid,
 } from "../db/dialect";
+import { ensureIdempotencyKeyIndex } from "../db/queries/event-store";
 import { unsafePushTables } from "../stack";
 import { createArchivedStreamsTable } from "./archive";
 import { createSnapshotsTable } from "./snapshot";
@@ -22,9 +23,11 @@ import type { EventMetadata } from "./types";
 // INSERT ... SELECT ... WHERE EXISTS isn't ergonomic in the typed builder.
 //
 // HTTP-level retry idempotency is handled by pipeline/idempotency.ts
-// (Redis-backed check + cached-response replay). The event-store itself
-// imposes no idempotency index — a single HTTP request may write N events
-// freely, metadata.requestId is purely a trace marker.
+// (Redis-backed check + cached-response replay); metadata.requestId is
+// purely a trace marker (no uniqueness constraint — one request may write
+// N events). Callers that need a hard per-event guarantee as a second line
+// of defense set metadata.idempotencyKey, enforced by the tenant-scoped
+// partial unique index ensureIdempotencyKeyIndex() creates below.
 
 export const eventsTable = pgTable(
   "kumiko_events",
@@ -77,6 +80,10 @@ export async function createEventsTable(db: DbConnection): Promise<void> {
   if (!(await tableExists(db, "public.kumiko_events"))) {
     await unsafePushTables(db, { kumikoEvents: eventsTable });
   }
+  // Runs unconditionally (both fresh + already-existing table) so installs
+  // that predate the idempotency-key index get healed the same way
+  // ensureSnapshotVersionColumn heals kumiko_snapshots.
+  await ensureIdempotencyKeyIndex(db);
   await createArchivedStreamsTable(db);
   await createSnapshotsTable(db);
 }

package/src/event-store/index.ts

@@ -12,7 +12,7 @@ export {
   isStreamArchived,
   restoreStream,
 } from "./archive";
-export { ArchivedStreamError, VersionConflictError } from "./errors";
+export { ArchivedStreamError, IdempotentAppendConflictError, VersionConflictError } from "./errors";
 export {
   append,
   EVENTS_PUBSUB_CHANNEL,