feat(run-engine): route execution snapshots through a versioned residency resolver

No user-facing change. This adds an optional internal route field while
the snapshot-store rollout remains inactive.

Mono-RevId: 3da62651b5918e6873a83e0d30c2a05ad24b6542

Author: d-cs

apps/supervisor/src/index.ts

@@ -661,6 +661,8 @@ class ManagedSupervisor {
         nextAttemptNumber: message.run.attemptNumber,
         snapshotId: message.snapshot.id,
         snapshotFriendlyId: message.snapshot.friendlyId,
+        // Carry the run's storage route to the cold-start pod so its start request echoes it back.
+        snapshotRoute: message.snapshotRoute,
         placementTags: message.placementTags,
         traceContext: message.run.traceContext,
         annotations: message.run.annotations,

apps/supervisor/src/workloadManager/compute.ts

@@ -157,6 +157,7 @@ export class ComputeWorkloadManager implements WorkloadManager {
       TRIGGER_DEPLOYMENT_VERSION: opts.deploymentVersion,
       TRIGGER_RUN_ID: opts.runFriendlyId,
       TRIGGER_SNAPSHOT_ID: opts.snapshotFriendlyId,
+      ...(opts.snapshotRoute ? { TRIGGER_SNAPSHOT_ROUTE: JSON.stringify(opts.snapshotRoute) } : {}),
       TRIGGER_SUPERVISOR_API_PROTOCOL: this.opts.workloadApiProtocol,
       TRIGGER_SUPERVISOR_API_PORT: String(this.opts.workloadApiPort),
       TRIGGER_SUPERVISOR_API_DOMAIN: this.opts.workloadApiDomain ?? "",

apps/supervisor/src/workloadManager/docker.ts

@@ -78,6 +78,9 @@ export class DockerWorkloadManager implements WorkloadManager {
       `TRIGGER_DEPLOYMENT_VERSION=${opts.deploymentVersion}`,
       `TRIGGER_RUN_ID=${opts.runFriendlyId}`,
       `TRIGGER_SNAPSHOT_ID=${opts.snapshotFriendlyId}`,
+      ...(opts.snapshotRoute
+        ? [`TRIGGER_SNAPSHOT_ROUTE=${JSON.stringify(opts.snapshotRoute)}`]
+        : []),
       `TRIGGER_SUPERVISOR_API_PROTOCOL=${this.opts.workloadApiProtocol}`,
       `TRIGGER_SUPERVISOR_API_PORT=${this.opts.workloadApiPort}`,
       `TRIGGER_SUPERVISOR_API_DOMAIN=${this.opts.workloadApiDomain ?? getDockerHostDomain()}`,

apps/supervisor/src/workloadManager/kubernetes.ts

@@ -215,6 +215,14 @@ export class KubernetesWorkloadManager implements WorkloadManager {
                     name: "TRIGGER_SNAPSHOT_ID",
                     value: opts.snapshotFriendlyId,
                   },
+                  ...(opts.snapshotRoute
+                    ? [
+                        {
+                          name: "TRIGGER_SNAPSHOT_ROUTE",
+                          value: JSON.stringify(opts.snapshotRoute),
+                        },
+                      ]
+                    : []),
                   {
                     name: "TRIGGER_SUPERVISOR_API_PROTOCOL",
                     value: this.opts.workloadApiProtocol,

apps/supervisor/src/workloadManager/types.ts

@@ -3,6 +3,7 @@ import type {
   MachinePreset,
   PlacementTag,
   RunAnnotations,
+  SnapshotRouteWire,
 } from "@trigger.dev/core/v3";
 
 export interface WorkloadManagerOptions {
@@ -50,6 +51,8 @@ export interface WorkloadManagerCreateOptions {
   runFriendlyId: string;
   snapshotId: string;
   snapshotFriendlyId: string;
+  // The run's storage route, materialized as the TRIGGER_SNAPSHOT_ROUTE env var for a cold start.
+  snapshotRoute?: SnapshotRouteWire;
   // Trace context for OTel span emission (W3C format: { traceparent: "00-...", tracestate?: "..." })
   traceContext?: Record<string, unknown>;
   annotations?: RunAnnotations;

apps/webapp/app/routes/engine.v1.dev.runs.$runFriendlyId.snapshots.$snapshotFriendlyId.attempts.start.ts

@@ -49,6 +49,8 @@ const { action } = createActionApiRoute(
       const engineResult = await engine.startRunAttempt({
         runId: RunId.toId(runFriendlyId),
         snapshotId: SnapshotId.toId(snapshotFriendlyId),
+        isWarmStart: body.isWarmStart,
+        snapshotRoute: body.snapshotRoute,
       });
 
       const defaultMachinePreset = machinePresetFromName(defaultMachine);

apps/webapp/app/routes/engine.v1.worker-actions.runs.$runFriendlyId.snapshots.$snapshotFriendlyId.attempts.complete.ts

@@ -29,6 +29,7 @@ export const action = createActionWorkerApiRoute(
       completion,
       runnerId,
       environmentId,
+      snapshotRoute: body.snapshotRoute,
     });
 
     return json({ result: completeResult });

apps/webapp/app/routes/engine.v1.worker-actions.runs.$runFriendlyId.snapshots.$snapshotFriendlyId.attempts.start.ts

@@ -28,6 +28,7 @@ export const action = createActionWorkerApiRoute(
       isWarmStart: body.isWarmStart,
       runnerId,
       environmentId,
+      snapshotRoute: body.snapshotRoute,
     });
 
     return json(runExecutionData);

apps/webapp/app/routes/engine.v1.worker-actions.runs.$runFriendlyId.snapshots.$snapshotFriendlyId.continue.ts

@@ -1,5 +1,7 @@
 import type { TypedResponse } from "@remix-run/server-runtime";
 import { json } from "@remix-run/server-runtime";
+import { WorkerApiContinueRunExecutionQueryParams } from "@trigger.dev/core/v3/runEngineWorker";
+import type { SnapshotRouteWire } from "@trigger.dev/core/v3";
 import type { WorkerApiContinueRunExecutionRequestBody } from "@trigger.dev/core/v3/workers";
 import { z } from "zod";
 import { logger } from "~/services/logger.server";
@@ -16,11 +18,38 @@ export const loader = createLoaderWorkerApiRoute(
   async ({
     authenticatedWorker,
     params,
+    request,
     runnerId,
     environmentId,
   }): Promise<TypedResponse<WorkerApiContinueRunExecutionRequestBody>> => {
     const { runFriendlyId, snapshotFriendlyId } = params;
 
+    // Optional, mixed-version: older workers omit it. It's a GET, so it travels as a URL query
+    // param (a JSON-encoded SnapshotRouteWire), not a body — see
+    // WorkerApiContinueRunExecutionQueryParams.
+    const rawSnapshotRoute = new URL(request.url).searchParams.get("snapshotRoute");
+    let snapshotRoute: SnapshotRouteWire | undefined;
+    if (rawSnapshotRoute) {
+      try {
+        const parsed = WorkerApiContinueRunExecutionQueryParams.shape.snapshotRoute.safeParse(
+          JSON.parse(rawSnapshotRoute)
+        );
+        if (parsed.success) {
+          snapshotRoute = parsed.data;
+        } else {
+          logger.warn("Continuing run execution: ignoring unparseable snapshotRoute query param", {
+            runFriendlyId,
+            snapshotFriendlyId,
+          });
+        }
+      } catch {
+        logger.warn("Continuing run execution: ignoring invalid snapshotRoute query param JSON", {
+          runFriendlyId,
+          snapshotFriendlyId,
+        });
+      }
+    }
+
     logger.debug("Continuing run execution", { runFriendlyId, snapshotFriendlyId });
 
     try {
@@ -29,6 +58,7 @@ export const loader = createLoaderWorkerApiRoute(
         snapshotFriendlyId,
         runnerId,
         environmentId,
+        snapshotRoute,
       });
 
       return json(continuationResult);

apps/webapp/app/routes/engine.v1.worker-actions.runs.$runFriendlyId.snapshots.$snapshotFriendlyId.suspend.ts

@@ -40,6 +40,7 @@ export const action = createActionWorkerApiRoute(
         snapshotFriendlyId,
         checkpoint: body.checkpoint,
         runnerId,
+        snapshotRoute: body.snapshotRoute,
       });
 
       return json({ ok: true });