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

package/src/lib/duplicate-events.ts

@@ -0,0 +1,188 @@
+import {
+  type EntityEventClass,
+  type Event,
+  entityEventClass,
+  isSlotEventId,
+} from '@workflow/world';
+
+/**
+ * Identifies events a replay reads past.
+ *
+ * Concurrent replays of one run write to a shared log, so a replay working
+ * from a stale prefix can commit a second `step_created` / `step_started` /
+ * `wait_created` for an entity the log already records one of. Every replay
+ * reads the first event of that class at the same position, so a later one
+ * cannot change what the workflow observes.
+ *
+ * The classification mirrors `entityEventClass` in `@workflow/world`, which is
+ * what the runtime keys its own duplicate detection on. What it cannot mirror
+ * is consumer state: the runtime passes over an event only after every
+ * registered callback has declined it, and a callback registered for a
+ * still-open entity legitimately claims a repeat (each retry of a step writes
+ * another `step_started`, and a live step consumer absorbs a second
+ * `step_created`). So a repeat counts here only once a terminal event for the
+ * same entity sits earlier in the log, which is the point past which no
+ * consumer remains.
+ */
+
+/**
+ * Classes whose event closes its entity: no consumer is left for it after.
+ *
+ * The run's own terminal events are absent because `entityEventClass` gives
+ * them no class. The runtime exits rather than replaying the body once the log
+ * holds one, so nothing ever consumes them and nothing can repeat them.
+ */
+const TERMINAL_EVENT_CLASSES: ReadonlySet<EntityEventClass> = new Set([
+  'step_terminal',
+  'wait_completed',
+  'hook_disposed',
+]);
+
+/** Classes with no entity to close first: the log records one per run. */
+const SINGLETON_EVENT_CLASSES: ReadonlySet<EntityEventClass> = new Set([
+  'run_started',
+]);
+
+/** Entity key for events that carry no correlation ID (the run itself). */
+const RUN_ENTITY_KEY = '';
+
+/**
+ * Shown against an event this module reports. Deliberately says what the log
+ * shows rather than what the runtime did with it: tolerating these repeats is
+ * recent, and on a run recorded before it a repeat no consumer claimed failed
+ * the replay instead of being passed over.
+ */
+export const DUPLICATE_EVENT_MESSAGE =
+  'Written by a concurrent replay after an event of the same kind was already recorded and acted on. The run follows the earlier one.';
+
+/**
+ * Candidate log order, by event ID.
+ *
+ * Event IDs are fixed-width and monotonic within a run under both the ULID and
+ * the slot scheme. Length is compared first so a shorter ID never sorts after
+ * a longer one on a log that mixes widths.
+ *
+ * Whether this *is* the log order depends on the ID scheme, which is why
+ * {@link hasKnowableLogOrder} gates the fold. See its doc.
+ */
+function compareEventId(a: Event, b: Event): number {
+  if (a.eventId.length !== b.eventId.length) {
+    return a.eventId.length - b.eventId.length;
+  }
+  return a.eventId < b.eventId ? -1 : a.eventId > b.eventId ? 1 : 0;
+}
+
+function createdAtMs(event: Event): number {
+  const createdAt = event.createdAt;
+  return createdAt instanceof Date
+    ? createdAt.getTime()
+    : new Date(createdAt as unknown as string).getTime();
+}
+
+/**
+ * Whether the order the run consumed its log in can be recovered from the
+ * events alone.
+ *
+ * Which occurrence of a class came first is the whole question here, so the
+ * fold needs the log's order, not an order. The backends do not agree on how
+ * to recover it for every ID scheme:
+ *
+ * - A **slot-numbered** run carries its position in the ID. The slot is drawn
+ *   at the publish, which is the linearization point, so slot order is log
+ *   order everywhere and the ID alone settles it.
+ * - A **ULID-numbered** run does not. One backend returns such a log in
+ *   `(createdAt, eventId)` order while another returns it keyed on the ID, and
+ *   `createdAt` is stamped when the write request arrives rather than when it
+ *   commits. Concurrent writers can therefore produce opposite timestamp and
+ *   ID orders, and the run consumed whichever its own backend served.
+ *
+ * So a ULID log is only knowable where the two orders agree. Where they
+ * contradict, the fold could name the surviving event and pass over the one
+ * the run acted on, which is worse than saying nothing.
+ */
+function hasKnowableLogOrder(orderedById: readonly Event[]): boolean {
+  if (orderedById.every((event) => isSlotEventId(event.eventId))) return true;
+
+  for (let index = 1; index < orderedById.length; index++) {
+    const previous = createdAtMs(orderedById[index - 1]);
+    const current = createdAtMs(orderedById[index]);
+    // A missing or unparseable timestamp leaves nothing to corroborate the ID
+    // order with, which is the same position as a contradiction.
+    if (Number.isNaN(previous) || Number.isNaN(current)) return false;
+    if (current < previous) return false;
+  }
+
+  return true;
+}
+
+/** The fold itself, over a log whose order is known. */
+function foldDuplicates(ordered: readonly Event[]): Set<string> {
+  const duplicates = new Set<string>();
+  const seenClasses = new Set<string>();
+  const closedEntities = new Set<string>();
+
+  for (const event of ordered) {
+    const eventClass = entityEventClass(event.eventType);
+    if (eventClass === undefined) continue;
+
+    const entity = event.correlationId ?? RUN_ENTITY_KEY;
+    const classKey = `${eventClass}:${entity}`;
+    const repeatsClass = seenClasses.has(classKey);
+    const entityWasClosed = closedEntities.has(entity);
+
+    if (TERMINAL_EVENT_CLASSES.has(eventClass)) {
+      closedEntities.add(entity);
+    }
+
+    if (!repeatsClass) {
+      // First of its class, but the entity already finished: no consumer is
+      // left to take it and it repeats nothing, so the runtime reports
+      // divergence here and exits. Everything past this point went unread, so
+      // the fold stops with it rather than recording the class and presenting
+      // a later event of it as a repeat the run passed over.
+      if (entityWasClosed) break;
+      seenClasses.add(classKey);
+      continue;
+    }
+
+    // The entity is still open, so a consumer is registered for it and takes
+    // this event: another attempt, not a repeat read past.
+    if (entityWasClosed || SINGLETON_EVENT_CLASSES.has(eventClass)) {
+      duplicates.add(event.eventId);
+    }
+  }
+
+  return duplicates;
+}
+
+/**
+ * The IDs of the events in `events` that repeat a class the log already
+ * records for the same entity, after that entity finished.
+ *
+ * `isCompleteHistory` must be false whenever the caller holds a subset of the
+ * run's log: one page of a paginated list, or the result of a search. Which
+ * occurrence of a class came first is a property of the whole log, so on a
+ * subset the earlier event may simply be missing, and the fold would report
+ * the surviving one. Nothing is classified in that case.
+ *
+ * Two other things make the answer unknowable and yield the same empty result:
+ * a log whose order cannot be recovered from the events (see
+ * {@link hasKnowableLogOrder}), and everything past the point the run
+ * diverged, since the run exited there and read no further.
+ */
+export function findDuplicateEventIds(
+  events: readonly Event[],
+  { isCompleteHistory }: { isCompleteHistory: boolean }
+): Set<string> {
+  if (!isCompleteHistory || events.length < 2) return new Set();
+
+  // Dropped before the sort, not during the fold: an event with no ID has no
+  // log position to order on, and the caller could not match it either.
+  const ordered = events
+    .filter((event) => Boolean(event.eventId))
+    .sort(compareEventId);
+
+  if (!hasKnowableLogOrder(ordered)) return new Set();
+
+  return foldDuplicates(ordered);
+}

package/src/lib/event-materialization.test.ts

@@ -0,0 +1,117 @@
+import type { Event, EventType } from '@workflow/world';
+import { describe, expect, it } from 'vitest';
+import { materializeSteps } from './event-materialization';
+
+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;
+  const offsetSeconds = options.at ?? nextId;
+  return {
+    eventId: `evt_${nextId}`,
+    runId: 'run_1',
+    eventType,
+    correlationId: options.correlationId,
+    createdAt: new Date(BASE_TIME + offsetSeconds * 1000),
+    occurredAt: new Date(BASE_TIME + offsetSeconds * 1000),
+    eventData: eventType === 'step_created' ? { stepName: 'doWork' } : {},
+  } as unknown as Event;
+}
+
+describe('materializeSteps', () => {
+  it('derives status and timings from the run of a well-formed step', () => {
+    const events = [
+      event('step_created', { correlationId: 'step_a', at: 1 }),
+      event('step_started', { correlationId: 'step_a', at: 2 }),
+      event('step_completed', { correlationId: 'step_a', at: 5 }),
+    ];
+
+    const [step] = materializeSteps(events);
+
+    expect(step.status).toBe('completed');
+    expect(step.attempt).toBe(1);
+    expect(step.startedAt?.getTime()).toBe(BASE_TIME + 2000);
+    expect(step.completedAt?.getTime()).toBe(BASE_TIME + 5000);
+  });
+
+  it('counts one attempt per start across retries', () => {
+    const events = [
+      event('step_created', { correlationId: 'step_a', at: 1 }),
+      event('step_started', { correlationId: 'step_a', at: 2 }),
+      event('step_retrying', { correlationId: 'step_a', at: 3 }),
+      event('step_started', { correlationId: 'step_a', at: 4 }),
+      event('step_completed', { correlationId: 'step_a', at: 6 }),
+    ];
+
+    const [step] = materializeSteps(events);
+
+    expect(step.attempt).toBe(2);
+    expect(step.status).toBe('completed');
+    // The first start is when the step went from queued to running.
+    expect(step.startedAt?.getTime()).toBe(BASE_TIME + 2000);
+  });
+
+  it('keeps the outcome the run acted on when a replay writes another one', () => {
+    const events = [
+      event('step_created', { correlationId: 'step_a', at: 1 }),
+      event('step_started', { correlationId: 'step_a', at: 2 }),
+      event('step_failed', { correlationId: 'step_a', at: 3 }),
+      // Written by a concurrent replay working from a stale prefix.
+      event('step_completed', { correlationId: 'step_a', at: 9 }),
+    ];
+
+    const [step] = materializeSteps(events, { isCompleteHistory: true });
+
+    expect(step.status).toBe('failed');
+    expect(step.completedAt?.getTime()).toBe(BASE_TIME + 3000);
+    expect(step.updatedAt.getTime()).toBe(BASE_TIME + 3000);
+  });
+
+  it('still lists the passed-over event on the entity', () => {
+    const events = [
+      event('step_created', { correlationId: 'step_a', at: 1 }),
+      event('step_started', { correlationId: 'step_a', at: 2 }),
+      event('step_failed', { correlationId: 'step_a', at: 3 }),
+      event('step_completed', { correlationId: 'step_a', at: 9 }),
+    ];
+
+    const [step] = materializeSteps(events, { isCompleteHistory: true });
+
+    expect(step.events).toHaveLength(4);
+  });
+
+  it('takes the last outcome when the log may be incomplete', () => {
+    const events = [
+      event('step_created', { correlationId: 'step_a', at: 1 }),
+      event('step_started', { correlationId: 'step_a', at: 2 }),
+      event('step_failed', { correlationId: 'step_a', at: 3 }),
+      event('step_completed', { correlationId: 'step_a', at: 9 }),
+    ];
+
+    // On a page of the log there is no telling which failure the run acted on,
+    // so nothing is passed over and the fold reports what it was given.
+    const [step] = materializeSteps(events);
+
+    expect(step.status).toBe('completed');
+  });
+
+  it('counts a repeated creation as one attempt while the step is open', () => {
+    const events = [
+      event('step_created', { correlationId: 'step_a', at: 1 }),
+      // A live step consumer claims this, so it is an attempt, not a repeat.
+      event('step_created', { correlationId: 'step_a', at: 2 }),
+      event('step_started', { correlationId: 'step_a', at: 3 }),
+    ];
+
+    const [step] = materializeSteps(events, { isCompleteHistory: true });
+
+    expect(step.events).toHaveLength(3);
+    expect(step.status).toBe('running');
+    expect(step.attempt).toBe(1);
+  });
+});

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,
   };
 }