Skip to content

feat(trace): session lineage fields (parentRunId/parentSessionId/delegationDepth) + runs index - #2873

Merged
esokullu merged 1 commit into
webbrain-one:mainfrom
alectimison-maker:feat/trace-lineage-fields
Aug 21, 2026
Merged

feat(trace): session lineage fields (parentRunId/parentSessionId/delegationDepth) + runs index#2873
esokullu merged 1 commit into
webbrain-one:mainfrom
alectimison-maker:feat/trace-lineage-fields

Conversation

@alectimison-maker

Copy link
Copy Markdown
Contributor

Summary

  • New browser-neutral module trace/run-header.js (Chrome + Firefox): allowlisted normalization of parentRunId / parentSessionId / delegationDepth.
  • startRun stores the three lineage fields on every run record; delegationDepth resolves to an explicit value, else 1 for a run with a parent, else 0.
  • Trace DB schema v1 → v2: idempotent sessionId (over conversationId) and parentRunId indexes for future session-level aggregation. No data migration.

Motivation

Closes #2870.

WebBrain has natural fork scenarios with no data to support them: cloud runs (cloud-runs.js) and workflow replays (replaySavedWorkflow) produce independent runs, so "which browser run did this derived run come from" is unanswerable, and cost attribution cannot aggregate across a session and its derived runs. conversationId already groups sibling runs in the Traces UI; a parent chain extends that pattern to derived runs.

Design

  • conversationId stays the session identity — no new field name, avoiding three-way compatibility cost (UI / export / storage).
  • Three new fields: parentRunId, parentSessionId, delegationDepth (old runs default to null/0 and are untouched).
  • normalizeRunHeader() follows the existing runtime-config.js allowlist pattern: bounded string ids (≤200 chars, no control characters), bounded integer depth (0–64), trimmed. Nothing content-bearing can reach these fields.
  • effectiveDelegationDepth(): explicit depth wins; a run with a parent but no depth is a direct child (1); everything else is a root (0).
  • DB v2: DB_VERSION 1→2; onupgradeneeded creates the indexes idempotently (indexNames.contains guard). The sessionId index is keyed on conversationId (which IS the session identity) and carries the semantic name so session-level queries read naturally; IndexedDB skips records with null keys, so old runs are simply absent from the indexes. v1 data survives the upgrade byte-for-byte.

Testing

  • node test/run.js — passed, 1956 tests (4 new: normalization boundaries, depth resolution, mirror identity + browser-neutrality, recorder wiring)
  • node --check on every touched file — passed

Skipped: unpacked-browser manual verification (no browser session available in this environment). The IndexedDB upgrade path is covered by source-level idempotency assertions; runtime IDB behavior in Chrome and Firefox is not manually exercised.

Compatibility and risks

  • v1 databases upgrade in place: only two new indexes are added; existing stores, records, and keys are untouched. Old runs (null lineage fields) are excluded from the new indexes automatically.
  • The new fields are additive on the run record; existing readers (UI, exporters) ignore them.
  • Risk: naming the session index sessionId while the field is conversationId — deliberate, documented in code, matching the issue design.

Scope

Deliberately deferred: this PR is recorder-side support only. Plumbing parentRunId from the cloud-run and replay entry points is the next PR; session aggregation views/stats follow later.

@vercel

vercel Bot commented Aug 21, 2026

Copy link
Copy Markdown

@alectimison-maker is attempting to deploy a commit to the esokullu's projects Team on Vercel.

A member of the Team first needs to authorize it.

Runs gain parentRunId, parentSessionId, and delegationDepth, normalized
through a new browser-neutral run-header.js allowlist (bounded ids and
depth, content-free by construction). delegationDepth resolves
explicit value, else 1 for a run with a parent, else 0 for root runs.
conversationId remains the session identity — the v2 schema adds a
sessionId index over that field plus a parentRunId index for future
session-level aggregation, created idempotently during upgrade with no
data migration. Old v1 records stay untouched and fully readable.

Mirrored to Firefox. Closes webbrain-one#2870
@webbrain-one
webbrain-one force-pushed the feat/trace-lineage-fields branch from 94c01f4 to 4e72a8a Compare August 21, 2026 07:08
@esokullu
esokullu merged commit f0dc957 into webbrain-one:main Aug 21, 2026
1 of 2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

trace: session lineage fields (parentRunId/parentSessionId/delegationDepth) + runs index

2 participants