feat(core): residency classifier ownerEngine(id) for run-ops split

Add a pure, isomorphic length-disjoint residency classifier in
packages/core/src/v3/isomorphic/runOpsResidency.ts. It classifies a
run-ops id (RunId or WaitpointId, friendly or internal) by internal id
length: cuid-length (25) -> "LEGACY", ksuid-length (27) -> "NEW", and
throws UnclassifiableRunId on any other length.

Exports ownerEngine / classifyResidency (same fn), classifyKind,
isClassifiable, UnclassifiableRunId, and the CUID_LENGTH/KSUID_LENGTH
constants. No dependency on friendlyId.ts (length-only); rides solely on
the 25-vs-27 margin. Adds a property/disjointness vitest suite driving
real cuid + ksuid mints.

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

Author: d-cs

.changeset/run-ops-residency-classifier.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/core": patch
+---
+
+Add residency classifier `ownerEngine(id)` for the run-ops DB split (length-disjoint cuid→LEGACY / ksuid→NEW; throws on ambiguity).

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";

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 W0-FND-01 flag state
+
+const SAMPLES = 50_000; // property-scale; CI-fast. (Bump locally toward "millions" per DoD.)
+
+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");
+  });
+});

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

@@ -0,0 +1,59 @@
+/** The two run-ops stores a run/waitpoint can reside in. */
+export type Residency = "LEGACY" | "NEW";
+
+/** Underlying id format. cuid → LEGACY store, ksuid → NEW store. */
+export type ResidencyKind = "cuid" | "ksuid";
+
+/** @bugsnag/cuid emits 25-char ids (W0-FND-01: cuid path, flag OFF). */
+export const CUID_LENGTH = 25;
+/** KSUID / nanoid-27 emits 27-char ids (W0-FND-01: ksuid path, flag ON). */
+export const KSUID_LENGTH = 27;
+
+/** Thrown when an id length matches neither the cuid nor the ksuid margin. */
+export class UnclassifiableRunId extends Error {
+  readonly value: string;
+  readonly valueLength: number;
+  constructor(value: string) {
+    super(
+      `Unclassifiable run-ops id: length ${value.length} matches neither cuid (${CUID_LENGTH}) nor ksuid (${KSUID_LENGTH}) — value=${JSON.stringify(
+        value
+      )}`
+    );
+    this.name = "UnclassifiableRunId";
+    this.value = value;
+    this.valueLength = value.length;
+  }
+}
+
+/**
+ * Strip a single leading `<prefix>_` (e.g. `run_`, `waitpoint_`) if present,
+ * so friendly and internal forms classify identically. Only the FIRST
+ * underscore is treated as the prefix separator (mirrors fromFriendlyId's
+ * two-part split contract in friendlyId.ts), without importing it.
+ */
+function internalForm(id: string): string {
+  const underscore = id.indexOf("_");
+  return underscore === -1 ? id : id.slice(underscore + 1);
+}
+
+/** Returns the underlying id FORMAT (cuid|ksuid), or throws if unclassifiable. */
+export function classifyKind(id: string): ResidencyKind {
+  const internal = internalForm(id);
+  if (internal.length === CUID_LENGTH) return "cuid";
+  if (internal.length === KSUID_LENGTH) return "ksuid";
+  throw new UnclassifiableRunId(id);
+}
+
+/** Non-throwing predicate: is this id length one we can classify? */
+export function isClassifiable(id: string): boolean {
+  const len = internalForm(id).length;
+  return len === CUID_LENGTH || len === KSUID_LENGTH;
+}
+
+/** Map an id to its owning run-ops store by length. Throws on ambiguity. */
+export function classifyResidency(id: string): Residency {
+  return classifyKind(id) === "ksuid" ? "NEW" : "LEGACY";
+}
+
+/** Primary public name (doc 04 / RoutingRunStore / cross-seam guard). */
+export const ownerEngine = classifyResidency;