[core] Combine initial run fetch, event fetch, and run_started event creation

.changeset/better-peas-buy.md

@@ -0,0 +1,8 @@
+---
+"@workflow/world": patch
+"@workflow/core": patch
+"@workflow/world-local": patch
+"@workflow/world-postgres": patch
+---
+
+Combine initial run fetch, event fetch, and run_started event creation

packages/core/src/runtime.ts

@@ -191,42 +191,50 @@ export function workflowEntrypoint(
                 });
 
                 let workflowStartedAt = -1;
-                let workflowRun = await world.runs.get(runId);
+                let workflowRun: WorkflowRun | undefined;
+                // Pre-loaded events from the run_started response.
+                // When present, we skip the events.list call to reduce TTFB.
+                let preloadedEvents: Event[] | undefined;
 
                 // --- Infrastructure: prepare the run state ---
+                // Always call run_started directly — this both transitions
+                // the run to 'running' AND returns the run entity, saving
+                // a separate runs.get round-trip.
+                // Contract: events.create('run_started') must be idempotent
+                // for runs already in 'running' status (return the run
+                // without error), not just for pending → running transitions.
                 // Network/server errors propagate to the queue handler for retry.
                 // WorkflowRuntimeError (data integrity issues) are fatal and
                 // produce run_failed since retrying won't fix them.
                 try {
-                  if (workflowRun.status === 'pending') {
-                    // Transition run to 'running' via event (event-sourced architecture)
-                    const result = await world.events.create(
-                      runId,
-                      {
-                        eventType: 'run_started',
-                        specVersion: SPEC_VERSION_CURRENT,
-                      },
-                      { requestId }
+                  const result = await world.events.create(
+                    runId,
+                    {
+                      eventType: 'run_started',
+                      specVersion: SPEC_VERSION_CURRENT,
+                    },
+                    { requestId }
+                  );
+                  if (!result.run) {
+                    throw new WorkflowRuntimeError(
+                      `Event creation for 'run_started' did not return the run entity for run "${runId}"`
                     );
-                    // Use the run entity from the event response (no extra get call needed)
-                    if (!result.run) {
-                      throw new WorkflowRuntimeError(
-                        `Event creation for 'run_started' did not return the run entity for run "${runId}"`
-                      );
-                    }
-                    workflowRun = result.run;
+                  }
+                  workflowRun = result.run;
+
+                  // If the world returned events, use them to skip
+                  // the initial events.list call and reduce TTFB.
+                  if (result.events && result.events.length > 0) {
+                    preloadedEvents = result.events;
                   }
 
-                  // At this point, the workflow is "running" and `startedAt` should
-                  // definitely be set.
                   if (!workflowRun.startedAt) {
                     throw new WorkflowRuntimeError(
                       `Workflow run "${runId}" has no "startedAt" timestamp`
                     );
                   }
                 } catch (err) {
                   // Run was concurrently completed/failed/cancelled
-                  // between the GET and the run_started event creation
                   if (EntityConflictError.is(err) || RunExpiredError.is(err)) {
                     runtimeLogger.info(
                       'Run already finished during setup, skipping',
@@ -294,8 +302,12 @@ export function workflowEntrypoint(
                   return;
                 }
 
-                // Load all events into memory before running
-                const events = await getAllWorkflowRunEvents(workflowRun.runId);
+                // Load all events into memory before running.
+                // If we got pre-loaded events from the run_started response,
+                // skip the events.list round-trip to reduce TTFB.
+                const events =
+                  preloadedEvents ??
+                  (await getAllWorkflowRunEvents(workflowRun.runId));
 
                 // Check for any elapsed waits and create wait_completed events
                 const now = Date.now();

packages/world-local/src/storage/events-storage.ts

@@ -190,7 +190,15 @@ export function createEventsStorage(
           };
         }
 
-        // Run state transitions are not allowed on terminal runs
+        // For run_started on terminal runs, use RunExpiredError so the
+        // runtime knows to exit without retrying.
+        if (data.eventType === 'run_started') {
+          throw new RunExpiredError(
+            `Workflow run "${effectiveRunId}" is already in terminal state "${currentRun.status}"`
+          );
+        }
+
+        // Other run state transitions are not allowed on terminal runs
         if (
           runTerminalEvents.includes(data.eventType) ||
           data.eventType === 'run_cancelled'
@@ -280,6 +288,10 @@ export function createEventsStorage(
         createdAt: now,
         specVersion: effectiveSpecVersion,
       };
+      // Strip eventData from run_started — it belongs on run_created only.
+      if (data.eventType === 'run_started' && 'eventData' in event) {
+        delete (event as any).eventData;
+      }
 
       // Track entity created/updated for EventResult
       let run: WorkflowRun | undefined;
@@ -316,6 +328,15 @@ export function createEventsStorage(
       } else if (data.eventType === 'run_started') {
         // Reuse currentRun from validation (already read above)
         if (currentRun) {
+          // If already running, return the run without inserting a
+          // duplicate event.  This makes run_started idempotent for
+          // concurrent invocations.  We omit preloaded events here
+          // because this is a rare race-condition path — the runtime
+          // falls back to getAllWorkflowRunEvents().
+          if (currentRun.status === 'running') {
+            return { run: currentRun };
+          }
+
           run = {
             runId: currentRun.runId,
             deploymentId: currentRun.deploymentId,
@@ -832,13 +853,29 @@ export function createEventsStorage(
       const resolveData = params?.resolveData ?? DEFAULT_RESOLVE_DATA_OPTION;
       const filteredEvent = stripEventDataRefs(event, resolveData);
 
+      // For run_started: include all events so the runtime can skip
+      // the initial events.list call and reduce TTFB.
+      let events: Event[] | undefined;
+      if (data.eventType === 'run_started' && run) {
+        const allEvents = await paginatedFileSystemQuery({
+          directory: path.join(basedir, 'events'),
+          schema: EventSchema,
+          filePrefix: `${effectiveRunId}-`,
+          sortOrder: 'asc',
+          getCreatedAt: getObjectCreatedAt('evnt'),
+          getId: (e) => e.eventId,
+        });
+        events = allEvents.data;
+      }
+
       // Return EventResult with event and any created/updated entity
       return {
         event: filteredEvent,
         run,
         step,
         hook,
         wait,
+        events,
       };
     },
 

packages/world-postgres/src/storage.ts

@@ -444,7 +444,15 @@ export function createEventsStorage(drizzle: Drizzle): Storage['events'] {
           };
         }
 
-        // Run state transitions are not allowed on terminal runs
+        // For run_started on terminal runs, use RunExpiredError so the
+        // runtime knows to exit without retrying.
+        if (data.eventType === 'run_started') {
+          throw new RunExpiredError(
+            `Workflow run "${effectiveRunId}" is already in terminal state "${currentRun.status}"`
+          );
+        }
+
+        // Other run state transitions are not allowed on terminal runs
         if (
           runTerminalEvents.includes(data.eventType) ||
           data.eventType === 'run_cancelled'
@@ -563,6 +571,23 @@ export function createEventsStorage(drizzle: Drizzle): Storage['events'] {
 
       // Handle run_started event: update run status
       if (data.eventType === 'run_started') {
+        // If the run is already running, return it without inserting a
+        // duplicate run_started event.  This makes run_started idempotent
+        // for concurrent invocations: replay is deterministic, so letting
+        // multiple callers proceed with the same run is safe.  We skip
+        // preloaded events here because this is a rare race-condition path
+        // — the runtime falls back to getAllWorkflowRunEvents().
+        if (currentRun?.status === 'running') {
+          const [fullRun] = await drizzle
+            .select()
+            .from(Schema.runs)
+            .where(eq(Schema.runs.runId, effectiveRunId))
+            .limit(1);
+          if (fullRun) {
+            return { run: deserializeRunError(compact(fullRun)) };
+          }
+        }
+
         const [runValue] = await drizzle
           .update(Schema.runs)
           .set({
@@ -1135,29 +1160,66 @@ export function createEventsStorage(drizzle: Drizzle): Storage['events'] {
         }
       }
 
+      // Strip eventData from run_started — it belongs on run_created only.
+      const storedEventData =
+        data.eventType === 'run_started'
+          ? undefined
+          : 'eventData' in data
+            ? data.eventData
+            : undefined;
+
       const [value] = await drizzle
         .insert(events)
         .values({
           runId: effectiveRunId,
           eventId,
           correlationId: data.correlationId,
           eventType: data.eventType,
-          eventData: 'eventData' in data ? data.eventData : undefined,
+          eventData: storedEventData,
           specVersion: effectiveSpecVersion,
         })
         .returning({ createdAt: events.createdAt });
       if (!value) {
         throw new EntityConflictError(`Event ${eventId} could not be created`);
       }
-      const result = { ...data, ...value, runId: effectiveRunId, eventId };
+      const result = {
+        ...data,
+        ...value,
+        runId: effectiveRunId,
+        eventId,
+        ...(storedEventData !== undefined
+          ? { eventData: storedEventData }
+          : {}),
+      };
+      if (data.eventType === 'run_started') {
+        delete (result as any).eventData;
+      }
       const parsed = EventSchema.parse(result);
       const resolveData = params?.resolveData ?? 'all';
+
+      // For run_started: include all events so the runtime can skip
+      // the initial events.list call and reduce TTFB.
+      let allEvents: Event[] | undefined;
+      if (data.eventType === 'run_started' && run) {
+        const eventRows = await drizzle
+          .select()
+          .from(Schema.events)
+          .where(eq(Schema.events.runId, effectiveRunId))
+          .orderBy(Schema.events.eventId);
+        allEvents = eventRows.map((e) => {
+          e.eventData ||= e.eventDataJson;
+          const parsed = EventSchema.parse(compact(e));
+          return stripEventDataRefs(parsed, resolveData);
+        });
+      }
+
       return {
         event: stripEventDataRefs(parsed, resolveData),
         run,
         step,
         hook,
         wait,
+        events: allEvents,
       };
     },
     async get(

packages/world/src/events.ts

@@ -369,6 +369,12 @@ export interface EventResult {
   hook?: import('./hooks.js').Hook;
   /** The wait entity (for wait_created/wait_completed events) */
   wait?: import('./waits.js').Wait;
+  /**
+   * All events up to this point, with data resolved. When populated
+   * on a run_started response, the runtime uses these to skip the
+   * initial events.list call and reduce TTFB.
+   */
+  events?: Event[];
 }
 
 export interface GetEventParams {