feat(run-ops): core residency classifier + ksuid mint primitives

d-cs · claude · d-cs · commit eaf82d38ab65 · 2026-07-02T09:44:34.000+01:00
Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/packages/core/src/v3/isomorphic/friendlyId.test.ts b/packages/core/src/v3/isomorphic/friendlyId.test.ts
@@ -0,0 +1,144 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  RunId,
+  WaitpointId,
+  SnapshotId,
+  QueueId,
+  setKsuidMintEnabled,
+  isKsuidMintEnabled,
+  generateKsuidId,
+  decodeKsuid,
+  KSUID_PAYLOAD_BYTES,
+} from "./friendlyId.js";
+
+const CUID_LEN = 25;
+const KSUID_LEN = 27;
+
+afterEach(() => setKsuidMintEnabled(false)); // never leak flag state across tests
+
+describe("KSUID mint (flag-gated) for RunId + WaitpointId", () => {
+  it("flag OFF: run + waitpoint mint cuid (25) and round-trip", () => {
+    setKsuidMintEnabled(false);
+    expect(isKsuidMintEnabled()).toBe(false);
+    for (const util of [RunId, WaitpointId]) {
+      const { id, friendlyId } = util.generate();
+      expect(id.length).toBe(CUID_LEN);
+      expect(util.fromFriendlyId(friendlyId)).toBe(id);
+      expect(util.toId(friendlyId)).toBe(id);
+      expect(util.toId(id)).toBe(id);
+      expect(util.toFriendlyId(id)).toBe(friendlyId);
+    }
+  });
+
+  it("flag ON: run + waitpoint mint 27-char and round-trip", () => {
+    setKsuidMintEnabled(true);
+    expect(isKsuidMintEnabled()).toBe(true);
+    for (const util of [RunId, WaitpointId]) {
+      const { id, friendlyId } = util.generate();
+      expect(id.length).toBe(KSUID_LEN);
+      expect(util.fromFriendlyId(friendlyId)).toBe(id);
+      expect(util.toId(friendlyId)).toBe(id);
+      expect(util.toId(id)).toBe(id);
+      expect(util.toFriendlyId(id)).toBe(friendlyId);
+    }
+  });
+
+  it("flag ON: SnapshotId stays cuid (25) — never 27-char", () => {
+    setKsuidMintEnabled(true);
+    const { id } = SnapshotId.generate();
+    expect(id.length).toBe(CUID_LEN);
+  });
+
+  it("flag ON: a non-run/waitpoint entity stays cuid (25)", () => {
+    setKsuidMintEnabled(true);
+    expect(QueueId.generate().id.length).toBe(CUID_LEN);
+  });
+
+  it("disjoint lengths: 27 (new) vs 25 (cuid) — the classifier margin", () => {
+    setKsuidMintEnabled(true);
+    expect(RunId.generate().id.length).not.toBe(SnapshotId.generate().id.length);
+  });
+
+  it("generateKsuidId() is directly callable, independent of the flag", () => {
+    setKsuidMintEnabled(false); // must NOT be gated behind the global flag
+    expect(generateKsuidId().length).toBe(KSUID_LEN);
+  });
+});
+
+describe("generateKsuidId is a genuine KSUID (decodable timestamp, time-ordered)", () => {
+  const BASE62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+  const KSUID_EPOCH = 1_400_000_000;
+
+  // Decode the 27-char base62 body back to the 4-byte timestamp prefix (unix seconds).
+  function decodeTimestamp(id: string): number {
+    let n = 0n;
+    for (const ch of id) n = n * 62n + BigInt(BASE62.indexOf(ch));
+    return Number(n >> 128n) + KSUID_EPOCH; // top 4 of the 20 bytes
+  }
+
+  afterEach(() => vi.useRealTimers());
+
+  it("is exactly 27 base62 chars", () => {
+    expect(generateKsuidId()).toMatch(/^[0-9A-Za-z]{27}$/);
+  });
+
+  it("carries a decodable timestamp within a few seconds of now", () => {
+    const before = Math.floor(Date.now() / 1000);
+    const ts = decodeTimestamp(generateKsuidId());
+    expect(ts).toBeGreaterThanOrEqual(before - 2);
+    expect(ts).toBeLessThanOrEqual(Math.floor(Date.now() / 1000) + 2);
+  });
+
+  it("is k-sortable: ids from later seconds sort lexicographically after earlier ones", () => {
+    vi.useFakeTimers();
+    const ids: string[] = [];
+    for (const t of ["2026-01-01T00:00:00Z", "2026-01-01T00:05:00Z", "2026-09-01T12:00:00Z"]) {
+      vi.setSystemTime(new Date(t));
+      ids.push(generateKsuidId());
+    }
+    expect([...ids].sort()).toEqual(ids);
+  });
+
+  it("is unique across many mints in the same second", () => {
+    const n = 1000;
+    expect(new Set(Array.from({ length: n }, generateKsuidId)).size).toBe(n);
+  });
+});
+
+describe("KSUID payload encode/decode (foundation primitive)", () => {
+  it("round-trips a full 16-byte payload exactly", () => {
+    const payload = new Uint8Array(KSUID_PAYLOAD_BYTES).map((_, i) => (i * 17 + 1) & 0xff);
+    const { payload: decoded } = decodeKsuid(generateKsuidId(payload));
+    expect(Array.from(decoded)).toEqual(Array.from(payload));
+  });
+
+  it("preserves a partial payload prefix and keeps the remainder for entropy", () => {
+    const meta = new Uint8Array([9, 8, 7, 6]);
+    const { payload } = decodeKsuid(generateKsuidId(meta));
+    expect(Array.from(payload.slice(0, 4))).toEqual([9, 8, 7, 6]);
+    expect(payload.length).toBe(KSUID_PAYLOAD_BYTES);
+  });
+
+  it("still carries a decodable timestamp when a payload is embedded", () => {
+    const before = Math.floor(Date.now() / 1000);
+    const { timestampSeconds } = decodeKsuid(generateKsuidId(new Uint8Array([1, 2, 3])));
+    expect(timestampSeconds).toBeGreaterThanOrEqual(before - 2);
+    expect(timestampSeconds).toBeLessThanOrEqual(Math.floor(Date.now() / 1000) + 2);
+  });
+
+  it("stays 27 chars with a full payload and decodes through a friendlyId prefix", () => {
+    const id = generateKsuidId(new Uint8Array(KSUID_PAYLOAD_BYTES).fill(0xab));
+    expect(id).toMatch(/^[0-9A-Za-z]{27}$/);
+    expect(Array.from(decodeKsuid(`run_${id}`).payload)).toEqual(
+      new Array(KSUID_PAYLOAD_BYTES).fill(0xab)
+    );
+  });
+
+  it("throws if the payload exceeds the 16-byte budget", () => {
+    expect(() => generateKsuidId(new Uint8Array(KSUID_PAYLOAD_BYTES + 1))).toThrow();
+  });
+
+  it("decodeKsuid rejects a body that is not 27 base62 chars", () => {
+    expect(() => decodeKsuid("run_tooShort")).toThrow();
+  });
+});
diff --git a/packages/core/src/v3/isomorphic/friendlyId.ts b/packages/core/src/v3/isomorphic/friendlyId.ts
@@ -7,7 +7,139 @@ export function generateFriendlyId(prefix: string, size?: number) {
   return `${prefix}_${idGenerator(size)}`;
 }
 
-export function generateInternalId() {
+// Injected by the server split-mode bootstrap. Default false =
+// today's behavior (cuid). Isomorphic file: never read process.env here.
+let ksuidMintEnabled = false;
+
+/** Server bootstrap calls this once with isSplitEnabled(). Off by default. */
+export function setKsuidMintEnabled(enabled: boolean): void {
+  ksuidMintEnabled = enabled;
+}
+
+/** Test/diagnostic read-back of the current mint mode. */
+export function isKsuidMintEnabled(): boolean {
+  return ksuidMintEnabled;
+}
+
+// KSUID epoch (2014-05-13T16:53:20Z) — seconds offset applied to the unix timestamp.
+const KSUID_EPOCH = 1_400_000_000;
+const KSUID_TIMESTAMP_BYTES = 4;
+export const KSUID_PAYLOAD_BYTES = 16;
+const KSUID_TOTAL_BYTES = KSUID_TIMESTAMP_BYTES + KSUID_PAYLOAD_BYTES;
+const KSUID_STRING_LENGTH = 27;
+const BASE62_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+
+/** Encode raw bytes as base62 (big-endian), left-padded to the given length. */
+function base62Encode(bytes: Uint8Array, length: number): string {
+  const digits = Array.from(bytes);
+  let result = "";
+
+  while (digits.length > 0) {
+    let remainder = 0;
+    const quotient: number[] = [];
+
+    for (let i = 0; i < digits.length; i++) {
+      const acc = (digits[i] ?? 0) + remainder * 256;
+      const q = Math.floor(acc / 62);
+      remainder = acc % 62;
+
+      if (quotient.length > 0 || q > 0) {
+        quotient.push(q);
+      }
+    }
+
+    result = BASE62_ALPHABET.charAt(remainder) + result;
+    digits.length = 0;
+    digits.push(...quotient);
+  }
+
+  return result.padStart(length, BASE62_ALPHABET.charAt(0));
+}
+
+/**
+ * 27-char, base62, time-ordered KSUID body (length-disjoint from the 25-char cuid): a 4-byte
+ * timestamp (seconds since the KSUID epoch) + a 16-byte payload; ids from different seconds
+ * sort in mint order. Payload defaults to CSPRNG entropy; callers may supply up to
+ * KSUID_PAYLOAD_BYTES metadata bytes (written first, remainder stays random for uniqueness).
+ */
+export function generateKsuidId(payload?: Uint8Array): string {
+  const bytes = new Uint8Array(KSUID_TOTAL_BYTES);
+
+  const timestamp = Math.floor(Date.now() / 1000) - KSUID_EPOCH;
+  bytes[0] = (timestamp >>> 24) & 0xff;
+  bytes[1] = (timestamp >>> 16) & 0xff;
+  bytes[2] = (timestamp >>> 8) & 0xff;
+  bytes[3] = timestamp & 0xff;
+
+  if (payload && payload.length > KSUID_PAYLOAD_BYTES) {
+    throw new Error(
+      `KSUID payload must be at most ${KSUID_PAYLOAD_BYTES} bytes (got ${payload.length})`
+    );
+  }
+  const reserved = payload?.length ?? 0;
+  if (payload && reserved > 0) {
+    bytes.set(payload, KSUID_TIMESTAMP_BYTES);
+  }
+  if (reserved < KSUID_PAYLOAD_BYTES) {
+    globalThis.crypto.getRandomValues(bytes.subarray(KSUID_TIMESTAMP_BYTES + reserved));
+  }
+
+  return base62Encode(bytes, KSUID_STRING_LENGTH);
+}
+
+/** Decoded parts of a KSUID body: its mint timestamp and 16-byte payload. */
+export interface DecodedKsuid {
+  timestampSeconds: number;
+  timestamp: Date;
+  payload: Uint8Array;
+}
+
+/**
+ * Decode a KSUID body (or a `prefix_<body>` friendly id) into its timestamp + 16-byte payload.
+ * The inverse of generateKsuidId's layout. Throws if the body is not 27 base62 chars.
+ */
+export function decodeKsuid(idOrFriendlyId: string): DecodedKsuid {
+  const underscore = idOrFriendlyId.indexOf("_");
+  const body = underscore === -1 ? idOrFriendlyId : idOrFriendlyId.slice(underscore + 1);
+  if (body.length !== KSUID_STRING_LENGTH) {
+    throw new Error(
+      `Not a KSUID body: expected ${KSUID_STRING_LENGTH} base62 chars, got ${body.length}`
+    );
+  }
+
+  let n = 0n;
+  for (const ch of body) {
+    const digit = BASE62_ALPHABET.indexOf(ch);
+    if (digit < 0) {
+      throw new Error(`Invalid base62 character in KSUID body: ${ch}`);
+    }
+    n = n * 62n + BigInt(digit);
+  }
+
+  const bytes = new Uint8Array(KSUID_TOTAL_BYTES);
+  for (let i = KSUID_TOTAL_BYTES - 1; i >= 0; i--) {
+    bytes[i] = Number(n & 0xffn);
+    n >>= 8n;
+  }
+
+  const timestampSeconds =
+    (bytes[0] ?? 0) * 0x1000000 +
+    (bytes[1] ?? 0) * 0x10000 +
+    (bytes[2] ?? 0) * 0x100 +
+    (bytes[3] ?? 0) +
+    KSUID_EPOCH;
+
+  return {
+    timestampSeconds,
+    timestamp: new Date(timestampSeconds * 1000),
+    payload: bytes.slice(KSUID_TIMESTAMP_BYTES),
+  };
+}
+
+export function generateInternalId(useKsuidWhenEnabled = false): string {
+  if (useKsuidWhenEnabled && ksuidMintEnabled) {
+    return generateKsuidId();
+  }
   return cuid();
 }
 
@@ -58,10 +190,13 @@ export function fromFriendlyId(friendlyId: string, expectedEntityName?: string):
 }
 
 export class IdUtil {
-  constructor(private entityName: string) {}
+  constructor(
+    private entityName: string,
+    private ksuidWhenEnabled = false
+  ) {}
 
   generate() {
-    const internalId = generateInternalId();
+    const internalId = generateInternalId(this.ksuidWhenEnabled);
 
     return {
       id: internalId,
@@ -90,9 +225,9 @@ export class IdUtil {
 export const BackgroundWorkerId = new IdUtil("worker");
 export const CheckpointId = new IdUtil("checkpoint");
 export const QueueId = new IdUtil("queue");
-export const RunId = new IdUtil("run");
+export const RunId = new IdUtil("run", true);
 export const SnapshotId = new IdUtil("snapshot");
-export const WaitpointId = new IdUtil("waitpoint");
+export const WaitpointId = new IdUtil("waitpoint", true);
 export const BatchId = new IdUtil("batch");
 export const BulkActionId = new IdUtil("bulk");
 export const AttemptId = new IdUtil("attempt");
diff --git a/packages/core/src/v3/isomorphic/index.ts b/packages/core/src/v3/isomorphic/index.ts
@@ -1,4 +1,5 @@
 export * from "./friendlyId.js";
+export * from "./runOpsResidency.js";
 export * from "./duration.js";
 export * from "./maxDuration.js";
 export * from "./queueName.js";
diff --git a/packages/core/src/v3/isomorphic/runOpsResidency.test.ts b/packages/core/src/v3/isomorphic/runOpsResidency.test.ts
@@ -0,0 +1,68 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { RunId, WaitpointId, SnapshotId, setKsuidMintEnabled } from "./friendlyId.js";
+import {
+  ownerEngine,
+  classifyResidency,
+  classifyKind,
+  isClassifiable,
+  UnclassifiableRunId,
+} from "./runOpsResidency.js";
+
+afterEach(() => setKsuidMintEnabled(false)); // never leak mint-flag state across tests
+
+const SAMPLES = 50_000; // property-scale; CI-fast. (Bump locally toward "millions" for deeper coverage.)
+
+describe("ownerEngine — residency classifier", () => {
+  it("cuid-length ids (mint flag OFF) classify LEGACY, friendly + internal", () => {
+    setKsuidMintEnabled(false);
+    for (const util of [RunId, WaitpointId]) {
+      const { id, friendlyId } = util.generate();
+      expect(ownerEngine(id)).toBe("LEGACY");
+      expect(ownerEngine(friendlyId)).toBe("LEGACY"); // strips run_/waitpoint_ prefix
+      expect(classifyResidency(id)).toBe("LEGACY"); // alias agrees
+      expect(classifyKind(id)).toBe("cuid");
+      expect(isClassifiable(id)).toBe(true);
+    }
+  });
+
+  it("ksuid-length ids (mint flag ON) classify NEW, friendly + internal", () => {
+    setKsuidMintEnabled(true);
+    for (const util of [RunId, WaitpointId]) {
+      const { id, friendlyId } = util.generate();
+      expect(ownerEngine(id)).toBe("NEW");
+      expect(ownerEngine(friendlyId)).toBe("NEW");
+      expect(classifyResidency(id)).toBe("NEW");
+      expect(classifyKind(id)).toBe("ksuid");
+    }
+  });
+
+  it("disjointness: no cuid sample is ever NEW, no ksuid sample is ever LEGACY", () => {
+    for (let i = 0; i < SAMPLES; i++) {
+      setKsuidMintEnabled(false);
+      expect(ownerEngine(RunId.generate().id)).toBe("LEGACY");
+      setKsuidMintEnabled(true);
+      expect(ownerEngine(RunId.generate().id)).toBe("NEW");
+    }
+  });
+
+  it("throws UnclassifiableRunId on malformed lengths (24, 26, 28, empty)", () => {
+    for (const bad of ["", "x".repeat(24), "x".repeat(26), "x".repeat(28), "x".repeat(40)]) {
+      expect(() => ownerEngine(bad)).toThrow(UnclassifiableRunId);
+    }
+  });
+
+  it("error carries the offending value + length for diagnostics", () => {
+    try {
+      ownerEngine("x".repeat(26));
+      throw new Error("should have thrown");
+    } catch (e) {
+      expect(e).toBeInstanceOf(UnclassifiableRunId);
+      expect((e as UnclassifiableRunId).message).toContain("26");
+    }
+  });
+
+  it("SnapshotId (always cuid, even with flag ON) classifies LEGACY — proves snapshot needs no residency key", () => {
+    setKsuidMintEnabled(true);
+    expect(ownerEngine(SnapshotId.generate().id)).toBe("LEGACY");
+  });
+});
diff --git a/packages/core/src/v3/isomorphic/runOpsResidency.ts b/packages/core/src/v3/isomorphic/runOpsResidency.ts

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`export * from "./friendlyId.js";`
	`2`	`+export * from "./runOpsResidency.js";`
`2`	`3`	`export * from "./duration.js";`
`3`	`4`	`export * from "./maxDuration.js";`
`4`	`5`	`export * from "./queueName.js";`