@cosmicdrift/kumiko-framework 0.270.0 → 0.273.0

package/src/utils/__tests__/ids.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { generateId } from "../ids";
+import { generateDeterministicId, generateId } from "../ids";
 
 // generateId is the row/stream/correlation ID source. The callers rely on
 // it being a UUIDv7 (time-sortable → dense B-Tree indexes), not a v4 — a
@@ -22,3 +22,31 @@ describe("generateId", () => {
     expect(new Set(ids).size).toBe(ids.length);
   });
 });
+
+describe("generateDeterministicId", () => {
+  test("returns a well-formed lowercase UUID", () => {
+    expect(generateDeterministicId("ledger:schedule", "contract-1")).toMatch(UUID_RX);
+  });
+
+  test("is UUID version 5 (content-addressed, not v7)", () => {
+    expect(generateDeterministicId("ledger:schedule", "contract-1")[14]).toBe("5");
+  });
+
+  test("is deterministic: same namespace + key always yields the same id", () => {
+    const a = generateDeterministicId("ledger:schedule", "contract-1");
+    const b = generateDeterministicId("ledger:schedule", "contract-1");
+    expect(a).toBe(b);
+  });
+
+  test("differs when the key changes", () => {
+    const a = generateDeterministicId("ledger:schedule", "contract-1");
+    const b = generateDeterministicId("ledger:schedule", "contract-2");
+    expect(a).not.toBe(b);
+  });
+
+  test("differs when the namespace changes for the same key", () => {
+    const a = generateDeterministicId("ledger:schedule", "contract-1");
+    const b = generateDeterministicId("ledger:transaction", "contract-1");
+    expect(a).not.toBe(b);
+  });
+});

package/src/utils/ids.ts

@@ -1,4 +1,4 @@
-import { v7 } from "uuid";
+import { v5, v7 } from "uuid";
 
 // Non-secret identifiers for DB rows, event streams, correlation/request
 // IDs, SSE connections, distributed locks. UUIDv7: first 48 bits are a
@@ -15,3 +15,12 @@ import { v7 } from "uuid";
 export function generateId(): string {
   return v7();
 }
+
+// Derived from a DNS name (RFC 4122 §4.3) so the namespace is reproducible, not a hand-picked constant.
+const DETERMINISTIC_ID_NAMESPACE = v5("kumiko.rocks", v5.DNS);
+
+// Same (namespace, key) → same id, so a redelivered event hits the same row. Ids are
+// unique per table, not per tenant: fold the tenant id into `key` or tenants collide.
+export function generateDeterministicId(namespace: string, key: string): string {
+  return v5(`${namespace}:${key}`, DETERMINISTIC_ID_NAMESPACE);
+}

package/src/utils/index.ts

@@ -2,7 +2,7 @@ export { assertUnreachable } from "./assert";
 export { toSnakeCase } from "./case";
 export { compareByCodepoint } from "./compare";
 export { readPositiveIntEnv } from "./env-parse";
-export { generateId } from "./ids";
+export { generateDeterministicId, generateId } from "./ids";
 export { isPlainObject } from "./is-plain-object";
 export { parseStringArrayJson } from "./parse-string-array-json";
 export { parseJsonOrThrow, parseJsonSafe, stringifyJson } from "./safe-json";