@workflow/web-shared 5.0.0-beta.41 → 5.0.0-beta.42

package/src/lib/event-materialization.ts

@@ -17,6 +17,7 @@ import {
   isWaitEventType,
   type StepStatus,
 } from '@workflow/world';
+import { findDuplicateEventIds } from './duplicate-events';
 
 // ---------------------------------------------------------------------------
 // Materialized entity types
@@ -105,9 +106,24 @@ function getEventTimestamp(event: Event | undefined): Date | undefined {
  *
  * Handles partial event lists gracefully: a step may only have a
  * step_created event with no completion yet.
+ *
+ * The derived status and timestamps come from the events the run acted on. A
+ * repeat of a class the log already records is read past by every replay, so
+ * a second terminal event written by a concurrent replay does not move a step
+ * off the outcome the first one recorded. Every event stays on the entity's
+ * `events` list.
+ *
+ * That reduction needs the whole log to be sound, so it only runs when
+ * `isCompleteHistory` says `events` is it. See {@link findDuplicateEventIds}.
  */
-export function materializeSteps(events: Event[]): MaterializedStep[] {
+export function materializeSteps(
+  events: Event[],
+  { isCompleteHistory = false }: { isCompleteHistory?: boolean } = {}
+): MaterializedStep[] {
   const groups = groupByCorrelationId(events, isStepEventType);
+  const duplicateEventIds = findDuplicateEventIds(events, {
+    isCompleteHistory,
+  });
   const steps: MaterializedStep[] = [];
 
   for (const [correlationId, stepEvents] of groups) {
@@ -121,6 +137,7 @@ export function materializeSteps(events: Event[]): MaterializedStep[] {
     let updatedAt = getEventTimestamp(created) ?? created.createdAt;
 
     for (const e of stepEvents) {
+      if (duplicateEventIds.has(e.eventId)) continue;
       switch (e.eventType) {
         case 'step_started':
           status = 'running';
@@ -248,9 +265,12 @@ export function materializeWaits(events: Event[]): MaterializedWait[] {
  * Convenience function that materializes all entity types from a flat
  * event list.
  */
-export function materializeAll(events: Event[]): MaterializedEntities {
+export function materializeAll(
+  events: Event[],
+  options: { isCompleteHistory?: boolean } = {}
+): MaterializedEntities {
   return {
-    steps: materializeSteps(events),
+    steps: materializeSteps(events, options),
     hooks: materializeHooks(events),
     waits: materializeWaits(events),
   };

package/src/lib/trace-builder.test.ts

@@ -0,0 +1,74 @@
+import type { Event, EventType, WorkflowRun } from '@workflow/world';
+import { describe, expect, it } from 'vitest';
+import { otelTimeToMs } from '../components/workflow-traces/trace-time-utils';
+import { buildTrace } from './trace-builder';
+
+const BASE_TIME = Date.parse('2026-01-01T00:00:00.000Z');
+
+let nextId = 0;
+
+function event(
+  eventType: EventType,
+  options: { correlationId?: string; at: number }
+): Event {
+  nextId += 1;
+  return {
+    eventId: `evt_${nextId}`,
+    runId: 'run_1',
+    eventType,
+    correlationId: options.correlationId,
+    createdAt: new Date(BASE_TIME + options.at * 1000),
+    occurredAt: new Date(BASE_TIME + options.at * 1000),
+    eventData: eventType === 'step_created' ? { stepName: 'doWork' } : {},
+  } as unknown as Event;
+}
+
+const run = {
+  runId: 'run_1',
+  workflowName: 'demo',
+  status: 'running',
+  createdAt: new Date(BASE_TIME),
+} as unknown as WorkflowRun;
+
+describe('buildTrace', () => {
+  it('ends a step span on the terminal event the run acted on', () => {
+    const events = [
+      event('run_created', { at: 0 }),
+      event('run_started', { at: 0 }),
+      event('step_created', { correlationId: 'step_a', at: 1 }),
+      event('step_started', { correlationId: 'step_a', at: 1 }),
+      event('step_completed', { correlationId: 'step_a', at: 4 }),
+      // A concurrent replay commits the same outcome much later. Measuring the
+      // span against it would report a 20s step that ran for 3s.
+      event('step_completed', { correlationId: 'step_a', at: 20 }),
+    ];
+
+    const trace = buildTrace(run, events, new Date(BASE_TIME + 30_000), {
+      isCompleteHistory: true,
+    });
+    const stepSpan = trace.spans.find((span) => span.resource === 'step');
+
+    expect(stepSpan).toBeDefined();
+    expect(otelTimeToMs(stepSpan?.endTime ?? [0, 0])).toBe(BASE_TIME + 4000);
+    expect(trace.knownDurationMs).toBe(4000);
+  });
+
+  it('keeps every event in the geometry when the log may be incomplete', () => {
+    const events = [
+      event('run_created', { at: 0 }),
+      event('run_started', { at: 0 }),
+      event('step_created', { correlationId: 'step_a', at: 1 }),
+      event('step_started', { correlationId: 'step_a', at: 1 }),
+      event('step_completed', { correlationId: 'step_a', at: 4 }),
+      event('step_completed', { correlationId: 'step_a', at: 20 }),
+    ];
+
+    // Without the whole log there is no telling which of the two completions
+    // the run acted on, so neither is dropped and the span covers both.
+    const trace = buildTrace(run, events, new Date(BASE_TIME + 30_000));
+    const stepSpan = trace.spans.find((span) => span.resource === 'step');
+
+    expect(otelTimeToMs(stepSpan?.endTime ?? [0, 0])).toBe(BASE_TIME + 20_000);
+    expect(trace.duplicateEventIds.size).toBe(0);
+  });
+});

package/src/lib/trace-builder.ts

@@ -22,6 +22,7 @@ import {
   waitToSpan,
 } from '../components/workflow-traces/trace-span-construction';
 import { otelTimeToMs } from '../components/workflow-traces/trace-time-utils';
+import { findDuplicateEventIds } from './duplicate-events';
 import type { Span } from './trace-types';
 
 /**
@@ -188,15 +189,40 @@ export interface TraceWithMeta {
   resources: { name: string; attributes: Record<string, string> }[];
   /** Duration in ms from trace start to the latest known event. */
   knownDurationMs: number;
+  /**
+   * The events left out of the span geometry as repeats. Empty unless the
+   * caller vouched for the log being complete. See
+   * {@link findDuplicateEventIds}.
+   */
+  duplicateEventIds: ReadonlySet<string>;
 }
 
 export function buildTrace(
   run: WorkflowRun,
   events: Event[],
-  now: Date
+  now: Date,
+  /**
+   * Whether `events` is the run's whole log. Defaults to false, which builds
+   * the trace from every event: on a subset there is no way to tell a repeat
+   * from the only copy the caller was given, and dropping the wrong one moves
+   * a span. See {@link findDuplicateEventIds}.
+   */
+  { isCompleteHistory = false }: { isCompleteHistory?: boolean } = {}
 ): TraceWithMeta {
-  const groupedEvents = groupEventsByCorrelation(events);
-  const latestKnownTime = computeLatestKnownTime(events, run);
+  // Span geometry comes from what the run acted on. A repeat of a class the
+  // log already records is read past by every replay, and letting one through
+  // here would stretch a span to whenever a concurrent replay committed it.
+  // The event lists still show them, marked as repeats.
+  const duplicateEventIds = findDuplicateEventIds(events, {
+    isCompleteHistory,
+  });
+  const actedOnEvents =
+    duplicateEventIds.size === 0
+      ? events
+      : events.filter((event) => !duplicateEventIds.has(event.eventId));
+
+  const groupedEvents = groupEventsByCorrelation(actedOnEvents);
+  const latestKnownTime = computeLatestKnownTime(actedOnEvents, run);
   const { runSpan, spans } = buildSpans(
     run,
     groupedEvents,
@@ -222,5 +248,6 @@ export function buildTrace(
       },
     ],
     knownDurationMs: Math.max(0, knownDurationMs),
+    duplicateEventIds,
   };
 }