feat(core): record replay lineage in run executionContext

.changeset/replay-lineage-execution-context.md

@@ -0,0 +1,5 @@
+---
+'@workflow/core': minor
+---
+
+Record the source run on replays: `recreateRunFromExisting` now stamps `replayedFromRunId` into the new run's `executionContext` (and `start` accepts a matching option) so tooling can surface a run as a replay and link back to its origin.

packages/core/src/runtime/runs.test.ts

@@ -12,14 +12,27 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 // Mock version module to avoid missing generated file
 vi.mock('../version.js', () => ({ version: '0.0.0-test' }));
 
+// Stub `start` so recreateRunFromExisting can be tested for the options it
+// forwards without exercising the full run-creation pipeline (serialization,
+// telemetry, queueing).
+vi.mock('./start.js', () => ({ start: vi.fn() }));
+
+// Keep serialization real except for argument hydration, which needs a real
+// serialized payload we don't have in these unit tests.
+vi.mock('../serialization.js', async (importActual) => {
+ const actual = await importActual<typeof import('../serialization.js')>();
+ return { ...actual, hydrateWorkflowArguments: vi.fn().mockResolvedValue([]) };
+});
+
 import { registerSerializationClass } from '../class-serialization.js';
 import {
  dehydrateRunError,
  dehydrateStepReturnValue,
  hydrateStepReturnValue,
 } from '../serialization.js';
 import { Run } from './run.js';
-import { reenqueueRun, wakeUpRun } from './runs.js';
+import { recreateRunFromExisting, reenqueueRun, wakeUpRun } from './runs.js';
+import { start } from './start.js';
 import { setWorld } from './world.js';
 
 function createMockWorld(
@@ -155,6 +168,31 @@ describe('reenqueueRun', () => {
  });
 });
 
+describe('recreateRunFromExisting', () => {
+ afterEach(() => {
+ vi.mocked(start).mockReset();
+ });
+
+ it('forwards the source run id to start as replayedFromRunId', async () => {
+ const world = createMockWorld({
+ run: { runId: 'wrun_source', deploymentId: 'deploy_source' },
+ });
+ vi.mocked(start).mockResolvedValue({ runId: 'wrun_new' } as Run<unknown>);
+
+ const newRunId = await recreateRunFromExisting(world, 'wrun_source');
+
+ expect(newRunId).toBe('wrun_new');
+ expect(start).toHaveBeenCalledWith(
+ { workflowId: 'test-workflow' },
+ expect.any(Array),
+ expect.objectContaining({
+ replayedFromRunId: 'wrun_source',
+ deploymentId: 'deploy_source',
+ })
+ );
+ });
+});
+
 describe('Run.exists', () => {
  afterEach(() => {
  setWorld(undefined as unknown as World);

packages/core/src/runtime/runs.ts

@@ -105,6 +105,7 @@ export async function recreateRunFromExisting(
  deploymentId,
  world,
  specVersion,
+ replayedFromRunId: runId,
  namespace: options.namespace,
  }
  );

packages/core/src/runtime/start.test.ts

@@ -770,6 +770,89 @@ describe('start', () => {
  });
  });
 
+ describe('replay lineage (executionContext.replayedFromRunId)', () => {
+ let mockEventsCreate: ReturnType<typeof vi.fn>;
+ let mockQueue: ReturnType<typeof vi.fn>;
+
+ const validWorkflow = Object.assign(() => Promise.resolve('result'), {
+ workflowId: 'test-workflow',
+ });
+
+ beforeEach(() => {
+ mockEventsCreate = vi.fn().mockImplementation((runId) => {
+ return Promise.resolve({
+ run: { runId: runId ?? 'wrun_test123', status: 'pending' },
+ });
+ });
+ mockQueue = vi.fn().mockResolvedValue(undefined);
+
+ setWorld({
+ specVersion: SPEC_VERSION_CURRENT,
+ getDeploymentId: vi.fn().mockResolvedValue('deploy_123'),
+ events: { create: mockEventsCreate },
+ queue: mockQueue,
+ });
+ });
+
+ afterEach(() => {
+ setWorld(undefined);
+ vi.clearAllMocks();
+ });
+
+ it('records replayedFromRunId in executionContext when provided', async () => {
+ const sourceRunId = 'wrun_01ARZ3NDEKTSV4RRFFQ69G5FAV';
+ await start(validWorkflow, [], { replayedFromRunId: sourceRunId });
+
+ expect(mockEventsCreate).toHaveBeenCalledWith(
+ expect.stringMatching(/^wrun_/),
+ expect.objectContaining({
+ eventType: 'run_created',
+ eventData: expect.objectContaining({
+ executionContext: expect.objectContaining({
+ replayedFromRunId: sourceRunId,
+ }),
+ }),
+ }),
+ expect.anything()
+ );
+ });
+
+ it('omits replayedFromRunId from executionContext when not provided', async () => {
+ await start(validWorkflow, []);
+
+ const eventData = mockEventsCreate.mock.calls[0]?.[1]?.eventData;
+ expect(eventData.executionContext).not.toHaveProperty(
+ 'replayedFromRunId'
+ );
+ });
+
+ it('rejects a replayedFromRunId without the wrun_ prefix', async () => {
+ await expect(
+ start(validWorkflow, [], { replayedFromRunId: 'not-a-run-id' })
+ ).rejects.toThrow(/replayedFromRunId must be a run ID/);
+ expect(mockEventsCreate).not.toHaveBeenCalled();
+ });
+
+ it('rejects a wrun_-prefixed value whose body is not a valid ULID', async () => {
+ await expect(
+ start(validWorkflow, [], {
+ replayedFromRunId: `wrun_${'x'.repeat(300)}`,
+ })
+ ).rejects.toThrow(/replayedFromRunId must be a run ID/);
+ expect(mockEventsCreate).not.toHaveBeenCalled();
+ });
+
+ it('rejects a non-string replayedFromRunId', async () => {
+ await expect(
+ start(validWorkflow, [], {
+ // Types forbid this, but JS callers can still pass it.
+ replayedFromRunId: 12345 as unknown as string,
+ })
+ ).rejects.toThrow(/replayedFromRunId must be a run ID/);
+ expect(mockEventsCreate).not.toHaveBeenCalled();
+ });
+ });
+
  describe('overload type inference', () => {
  // Type-only assertions that don't execute start() at runtime.
  // We use expectTypeOf on the function signature's return type directly.

packages/core/src/runtime/start.ts

@@ -6,6 +6,7 @@ import {
  SPEC_VERSION_SUPPORTS_ATTRIBUTES,
  SPEC_VERSION_SUPPORTS_CBOR_QUEUE_TRANSPORT,
  SPEC_VERSION_SUPPORTS_COMPRESSION,
+ workflowRunIdSchema,
 } from '@workflow/world';
 import { monotonicFactory } from 'ulid';
 import { normalizeAttributeChanges } from '../attribute-changes.js';
@@ -90,6 +91,20 @@ export interface StartOptionsBase {
  */
  allowReservedAttributes?: boolean;
 
+ /**
+ * The ID of an existing run this run is being replayed from, if any.
+ *
+ * Recorded on the new run's `executionContext` as `replayedFromRunId` so
+ * tooling (e.g. the dashboard runs list) can show that a run originated as
+ * a replay and link back to its source. Set automatically by
+ * {@link recreateRunFromExisting}; there's usually no reason to pass it
+ * directly.
+ *
+ * Must be a run ID: `wrun_` followed by a 26-char ULID. It's a foreign key
+ * to the source run, so `start()` validates the exact shape and rejects
+ * anything else rather than persist a lineage link that points at garbage.
+ */
+ replayedFromRunId?: string;
  /**
  * Queue namespace of the target deployment. Scopes the workflow queue
  * topic to `__{namespace}_wkf_workflow_*` (e.g. `'eve'`) instead of the
@@ -335,6 +350,19 @@ export async function start<TArgs extends unknown[], TResult>(
  }
  : {};
 
+ // `replayedFromRunId` is a foreign key to the source run; reject anything
+ // that isn't a real run ID so the lineage link can't point at garbage.
+ if (
+ opts.replayedFromRunId !== undefined &&
+ !workflowRunIdSchema.safeParse(opts.replayedFromRunId).success
+ ) {
+ throw new WorkflowRuntimeError(
+ `replayedFromRunId must be a run ID (wrun_<ulid>); received ${JSON.stringify(
+ String(opts.replayedFromRunId).slice(0, 64)
+ )}.`
+ );
+ }
+
  // Resolve encryption key for the new run. The runId has already been
  // generated above (client-generated ULID) and will be used for both
  // key derivation and the run_created event. The World implementation
@@ -372,6 +400,9 @@ export async function start<TArgs extends unknown[], TResult>(
  traceCarrier,
  workflowCoreVersion,
  features: { encryption: !!encryptionKey },
+ ...(opts.replayedFromRunId
+ ? { replayedFromRunId: opts.replayedFromRunId }
+ : {}),
  };
 
  // Call events.create (run_created) and queue in parallel.

packages/world/src/index.ts

@@ -125,6 +125,8 @@ export {
  DEFAULT_TIMESTAMP_THRESHOLD_PAST_MS,
  ulidToDate,
  validateUlidTimestamp,
+ workflowRunIdSchema,
 } from './ulid.js';
+export type { WorkflowRunId } from './ulid.js';
 export type * from './waits.js';
 export { WaitSchema, WaitStatusSchema } from './waits.js';

packages/world/src/ulid.ts

@@ -3,6 +3,16 @@ import { z } from 'zod';
 
 const UlidSchema = z.string().ulid();
 
+/**
+ * A workflow run ID: the `wrun_` prefix followed by a 26-char ULID (minted
+ * client-side in core's `start()`). Validates the exact shape — prefix plus a
+ * well-formed ULID — rather than a loose length bound, so callers can't smuggle
+ * arbitrary strings through APIs that persist a run ID verbatim.
+ */
+export const workflowRunIdSchema = z.templateLiteral(['wrun_', z.ulid()]);
+
+export type WorkflowRunId = z.infer<typeof workflowRunIdSchema>;
+
 /**
  * Default threshold for ULID timestamps in the past (24 hours).
  *

.changeset/replay-lineage-execution-context.md

@@ -0,0 +1,5 @@
+---
+'@workflow/core': minor
+---
+
+Record the source run on replays: `recreateRunFromExisting` now stamps `replayedFromRunId` into the new run's `executionContext` (and `start` accepts a matching option) so tooling can surface a run as a replay and link back to its origin.

packages/core/src/runtime/runs.test.ts

@@ -12,14 +12,27 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 // Mock version module to avoid missing generated file
 vi.mock('../version.js', () => ({ version: '0.0.0-test' }));
 
+// Stub `start` so recreateRunFromExisting can be tested for the options it
+// forwards without exercising the full run-creation pipeline (serialization,
+// telemetry, queueing).
+vi.mock('./start.js', () => ({ start: vi.fn() }));
+
+// Keep serialization real except for argument hydration, which needs a real
+// serialized payload we don't have in these unit tests.
+vi.mock('../serialization.js', async (importActual) => {
+ const actual = await importActual<typeof import('../serialization.js')>();
+ return { ...actual, hydrateWorkflowArguments: vi.fn().mockResolvedValue([]) };
+});
+
 import { registerSerializationClass } from '../class-serialization.js';
 import {
  dehydrateRunError,
  dehydrateStepReturnValue,
  hydrateStepReturnValue,
 } from '../serialization.js';
 import { Run } from './run.js';
-import { reenqueueRun, wakeUpRun } from './runs.js';
+import { recreateRunFromExisting, reenqueueRun, wakeUpRun } from './runs.js';
+import { start } from './start.js';
 import { setWorld } from './world.js';
 
 function createMockWorld(
@@ -155,6 +168,31 @@ describe('reenqueueRun', () => {
  });
 });
 
+describe('recreateRunFromExisting', () => {
+ afterEach(() => {
+ vi.mocked(start).mockReset();
+ });
+
+ it('forwards the source run id to start as replayedFromRunId', async () => {
+ const world = createMockWorld({
+ run: { runId: 'wrun_source', deploymentId: 'deploy_source' },
+ });
+ vi.mocked(start).mockResolvedValue({ runId: 'wrun_new' } as Run<unknown>);
+
+ const newRunId = await recreateRunFromExisting(world, 'wrun_source');
+
+ expect(newRunId).toBe('wrun_new');
+ expect(start).toHaveBeenCalledWith(
+ { workflowId: 'test-workflow' },
+ expect.any(Array),
+ expect.objectContaining({
+ replayedFromRunId: 'wrun_source',
+ deploymentId: 'deploy_source',
+ })
+ );
+ });
+});
+
 describe('Run.exists', () => {
  afterEach(() => {
  setWorld(undefined as unknown as World);

packages/core/src/runtime/runs.ts

@@ -105,6 +105,7 @@ export async function recreateRunFromExisting(
  deploymentId,
  world,
  specVersion,
+ replayedFromRunId: runId,
  namespace: options.namespace,
  }
  );

packages/core/src/runtime/start.test.ts

@@ -770,6 +770,89 @@ describe('start', () => {
  });
  });
 
+ describe('replay lineage (executionContext.replayedFromRunId)', () => {
+ let mockEventsCreate: ReturnType<typeof vi.fn>;
+ let mockQueue: ReturnType<typeof vi.fn>;
+
+ const validWorkflow = Object.assign(() => Promise.resolve('result'), {
+ workflowId: 'test-workflow',
+ });
+
+ beforeEach(() => {
+ mockEventsCreate = vi.fn().mockImplementation((runId) => {
+ return Promise.resolve({
+ run: { runId: runId ?? 'wrun_test123', status: 'pending' },
+ });
+ });
+ mockQueue = vi.fn().mockResolvedValue(undefined);
+
+ setWorld({
+ specVersion: SPEC_VERSION_CURRENT,
+ getDeploymentId: vi.fn().mockResolvedValue('deploy_123'),
+ events: { create: mockEventsCreate },
+ queue: mockQueue,
+ });
+ });
+
+ afterEach(() => {
+ setWorld(undefined);
+ vi.clearAllMocks();
+ });
+
+ it('records replayedFromRunId in executionContext when provided', async () => {
+ const sourceRunId = 'wrun_01ARZ3NDEKTSV4RRFFQ69G5FAV';
+ await start(validWorkflow, [], { replayedFromRunId: sourceRunId });
+
+ expect(mockEventsCreate).toHaveBeenCalledWith(
+ expect.stringMatching(/^wrun_/),
+ expect.objectContaining({
+ eventType: 'run_created',
+ eventData: expect.objectContaining({
+ executionContext: expect.objectContaining({
+ replayedFromRunId: sourceRunId,
+ }),
+ }),
+ }),
+ expect.anything()
+ );
+ });
+
+ it('omits replayedFromRunId from executionContext when not provided', async () => {
+ await start(validWorkflow, []);
+
+ const eventData = mockEventsCreate.mock.calls[0]?.[1]?.eventData;
+ expect(eventData.executionContext).not.toHaveProperty(
+ 'replayedFromRunId'
+ );
+ });
+
+ it('rejects a replayedFromRunId without the wrun_ prefix', async () => {
+ await expect(
+ start(validWorkflow, [], { replayedFromRunId: 'not-a-run-id' })
+ ).rejects.toThrow(/replayedFromRunId must be a run ID/);
+ expect(mockEventsCreate).not.toHaveBeenCalled();
+ });
+
+ it('rejects a wrun_-prefixed value whose body is not a valid ULID', async () => {
+ await expect(
+ start(validWorkflow, [], {
+ replayedFromRunId: `wrun_${'x'.repeat(300)}`,
+ })
+ ).rejects.toThrow(/replayedFromRunId must be a run ID/);
+ expect(mockEventsCreate).not.toHaveBeenCalled();
+ });
+
+ it('rejects a non-string replayedFromRunId', async () => {
+ await expect(
+ start(validWorkflow, [], {
+ // Types forbid this, but JS callers can still pass it.
+ replayedFromRunId: 12345 as unknown as string,
+ })
+ ).rejects.toThrow(/replayedFromRunId must be a run ID/);
+ expect(mockEventsCreate).not.toHaveBeenCalled();
+ });
+ });
+
  describe('overload type inference', () => {
  // Type-only assertions that don't execute start() at runtime.
  // We use expectTypeOf on the function signature's return type directly.

packages/core/src/runtime/start.ts

@@ -6,6 +6,7 @@ import {
  SPEC_VERSION_SUPPORTS_ATTRIBUTES,
  SPEC_VERSION_SUPPORTS_CBOR_QUEUE_TRANSPORT,
  SPEC_VERSION_SUPPORTS_COMPRESSION,
+ workflowRunIdSchema,
 } from '@workflow/world';
 import { monotonicFactory } from 'ulid';
 import { normalizeAttributeChanges } from '../attribute-changes.js';
@@ -90,6 +91,20 @@ export interface StartOptionsBase {
  */
  allowReservedAttributes?: boolean;
 
+ /**
+ * The ID of an existing run this run is being replayed from, if any.
+ *
+ * Recorded on the new run's `executionContext` as `replayedFromRunId` so
+ * tooling (e.g. the dashboard runs list) can show that a run originated as
+ * a replay and link back to its source. Set automatically by
+ * {@link recreateRunFromExisting}; there's usually no reason to pass it
+ * directly.
+ *
+ * Must be a run ID: `wrun_` followed by a 26-char ULID. It's a foreign key
+ * to the source run, so `start()` validates the exact shape and rejects
+ * anything else rather than persist a lineage link that points at garbage.
+ */
+ replayedFromRunId?: string;
  /**
  * Queue namespace of the target deployment. Scopes the workflow queue
  * topic to `__{namespace}_wkf_workflow_*` (e.g. `'eve'`) instead of the
@@ -335,6 +350,19 @@ export async function start<TArgs extends unknown[], TResult>(
  }
  : {};
 
+ // `replayedFromRunId` is a foreign key to the source run; reject anything
+ // that isn't a real run ID so the lineage link can't point at garbage.
+ if (
+ opts.replayedFromRunId !== undefined &&
+ !workflowRunIdSchema.safeParse(opts.replayedFromRunId).success
+ ) {
+ throw new WorkflowRuntimeError(
+ `replayedFromRunId must be a run ID (wrun_<ulid>); received ${JSON.stringify(
+ String(opts.replayedFromRunId).slice(0, 64)
+ )}.`
+ );
+ }
+
  // Resolve encryption key for the new run. The runId has already been
  // generated above (client-generated ULID) and will be used for both
  // key derivation and the run_created event. The World implementation
@@ -372,6 +400,9 @@ export async function start<TArgs extends unknown[], TResult>(
  traceCarrier,
  workflowCoreVersion,
  features: { encryption: !!encryptionKey },
+ ...(opts.replayedFromRunId
+ ? { replayedFromRunId: opts.replayedFromRunId }
+ : {}),
  };
 
  // Call events.create (run_created) and queue in parallel.

packages/world/src/index.ts

@@ -125,6 +125,8 @@ export {
  DEFAULT_TIMESTAMP_THRESHOLD_PAST_MS,
  ulidToDate,
  validateUlidTimestamp,
+ workflowRunIdSchema,
 } from './ulid.js';
+export type { WorkflowRunId } from './ulid.js';
 export type * from './waits.js';
 export { WaitSchema, WaitStatusSchema } from './waits.js';

packages/world/src/ulid.ts

@@ -3,6 +3,16 @@ import { z } from 'zod';
 
 const UlidSchema = z.string().ulid();
 
+/**
+ * A workflow run ID: the `wrun_` prefix followed by a 26-char ULID (minted
+ * client-side in core's `start()`). Validates the exact shape — prefix plus a
+ * well-formed ULID — rather than a loose length bound, so callers can't smuggle
+ * arbitrary strings through APIs that persist a run ID verbatim.
+ */
+export const workflowRunIdSchema = z.templateLiteral(['wrun_', z.ulid()]);
+
+export type WorkflowRunId = z.infer<typeof workflowRunIdSchema>;
+
 /**
  * Default threshold for ULID timestamps in the past (24 hours).
  *

.changeset/replay-lineage-execution-context.md

@@ -0,0 +1,5 @@
+---
+'@workflow/core': minor
+---
+
+Record the source run on replays: `recreateRunFromExisting` now stamps `replayedFromRunId` into the new run's `executionContext` (and `start` accepts a matching option) so tooling can surface a run as a replay and link back to its origin.

packages/core/src/runtime/runs.test.ts

@@ -12,14 +12,27 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 // Mock version module to avoid missing generated file
 vi.mock('../version.js', () => ({ version: '0.0.0-test' }));
 
+// Stub `start` so recreateRunFromExisting can be tested for the options it
+// forwards without exercising the full run-creation pipeline (serialization,
+// telemetry, queueing).
+vi.mock('./start.js', () => ({ start: vi.fn() }));
+
+// Keep serialization real except for argument hydration, which needs a real
+// serialized payload we don't have in these unit tests.
+vi.mock('../serialization.js', async (importActual) => {
+ const actual = await importActual<typeof import('../serialization.js')>();
+ return { ...actual, hydrateWorkflowArguments: vi.fn().mockResolvedValue([]) };
+});
+
 import { registerSerializationClass } from '../class-serialization.js';
 import {
  dehydrateRunError,
  dehydrateStepReturnValue,
  hydrateStepReturnValue,
 } from '../serialization.js';
 import { Run } from './run.js';
-import { reenqueueRun, wakeUpRun } from './runs.js';
+import { recreateRunFromExisting, reenqueueRun, wakeUpRun } from './runs.js';
+import { start } from './start.js';
 import { setWorld } from './world.js';
 
 function createMockWorld(
@@ -155,6 +168,31 @@ describe('reenqueueRun', () => {
  });
 });
 
+describe('recreateRunFromExisting', () => {
+ afterEach(() => {
+ vi.mocked(start).mockReset();
+ });
+
+ it('forwards the source run id to start as replayedFromRunId', async () => {
+ const world = createMockWorld({
+ run: { runId: 'wrun_source', deploymentId: 'deploy_source' },
+ });
+ vi.mocked(start).mockResolvedValue({ runId: 'wrun_new' } as Run<unknown>);
+
+ const newRunId = await recreateRunFromExisting(world, 'wrun_source');
+
+ expect(newRunId).toBe('wrun_new');
+ expect(start).toHaveBeenCalledWith(
+ { workflowId: 'test-workflow' },
+ expect.any(Array),
+ expect.objectContaining({
+ replayedFromRunId: 'wrun_source',
+ deploymentId: 'deploy_source',
+ })
+ );
+ });
+});
+
 describe('Run.exists', () => {
  afterEach(() => {
  setWorld(undefined as unknown as World);

packages/core/src/runtime/runs.ts

@@ -105,6 +105,7 @@ export async function recreateRunFromExisting(
  deploymentId,
  world,
  specVersion,
+ replayedFromRunId: runId,
  namespace: options.namespace,
  }
  );

packages/core/src/runtime/start.test.ts

@@ -770,6 +770,89 @@ describe('start', () => {
  });
  });
 
+ describe('replay lineage (executionContext.replayedFromRunId)', () => {
+ let mockEventsCreate: ReturnType<typeof vi.fn>;
+ let mockQueue: ReturnType<typeof vi.fn>;
+
+ const validWorkflow = Object.assign(() => Promise.resolve('result'), {
+ workflowId: 'test-workflow',
+ });
+
+ beforeEach(() => {
+ mockEventsCreate = vi.fn().mockImplementation((runId) => {
+ return Promise.resolve({
+ run: { runId: runId ?? 'wrun_test123', status: 'pending' },
+ });
+ });
+ mockQueue = vi.fn().mockResolvedValue(undefined);
+
+ setWorld({
+ specVersion: SPEC_VERSION_CURRENT,
+ getDeploymentId: vi.fn().mockResolvedValue('deploy_123'),
+ events: { create: mockEventsCreate },
+ queue: mockQueue,
+ });
+ });
+
+ afterEach(() => {
+ setWorld(undefined);
+ vi.clearAllMocks();
+ });
+
+ it('records replayedFromRunId in executionContext when provided', async () => {
+ const sourceRunId = 'wrun_01ARZ3NDEKTSV4RRFFQ69G5FAV';
+ await start(validWorkflow, [], { replayedFromRunId: sourceRunId });
+
+ expect(mockEventsCreate).toHaveBeenCalledWith(
+ expect.stringMatching(/^wrun_/),
+ expect.objectContaining({
+ eventType: 'run_created',
+ eventData: expect.objectContaining({
+ executionContext: expect.objectContaining({
+ replayedFromRunId: sourceRunId,
+ }),
+ }),
+ }),
+ expect.anything()
+ );
+ });
+
+ it('omits replayedFromRunId from executionContext when not provided', async () => {
+ await start(validWorkflow, []);
+
+ const eventData = mockEventsCreate.mock.calls[0]?.[1]?.eventData;
+ expect(eventData.executionContext).not.toHaveProperty(
+ 'replayedFromRunId'
+ );
+ });
+
+ it('rejects a replayedFromRunId without the wrun_ prefix', async () => {
+ await expect(
+ start(validWorkflow, [], { replayedFromRunId: 'not-a-run-id' })
+ ).rejects.toThrow(/replayedFromRunId must be a run ID/);
+ expect(mockEventsCreate).not.toHaveBeenCalled();
+ });
+
+ it('rejects a wrun_-prefixed value whose body is not a valid ULID', async () => {
+ await expect(
+ start(validWorkflow, [], {
+ replayedFromRunId: `wrun_${'x'.repeat(300)}`,
+ })
+ ).rejects.toThrow(/replayedFromRunId must be a run ID/);
+ expect(mockEventsCreate).not.toHaveBeenCalled();
+ });
+
+ it('rejects a non-string replayedFromRunId', async () => {
+ await expect(
+ start(validWorkflow, [], {
+ // Types forbid this, but JS callers can still pass it.
+ replayedFromRunId: 12345 as unknown as string,
+ })
+ ).rejects.toThrow(/replayedFromRunId must be a run ID/);
+ expect(mockEventsCreate).not.toHaveBeenCalled();
+ });
+ });
+
  describe('overload type inference', () => {
  // Type-only assertions that don't execute start() at runtime.
  // We use expectTypeOf on the function signature's return type directly.

packages/core/src/runtime/start.ts

@@ -6,6 +6,7 @@ import {
  SPEC_VERSION_SUPPORTS_ATTRIBUTES,
  SPEC_VERSION_SUPPORTS_CBOR_QUEUE_TRANSPORT,
  SPEC_VERSION_SUPPORTS_COMPRESSION,
+ workflowRunIdSchema,
 } from '@workflow/world';
 import { monotonicFactory } from 'ulid';
 import { normalizeAttributeChanges } from '../attribute-changes.js';
@@ -90,6 +91,20 @@ export interface StartOptionsBase {
  */
  allowReservedAttributes?: boolean;
 
+ /**
+ * The ID of an existing run this run is being replayed from, if any.
+ *
+ * Recorded on the new run's `executionContext` as `replayedFromRunId` so
+ * tooling (e.g. the dashboard runs list) can show that a run originated as
+ * a replay and link back to its source. Set automatically by
+ * {@link recreateRunFromExisting}; there's usually no reason to pass it
+ * directly.
+ *
+ * Must be a run ID: `wrun_` followed by a 26-char ULID. It's a foreign key
+ * to the source run, so `start()` validates the exact shape and rejects
+ * anything else rather than persist a lineage link that points at garbage.
+ */
+ replayedFromRunId?: string;
  /**
  * Queue namespace of the target deployment. Scopes the workflow queue
  * topic to `__{namespace}_wkf_workflow_*` (e.g. `'eve'`) instead of the
@@ -335,6 +350,19 @@ export async function start<TArgs extends unknown[], TResult>(
  }
  : {};
 
+ // `replayedFromRunId` is a foreign key to the source run; reject anything
+ // that isn't a real run ID so the lineage link can't point at garbage.
+ if (
+ opts.replayedFromRunId !== undefined &&
+ !workflowRunIdSchema.safeParse(opts.replayedFromRunId).success
+ ) {
+ throw new WorkflowRuntimeError(
+ `replayedFromRunId must be a run ID (wrun_<ulid>); received ${JSON.stringify(
+ String(opts.replayedFromRunId).slice(0, 64)
+ )}.`
+ );
+ }
+
  // Resolve encryption key for the new run. The runId has already been
  // generated above (client-generated ULID) and will be used for both
  // key derivation and the run_created event. The World implementation
@@ -372,6 +400,9 @@ export async function start<TArgs extends unknown[], TResult>(
  traceCarrier,
  workflowCoreVersion,
  features: { encryption: !!encryptionKey },
+ ...(opts.replayedFromRunId
+ ? { replayedFromRunId: opts.replayedFromRunId }
+ : {}),
  };
 
  // Call events.create (run_created) and queue in parallel.

packages/world/src/index.ts

@@ -125,6 +125,8 @@ export {
  DEFAULT_TIMESTAMP_THRESHOLD_PAST_MS,
  ulidToDate,
  validateUlidTimestamp,
+ workflowRunIdSchema,
 } from './ulid.js';
+export type { WorkflowRunId } from './ulid.js';
 export type * from './waits.js';
 export { WaitSchema, WaitStatusSchema } from './waits.js';

packages/world/src/ulid.ts

@@ -3,6 +3,16 @@ import { z } from 'zod';
 
 const UlidSchema = z.string().ulid();
 
+/**
+ * A workflow run ID: the `wrun_` prefix followed by a 26-char ULID (minted
+ * client-side in core's `start()`). Validates the exact shape — prefix plus a
+ * well-formed ULID — rather than a loose length bound, so callers can't smuggle
+ * arbitrary strings through APIs that persist a run ID verbatim.
+ */
+export const workflowRunIdSchema = z.templateLiteral(['wrun_', z.ulid()]);
+
+export type WorkflowRunId = z.infer<typeof workflowRunIdSchema>;
+
 /**
  * Default threshold for ULID timestamps in the past (24 hours).
  *

.changeset/replay-lineage-execution-context.md

@@ -0,0 +1,5 @@
+---
+'@workflow/core': minor
+---
+
+Record the source run on replays: `recreateRunFromExisting` now stamps `replayedFromRunId` into the new run's `executionContext` (and `start` accepts a matching option) so tooling can surface a run as a replay and link back to its origin.

packages/core/src/runtime/runs.test.ts

@@ -12,14 +12,27 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 // Mock version module to avoid missing generated file
 vi.mock('../version.js', () => ({ version: '0.0.0-test' }));
 
+// Stub `start` so recreateRunFromExisting can be tested for the options it
+// forwards without exercising the full run-creation pipeline (serialization,
+// telemetry, queueing).
+vi.mock('./start.js', () => ({ start: vi.fn() }));
+
+// Keep serialization real except for argument hydration, which needs a real
+// serialized payload we don't have in these unit tests.
+vi.mock('../serialization.js', async (importActual) => {
+ const actual = await importActual<typeof import('../serialization.js')>();
+ return { ...actual, hydrateWorkflowArguments: vi.fn().mockResolvedValue([]) };
+});
+
 import { registerSerializationClass } from '../class-serialization.js';
 import {
  dehydrateRunError,
  dehydrateStepReturnValue,
  hydrateStepReturnValue,
 } from '../serialization.js';
 import { Run } from './run.js';
-import { reenqueueRun, wakeUpRun } from './runs.js';
+import { recreateRunFromExisting, reenqueueRun, wakeUpRun } from './runs.js';
+import { start } from './start.js';
 import { setWorld } from './world.js';
 
 function createMockWorld(
@@ -155,6 +168,31 @@ describe('reenqueueRun', () => {
  });
 });
 
+describe('recreateRunFromExisting', () => {
+ afterEach(() => {
+ vi.mocked(start).mockReset();
+ });
+
+ it('forwards the source run id to start as replayedFromRunId', async () => {
+ const world = createMockWorld({
+ run: { runId: 'wrun_source', deploymentId: 'deploy_source' },
+ });
+ vi.mocked(start).mockResolvedValue({ runId: 'wrun_new' } as Run<unknown>);
+
+ const newRunId = await recreateRunFromExisting(world, 'wrun_source');
+
+ expect(newRunId).toBe('wrun_new');
+ expect(start).toHaveBeenCalledWith(
+ { workflowId: 'test-workflow' },
+ expect.any(Array),
+ expect.objectContaining({
+ replayedFromRunId: 'wrun_source',
+ deploymentId: 'deploy_source',
+ })
+ );
+ });
+});
+
 describe('Run.exists', () => {
  afterEach(() => {
  setWorld(undefined as unknown as World);

packages/core/src/runtime/runs.ts

@@ -105,6 +105,7 @@ export async function recreateRunFromExisting(
  deploymentId,
  world,
  specVersion,
+ replayedFromRunId: runId,
  namespace: options.namespace,
  }
  );

packages/core/src/runtime/start.test.ts

@@ -770,6 +770,89 @@ describe('start', () => {
  });
  });
 
+ describe('replay lineage (executionContext.replayedFromRunId)', () => {
+ let mockEventsCreate: ReturnType<typeof vi.fn>;
+ let mockQueue: ReturnType<typeof vi.fn>;
+
+ const validWorkflow = Object.assign(() => Promise.resolve('result'), {
+ workflowId: 'test-workflow',
+ });
+
+ beforeEach(() => {
+ mockEventsCreate = vi.fn().mockImplementation((runId) => {
+ return Promise.resolve({
+ run: { runId: runId ?? 'wrun_test123', status: 'pending' },
+ });
+ });
+ mockQueue = vi.fn().mockResolvedValue(undefined);
+
+ setWorld({
+ specVersion: SPEC_VERSION_CURRENT,
+ getDeploymentId: vi.fn().mockResolvedValue('deploy_123'),
+ events: { create: mockEventsCreate },
+ queue: mockQueue,
+ });
+ });
+
+ afterEach(() => {
+ setWorld(undefined);
+ vi.clearAllMocks();
+ });
+
+ it('records replayedFromRunId in executionContext when provided', async () => {
+ const sourceRunId = 'wrun_01ARZ3NDEKTSV4RRFFQ69G5FAV';
+ await start(validWorkflow, [], { replayedFromRunId: sourceRunId });
+
+ expect(mockEventsCreate).toHaveBeenCalledWith(
+ expect.stringMatching(/^wrun_/),
+ expect.objectContaining({
+ eventType: 'run_created',
+ eventData: expect.objectContaining({
+ executionContext: expect.objectContaining({
+ replayedFromRunId: sourceRunId,
+ }),
+ }),
+ }),
+ expect.anything()
+ );
+ });
+
+ it('omits replayedFromRunId from executionContext when not provided', async () => {
+ await start(validWorkflow, []);
+
+ const eventData = mockEventsCreate.mock.calls[0]?.[1]?.eventData;
+ expect(eventData.executionContext).not.toHaveProperty(
+ 'replayedFromRunId'
+ );
+ });
+
+ it('rejects a replayedFromRunId without the wrun_ prefix', async () => {
+ await expect(
+ start(validWorkflow, [], { replayedFromRunId: 'not-a-run-id' })
+ ).rejects.toThrow(/replayedFromRunId must be a run ID/);
+ expect(mockEventsCreate).not.toHaveBeenCalled();
+ });
+
+ it('rejects a wrun_-prefixed value whose body is not a valid ULID', async () => {
+ await expect(
+ start(validWorkflow, [], {
+ replayedFromRunId: `wrun_${'x'.repeat(300)}`,
+ })
+ ).rejects.toThrow(/replayedFromRunId must be a run ID/);
+ expect(mockEventsCreate).not.toHaveBeenCalled();
+ });
+
+ it('rejects a non-string replayedFromRunId', async () => {
+ await expect(
+ start(validWorkflow, [], {
+ // Types forbid this, but JS callers can still pass it.
+ replayedFromRunId: 12345 as unknown as string,
+ })
+ ).rejects.toThrow(/replayedFromRunId must be a run ID/);
+ expect(mockEventsCreate).not.toHaveBeenCalled();
+ });
+ });
+
  describe('overload type inference', () => {
  // Type-only assertions that don't execute start() at runtime.
  // We use expectTypeOf on the function signature's return type directly.

packages/core/src/runtime/start.ts

@@ -6,6 +6,7 @@ import {
  SPEC_VERSION_SUPPORTS_ATTRIBUTES,
  SPEC_VERSION_SUPPORTS_CBOR_QUEUE_TRANSPORT,
  SPEC_VERSION_SUPPORTS_COMPRESSION,
+ workflowRunIdSchema,
 } from '@workflow/world';
 import { monotonicFactory } from 'ulid';
 import { normalizeAttributeChanges } from '../attribute-changes.js';
@@ -90,6 +91,20 @@ export interface StartOptionsBase {
  */
  allowReservedAttributes?: boolean;
 
+ /**
+ * The ID of an existing run this run is being replayed from, if any.
+ *
+ * Recorded on the new run's `executionContext` as `replayedFromRunId` so
+ * tooling (e.g. the dashboard runs list) can show that a run originated as
+ * a replay and link back to its source. Set automatically by
+ * {@link recreateRunFromExisting}; there's usually no reason to pass it
+ * directly.
+ *
+ * Must be a run ID: `wrun_` followed by a 26-char ULID. It's a foreign key
+ * to the source run, so `start()` validates the exact shape and rejects
+ * anything else rather than persist a lineage link that points at garbage.
+ */
+ replayedFromRunId?: string;
  /**
  * Queue namespace of the target deployment. Scopes the workflow queue
  * topic to `__{namespace}_wkf_workflow_*` (e.g. `'eve'`) instead of the
@@ -335,6 +350,19 @@ export async function start<TArgs extends unknown[], TResult>(
  }
  : {};
 
+ // `replayedFromRunId` is a foreign key to the source run; reject anything
+ // that isn't a real run ID so the lineage link can't point at garbage.
+ if (
+ opts.replayedFromRunId !== undefined &&
+ !workflowRunIdSchema.safeParse(opts.replayedFromRunId).success
+ ) {
+ throw new WorkflowRuntimeError(
+ `replayedFromRunId must be a run ID (wrun_<ulid>); received ${JSON.stringify(
+ String(opts.replayedFromRunId).slice(0, 64)
+ )}.`
+ );
+ }
+
  // Resolve encryption key for the new run. The runId has already been
  // generated above (client-generated ULID) and will be used for both
  // key derivation and the run_created event. The World implementation
@@ -372,6 +400,9 @@ export async function start<TArgs extends unknown[], TResult>(
  traceCarrier,
  workflowCoreVersion,
  features: { encryption: !!encryptionKey },
+ ...(opts.replayedFromRunId
+ ? { replayedFromRunId: opts.replayedFromRunId }
+ : {}),
  };
 
  // Call events.create (run_created) and queue in parallel.

packages/world/src/index.ts

@@ -125,6 +125,8 @@ export {
  DEFAULT_TIMESTAMP_THRESHOLD_PAST_MS,
  ulidToDate,
  validateUlidTimestamp,
+ workflowRunIdSchema,
 } from './ulid.js';
+export type { WorkflowRunId } from './ulid.js';
 export type * from './waits.js';
 export { WaitSchema, WaitStatusSchema } from './waits.js';

packages/world/src/ulid.ts

@@ -3,6 +3,16 @@ import { z } from 'zod';
 
 const UlidSchema = z.string().ulid();
 
+/**
+ * A workflow run ID: the `wrun_` prefix followed by a 26-char ULID (minted
+ * client-side in core's `start()`). Validates the exact shape — prefix plus a
+ * well-formed ULID — rather than a loose length bound, so callers can't smuggle
+ * arbitrary strings through APIs that persist a run ID verbatim.
+ */
+export const workflowRunIdSchema = z.templateLiteral(['wrun_', z.ulid()]);
+
+export type WorkflowRunId = z.infer<typeof workflowRunIdSchema>;
+
 /**
  * Default threshold for ULID timestamps in the past (24 hours).
  *

.changeset/replay-lineage-execution-context.md

@@ -0,0 +1,5 @@
+---
+'@workflow/core': minor
+---
+
+Record the source run on replays: `recreateRunFromExisting` now stamps `replayedFromRunId` into the new run's `executionContext` (and `start` accepts a matching option) so tooling can surface a run as a replay and link back to its origin.

packages/core/src/runtime/runs.test.ts

@@ -12,14 +12,27 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 // Mock version module to avoid missing generated file
 vi.mock('../version.js', () => ({ version: '0.0.0-test' }));
 
+// Stub `start` so recreateRunFromExisting can be tested for the options it
+// forwards without exercising the full run-creation pipeline (serialization,
+// telemetry, queueing).
+vi.mock('./start.js', () => ({ start: vi.fn() }));
+
+// Keep serialization real except for argument hydration, which needs a real
+// serialized payload we don't have in these unit tests.
+vi.mock('../serialization.js', async (importActual) => {
+ const actual = await importActual<typeof import('../serialization.js')>();
+ return { ...actual, hydrateWorkflowArguments: vi.fn().mockResolvedValue([]) };
+});
+
 import { registerSerializationClass } from '../class-serialization.js';
 import {
  dehydrateRunError,
  dehydrateStepReturnValue,
  hydrateStepReturnValue,
 } from '../serialization.js';
 import { Run } from './run.js';
-import { reenqueueRun, wakeUpRun } from './runs.js';
+import { recreateRunFromExisting, reenqueueRun, wakeUpRun } from './runs.js';
+import { start } from './start.js';
 import { setWorld } from './world.js';
 
 function createMockWorld(
@@ -155,6 +168,31 @@ describe('reenqueueRun', () => {
  });
 });
 
+describe('recreateRunFromExisting', () => {
+ afterEach(() => {
+ vi.mocked(start).mockReset();
+ });
+
+ it('forwards the source run id to start as replayedFromRunId', async () => {
+ const world = createMockWorld({
+ run: { runId: 'wrun_source', deploymentId: 'deploy_source' },
+ });
+ vi.mocked(start).mockResolvedValue({ runId: 'wrun_new' } as Run<unknown>);
+
+ const newRunId = await recreateRunFromExisting(world, 'wrun_source');
+
+ expect(newRunId).toBe('wrun_new');
+ expect(start).toHaveBeenCalledWith(
+ { workflowId: 'test-workflow' },
+ expect.any(Array),
+ expect.objectContaining({
+ replayedFromRunId: 'wrun_source',
+ deploymentId: 'deploy_source',
+ })
+ );
+ });
+});
+
 describe('Run.exists', () => {
  afterEach(() => {
  setWorld(undefined as unknown as World);

packages/core/src/runtime/runs.ts

@@ -105,6 +105,7 @@ export async function recreateRunFromExisting(
  deploymentId,
  world,
  specVersion,
+ replayedFromRunId: runId,
  namespace: options.namespace,
  }
  );

packages/core/src/runtime/start.test.ts

@@ -770,6 +770,89 @@ describe('start', () => {
  });
  });
 
+ describe('replay lineage (executionContext.replayedFromRunId)', () => {
+ let mockEventsCreate: ReturnType<typeof vi.fn>;
+ let mockQueue: ReturnType<typeof vi.fn>;
+
+ const validWorkflow = Object.assign(() => Promise.resolve('result'), {
+ workflowId: 'test-workflow',
+ });
+
+ beforeEach(() => {
+ mockEventsCreate = vi.fn().mockImplementation((runId) => {
+ return Promise.resolve({
+ run: { runId: runId ?? 'wrun_test123', status: 'pending' },
+ });
+ });
+ mockQueue = vi.fn().mockResolvedValue(undefined);
+
+ setWorld({
+ specVersion: SPEC_VERSION_CURRENT,
+ getDeploymentId: vi.fn().mockResolvedValue('deploy_123'),
+ events: { create: mockEventsCreate },
+ queue: mockQueue,
+ });
+ });
+
+ afterEach(() => {
+ setWorld(undefined);
+ vi.clearAllMocks();
+ });
+
+ it('records replayedFromRunId in executionContext when provided', async () => {
+ const sourceRunId = 'wrun_01ARZ3NDEKTSV4RRFFQ69G5FAV';
+ await start(validWorkflow, [], { replayedFromRunId: sourceRunId });
+
+ expect(mockEventsCreate).toHaveBeenCalledWith(
+ expect.stringMatching(/^wrun_/),
+ expect.objectContaining({
+ eventType: 'run_created',
+ eventData: expect.objectContaining({
+ executionContext: expect.objectContaining({
+ replayedFromRunId: sourceRunId,
+ }),
+ }),
+ }),
+ expect.anything()
+ );
+ });
+
+ it('omits replayedFromRunId from executionContext when not provided', async () => {
+ await start(validWorkflow, []);
+
+ const eventData = mockEventsCreate.mock.calls[0]?.[1]?.eventData;
+ expect(eventData.executionContext).not.toHaveProperty(
+ 'replayedFromRunId'
+ );
+ });
+
+ it('rejects a replayedFromRunId without the wrun_ prefix', async () => {
+ await expect(
+ start(validWorkflow, [], { replayedFromRunId: 'not-a-run-id' })
+ ).rejects.toThrow(/replayedFromRunId must be a run ID/);
+ expect(mockEventsCreate).not.toHaveBeenCalled();
+ });
+
+ it('rejects a wrun_-prefixed value whose body is not a valid ULID', async () => {
+ await expect(
+ start(validWorkflow, [], {
+ replayedFromRunId: `wrun_${'x'.repeat(300)}`,
+ })
+ ).rejects.toThrow(/replayedFromRunId must be a run ID/);
+ expect(mockEventsCreate).not.toHaveBeenCalled();
+ });
+
+ it('rejects a non-string replayedFromRunId', async () => {
+ await expect(
+ start(validWorkflow, [], {
+ // Types forbid this, but JS callers can still pass it.
+ replayedFromRunId: 12345 as unknown as string,
+ })
+ ).rejects.toThrow(/replayedFromRunId must be a run ID/);
+ expect(mockEventsCreate).not.toHaveBeenCalled();
+ });
+ });
+
  describe('overload type inference', () => {
  // Type-only assertions that don't execute start() at runtime.
  // We use expectTypeOf on the function signature's return type directly.

packages/core/src/runtime/start.ts

@@ -6,6 +6,7 @@ import {
  SPEC_VERSION_SUPPORTS_ATTRIBUTES,
  SPEC_VERSION_SUPPORTS_CBOR_QUEUE_TRANSPORT,
  SPEC_VERSION_SUPPORTS_COMPRESSION,
+ workflowRunIdSchema,
 } from '@workflow/world';
 import { monotonicFactory } from 'ulid';
 import { normalizeAttributeChanges } from '../attribute-changes.js';
@@ -90,6 +91,20 @@ export interface StartOptionsBase {
  */
  allowReservedAttributes?: boolean;
 
+ /**
+ * The ID of an existing run this run is being replayed from, if any.
+ *
+ * Recorded on the new run's `executionContext` as `replayedFromRunId` so
+ * tooling (e.g. the dashboard runs list) can show that a run originated as
+ * a replay and link back to its source. Set automatically by
+ * {@link recreateRunFromExisting}; there's usually no reason to pass it
+ * directly.
+ *
+ * Must be a run ID: `wrun_` followed by a 26-char ULID. It's a foreign key
+ * to the source run, so `start()` validates the exact shape and rejects
+ * anything else rather than persist a lineage link that points at garbage.
+ */
+ replayedFromRunId?: string;
  /**
  * Queue namespace of the target deployment. Scopes the workflow queue
  * topic to `__{namespace}_wkf_workflow_*` (e.g. `'eve'`) instead of the
@@ -335,6 +350,19 @@ export async function start<TArgs extends unknown[], TResult>(
  }
  : {};
 
+ // `replayedFromRunId` is a foreign key to the source run; reject anything
+ // that isn't a real run ID so the lineage link can't point at garbage.
+ if (
+ opts.replayedFromRunId !== undefined &&
+ !workflowRunIdSchema.safeParse(opts.replayedFromRunId).success
+ ) {
+ throw new WorkflowRuntimeError(
+ `replayedFromRunId must be a run ID (wrun_<ulid>); received ${JSON.stringify(
+ String(opts.replayedFromRunId).slice(0, 64)
+ )}.`
+ );
+ }
+
  // Resolve encryption key for the new run. The runId has already been
  // generated above (client-generated ULID) and will be used for both
  // key derivation and the run_created event. The World implementation
@@ -372,6 +400,9 @@ export async function start<TArgs extends unknown[], TResult>(
  traceCarrier,
  workflowCoreVersion,
  features: { encryption: !!encryptionKey },
+ ...(opts.replayedFromRunId
+ ? { replayedFromRunId: opts.replayedFromRunId }
+ : {}),
  };
 
  // Call events.create (run_created) and queue in parallel.

packages/world/src/index.ts

@@ -125,6 +125,8 @@ export {
  DEFAULT_TIMESTAMP_THRESHOLD_PAST_MS,
  ulidToDate,
  validateUlidTimestamp,
+ workflowRunIdSchema,
 } from './ulid.js';
+export type { WorkflowRunId } from './ulid.js';
 export type * from './waits.js';
 export { WaitSchema, WaitStatusSchema } from './waits.js';

packages/world/src/ulid.ts

@@ -3,6 +3,16 @@ import { z } from 'zod';
 
 const UlidSchema = z.string().ulid();
 
+/**
+ * A workflow run ID: the `wrun_` prefix followed by a 26-char ULID (minted
+ * client-side in core's `start()`). Validates the exact shape — prefix plus a
+ * well-formed ULID — rather than a loose length bound, so callers can't smuggle
+ * arbitrary strings through APIs that persist a run ID verbatim.
+ */
+export const workflowRunIdSchema = z.templateLiteral(['wrun_', z.ulid()]);
+
+export type WorkflowRunId = z.infer<typeof workflowRunIdSchema>;
+
 /**
  * Default threshold for ULID timestamps in the past (24 hours).
  *

.changeset/replay-lineage-execution-context.md

@@ -0,0 +1,5 @@
+---
+'@workflow/core': minor
+---
+
+Record the source run on replays: `recreateRunFromExisting` now stamps `replayedFromRunId` into the new run's `executionContext` (and `start` accepts a matching option) so tooling can surface a run as a replay and link back to its origin.

packages/core/src/runtime/runs.test.ts

@@ -12,14 +12,27 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 // Mock version module to avoid missing generated file
 vi.mock('../version.js', () => ({ version: '0.0.0-test' }));
 
+// Stub `start` so recreateRunFromExisting can be tested for the options it
+// forwards without exercising the full run-creation pipeline (serialization,
+// telemetry, queueing).
+vi.mock('./start.js', () => ({ start: vi.fn() }));
+
+// Keep serialization real except for argument hydration, which needs a real
+// serialized payload we don't have in these unit tests.
+vi.mock('../serialization.js', async (importActual) => {
+ const actual = await importActual<typeof import('../serialization.js')>();
+ return { ...actual, hydrateWorkflowArguments: vi.fn().mockResolvedValue([]) };
+});
+
 import { registerSerializationClass } from '../class-serialization.js';
 import {
  dehydrateRunError,
  dehydrateStepReturnValue,
  hydrateStepReturnValue,
 } from '../serialization.js';
 import { Run } from './run.js';
-import { reenqueueRun, wakeUpRun } from './runs.js';
+import { recreateRunFromExisting, reenqueueRun, wakeUpRun } from './runs.js';
+import { start } from './start.js';
 import { setWorld } from './world.js';
 
 function createMockWorld(
@@ -155,6 +168,31 @@ describe('reenqueueRun', () => {
  });
 });
 
+describe('recreateRunFromExisting', () => {
+ afterEach(() => {
+ vi.mocked(start).mockReset();
+ });
+
+ it('forwards the source run id to start as replayedFromRunId', async () => {
+ const world = createMockWorld({
+ run: { runId: 'wrun_source', deploymentId: 'deploy_source' },
+ });
+ vi.mocked(start).mockResolvedValue({ runId: 'wrun_new' } as Run<unknown>);
+
+ const newRunId = await recreateRunFromExisting(world, 'wrun_source');
+
+ expect(newRunId).toBe('wrun_new');
+ expect(start).toHaveBeenCalledWith(
+ { workflowId: 'test-workflow' },
+ expect.any(Array),
+ expect.objectContaining({
+ replayedFromRunId: 'wrun_source',
+ deploymentId: 'deploy_source',
+ })
+ );
+ });
+});
+
 describe('Run.exists', () => {
  afterEach(() => {
  setWorld(undefined as unknown as World);

packages/core/src/runtime/runs.ts

@@ -105,6 +105,7 @@ export async function recreateRunFromExisting(
  deploymentId,
  world,
  specVersion,
+ replayedFromRunId: runId,
  namespace: options.namespace,
  }
  );

packages/core/src/runtime/start.test.ts

@@ -770,6 +770,89 @@ describe('start', () => {
  });
  });
 
+ describe('replay lineage (executionContext.replayedFromRunId)', () => {
+ let mockEventsCreate: ReturnType<typeof vi.fn>;
+ let mockQueue: ReturnType<typeof vi.fn>;
+
+ const validWorkflow = Object.assign(() => Promise.resolve('result'), {
+ workflowId: 'test-workflow',
+ });
+
+ beforeEach(() => {
+ mockEventsCreate = vi.fn().mockImplementation((runId) => {
+ return Promise.resolve({
+ run: { runId: runId ?? 'wrun_test123', status: 'pending' },
+ });
+ });
+ mockQueue = vi.fn().mockResolvedValue(undefined);
+
+ setWorld({
+ specVersion: SPEC_VERSION_CURRENT,
+ getDeploymentId: vi.fn().mockResolvedValue('deploy_123'),
+ events: { create: mockEventsCreate },
+ queue: mockQueue,
+ });
+ });
+
+ afterEach(() => {
+ setWorld(undefined);
+ vi.clearAllMocks();
+ });
+
+ it('records replayedFromRunId in executionContext when provided', async () => {
+ const sourceRunId = 'wrun_01ARZ3NDEKTSV4RRFFQ69G5FAV';
+ await start(validWorkflow, [], { replayedFromRunId: sourceRunId });
+
+ expect(mockEventsCreate).toHaveBeenCalledWith(
+ expect.stringMatching(/^wrun_/),
+ expect.objectContaining({
+ eventType: 'run_created',
+ eventData: expect.objectContaining({
+ executionContext: expect.objectContaining({
+ replayedFromRunId: sourceRunId,
+ }),
+ }),
+ }),
+ expect.anything()
+ );
+ });
+
+ it('omits replayedFromRunId from executionContext when not provided', async () => {
+ await start(validWorkflow, []);
+
+ const eventData = mockEventsCreate.mock.calls[0]?.[1]?.eventData;
+ expect(eventData.executionContext).not.toHaveProperty(
+ 'replayedFromRunId'
+ );
+ });
+
+ it('rejects a replayedFromRunId without the wrun_ prefix', async () => {
+ await expect(
+ start(validWorkflow, [], { replayedFromRunId: 'not-a-run-id' })
+ ).rejects.toThrow(/replayedFromRunId must be a run ID/);
+ expect(mockEventsCreate).not.toHaveBeenCalled();
+ });
+
+ it('rejects a wrun_-prefixed value whose body is not a valid ULID', async () => {
+ await expect(
+ start(validWorkflow, [], {
+ replayedFromRunId: `wrun_${'x'.repeat(300)}`,
+ })
+ ).rejects.toThrow(/replayedFromRunId must be a run ID/);
+ expect(mockEventsCreate).not.toHaveBeenCalled();
+ });
+
+ it('rejects a non-string replayedFromRunId', async () => {
+ await expect(
+ start(validWorkflow, [], {
+ // Types forbid this, but JS callers can still pass it.
+ replayedFromRunId: 12345 as unknown as string,
+ })
+ ).rejects.toThrow(/replayedFromRunId must be a run ID/);
+ expect(mockEventsCreate).not.toHaveBeenCalled();
+ });
+ });
+
  describe('overload type inference', () => {
  // Type-only assertions that don't execute start() at runtime.
  // We use expectTypeOf on the function signature's return type directly.

packages/core/src/runtime/start.ts

@@ -6,6 +6,7 @@ import {
  SPEC_VERSION_SUPPORTS_ATTRIBUTES,
  SPEC_VERSION_SUPPORTS_CBOR_QUEUE_TRANSPORT,
  SPEC_VERSION_SUPPORTS_COMPRESSION,
+ workflowRunIdSchema,
 } from '@workflow/world';
 import { monotonicFactory } from 'ulid';
 import { normalizeAttributeChanges } from '../attribute-changes.js';
@@ -90,6 +91,20 @@ export interface StartOptionsBase {
  */
  allowReservedAttributes?: boolean;
 
+ /**
+ * The ID of an existing run this run is being replayed from, if any.
+ *
+ * Recorded on the new run's `executionContext` as `replayedFromRunId` so
+ * tooling (e.g. the dashboard runs list) can show that a run originated as
+ * a replay and link back to its source. Set automatically by
+ * {@link recreateRunFromExisting}; there's usually no reason to pass it
+ * directly.
+ *
+ * Must be a run ID: `wrun_` followed by a 26-char ULID. It's a foreign key
+ * to the source run, so `start()` validates the exact shape and rejects
+ * anything else rather than persist a lineage link that points at garbage.
+ */
+ replayedFromRunId?: string;
  /**
  * Queue namespace of the target deployment. Scopes the workflow queue
  * topic to `__{namespace}_wkf_workflow_*` (e.g. `'eve'`) instead of the
@@ -335,6 +350,19 @@ export async function start<TArgs extends unknown[], TResult>(
  }
  : {};
 
+ // `replayedFromRunId` is a foreign key to the source run; reject anything
+ // that isn't a real run ID so the lineage link can't point at garbage.
+ if (
+ opts.replayedFromRunId !== undefined &&
+ !workflowRunIdSchema.safeParse(opts.replayedFromRunId).success
+ ) {
+ throw new WorkflowRuntimeError(
+ `replayedFromRunId must be a run ID (wrun_<ulid>); received ${JSON.stringify(
+ String(opts.replayedFromRunId).slice(0, 64)
+ )}.`
+ );
+ }
+
  // Resolve encryption key for the new run. The runId has already been
  // generated above (client-generated ULID) and will be used for both
  // key derivation and the run_created event. The World implementation
@@ -372,6 +400,9 @@ export async function start<TArgs extends unknown[], TResult>(
  traceCarrier,
  workflowCoreVersion,
  features: { encryption: !!encryptionKey },
+ ...(opts.replayedFromRunId
+ ? { replayedFromRunId: opts.replayedFromRunId }
+ : {}),
  };
 
  // Call events.create (run_created) and queue in parallel.

packages/world/src/index.ts

@@ -125,6 +125,8 @@ export {
  DEFAULT_TIMESTAMP_THRESHOLD_PAST_MS,
  ulidToDate,
  validateUlidTimestamp,
+ workflowRunIdSchema,
 } from './ulid.js';
+export type { WorkflowRunId } from './ulid.js';
 export type * from './waits.js';
 export { WaitSchema, WaitStatusSchema } from './waits.js';

packages/world/src/ulid.ts

@@ -3,6 +3,16 @@ import { z } from 'zod';
 
 const UlidSchema = z.string().ulid();
 
+/**
+ * A workflow run ID: the `wrun_` prefix followed by a 26-char ULID (minted
+ * client-side in core's `start()`). Validates the exact shape — prefix plus a
+ * well-formed ULID — rather than a loose length bound, so callers can't smuggle
+ * arbitrary strings through APIs that persist a run ID verbatim.
+ */
+export const workflowRunIdSchema = z.templateLiteral(['wrun_', z.ulid()]);
+
+export type WorkflowRunId = z.infer<typeof workflowRunIdSchema>;
+
 /**
  * Default threshold for ULID timestamps in the past (24 hours).
  *

.changeset/replay-lineage-execution-context.md

@@ -0,0 +1,5 @@
+---
+'@workflow/core': minor
+---
+
+Record the source run on replays: `recreateRunFromExisting` now stamps `replayedFromRunId` into the new run's `executionContext` (and `start` accepts a matching option) so tooling can surface a run as a replay and link back to its origin.

packages/core/src/runtime/runs.test.ts

@@ -12,14 +12,27 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 // Mock version module to avoid missing generated file
 vi.mock('../version.js', () => ({ version: '0.0.0-test' }));
 
+// Stub `start` so recreateRunFromExisting can be tested for the options it
+// forwards without exercising the full run-creation pipeline (serialization,
+// telemetry, queueing).
+vi.mock('./start.js', () => ({ start: vi.fn() }));
+
+// Keep serialization real except for argument hydration, which needs a real
+// serialized payload we don't have in these unit tests.
+vi.mock('../serialization.js', async (importActual) => {
+ const actual = await importActual<typeof import('../serialization.js')>();
+ return { ...actual, hydrateWorkflowArguments: vi.fn().mockResolvedValue([]) };
+});
+
 import { registerSerializationClass } from '../class-serialization.js';
 import {
  dehydrateRunError,
  dehydrateStepReturnValue,
  hydrateStepReturnValue,
 } from '../serialization.js';
 import { Run } from './run.js';
-import { reenqueueRun, wakeUpRun } from './runs.js';
+import { recreateRunFromExisting, reenqueueRun, wakeUpRun } from './runs.js';
+import { start } from './start.js';
 import { setWorld } from './world.js';
 
 function createMockWorld(
@@ -155,6 +168,31 @@ describe('reenqueueRun', () => {
  });
 });
 
+describe('recreateRunFromExisting', () => {
+ afterEach(() => {
+ vi.mocked(start).mockReset();
+ });
+
+ it('forwards the source run id to start as replayedFromRunId', async () => {
+ const world = createMockWorld({
+ run: { runId: 'wrun_source', deploymentId: 'deploy_source' },
+ });
+ vi.mocked(start).mockResolvedValue({ runId: 'wrun_new' } as Run<unknown>);
+
+ const newRunId = await recreateRunFromExisting(world, 'wrun_source');
+
+ expect(newRunId).toBe('wrun_new');
+ expect(start).toHaveBeenCalledWith(
+ { workflowId: 'test-workflow' },
+ expect.any(Array),
+ expect.objectContaining({
+ replayedFromRunId: 'wrun_source',
+ deploymentId: 'deploy_source',
+ })
+ );
+ });
+});
+
 describe('Run.exists', () => {
  afterEach(() => {
  setWorld(undefined as unknown as World);

packages/core/src/runtime/runs.ts

@@ -105,6 +105,7 @@ export async function recreateRunFromExisting(
  deploymentId,
  world,
  specVersion,
+ replayedFromRunId: runId,
  namespace: options.namespace,
  }
  );

packages/core/src/runtime/start.test.ts

@@ -770,6 +770,89 @@ describe('start', () => {
  });
  });
 
+ describe('replay lineage (executionContext.replayedFromRunId)', () => {
+ let mockEventsCreate: ReturnType<typeof vi.fn>;
+ let mockQueue: ReturnType<typeof vi.fn>;
+
+ const validWorkflow = Object.assign(() => Promise.resolve('result'), {
+ workflowId: 'test-workflow',
+ });
+
+ beforeEach(() => {
+ mockEventsCreate = vi.fn().mockImplementation((runId) => {
+ return Promise.resolve({
+ run: { runId: runId ?? 'wrun_test123', status: 'pending' },
+ });
+ });
+ mockQueue = vi.fn().mockResolvedValue(undefined);
+
+ setWorld({
+ specVersion: SPEC_VERSION_CURRENT,
+ getDeploymentId: vi.fn().mockResolvedValue('deploy_123'),
+ events: { create: mockEventsCreate },
+ queue: mockQueue,
+ });
+ });
+
+ afterEach(() => {
+ setWorld(undefined);
+ vi.clearAllMocks();
+ });
+
+ it('records replayedFromRunId in executionContext when provided', async () => {
+ const sourceRunId = 'wrun_01ARZ3NDEKTSV4RRFFQ69G5FAV';
+ await start(validWorkflow, [], { replayedFromRunId: sourceRunId });
+
+ expect(mockEventsCreate).toHaveBeenCalledWith(
+ expect.stringMatching(/^wrun_/),
+ expect.objectContaining({
+ eventType: 'run_created',
+ eventData: expect.objectContaining({
+ executionContext: expect.objectContaining({
+ replayedFromRunId: sourceRunId,
+ }),
+ }),
+ }),
+ expect.anything()
+ );
+ });
+
+ it('omits replayedFromRunId from executionContext when not provided', async () => {
+ await start(validWorkflow, []);
+
+ const eventData = mockEventsCreate.mock.calls[0]?.[1]?.eventData;
+ expect(eventData.executionContext).not.toHaveProperty(
+ 'replayedFromRunId'
+ );
+ });
+
+ it('rejects a replayedFromRunId without the wrun_ prefix', async () => {
+ await expect(
+ start(validWorkflow, [], { replayedFromRunId: 'not-a-run-id' })
+ ).rejects.toThrow(/replayedFromRunId must be a run ID/);
+ expect(mockEventsCreate).not.toHaveBeenCalled();
+ });
+
+ it('rejects a wrun_-prefixed value whose body is not a valid ULID', async () => {
+ await expect(
+ start(validWorkflow, [], {
+ replayedFromRunId: `wrun_${'x'.repeat(300)}`,
+ })
+ ).rejects.toThrow(/replayedFromRunId must be a run ID/);
+ expect(mockEventsCreate).not.toHaveBeenCalled();
+ });
+
+ it('rejects a non-string replayedFromRunId', async () => {
+ await expect(
+ start(validWorkflow, [], {
+ // Types forbid this, but JS callers can still pass it.
+ replayedFromRunId: 12345 as unknown as string,
+ })
+ ).rejects.toThrow(/replayedFromRunId must be a run ID/);
+ expect(mockEventsCreate).not.toHaveBeenCalled();
+ });
+ });
+
  describe('overload type inference', () => {
  // Type-only assertions that don't execute start() at runtime.
  // We use expectTypeOf on the function signature's return type directly.

packages/core/src/runtime/start.ts

@@ -6,6 +6,7 @@ import {
  SPEC_VERSION_SUPPORTS_ATTRIBUTES,
  SPEC_VERSION_SUPPORTS_CBOR_QUEUE_TRANSPORT,
  SPEC_VERSION_SUPPORTS_COMPRESSION,
+ workflowRunIdSchema,
 } from '@workflow/world';
 import { monotonicFactory } from 'ulid';
 import { normalizeAttributeChanges } from '../attribute-changes.js';
@@ -90,6 +91,20 @@ export interface StartOptionsBase {
  */
  allowReservedAttributes?: boolean;
 
+ /**
+ * The ID of an existing run this run is being replayed from, if any.
+ *
+ * Recorded on the new run's `executionContext` as `replayedFromRunId` so
+ * tooling (e.g. the dashboard runs list) can show that a run originated as
+ * a replay and link back to its source. Set automatically by
+ * {@link recreateRunFromExisting}; there's usually no reason to pass it
+ * directly.
+ *
+ * Must be a run ID: `wrun_` followed by a 26-char ULID. It's a foreign key
+ * to the source run, so `start()` validates the exact shape and rejects
+ * anything else rather than persist a lineage link that points at garbage.
+ */
+ replayedFromRunId?: string;
  /**
  * Queue namespace of the target deployment. Scopes the workflow queue
  * topic to `__{namespace}_wkf_workflow_*` (e.g. `'eve'`) instead of the
@@ -335,6 +350,19 @@ export async function start<TArgs extends unknown[], TResult>(
  }
  : {};
 
+ // `replayedFromRunId` is a foreign key to the source run; reject anything
+ // that isn't a real run ID so the lineage link can't point at garbage.
+ if (
+ opts.replayedFromRunId !== undefined &&
+ !workflowRunIdSchema.safeParse(opts.replayedFromRunId).success
+ ) {
+ throw new WorkflowRuntimeError(
+ `replayedFromRunId must be a run ID (wrun_<ulid>); received ${JSON.stringify(
+ String(opts.replayedFromRunId).slice(0, 64)
+ )}.`
+ );
+ }
+
  // Resolve encryption key for the new run. The runId has already been
  // generated above (client-generated ULID) and will be used for both
  // key derivation and the run_created event. The World implementation
@@ -372,6 +400,9 @@ export async function start<TArgs extends unknown[], TResult>(
  traceCarrier,
  workflowCoreVersion,
  features: { encryption: !!encryptionKey },
+ ...(opts.replayedFromRunId
+ ? { replayedFromRunId: opts.replayedFromRunId }
+ : {}),
  };
 
  // Call events.create (run_created) and queue in parallel.

packages/world/src/index.ts

@@ -125,6 +125,8 @@ export {
  DEFAULT_TIMESTAMP_THRESHOLD_PAST_MS,
  ulidToDate,
  validateUlidTimestamp,
+ workflowRunIdSchema,
 } from './ulid.js';
+export type { WorkflowRunId } from './ulid.js';
 export type * from './waits.js';
 export { WaitSchema, WaitStatusSchema } from './waits.js';

packages/world/src/ulid.ts

@@ -3,6 +3,16 @@ import { z } from 'zod';
 
 const UlidSchema = z.string().ulid();
 
+/**
+ * A workflow run ID: the `wrun_` prefix followed by a 26-char ULID (minted
+ * client-side in core's `start()`). Validates the exact shape — prefix plus a
+ * well-formed ULID — rather than a loose length bound, so callers can't smuggle
+ * arbitrary strings through APIs that persist a run ID verbatim.
+ */
+export const workflowRunIdSchema = z.templateLiteral(['wrun_', z.ulid()]);
+
+export type WorkflowRunId = z.infer<typeof workflowRunIdSchema>;
+
 /**
  * Default threshold for ULID timestamps in the past (24 hours).
  *

.changeset/replay-lineage-execution-context.md

@@ -0,0 +1,5 @@
+---
+'@workflow/core': minor
+---
+
+Record the source run on replays: `recreateRunFromExisting` now stamps `replayedFromRunId` into the new run's `executionContext` (and `start` accepts a matching option) so tooling can surface a run as a replay and link back to its origin.

packages/core/src/runtime/runs.test.ts

@@ -12,14 +12,27 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 // Mock version module to avoid missing generated file
 vi.mock('../version.js', () => ({ version: '0.0.0-test' }));
 
+// Stub `start` so recreateRunFromExisting can be tested for the options it
+// forwards without exercising the full run-creation pipeline (serialization,
+// telemetry, queueing).
+vi.mock('./start.js', () => ({ start: vi.fn() }));
+
+// Keep serialization real except for argument hydration, which needs a real
+// serialized payload we don't have in these unit tests.
+vi.mock('../serialization.js', async (importActual) => {
+ const actual = await importActual<typeof import('../serialization.js')>();
+ return { ...actual, hydrateWorkflowArguments: vi.fn().mockResolvedValue([]) };
+});
+
 import { registerSerializationClass } from '../class-serialization.js';
 import {
  dehydrateRunError,
  dehydrateStepReturnValue,
  hydrateStepReturnValue,
 } from '../serialization.js';
 import { Run } from './run.js';
-import { reenqueueRun, wakeUpRun } from './runs.js';
+import { recreateRunFromExisting, reenqueueRun, wakeUpRun } from './runs.js';
+import { start } from './start.js';
 import { setWorld } from './world.js';
 
 function createMockWorld(
@@ -155,6 +168,31 @@ describe('reenqueueRun', () => {
  });
 });
 
+describe('recreateRunFromExisting', () => {
+ afterEach(() => {
+ vi.mocked(start).mockReset();
+ });
+
+ it('forwards the source run id to start as replayedFromRunId', async () => {
+ const world = createMockWorld({
+ run: { runId: 'wrun_source', deploymentId: 'deploy_source' },
+ });
+ vi.mocked(start).mockResolvedValue({ runId: 'wrun_new' } as Run<unknown>);
+
+ const newRunId = await recreateRunFromExisting(world, 'wrun_source');
+
+ expect(newRunId).toBe('wrun_new');
+ expect(start).toHaveBeenCalledWith(
+ { workflowId: 'test-workflow' },
+ expect.any(Array),
+ expect.objectContaining({
+ replayedFromRunId: 'wrun_source',
+ deploymentId: 'deploy_source',
+ })
+ );
+ });
+});
+
 describe('Run.exists', () => {
  afterEach(() => {
  setWorld(undefined as unknown as World);

packages/core/src/runtime/runs.ts

@@ -105,6 +105,7 @@ export async function recreateRunFromExisting(
  deploymentId,
  world,
  specVersion,
+ replayedFromRunId: runId,
  namespace: options.namespace,
  }
  );

packages/core/src/runtime/start.test.ts

@@ -770,6 +770,89 @@ describe('start', () => {
  });
  });
 
+ describe('replay lineage (executionContext.replayedFromRunId)', () => {
+ let mockEventsCreate: ReturnType<typeof vi.fn>;
+ let mockQueue: ReturnType<typeof vi.fn>;
+
+ const validWorkflow = Object.assign(() => Promise.resolve('result'), {
+ workflowId: 'test-workflow',
+ });
+
+ beforeEach(() => {
+ mockEventsCreate = vi.fn().mockImplementation((runId) => {
+ return Promise.resolve({
+ run: { runId: runId ?? 'wrun_test123', status: 'pending' },
+ });
+ });
+ mockQueue = vi.fn().mockResolvedValue(undefined);
+
+ setWorld({
+ specVersion: SPEC_VERSION_CURRENT,
+ getDeploymentId: vi.fn().mockResolvedValue('deploy_123'),
+ events: { create: mockEventsCreate },
+ queue: mockQueue,
+ });
+ });
+
+ afterEach(() => {
+ setWorld(undefined);
+ vi.clearAllMocks();
+ });
+
+ it('records replayedFromRunId in executionContext when provided', async () => {
+ const sourceRunId = 'wrun_01ARZ3NDEKTSV4RRFFQ69G5FAV';
+ await start(validWorkflow, [], { replayedFromRunId: sourceRunId });
+
+ expect(mockEventsCreate).toHaveBeenCalledWith(
+ expect.stringMatching(/^wrun_/),
+ expect.objectContaining({
+ eventType: 'run_created',
+ eventData: expect.objectContaining({
+ executionContext: expect.objectContaining({
+ replayedFromRunId: sourceRunId,
+ }),
+ }),
+ }),
+ expect.anything()
+ );
+ });
+
+ it('omits replayedFromRunId from executionContext when not provided', async () => {
+ await start(validWorkflow, []);
+
+ const eventData = mockEventsCreate.mock.calls[0]?.[1]?.eventData;
+ expect(eventData.executionContext).not.toHaveProperty(
+ 'replayedFromRunId'
+ );
+ });
+
+ it('rejects a replayedFromRunId without the wrun_ prefix', async () => {
+ await expect(
+ start(validWorkflow, [], { replayedFromRunId: 'not-a-run-id' })
+ ).rejects.toThrow(/replayedFromRunId must be a run ID/);
+ expect(mockEventsCreate).not.toHaveBeenCalled();
+ });
+
+ it('rejects a wrun_-prefixed value whose body is not a valid ULID', async () => {
+ await expect(
+ start(validWorkflow, [], {
+ replayedFromRunId: `wrun_${'x'.repeat(300)}`,
+ })
+ ).rejects.toThrow(/replayedFromRunId must be a run ID/);
+ expect(mockEventsCreate).not.toHaveBeenCalled();
+ });
+
+ it('rejects a non-string replayedFromRunId', async () => {
+ await expect(
+ start(validWorkflow, [], {
+ // Types forbid this, but JS callers can still pass it.
+ replayedFromRunId: 12345 as unknown as string,
+ })
+ ).rejects.toThrow(/replayedFromRunId must be a run ID/);
+ expect(mockEventsCreate).not.toHaveBeenCalled();
+ });
+ });
+
  describe('overload type inference', () => {
  // Type-only assertions that don't execute start() at runtime.
  // We use expectTypeOf on the function signature's return type directly.

packages/core/src/runtime/start.ts

@@ -6,6 +6,7 @@ import {
  SPEC_VERSION_SUPPORTS_ATTRIBUTES,
  SPEC_VERSION_SUPPORTS_CBOR_QUEUE_TRANSPORT,
  SPEC_VERSION_SUPPORTS_COMPRESSION,
+ workflowRunIdSchema,
 } from '@workflow/world';
 import { monotonicFactory } from 'ulid';
 import { normalizeAttributeChanges } from '../attribute-changes.js';
@@ -90,6 +91,20 @@ export interface StartOptionsBase {
  */
  allowReservedAttributes?: boolean;
 
+ /**
+ * The ID of an existing run this run is being replayed from, if any.
+ *
+ * Recorded on the new run's `executionContext` as `replayedFromRunId` so
+ * tooling (e.g. the dashboard runs list) can show that a run originated as
+ * a replay and link back to its source. Set automatically by
+ * {@link recreateRunFromExisting}; there's usually no reason to pass it
+ * directly.
+ *
+ * Must be a run ID: `wrun_` followed by a 26-char ULID. It's a foreign key
+ * to the source run, so `start()` validates the exact shape and rejects
+ * anything else rather than persist a lineage link that points at garbage.
+ */
+ replayedFromRunId?: string;
  /**
  * Queue namespace of the target deployment. Scopes the workflow queue
  * topic to `__{namespace}_wkf_workflow_*` (e.g. `'eve'`) instead of the
@@ -335,6 +350,19 @@ export async function start<TArgs extends unknown[], TResult>(
  }
  : {};
 
+ // `replayedFromRunId` is a foreign key to the source run; reject anything
+ // that isn't a real run ID so the lineage link can't point at garbage.
+ if (
+ opts.replayedFromRunId !== undefined &&
+ !workflowRunIdSchema.safeParse(opts.replayedFromRunId).success
+ ) {
+ throw new WorkflowRuntimeError(
+ `replayedFromRunId must be a run ID (wrun_<ulid>); received ${JSON.stringify(
+ String(opts.replayedFromRunId).slice(0, 64)
+ )}.`
+ );
+ }
+
  // Resolve encryption key for the new run. The runId has already been
  // generated above (client-generated ULID) and will be used for both
  // key derivation and the run_created event. The World implementation
@@ -372,6 +400,9 @@ export async function start<TArgs extends unknown[], TResult>(
  traceCarrier,
  workflowCoreVersion,
  features: { encryption: !!encryptionKey },
+ ...(opts.replayedFromRunId
+ ? { replayedFromRunId: opts.replayedFromRunId }
+ : {}),
  };
 
  // Call events.create (run_created) and queue in parallel.

packages/world/src/index.ts

@@ -125,6 +125,8 @@ export {
  DEFAULT_TIMESTAMP_THRESHOLD_PAST_MS,
  ulidToDate,
  validateUlidTimestamp,
+ workflowRunIdSchema,
 } from './ulid.js';
+export type { WorkflowRunId } from './ulid.js';
 export type * from './waits.js';
 export { WaitSchema, WaitStatusSchema } from './waits.js';

packages/world/src/ulid.ts

@@ -3,6 +3,16 @@ import { z } from 'zod';
 
 const UlidSchema = z.string().ulid();
 
+/**
+ * A workflow run ID: the `wrun_` prefix followed by a 26-char ULID (minted
+ * client-side in core's `start()`). Validates the exact shape — prefix plus a
+ * well-formed ULID — rather than a loose length bound, so callers can't smuggle
+ * arbitrary strings through APIs that persist a run ID verbatim.
+ */
+export const workflowRunIdSchema = z.templateLiteral(['wrun_', z.ulid()]);
+
+export type WorkflowRunId = z.infer<typeof workflowRunIdSchema>;
+
 /**
  * Default threshold for ULID timestamps in the past (24 hours).
  *