fix(core): guard ksuid random source and address review nits

Fall back to node:crypto webcrypto when globalThis.crypto is unavailable
(Node 18.20), share the ksuid length constant with the residency
classifier, and tighten the ksuid/residency tests.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: d-cs

packages/core/src/v3/isomorphic/friendlyId.test.ts

@@ -50,16 +50,6 @@ describe("RunId + WaitpointId mint cuid by default; ksuid via generateKsuidId",
 });
 
 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", () => {
@@ -68,7 +58,7 @@ describe("generateKsuidId is a genuine KSUID (decodable timestamp, time-ordered)
 
   it("carries a decodable timestamp within a few seconds of now", () => {
     const before = Math.floor(Date.now() / 1000);
-    const ts = decodeTimestamp(generateKsuidId());
+    const { timestampSeconds: ts } = decodeKsuid(generateKsuidId());
     expect(ts).toBeGreaterThanOrEqual(before - 2);
     expect(ts).toBeLessThanOrEqual(Math.floor(Date.now() / 1000) + 2);
   });
@@ -85,7 +75,7 @@ describe("generateKsuidId is a genuine KSUID (decodable timestamp, time-ordered)
 
   it("is unique across many mints in the same second", () => {
     const n = 1000;
-    expect(new Set(Array.from({ length: n }, generateKsuidId)).size).toBe(n);
+    expect(new Set(Array.from({ length: n }, () => generateKsuidId())).size).toBe(n);
   });
 });
 

packages/core/src/v3/isomorphic/friendlyId.ts

@@ -12,9 +12,35 @@ 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;
+export const KSUID_STRING_LENGTH = 27;
 const BASE62_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
 
+// globalThis.crypto is absent on Node 18.20 (a supported engine) without a flag, so fall back to
+// node:crypto's webcrypto, loaded only when the global is missing to stay isomorphic.
+type RandomFiller = (array: Uint8Array) => void;
+
+function resolveGetRandomValues(): RandomFiller {
+  const globalCrypto = (globalThis as { crypto?: Crypto }).crypto;
+  if (globalCrypto?.getRandomValues) {
+    return (array) => globalCrypto.getRandomValues(array);
+  }
+  const webcrypto = loadNodeWebCrypto();
+  if (webcrypto?.getRandomValues) {
+    return (array) => webcrypto.getRandomValues(array);
+  }
+  throw new Error("No Web Crypto getRandomValues implementation available");
+}
+
+function loadNodeWebCrypto(): Crypto | undefined {
+  try {
+    return (typeof require === "function" ? require("node:crypto") : undefined)?.webcrypto;
+  } catch {
+    return undefined;
+  }
+}
+
+const getRandomValues: RandomFiller = resolveGetRandomValues();
+
 /** 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);
@@ -67,18 +93,18 @@ export function generateKsuidId(payload?: Uint8Array): string {
     bytes.set(payload, KSUID_TIMESTAMP_BYTES);
   }
   if (reserved < KSUID_PAYLOAD_BYTES) {
-    globalThis.crypto.getRandomValues(bytes.subarray(KSUID_TIMESTAMP_BYTES + reserved));
+    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 {
+export type DecodedKsuid = {
   timestampSeconds: number;
   timestamp: Date;
   payload: Uint8Array;
-}
+};
 
 /**
  * Decode a KSUID body (or a `prefix_<body>` friendly id) into its timestamp + 16-byte payload.

packages/core/src/v3/isomorphic/runOpsResidency.test.ts

@@ -43,6 +43,7 @@ describe("ownerEngine — residency classifier", () => {
   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);
+      expect(isClassifiable(bad)).toBe(false);
     }
   });
 

packages/core/src/v3/isomorphic/runOpsResidency.ts

@@ -1,3 +1,5 @@
+import { KSUID_STRING_LENGTH } from "./friendlyId.js";
+
 /** The two run-ops stores a run/waitpoint can reside in. */
 export type Residency = "LEGACY" | "NEW";
 
@@ -7,7 +9,7 @@ export type ResidencyKind = "cuid" | "ksuid";
 /** @bugsnag/cuid emits 25-char ids (cuid path, flag OFF). */
 export const CUID_LENGTH = 25;
 /** KSUID / nanoid-27 emits 27-char ids (ksuid path, flag ON). */
-export const KSUID_LENGTH = 27;
+export const KSUID_LENGTH = KSUID_STRING_LENGTH;
 
 /** Thrown when an id length matches neither the cuid nor the ksuid margin. */
 export class UnclassifiableRunId extends Error {