fix(run-ops): DNS-safe, sortable base32hex run id (replace base62 KSUID)

The run-ops split minted NEW-store run ids as 27-char base62 KSUIDs. The
supervisor puts the run id in the k8s pod name (runner-<id>), and pod names
must be DNS-1123 labels (lowercase [a-z0-9-]), so uppercase base62 ids made
k8s reject the pod (422) and those runs never launched. .toLowerCase() can't
fix it (base62 folds distinct symbols, colliding ids and destroying sort).

Change the encoding, not the structure: mint a 26-char lowercase base32hex id
(24-char core = 6-byte ms timestamp + 9 CSPRNG bytes, + region char + version
char "1"). Lexicographically time-sortable at ms resolution, DNS-safe from
birth, hyphen-free (so firekeeper's runner-<id>-attempt-N round-trip is
unchanged). The residency discriminator switches from id length to the fixed
version char, so the format can evolve without a hard migration.

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

Author: d-cs

.changeset/olive-bees-repeat.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/core": patch
+---
+
+Change the run-ops run id format from a 27-char base62 KSUID to a 26-char lowercase base32hex id (ms timestamp + CSPRNG core, region char, version char) so run ids are DNS-1123 safe for Kubernetes pod names while staying lexicographically time-sortable

apps/webapp/app/runEngine/concerns/idempotencyResidency.server.test.ts

@@ -18,7 +18,7 @@ function makeDeps(over: Partial<ResolveIdempotencyClientDeps>): ResolveIdempoten
     legacyClient: LEGACY_CLIENT,
     resolveMintKind: async () => "ksuid",
     classify: (id) => {
-      if (id.length === 27) return "NEW";
+      if (id.length === 26 && id[25] === "1") return "NEW";
       if (id.length === 25) return "LEGACY";
       throw new Error(`unclassifiable: ${id.length}`);
     },
@@ -55,7 +55,7 @@ describe("resolveIdempotencyDedupClient", () => {
   });
 
   it("routes a child to the NEW client when the ksuid parent is NEW-resident", async () => {
-    const ksuidParent = RunId.toFriendlyId("a".repeat(27));
+    const ksuidParent = RunId.toFriendlyId("a".repeat(24) + "01");
     const client = await resolveIdempotencyDedupClient(
       { environmentForMint: env, parentRunFriendlyId: ksuidParent },
       makeDeps({ resolveMintKind: async () => "cuid" }) // mint flag must NOT win for a child

apps/webapp/app/runEngine/services/triggerFailedTask.server.ts

@@ -1,6 +1,6 @@
 import type { RunEngine } from "@internal/run-engine";
 import { TaskRunErrorCodes, type TaskRunError } from "@trigger.dev/core/v3";
-import { RunId, generateKsuidId } from "@trigger.dev/core/v3/isomorphic";
+import { RunId, generateRunOpsId } from "@trigger.dev/core/v3/isomorphic";
 import type {
   PrismaClientOrTransaction,
   RuntimeEnvironmentType,
@@ -103,7 +103,7 @@ export class TriggerFailedTaskService {
         });
 
     return mintKind === "ksuid"
-      ? RunId.toFriendlyId(generateKsuidId())
+      ? RunId.toFriendlyId(generateRunOpsId())
       : RunId.generate().friendlyId;
   }
 

apps/webapp/app/runEngine/services/triggerTask.server.ts

@@ -14,7 +14,7 @@ import {
   TriggerTraceContext,
 } from "@trigger.dev/core/v3";
 import {
-  generateKsuidId,
+  generateRunOpsId,
   parseTraceparent,
   RunId,
   serializeTraceparent,
@@ -136,9 +136,14 @@ export class RunEngineTriggerTaskService {
   //  - CHILD run (has a parent): inherit the parent's residency by id-shape, so a
   //    parent and child never split across stores (ksuid parent → ksuid child,
   //    cuid parent → cuid child).
+  // `region` is the caller-requested region (body.options.region). The id is
+  // minted before the worker queue is resolved (the idempotency concern needs
+  // the friendlyId first), so the stamped region char reflects the requested
+  // region — or the default char when the run targets the default region.
   private async mintRunFriendlyId(
     environment: AuthenticatedEnvironment,
-    parentRunFriendlyId?: string
+    parentRunFriendlyId?: string,
+    region?: string
   ): Promise<string> {
     const mintKind = parentRunFriendlyId
       ? resolveInheritedMintKind(parentRunFriendlyId)
@@ -149,7 +154,7 @@ export class RunEngineTriggerTaskService {
         });
 
     return mintKind === "ksuid"
-      ? RunId.toFriendlyId(generateKsuidId())
+      ? RunId.toFriendlyId(generateRunOpsId(region))
       : RunId.generate().friendlyId;
   }
 
@@ -183,7 +188,11 @@ export class RunEngineTriggerTaskService {
           // parent is present, else the environment's setting.
           const runFriendlyId =
             options?.runFriendlyId ??
-            (await this.mintRunFriendlyId(environment, body.options?.parentRunId));
+            (await this.mintRunFriendlyId(
+              environment,
+              body.options?.parentRunId,
+              body.options?.region
+            ));
           const triggerRequest = {
             taskId,
             friendlyId: runFriendlyId,

apps/webapp/app/utils/friendlyId.test.ts

@@ -2,30 +2,31 @@ import { describe, expect, it } from "vitest";
 import {
   BatchId,
   generateFriendlyId,
-  generateKsuidId,
+  generateRunOpsId,
   RunId,
 } from "@trigger.dev/core/v3/isomorphic";
 import { isValidFriendlyId, makeFriendlyIdValidator } from "./friendlyId";
 
 describe("isValidFriendlyId", () => {
   it("accepts every id generation the real generators produce", () => {
-    // nanoid (legacy V1), cuid (run-engine), ksuid (run-ops split)
+    // nanoid (legacy V1), cuid (run-engine), run-ops v1 (run-ops split)
     expect(isValidFriendlyId(generateFriendlyId("run"), "run")).toBe(true);
     expect(isValidFriendlyId(RunId.generate().friendlyId, "run")).toBe(true);
-    expect(isValidFriendlyId(RunId.toFriendlyId(generateKsuidId()), "run")).toBe(true);
+    expect(isValidFriendlyId(RunId.toFriendlyId(generateRunOpsId()), "run")).toBe(true);
 
     expect(isValidFriendlyId(generateFriendlyId("batch"), "batch")).toBe(true);
     expect(isValidFriendlyId(BatchId.generate().friendlyId, "batch")).toBe(true);
-    expect(isValidFriendlyId(BatchId.toFriendlyId(generateKsuidId()), "batch")).toBe(true);
+    expect(isValidFriendlyId(BatchId.toFriendlyId(generateRunOpsId()), "batch")).toBe(true);
   });
 
-  it("accepts each valid body length (21 nanoid, 25 cuid, 27 ksuid)", () => {
+  it("accepts each valid body length (21 nanoid, 25 cuid, 26 run-ops v1, 27 legacy base62)", () => {
     expect(isValidFriendlyId("run_" + "a".repeat(21), "run")).toBe(true);
     expect(isValidFriendlyId("run_" + "a".repeat(25), "run")).toBe(true);
+    expect(isValidFriendlyId("run_" + "a".repeat(26), "run")).toBe(true);
     expect(isValidFriendlyId("run_" + "a".repeat(27), "run")).toBe(true);
   });
 
-  it("accepts mixed-case (uppercase) ksuid bodies", () => {
+  it("accepts mixed-case (uppercase) legacy base62 bodies", () => {
     expect(isValidFriendlyId("run_2ABCdefGHI0123456789jklMN", "run")).toBe(true);
   });
 
@@ -39,7 +40,7 @@ describe("isValidFriendlyId", () => {
   });
 
   it("rejects body lengths that match no generator", () => {
-    for (const len of [0, 20, 22, 24, 26, 28]) {
+    for (const len of [0, 20, 22, 24, 28]) {
       expect(isValidFriendlyId("run_" + "a".repeat(len), "run")).toBe(false);
     }
   });
@@ -64,8 +65,8 @@ describe("makeFriendlyIdValidator", () => {
   it("returns undefined for a valid id of any generation", () => {
     expect(validateRunId(generateFriendlyId("run"))).toBeUndefined();
     expect(validateRunId(RunId.generate().friendlyId)).toBeUndefined();
-    expect(validateRunId(RunId.toFriendlyId(generateKsuidId()))).toBeUndefined();
-    expect(validateBatchId(BatchId.toFriendlyId(generateKsuidId()))).toBeUndefined();
+    expect(validateRunId(RunId.toFriendlyId(generateRunOpsId()))).toBeUndefined();
+    expect(validateBatchId(BatchId.toFriendlyId(generateRunOpsId()))).toBeUndefined();
   });
 
   it("reports a wrong prefix distinctly from a wrong shape", () => {

apps/webapp/app/utils/friendlyId.ts

@@ -1,22 +1,26 @@
-import { CUID_LENGTH, KSUID_LENGTH } from "@trigger.dev/core/v3/isomorphic";
+import { CUID_LENGTH, RUN_OPS_ID_LENGTH } from "@trigger.dev/core/v3/isomorphic";
 
-// The body after `<prefix>_` is a base62 id; three generator lengths remain
-// valid in existing data and must all be accepted: 21 (nanoid), 25 (cuid),
-// 27 (ksuid). cuid/ksuid come from core so this tracks any future change.
+// The body after `<prefix>_` is an alphanumeric id; four generator lengths
+// remain valid in existing data and must all be accepted: 21 (nanoid),
+// 25 (cuid), 26 (run-ops v1 base32hex), 27 (pre-cutover base62, kept so old
+// ids still pass filter validation). cuid/run-ops come from core so this
+// tracks any future change.
 const NANOID_BODY_LENGTH = 21;
+const LEGACY_BASE62_BODY_LENGTH = 27;
 const VALID_BODY_LENGTHS: ReadonlySet<number> = new Set([
   NANOID_BODY_LENGTH,
   CUID_LENGTH,
-  KSUID_LENGTH,
+  RUN_OPS_ID_LENGTH,
+  LEGACY_BASE62_BODY_LENGTH,
 ]);
 
-const BASE62 = /^[0-9A-Za-z]+$/;
+const ALPHANUMERIC = /^[0-9A-Za-z]+$/;
 
 export function isValidFriendlyId(value: string, prefix: string): boolean {
   const marker = `${prefix}_`;
   if (!value.startsWith(marker)) return false;
   const body = value.slice(marker.length);
-  return VALID_BODY_LENGTHS.has(body.length) && BASE62.test(body);
+  return VALID_BODY_LENGTHS.has(body.length) && ALPHANUMERIC.test(body);
 }
 
 export function makeFriendlyIdValidator(prefix: string, label: string) {

apps/webapp/app/v3/runOpsMigration/crossSeamGuard.server.ts

@@ -56,7 +56,6 @@ export function selectStoreForWaitpoint(
 
   const classify = deps?.classify ?? ownerEngine;
 
-  // Loud on ambiguity: classify throws UnclassifiableRunId with the real id; never catch-and-default.
   const residency: RunOpsResidency = classify(input.waitpointId);
 
   const pinnedReason = applyPinningRules(input);

apps/webapp/app/v3/runOpsMigration/mintBatchFriendlyId.server.test.ts

@@ -3,10 +3,10 @@ import { batchIdForMintKind, resolveBatchMintKind } from "./mintBatchFriendlyId.
 import { classifyKind } from "@trigger.dev/core/v3/isomorphic";
 
 describe("batchIdForMintKind (pure)", () => {
-  it("ksuid -> 27-char classifiable NEW batch id (no 21-char ids)", () => {
+  it("ksuid -> 26-char classifiable NEW batch id (no 21-char ids)", () => {
     const r = batchIdForMintKind("ksuid");
     expect(r.friendlyId.startsWith("batch_")).toBe(true);
-    expect(r.id.length).toBe(27);
+    expect(r.id.length).toBe(26);
     expect(classifyKind(r.id)).toBe("ksuid");
     expect(classifyKind(r.friendlyId)).toBe("ksuid");
   });
@@ -20,7 +20,7 @@ describe("batchIdForMintKind (pure)", () => {
 
   it("never mints a 21-char id", () => {
     for (const kind of ["cuid", "ksuid"] as const) {
-      expect([25, 27]).toContain(batchIdForMintKind(kind).id.length);
+      expect([25, 26]).toContain(batchIdForMintKind(kind).id.length);
     }
   });
 });
@@ -52,7 +52,7 @@ describe("resolveBatchMintKind", () => {
   });
 
   it("CHILD batch inherits a ksuid (NEW) parent by id-shape", async () => {
-    const parentRunFriendlyId = `run_${"a".repeat(27)}`;
+    const parentRunFriendlyId = `run_${"a".repeat(24) + "01"}`;
     const resolveRunIdMintKind = vi.fn();
 
     const kind = await resolveBatchMintKind({
@@ -94,7 +94,7 @@ describe("resolveBatchMintKind", () => {
   });
 
   it("FLIP ksuid->cuid: a ksuid (NEW) parent still mints a ksuid child though the flag now says cuid", async () => {
-    const parentRunFriendlyId = `run_${"a".repeat(27)}`;
+    const parentRunFriendlyId = `run_${"a".repeat(24) + "01"}`;
     const resolveRunIdMintKind = vi.fn().mockResolvedValue("cuid"); // flag flipped back to cuid
     const kind = await resolveBatchMintKind({
       environment,

apps/webapp/app/v3/runOpsMigration/mintBatchFriendlyId.server.ts

@@ -1,4 +1,4 @@
-import { BatchId, generateKsuidId } from "@trigger.dev/core/v3/isomorphic";
+import { BatchId, generateRunOpsId } from "@trigger.dev/core/v3/isomorphic";
 import {
   resolveRunIdMintKind as defaultResolveRunIdMintKind,
   type RunIdMintKind,
@@ -15,7 +15,7 @@ const defaultDeps: ResolveDeps = {
 
 export function batchIdForMintKind(kind: RunIdMintKind): { id: string; friendlyId: string } {
   if (kind === "ksuid") {
-    const id = generateKsuidId();
+    const id = generateRunOpsId();
     return { id, friendlyId: BatchId.toFriendlyId(id) };
   }
   return BatchId.generate();

apps/webapp/app/v3/runOpsMigration/readThrough.server.test.ts

@@ -10,9 +10,9 @@ import { readThroughRun, type ReadThroughResult } from "./readThrough.server";
 
 vi.setConfig({ testTimeout: 60_000 });
 
-// 25-char cuid body → LEGACY residency. 27-char body → NEW residency.
+// 25-char cuid body → LEGACY residency. 26-char v1 body (version "1" at index 25) → NEW residency.
 const LEGACY_RUN_ID = "run_" + "a".repeat(25);
-const NEW_RUN_ID = "run_" + "b".repeat(27);
+const NEW_RUN_ID = "run_" + "b".repeat(24) + "01";
 
 // Lightweight real read: a trivial `$queryRaw` that genuinely hits the given container.
 // `hit` controls whether the read "finds" the run, so we exercise routing without