fix(runtime): preserve deliveries when workflow versions are missing

.changeset/quiet-signals-wait.md

@@ -0,0 +1,7 @@
+---
+'@tanstack/workflow-runtime': patch
+---
+
+Reject signal, approval, and timer deliveries for a run whose workflow version
+is not registered, returning `version-mismatch` and leaving the run paused
+instead of consuming the delivery and stranding the run.

docs/concepts/replay-and-resume.md

@@ -106,6 +106,10 @@ On resume the engine reads `RunState.workflowVersion` and routes to the matching
 
 Mismatched version with nothing in `previousVersions` → `RUN_ERRORED { code: 'workflow_version_mismatch' }`.
 
+When the run is driven through `@tanstack/workflow-runtime`, signal, approval, and timer deliveries to such a run are rejected before they are consumed: the result kind is `version-mismatch` and the run stays `paused`, so restoring the missing version lets the same delivery resume it.
+
+A rejected signal or approval payload is not stored by the runtime. Keep it in a durable inbox or return a retryable HTTP response, such as 503, to a sender that retries. Retry with the same signal ID or approval ID after restoring the missing workflow version. The Cloudflare D1 payment example returns 503 for this case.
+
 ## Attach (read-only subscribe)
 
 A second subscriber (browser refresh, mobile reconnect) reads current state without driving the run forward:

examples/deployment-pocs/cloudflare-d1/src/worker.ts

@@ -73,12 +73,11 @@ export default {
       }
 
       if (url.pathname === '/signals/payment' && request.method === 'POST') {
-        return json(
-          await deliverPayment(
-            runtime,
-            await readJson<PaymentSignalBody>(request),
-          ),
+        const result = await deliverPayment(
+          runtime,
+          await readJson<PaymentSignalBody>(request),
         )
+        return json(result, result.kind === 'version-mismatch' ? 503 : 200)
       }
 
       if (url.pathname === '/sweep' && request.method === 'POST') {

packages/workflow-runtime/src/runtime-driver.ts

@@ -212,6 +212,14 @@ async function deliverSignal<
         args.minYieldRemainingMs,
       )
       const leaseMs = resolveLeaseMs(config, args.leaseMs)
+      const prepared = await prepareRunDelivery(config, telemetry, args.runId)
+      if (prepared.rejected) {
+        span.setAttribute(
+          'tanstack.workflow.result_kind',
+          prepared.rejected.kind,
+        )
+        return prepared.rejected
+      }
       const delivery = {
         signalId: args.signalId,
         stepId: args.stepId,
@@ -236,7 +244,9 @@ async function deliverSignal<
         return result
       }
 
-      const workflow = await loadWorkflow(config, delivered.run.workflowId)
+      const workflow =
+        prepared.workflow ??
+        (await loadWorkflow(config, delivered.run.workflowId))
       const result = await driveClaimedRun(config, telemetry, {
         workflow,
         workflowId: delivered.run.workflowId,
@@ -279,6 +289,8 @@ async function deliverSignalFromRuntime<
     args.minYieldRemainingMs,
   )
   const leaseMs = resolveLeaseMs(config, args.leaseMs)
+  const prepared = await prepareRunDelivery(config, telemetry, args.runId)
+  if (prepared.rejected) return prepared.rejected
   const delivery = {
     signalId: args.signalId,
     stepId: args.stepId,
@@ -301,7 +313,8 @@ async function deliverSignalFromRuntime<
     return resultFromSignalDelivery(args.runId, delivered)
   }
 
-  const workflow = await loadWorkflow(config, delivered.run.workflowId)
+  const workflow =
+    prepared.workflow ?? (await loadWorkflow(config, delivered.run.workflowId))
   return driveClaimedRun(config, telemetry, {
     workflow,
     workflowId: delivered.run.workflowId,
@@ -338,6 +351,14 @@ async function deliverApproval<
         args.minYieldRemainingMs,
       )
       const leaseMs = resolveLeaseMs(config, args.leaseMs)
+      const prepared = await prepareRunDelivery(config, telemetry, args.runId)
+      if (prepared.rejected) {
+        span.setAttribute(
+          'tanstack.workflow.result_kind',
+          prepared.rejected.kind,
+        )
+        return prepared.rejected
+      }
       const delivered = await traceStoreOperation(
         telemetry,
         'store.deliver_approval',
@@ -355,7 +376,9 @@ async function deliverApproval<
         return result
       }
 
-      const workflow = await loadWorkflow(config, delivered.run.workflowId)
+      const workflow =
+        prepared.workflow ??
+        (await loadWorkflow(config, delivered.run.workflowId))
       const result = await driveClaimedRun(config, telemetry, {
         workflow,
         workflowId: delivered.run.workflowId,
@@ -419,6 +442,8 @@ async function sweep<TWorkflows extends Record<string, WorkflowRegistration>>(
       const recovered: Array<WorkflowRuntimeRunResult> = []
       const scheduled: Array<WorkflowRuntimeRunResult> = []
       const timers: Array<WorkflowRuntimeRunResult> = []
+      const seenTimers = new Set<string>()
+      let rejectedTimer = false
       let deadlineReached = false
 
       while (recovered.length < maxRecoveredRuns) {
@@ -554,24 +579,30 @@ async function sweep<TWorkflows extends Record<string, WorkflowRegistration>>(
           deadlineReached = true
           break
         }
-
         const dueTimers = await traceStoreOperation(
           telemetry,
           'store.claim_due_timers',
           { leaseOwner },
           () =>
             config.store.claimDueTimers({
               now,
-              limit: 1,
+              limit: maxTimers,
               leaseOwner,
               leaseMs,
             }),
         )
-        const timer = dueTimers[0]
-        if (!timer) break
-
-        timers.push(
-          await deliverTimer(config, telemetry, {
+        let advanced = false
+        for (const timer of dueTimers) {
+          const timerKey = JSON.stringify([timer.runId, timer.signalId])
+          if (seenTimers.has(timerKey)) continue
+          if (timers.length >= maxTimers) break
+          if (shouldStopForDeadline(deadline, minYieldRemainingMs)) {
+            deadlineReached = true
+            break
+          }
+          seenTimers.add(timerKey)
+          advanced = true
+          const result = await deliverTimer(config, telemetry, {
             timer,
             now,
             leaseOwner,
@@ -582,8 +613,11 @@ async function sweep<TWorkflows extends Record<string, WorkflowRegistration>>(
             minYieldRemainingMs,
             yieldResumeAt: now + 1,
             publish: args.publish,
-          }),
-        )
+          })
+          if (result.kind === 'version-mismatch') rejectedTimer = true
+          timers.push(result)
+        }
+        if (!advanced || deadlineReached) break
       }
 
       const result = {
@@ -593,6 +627,7 @@ async function sweep<TWorkflows extends Record<string, WorkflowRegistration>>(
         summary: summarizeSweep(recovered, scheduled, timers),
         deadlineReached,
         remainingMayExist:
+          rejectedTimer ||
           deadlineReached ||
           recovered.length >= maxRecoveredRuns ||
           scheduled.length >= maxScheduledRuns ||
@@ -853,6 +888,66 @@ async function syncTimerFromRunState<
   )
 }
 
+// Deliveries are checked before the store consumes them: once consumed,
+// a run whose version this runtime can't replay would be left `running`
+// with no lease and nothing awaited, and redelivery would be refused.
+async function prepareRunDelivery<
+  TWorkflows extends Record<string, WorkflowRegistration>,
+>(
+  config: WorkflowRuntimeConfig<TWorkflows>,
+  telemetry: WorkflowTelemetry,
+  runId: string,
+): Promise<{
+  workflow?: AnyWorkflowDefinition
+  rejected?: WorkflowRuntimeRunResult
+}> {
+  const run = await traceStoreOperation(
+    telemetry,
+    'store.load_run',
+    { runId },
+    () => config.store.loadRun(runId),
+  )
+  if (!run) {
+    return {
+      rejected: { kind: 'not-found', runId, events: [], eventCount: 0 },
+    }
+  }
+  if (
+    run.status === 'finished' ||
+    run.status === 'errored' ||
+    run.status === 'aborted'
+  ) {
+    return {}
+  }
+
+  const state = await traceStoreOperation(
+    telemetry,
+    'store.load_run_state',
+    { runId },
+    () => config.store.loadRunState(runId),
+  )
+  const version = state?.workflowVersion ?? run.workflowVersion
+  const workflow = await loadWorkflow(config, run.workflowId)
+  if (
+    !version ||
+    workflow.version === version ||
+    workflow.previousVersions?.some((previous) => previous.version === version)
+  ) {
+    return { workflow }
+  }
+
+  return {
+    rejected: {
+      kind: 'version-mismatch',
+      runId,
+      workflowId: run.workflowId,
+      run,
+      events: [],
+      eventCount: 0,
+    },
+  }
+}
+
 async function loadWorkflow<
   TWorkflows extends Record<string, WorkflowRegistration>,
 >(

packages/workflow-runtime/src/types.ts

@@ -445,6 +445,7 @@ export type WorkflowRuntimeRunResultKind =
   | 'not-claimable'
   | 'not-waiting'
   | 'duplicate'
+  | 'version-mismatch'
 
 export interface WorkflowRuntimeRunResult {
   kind: WorkflowRuntimeRunResultKind