feat: cross-run lineage via reserved run attributes

.changeset/start-cross-run-lineage.md

@@ -0,0 +1,6 @@
+---
+"@workflow/core": patch
+"@workflow/world": patch
+---
+
+Record cross-run lineage when `start()` is called from inside a workflow or step: the new run is tagged with `$parentRunId` (its direct parent) and inherits the parent's `$rootRunId`, so a daisy chain or fan-out of any depth groups under one root id.

docs/content/docs/v5/observability/attributes.mdx

@@ -57,6 +57,15 @@ export async function cleanupAttributes() {
 
 Attribute keys must be 1-256 characters, values must be strings up to 256 bytes, and each run can have up to 64 attributes. Keys that start with `$` are reserved for framework and library code.
 
+## Reserved keys
+
+When `start()` is called from inside a running workflow or step, the new run is automatically tagged with two reserved attributes:
+
+- `$parentRunId`: the run that started it.
+- `$rootRunId`: the root of the chain. It is inherited, so every run in a daisy chain or fan-out shares one root id.
+
+Top-level runs (started outside any workflow or step) are not tagged.
+
 ## Viewing attributes
 
 The run details panel in the observability UI shows the run's current attributes as key-value rows. Reserved `$`-prefixed keys are marked with a badge and sorted after user keys:

packages/core/src/runtime.ts

@@ -17,6 +17,7 @@ import {
 import {
  type Event,
  getQueueTopicPrefix,
+ ROOT_RUN_ID_ATTRIBUTE,
  resolveQueueNamespace,
  SPEC_VERSION_CURRENT,
  SPEC_VERSION_SUPPORTS_COMPRESSION,
@@ -242,6 +243,17 @@ function hasRecordedTerminalRunEvent(events: Event[], runId: string): boolean {
  return true;
 }
 
+/**
+ * The lineage root of a loaded run: its `$rootRunId` attribute, or its own id
+ * when it is itself a root.
+ */
+function rootRunIdFrom(
+ attributes: Record<string, string> | undefined,
+ runId: string
+): string {
+ return attributes?.[ROOT_RUN_ID_ATTRIBUTE] ?? runId;
+}
+
 /**
  * Whether the run has any hook or wait that an out-of-band writer could
  * append an event for between an inline step's `step_completed` write and
@@ -728,6 +740,7 @@ export function workflowEntrypoint(
  workflowDeploymentId: bgRun.deploymentId,
  workflowName,
  workflowStartedAt: bgStartedAt,
+ rootRunId: rootRunIdFrom(bgRun.attributes, runId),
  stepId: incomingStepId,
  stepName: incomingStepName,
  runSpecVersion: bgRun.specVersion,
@@ -1984,6 +1997,10 @@ export function workflowEntrypoint(
  workflowRun.deploymentId,
  workflowName,
  workflowStartedAt,
+ rootRunId: rootRunIdFrom(
+ workflowRun.attributes,
+ runId
+ ),
  stepId: s.correlationId,
  stepName: s.stepName,
  runSpecVersion: workflowRun.specVersion,

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

@@ -0,0 +1,156 @@
+import {
+ SPEC_VERSION_CURRENT,
+ SPEC_VERSION_SUPPORTS_ATTRIBUTES,
+} from '@workflow/world';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { contextStorage } from '../step/context-storage.js';
+import { start } from './start.js';
+import { setWorld } from './world.js';
+
+vi.mock('@vercel/functions', () => ({ waitUntil: vi.fn() }));
+vi.mock('../telemetry.js', () => ({
+ serializeTraceCarrier: vi.fn().mockResolvedValue({}),
+ trace: vi.fn((_name, fn) => fn(undefined)),
+}));
+
+/**
+ * Cross-run lineage: start() records reserved `$rootRunId` / `$parentRunId`
+ * attributes when it runs inside another run, so a daisy chain or fan-out
+ * groups under one root id. The lineage is a pure read of the ambient step
+ * context: the runtime fills both the parent run id and its root from the run
+ * it already has loaded, so start() never reads back the parent (`runs.get` is
+ * never called). A top-level start() records nothing.
+ */
+describe('start() cross-run lineage', () => {
+ let eventsCreate: ReturnType<typeof vi.fn>;
+ let runsGet: ReturnType<typeof vi.fn>;
+ let queue: ReturnType<typeof vi.fn>;
+
+ // The runtime requires the world to declare the current spec version; the
+ // per-run spec is driven separately via `opts.specVersion` where needed.
+ function useWorld() {
+ setWorld({
+ specVersion: SPEC_VERSION_CURRENT,
+ getDeploymentId: vi.fn().mockResolvedValue('deploy_123'),
+ events: { create: eventsCreate },
+ runs: { get: runsGet },
+ queue,
+ } as any);
+ }
+
+ beforeEach(() => {
+ eventsCreate = vi.fn().mockImplementation((runId) =>
+ Promise.resolve({
+ run: { runId: runId ?? 'wrun_x', status: 'pending' },
+ })
+ );
+ runsGet = vi.fn();
+ queue = vi.fn().mockResolvedValue(undefined);
+ useWorld();
+ });
+
+ afterEach(() => {
+ setWorld(undefined);
+ vi.clearAllMocks();
+ });
+
+ const wf = (id: string) =>
+ Object.assign(() => Promise.resolve('ok'), { workflowId: id });
+
+ /** Attributes seeded onto the run_created event for the first start() call. */
+ function seededAttributes(): Record<string, string> | undefined {
+ return eventsCreate.mock.calls[0]?.[1]?.eventData?.attributes;
+ }
+
+ /**
+ * Run `fn` as if executing inside a parent run's step context. Pass
+ * `rootRunId` to model the runtime having put the parent's root on the
+ * context (the wired path); omit it to exercise the anchor-to-parent default.
+ */
+ function insideRun<T>(
+ parentRunId: string,
+ fn: () => Promise<T>,
+ rootRunId?: string
+ ): Promise<T> {
+ return contextStorage.run(
+ {
+ stepMetadata: {
+ stepName: 'start',
+ stepId: 'step_1',
+ stepStartedAt: new Date(),
+ attempt: 1,
+ },
+ workflowMetadata: {
+ workflowName: 'parent',
+ workflowRunId: parentRunId,
+ workflowStartedAt: new Date(),
+ url: 'http://localhost:3000',
+ features: { encryption: false },
+ },
+ rootRunId,
+ ops: [],
+ } as any,
+ fn
+ );
+ }
+
+ it('records no lineage for a top-level start()', async () => {
+ await start(wf('test-workflow'), []);
+
+ expect(seededAttributes()).toBeUndefined();
+ expect(runsGet).not.toHaveBeenCalled();
+ });
+
+ it('inherits the root from the context with no read-back', async () => {
+ await insideRun(
+ 'wrun_parent',
+ () => start(wf('child-workflow'), []),
+ 'wrun_root'
+ );
+
+ expect(runsGet).not.toHaveBeenCalled();
+ expect(seededAttributes()).toEqual({
+ $rootRunId: 'wrun_root',
+ $parentRunId: 'wrun_parent',
+ });
+ });
+
+ it('anchors the root to the parent when the context carries none', async () => {
+ await insideRun('wrun_parent', () => start(wf('child-workflow'), []));
+
+ expect(runsGet).not.toHaveBeenCalled();
+ expect(seededAttributes()).toEqual({
+ $rootRunId: 'wrun_parent',
+ $parentRunId: 'wrun_parent',
+ });
+ });
+
+ it('merges caller-provided attributes over the inferred lineage', async () => {
+ await insideRun(
+ 'wrun_parent',
+ () => start(wf('child-workflow'), [], { attributes: { tenant: 't1' } }),
+ 'wrun_root'
+ );
+
+ const expected = {
+ $rootRunId: 'wrun_root',
+ $parentRunId: 'wrun_parent',
+ tenant: 't1',
+ };
+ expect(seededAttributes()).toEqual(expected);
+ // Lineage must also ride the resilient-start queue input, not just the
+ // run_created event, so both creation paths carry it.
+ expect(queue.mock.calls[0]?.[1]?.runInput?.attributes).toEqual(expected);
+ });
+
+ it('records no lineage when the run predates attribute support', async () => {
+ await insideRun('wrun_parent', () =>
+ start(wf('child-workflow'), [], {
+ specVersion: SPEC_VERSION_SUPPORTS_ATTRIBUTES - 1,
+ })
+ );
+
+ expect(seededAttributes()).toBeUndefined();
+ expect(runsGet).not.toHaveBeenCalled();
+ });
+});

packages/core/src/runtime/start.ts

@@ -3,6 +3,8 @@ import { workflowDisplayName } from '@workflow/utils/parse-name';
 import type { WorkflowInvokePayload, World } from '@workflow/world';
 import {
  isLegacySpecVersion,
+ PARENT_RUN_ID_ATTRIBUTE,
+ ROOT_RUN_ID_ATTRIBUTE,
  SPEC_VERSION_SUPPORTS_ATTRIBUTES,
  SPEC_VERSION_SUPPORTS_CBOR_QUEUE_TRANSPORT,
  SPEC_VERSION_SUPPORTS_COMPRESSION,
@@ -19,6 +21,7 @@ import {
  dehydrateWorkflowArguments,
  SerializationFormat,
 } from '../serialization.js';
+import { contextStorage } from '../step/context-storage.js';
 import * as Attribute from '../telemetry/semantic-conventions.js';
 import { serializeTraceCarrier, trace } from '../telemetry.js';
 import { version as workflowCoreVersion } from '../version.js';
@@ -42,6 +45,28 @@ const CROSS_DEPLOYMENT_CAPABILITY_PROBE_TIMEOUT_MS = 2_000;
 /** ULID generator for client-side runId generation */
 const ulid = monotonicFactory();
 
+/**
+ * Cross-run lineage for a run being started from inside another run.
+ *
+ * The ambient step context carries the parent run id and the root of its
+ * lineage; the runtime fills both from the run it already has loaded, so this
+ * is a pure context read with no I/O. The new run records `$parentRunId` (the
+ * edge) and inherits the parent's `$rootRunId` (the parent itself when it is a
+ * root), so a daisy chain or fan-out of any depth groups under one root id.
+ * Returns `undefined` for a top-level `start()`, which has no context, so
+ * standalone runs carry no lineage.
+ */
+function resolveLineageAttributes(): Record<string, string> | undefined {
+ const store = contextStorage.getStore();
+ const parentRunId = store?.workflowMetadata?.workflowRunId;
+ if (!parentRunId) return undefined;
+
+ return {
+ [ROOT_RUN_ID_ATTRIBUTE]: store.rootRunId ?? parentRunId,
+ [PARENT_RUN_ID_ATTRIBUTE]: parentRunId,
+ };
+}
+
 // `deploymentId: 'latest'` is a no-op in Worlds without atomic deployments.
 // The warning that explains this only needs to fire once per process: a
 // workflow that hardcodes 'latest' for its Vercel deployment would otherwise
@@ -360,13 +385,24 @@ export async function start<TArgs extends unknown[], TResult>(
  changes.map(({ key, value }) => [key, value as string])
  );
  }
- // Seed payload shared by run_created and the resilient-start queue
- // input. The flag rides along so server-side validation matches the
- // client-side check above on both paths.
- const attributeSeed = attributes
+
+ // Cross-run lineage: the reserved keys ride on the run's existing
+ // attributes, so they add no extra write. Caller attributes are spread
+ // last, so a caller with allowReservedAttributes can deliberately
+ // re-parent.
+ const lineage =
+ specVersion >= SPEC_VERSION_SUPPORTS_ATTRIBUTES
+ ? resolveLineageAttributes()
+ : undefined;
+ const runAttributes = lineage
+ ? { ...lineage, ...attributes }
+ : attributes;
+
+ // Shared by the run_created event and the resilient-start queue input.
+ const attributeSeed = runAttributes
  ? {
- attributes,
- ...(allowReservedAttributes
+ attributes: runAttributes,
+ ...(allowReservedAttributes || lineage != null
  ? { allowReservedAttributes: true as const }
  : {}),
  }

packages/core/src/runtime/step-executor.ts

@@ -81,6 +81,8 @@ export interface StepExecutorParams {
  workflowDeploymentId?: string;
  workflowName: string;
  workflowStartedAt: number;
+ /** Root run id of this run's lineage, carried into the step context. */
+ rootRunId?: string;
  stepId: string;
  stepName: string;
  encryptionKey?: CryptoKey;
@@ -690,6 +692,7 @@ export async function executeStep(
  features: { encryption: !!encryptionKey },
  },
  workflowDeploymentId: params.workflowDeploymentId,
+ rootRunId: params.rootRunId,
  ops,
  preCompletionOps,
  closureVars: hydratedInput.closureVars,

packages/core/src/step/context-storage.ts

@@ -22,6 +22,12 @@ export type StepContext = {
  workflowMetadata: WorkflowMetadata;
  /** Deployment that owns the current workflow run, used for forwarded streams. */
  workflowDeploymentId?: string;
+ /**
+ * Root run id of the current run's lineage (`$rootRunId`), so a nested
+ * `start()` inherits it without reloading the parent. Set by the runtime from
+ * the run it already has loaded.
+ */
+ rootRunId?: string;
  ops: Promise<void>[];
  /**
  * Operations that MUST be durably committed before the step's

packages/world-testing/src/index.mts

@@ -3,6 +3,7 @@ import { errors } from './errors.mjs';
 import { hooks } from './hooks.mjs';
 import { idempotency } from './idempotency.mjs';
 import { inlineExecution } from './inline-execution.mjs';
+import { lineage } from './lineage.mjs';
 import { nullByte } from './null-byte.mjs';
 
 export function createTestSuite(pkgName: string) {
@@ -12,4 +13,5 @@ export function createTestSuite(pkgName: string) {
  nullByte(pkgName);
  errors(pkgName);
  inlineExecution(pkgName);
+ lineage(pkgName);
 }

.changeset/start-cross-run-lineage.md

@@ -0,0 +1,6 @@
+---
+"@workflow/core": patch
+"@workflow/world": patch
+---
+
+Record cross-run lineage when `start()` is called from inside a workflow or step: the new run is tagged with `$parentRunId` (its direct parent) and inherits the parent's `$rootRunId`, so a daisy chain or fan-out of any depth groups under one root id.

docs/content/docs/v5/observability/attributes.mdx

@@ -57,6 +57,15 @@ export async function cleanupAttributes() {
 
 Attribute keys must be 1-256 characters, values must be strings up to 256 bytes, and each run can have up to 64 attributes. Keys that start with `$` are reserved for framework and library code.
 
+## Reserved keys
+
+When `start()` is called from inside a running workflow or step, the new run is automatically tagged with two reserved attributes:
+
+- `$parentRunId`: the run that started it.
+- `$rootRunId`: the root of the chain. It is inherited, so every run in a daisy chain or fan-out shares one root id.
+
+Top-level runs (started outside any workflow or step) are not tagged.
+
 ## Viewing attributes
 
 The run details panel in the observability UI shows the run's current attributes as key-value rows. Reserved `$`-prefixed keys are marked with a badge and sorted after user keys:

packages/core/src/runtime.ts

@@ -17,6 +17,7 @@ import {
 import {
  type Event,
  getQueueTopicPrefix,
+ ROOT_RUN_ID_ATTRIBUTE,
  resolveQueueNamespace,
  SPEC_VERSION_CURRENT,
  SPEC_VERSION_SUPPORTS_COMPRESSION,
@@ -242,6 +243,17 @@ function hasRecordedTerminalRunEvent(events: Event[], runId: string): boolean {
  return true;
 }
 
+/**
+ * The lineage root of a loaded run: its `$rootRunId` attribute, or its own id
+ * when it is itself a root.
+ */
+function rootRunIdFrom(
+ attributes: Record<string, string> | undefined,
+ runId: string
+): string {
+ return attributes?.[ROOT_RUN_ID_ATTRIBUTE] ?? runId;
+}
+
 /**
  * Whether the run has any hook or wait that an out-of-band writer could
  * append an event for between an inline step's `step_completed` write and
@@ -728,6 +740,7 @@ export function workflowEntrypoint(
  workflowDeploymentId: bgRun.deploymentId,
  workflowName,
  workflowStartedAt: bgStartedAt,
+ rootRunId: rootRunIdFrom(bgRun.attributes, runId),
  stepId: incomingStepId,
  stepName: incomingStepName,
  runSpecVersion: bgRun.specVersion,
@@ -1984,6 +1997,10 @@ export function workflowEntrypoint(
  workflowRun.deploymentId,
  workflowName,
  workflowStartedAt,
+ rootRunId: rootRunIdFrom(
+ workflowRun.attributes,
+ runId
+ ),
  stepId: s.correlationId,
  stepName: s.stepName,
  runSpecVersion: workflowRun.specVersion,

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

@@ -0,0 +1,156 @@
+import {
+ SPEC_VERSION_CURRENT,
+ SPEC_VERSION_SUPPORTS_ATTRIBUTES,
+} from '@workflow/world';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { contextStorage } from '../step/context-storage.js';
+import { start } from './start.js';
+import { setWorld } from './world.js';
+
+vi.mock('@vercel/functions', () => ({ waitUntil: vi.fn() }));
+vi.mock('../telemetry.js', () => ({
+ serializeTraceCarrier: vi.fn().mockResolvedValue({}),
+ trace: vi.fn((_name, fn) => fn(undefined)),
+}));
+
+/**
+ * Cross-run lineage: start() records reserved `$rootRunId` / `$parentRunId`
+ * attributes when it runs inside another run, so a daisy chain or fan-out
+ * groups under one root id. The lineage is a pure read of the ambient step
+ * context: the runtime fills both the parent run id and its root from the run
+ * it already has loaded, so start() never reads back the parent (`runs.get` is
+ * never called). A top-level start() records nothing.
+ */
+describe('start() cross-run lineage', () => {
+ let eventsCreate: ReturnType<typeof vi.fn>;
+ let runsGet: ReturnType<typeof vi.fn>;
+ let queue: ReturnType<typeof vi.fn>;
+
+ // The runtime requires the world to declare the current spec version; the
+ // per-run spec is driven separately via `opts.specVersion` where needed.
+ function useWorld() {
+ setWorld({
+ specVersion: SPEC_VERSION_CURRENT,
+ getDeploymentId: vi.fn().mockResolvedValue('deploy_123'),
+ events: { create: eventsCreate },
+ runs: { get: runsGet },
+ queue,
+ } as any);
+ }
+
+ beforeEach(() => {
+ eventsCreate = vi.fn().mockImplementation((runId) =>
+ Promise.resolve({
+ run: { runId: runId ?? 'wrun_x', status: 'pending' },
+ })
+ );
+ runsGet = vi.fn();
+ queue = vi.fn().mockResolvedValue(undefined);
+ useWorld();
+ });
+
+ afterEach(() => {
+ setWorld(undefined);
+ vi.clearAllMocks();
+ });
+
+ const wf = (id: string) =>
+ Object.assign(() => Promise.resolve('ok'), { workflowId: id });
+
+ /** Attributes seeded onto the run_created event for the first start() call. */
+ function seededAttributes(): Record<string, string> | undefined {
+ return eventsCreate.mock.calls[0]?.[1]?.eventData?.attributes;
+ }
+
+ /**
+ * Run `fn` as if executing inside a parent run's step context. Pass
+ * `rootRunId` to model the runtime having put the parent's root on the
+ * context (the wired path); omit it to exercise the anchor-to-parent default.
+ */
+ function insideRun<T>(
+ parentRunId: string,
+ fn: () => Promise<T>,
+ rootRunId?: string
+ ): Promise<T> {
+ return contextStorage.run(
+ {
+ stepMetadata: {
+ stepName: 'start',
+ stepId: 'step_1',
+ stepStartedAt: new Date(),
+ attempt: 1,
+ },
+ workflowMetadata: {
+ workflowName: 'parent',
+ workflowRunId: parentRunId,
+ workflowStartedAt: new Date(),
+ url: 'http://localhost:3000',
+ features: { encryption: false },
+ },
+ rootRunId,
+ ops: [],
+ } as any,
+ fn
+ );
+ }
+
+ it('records no lineage for a top-level start()', async () => {
+ await start(wf('test-workflow'), []);
+
+ expect(seededAttributes()).toBeUndefined();
+ expect(runsGet).not.toHaveBeenCalled();
+ });
+
+ it('inherits the root from the context with no read-back', async () => {
+ await insideRun(
+ 'wrun_parent',
+ () => start(wf('child-workflow'), []),
+ 'wrun_root'
+ );
+
+ expect(runsGet).not.toHaveBeenCalled();
+ expect(seededAttributes()).toEqual({
+ $rootRunId: 'wrun_root',
+ $parentRunId: 'wrun_parent',
+ });
+ });
+
+ it('anchors the root to the parent when the context carries none', async () => {
+ await insideRun('wrun_parent', () => start(wf('child-workflow'), []));
+
+ expect(runsGet).not.toHaveBeenCalled();
+ expect(seededAttributes()).toEqual({
+ $rootRunId: 'wrun_parent',
+ $parentRunId: 'wrun_parent',
+ });
+ });
+
+ it('merges caller-provided attributes over the inferred lineage', async () => {
+ await insideRun(
+ 'wrun_parent',
+ () => start(wf('child-workflow'), [], { attributes: { tenant: 't1' } }),
+ 'wrun_root'
+ );
+
+ const expected = {
+ $rootRunId: 'wrun_root',
+ $parentRunId: 'wrun_parent',
+ tenant: 't1',
+ };
+ expect(seededAttributes()).toEqual(expected);
+ // Lineage must also ride the resilient-start queue input, not just the
+ // run_created event, so both creation paths carry it.
+ expect(queue.mock.calls[0]?.[1]?.runInput?.attributes).toEqual(expected);
+ });
+
+ it('records no lineage when the run predates attribute support', async () => {
+ await insideRun('wrun_parent', () =>
+ start(wf('child-workflow'), [], {
+ specVersion: SPEC_VERSION_SUPPORTS_ATTRIBUTES - 1,
+ })
+ );
+
+ expect(seededAttributes()).toBeUndefined();
+ expect(runsGet).not.toHaveBeenCalled();
+ });
+});

packages/core/src/runtime/start.ts

@@ -3,6 +3,8 @@ import { workflowDisplayName } from '@workflow/utils/parse-name';
 import type { WorkflowInvokePayload, World } from '@workflow/world';
 import {
  isLegacySpecVersion,
+ PARENT_RUN_ID_ATTRIBUTE,
+ ROOT_RUN_ID_ATTRIBUTE,
  SPEC_VERSION_SUPPORTS_ATTRIBUTES,
  SPEC_VERSION_SUPPORTS_CBOR_QUEUE_TRANSPORT,
  SPEC_VERSION_SUPPORTS_COMPRESSION,
@@ -19,6 +21,7 @@ import {
  dehydrateWorkflowArguments,
  SerializationFormat,
 } from '../serialization.js';
+import { contextStorage } from '../step/context-storage.js';
 import * as Attribute from '../telemetry/semantic-conventions.js';
 import { serializeTraceCarrier, trace } from '../telemetry.js';
 import { version as workflowCoreVersion } from '../version.js';
@@ -42,6 +45,28 @@ const CROSS_DEPLOYMENT_CAPABILITY_PROBE_TIMEOUT_MS = 2_000;
 /** ULID generator for client-side runId generation */
 const ulid = monotonicFactory();
 
+/**
+ * Cross-run lineage for a run being started from inside another run.
+ *
+ * The ambient step context carries the parent run id and the root of its
+ * lineage; the runtime fills both from the run it already has loaded, so this
+ * is a pure context read with no I/O. The new run records `$parentRunId` (the
+ * edge) and inherits the parent's `$rootRunId` (the parent itself when it is a
+ * root), so a daisy chain or fan-out of any depth groups under one root id.
+ * Returns `undefined` for a top-level `start()`, which has no context, so
+ * standalone runs carry no lineage.
+ */
+function resolveLineageAttributes(): Record<string, string> | undefined {
+ const store = contextStorage.getStore();
+ const parentRunId = store?.workflowMetadata?.workflowRunId;
+ if (!parentRunId) return undefined;
+
+ return {
+ [ROOT_RUN_ID_ATTRIBUTE]: store.rootRunId ?? parentRunId,
+ [PARENT_RUN_ID_ATTRIBUTE]: parentRunId,
+ };
+}
+
 // `deploymentId: 'latest'` is a no-op in Worlds without atomic deployments.
 // The warning that explains this only needs to fire once per process: a
 // workflow that hardcodes 'latest' for its Vercel deployment would otherwise
@@ -360,13 +385,24 @@ export async function start<TArgs extends unknown[], TResult>(
  changes.map(({ key, value }) => [key, value as string])
  );
  }
- // Seed payload shared by run_created and the resilient-start queue
- // input. The flag rides along so server-side validation matches the
- // client-side check above on both paths.
- const attributeSeed = attributes
+
+ // Cross-run lineage: the reserved keys ride on the run's existing
+ // attributes, so they add no extra write. Caller attributes are spread
+ // last, so a caller with allowReservedAttributes can deliberately
+ // re-parent.
+ const lineage =
+ specVersion >= SPEC_VERSION_SUPPORTS_ATTRIBUTES
+ ? resolveLineageAttributes()
+ : undefined;
+ const runAttributes = lineage
+ ? { ...lineage, ...attributes }
+ : attributes;
+
+ // Shared by the run_created event and the resilient-start queue input.
+ const attributeSeed = runAttributes
  ? {
- attributes,
- ...(allowReservedAttributes
+ attributes: runAttributes,
+ ...(allowReservedAttributes || lineage != null
  ? { allowReservedAttributes: true as const }
  : {}),
  }

packages/core/src/runtime/step-executor.ts

@@ -81,6 +81,8 @@ export interface StepExecutorParams {
  workflowDeploymentId?: string;
  workflowName: string;
  workflowStartedAt: number;
+ /** Root run id of this run's lineage, carried into the step context. */
+ rootRunId?: string;
  stepId: string;
  stepName: string;
  encryptionKey?: CryptoKey;
@@ -690,6 +692,7 @@ export async function executeStep(
  features: { encryption: !!encryptionKey },
  },
  workflowDeploymentId: params.workflowDeploymentId,
+ rootRunId: params.rootRunId,
  ops,
  preCompletionOps,
  closureVars: hydratedInput.closureVars,

packages/core/src/step/context-storage.ts

@@ -22,6 +22,12 @@ export type StepContext = {
  workflowMetadata: WorkflowMetadata;
  /** Deployment that owns the current workflow run, used for forwarded streams. */
  workflowDeploymentId?: string;
+ /**
+ * Root run id of the current run's lineage (`$rootRunId`), so a nested
+ * `start()` inherits it without reloading the parent. Set by the runtime from
+ * the run it already has loaded.
+ */
+ rootRunId?: string;
  ops: Promise<void>[];
  /**
  * Operations that MUST be durably committed before the step's

packages/world-testing/src/index.mts

@@ -3,6 +3,7 @@ import { errors } from './errors.mjs';
 import { hooks } from './hooks.mjs';
 import { idempotency } from './idempotency.mjs';
 import { inlineExecution } from './inline-execution.mjs';
+import { lineage } from './lineage.mjs';
 import { nullByte } from './null-byte.mjs';
 
 export function createTestSuite(pkgName: string) {
@@ -12,4 +13,5 @@ export function createTestSuite(pkgName: string) {
  nullByte(pkgName);
  errors(pkgName);
  inlineExecution(pkgName);
+ lineage(pkgName);
 }

.changeset/start-cross-run-lineage.md

@@ -0,0 +1,6 @@
+---
+"@workflow/core": patch
+"@workflow/world": patch
+---
+
+Record cross-run lineage when `start()` is called from inside a workflow or step: the new run is tagged with `$parentRunId` (its direct parent) and inherits the parent's `$rootRunId`, so a daisy chain or fan-out of any depth groups under one root id.

docs/content/docs/v5/observability/attributes.mdx

@@ -57,6 +57,15 @@ export async function cleanupAttributes() {
 
 Attribute keys must be 1-256 characters, values must be strings up to 256 bytes, and each run can have up to 64 attributes. Keys that start with `$` are reserved for framework and library code.
 
+## Reserved keys
+
+When `start()` is called from inside a running workflow or step, the new run is automatically tagged with two reserved attributes:
+
+- `$parentRunId`: the run that started it.
+- `$rootRunId`: the root of the chain. It is inherited, so every run in a daisy chain or fan-out shares one root id.
+
+Top-level runs (started outside any workflow or step) are not tagged.
+
 ## Viewing attributes
 
 The run details panel in the observability UI shows the run's current attributes as key-value rows. Reserved `$`-prefixed keys are marked with a badge and sorted after user keys:

packages/core/src/runtime.ts

@@ -17,6 +17,7 @@ import {
 import {
  type Event,
  getQueueTopicPrefix,
+ ROOT_RUN_ID_ATTRIBUTE,
  resolveQueueNamespace,
  SPEC_VERSION_CURRENT,
  SPEC_VERSION_SUPPORTS_COMPRESSION,
@@ -242,6 +243,17 @@ function hasRecordedTerminalRunEvent(events: Event[], runId: string): boolean {
  return true;
 }
 
+/**
+ * The lineage root of a loaded run: its `$rootRunId` attribute, or its own id
+ * when it is itself a root.
+ */
+function rootRunIdFrom(
+ attributes: Record<string, string> | undefined,
+ runId: string
+): string {
+ return attributes?.[ROOT_RUN_ID_ATTRIBUTE] ?? runId;
+}
+
 /**
  * Whether the run has any hook or wait that an out-of-band writer could
  * append an event for between an inline step's `step_completed` write and
@@ -728,6 +740,7 @@ export function workflowEntrypoint(
  workflowDeploymentId: bgRun.deploymentId,
  workflowName,
  workflowStartedAt: bgStartedAt,
+ rootRunId: rootRunIdFrom(bgRun.attributes, runId),
  stepId: incomingStepId,
  stepName: incomingStepName,
  runSpecVersion: bgRun.specVersion,
@@ -1984,6 +1997,10 @@ export function workflowEntrypoint(
  workflowRun.deploymentId,
  workflowName,
  workflowStartedAt,
+ rootRunId: rootRunIdFrom(
+ workflowRun.attributes,
+ runId
+ ),
  stepId: s.correlationId,
  stepName: s.stepName,
  runSpecVersion: workflowRun.specVersion,

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

@@ -0,0 +1,156 @@
+import {
+ SPEC_VERSION_CURRENT,
+ SPEC_VERSION_SUPPORTS_ATTRIBUTES,
+} from '@workflow/world';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { contextStorage } from '../step/context-storage.js';
+import { start } from './start.js';
+import { setWorld } from './world.js';
+
+vi.mock('@vercel/functions', () => ({ waitUntil: vi.fn() }));
+vi.mock('../telemetry.js', () => ({
+ serializeTraceCarrier: vi.fn().mockResolvedValue({}),
+ trace: vi.fn((_name, fn) => fn(undefined)),
+}));
+
+/**
+ * Cross-run lineage: start() records reserved `$rootRunId` / `$parentRunId`
+ * attributes when it runs inside another run, so a daisy chain or fan-out
+ * groups under one root id. The lineage is a pure read of the ambient step
+ * context: the runtime fills both the parent run id and its root from the run
+ * it already has loaded, so start() never reads back the parent (`runs.get` is
+ * never called). A top-level start() records nothing.
+ */
+describe('start() cross-run lineage', () => {
+ let eventsCreate: ReturnType<typeof vi.fn>;
+ let runsGet: ReturnType<typeof vi.fn>;
+ let queue: ReturnType<typeof vi.fn>;
+
+ // The runtime requires the world to declare the current spec version; the
+ // per-run spec is driven separately via `opts.specVersion` where needed.
+ function useWorld() {
+ setWorld({
+ specVersion: SPEC_VERSION_CURRENT,
+ getDeploymentId: vi.fn().mockResolvedValue('deploy_123'),
+ events: { create: eventsCreate },
+ runs: { get: runsGet },
+ queue,
+ } as any);
+ }
+
+ beforeEach(() => {
+ eventsCreate = vi.fn().mockImplementation((runId) =>
+ Promise.resolve({
+ run: { runId: runId ?? 'wrun_x', status: 'pending' },
+ })
+ );
+ runsGet = vi.fn();
+ queue = vi.fn().mockResolvedValue(undefined);
+ useWorld();
+ });
+
+ afterEach(() => {
+ setWorld(undefined);
+ vi.clearAllMocks();
+ });
+
+ const wf = (id: string) =>
+ Object.assign(() => Promise.resolve('ok'), { workflowId: id });
+
+ /** Attributes seeded onto the run_created event for the first start() call. */
+ function seededAttributes(): Record<string, string> | undefined {
+ return eventsCreate.mock.calls[0]?.[1]?.eventData?.attributes;
+ }
+
+ /**
+ * Run `fn` as if executing inside a parent run's step context. Pass
+ * `rootRunId` to model the runtime having put the parent's root on the
+ * context (the wired path); omit it to exercise the anchor-to-parent default.
+ */
+ function insideRun<T>(
+ parentRunId: string,
+ fn: () => Promise<T>,
+ rootRunId?: string
+ ): Promise<T> {
+ return contextStorage.run(
+ {
+ stepMetadata: {
+ stepName: 'start',
+ stepId: 'step_1',
+ stepStartedAt: new Date(),
+ attempt: 1,
+ },
+ workflowMetadata: {
+ workflowName: 'parent',
+ workflowRunId: parentRunId,
+ workflowStartedAt: new Date(),
+ url: 'http://localhost:3000',
+ features: { encryption: false },
+ },
+ rootRunId,
+ ops: [],
+ } as any,
+ fn
+ );
+ }
+
+ it('records no lineage for a top-level start()', async () => {
+ await start(wf('test-workflow'), []);
+
+ expect(seededAttributes()).toBeUndefined();
+ expect(runsGet).not.toHaveBeenCalled();
+ });
+
+ it('inherits the root from the context with no read-back', async () => {
+ await insideRun(
+ 'wrun_parent',
+ () => start(wf('child-workflow'), []),
+ 'wrun_root'
+ );
+
+ expect(runsGet).not.toHaveBeenCalled();
+ expect(seededAttributes()).toEqual({
+ $rootRunId: 'wrun_root',
+ $parentRunId: 'wrun_parent',
+ });
+ });
+
+ it('anchors the root to the parent when the context carries none', async () => {
+ await insideRun('wrun_parent', () => start(wf('child-workflow'), []));
+
+ expect(runsGet).not.toHaveBeenCalled();
+ expect(seededAttributes()).toEqual({
+ $rootRunId: 'wrun_parent',
+ $parentRunId: 'wrun_parent',
+ });
+ });
+
+ it('merges caller-provided attributes over the inferred lineage', async () => {
+ await insideRun(
+ 'wrun_parent',
+ () => start(wf('child-workflow'), [], { attributes: { tenant: 't1' } }),
+ 'wrun_root'
+ );
+
+ const expected = {
+ $rootRunId: 'wrun_root',
+ $parentRunId: 'wrun_parent',
+ tenant: 't1',
+ };
+ expect(seededAttributes()).toEqual(expected);
+ // Lineage must also ride the resilient-start queue input, not just the
+ // run_created event, so both creation paths carry it.
+ expect(queue.mock.calls[0]?.[1]?.runInput?.attributes).toEqual(expected);
+ });
+
+ it('records no lineage when the run predates attribute support', async () => {
+ await insideRun('wrun_parent', () =>
+ start(wf('child-workflow'), [], {
+ specVersion: SPEC_VERSION_SUPPORTS_ATTRIBUTES - 1,
+ })
+ );
+
+ expect(seededAttributes()).toBeUndefined();
+ expect(runsGet).not.toHaveBeenCalled();
+ });
+});

packages/core/src/runtime/start.ts

@@ -3,6 +3,8 @@ import { workflowDisplayName } from '@workflow/utils/parse-name';
 import type { WorkflowInvokePayload, World } from '@workflow/world';
 import {
  isLegacySpecVersion,
+ PARENT_RUN_ID_ATTRIBUTE,
+ ROOT_RUN_ID_ATTRIBUTE,
  SPEC_VERSION_SUPPORTS_ATTRIBUTES,
  SPEC_VERSION_SUPPORTS_CBOR_QUEUE_TRANSPORT,
  SPEC_VERSION_SUPPORTS_COMPRESSION,
@@ -19,6 +21,7 @@ import {
  dehydrateWorkflowArguments,
  SerializationFormat,
 } from '../serialization.js';
+import { contextStorage } from '../step/context-storage.js';
 import * as Attribute from '../telemetry/semantic-conventions.js';
 import { serializeTraceCarrier, trace } from '../telemetry.js';
 import { version as workflowCoreVersion } from '../version.js';
@@ -42,6 +45,28 @@ const CROSS_DEPLOYMENT_CAPABILITY_PROBE_TIMEOUT_MS = 2_000;
 /** ULID generator for client-side runId generation */
 const ulid = monotonicFactory();
 
+/**
+ * Cross-run lineage for a run being started from inside another run.
+ *
+ * The ambient step context carries the parent run id and the root of its
+ * lineage; the runtime fills both from the run it already has loaded, so this
+ * is a pure context read with no I/O. The new run records `$parentRunId` (the
+ * edge) and inherits the parent's `$rootRunId` (the parent itself when it is a
+ * root), so a daisy chain or fan-out of any depth groups under one root id.
+ * Returns `undefined` for a top-level `start()`, which has no context, so
+ * standalone runs carry no lineage.
+ */
+function resolveLineageAttributes(): Record<string, string> | undefined {
+ const store = contextStorage.getStore();
+ const parentRunId = store?.workflowMetadata?.workflowRunId;
+ if (!parentRunId) return undefined;
+
+ return {
+ [ROOT_RUN_ID_ATTRIBUTE]: store.rootRunId ?? parentRunId,
+ [PARENT_RUN_ID_ATTRIBUTE]: parentRunId,
+ };
+}
+
 // `deploymentId: 'latest'` is a no-op in Worlds without atomic deployments.
 // The warning that explains this only needs to fire once per process: a
 // workflow that hardcodes 'latest' for its Vercel deployment would otherwise
@@ -360,13 +385,24 @@ export async function start<TArgs extends unknown[], TResult>(
  changes.map(({ key, value }) => [key, value as string])
  );
  }
- // Seed payload shared by run_created and the resilient-start queue
- // input. The flag rides along so server-side validation matches the
- // client-side check above on both paths.
- const attributeSeed = attributes
+
+ // Cross-run lineage: the reserved keys ride on the run's existing
+ // attributes, so they add no extra write. Caller attributes are spread
+ // last, so a caller with allowReservedAttributes can deliberately
+ // re-parent.
+ const lineage =
+ specVersion >= SPEC_VERSION_SUPPORTS_ATTRIBUTES
+ ? resolveLineageAttributes()
+ : undefined;
+ const runAttributes = lineage
+ ? { ...lineage, ...attributes }
+ : attributes;
+
+ // Shared by the run_created event and the resilient-start queue input.
+ const attributeSeed = runAttributes
  ? {
- attributes,
- ...(allowReservedAttributes
+ attributes: runAttributes,
+ ...(allowReservedAttributes || lineage != null
  ? { allowReservedAttributes: true as const }
  : {}),
  }

packages/core/src/runtime/step-executor.ts

@@ -81,6 +81,8 @@ export interface StepExecutorParams {
  workflowDeploymentId?: string;
  workflowName: string;
  workflowStartedAt: number;
+ /** Root run id of this run's lineage, carried into the step context. */
+ rootRunId?: string;
  stepId: string;
  stepName: string;
  encryptionKey?: CryptoKey;
@@ -690,6 +692,7 @@ export async function executeStep(
  features: { encryption: !!encryptionKey },
  },
  workflowDeploymentId: params.workflowDeploymentId,
+ rootRunId: params.rootRunId,
  ops,
  preCompletionOps,
  closureVars: hydratedInput.closureVars,

packages/core/src/step/context-storage.ts

@@ -22,6 +22,12 @@ export type StepContext = {
  workflowMetadata: WorkflowMetadata;
  /** Deployment that owns the current workflow run, used for forwarded streams. */
  workflowDeploymentId?: string;
+ /**
+ * Root run id of the current run's lineage (`$rootRunId`), so a nested
+ * `start()` inherits it without reloading the parent. Set by the runtime from
+ * the run it already has loaded.
+ */
+ rootRunId?: string;
  ops: Promise<void>[];
  /**
  * Operations that MUST be durably committed before the step's

packages/world-testing/src/index.mts

@@ -3,6 +3,7 @@ import { errors } from './errors.mjs';
 import { hooks } from './hooks.mjs';
 import { idempotency } from './idempotency.mjs';
 import { inlineExecution } from './inline-execution.mjs';
+import { lineage } from './lineage.mjs';
 import { nullByte } from './null-byte.mjs';
 
 export function createTestSuite(pkgName: string) {
@@ -12,4 +13,5 @@ export function createTestSuite(pkgName: string) {
  nullByte(pkgName);
  errors(pkgName);
  inlineExecution(pkgName);
+ lineage(pkgName);
 }

.changeset/start-cross-run-lineage.md

@@ -0,0 +1,6 @@
+---
+"@workflow/core": patch
+"@workflow/world": patch
+---
+
+Record cross-run lineage when `start()` is called from inside a workflow or step: the new run is tagged with `$parentRunId` (its direct parent) and inherits the parent's `$rootRunId`, so a daisy chain or fan-out of any depth groups under one root id.

docs/content/docs/v5/observability/attributes.mdx

@@ -57,6 +57,15 @@ export async function cleanupAttributes() {
 
 Attribute keys must be 1-256 characters, values must be strings up to 256 bytes, and each run can have up to 64 attributes. Keys that start with `$` are reserved for framework and library code.
 
+## Reserved keys
+
+When `start()` is called from inside a running workflow or step, the new run is automatically tagged with two reserved attributes:
+
+- `$parentRunId`: the run that started it.
+- `$rootRunId`: the root of the chain. It is inherited, so every run in a daisy chain or fan-out shares one root id.
+
+Top-level runs (started outside any workflow or step) are not tagged.
+
 ## Viewing attributes
 
 The run details panel in the observability UI shows the run's current attributes as key-value rows. Reserved `$`-prefixed keys are marked with a badge and sorted after user keys:

packages/core/src/runtime.ts

@@ -17,6 +17,7 @@ import {
 import {
  type Event,
  getQueueTopicPrefix,
+ ROOT_RUN_ID_ATTRIBUTE,
  resolveQueueNamespace,
  SPEC_VERSION_CURRENT,
  SPEC_VERSION_SUPPORTS_COMPRESSION,
@@ -242,6 +243,17 @@ function hasRecordedTerminalRunEvent(events: Event[], runId: string): boolean {
  return true;
 }
 
+/**
+ * The lineage root of a loaded run: its `$rootRunId` attribute, or its own id
+ * when it is itself a root.
+ */
+function rootRunIdFrom(
+ attributes: Record<string, string> | undefined,
+ runId: string
+): string {
+ return attributes?.[ROOT_RUN_ID_ATTRIBUTE] ?? runId;
+}
+
 /**
  * Whether the run has any hook or wait that an out-of-band writer could
  * append an event for between an inline step's `step_completed` write and
@@ -728,6 +740,7 @@ export function workflowEntrypoint(
  workflowDeploymentId: bgRun.deploymentId,
  workflowName,
  workflowStartedAt: bgStartedAt,
+ rootRunId: rootRunIdFrom(bgRun.attributes, runId),
  stepId: incomingStepId,
  stepName: incomingStepName,
  runSpecVersion: bgRun.specVersion,
@@ -1984,6 +1997,10 @@ export function workflowEntrypoint(
  workflowRun.deploymentId,
  workflowName,
  workflowStartedAt,
+ rootRunId: rootRunIdFrom(
+ workflowRun.attributes,
+ runId
+ ),
  stepId: s.correlationId,
  stepName: s.stepName,
  runSpecVersion: workflowRun.specVersion,

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

@@ -0,0 +1,156 @@
+import {
+ SPEC_VERSION_CURRENT,
+ SPEC_VERSION_SUPPORTS_ATTRIBUTES,
+} from '@workflow/world';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { contextStorage } from '../step/context-storage.js';
+import { start } from './start.js';
+import { setWorld } from './world.js';
+
+vi.mock('@vercel/functions', () => ({ waitUntil: vi.fn() }));
+vi.mock('../telemetry.js', () => ({
+ serializeTraceCarrier: vi.fn().mockResolvedValue({}),
+ trace: vi.fn((_name, fn) => fn(undefined)),
+}));
+
+/**
+ * Cross-run lineage: start() records reserved `$rootRunId` / `$parentRunId`
+ * attributes when it runs inside another run, so a daisy chain or fan-out
+ * groups under one root id. The lineage is a pure read of the ambient step
+ * context: the runtime fills both the parent run id and its root from the run
+ * it already has loaded, so start() never reads back the parent (`runs.get` is
+ * never called). A top-level start() records nothing.
+ */
+describe('start() cross-run lineage', () => {
+ let eventsCreate: ReturnType<typeof vi.fn>;
+ let runsGet: ReturnType<typeof vi.fn>;
+ let queue: ReturnType<typeof vi.fn>;
+
+ // The runtime requires the world to declare the current spec version; the
+ // per-run spec is driven separately via `opts.specVersion` where needed.
+ function useWorld() {
+ setWorld({
+ specVersion: SPEC_VERSION_CURRENT,
+ getDeploymentId: vi.fn().mockResolvedValue('deploy_123'),
+ events: { create: eventsCreate },
+ runs: { get: runsGet },
+ queue,
+ } as any);
+ }
+
+ beforeEach(() => {
+ eventsCreate = vi.fn().mockImplementation((runId) =>
+ Promise.resolve({
+ run: { runId: runId ?? 'wrun_x', status: 'pending' },
+ })
+ );
+ runsGet = vi.fn();
+ queue = vi.fn().mockResolvedValue(undefined);
+ useWorld();
+ });
+
+ afterEach(() => {
+ setWorld(undefined);
+ vi.clearAllMocks();
+ });
+
+ const wf = (id: string) =>
+ Object.assign(() => Promise.resolve('ok'), { workflowId: id });
+
+ /** Attributes seeded onto the run_created event for the first start() call. */
+ function seededAttributes(): Record<string, string> | undefined {
+ return eventsCreate.mock.calls[0]?.[1]?.eventData?.attributes;
+ }
+
+ /**
+ * Run `fn` as if executing inside a parent run's step context. Pass
+ * `rootRunId` to model the runtime having put the parent's root on the
+ * context (the wired path); omit it to exercise the anchor-to-parent default.
+ */
+ function insideRun<T>(
+ parentRunId: string,
+ fn: () => Promise<T>,
+ rootRunId?: string
+ ): Promise<T> {
+ return contextStorage.run(
+ {
+ stepMetadata: {
+ stepName: 'start',
+ stepId: 'step_1',
+ stepStartedAt: new Date(),
+ attempt: 1,
+ },
+ workflowMetadata: {
+ workflowName: 'parent',
+ workflowRunId: parentRunId,
+ workflowStartedAt: new Date(),
+ url: 'http://localhost:3000',
+ features: { encryption: false },
+ },
+ rootRunId,
+ ops: [],
+ } as any,
+ fn
+ );
+ }
+
+ it('records no lineage for a top-level start()', async () => {
+ await start(wf('test-workflow'), []);
+
+ expect(seededAttributes()).toBeUndefined();
+ expect(runsGet).not.toHaveBeenCalled();
+ });
+
+ it('inherits the root from the context with no read-back', async () => {
+ await insideRun(
+ 'wrun_parent',
+ () => start(wf('child-workflow'), []),
+ 'wrun_root'
+ );
+
+ expect(runsGet).not.toHaveBeenCalled();
+ expect(seededAttributes()).toEqual({
+ $rootRunId: 'wrun_root',
+ $parentRunId: 'wrun_parent',
+ });
+ });
+
+ it('anchors the root to the parent when the context carries none', async () => {
+ await insideRun('wrun_parent', () => start(wf('child-workflow'), []));
+
+ expect(runsGet).not.toHaveBeenCalled();
+ expect(seededAttributes()).toEqual({
+ $rootRunId: 'wrun_parent',
+ $parentRunId: 'wrun_parent',
+ });
+ });
+
+ it('merges caller-provided attributes over the inferred lineage', async () => {
+ await insideRun(
+ 'wrun_parent',
+ () => start(wf('child-workflow'), [], { attributes: { tenant: 't1' } }),
+ 'wrun_root'
+ );
+
+ const expected = {
+ $rootRunId: 'wrun_root',
+ $parentRunId: 'wrun_parent',
+ tenant: 't1',
+ };
+ expect(seededAttributes()).toEqual(expected);
+ // Lineage must also ride the resilient-start queue input, not just the
+ // run_created event, so both creation paths carry it.
+ expect(queue.mock.calls[0]?.[1]?.runInput?.attributes).toEqual(expected);
+ });
+
+ it('records no lineage when the run predates attribute support', async () => {
+ await insideRun('wrun_parent', () =>
+ start(wf('child-workflow'), [], {
+ specVersion: SPEC_VERSION_SUPPORTS_ATTRIBUTES - 1,
+ })
+ );
+
+ expect(seededAttributes()).toBeUndefined();
+ expect(runsGet).not.toHaveBeenCalled();
+ });
+});

packages/core/src/runtime/start.ts

@@ -3,6 +3,8 @@ import { workflowDisplayName } from '@workflow/utils/parse-name';
 import type { WorkflowInvokePayload, World } from '@workflow/world';
 import {
  isLegacySpecVersion,
+ PARENT_RUN_ID_ATTRIBUTE,
+ ROOT_RUN_ID_ATTRIBUTE,
  SPEC_VERSION_SUPPORTS_ATTRIBUTES,
  SPEC_VERSION_SUPPORTS_CBOR_QUEUE_TRANSPORT,
  SPEC_VERSION_SUPPORTS_COMPRESSION,
@@ -19,6 +21,7 @@ import {
  dehydrateWorkflowArguments,
  SerializationFormat,
 } from '../serialization.js';
+import { contextStorage } from '../step/context-storage.js';
 import * as Attribute from '../telemetry/semantic-conventions.js';
 import { serializeTraceCarrier, trace } from '../telemetry.js';
 import { version as workflowCoreVersion } from '../version.js';
@@ -42,6 +45,28 @@ const CROSS_DEPLOYMENT_CAPABILITY_PROBE_TIMEOUT_MS = 2_000;
 /** ULID generator for client-side runId generation */
 const ulid = monotonicFactory();
 
+/**
+ * Cross-run lineage for a run being started from inside another run.
+ *
+ * The ambient step context carries the parent run id and the root of its
+ * lineage; the runtime fills both from the run it already has loaded, so this
+ * is a pure context read with no I/O. The new run records `$parentRunId` (the
+ * edge) and inherits the parent's `$rootRunId` (the parent itself when it is a
+ * root), so a daisy chain or fan-out of any depth groups under one root id.
+ * Returns `undefined` for a top-level `start()`, which has no context, so
+ * standalone runs carry no lineage.
+ */
+function resolveLineageAttributes(): Record<string, string> | undefined {
+ const store = contextStorage.getStore();
+ const parentRunId = store?.workflowMetadata?.workflowRunId;
+ if (!parentRunId) return undefined;
+
+ return {
+ [ROOT_RUN_ID_ATTRIBUTE]: store.rootRunId ?? parentRunId,
+ [PARENT_RUN_ID_ATTRIBUTE]: parentRunId,
+ };
+}
+
 // `deploymentId: 'latest'` is a no-op in Worlds without atomic deployments.
 // The warning that explains this only needs to fire once per process: a
 // workflow that hardcodes 'latest' for its Vercel deployment would otherwise
@@ -360,13 +385,24 @@ export async function start<TArgs extends unknown[], TResult>(
  changes.map(({ key, value }) => [key, value as string])
  );
  }
- // Seed payload shared by run_created and the resilient-start queue
- // input. The flag rides along so server-side validation matches the
- // client-side check above on both paths.
- const attributeSeed = attributes
+
+ // Cross-run lineage: the reserved keys ride on the run's existing
+ // attributes, so they add no extra write. Caller attributes are spread
+ // last, so a caller with allowReservedAttributes can deliberately
+ // re-parent.
+ const lineage =
+ specVersion >= SPEC_VERSION_SUPPORTS_ATTRIBUTES
+ ? resolveLineageAttributes()
+ : undefined;
+ const runAttributes = lineage
+ ? { ...lineage, ...attributes }
+ : attributes;
+
+ // Shared by the run_created event and the resilient-start queue input.
+ const attributeSeed = runAttributes
  ? {
- attributes,
- ...(allowReservedAttributes
+ attributes: runAttributes,
+ ...(allowReservedAttributes || lineage != null
  ? { allowReservedAttributes: true as const }
  : {}),
  }

packages/core/src/runtime/step-executor.ts

@@ -81,6 +81,8 @@ export interface StepExecutorParams {
  workflowDeploymentId?: string;
  workflowName: string;
  workflowStartedAt: number;
+ /** Root run id of this run's lineage, carried into the step context. */
+ rootRunId?: string;
  stepId: string;
  stepName: string;
  encryptionKey?: CryptoKey;
@@ -690,6 +692,7 @@ export async function executeStep(
  features: { encryption: !!encryptionKey },
  },
  workflowDeploymentId: params.workflowDeploymentId,
+ rootRunId: params.rootRunId,
  ops,
  preCompletionOps,
  closureVars: hydratedInput.closureVars,

packages/core/src/step/context-storage.ts

@@ -22,6 +22,12 @@ export type StepContext = {
  workflowMetadata: WorkflowMetadata;
  /** Deployment that owns the current workflow run, used for forwarded streams. */
  workflowDeploymentId?: string;
+ /**
+ * Root run id of the current run's lineage (`$rootRunId`), so a nested
+ * `start()` inherits it without reloading the parent. Set by the runtime from
+ * the run it already has loaded.
+ */
+ rootRunId?: string;
  ops: Promise<void>[];
  /**
  * Operations that MUST be durably committed before the step's

packages/world-testing/src/index.mts

@@ -3,6 +3,7 @@ import { errors } from './errors.mjs';
 import { hooks } from './hooks.mjs';
 import { idempotency } from './idempotency.mjs';
 import { inlineExecution } from './inline-execution.mjs';
+import { lineage } from './lineage.mjs';
 import { nullByte } from './null-byte.mjs';
 
 export function createTestSuite(pkgName: string) {
@@ -12,4 +13,5 @@ export function createTestSuite(pkgName: string) {
  nullByte(pkgName);
  errors(pkgName);
  inlineExecution(pkgName);
+ lineage(pkgName);
 }

.changeset/start-cross-run-lineage.md

@@ -0,0 +1,6 @@
+---
+"@workflow/core": patch
+"@workflow/world": patch
+---
+
+Record cross-run lineage when `start()` is called from inside a workflow or step: the new run is tagged with `$parentRunId` (its direct parent) and inherits the parent's `$rootRunId`, so a daisy chain or fan-out of any depth groups under one root id.

docs/content/docs/v5/observability/attributes.mdx

@@ -57,6 +57,15 @@ export async function cleanupAttributes() {
 
 Attribute keys must be 1-256 characters, values must be strings up to 256 bytes, and each run can have up to 64 attributes. Keys that start with `$` are reserved for framework and library code.
 
+## Reserved keys
+
+When `start()` is called from inside a running workflow or step, the new run is automatically tagged with two reserved attributes:
+
+- `$parentRunId`: the run that started it.
+- `$rootRunId`: the root of the chain. It is inherited, so every run in a daisy chain or fan-out shares one root id.
+
+Top-level runs (started outside any workflow or step) are not tagged.
+
 ## Viewing attributes
 
 The run details panel in the observability UI shows the run's current attributes as key-value rows. Reserved `$`-prefixed keys are marked with a badge and sorted after user keys:

packages/core/src/runtime.ts

@@ -17,6 +17,7 @@ import {
 import {
  type Event,
  getQueueTopicPrefix,
+ ROOT_RUN_ID_ATTRIBUTE,
  resolveQueueNamespace,
  SPEC_VERSION_CURRENT,
  SPEC_VERSION_SUPPORTS_COMPRESSION,
@@ -242,6 +243,17 @@ function hasRecordedTerminalRunEvent(events: Event[], runId: string): boolean {
  return true;
 }
 
+/**
+ * The lineage root of a loaded run: its `$rootRunId` attribute, or its own id
+ * when it is itself a root.
+ */
+function rootRunIdFrom(
+ attributes: Record<string, string> | undefined,
+ runId: string
+): string {
+ return attributes?.[ROOT_RUN_ID_ATTRIBUTE] ?? runId;
+}
+
 /**
  * Whether the run has any hook or wait that an out-of-band writer could
  * append an event for between an inline step's `step_completed` write and
@@ -728,6 +740,7 @@ export function workflowEntrypoint(
  workflowDeploymentId: bgRun.deploymentId,
  workflowName,
  workflowStartedAt: bgStartedAt,
+ rootRunId: rootRunIdFrom(bgRun.attributes, runId),
  stepId: incomingStepId,
  stepName: incomingStepName,
  runSpecVersion: bgRun.specVersion,
@@ -1984,6 +1997,10 @@ export function workflowEntrypoint(
  workflowRun.deploymentId,
  workflowName,
  workflowStartedAt,
+ rootRunId: rootRunIdFrom(
+ workflowRun.attributes,
+ runId
+ ),
  stepId: s.correlationId,
  stepName: s.stepName,
  runSpecVersion: workflowRun.specVersion,

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

@@ -0,0 +1,156 @@
+import {
+ SPEC_VERSION_CURRENT,
+ SPEC_VERSION_SUPPORTS_ATTRIBUTES,
+} from '@workflow/world';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { contextStorage } from '../step/context-storage.js';
+import { start } from './start.js';
+import { setWorld } from './world.js';
+
+vi.mock('@vercel/functions', () => ({ waitUntil: vi.fn() }));
+vi.mock('../telemetry.js', () => ({
+ serializeTraceCarrier: vi.fn().mockResolvedValue({}),
+ trace: vi.fn((_name, fn) => fn(undefined)),
+}));
+
+/**
+ * Cross-run lineage: start() records reserved `$rootRunId` / `$parentRunId`
+ * attributes when it runs inside another run, so a daisy chain or fan-out
+ * groups under one root id. The lineage is a pure read of the ambient step
+ * context: the runtime fills both the parent run id and its root from the run
+ * it already has loaded, so start() never reads back the parent (`runs.get` is
+ * never called). A top-level start() records nothing.
+ */
+describe('start() cross-run lineage', () => {
+ let eventsCreate: ReturnType<typeof vi.fn>;
+ let runsGet: ReturnType<typeof vi.fn>;
+ let queue: ReturnType<typeof vi.fn>;
+
+ // The runtime requires the world to declare the current spec version; the
+ // per-run spec is driven separately via `opts.specVersion` where needed.
+ function useWorld() {
+ setWorld({
+ specVersion: SPEC_VERSION_CURRENT,
+ getDeploymentId: vi.fn().mockResolvedValue('deploy_123'),
+ events: { create: eventsCreate },
+ runs: { get: runsGet },
+ queue,
+ } as any);
+ }
+
+ beforeEach(() => {
+ eventsCreate = vi.fn().mockImplementation((runId) =>
+ Promise.resolve({
+ run: { runId: runId ?? 'wrun_x', status: 'pending' },
+ })
+ );
+ runsGet = vi.fn();
+ queue = vi.fn().mockResolvedValue(undefined);
+ useWorld();
+ });
+
+ afterEach(() => {
+ setWorld(undefined);
+ vi.clearAllMocks();
+ });
+
+ const wf = (id: string) =>
+ Object.assign(() => Promise.resolve('ok'), { workflowId: id });
+
+ /** Attributes seeded onto the run_created event for the first start() call. */
+ function seededAttributes(): Record<string, string> | undefined {
+ return eventsCreate.mock.calls[0]?.[1]?.eventData?.attributes;
+ }
+
+ /**
+ * Run `fn` as if executing inside a parent run's step context. Pass
+ * `rootRunId` to model the runtime having put the parent's root on the
+ * context (the wired path); omit it to exercise the anchor-to-parent default.
+ */
+ function insideRun<T>(
+ parentRunId: string,
+ fn: () => Promise<T>,
+ rootRunId?: string
+ ): Promise<T> {
+ return contextStorage.run(
+ {
+ stepMetadata: {
+ stepName: 'start',
+ stepId: 'step_1',
+ stepStartedAt: new Date(),
+ attempt: 1,
+ },
+ workflowMetadata: {
+ workflowName: 'parent',
+ workflowRunId: parentRunId,
+ workflowStartedAt: new Date(),
+ url: 'http://localhost:3000',
+ features: { encryption: false },
+ },
+ rootRunId,
+ ops: [],
+ } as any,
+ fn
+ );
+ }
+
+ it('records no lineage for a top-level start()', async () => {
+ await start(wf('test-workflow'), []);
+
+ expect(seededAttributes()).toBeUndefined();
+ expect(runsGet).not.toHaveBeenCalled();
+ });
+
+ it('inherits the root from the context with no read-back', async () => {
+ await insideRun(
+ 'wrun_parent',
+ () => start(wf('child-workflow'), []),
+ 'wrun_root'
+ );
+
+ expect(runsGet).not.toHaveBeenCalled();
+ expect(seededAttributes()).toEqual({
+ $rootRunId: 'wrun_root',
+ $parentRunId: 'wrun_parent',
+ });
+ });
+
+ it('anchors the root to the parent when the context carries none', async () => {
+ await insideRun('wrun_parent', () => start(wf('child-workflow'), []));
+
+ expect(runsGet).not.toHaveBeenCalled();
+ expect(seededAttributes()).toEqual({
+ $rootRunId: 'wrun_parent',
+ $parentRunId: 'wrun_parent',
+ });
+ });
+
+ it('merges caller-provided attributes over the inferred lineage', async () => {
+ await insideRun(
+ 'wrun_parent',
+ () => start(wf('child-workflow'), [], { attributes: { tenant: 't1' } }),
+ 'wrun_root'
+ );
+
+ const expected = {
+ $rootRunId: 'wrun_root',
+ $parentRunId: 'wrun_parent',
+ tenant: 't1',
+ };
+ expect(seededAttributes()).toEqual(expected);
+ // Lineage must also ride the resilient-start queue input, not just the
+ // run_created event, so both creation paths carry it.
+ expect(queue.mock.calls[0]?.[1]?.runInput?.attributes).toEqual(expected);
+ });
+
+ it('records no lineage when the run predates attribute support', async () => {
+ await insideRun('wrun_parent', () =>
+ start(wf('child-workflow'), [], {
+ specVersion: SPEC_VERSION_SUPPORTS_ATTRIBUTES - 1,
+ })
+ );
+
+ expect(seededAttributes()).toBeUndefined();
+ expect(runsGet).not.toHaveBeenCalled();
+ });
+});

packages/core/src/runtime/start.ts

@@ -3,6 +3,8 @@ import { workflowDisplayName } from '@workflow/utils/parse-name';
 import type { WorkflowInvokePayload, World } from '@workflow/world';
 import {
  isLegacySpecVersion,
+ PARENT_RUN_ID_ATTRIBUTE,
+ ROOT_RUN_ID_ATTRIBUTE,
  SPEC_VERSION_SUPPORTS_ATTRIBUTES,
  SPEC_VERSION_SUPPORTS_CBOR_QUEUE_TRANSPORT,
  SPEC_VERSION_SUPPORTS_COMPRESSION,
@@ -19,6 +21,7 @@ import {
  dehydrateWorkflowArguments,
  SerializationFormat,
 } from '../serialization.js';
+import { contextStorage } from '../step/context-storage.js';
 import * as Attribute from '../telemetry/semantic-conventions.js';
 import { serializeTraceCarrier, trace } from '../telemetry.js';
 import { version as workflowCoreVersion } from '../version.js';
@@ -42,6 +45,28 @@ const CROSS_DEPLOYMENT_CAPABILITY_PROBE_TIMEOUT_MS = 2_000;
 /** ULID generator for client-side runId generation */
 const ulid = monotonicFactory();
 
+/**
+ * Cross-run lineage for a run being started from inside another run.
+ *
+ * The ambient step context carries the parent run id and the root of its
+ * lineage; the runtime fills both from the run it already has loaded, so this
+ * is a pure context read with no I/O. The new run records `$parentRunId` (the
+ * edge) and inherits the parent's `$rootRunId` (the parent itself when it is a
+ * root), so a daisy chain or fan-out of any depth groups under one root id.
+ * Returns `undefined` for a top-level `start()`, which has no context, so
+ * standalone runs carry no lineage.
+ */
+function resolveLineageAttributes(): Record<string, string> | undefined {
+ const store = contextStorage.getStore();
+ const parentRunId = store?.workflowMetadata?.workflowRunId;
+ if (!parentRunId) return undefined;
+
+ return {
+ [ROOT_RUN_ID_ATTRIBUTE]: store.rootRunId ?? parentRunId,
+ [PARENT_RUN_ID_ATTRIBUTE]: parentRunId,
+ };
+}
+
 // `deploymentId: 'latest'` is a no-op in Worlds without atomic deployments.
 // The warning that explains this only needs to fire once per process: a
 // workflow that hardcodes 'latest' for its Vercel deployment would otherwise
@@ -360,13 +385,24 @@ export async function start<TArgs extends unknown[], TResult>(
  changes.map(({ key, value }) => [key, value as string])
  );
  }
- // Seed payload shared by run_created and the resilient-start queue
- // input. The flag rides along so server-side validation matches the
- // client-side check above on both paths.
- const attributeSeed = attributes
+
+ // Cross-run lineage: the reserved keys ride on the run's existing
+ // attributes, so they add no extra write. Caller attributes are spread
+ // last, so a caller with allowReservedAttributes can deliberately
+ // re-parent.
+ const lineage =
+ specVersion >= SPEC_VERSION_SUPPORTS_ATTRIBUTES
+ ? resolveLineageAttributes()
+ : undefined;
+ const runAttributes = lineage
+ ? { ...lineage, ...attributes }
+ : attributes;
+
+ // Shared by the run_created event and the resilient-start queue input.
+ const attributeSeed = runAttributes
  ? {
- attributes,
- ...(allowReservedAttributes
+ attributes: runAttributes,
+ ...(allowReservedAttributes || lineage != null
  ? { allowReservedAttributes: true as const }
  : {}),
  }

packages/core/src/runtime/step-executor.ts

@@ -81,6 +81,8 @@ export interface StepExecutorParams {
  workflowDeploymentId?: string;
  workflowName: string;
  workflowStartedAt: number;
+ /** Root run id of this run's lineage, carried into the step context. */
+ rootRunId?: string;
  stepId: string;
  stepName: string;
  encryptionKey?: CryptoKey;
@@ -690,6 +692,7 @@ export async function executeStep(
  features: { encryption: !!encryptionKey },
  },
  workflowDeploymentId: params.workflowDeploymentId,
+ rootRunId: params.rootRunId,
  ops,
  preCompletionOps,
  closureVars: hydratedInput.closureVars,

packages/core/src/step/context-storage.ts

@@ -22,6 +22,12 @@ export type StepContext = {
  workflowMetadata: WorkflowMetadata;
  /** Deployment that owns the current workflow run, used for forwarded streams. */
  workflowDeploymentId?: string;
+ /**
+ * Root run id of the current run's lineage (`$rootRunId`), so a nested
+ * `start()` inherits it without reloading the parent. Set by the runtime from
+ * the run it already has loaded.
+ */
+ rootRunId?: string;
  ops: Promise<void>[];
  /**
  * Operations that MUST be durably committed before the step's

packages/world-testing/src/index.mts

@@ -3,6 +3,7 @@ import { errors } from './errors.mjs';
 import { hooks } from './hooks.mjs';
 import { idempotency } from './idempotency.mjs';
 import { inlineExecution } from './inline-execution.mjs';
+import { lineage } from './lineage.mjs';
 import { nullByte } from './null-byte.mjs';
 
 export function createTestSuite(pkgName: string) {
@@ -12,4 +13,5 @@ export function createTestSuite(pkgName: string) {
  nullByte(pkgName);
  errors(pkgName);
  inlineExecution(pkgName);
+ lineage(pkgName);
 }

.changeset/start-cross-run-lineage.md

@@ -0,0 +1,6 @@
+---
+"@workflow/core": patch
+"@workflow/world": patch
+---
+
+Record cross-run lineage when `start()` is called from inside a workflow or step: the new run is tagged with `$parentRunId` (its direct parent) and inherits the parent's `$rootRunId`, so a daisy chain or fan-out of any depth groups under one root id.

docs/content/docs/v5/observability/attributes.mdx

@@ -57,6 +57,15 @@ export async function cleanupAttributes() {
 
 Attribute keys must be 1-256 characters, values must be strings up to 256 bytes, and each run can have up to 64 attributes. Keys that start with `$` are reserved for framework and library code.
 
+## Reserved keys
+
+When `start()` is called from inside a running workflow or step, the new run is automatically tagged with two reserved attributes:
+
+- `$parentRunId`: the run that started it.
+- `$rootRunId`: the root of the chain. It is inherited, so every run in a daisy chain or fan-out shares one root id.
+
+Top-level runs (started outside any workflow or step) are not tagged.
+
 ## Viewing attributes
 
 The run details panel in the observability UI shows the run's current attributes as key-value rows. Reserved `$`-prefixed keys are marked with a badge and sorted after user keys:

packages/core/src/runtime.ts

@@ -17,6 +17,7 @@ import {
 import {
  type Event,
  getQueueTopicPrefix,
+ ROOT_RUN_ID_ATTRIBUTE,
  resolveQueueNamespace,
  SPEC_VERSION_CURRENT,
  SPEC_VERSION_SUPPORTS_COMPRESSION,
@@ -242,6 +243,17 @@ function hasRecordedTerminalRunEvent(events: Event[], runId: string): boolean {
  return true;
 }
 
+/**
+ * The lineage root of a loaded run: its `$rootRunId` attribute, or its own id
+ * when it is itself a root.
+ */
+function rootRunIdFrom(
+ attributes: Record<string, string> | undefined,
+ runId: string
+): string {
+ return attributes?.[ROOT_RUN_ID_ATTRIBUTE] ?? runId;
+}
+
 /**
  * Whether the run has any hook or wait that an out-of-band writer could
  * append an event for between an inline step's `step_completed` write and
@@ -728,6 +740,7 @@ export function workflowEntrypoint(
  workflowDeploymentId: bgRun.deploymentId,
  workflowName,
  workflowStartedAt: bgStartedAt,
+ rootRunId: rootRunIdFrom(bgRun.attributes, runId),
  stepId: incomingStepId,
  stepName: incomingStepName,
  runSpecVersion: bgRun.specVersion,
@@ -1984,6 +1997,10 @@ export function workflowEntrypoint(
  workflowRun.deploymentId,
  workflowName,
  workflowStartedAt,
+ rootRunId: rootRunIdFrom(
+ workflowRun.attributes,
+ runId
+ ),
  stepId: s.correlationId,
  stepName: s.stepName,
  runSpecVersion: workflowRun.specVersion,

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

@@ -0,0 +1,156 @@
+import {
+ SPEC_VERSION_CURRENT,
+ SPEC_VERSION_SUPPORTS_ATTRIBUTES,
+} from '@workflow/world';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { contextStorage } from '../step/context-storage.js';
+import { start } from './start.js';
+import { setWorld } from './world.js';
+
+vi.mock('@vercel/functions', () => ({ waitUntil: vi.fn() }));
+vi.mock('../telemetry.js', () => ({
+ serializeTraceCarrier: vi.fn().mockResolvedValue({}),
+ trace: vi.fn((_name, fn) => fn(undefined)),
+}));
+
+/**
+ * Cross-run lineage: start() records reserved `$rootRunId` / `$parentRunId`
+ * attributes when it runs inside another run, so a daisy chain or fan-out
+ * groups under one root id. The lineage is a pure read of the ambient step
+ * context: the runtime fills both the parent run id and its root from the run
+ * it already has loaded, so start() never reads back the parent (`runs.get` is
+ * never called). A top-level start() records nothing.
+ */
+describe('start() cross-run lineage', () => {
+ let eventsCreate: ReturnType<typeof vi.fn>;
+ let runsGet: ReturnType<typeof vi.fn>;
+ let queue: ReturnType<typeof vi.fn>;
+
+ // The runtime requires the world to declare the current spec version; the
+ // per-run spec is driven separately via `opts.specVersion` where needed.
+ function useWorld() {
+ setWorld({
+ specVersion: SPEC_VERSION_CURRENT,
+ getDeploymentId: vi.fn().mockResolvedValue('deploy_123'),
+ events: { create: eventsCreate },
+ runs: { get: runsGet },
+ queue,
+ } as any);
+ }
+
+ beforeEach(() => {
+ eventsCreate = vi.fn().mockImplementation((runId) =>
+ Promise.resolve({
+ run: { runId: runId ?? 'wrun_x', status: 'pending' },
+ })
+ );
+ runsGet = vi.fn();
+ queue = vi.fn().mockResolvedValue(undefined);
+ useWorld();
+ });
+
+ afterEach(() => {
+ setWorld(undefined);
+ vi.clearAllMocks();
+ });
+
+ const wf = (id: string) =>
+ Object.assign(() => Promise.resolve('ok'), { workflowId: id });
+
+ /** Attributes seeded onto the run_created event for the first start() call. */
+ function seededAttributes(): Record<string, string> | undefined {
+ return eventsCreate.mock.calls[0]?.[1]?.eventData?.attributes;
+ }
+
+ /**
+ * Run `fn` as if executing inside a parent run's step context. Pass
+ * `rootRunId` to model the runtime having put the parent's root on the
+ * context (the wired path); omit it to exercise the anchor-to-parent default.
+ */
+ function insideRun<T>(
+ parentRunId: string,
+ fn: () => Promise<T>,
+ rootRunId?: string
+ ): Promise<T> {
+ return contextStorage.run(
+ {
+ stepMetadata: {
+ stepName: 'start',
+ stepId: 'step_1',
+ stepStartedAt: new Date(),
+ attempt: 1,
+ },
+ workflowMetadata: {
+ workflowName: 'parent',
+ workflowRunId: parentRunId,
+ workflowStartedAt: new Date(),
+ url: 'http://localhost:3000',
+ features: { encryption: false },
+ },
+ rootRunId,
+ ops: [],
+ } as any,
+ fn
+ );
+ }
+
+ it('records no lineage for a top-level start()', async () => {
+ await start(wf('test-workflow'), []);
+
+ expect(seededAttributes()).toBeUndefined();
+ expect(runsGet).not.toHaveBeenCalled();
+ });
+
+ it('inherits the root from the context with no read-back', async () => {
+ await insideRun(
+ 'wrun_parent',
+ () => start(wf('child-workflow'), []),
+ 'wrun_root'
+ );
+
+ expect(runsGet).not.toHaveBeenCalled();
+ expect(seededAttributes()).toEqual({
+ $rootRunId: 'wrun_root',
+ $parentRunId: 'wrun_parent',
+ });
+ });
+
+ it('anchors the root to the parent when the context carries none', async () => {
+ await insideRun('wrun_parent', () => start(wf('child-workflow'), []));
+
+ expect(runsGet).not.toHaveBeenCalled();
+ expect(seededAttributes()).toEqual({
+ $rootRunId: 'wrun_parent',
+ $parentRunId: 'wrun_parent',
+ });
+ });
+
+ it('merges caller-provided attributes over the inferred lineage', async () => {
+ await insideRun(
+ 'wrun_parent',
+ () => start(wf('child-workflow'), [], { attributes: { tenant: 't1' } }),
+ 'wrun_root'
+ );
+
+ const expected = {
+ $rootRunId: 'wrun_root',
+ $parentRunId: 'wrun_parent',
+ tenant: 't1',
+ };
+ expect(seededAttributes()).toEqual(expected);
+ // Lineage must also ride the resilient-start queue input, not just the
+ // run_created event, so both creation paths carry it.
+ expect(queue.mock.calls[0]?.[1]?.runInput?.attributes).toEqual(expected);
+ });
+
+ it('records no lineage when the run predates attribute support', async () => {
+ await insideRun('wrun_parent', () =>
+ start(wf('child-workflow'), [], {
+ specVersion: SPEC_VERSION_SUPPORTS_ATTRIBUTES - 1,
+ })
+ );
+
+ expect(seededAttributes()).toBeUndefined();
+ expect(runsGet).not.toHaveBeenCalled();
+ });
+});

packages/core/src/runtime/start.ts

@@ -3,6 +3,8 @@ import { workflowDisplayName } from '@workflow/utils/parse-name';
 import type { WorkflowInvokePayload, World } from '@workflow/world';
 import {
  isLegacySpecVersion,
+ PARENT_RUN_ID_ATTRIBUTE,
+ ROOT_RUN_ID_ATTRIBUTE,
  SPEC_VERSION_SUPPORTS_ATTRIBUTES,
  SPEC_VERSION_SUPPORTS_CBOR_QUEUE_TRANSPORT,
  SPEC_VERSION_SUPPORTS_COMPRESSION,
@@ -19,6 +21,7 @@ import {
  dehydrateWorkflowArguments,
  SerializationFormat,
 } from '../serialization.js';
+import { contextStorage } from '../step/context-storage.js';
 import * as Attribute from '../telemetry/semantic-conventions.js';
 import { serializeTraceCarrier, trace } from '../telemetry.js';
 import { version as workflowCoreVersion } from '../version.js';
@@ -42,6 +45,28 @@ const CROSS_DEPLOYMENT_CAPABILITY_PROBE_TIMEOUT_MS = 2_000;
 /** ULID generator for client-side runId generation */
 const ulid = monotonicFactory();
 
+/**
+ * Cross-run lineage for a run being started from inside another run.
+ *
+ * The ambient step context carries the parent run id and the root of its
+ * lineage; the runtime fills both from the run it already has loaded, so this
+ * is a pure context read with no I/O. The new run records `$parentRunId` (the
+ * edge) and inherits the parent's `$rootRunId` (the parent itself when it is a
+ * root), so a daisy chain or fan-out of any depth groups under one root id.
+ * Returns `undefined` for a top-level `start()`, which has no context, so
+ * standalone runs carry no lineage.
+ */
+function resolveLineageAttributes(): Record<string, string> | undefined {
+ const store = contextStorage.getStore();
+ const parentRunId = store?.workflowMetadata?.workflowRunId;
+ if (!parentRunId) return undefined;
+
+ return {
+ [ROOT_RUN_ID_ATTRIBUTE]: store.rootRunId ?? parentRunId,
+ [PARENT_RUN_ID_ATTRIBUTE]: parentRunId,
+ };
+}
+
 // `deploymentId: 'latest'` is a no-op in Worlds without atomic deployments.
 // The warning that explains this only needs to fire once per process: a
 // workflow that hardcodes 'latest' for its Vercel deployment would otherwise
@@ -360,13 +385,24 @@ export async function start<TArgs extends unknown[], TResult>(
  changes.map(({ key, value }) => [key, value as string])
  );
  }
- // Seed payload shared by run_created and the resilient-start queue
- // input. The flag rides along so server-side validation matches the
- // client-side check above on both paths.
- const attributeSeed = attributes
+
+ // Cross-run lineage: the reserved keys ride on the run's existing
+ // attributes, so they add no extra write. Caller attributes are spread
+ // last, so a caller with allowReservedAttributes can deliberately
+ // re-parent.
+ const lineage =
+ specVersion >= SPEC_VERSION_SUPPORTS_ATTRIBUTES
+ ? resolveLineageAttributes()
+ : undefined;
+ const runAttributes = lineage
+ ? { ...lineage, ...attributes }
+ : attributes;
+
+ // Shared by the run_created event and the resilient-start queue input.
+ const attributeSeed = runAttributes
  ? {
- attributes,
- ...(allowReservedAttributes
+ attributes: runAttributes,
+ ...(allowReservedAttributes || lineage != null
  ? { allowReservedAttributes: true as const }
  : {}),
  }

packages/core/src/runtime/step-executor.ts

@@ -81,6 +81,8 @@ export interface StepExecutorParams {
  workflowDeploymentId?: string;
  workflowName: string;
  workflowStartedAt: number;
+ /** Root run id of this run's lineage, carried into the step context. */
+ rootRunId?: string;
  stepId: string;
  stepName: string;
  encryptionKey?: CryptoKey;
@@ -690,6 +692,7 @@ export async function executeStep(
  features: { encryption: !!encryptionKey },
  },
  workflowDeploymentId: params.workflowDeploymentId,
+ rootRunId: params.rootRunId,
  ops,
  preCompletionOps,
  closureVars: hydratedInput.closureVars,

packages/core/src/step/context-storage.ts

@@ -22,6 +22,12 @@ export type StepContext = {
  workflowMetadata: WorkflowMetadata;
  /** Deployment that owns the current workflow run, used for forwarded streams. */
  workflowDeploymentId?: string;
+ /**
+ * Root run id of the current run's lineage (`$rootRunId`), so a nested
+ * `start()` inherits it without reloading the parent. Set by the runtime from
+ * the run it already has loaded.
+ */
+ rootRunId?: string;
  ops: Promise<void>[];
  /**
  * Operations that MUST be durably committed before the step's

packages/world-testing/src/index.mts

@@ -3,6 +3,7 @@ import { errors } from './errors.mjs';
 import { hooks } from './hooks.mjs';
 import { idempotency } from './idempotency.mjs';
 import { inlineExecution } from './inline-execution.mjs';
+import { lineage } from './lineage.mjs';
 import { nullByte } from './null-byte.mjs';
 
 export function createTestSuite(pkgName: string) {
@@ -12,4 +13,5 @@ export function createTestSuite(pkgName: string) {
  nullByte(pkgName);
  errors(pkgName);
  inlineExecution(pkgName);
+ lineage(pkgName);
 }

.changeset/start-cross-run-lineage.md

@@ -0,0 +1,6 @@
+---
+"@workflow/core": patch
+"@workflow/world": patch
+---
+
+Record cross-run lineage when `start()` is called from inside a workflow or step: the new run is tagged with `$parentRunId` (its direct parent) and inherits the parent's `$rootRunId`, so a daisy chain or fan-out of any depth groups under one root id.

docs/content/docs/v5/observability/attributes.mdx

@@ -57,6 +57,15 @@ export async function cleanupAttributes() {
 
 Attribute keys must be 1-256 characters, values must be strings up to 256 bytes, and each run can have up to 64 attributes. Keys that start with `$` are reserved for framework and library code.
 
+## Reserved keys
+
+When `start()` is called from inside a running workflow or step, the new run is automatically tagged with two reserved attributes:
+
+- `$parentRunId`: the run that started it.
+- `$rootRunId`: the root of the chain. It is inherited, so every run in a daisy chain or fan-out shares one root id.
+
+Top-level runs (started outside any workflow or step) are not tagged.
+
 ## Viewing attributes
 
 The run details panel in the observability UI shows the run's current attributes as key-value rows. Reserved `$`-prefixed keys are marked with a badge and sorted after user keys:

packages/core/src/runtime.ts

@@ -17,6 +17,7 @@ import {
 import {
  type Event,
  getQueueTopicPrefix,
+ ROOT_RUN_ID_ATTRIBUTE,
  resolveQueueNamespace,
  SPEC_VERSION_CURRENT,
  SPEC_VERSION_SUPPORTS_COMPRESSION,
@@ -242,6 +243,17 @@ function hasRecordedTerminalRunEvent(events: Event[], runId: string): boolean {
  return true;
 }
 
+/**
+ * The lineage root of a loaded run: its `$rootRunId` attribute, or its own id
+ * when it is itself a root.
+ */
+function rootRunIdFrom(
+ attributes: Record<string, string> | undefined,
+ runId: string
+): string {
+ return attributes?.[ROOT_RUN_ID_ATTRIBUTE] ?? runId;
+}
+
 /**
  * Whether the run has any hook or wait that an out-of-band writer could
  * append an event for between an inline step's `step_completed` write and
@@ -728,6 +740,7 @@ export function workflowEntrypoint(
  workflowDeploymentId: bgRun.deploymentId,
  workflowName,
  workflowStartedAt: bgStartedAt,
+ rootRunId: rootRunIdFrom(bgRun.attributes, runId),
  stepId: incomingStepId,
  stepName: incomingStepName,
  runSpecVersion: bgRun.specVersion,
@@ -1984,6 +1997,10 @@ export function workflowEntrypoint(
  workflowRun.deploymentId,
  workflowName,
  workflowStartedAt,
+ rootRunId: rootRunIdFrom(
+ workflowRun.attributes,
+ runId
+ ),
  stepId: s.correlationId,
  stepName: s.stepName,
  runSpecVersion: workflowRun.specVersion,

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

@@ -0,0 +1,156 @@
+import {
+ SPEC_VERSION_CURRENT,
+ SPEC_VERSION_SUPPORTS_ATTRIBUTES,
+} from '@workflow/world';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { contextStorage } from '../step/context-storage.js';
+import { start } from './start.js';
+import { setWorld } from './world.js';
+
+vi.mock('@vercel/functions', () => ({ waitUntil: vi.fn() }));
+vi.mock('../telemetry.js', () => ({
+ serializeTraceCarrier: vi.fn().mockResolvedValue({}),
+ trace: vi.fn((_name, fn) => fn(undefined)),
+}));
+
+/**
+ * Cross-run lineage: start() records reserved `$rootRunId` / `$parentRunId`
+ * attributes when it runs inside another run, so a daisy chain or fan-out
+ * groups under one root id. The lineage is a pure read of the ambient step
+ * context: the runtime fills both the parent run id and its root from the run
+ * it already has loaded, so start() never reads back the parent (`runs.get` is
+ * never called). A top-level start() records nothing.
+ */
+describe('start() cross-run lineage', () => {
+ let eventsCreate: ReturnType<typeof vi.fn>;
+ let runsGet: ReturnType<typeof vi.fn>;
+ let queue: ReturnType<typeof vi.fn>;
+
+ // The runtime requires the world to declare the current spec version; the
+ // per-run spec is driven separately via `opts.specVersion` where needed.
+ function useWorld() {
+ setWorld({
+ specVersion: SPEC_VERSION_CURRENT,
+ getDeploymentId: vi.fn().mockResolvedValue('deploy_123'),
+ events: { create: eventsCreate },
+ runs: { get: runsGet },
+ queue,
+ } as any);
+ }
+
+ beforeEach(() => {
+ eventsCreate = vi.fn().mockImplementation((runId) =>
+ Promise.resolve({
+ run: { runId: runId ?? 'wrun_x', status: 'pending' },
+ })
+ );
+ runsGet = vi.fn();
+ queue = vi.fn().mockResolvedValue(undefined);
+ useWorld();
+ });
+
+ afterEach(() => {
+ setWorld(undefined);
+ vi.clearAllMocks();
+ });
+
+ const wf = (id: string) =>
+ Object.assign(() => Promise.resolve('ok'), { workflowId: id });
+
+ /** Attributes seeded onto the run_created event for the first start() call. */
+ function seededAttributes(): Record<string, string> | undefined {
+ return eventsCreate.mock.calls[0]?.[1]?.eventData?.attributes;
+ }
+
+ /**
+ * Run `fn` as if executing inside a parent run's step context. Pass
+ * `rootRunId` to model the runtime having put the parent's root on the
+ * context (the wired path); omit it to exercise the anchor-to-parent default.
+ */
+ function insideRun<T>(
+ parentRunId: string,
+ fn: () => Promise<T>,
+ rootRunId?: string
+ ): Promise<T> {
+ return contextStorage.run(
+ {
+ stepMetadata: {
+ stepName: 'start',
+ stepId: 'step_1',
+ stepStartedAt: new Date(),
+ attempt: 1,
+ },
+ workflowMetadata: {
+ workflowName: 'parent',
+ workflowRunId: parentRunId,
+ workflowStartedAt: new Date(),
+ url: 'http://localhost:3000',
+ features: { encryption: false },
+ },
+ rootRunId,
+ ops: [],
+ } as any,
+ fn
+ );
+ }
+
+ it('records no lineage for a top-level start()', async () => {
+ await start(wf('test-workflow'), []);
+
+ expect(seededAttributes()).toBeUndefined();
+ expect(runsGet).not.toHaveBeenCalled();
+ });
+
+ it('inherits the root from the context with no read-back', async () => {
+ await insideRun(
+ 'wrun_parent',
+ () => start(wf('child-workflow'), []),
+ 'wrun_root'
+ );
+
+ expect(runsGet).not.toHaveBeenCalled();
+ expect(seededAttributes()).toEqual({
+ $rootRunId: 'wrun_root',
+ $parentRunId: 'wrun_parent',
+ });
+ });
+
+ it('anchors the root to the parent when the context carries none', async () => {
+ await insideRun('wrun_parent', () => start(wf('child-workflow'), []));
+
+ expect(runsGet).not.toHaveBeenCalled();
+ expect(seededAttributes()).toEqual({
+ $rootRunId: 'wrun_parent',
+ $parentRunId: 'wrun_parent',
+ });
+ });
+
+ it('merges caller-provided attributes over the inferred lineage', async () => {
+ await insideRun(
+ 'wrun_parent',
+ () => start(wf('child-workflow'), [], { attributes: { tenant: 't1' } }),
+ 'wrun_root'
+ );
+
+ const expected = {
+ $rootRunId: 'wrun_root',
+ $parentRunId: 'wrun_parent',
+ tenant: 't1',
+ };
+ expect(seededAttributes()).toEqual(expected);
+ // Lineage must also ride the resilient-start queue input, not just the
+ // run_created event, so both creation paths carry it.
+ expect(queue.mock.calls[0]?.[1]?.runInput?.attributes).toEqual(expected);
+ });
+
+ it('records no lineage when the run predates attribute support', async () => {
+ await insideRun('wrun_parent', () =>
+ start(wf('child-workflow'), [], {
+ specVersion: SPEC_VERSION_SUPPORTS_ATTRIBUTES - 1,
+ })
+ );
+
+ expect(seededAttributes()).toBeUndefined();
+ expect(runsGet).not.toHaveBeenCalled();
+ });
+});

packages/core/src/runtime/start.ts

@@ -3,6 +3,8 @@ import { workflowDisplayName } from '@workflow/utils/parse-name';
 import type { WorkflowInvokePayload, World } from '@workflow/world';
 import {
  isLegacySpecVersion,
+ PARENT_RUN_ID_ATTRIBUTE,
+ ROOT_RUN_ID_ATTRIBUTE,
  SPEC_VERSION_SUPPORTS_ATTRIBUTES,
  SPEC_VERSION_SUPPORTS_CBOR_QUEUE_TRANSPORT,
  SPEC_VERSION_SUPPORTS_COMPRESSION,
@@ -19,6 +21,7 @@ import {
  dehydrateWorkflowArguments,
  SerializationFormat,
 } from '../serialization.js';
+import { contextStorage } from '../step/context-storage.js';
 import * as Attribute from '../telemetry/semantic-conventions.js';
 import { serializeTraceCarrier, trace } from '../telemetry.js';
 import { version as workflowCoreVersion } from '../version.js';
@@ -42,6 +45,28 @@ const CROSS_DEPLOYMENT_CAPABILITY_PROBE_TIMEOUT_MS = 2_000;
 /** ULID generator for client-side runId generation */
 const ulid = monotonicFactory();
 
+/**
+ * Cross-run lineage for a run being started from inside another run.
+ *
+ * The ambient step context carries the parent run id and the root of its
+ * lineage; the runtime fills both from the run it already has loaded, so this
+ * is a pure context read with no I/O. The new run records `$parentRunId` (the
+ * edge) and inherits the parent's `$rootRunId` (the parent itself when it is a
+ * root), so a daisy chain or fan-out of any depth groups under one root id.
+ * Returns `undefined` for a top-level `start()`, which has no context, so
+ * standalone runs carry no lineage.
+ */
+function resolveLineageAttributes(): Record<string, string> | undefined {
+ const store = contextStorage.getStore();
+ const parentRunId = store?.workflowMetadata?.workflowRunId;
+ if (!parentRunId) return undefined;
+
+ return {
+ [ROOT_RUN_ID_ATTRIBUTE]: store.rootRunId ?? parentRunId,
+ [PARENT_RUN_ID_ATTRIBUTE]: parentRunId,
+ };
+}
+
 // `deploymentId: 'latest'` is a no-op in Worlds without atomic deployments.
 // The warning that explains this only needs to fire once per process: a
 // workflow that hardcodes 'latest' for its Vercel deployment would otherwise
@@ -360,13 +385,24 @@ export async function start<TArgs extends unknown[], TResult>(
  changes.map(({ key, value }) => [key, value as string])
  );
  }
- // Seed payload shared by run_created and the resilient-start queue
- // input. The flag rides along so server-side validation matches the
- // client-side check above on both paths.
- const attributeSeed = attributes
+
+ // Cross-run lineage: the reserved keys ride on the run's existing
+ // attributes, so they add no extra write. Caller attributes are spread
+ // last, so a caller with allowReservedAttributes can deliberately
+ // re-parent.
+ const lineage =
+ specVersion >= SPEC_VERSION_SUPPORTS_ATTRIBUTES
+ ? resolveLineageAttributes()
+ : undefined;
+ const runAttributes = lineage
+ ? { ...lineage, ...attributes }
+ : attributes;
+
+ // Shared by the run_created event and the resilient-start queue input.
+ const attributeSeed = runAttributes
  ? {
- attributes,
- ...(allowReservedAttributes
+ attributes: runAttributes,
+ ...(allowReservedAttributes || lineage != null
  ? { allowReservedAttributes: true as const }
  : {}),
  }

packages/core/src/runtime/step-executor.ts

@@ -81,6 +81,8 @@ export interface StepExecutorParams {
  workflowDeploymentId?: string;
  workflowName: string;
  workflowStartedAt: number;
+ /** Root run id of this run's lineage, carried into the step context. */
+ rootRunId?: string;
  stepId: string;
  stepName: string;
  encryptionKey?: CryptoKey;
@@ -690,6 +692,7 @@ export async function executeStep(
  features: { encryption: !!encryptionKey },
  },
  workflowDeploymentId: params.workflowDeploymentId,
+ rootRunId: params.rootRunId,
  ops,
  preCompletionOps,
  closureVars: hydratedInput.closureVars,

packages/core/src/step/context-storage.ts

@@ -22,6 +22,12 @@ export type StepContext = {
  workflowMetadata: WorkflowMetadata;
  /** Deployment that owns the current workflow run, used for forwarded streams. */
  workflowDeploymentId?: string;
+ /**
+ * Root run id of the current run's lineage (`$rootRunId`), so a nested
+ * `start()` inherits it without reloading the parent. Set by the runtime from
+ * the run it already has loaded.
+ */
+ rootRunId?: string;
  ops: Promise<void>[];
  /**
  * Operations that MUST be durably committed before the step's

packages/world-testing/src/index.mts

@@ -3,6 +3,7 @@ import { errors } from './errors.mjs';
 import { hooks } from './hooks.mjs';
 import { idempotency } from './idempotency.mjs';
 import { inlineExecution } from './inline-execution.mjs';
+import { lineage } from './lineage.mjs';
 import { nullByte } from './null-byte.mjs';
 
 export function createTestSuite(pkgName: string) {
@@ -12,4 +13,5 @@ export function createTestSuite(pkgName: string) {
  nullByte(pkgName);
  errors(pkgName);
  inlineExecution(pkgName);
+ lineage(pkgName);
 }

.changeset/start-cross-run-lineage.md

@@ -0,0 +1,6 @@
+---
+"@workflow/core": patch
+"@workflow/world": patch
+---
+
+Record cross-run lineage when `start()` is called from inside a workflow or step: the new run is tagged with `$parentRunId` (its direct parent) and inherits the parent's `$rootRunId`, so a daisy chain or fan-out of any depth groups under one root id.

docs/content/docs/v5/observability/attributes.mdx

@@ -57,6 +57,15 @@ export async function cleanupAttributes() {
 
 Attribute keys must be 1-256 characters, values must be strings up to 256 bytes, and each run can have up to 64 attributes. Keys that start with `$` are reserved for framework and library code.
 
+## Reserved keys
+
+When `start()` is called from inside a running workflow or step, the new run is automatically tagged with two reserved attributes:
+
+- `$parentRunId`: the run that started it.
+- `$rootRunId`: the root of the chain. It is inherited, so every run in a daisy chain or fan-out shares one root id.
+
+Top-level runs (started outside any workflow or step) are not tagged.
+
 ## Viewing attributes
 
 The run details panel in the observability UI shows the run's current attributes as key-value rows. Reserved `$`-prefixed keys are marked with a badge and sorted after user keys:

packages/core/src/runtime.ts

@@ -17,6 +17,7 @@ import {
 import {
  type Event,
  getQueueTopicPrefix,
+ ROOT_RUN_ID_ATTRIBUTE,
  resolveQueueNamespace,
  SPEC_VERSION_CURRENT,
  SPEC_VERSION_SUPPORTS_COMPRESSION,
@@ -242,6 +243,17 @@ function hasRecordedTerminalRunEvent(events: Event[], runId: string): boolean {
  return true;
 }
 
+/**
+ * The lineage root of a loaded run: its `$rootRunId` attribute, or its own id
+ * when it is itself a root.
+ */
+function rootRunIdFrom(
+ attributes: Record<string, string> | undefined,
+ runId: string
+): string {
+ return attributes?.[ROOT_RUN_ID_ATTRIBUTE] ?? runId;
+}
+
 /**
  * Whether the run has any hook or wait that an out-of-band writer could
  * append an event for between an inline step's `step_completed` write and
@@ -728,6 +740,7 @@ export function workflowEntrypoint(
  workflowDeploymentId: bgRun.deploymentId,
  workflowName,
  workflowStartedAt: bgStartedAt,
+ rootRunId: rootRunIdFrom(bgRun.attributes, runId),
  stepId: incomingStepId,
  stepName: incomingStepName,
  runSpecVersion: bgRun.specVersion,
@@ -1984,6 +1997,10 @@ export function workflowEntrypoint(
  workflowRun.deploymentId,
  workflowName,
  workflowStartedAt,
+ rootRunId: rootRunIdFrom(
+ workflowRun.attributes,
+ runId
+ ),
  stepId: s.correlationId,
  stepName: s.stepName,
  runSpecVersion: workflowRun.specVersion,

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

@@ -0,0 +1,156 @@
+import {
+ SPEC_VERSION_CURRENT,
+ SPEC_VERSION_SUPPORTS_ATTRIBUTES,
+} from '@workflow/world';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { contextStorage } from '../step/context-storage.js';
+import { start } from './start.js';
+import { setWorld } from './world.js';
+
+vi.mock('@vercel/functions', () => ({ waitUntil: vi.fn() }));
+vi.mock('../telemetry.js', () => ({
+ serializeTraceCarrier: vi.fn().mockResolvedValue({}),
+ trace: vi.fn((_name, fn) => fn(undefined)),
+}));
+
+/**
+ * Cross-run lineage: start() records reserved `$rootRunId` / `$parentRunId`
+ * attributes when it runs inside another run, so a daisy chain or fan-out
+ * groups under one root id. The lineage is a pure read of the ambient step
+ * context: the runtime fills both the parent run id and its root from the run
+ * it already has loaded, so start() never reads back the parent (`runs.get` is
+ * never called). A top-level start() records nothing.
+ */
+describe('start() cross-run lineage', () => {
+ let eventsCreate: ReturnType<typeof vi.fn>;
+ let runsGet: ReturnType<typeof vi.fn>;
+ let queue: ReturnType<typeof vi.fn>;
+
+ // The runtime requires the world to declare the current spec version; the
+ // per-run spec is driven separately via `opts.specVersion` where needed.
+ function useWorld() {
+ setWorld({
+ specVersion: SPEC_VERSION_CURRENT,
+ getDeploymentId: vi.fn().mockResolvedValue('deploy_123'),
+ events: { create: eventsCreate },
+ runs: { get: runsGet },
+ queue,
+ } as any);
+ }
+
+ beforeEach(() => {
+ eventsCreate = vi.fn().mockImplementation((runId) =>
+ Promise.resolve({
+ run: { runId: runId ?? 'wrun_x', status: 'pending' },
+ })
+ );
+ runsGet = vi.fn();
+ queue = vi.fn().mockResolvedValue(undefined);
+ useWorld();
+ });
+
+ afterEach(() => {
+ setWorld(undefined);
+ vi.clearAllMocks();
+ });
+
+ const wf = (id: string) =>
+ Object.assign(() => Promise.resolve('ok'), { workflowId: id });
+
+ /** Attributes seeded onto the run_created event for the first start() call. */
+ function seededAttributes(): Record<string, string> | undefined {
+ return eventsCreate.mock.calls[0]?.[1]?.eventData?.attributes;
+ }
+
+ /**
+ * Run `fn` as if executing inside a parent run's step context. Pass
+ * `rootRunId` to model the runtime having put the parent's root on the
+ * context (the wired path); omit it to exercise the anchor-to-parent default.
+ */
+ function insideRun<T>(
+ parentRunId: string,
+ fn: () => Promise<T>,
+ rootRunId?: string
+ ): Promise<T> {
+ return contextStorage.run(
+ {
+ stepMetadata: {
+ stepName: 'start',
+ stepId: 'step_1',
+ stepStartedAt: new Date(),
+ attempt: 1,
+ },
+ workflowMetadata: {
+ workflowName: 'parent',
+ workflowRunId: parentRunId,
+ workflowStartedAt: new Date(),
+ url: 'http://localhost:3000',
+ features: { encryption: false },
+ },
+ rootRunId,
+ ops: [],
+ } as any,
+ fn
+ );
+ }
+
+ it('records no lineage for a top-level start()', async () => {
+ await start(wf('test-workflow'), []);
+
+ expect(seededAttributes()).toBeUndefined();
+ expect(runsGet).not.toHaveBeenCalled();
+ });
+
+ it('inherits the root from the context with no read-back', async () => {
+ await insideRun(
+ 'wrun_parent',
+ () => start(wf('child-workflow'), []),
+ 'wrun_root'
+ );
+
+ expect(runsGet).not.toHaveBeenCalled();
+ expect(seededAttributes()).toEqual({
+ $rootRunId: 'wrun_root',
+ $parentRunId: 'wrun_parent',
+ });
+ });
+
+ it('anchors the root to the parent when the context carries none', async () => {
+ await insideRun('wrun_parent', () => start(wf('child-workflow'), []));
+
+ expect(runsGet).not.toHaveBeenCalled();
+ expect(seededAttributes()).toEqual({
+ $rootRunId: 'wrun_parent',
+ $parentRunId: 'wrun_parent',
+ });
+ });
+
+ it('merges caller-provided attributes over the inferred lineage', async () => {
+ await insideRun(
+ 'wrun_parent',
+ () => start(wf('child-workflow'), [], { attributes: { tenant: 't1' } }),
+ 'wrun_root'
+ );
+
+ const expected = {
+ $rootRunId: 'wrun_root',
+ $parentRunId: 'wrun_parent',
+ tenant: 't1',
+ };
+ expect(seededAttributes()).toEqual(expected);
+ // Lineage must also ride the resilient-start queue input, not just the
+ // run_created event, so both creation paths carry it.
+ expect(queue.mock.calls[0]?.[1]?.runInput?.attributes).toEqual(expected);
+ });
+
+ it('records no lineage when the run predates attribute support', async () => {
+ await insideRun('wrun_parent', () =>
+ start(wf('child-workflow'), [], {
+ specVersion: SPEC_VERSION_SUPPORTS_ATTRIBUTES - 1,
+ })
+ );
+
+ expect(seededAttributes()).toBeUndefined();
+ expect(runsGet).not.toHaveBeenCalled();
+ });
+});

packages/core/src/runtime/start.ts

@@ -3,6 +3,8 @@ import { workflowDisplayName } from '@workflow/utils/parse-name';
 import type { WorkflowInvokePayload, World } from '@workflow/world';
 import {
  isLegacySpecVersion,
+ PARENT_RUN_ID_ATTRIBUTE,
+ ROOT_RUN_ID_ATTRIBUTE,
  SPEC_VERSION_SUPPORTS_ATTRIBUTES,
  SPEC_VERSION_SUPPORTS_CBOR_QUEUE_TRANSPORT,
  SPEC_VERSION_SUPPORTS_COMPRESSION,
@@ -19,6 +21,7 @@ import {
  dehydrateWorkflowArguments,
  SerializationFormat,
 } from '../serialization.js';
+import { contextStorage } from '../step/context-storage.js';
 import * as Attribute from '../telemetry/semantic-conventions.js';
 import { serializeTraceCarrier, trace } from '../telemetry.js';
 import { version as workflowCoreVersion } from '../version.js';
@@ -42,6 +45,28 @@ const CROSS_DEPLOYMENT_CAPABILITY_PROBE_TIMEOUT_MS = 2_000;
 /** ULID generator for client-side runId generation */
 const ulid = monotonicFactory();
 
+/**
+ * Cross-run lineage for a run being started from inside another run.
+ *
+ * The ambient step context carries the parent run id and the root of its
+ * lineage; the runtime fills both from the run it already has loaded, so this
+ * is a pure context read with no I/O. The new run records `$parentRunId` (the
+ * edge) and inherits the parent's `$rootRunId` (the parent itself when it is a
+ * root), so a daisy chain or fan-out of any depth groups under one root id.
+ * Returns `undefined` for a top-level `start()`, which has no context, so
+ * standalone runs carry no lineage.
+ */
+function resolveLineageAttributes(): Record<string, string> | undefined {
+ const store = contextStorage.getStore();
+ const parentRunId = store?.workflowMetadata?.workflowRunId;
+ if (!parentRunId) return undefined;
+
+ return {
+ [ROOT_RUN_ID_ATTRIBUTE]: store.rootRunId ?? parentRunId,
+ [PARENT_RUN_ID_ATTRIBUTE]: parentRunId,
+ };
+}
+
 // `deploymentId: 'latest'` is a no-op in Worlds without atomic deployments.
 // The warning that explains this only needs to fire once per process: a
 // workflow that hardcodes 'latest' for its Vercel deployment would otherwise
@@ -360,13 +385,24 @@ export async function start<TArgs extends unknown[], TResult>(
  changes.map(({ key, value }) => [key, value as string])
  );
  }
- // Seed payload shared by run_created and the resilient-start queue
- // input. The flag rides along so server-side validation matches the
- // client-side check above on both paths.
- const attributeSeed = attributes
+
+ // Cross-run lineage: the reserved keys ride on the run's existing
+ // attributes, so they add no extra write. Caller attributes are spread
+ // last, so a caller with allowReservedAttributes can deliberately
+ // re-parent.
+ const lineage =
+ specVersion >= SPEC_VERSION_SUPPORTS_ATTRIBUTES
+ ? resolveLineageAttributes()
+ : undefined;
+ const runAttributes = lineage
+ ? { ...lineage, ...attributes }
+ : attributes;
+
+ // Shared by the run_created event and the resilient-start queue input.
+ const attributeSeed = runAttributes
  ? {
- attributes,
- ...(allowReservedAttributes
+ attributes: runAttributes,
+ ...(allowReservedAttributes || lineage != null
  ? { allowReservedAttributes: true as const }
  : {}),
  }

packages/core/src/runtime/step-executor.ts

@@ -81,6 +81,8 @@ export interface StepExecutorParams {
  workflowDeploymentId?: string;
  workflowName: string;
  workflowStartedAt: number;
+ /** Root run id of this run's lineage, carried into the step context. */
+ rootRunId?: string;
  stepId: string;
  stepName: string;
  encryptionKey?: CryptoKey;
@@ -690,6 +692,7 @@ export async function executeStep(
  features: { encryption: !!encryptionKey },
  },
  workflowDeploymentId: params.workflowDeploymentId,
+ rootRunId: params.rootRunId,
  ops,
  preCompletionOps,
  closureVars: hydratedInput.closureVars,

packages/core/src/step/context-storage.ts

@@ -22,6 +22,12 @@ export type StepContext = {
  workflowMetadata: WorkflowMetadata;
  /** Deployment that owns the current workflow run, used for forwarded streams. */
  workflowDeploymentId?: string;
+ /**
+ * Root run id of the current run's lineage (`$rootRunId`), so a nested
+ * `start()` inherits it without reloading the parent. Set by the runtime from
+ * the run it already has loaded.
+ */
+ rootRunId?: string;
  ops: Promise<void>[];
  /**
  * Operations that MUST be durably committed before the step's

packages/world-testing/src/index.mts

@@ -3,6 +3,7 @@ import { errors } from './errors.mjs';
 import { hooks } from './hooks.mjs';
 import { idempotency } from './idempotency.mjs';
 import { inlineExecution } from './inline-execution.mjs';
+import { lineage } from './lineage.mjs';
 import { nullByte } from './null-byte.mjs';
 
 export function createTestSuite(pkgName: string) {
@@ -12,4 +13,5 @@ export function createTestSuite(pkgName: string) {
  nullByte(pkgName);
  errors(pkgName);
  inlineExecution(pkgName);
+ lineage(pkgName);
 }