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

package/src/lib/hydration.ts

@@ -137,8 +137,8 @@ export function getWebRevivers(): Revivers {
     // 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
+    // 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;
@@ -171,7 +171,7 @@ export function getWebRevivers(): Revivers {
     // `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
+    // here). The web o11y UI 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
@@ -209,7 +209,7 @@ export function getWebRevivers(): Revivers {
       // 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
+      // 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);
@@ -492,17 +492,12 @@ export async function hydrateResourceIOAsync<T>(
   );
   // 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.
+  // lazy: the WASM is only compiled when a zstd payload is actually decoded.
   const { ensureZstdDecoderRegistered } = await import(
     './zstd-browser-decoder.js'
   );
   ensureZstdDecoderRegistered();
-  // Resolve the *full* key capability, not just the symmetric key: a run's
-  // event log can contain sealed ('encp') payloads that another run wrote to
-  // it (a cross-deployment hook resumption, say), and opening those needs the
-  // run's X25519 scalar in addition to its AES key. Both are derived from the
-  // same 32 bytes the key-retrieval endpoint returns.
-  // Resolve the *full* key capability, not just the symmetric key: a run's
+  // Resolve the *full* key capability: a run's
   // event log can contain sealed ('encp') payloads that another run wrote to
   // it (a cross-deployment hook resumption, say), and opening those needs the
   // run's X25519 scalar in addition to its AES key. Both derive from the same
@@ -520,7 +515,7 @@ export async function hydrateResourceIOAsync<T>(
     if (value instanceof Uint8Array) {
       return hydrateDataWithKey(value, revivers, cryptoKey);
     }
-    // Not serialized — return as-is.
+    // Not serialized, so return as-is.
     return value;
   }
 

package/src/lib/sealed-events.ts

@@ -0,0 +1,32 @@
+import { type Event, isSealedNoopEvent as isSealedNoop } from '@workflow/world';
+
+/**
+ * Sealed-position `noop` events (specVersion 7).
+ *
+ * A sealed-log backend hands each write its position before the write
+ * commits, so a writer that dies after claiming a position leaves a hole.
+ * The backend closes a provably abandoned hole by writing a `noop` event
+ * into it, creating a log-only row the run itself never observes. Replay steps
+ * over it without offering it to any consumer and without advancing the
+ * deterministic clock.
+ *
+ * The observability UI mirrors that treatment. A `noop` appears in event
+ * lists (greyed, with {@link SEALED_EVENT_MESSAGE} on hover) because it is a
+ * real row of the log, but it is excluded from span geometry and from
+ * trace-duration bounds: its `createdAt` is the *sealer's* wall clock, which
+ * can postdate every real event around it, and letting it stretch a span or
+ * the trace's known duration would chart the sealer's schedule rather than
+ * the run's.
+ */
+export const SEALED_EVENT_MESSAGE =
+  'No-op events are written by the backend to seal an abandoned log position';
+
+/**
+ * Whether `event` is a backend-written seal for an abandoned position.
+ *
+ * Delegates to `@workflow/world` so the UI, the `node:vm` engine and the
+ * QuickJS engine cannot drift on what a seal is.
+ */
+export function isSealedNoopEvent(event: Pick<Event, 'eventType'>): boolean {
+  return isSealedNoop(event);
+}

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

@@ -1,7 +1,7 @@
 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';
+import { buildTrace, filterSpanRawEvents } from './trace-builder';
 
 const BASE_TIME = Date.parse('2026-01-01T00:00:00.000Z');
 
@@ -71,4 +71,32 @@ describe('buildTrace', () => {
     expect(otelTimeToMs(stepSpan?.endTime ?? [0, 0])).toBe(BASE_TIME + 20_000);
     expect(trace.duplicateEventIds.size).toBe(0);
   });
+
+  it('keeps sealed-position noops out of the geometry and its time bounds', () => {
+    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 hole sealed by a reader long after the run went quiet. Its
+      // createdAt is the SEALER's clock — letting it into the geometry would
+      // stretch the trace to the sealer's schedule.
+      event('noop', { correlationId: 'noop_5', at: 300 }),
+    ];
+
+    const trace = buildTrace(run, events, new Date(BASE_TIME + 400_000), {
+      isCompleteHistory: true,
+    });
+
+    // No span for the noop's correlationId, and the trace's known duration
+    // ends at the last real event, not at the seal.
+    expect(trace.spans.some((span) => span.spanId === 'noop_5')).toBe(false);
+    expect(trace.knownDurationMs).toBe(4000);
+
+    // The run span's raw event list still shows the seal (greyed in the UI),
+    // exactly like duplicate rows: real log rows, marked with the reason.
+    const runRaw = filterSpanRawEvents(events, 'run', 'run_1');
+    expect(runRaw.some((e) => e.eventType === 'noop')).toBe(true);
+  });
 });

package/src/lib/trace-builder.ts

@@ -23,6 +23,7 @@ import {
 } from '../components/workflow-traces/trace-span-construction';
 import { otelTimeToMs } from '../components/workflow-traces/trace-time-utils';
 import { findDuplicateEventIds } from './duplicate-events';
+import { isSealedNoopEvent } from './sealed-events';
 import type { Span } from './trace-types';
 
 /**
@@ -212,14 +213,18 @@ export function buildTrace(
   // 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.
+  // Sealed-position noops are excluded for the same reason with a different
+  // clock: a noop's createdAt is the sealer's wall time, which can postdate
+  // every real event around it, so feeding it into span grouping or the
+  // latest-known-time bound would chart the sealer's schedule instead of the
+  // run's. The event lists still show both, marked with the reason.
   const duplicateEventIds = findDuplicateEventIds(events, {
     isCompleteHistory,
   });
-  const actedOnEvents =
-    duplicateEventIds.size === 0
-      ? events
-      : events.filter((event) => !duplicateEventIds.has(event.eventId));
+  const actedOnEvents = events.filter(
+    (event) =>
+      !duplicateEventIds.has(event.eventId) && !isSealedNoopEvent(event)
+  );
 
   const groupedEvents = groupEventsByCorrelation(actedOnEvents);
   const latestKnownTime = computeLatestKnownTime(actedOnEvents, run);

package/src/lib/utils.ts

@@ -80,7 +80,7 @@ export function formatDuration(ms: number, compact = false): string {
  * Unlike {@link formatDuration}, this keeps sub-second detail, so 1626ms
  * renders as "1.63s" rather than "2s". `fractionDigits` sets both the number of
  * decimals on the seconds component (trailing zeros trimmed, so 2000ms is "2s"
- * and 1500ms is "1.5s") and the rounding granularity — the default of 2 rounds
+ * and 1500ms is "1.5s") and the rounding granularity: the default of 2 rounds
  * to 10ms; the timeline ruler passes fewer digits to match its tick step.
  *
  * - < 1s: shows whole milliseconds (e.g. "626ms")

package/src/lib/zstd-browser-decoder.ts

@@ -8,7 +8,7 @@
  *
  * The package leaves WASM sourcing to the caller; we resolve the shipped
  * `zstd.wasm` as a bundler asset (`new URL(..., import.meta.url)`, the same
- * pattern the trace-viewer Worker uses) and compile it once, lazily — the
+ * pattern the trace-viewer Worker uses) and compile it once, lazily: the
  * WASM is fetched only the first time a zstd payload is actually decoded.
  */
 import { registerZstdDecoder } from '@workflow/core/serialization-format';