@workflow/web-shared 5.0.0-beta.3 → 5.0.0-beta.31

package/src/lib/event-materialization.ts

@@ -10,7 +10,13 @@
  * of making separate API calls for each entity type.
  */
 
-import type { Event, StepStatus } from '@workflow/world';
+import {
+  type Event,
+  isHookLifecycleEventType,
+  isStepEventType,
+  isWaitEventType,
+  type StepStatus,
+} from '@workflow/world';
 
 // ---------------------------------------------------------------------------
 // Materialized entity types
@@ -60,18 +66,18 @@ export interface MaterializedEntities {
 }
 
 // ---------------------------------------------------------------------------
-// Helper: group events by correlationId prefix
+// Helper: group events by correlationId
 // ---------------------------------------------------------------------------
 
 function groupByCorrelationId(
   events: Event[],
-  prefixes: string[]
+  matchesEventType: (eventType: string) => boolean
 ): Map<string, Event[]> {
   const groups = new Map<string, Event[]>();
   for (const event of events) {
     const cid = event.correlationId;
     if (!cid) continue;
-    if (!prefixes.some((p) => cid.startsWith(p))) continue;
+    if (!matchesEventType(event.eventType)) continue;
     const existing = groups.get(cid);
     if (existing) {
       existing.push(event);
@@ -82,6 +88,14 @@ function groupByCorrelationId(
   return groups;
 }
 
+function getEventTimestamp(event: Event | undefined): Date | undefined {
+  const value = event?.occurredAt ?? event?.createdAt;
+  if (!value) return undefined;
+
+  const date = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(date.getTime()) ? undefined : date;
+}
+
 // ---------------------------------------------------------------------------
 // materializeSteps
 // ---------------------------------------------------------------------------
@@ -93,7 +107,7 @@ function groupByCorrelationId(
  * step_created event with no completion yet.
  */
 export function materializeSteps(events: Event[]): MaterializedStep[] {
-  const groups = groupByCorrelationId(events, ['step_']);
+  const groups = groupByCorrelationId(events, isStepEventType);
   const steps: MaterializedStep[] = [];
 
   for (const [correlationId, stepEvents] of groups) {
@@ -104,31 +118,31 @@ export function materializeSteps(events: Event[]): MaterializedStep[] {
     let attempt = 0;
     let startedAt: Date | undefined;
     let completedAt: Date | undefined;
-    let updatedAt = created.createdAt;
+    let updatedAt = getEventTimestamp(created) ?? created.createdAt;
 
     for (const e of stepEvents) {
       switch (e.eventType) {
         case 'step_started':
           status = 'running';
           attempt += 1;
-          if (!startedAt) startedAt = e.createdAt;
+          if (!startedAt) startedAt = getEventTimestamp(e) ?? e.createdAt;
           completedAt = undefined;
-          updatedAt = e.createdAt;
+          updatedAt = getEventTimestamp(e) ?? e.createdAt;
           break;
         case 'step_completed':
           status = 'completed';
-          completedAt = e.createdAt;
-          updatedAt = e.createdAt;
+          completedAt = getEventTimestamp(e) ?? e.createdAt;
+          updatedAt = getEventTimestamp(e) ?? e.createdAt;
           break;
         case 'step_failed':
           status = 'failed';
-          completedAt = e.createdAt;
-          updatedAt = e.createdAt;
+          completedAt = getEventTimestamp(e) ?? e.createdAt;
+          updatedAt = getEventTimestamp(e) ?? e.createdAt;
           break;
         case 'step_retrying':
           status = 'pending';
           completedAt = undefined;
-          updatedAt = e.createdAt;
+          updatedAt = getEventTimestamp(e) ?? e.createdAt;
           break;
       }
     }
@@ -142,7 +156,7 @@ export function materializeSteps(events: Event[]): MaterializedStep[] {
           : correlationId,
       status,
       attempt,
-      createdAt: created.createdAt,
+      createdAt: getEventTimestamp(created) ?? created.createdAt,
       startedAt,
       completedAt,
       updatedAt,
@@ -161,7 +175,7 @@ export function materializeSteps(events: Event[]): MaterializedStep[] {
  * Group hook_* events by correlationId and build Hook-like entities.
  */
 export function materializeHooks(events: Event[]): MaterializedHook[] {
-  const groups = groupByCorrelationId(events, ['hook_']);
+  const groups = groupByCorrelationId(events, isHookLifecycleEventType);
   const hooks: MaterializedHook[] = [];
 
   for (const [correlationId, hookEvents] of groups) {
@@ -181,10 +195,10 @@ export function materializeHooks(events: Event[]): MaterializedHook[] {
         created.eventType === 'hook_created'
           ? created.eventData?.token
           : undefined,
-      createdAt: created.createdAt,
+      createdAt: getEventTimestamp(created) ?? created.createdAt,
       receivedCount: receivedEvents.length,
-      lastReceivedAt: lastReceived?.createdAt,
-      disposedAt: disposed?.createdAt,
+      lastReceivedAt: getEventTimestamp(lastReceived),
+      disposedAt: getEventTimestamp(disposed),
       events: hookEvents,
     });
   }
@@ -200,7 +214,7 @@ export function materializeHooks(events: Event[]): MaterializedHook[] {
  * Group wait_* events by correlationId and build Wait-like entities.
  */
 export function materializeWaits(events: Event[]): MaterializedWait[] {
-  const groups = groupByCorrelationId(events, ['wait_']);
+  const groups = groupByCorrelationId(events, isWaitEventType);
   const waits: MaterializedWait[] = [];
 
   for (const [correlationId, waitEvents] of groups) {
@@ -213,12 +227,12 @@ export function materializeWaits(events: Event[]): MaterializedWait[] {
       waitId: correlationId,
       runId: created.runId,
       status: completed ? 'completed' : 'waiting',
-      createdAt: created.createdAt,
+      createdAt: getEventTimestamp(created) ?? created.createdAt,
       resumeAt:
         created.eventType === 'wait_created'
           ? created.eventData?.resumeAt
           : undefined,
-      completedAt: completed?.createdAt,
+      completedAt: getEventTimestamp(completed),
       events: waitEvents,
     });
   }

package/src/lib/exact-event-search-id.ts

@@ -0,0 +1,67 @@
+import type { Event } from '@workflow/world';
+
+const WORKFLOW_ULID_BODY = '[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}';
+
+const STEP_ID_PATTERN = new RegExp(`^step_(${WORKFLOW_ULID_BODY})$`, 'i');
+const WAIT_ID_PATTERN = new RegExp(`^wait_(${WORKFLOW_ULID_BODY})$`, 'i');
+const HOOK_ID_PATTERN = new RegExp(`^hook_(${WORKFLOW_ULID_BODY})$`, 'i');
+const EVENT_ID_PATTERN = new RegExp(`^evnt_(${WORKFLOW_ULID_BODY})$`, 'i');
+
+const WORKFLOW_ID_PREFIX_PATTERN = /^(step_|wait_|hook_|evnt_|wrun_)/i;
+
+export type ExactWorkflowSearchIdKind = 'step' | 'wait' | 'hook' | 'event';
+
+export type ExactWorkflowSearchId = {
+  kind: ExactWorkflowSearchIdKind;
+  id: string;
+};
+
+export type ExactIdSearchResult =
+  | { status: 'ok'; events: Event[]; truncated?: boolean }
+  | { status: 'not_found' }
+  | { status: 'error'; message: string };
+
+function matchPrefixedId(
+  pattern: RegExp,
+  prefix: 'step' | 'wait' | 'hook' | 'evnt',
+  kind: ExactWorkflowSearchIdKind,
+  query: string
+): ExactWorkflowSearchId | null {
+  const match = query.match(pattern);
+  if (!match) {
+    return null;
+  }
+  return { kind, id: `${prefix}_${match[1].toUpperCase()}` };
+}
+
+/**
+ * Returns a parsed workflow ID when `query` is a full step, wait, hook, or event ID.
+ * Partial IDs and run IDs (`wrun_`) are ignored. ULID bodies are matched case-insensitively
+ * and normalized to uppercase in the returned ID.
+ */
+export function parseExactWorkflowSearchId(
+  query: string
+): ExactWorkflowSearchId | null {
+  const trimmed = query.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  return (
+    matchPrefixedId(STEP_ID_PATTERN, 'step', 'step', trimmed) ??
+    matchPrefixedId(WAIT_ID_PATTERN, 'wait', 'wait', trimmed) ??
+    matchPrefixedId(HOOK_ID_PATTERN, 'hook', 'hook', trimmed) ??
+    matchPrefixedId(EVENT_ID_PATTERN, 'evnt', 'event', trimmed)
+  );
+}
+
+/** True when input looks like the user is attempting an ID search (including partial). */
+export function looksLikeWorkflowIdSearchInput(query: string): boolean {
+  const trimmed = query.trim();
+  if (!WORKFLOW_ID_PREFIX_PATTERN.test(trimmed)) {
+    return false;
+  }
+  // Distinguish IDs (contain digits) from event-type strings like step_started.
+  // Assumes workflow event types do not include digits in their names.
+  return /\d/.test(trimmed);
+}

package/src/lib/hydration.ts

@@ -16,7 +16,7 @@ import {
   type Revivers,
   serializedInstanceToRef,
 } from '@workflow/core/serialization-format';
-import { EVENT_DATA_REF_FIELDS } from '@workflow/world';
+import { getEventDataRefFields } from '@workflow/world';
 
 // Re-export types and utilities that consumers need
 export {
@@ -58,12 +58,60 @@ function base64ToArrayBuffer(base64: string): ArrayBuffer {
 // Web revivers (browser-safe, no Buffer dependency)
 // ---------------------------------------------------------------------------
 
+/**
+ * Build a reviver for one of the built-in `Error` subclasses (e.g.
+ * `TypeError`, `RangeError`). The constructor for the named subclass is
+ * resolved off `globalThis` at call time so the produced instance has the
+ * correct prototype chain in the consumer realm. Falls back to a generic
+ * `Error` (with `name` set) if the global isn't available, which keeps the
+ * o11y UI rendering even on exotic browsers.
+ *
+ * `cause` is passed through `ErrorOptions` to the constructor when present,
+ * matching `getCommonRevivers` in `@workflow/core` so the resulting `cause`
+ * property has the same semantics (non-enumerable, set by the engine) as a
+ * freshly thrown Error in the consumer realm. The `'cause' in value` check
+ * preserves the distinction between "no cause" and "cause is undefined".
+ */
+function makeWebErrorSubclassReviver(
+  name:
+    | 'EvalError'
+    | 'RangeError'
+    | 'ReferenceError'
+    | 'SyntaxError'
+    | 'TypeError'
+    | 'URIError'
+) {
+  return (value: { message: string; stack?: string; cause?: unknown }) => {
+    const opts = 'cause' in value ? { cause: value.cause } : undefined;
+    const Ctor = (globalThis as Record<string, any>)[name] as
+      | ErrorConstructor
+      | undefined;
+    let error: Error;
+    if (typeof Ctor === 'function') {
+      error = new Ctor(value.message, opts);
+    } else {
+      // Fallback path: no built-in subclass available (exotic env). Construct
+      // a plain Error with the right `name` and copy `cause` manually since
+      // the base Error constructor is what we actually called.
+      error = Object.assign(new Error(value.message, opts), { name });
+    }
+    if (value.stack !== undefined) error.stack = value.stack;
+    return error;
+  };
+}
+
 /**
  * Get the web-specific revivers for hydrating serialized data.
  *
  * Uses `atob()` for base64 decoding (no Node.js Buffer dependency).
  * All types are revived as real instances (Date, Map, Set, URL,
  * URLSearchParams, Headers, Error, etc.).
+ *
+ * NOTE: this set must mirror the keys in `SerializableSpecial` (see
+ * `@workflow/core/serialization/types`). Any reducer key added on the
+ * serialization side that isn't covered here will cause `devalue.unflatten`
+ * to throw `Unknown type X`, which `hydrateResourceIO` swallows and
+ * surfaces as a "Failed to load resource details" banner in the o11y UI.
  */
 export function getWebRevivers(): Revivers {
   function reviveArrayBuffer(value: string): ArrayBuffer {
@@ -83,10 +131,120 @@ export function getWebRevivers(): Revivers {
     BigUint64Array: (value: string) =>
       new BigUint64Array(reviveArrayBuffer(value)),
     Date: (value) => new Date(value),
+
+    // Error family. The reducer side (see
+    // `packages/core/src/serialization/reducers/common.ts`) emits a tagged
+    // entry for each built-in Error subclass plus the workflow-specific
+    // `FatalError` / `RetryableError` / `HookConflictError` /
+    // `RuntimeDecryptionError` and `AggregateError`. Without
+    // matching revivers here, `devalue.unflatten` throws "Unknown type X"
+    // — which surfaces in the web o11y UI as "Failed to load resource
+    // details: Unknown type FatalError".
     Error: (value) => {
+      const opts = 'cause' in value ? { cause: value.cause } : undefined;
+      const error = new Error(value.message, opts);
+      error.name = value.name;
+      if (value.stack !== undefined) error.stack = value.stack;
+      return error;
+    },
+    EvalError: makeWebErrorSubclassReviver('EvalError'),
+    RangeError: makeWebErrorSubclassReviver('RangeError'),
+    ReferenceError: makeWebErrorSubclassReviver('ReferenceError'),
+    SyntaxError: makeWebErrorSubclassReviver('SyntaxError'),
+    TypeError: makeWebErrorSubclassReviver('TypeError'),
+    URIError: makeWebErrorSubclassReviver('URIError'),
+    AggregateError: (value) => {
+      const opts = 'cause' in value ? { cause: value.cause } : undefined;
+      const Ctor = (
+        globalThis as { AggregateError?: AggregateErrorConstructor }
+      ).AggregateError;
+      const error =
+        typeof Ctor === 'function'
+          ? new Ctor(value.errors, value.message, opts)
+          : Object.assign(new Error(value.message, opts), {
+              name: 'AggregateError',
+              errors: value.errors,
+            });
+      if (value.stack !== undefined) error.stack = value.stack;
+      return error;
+    },
+    // `FatalError` and `RetryableError` are not built-in browser globals,
+    // so we can't resolve a constructor from globalThis. The web o11y UI
+    // doesn't need `instanceof FatalError` to pass (no user code runs
+    // here) — it just needs `name`, `message`, `stack`, and any extra
+    // enumerable fields to render. Construct a plain `Error` with `name`
+    // set; ObjectInspector reads `constructor.name` for the displayed
+    // class label, but we don't have the real class, so we emit a tagged
+    // Error whose `name` field carries the class identity. This matches
+    // how the existing base `Error` reviver presents unknown subclasses.
+    FatalError: (value) => {
+      const opts = 'cause' in value ? { cause: value.cause } : undefined;
+      const error = new Error(value.message, opts);
+      error.name = 'FatalError';
+      if (value.stack !== undefined) error.stack = value.stack;
+      return error;
+    },
+    HookConflictError: (value) => {
+      const opts = 'cause' in value ? { cause: value.cause } : undefined;
+      const error = new Error(value.message, opts) as Error & {
+        token?: string;
+        conflictingRunId?: string;
+      };
+      error.name = 'HookConflictError';
+      error.token = value.token;
+      if (value.conflictingRunId !== undefined) {
+        error.conflictingRunId = value.conflictingRunId;
+      }
+      if (value.stack !== undefined) error.stack = value.stack;
+      return error;
+    },
+    RetryableError: (value) => {
+      const opts = 'cause' in value ? { cause: value.cause } : undefined;
+      const error = new Error(value.message, opts) as Error & {
+        retryAfter?: Date;
+      };
+      error.name = 'RetryableError';
+      if (value.stack !== undefined) error.stack = value.stack;
+      // `retryAfter` is serialized as an epoch ms number (see the runtime
+      // RetryableError reducer for the rationale around realm-safety).
+      // Rehydrate as a Date so o11y consumers can render it directly.
+      // Guard against payloads from older runtime versions that predate
+      // the field — without this check, `new Date(undefined)` would
+      // produce an Invalid Date rather than omitting the property.
+      if (value.retryAfter != null) {
+        error.retryAfter = new Date(value.retryAfter);
+      }
+      return error;
+    },
+    RuntimeDecryptionError: (value) => {
+      const opts = 'cause' in value ? { cause: value.cause } : undefined;
+      const error = new Error(value.message, opts) as Error & {
+        context?: unknown;
+      };
+      error.name = 'RuntimeDecryptionError';
+      if (value.context !== undefined) {
+        error.context = value.context;
+      }
+      if (value.stack !== undefined) error.stack = value.stack;
+      return error;
+    },
+    DOMException: (value) => {
+      // Modern browsers and Node 18+ expose `DOMException` on globalThis.
+      // `AbortController.abort()` with no argument synthesizes one as the
+      // signal's reason, so this is a common payload for any aborted step.
+      const G = globalThis as { DOMException?: typeof DOMException };
+      if (typeof G.DOMException === 'function') {
+        const e = new G.DOMException(value.message, value.name);
+        if (value.stack !== undefined) e.stack = value.stack;
+        if ('cause' in value) (e as { cause?: unknown }).cause = value.cause;
+        return e;
+      }
       const error = new Error(value.message);
       error.name = value.name;
-      error.stack = value.stack;
+      if (value.stack !== undefined) error.stack = value.stack;
+      if ('cause' in value) {
+        (error as Error & { cause?: unknown }).cause = value.cause;
+      }
       return error;
     },
     Float32Array: (value: string) => new Float32Array(reviveArrayBuffer(value)),
@@ -140,7 +298,7 @@ export function getWebRevivers(): Revivers {
 
     // Web-specific overrides for class instances.
     // Create objects with a dynamically-named constructor so that
-    // react-inspector shows the class name (it reads constructor.name).
+    // the data inspector shows the class name (it reads constructor.name).
     Class: (value) => `<class:${extractClassName(value.classId)}>`,
     Instance: (value) => {
       // Run instances are rendered as clickable RunRef badges
@@ -153,7 +311,7 @@ export function getWebRevivers(): Revivers {
       const props =
         data && typeof data === 'object' ? { ...data } : { value: data };
       // Create a constructor with the right name using computed property
-      // so react-inspector's `object.constructor.name` shows the class name.
+      // so the data inspector's `object.constructor.name` shows the class name.
       // Must use `function` (not arrow) because arrow functions have no .prototype.
       // biome-ignore lint/complexity/useArrowFunction: arrow functions have no .prototype
       const ctor = { [className]: function () {} }[className]!;
@@ -288,7 +446,7 @@ function replaceEncryptedAndExpiredWithMarkers<T>(resource: T): T {
   if (result.eventData && typeof result.eventData === 'object') {
     const eventType =
       typeof result.eventType === 'string' ? result.eventType : '';
-    const refKeys = EVENT_DATA_REF_FIELDS[eventType] ?? [];
+    const refKeys = getEventDataRefFields(eventType);
     const ed = { ...(result.eventData as Record<string, unknown>) };
     for (const key of refKeys) {
       if (key in ed) {
@@ -307,36 +465,56 @@ function replaceEncryptedAndExpiredWithMarkers<T>(resource: T): T {
  * When a key is provided, encrypted fields are decrypted before hydration.
  * This is the async version used when the user clicks "Decrypt" in the web UI.
  *
- * Handles both top-level fields (input, output, metadata) and nested
- * eventData subfields per `EVENT_DATA_REF_FIELDS` from `@workflow/world` for that event type.
+ * Handles both top-level fields (input, output, metadata) and nested eventData
+ * payload fields for that event type.
  */
 export async function hydrateResourceIOWithKey<T>(
   resource: T,
   key: Uint8Array
+): Promise<T> {
+  return hydrateResourceIOAsync(resource, key);
+}
+
+/**
+ * Async hydration for web display.
+ *
+ * This follows the same resource-field mapping as {@link hydrateResourceIO},
+ * but can also inflate compressed browser payloads through the registered
+ * zstd WASM decoder. When a key is provided, encrypted fields are decrypted
+ * first and then inflated/hydrated.
+ */
+export async function hydrateResourceIOAsync<T>(
+  resource: T,
+  key?: Uint8Array
 ): Promise<T> {
   const { hydrateDataWithKey } = await import(
     '@workflow/core/serialization-format'
   );
-  const { importKey } = await import('@workflow/core/encryption');
-  const cryptoKey = await importKey(key);
+  // Payloads may be zstd-compressed (the Web DecompressionStream has no zstd);
+  // register the WASM-backed browser decoder before hydrating. Idempotent and
+  // lazy — the WASM is only compiled when a zstd payload is actually decoded.
+  const { ensureZstdDecoderRegistered } = await import(
+    './zstd-browser-decoder.js'
+  );
+  ensureZstdDecoderRegistered();
+  const cryptoKey = key
+    ? await import('@workflow/core/encryption').then(({ importKey }) =>
+        importKey(key)
+      )
+    : undefined;
   const revivers = getRevivers();
 
-  /** Extract original encrypted bytes from a marker or raw Uint8Array, then decrypt + hydrate */
-  async function decryptField(
-    value: unknown,
-    rev: Revivers,
-    k: Awaited<ReturnType<typeof importKey>>
-  ): Promise<unknown> {
+  async function hydrateField(value: unknown): Promise<unknown> {
     // Already-hydrated: encrypted marker with stored bytes
     if (isEncryptedMarker(value)) {
       const raw = (value as any).__encryptedData as Uint8Array;
-      return hydrateDataWithKey(raw, rev, k);
+      return cryptoKey ? hydrateDataWithKey(raw, revivers, cryptoKey) : value;
     }
-    // Raw encrypted Uint8Array (not yet hydrated)
+    // Raw Uint8Array: may be encrypted, compressed, or plain devalue.
     if (value instanceof Uint8Array) {
-      return hydrateDataWithKey(value, rev, k);
+      return hydrateDataWithKey(value, revivers, cryptoKey);
     }
-    // Not encrypted — return as-is
+    // Not serialized — return as-is.
     return value;
   }
 
@@ -346,29 +524,25 @@ export async function hydrateResourceIOWithKey<T>(
   // Decrypt + hydrate top-level serialized fields (runs, steps, hooks)
   for (const field of ['input', 'output', 'metadata', 'error']) {
     if (field in result) {
-      result[field] = await decryptField(result[field], revivers, cryptoKey);
+      result[field] = await hydrateField(result[field]);
     }
   }
 
-  // Decrypt + hydrate eventData subfields (events)
+  // Hydrate eventData subfields (events)
   if (result.eventData && typeof result.eventData === 'object') {
     const eventType =
       typeof result.eventType === 'string' ? result.eventType : '';
-    const refKeys = EVENT_DATA_REF_FIELDS[eventType] ?? [];
+    const refKeys = getEventDataRefFields(eventType);
     const eventData = { ...(result.eventData as Record<string, unknown>) };
     for (const field of refKeys) {
       if (field in eventData) {
-        eventData[field] = await decryptField(
-          eventData[field],
-          revivers,
-          cryptoKey
-        );
+        eventData[field] = await hydrateField(eventData[field]);
       }
     }
     result.eventData = eventData;
   }
 
-  return result as T;
+  return replaceEncryptedAndExpiredWithMarkers(result as T);
 }
 
 /**
@@ -387,7 +561,7 @@ export function hasEncryptedFields(resource: unknown): boolean {
 
   if (r.eventData && typeof r.eventData === 'object') {
     const eventType = typeof r.eventType === 'string' ? r.eventType : '';
-    const refKeys = EVENT_DATA_REF_FIELDS[eventType] ?? [];
+    const refKeys = getEventDataRefFields(eventType);
     const ed = r.eventData as Record<string, unknown>;
     for (const key of refKeys) {
       if (key in ed && isEncryptedMarker(ed[key])) return true;

package/src/lib/trace-builder.ts

@@ -6,30 +6,54 @@
  * a fully-formed Trace ready for the trace viewer.
  */
 
-import type { Event, WorkflowRun } from '@workflow/world';
+import {
+  type Event,
+  isHookLifecycleEventType,
+  isStepEventType,
+  isWaitEventType,
+  type WorkflowRun,
+} from '@workflow/world';
 import type { Span } from '../components/trace-viewer/types';
 import {
+  getEventTimestamp,
   hookToSpan,
   runToSpan,
   stepToSpan,
-  waitToSpan,
   WORKFLOW_LIBRARY,
+  waitToSpan,
 } from '../components/workflow-traces/trace-span-construction';
 import { otelTimeToMs } from '../components/workflow-traces/trace-time-utils';
 
-// ---------------------------------------------------------------------------
-// Event type classifiers
-// ---------------------------------------------------------------------------
-
-export const isStepEvent = (eventType: string) => eventType.startsWith('step_');
-
-export const isTimerEvent = (eventType: string) =>
-  eventType === 'wait_created' || eventType === 'wait_completed';
+/**
+ * Events that belong to the run root span rather than a child entity span.
+ * Mirrors the fallthrough logic in {@link groupEventsByCorrelation}: events
+ * without a correlationId (run lifecycle) plus correlated events that aren't
+ * step/timer/hook events (e.g. `attr_set`, whose correlationId is a dedup
+ * token rather than a child entity ID).
+ */
+export const isRunLevelEvent = (event: Event): boolean =>
+  !event.correlationId ||
+  (!isWaitEventType(event.eventType) &&
+    !isHookLifecycleEventType(event.eventType) &&
+    !isStepEventType(event.eventType));
 
-export const isHookLifecycleEvent = (eventType: string) =>
-  eventType === 'hook_received' ||
-  eventType === 'hook_created' ||
-  eventType === 'hook_disposed';
+/**
+ * Filter the raw event list down to the events for a selected span.
+ * For the run root span this returns run-level events (see
+ * {@link isRunLevelEvent}); for child spans it returns the events
+ * correlated to that span's ID.
+ */
+export function filterSpanRawEvents(
+  events: Event[],
+  resource: string | undefined,
+  spanId: string | undefined
+): Event[] {
+  if (resource === 'run') {
+    return events.filter(isRunLevelEvent);
+  }
+  if (!spanId) return [];
+  return events.filter((e) => e.correlationId === spanId);
+}
 
 // ---------------------------------------------------------------------------
 // Event grouping
@@ -68,17 +92,17 @@ export function groupEventsByCorrelation(events: Event[]): GroupedEvents {
       continue;
     }
 
-    if (isTimerEvent(event.eventType)) {
+    if (isWaitEventType(event.eventType)) {
       pushEvent(timerEvents, correlationId, event);
       continue;
     }
 
-    if (isHookLifecycleEvent(event.eventType)) {
+    if (isHookLifecycleEventType(event.eventType)) {
       pushEvent(hookEvents, correlationId, event);
       continue;
     }
 
-    if (isStepEvent(event.eventType)) {
+    if (isStepEventType(event.eventType)) {
       pushEvent(eventsByStepId, correlationId, event);
       continue;
     }
@@ -101,7 +125,7 @@ export function groupEventsByCorrelation(events: Event[]): GroupedEvents {
 function computeLatestKnownTime(events: Event[], run: WorkflowRun): Date {
   let latest = new Date(run.createdAt).getTime();
   for (const event of events) {
-    const t = new Date(event.createdAt).getTime();
+    const t = (getEventTimestamp(event) ?? new Date(event.createdAt)).getTime();
     if (t > latest) latest = t;
   }
   return new Date(latest);
@@ -117,6 +141,7 @@ function buildSpans(
   // unknown territory. Even when the run is completed, we may not have loaded
   // all events yet, so always use the latest event we've actually seen.
   const childMaxEnd = latestKnownTime;
+  const runMaxEnd = run.completedAt ?? now;
 
   const stepSpans = Array.from(groupedEvents.eventsByStepId.values())
     .map((events) => stepToSpan(events, childMaxEnd))
@@ -127,7 +152,7 @@ function buildSpans(
     .filter((span): span is Span => span !== null);
 
   const waitSpans = Array.from(groupedEvents.timerEvents.values())
-    .map((events) => waitToSpan(events, childMaxEnd))
+    .map((events) => waitToSpan(events, childMaxEnd, runMaxEnd))
     .filter((span): span is Span => span !== null);
 
   return {