[world-vercel] Attest the executor's spec version on run_started (#4366)

run_started repeats the spec version the caller of start() stamped, which
is older when the run was started from another deployment. Send the
version this SDK mints alongside it, so the backend can move such a run
onto the event-id scheme this runtime reads before any event is numbered.

Author: VaguelySerious

.changeset/executor-spec-version.md

@@ -0,0 +1,5 @@
+---
+"@workflow/world-vercel": patch
+---
+
+Fix runs started from an older deployment with `deploymentId: 'latest'` failing on a newer one

.changeset/spec-version-classification.md

@@ -0,0 +1,5 @@
+---
+"@workflow/world": patch
+---
+
+Classify each spec version as capability-only or structural (`CAPABILITY_ONLY_SPEC_VERSIONS`, `STRUCTURAL_SPEC_VERSIONS`, `crossesStructuralSpecVersion`), so a backend raising a run to its executor's version knows which moves need a fresh log

packages/world-vercel/src/events-v4.ts

@@ -225,6 +225,13 @@ interface CreateEventV4InputBase {
    *  user data (e.g. step_started). */
   payload?: Uint8Array;
   specVersion: number;
+  /**
+   * `run_started` only: the spec version this SDK runs. `specVersion` on
+   * `run_started` repeats the version the caller of `start()` stamped, which
+   * can be older when the run was started from another deployment. The server
+   * uses this to raise such a run to the version this runtime runs.
+   */
+  executorSpecVersion?: number;
   correlationId?: string;
   vercelId?: string;
   /** Compute instance that wrote this event; rides the frame meta by `vercelId`. */
@@ -594,6 +601,9 @@ function buildPostFrameMeta(
     eventType: input.eventType,
     specVersion: input.specVersion,
   };
+  if (input.executorSpecVersion !== undefined) {
+    meta.executorSpecVersion = input.executorSpecVersion;
+  }
   if (input.correlationId !== undefined)
     meta.correlationId = input.correlationId;
   if (input.vercelId !== undefined) meta.vercelId = input.vercelId;

packages/world-vercel/src/events.test.ts

@@ -5,6 +5,10 @@ import {
   type AnyEventRequest,
   type CreateEventParams,
   EventSchema,
+  mintedSpecVersion,
+  SEALED_LOG_ENV_VAR,
+  SPEC_VERSION_SUPPORTS_CBOR_QUEUE_TRANSPORT,
+  SPEC_VERSION_SUPPORTS_SLOT_IDENTITY,
 } from '@workflow/world';
 import { decode, encode } from 'cbor-x';
 import { ulid } from 'ulid';
@@ -235,6 +239,90 @@ describe('createWorkflowRunEvent with v1Compat', () => {
   });
 });
 
+/**
+ * `run_started` attests the spec version this SDK runs, separately from the
+ * `specVersion` it repeats from the queue message (the stamp of whoever called
+ * `start()`, possibly an older deployment). The backend raises a run stamped
+ * lower to this value.
+ */
+describe('createWorkflowRunEvent executorSpecVersion', () => {
+  async function postRunStartedAndCaptureMeta(
+    extraConfig: { mintedSpecVersion?: number } = {}
+  ): Promise<Record<string, unknown> | undefined> {
+    const agent = mockAgent();
+    let capturedMeta: Record<string, unknown> | undefined;
+    agent
+      .get(ORIGIN)
+      .intercept({
+        path: '/api/v4/runs/wrun_1/events/run_started',
+        method: 'POST',
+      })
+      .reply(
+        200,
+        (opts: { body?: unknown }) => {
+          capturedMeta = decodePostedMeta(opts.body);
+          return runStartedResponse();
+        },
+        {
+          headers: {
+            'content-type': V4_FRAME_CONTENT_TYPE,
+            'x-wf-event-id': 'evnt_1',
+            'x-wf-run-id': 'wrun_1',
+            'x-wf-created-at': '2026-06-10T00:00:00.000Z',
+            'x-wf-max-events': '10000',
+          },
+        }
+      );
+    await createWorkflowRunEvent(
+      'wrun_1',
+      {
+        eventType: 'run_started',
+        specVersion: SPEC_VERSION_SUPPORTS_CBOR_QUEUE_TRANSPORT,
+      } as AnyEventRequest,
+      undefined,
+      { token: 'test-token', dispatcher: agent, ...extraConfig }
+    );
+    agent.assertNoPendingInterceptors();
+    return capturedMeta;
+  }
+
+  it("sends the version this SDK mints next to the caller's stamp", async () => {
+    const meta = await postRunStartedAndCaptureMeta();
+    expect(meta?.specVersion).toBe(SPEC_VERSION_SUPPORTS_CBOR_QUEUE_TRANSPORT);
+    expect(meta?.executorSpecVersion).toBe(mintedSpecVersion());
+  });
+
+  it('attests the version the World declared at creation, not a later env read', async () => {
+    // `createWorld` records what it declared; flipping the kill switch
+    // in-process afterwards must not make run_started claim more than the
+    // runtime validated.
+    vi.stubEnv(SEALED_LOG_ENV_VAR, '1');
+    try {
+      const meta = await postRunStartedAndCaptureMeta({
+        mintedSpecVersion: SPEC_VERSION_SUPPORTS_SLOT_IDENTITY,
+      });
+      expect(meta?.executorSpecVersion).toBe(
+        SPEC_VERSION_SUPPORTS_SLOT_IDENTITY
+      );
+    } finally {
+      vi.unstubAllEnvs();
+    }
+  });
+
+  it('follows the sealed-log kill switch', async () => {
+    vi.stubEnv(SEALED_LOG_ENV_VAR, '0');
+    try {
+      const meta = await postRunStartedAndCaptureMeta();
+      expect(meta?.executorSpecVersion).toBe(mintedSpecVersion());
+      expect(meta?.executorSpecVersion).toBe(
+        SPEC_VERSION_SUPPORTS_SLOT_IDENTITY
+      );
+    } finally {
+      vi.unstubAllEnvs();
+    }
+  });
+});
+
 /**
  * A replay-context create names the position its decisions were made at:
  * `eventCount`, the highest event slot the runtime had loaded. Locks in that it

packages/world-vercel/src/events.ts

@@ -53,6 +53,7 @@ import {
   isHookEventRequiringExistence,
   type ListEventsByCorrelationIdParams,
   type ListEventsParams,
+  mintedSpecVersion,
   type PaginatedResponse,
   validateUlidTimestamp,
   type WorkflowRun,
@@ -774,6 +775,11 @@ async function createWorkflowRunEventInner(
   const input = {
     runId: id,
     specVersion: data.specVersion ?? 2,
+    ...(data.eventType === 'run_started'
+      ? {
+          executorSpecVersion: config?.mintedSpecVersion ?? mintedSpecVersion(),
+        }
+      : {}),
     ...(data.correlationId ? { correlationId: data.correlationId } : {}),
     ...(params?.requestId ? { vercelId: params.requestId } : {}),
     ...(params?.computeInstanceId

packages/world-vercel/src/index.ts

@@ -28,6 +28,10 @@ export function createWorld(config?: APIConfig): World {
   // Use config value first (set correctly by CLI/web), fall back to env var (runtime).
   const projectId =
     config?.projectConfig?.projectId || process.env.VERCEL_PROJECT_ID;
+  // Read once: the runtime validates this declaration, and `run_started`
+  // attests the same value (see `APIConfig.mintedSpecVersion`).
+  const specVersion = mintedSpecVersion();
+  config = { ...config, mintedSpecVersion: specVersion };
 
   return {
     // The version is what tells the backend which id scheme a run uses: it is
@@ -39,7 +43,7 @@ export function createWorld(config?: APIConfig): World {
     // version that introduced slots: a bump has to move this declaration with
     // it, or the runtime's compatibility floor rises past the adapter shipped
     // alongside it and rejects it (see `assertWorldSupportsRuntimeProtocol`).
-    specVersion: mintedSpecVersion(),
+    specVersion,
     capabilities: {
       hookRetention: { active: true },
       // Vercel Queues supports maxConcurrency-limited consumers, which

packages/world-vercel/src/utils.ts

@@ -128,6 +128,16 @@ export interface APIConfig {
     teamId?: string;
     environment?: string;
   };
+  /**
+   * The spec version this World declared when it was created. Set by
+   * `createWorld`, which reads `mintedSpecVersion()` once; `run_started`
+   * attests this value as `executorSpecVersion` so the attestation always
+   * matches what the runtime validated, even if `WORKFLOW_SEALED_LOG` changes
+   * in-process afterwards.
+   *
+   * @internal
+   */
+  mintedSpecVersion?: number;
 }
 
 export const DEFAULT_RESOLVE_DATA_OPTION = 'all';

packages/world/src/index.ts

@@ -155,6 +155,8 @@ export {
 } from './slot-identity.js';
 export type { SpecVersion } from './spec-version.js';
 export {
+  CAPABILITY_ONLY_SPEC_VERSIONS,
+  crossesStructuralSpecVersion,
   isLegacySpecVersion,
   mintedSpecVersion,
   requiresNewerWorld,
@@ -169,6 +171,7 @@ export {
   SPEC_VERSION_SUPPORTS_HOOK_FORCE_CLAIM,
   SPEC_VERSION_SUPPORTS_SEALED_LOG,
   SPEC_VERSION_SUPPORTS_SLOT_IDENTITY,
+  STRUCTURAL_SPEC_VERSIONS,
 } from './spec-version.js';
 export type * from './steps.js';
 export {

packages/world/src/spec-version.test.ts

@@ -1,5 +1,8 @@
 import { describe, expect, it } from 'vitest';
+import * as specVersions from './spec-version.js';
 import {
+  CAPABILITY_ONLY_SPEC_VERSIONS,
+  crossesStructuralSpecVersion,
   isLegacySpecVersion,
   mintedSpecVersion,
   requiresNewerWorld,
@@ -12,8 +15,49 @@ import {
   SPEC_VERSION_SUPPORTS_HOOK_FORCE_CLAIM,
   SPEC_VERSION_SUPPORTS_SEALED_LOG,
   SPEC_VERSION_SUPPORTS_SLOT_IDENTITY,
+  STRUCTURAL_SPEC_VERSIONS,
 } from './spec-version.js';
 
+describe('spec version classification', () => {
+  const versionConstants = Object.entries(specVersions).filter(([name]) =>
+    name.startsWith('SPEC_VERSION_SUPPORTS_')
+  ) as [string, number][];
+
+  it.each(
+    versionConstants
+  )('%s is classified as capability-only or structural', (_name, version) => {
+    // A new version constant must be placed in exactly one set: a backend
+    // raises running runs across capability-only versions, so leaving a
+    // structural one out of STRUCTURAL_SPEC_VERSIONS is only safe because
+    // the check is an allow-list, and this keeps the lists honest.
+    expect(
+      Number(CAPABILITY_ONLY_SPEC_VERSIONS.has(version)) +
+        Number(STRUCTURAL_SPEC_VERSIONS.has(version))
+    ).toBe(1);
+  });
+
+  it('treats slot identity and the sealed log as structural', () => {
+    expect(crossesStructuralSpecVersion(5, 6)).toBe(true);
+    expect(crossesStructuralSpecVersion(6, 7)).toBe(true);
+    expect(crossesStructuralSpecVersion(3, 8)).toBe(true);
+  });
+
+  it('lets capability-only versions be crossed', () => {
+    expect(crossesStructuralSpecVersion(3, 5)).toBe(false);
+    expect(crossesStructuralSpecVersion(7, 8)).toBe(false);
+    expect(crossesStructuralSpecVersion(8, 8)).toBe(false);
+  });
+
+  it('treats an unclassified future version as structural', () => {
+    expect(
+      crossesStructuralSpecVersion(
+        SPEC_VERSION_MAX_SUPPORTED,
+        SPEC_VERSION_MAX_SUPPORTED + 1
+      )
+    ).toBe(true);
+  });
+});
+
 describe('spec version constants', () => {
   it('current spec version is the hook-force-claim version', () => {
     expect(SPEC_VERSION_SUPPORTS_SLOT_IDENTITY).toBe(6);

packages/world/src/spec-version.ts

@@ -188,6 +188,49 @@ export function mintedSpecVersion(
 export const SPEC_VERSION_MAX_SUPPORTED =
   SPEC_VERSION_SUPPORTS_HOOK_FORCE_CLAIM as SpecVersion;
 
+/**
+ * Spec versions whose only effect is to switch on capabilities of a run's
+ * reader and writer, which is the runtime executing it. A backend may raise
+ * a running run across these (to its executor's attested version, see
+ * `executorSpecVersion` on `run_started`), because nothing already in the
+ * run's log changes meaning.
+ *
+ * Every other version is STRUCTURAL: it changes how the log is laid out or
+ * read (event sourcing itself, slot-numbered event ids, sealed-log
+ * sequencing), so a run may only be moved across it before any event past
+ * `run_created` exists. That includes versions not listed here yet: an
+ * unclassified future version is structural by default, and adding a
+ * version constant without classifying it fails this package's tests.
+ */
+export const CAPABILITY_ONLY_SPEC_VERSIONS: ReadonlySet<number> = new Set([
+  SPEC_VERSION_SUPPORTS_CBOR_QUEUE_TRANSPORT,
+  SPEC_VERSION_SUPPORTS_ATTRIBUTES,
+  SPEC_VERSION_SUPPORTS_COMPRESSION,
+  SPEC_VERSION_SUPPORTS_HOOK_FORCE_CLAIM,
+]);
+
+/** The structural spec versions; see {@link CAPABILITY_ONLY_SPEC_VERSIONS}. */
+export const STRUCTURAL_SPEC_VERSIONS: ReadonlySet<number> = new Set([
+  SPEC_VERSION_SUPPORTS_EVENT_SOURCING,
+  SPEC_VERSION_SUPPORTS_SLOT_IDENTITY,
+  SPEC_VERSION_SUPPORTS_SEALED_LOG,
+]);
+
+/**
+ * Whether moving a run from spec version `from` up to `to` crosses a
+ * structural version, and so is only allowed while the run's log holds
+ * nothing but `run_created`. See {@link CAPABILITY_ONLY_SPEC_VERSIONS}.
+ */
+export function crossesStructuralSpecVersion(
+  from: number,
+  to: number
+): boolean {
+  for (let v = from + 1; v <= to; v++) {
+    if (!CAPABILITY_ONLY_SPEC_VERSIONS.has(v)) return true;
+  }
+  return false;
+}
+
 /**
  * Check if a spec version is legacy (<= SPEC_VERSION_LEGACY or undefined).
  * Legacy runs require different handling - they use direct entity mutation