feat(core): flag-gated 27-char mint for RunId + WaitpointId

Adds a flag-gated 27-char id mint for RunId and WaitpointId only, so those
two id types produce length-classifiable residency keys (27-char vs 25-char
cuid) for the run-ops DB split. The mint is OFF by default (preserving
today's cuid behavior exactly) and activates only when the server injects
the split flag via setKsuidMintEnabled. cuid is preserved for SnapshotId
and all other entities, and generateKsuidId is directly callable
independent of the flag.

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

Author: d-cs

.changeset/ksuid-mint-run-waitpoint.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/core": patch
+---
+
+Flag-gated 27-char mint for RunId + WaitpointId (residency key for the run-ops DB split); cuid preserved for all other ids and when the flag is off.

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

@@ -0,0 +1,64 @@
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  RunId,
+  WaitpointId,
+  SnapshotId,
+  QueueId,
+  setKsuidMintEnabled,
+  isKsuidMintEnabled,
+  generateKsuidId,
+} 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 (W1-INF-04 contract), independent of the flag", () => {
+    setKsuidMintEnabled(false); // must NOT be gated behind the global flag
+    expect(generateKsuidId().length).toBe(KSUID_LEN);
+  });
+});

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

@@ -7,7 +7,37 @@ export function generateFriendlyId(prefix: string, size?: number) {
   return `${prefix}_${idGenerator(size)}`;
 }
 
-export function generateInternalId() {
+// Injected by the server split-mode bootstrap (W0-FND-07). 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;
+}
+
+// 27-char fixed-length alphanumeric — length-disjoint from the 25-char cuid.
+// Named "Ksuid" because that is the cross-unit contract name; the default
+// implementation is a 27-char nanoid (no new dependency, fully isomorphic).
+const ksuidIdGenerator = customAlphabet(
+  "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ",
+  27
+);
+
+/** 27-char id — length-disjoint from the 25-char cuid. Always callable (W1-INF-04). */
+export function generateKsuidId(): string {
+  return ksuidIdGenerator();
+}
+
+export function generateInternalId(useKsuidWhenEnabled = false): string {
+  if (useKsuidWhenEnabled && ksuidMintEnabled) {
+    return generateKsuidId();
+  }
   return cuid();
 }
 
@@ -58,10 +88,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 +123,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");