@dxos/plugin-assistant 0.8.4-main.fd6878d → 0.8.4-staging.60fe92afc8

package/src/execution-graph/index.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export {
+  CommitSelector,
+  buildExecutionGraph,
+  type BuildExecutionGraphParams,
+  type ExecutionGraph,
+  type ExecutionGraphDetailsMap,
+} from './execution-graph';
+export {
+  BEGIN_EVENT_TYPES,
+  END_EVENT_TYPES,
+  ROOT_SPAN_ID,
+  buildSpanTree,
+  flattenSpanTree,
+  isSpanBeginEvent,
+  isSpanEndEvent,
+  walkSpanTree,
+  type BuildSpanTreeOptions,
+  type Span,
+  type SpanMeta,
+} from './span-tree';

package/src/execution-graph/remote-snapshot.test.ts

@@ -0,0 +1,116 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, test } from 'vitest';
+
+import { Trace } from '@dxos/compute';
+import { Obj } from '@dxos/echo';
+
+import { buildExecutionGraph } from './execution-graph';
+
+/**
+ * Regression for sub-operations collapsing onto `main` when the event window in `buildSpanTree`
+ * dropped the parent span's `operation.start`.
+ *
+ * The remote trace snapshot has 714 chronological events. The 4th `Run Routine` span hosts every
+ * `Create object` / `Add schema` / `List schemas` / `Query` / `Add to context` sub-operation.
+ * Its `operation.start` lives near the front of the stream (index 70). Before the fix, the
+ * default `eventLimit = 300` would `slice(-300)` away that begin event, leaving the sub-ops'
+ * `parentPid` lookup unsatisfied — they ended up as top-level collapsible spans rendering their
+ * end commits on `main`.
+ */
+describe('TracePanel remote snapshot', () => {
+  test('sub-operations land on their parent Routine branch, never on main', ({ expect }) => {
+    const messages = loadRemoteTraceMessages(REMOTE_SNAPSHOT);
+    const { commits } = buildExecutionGraph({ traceMessages: messages });
+
+    // Commits whose message starts with one of these names originate from sub-operations
+    // (Trace.OperationEnd) — every one should live on the Routine's branch, never on `main`.
+    const subOpPrefixes = ['Create object', 'Add schema', 'List schemas', 'Query', 'Add to context'];
+    const isSubOpEnd = (message: string | undefined): boolean =>
+      message !== undefined && subOpPrefixes.some((prefix) => message.startsWith(prefix));
+
+    const subOpCommits = commits.filter((commit) => isSubOpEnd(commit.message));
+    expect(subOpCommits.length).toBeGreaterThan(0);
+
+    const onMain = subOpCommits.filter((commit) => commit.branch === 'main');
+    expect(onMain).toEqual([]);
+
+    // All sub-op end commits share the parent Routine's pid as their branch.
+    const branches = new Set(subOpCommits.map((commit) => commit.branch));
+    expect(branches.size).toBe(1);
+    expect(branches.has('main')).toBe(false);
+  });
+
+  test('Routine end commits anchor to the previous main commit, not back to their own begin', ({ expect }) => {
+    // Regression: the multi-Routine snapshot has overlapping top-level Routine spans (R2 starts
+    // before R1 ends, R4 starts before R3 ends). Previously, R1.end's first parent was
+    // R1.begin (looked up by `beginCommitIdBySpan`), which drew an edge across R2.begin in the
+    // rendered timeline. The fix anchors end commits to the immediate predecessor on the
+    // parent branch (R2.begin) and treats the own-branch tail as a separate merge parent.
+    const messages = loadRemoteTraceMessages(MULTI_SNAPSHOT);
+    const { commits } = buildExecutionGraph({ traceMessages: messages });
+
+    const mainCommits = commits.filter((commit) => commit.branch === 'main');
+    // Sanity check: 4 begin + 4 end Run-Routine commits on main.
+    expect(mainCommits).toHaveLength(8);
+
+    // For each commit on main, its first parent (if any) must be a commit that appears
+    // *earlier* in the main commit sequence — no "skip-back" edges to an older begin commit.
+    const idToMainIndex = new Map(mainCommits.map((commit, index) => [commit.id, index]));
+    for (let index = 1; index < mainCommits.length; index += 1) {
+      const commit = mainCommits[index];
+      const onMainParents = (commit.parents ?? []).filter((parentId) => idToMainIndex.has(parentId));
+      expect(onMainParents.length).toBeGreaterThan(0);
+      for (const parentId of onMainParents) {
+        const parentIndex = idToMainIndex.get(parentId)!;
+        // Every parent on main must be the immediate predecessor (index - 1). An older parent
+        // would render an edge that crosses over the intervening commits.
+        expect(parentIndex).toBe(index - 1);
+      }
+    }
+  });
+});
+
+const REMOTE_SNAPSHOT = 'trace-timeline-remote.dx.json';
+const MULTI_SNAPSHOT = 'trace-timeline-multiple.dx.json';
+
+interface RawMessage {
+  meta?: Trace.Meta;
+  isEphemeral?: boolean;
+  events?: Array<{ type: string; timestamp: number; data: unknown }>;
+}
+
+const loadRemoteTraceMessages = (filename: string): Trace.Message[] => {
+  const snapshotPath = join(__dirname, '../testing/data', filename);
+  const json = JSON.parse(readFileSync(snapshotPath, 'utf8')) as unknown;
+
+  const messages: Trace.Message[] = [];
+  const visit = (node: unknown): void => {
+    if (Array.isArray(node)) {
+      node.forEach(visit);
+      return;
+    }
+    if (node === null || typeof node !== 'object') {
+      return;
+    }
+    const candidate = node as RawMessage & Record<string, unknown>;
+    if (Array.isArray(candidate.events) && candidate.meta && typeof candidate.meta === 'object') {
+      messages.push(
+        Obj.make(Trace.Message, {
+          meta: candidate.meta,
+          isEphemeral: candidate.isEphemeral ?? false,
+          events: candidate.events,
+        }),
+      );
+    }
+    for (const value of Object.values(node as Record<string, unknown>)) {
+      visit(value);
+    }
+  };
+  visit(json);
+  return messages;
+};

package/src/execution-graph/span-tree.test.ts

@@ -0,0 +1,249 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+import { AgentRequestBegin, AgentRequestEnd } from '@dxos/assistant';
+import { Trace } from '@dxos/compute';
+
+import { ROOT_SPAN_ID, buildSpanTree, flattenSpanTree } from './span-tree';
+import { collectTraceEvents, withMeta } from './testing';
+
+const NoteEvent = Trace.EventType('note', {
+  schema: Schema.Struct({
+    text: Schema.optional(Schema.String),
+    index: Schema.optional(Schema.Number),
+  }),
+  isEphemeral: false,
+});
+
+const FooEvent = Trace.EventType('foo', {
+  schema: Schema.Struct({}),
+  isEphemeral: false,
+});
+
+describe('buildSpanTree', () => {
+  test('returns a root span for empty input', ({ expect }) => {
+    const tree = buildSpanTree([]);
+    expect(tree.id).toBe(ROOT_SPAN_ID);
+    expect(tree.children).toEqual([]);
+    expect(tree.events).toEqual([]);
+  });
+
+  test('events without pid attach to root span', ({ expect }) => {
+    const messages = collectTraceEvents(Trace.write(FooEvent, {}));
+    const tree = buildSpanTree(messages);
+    expect(tree.children).toEqual([]);
+    expect(tree.events).toHaveLength(1);
+    expect(tree.events[0].type).toBe('foo');
+  });
+
+  test('a single operation start/end pair produces one span under root', ({ expect }) => {
+    const messages = collectTraceEvents(
+      withMeta(
+        { pid: 'op-1' },
+        Effect.gen(function* () {
+          yield* Trace.write(Trace.OperationStart, { key: 'reply', name: 'Reply' });
+          yield* Trace.write(Trace.OperationEnd, { key: 'reply', name: 'Reply', outcome: 'success' });
+        }),
+      ),
+    );
+    const tree = buildSpanTree(messages);
+    expect(tree.children).toHaveLength(1);
+    expect(tree.children[0].meta.pid).toBe('op-1');
+    expect(tree.children[0].events).toHaveLength(2);
+    expect(tree.children[0].children).toEqual([]);
+  });
+
+  test('a nested operation attaches to its open parent', ({ expect }) => {
+    const messages = collectTraceEvents(
+      Effect.gen(function* () {
+        yield* withMeta({ pid: 'agent-1' }, Trace.write(AgentRequestBegin, {}));
+        yield* withMeta(
+          { pid: 'op-1', parentPid: 'agent-1' },
+          Effect.gen(function* () {
+            yield* Trace.write(Trace.OperationStart, { key: 'lookup', name: 'Lookup' });
+            yield* Trace.write(Trace.OperationEnd, { key: 'lookup', name: 'Lookup', outcome: 'success' });
+          }),
+        );
+        yield* withMeta({ pid: 'agent-1' }, Trace.write(AgentRequestEnd, { status: 'success' }));
+      }),
+    );
+    const tree = buildSpanTree(messages);
+    expect(tree.children).toHaveLength(1);
+    const agentSpan = tree.children[0];
+    expect(agentSpan.meta.pid).toBe('agent-1');
+    expect(agentSpan.children).toHaveLength(1);
+    expect(agentSpan.children[0].meta.pid).toBe('op-1');
+    expect(agentSpan.children[0].events).toHaveLength(2);
+  });
+
+  test('sequential agent requests in one process become sibling spans', ({ expect }) => {
+    const messages = collectTraceEvents(
+      withMeta(
+        { pid: 'agent-1' },
+        Effect.gen(function* () {
+          yield* Trace.write(AgentRequestBegin, {});
+          yield* Trace.write(AgentRequestEnd, { status: 'success' });
+          yield* Trace.write(AgentRequestBegin, {});
+          yield* Trace.write(AgentRequestEnd, { status: 'success' });
+        }),
+      ),
+    );
+    const tree = buildSpanTree(messages);
+    expect(tree.children).toHaveLength(2);
+    expect(tree.children.every((child) => child.meta.pid === 'agent-1')).toBe(true);
+    // Span ids are distinct even though pids are shared.
+    expect(tree.children[0].id).not.toBe(tree.children[1].id);
+  });
+
+  test('non-boundary events attach to the currently-open span', ({ expect }) => {
+    const messages = collectTraceEvents(
+      withMeta(
+        { pid: 'agent-1' },
+        Effect.gen(function* () {
+          yield* Trace.write(AgentRequestBegin, {});
+          yield* Trace.write(NoteEvent, {});
+          yield* Trace.write(AgentRequestEnd, { status: 'success' });
+        }),
+      ),
+    );
+    const tree = buildSpanTree(messages);
+    expect(tree.children[0].events).toHaveLength(3);
+    expect(tree.children[0].events.map((event) => event.type)).toEqual([
+      AgentRequestBegin.key,
+      'note',
+      AgentRequestEnd.key,
+    ]);
+  });
+
+  test('non-boundary event without an open span lands on root', ({ expect }) => {
+    const messages = collectTraceEvents(withMeta({ pid: 'orphan-pid' }, Trace.write(NoteEvent, {})));
+    const tree = buildSpanTree(messages);
+    expect(tree.children).toEqual([]);
+    expect(tree.events).toHaveLength(1);
+    expect(tree.events[0].type).toBe('note');
+  });
+
+  test('end event without a matching begin attaches to root', ({ expect }) => {
+    const messages = collectTraceEvents(
+      withMeta({ pid: 'op-1' }, Trace.write(Trace.OperationEnd, { key: 'reply', name: 'Reply', outcome: 'success' })),
+    );
+    const tree = buildSpanTree(messages);
+    expect(tree.children).toEqual([]);
+    expect(tree.events).toHaveLength(1);
+  });
+
+  test('sorts sibling spans chronologically by their first event', ({ expect }) => {
+    // Build events in chronological order, then reverse the message array before feeding
+    // into `buildSpanTree` to verify that the algorithm orders siblings by their first
+    // event's timestamp rather than by input order.
+    const messages = collectTraceEvents(
+      Effect.gen(function* () {
+        yield* withMeta(
+          { pid: 'op-early' },
+          Effect.gen(function* () {
+            yield* Trace.write(Trace.OperationStart, { key: 'a' });
+            yield* Trace.write(Trace.OperationEnd, { key: 'a', outcome: 'success' });
+          }),
+        );
+        yield* withMeta(
+          { pid: 'op-late' },
+          Effect.gen(function* () {
+            yield* Trace.write(Trace.OperationStart, { key: 'b' });
+            yield* Trace.write(Trace.OperationEnd, { key: 'b', outcome: 'success' });
+          }),
+        );
+      }),
+    );
+    const tree = buildSpanTree([...messages].reverse());
+    expect(tree.children.map((child) => child.meta.pid)).toEqual(['op-early', 'op-late']);
+  });
+
+  test('eventLimit drops oldest non-boundary events but always retains span boundaries', ({ expect }) => {
+    // Three non-boundary events (`note 1..3`), all boundary events should be kept regardless.
+    // With `eventLimit: 1`, only the most recent `note` should survive.
+    const messages = collectTraceEvents(
+      withMeta(
+        { pid: 'agent-1' },
+        Effect.gen(function* () {
+          yield* Trace.write(AgentRequestBegin, {});
+          yield* Trace.write(NoteEvent, { text: 'note 1' });
+          yield* Trace.write(NoteEvent, { text: 'note 2' });
+          yield* Trace.write(NoteEvent, { text: 'note 3' });
+          yield* Trace.write(AgentRequestEnd, { status: 'success' });
+        }),
+      ),
+    );
+    const tree = buildSpanTree(messages, { eventLimit: 1 });
+    expect(tree.children).toHaveLength(1);
+    const agentSpan = tree.children[0];
+    expect(agentSpan.events.map((event) => event.type)).toEqual([AgentRequestBegin.key, 'note', AgentRequestEnd.key]);
+    expect((agentSpan.events[1].data as { text: string }).text).toBe('note 3');
+  });
+
+  test('eventLimit preserves parent-child structure when the parent begin is older than the window', ({ expect }) => {
+    // Regression: previously `events.slice(-eventLimit)` would drop the parent's begin event
+    // when the limit fell mid-span, orphaning every child span onto root. The fix retains all
+    // boundary events so the parent stays open and children remain nested.
+    const messages = collectTraceEvents(
+      Effect.gen(function* () {
+        yield* withMeta(
+          { pid: 'parent-1' },
+          Effect.gen(function* () {
+            yield* Trace.write(AgentRequestBegin, {});
+            for (let index = 0; index < 20; index += 1) {
+              yield* Trace.write(NoteEvent, { index });
+            }
+          }),
+        );
+        yield* withMeta(
+          { pid: 'child-1', parentPid: 'parent-1' },
+          Effect.gen(function* () {
+            yield* Trace.write(Trace.OperationStart, { key: 'lookup', name: 'Lookup' });
+            yield* Trace.write(Trace.OperationEnd, { key: 'lookup', name: 'Lookup', outcome: 'success' });
+          }),
+        );
+        yield* withMeta({ pid: 'parent-1' }, Trace.write(AgentRequestEnd, { status: 'success' }));
+      }),
+    );
+    const tree = buildSpanTree(messages, {
+      // Limit far below the 20 `note` events — naive slicing would drop the parent's begin.
+      eventLimit: 2,
+    });
+    expect(tree.children).toHaveLength(1);
+    const parentSpan = tree.children[0];
+    expect(parentSpan.meta.pid).toBe('parent-1');
+    expect(parentSpan.children).toHaveLength(1);
+    expect(parentSpan.children[0].meta.pid).toBe('child-1');
+    expect(parentSpan.children[0].events.map((event) => event.type)).toEqual([
+      Trace.OperationStart.key,
+      Trace.OperationEnd.key,
+    ]);
+  });
+
+  test('flattenSpanTree returns root + all descendants in depth-first order', ({ expect }) => {
+    const messages = collectTraceEvents(
+      Effect.gen(function* () {
+        yield* withMeta({ pid: 'agent-1' }, Trace.write(AgentRequestBegin, {}));
+        yield* withMeta(
+          { pid: 'op-1', parentPid: 'agent-1' },
+          Effect.gen(function* () {
+            yield* Trace.write(Trace.OperationStart, { key: 'a' });
+            yield* Trace.write(Trace.OperationEnd, { key: 'a', outcome: 'success' });
+          }),
+        );
+        yield* withMeta({ pid: 'agent-1' }, Trace.write(AgentRequestEnd, { status: 'success' }));
+      }),
+    );
+    const tree = buildSpanTree(messages);
+    const order = flattenSpanTree(tree);
+    expect(order[0].id).toBe(ROOT_SPAN_ID);
+    expect(order[1].meta.pid).toBe('agent-1');
+    expect(order[2].meta.pid).toBe('op-1');
+    expect(order).toHaveLength(3);
+  });
+});

package/src/execution-graph/span-tree.ts

@@ -0,0 +1,269 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { AgentRequestBegin, AgentRequestEnd } from '@dxos/assistant';
+import { Trace } from '@dxos/compute';
+
+/**
+ * Synthetic id assigned to the root span.
+ * The root is a virtual container for top-level spans (those without a parent in the captured trace).
+ */
+export const ROOT_SPAN_ID = '<main>';
+
+/**
+ * Computed metadata for a span.
+ * Derived from the meta of the begin event that opened the span.
+ */
+export interface SpanMeta {
+  readonly pid?: string;
+  readonly parentPid?: string;
+  readonly processName?: string;
+  readonly conversationId?: string;
+  readonly triggerId?: string;
+  readonly toolCallId?: string;
+  readonly runtimeName?: string;
+}
+
+/**
+ * A span in the trace hierarchy.
+ *
+ * Each span represents a single bounded unit of work — an operation invocation or an
+ * agent request. Spans are opened by `OperationStart` / `AgentRequestBegin` events and
+ * closed by their matching `OperationEnd` / `AgentRequestEnd` events. A single process
+ * (pid) may produce multiple sequential spans (for example, an agent session that serves
+ * three prompts produces three sibling spans sharing the agent's pid).
+ *
+ * `events` contains the bounded events for this span only — child spans' events are not
+ * duplicated here. `children` contains sub-spans that opened while this span was active.
+ */
+export interface Span {
+  readonly id: string;
+  readonly meta: SpanMeta;
+  readonly events: Trace.FlatEvent[];
+  readonly children: Span[];
+}
+
+export const BEGIN_EVENT_TYPES = new Set<string>([Trace.OperationStart.key, AgentRequestBegin.key]);
+export const END_EVENT_TYPES = new Set<string>([Trace.OperationEnd.key, AgentRequestEnd.key]);
+
+export const isSpanBeginEvent = (event: Trace.FlatEvent): boolean => BEGIN_EVENT_TYPES.has(event.type);
+export const isSpanEndEvent = (event: Trace.FlatEvent): boolean => END_EVENT_TYPES.has(event.type);
+
+const computeMeta = (rawMeta: Trace.Meta): SpanMeta => ({
+  pid: rawMeta.pid,
+  parentPid: rawMeta.parentPid,
+  processName: rawMeta.processName,
+  conversationId: rawMeta.conversationId,
+  triggerId: rawMeta.triggerId,
+  toolCallId: rawMeta.toolCallId,
+  runtimeName: rawMeta.runtimeName,
+});
+
+interface MutableSpan {
+  id: string;
+  meta: SpanMeta;
+  events: Trace.FlatEvent[];
+  children: MutableSpan[];
+  firstTimestamp: number;
+}
+
+const makeMutableSpan = (id: string, meta: SpanMeta): MutableSpan => ({
+  id,
+  meta,
+  events: [],
+  children: [],
+  firstTimestamp: Number.POSITIVE_INFINITY,
+});
+
+const freezeSpan = (span: MutableSpan): Span => ({
+  id: span.id,
+  meta: span.meta,
+  events: span.events,
+  children: span.children.map(freezeSpan),
+});
+
+export interface BuildSpanTreeOptions {
+  /**
+   * If provided, caps how many *non-boundary* events (status updates, partial blocks, etc.)
+   * are retained — only the most recent `eventLimit` of them survive. Span boundary events
+   * (`OperationStart` / `OperationEnd` / `AgentRequestBegin` / `AgentRequestEnd`) are *always*
+   * retained regardless of the limit, because dropping them would orphan their child spans
+   * and collapse them onto the root branch.
+   */
+  eventLimit?: number;
+}
+
+/**
+ * Builds a hierarchical span tree from a list of trace messages.
+ *
+ * Algorithm:
+ *   1. Flatten messages into events and sort them chronologically.
+ *   2. For each event:
+ *      - Begin events (`OperationStart`, `AgentRequestBegin`) open a new span whose parent
+ *        is the currently-open span of the event's `meta.parentPid`, or the root if there is
+ *        none. The begin event itself becomes the first event of the new span.
+ *      - End events (`OperationEnd`, `AgentRequestEnd`) close the currently-open span for
+ *        the event's `meta.pid` and become its last event.
+ *      - Other events attach to the currently-open span for their `meta.pid`, or to the
+ *        root span if no span is currently open for that pid (or the event has no pid).
+ *   3. Sort each span's children by their earliest event timestamp.
+ */
+export const buildSpanTree = (messages: readonly Trace.Message[], options: BuildSpanTreeOptions = {}): Span => {
+  const allEvents = messages.flatMap((message) => Trace.flatten(message));
+  allEvents.sort((a, b) => a.timestamp - b.timestamp);
+
+  // The limit caps verbose middle events (status/partial-block) only. Span boundary events
+  // are always retained so the parent/child structure of older spans isn't dropped — losing a
+  // begin event detaches every descendant and collapses them onto the root branch.
+  const events = applyEventLimit(allEvents, options.eventLimit);
+
+  const root = makeMutableSpan(ROOT_SPAN_ID, {});
+
+  // Currently-open span for each pid.
+  // A process may host multiple sequential spans (e.g. successive agent requests), so we
+  // track the active one and start a new span on the next begin event.
+  const openSpans = new Map<string, MutableSpan>();
+
+  // Most-recent span for each pid, open OR already closed. Used as the parent fallback for a
+  // child process whose parent span has already ended — e.g. a delegated sub-agent runs
+  // concurrently and its begin event arrives after the supervisor's turn (its parent) closed.
+  // Without this the child would nest at the root and render on its own top-level lane, reusing
+  // a sibling's released lane instead of forking off its parent.
+  const lastSpanByPid = new Map<string, MutableSpan>();
+
+  let spanCounter = 0;
+  const allocSpanId = (pid: string): string => {
+    const id = `${pid}#${spanCounter}`;
+    spanCounter += 1;
+    return id;
+  };
+
+  const noteTimestamp = (span: MutableSpan, timestamp: number): void => {
+    if (timestamp < span.firstTimestamp) {
+      span.firstTimestamp = timestamp;
+    }
+  };
+
+  for (const event of events) {
+    const pid = event.meta.pid;
+
+    if (!pid) {
+      // Events without a pid attach to the root.
+      root.events.push(event);
+      noteTimestamp(root, event.timestamp);
+      continue;
+    }
+
+    if (BEGIN_EVENT_TYPES.has(event.type)) {
+      const parentPid = event.meta.parentPid;
+      // Prefer the parent's currently-open span; fall back to its most-recent (closed) span so a
+      // child process whose parent has already ended still nests under it (delegated sub-agents).
+      const parent = (parentPid && (openSpans.get(parentPid) ?? lastSpanByPid.get(parentPid))) || root;
+      const span = makeMutableSpan(allocSpanId(pid), computeMeta(event.meta));
+      span.events.push(event);
+      noteTimestamp(span, event.timestamp);
+      parent.children.push(span);
+      // The new span supersedes any previously-open span for this pid.
+      openSpans.set(pid, span);
+      lastSpanByPid.set(pid, span);
+      continue;
+    }
+
+    if (END_EVENT_TYPES.has(event.type)) {
+      const span = openSpans.get(pid);
+      if (span) {
+        span.events.push(event);
+        noteTimestamp(span, event.timestamp);
+        openSpans.delete(pid);
+      } else {
+        // End event without a matching begin — attach to root so the event isn't lost.
+        root.events.push(event);
+        noteTimestamp(root, event.timestamp);
+      }
+      continue;
+    }
+
+    // Non-boundary event: attach to the currently-open span for this pid if any.
+    const open = openSpans.get(pid);
+    if (open) {
+      open.events.push(event);
+      noteTimestamp(open, event.timestamp);
+    } else {
+      root.events.push(event);
+      noteTimestamp(root, event.timestamp);
+    }
+  }
+
+  // Sort children chronologically for deterministic output.
+  const sortChildren = (span: MutableSpan): void => {
+    span.children.sort((a, b) => a.firstTimestamp - b.firstTimestamp);
+    for (const child of span.children) {
+      sortChildren(child);
+    }
+  };
+  sortChildren(root);
+
+  return freezeSpan(root);
+};
+
+/**
+ * Caps the number of non-boundary events while retaining every span boundary event.
+ *
+ * Boundary events define the span tree's structure: dropping a begin event detaches every
+ * descendant span (its `parentPid` lookup fails, so children fall back to the root), and
+ * dropping an end event leaves a span open and corrupts the open-span map for sibling spans
+ * that share a pid. Status/partial-block events are the noisy bulk and the only ones the
+ * limit needs to control.
+ *
+ * The returned array stays in chronological order.
+ */
+const applyEventLimit = (events: readonly Trace.FlatEvent[], eventLimit: number | undefined): Trace.FlatEvent[] => {
+  if (eventLimit === undefined) {
+    return [...events];
+  }
+
+  let nonBoundaryCount = 0;
+  for (const event of events) {
+    if (!isBoundary(event)) {
+      nonBoundaryCount += 1;
+    }
+  }
+  if (nonBoundaryCount <= eventLimit) {
+    return [...events];
+  }
+
+  const dropCount = nonBoundaryCount - eventLimit;
+  let dropped = 0;
+  const result: Trace.FlatEvent[] = [];
+  for (const event of events) {
+    if (!isBoundary(event) && dropped < dropCount) {
+      dropped += 1;
+      continue;
+    }
+    result.push(event);
+  }
+  return result;
+};
+
+const isBoundary = (event: Trace.FlatEvent): boolean =>
+  BEGIN_EVENT_TYPES.has(event.type) || END_EVENT_TYPES.has(event.type);
+
+/**
+ * Walks the span tree in depth-first pre-order, invoking `visit` for each span (root included).
+ */
+export const walkSpanTree = (root: Span, visit: (span: Span, depth: number) => void, depth = 0): void => {
+  visit(root, depth);
+  for (const child of root.children) {
+    walkSpanTree(child, visit, depth + 1);
+  }
+};
+
+/**
+ * Returns all spans in the tree in depth-first pre-order, root first.
+ */
+export const flattenSpanTree = (root: Span): Span[] => {
+  const result: Span[] = [];
+  walkSpanTree(root, (span) => result.push(span));
+  return result;
+};