agent-tracegraph 0.7.0__tar.gz → 0.8.0__tar.gz

{agent_tracegraph-0.7.0 → agent_tracegraph-0.8.0}/CHANGELOG.md

@@ -6,6 +6,64 @@ The **artifact** schema version and the **report**/**review-candidate** JSON sch
 separate contracts from this version number; changes to any of them are called out
 explicitly.
 
+## 0.8.0 - 2026-10-20
+
+### Changed
+
+- **`analyze` and the incident memo say when a causal parent was chosen heuristically** (#138).
+  Ingest records `otlp.graph_parent_by_timing` (a loop parent taken by start time or, since #136,
+  by start number) or `otlp.graph_parent_fallback` (a declared graph parent not honored, so the
+  span parent is used) in the artifact, and `check` and `summarize` read those codes, but
+  `analyze` and `export-incident-memo` did not, so a report or memo built from the artifact did
+  not say that a parent may have been chosen heuristically, and the memo wrote a graph parent
+  taken by start order as "caused by". `analyze` now adds a warning for each side that
+  carries either code, and the memo adds a fidelity disclosure. The record does not say which
+  edge was chosen that way, so in a trace with `otlp.graph_parent_by_timing` the memo writes every
+  `graph_parent` edge in its causal ancestry graph as "preceded by (graph parent, possibly chosen heuristically)" instead of
+  "caused by"; checkpoint parents and span links keep "caused by". Reports and memos of traces
+  without these codes are unchanged.
+
+- **`explain`, `query --explain` and `inspect` say when a causal parent was chosen heuristically**
+  (#140). They read the same two codes: `inspect` prints the caveat `analyze` uses under its
+  tree, and `explain` and `query --explain` under every chain with at least one cause (a root
+  step has no parent to qualify). In such a trace their fan-in note no longer says "multiple real
+  causes" or "trust this raw chain, not the tree"; it says the single-parent tree drops some
+  recorded causes and the raw chain lists every recorded ancestor, and the `query --explain` note
+  says "in this chain" rather than "in this match", since the step with several causes can be an
+  ancestor outside the match. Output for traces without these codes is unchanged. `analyze` still
+  classifies failures through a `graph_parent` edge as it did.
+
+- **A Phoenix loop parent is chosen by start numbers whose unit is unknown again** (#136). Since
+  0.7.0 a Phoenix time given as a number below 10^17 is reported as unavailable, and with it the
+  only evidence for choosing among several spans that carry the `graph.node.id` a span names as
+  its `graph.node.parent_id`. The span then fell back to its `parent_id`, or the export was
+  refused without one. Now, when that span and every candidate start at such a number, the
+  nearest preceding candidate by those numbers is taken. 0.6.1 also chose by them, read as
+  nanoseconds, but it dropped a float's fraction first, so with fractional seconds (`a` at
+  1783987200.25, `b` at 1783987200.75, the span at 1783987200.5) it took `b` where this release
+  takes `a`. The times themselves stay unavailable. The choice is counted under the existing
+  `otlp.graph_parent_by_timing` gap with its own warning line, which says it assumes the export
+  gives every time in one unit; `check` treats it as a heuristic edge, as it does a choice by
+  readable time. Exports with ISO or nanosecond times are read as before, and so is a set of
+  candidates where any one has a readable time, no start, or no number below the floor. The
+  0.7.0 example (spans `a` and `b` at 1783987200 and 1783987201, `c` at 1783987202 with no
+  `parent_id`) is accepted again with `b` as `c`'s parent. Where 0.7.0 fell back to the span's
+  `parent_id`, the parent taken now can differ, and so can what follows from it. Each case below
+  is a separate export built from that example, adding only what it names:
+  - The export can be refused if the new choice closes a causal cycle. Add a root span `r` at
+    1783987199 and give `c` the `parent_id` `r` and `b` the `parent_id` `c`: 0.7.0 kept `r` as
+    `c`'s parent and exited 0; this release takes `b`, so `ingest-phoenix` and `analyze` exit 2
+    and `phoenix diagnose` exits 1 (0.6.1 refused that export too).
+  - `analyze` can classify failures differently, because the edge is now a `graph_parent`, which
+    it reads as explicit ancestry (#142). Give `c` the `parent_id` `b` and let `b` and `c` fail:
+    0.7.0 reported both as primary failures; this release reports `b` as primary and `c` as
+    propagated.
+  - Step numbers can change. Add spans `x`, `y` (`parent_id` `x`) and `z` with no start time,
+    and give `b` the `parent_id` `y` and `c` the `parent_id` `z`: 0.7.0 numbered `c` 3 and `b` 5;
+    this release numbers `b` 4 and `c` 5.
+
+  Ties are still broken with these spans at time 0, so step order can also differ from 0.6.1.
+
 ## 0.7.0 - 2026-10-20
 
 ### Added

{agent_tracegraph-0.7.0 → agent_tracegraph-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-tracegraph
-Version: 0.7.0
+Version: 0.8.0
 Summary: Time-travel debugging and causal RCA for LangGraph agent traces, on a causal graph.
 Project-URL: Homepage, https://github.com/memtomem/tracegraph
 Project-URL: Repository, https://github.com/memtomem/tracegraph
@@ -38,7 +38,7 @@ tracegraph ingests agent execution traces that already exist (LangGraph checkpoi
 Phoenix CLI exports, and OpenInference/OTLP spans) into a **normalized causal graph**,
 then runs analyses the mainstream observability tools don't:
 
-- **`explain`** — walk backward from a failure over the *raw* causal graph to every real cause.
+- **`explain`** — walk backward from a failure over the *raw* causal graph to every recorded cause.
 - **`diff`** — exact structural regression diff between two runs (rooted-tree / AHU isomorphism).
 - **cross-trace pattern matching** — e.g. "tool X → retry → tool X → failure" across all runs.
 
@@ -221,6 +221,15 @@ Phoenix exports preserve span parents but currently do not expose the original O
 links. These artifacts are explicitly marked `causal_fidelity=parent_only`; tracegraph warns
 that additional fan-in causes may be missing instead of claiming a complete DAG.
 
+Phoenix's own export gives times as ISO strings. A time given as a number is read as epoch
+nanoseconds only from 10^17 up; a smaller one (seconds, milliseconds, a relative offset) is in
+a unit tracegraph cannot tell, so it is reported as unavailable and disclosed as
+`otlp.unreadable_timestamp`. Such numbers still order spans for one purpose: when several
+spans carry the `graph.node.id` that a span names as its `graph.node.parent_id`, and that span
+and every candidate start at such a number, the nearest preceding candidate by those numbers is
+the parent. That assumes the export gives every time in one unit, and it is disclosed under
+`otlp.graph_parent_by_timing` with its own warning line, so `check` treats the edge as heuristic.
+
 The exact Phoenix CLI and server versions used by CI are centrally pinned. See the
 [Phoenix runtime pin maintenance runbook](docs/phoenix-cli-contract.md) for the controlled
 upgrade and contract-verification procedure, and the
@@ -456,6 +465,14 @@ origins, fidelity disclosures, and the digest of the exact artifact bytes. Logic
 comparison keys are JSON-encoded typed paths; consumers should treat them as opaque strings.
 Containment and unknown edges preserve all error investigation candidates, deeper first.
 Explicit causal ancestry supplies context, not proof that an exception propagated.
+When the artifact records that a causal parent was chosen heuristically at ingest
+(`otlp.graph_parent_by_timing` or `otlp.graph_parent_fallback`), `analyze` adds a warning for
+that side and the memo a fidelity disclosure. The record does not say which edge, so a memo of
+a trace with `otlp.graph_parent_by_timing` writes every `graph_parent` edge as "preceded by
+(graph parent, possibly chosen heuristically)" instead of "caused by". `inspect` prints the
+same caveat under its tree, and `explain` and `query --explain` under every chain that has at
+least one cause; there their fan-in note no longer calls the causes real or says to trust the
+chain.
 Explicit OTLP OK takes precedence over handled exception events on new ingestion; old
 artifacts are not reinterpreted.
 A span whose status is UNSET and that carries no exception event (one with a message or

{agent_tracegraph-0.7.0 → agent_tracegraph-0.8.0}/README.md

@@ -7,7 +7,7 @@ tracegraph ingests agent execution traces that already exist (LangGraph checkpoi
 Phoenix CLI exports, and OpenInference/OTLP spans) into a **normalized causal graph**,
 then runs analyses the mainstream observability tools don't:
 
-- **`explain`** — walk backward from a failure over the *raw* causal graph to every real cause.
+- **`explain`** — walk backward from a failure over the *raw* causal graph to every recorded cause.
 - **`diff`** — exact structural regression diff between two runs (rooted-tree / AHU isomorphism).
 - **cross-trace pattern matching** — e.g. "tool X → retry → tool X → failure" across all runs.
 
@@ -190,6 +190,15 @@ Phoenix exports preserve span parents but currently do not expose the original O
 links. These artifacts are explicitly marked `causal_fidelity=parent_only`; tracegraph warns
 that additional fan-in causes may be missing instead of claiming a complete DAG.
 
+Phoenix's own export gives times as ISO strings. A time given as a number is read as epoch
+nanoseconds only from 10^17 up; a smaller one (seconds, milliseconds, a relative offset) is in
+a unit tracegraph cannot tell, so it is reported as unavailable and disclosed as
+`otlp.unreadable_timestamp`. Such numbers still order spans for one purpose: when several
+spans carry the `graph.node.id` that a span names as its `graph.node.parent_id`, and that span
+and every candidate start at such a number, the nearest preceding candidate by those numbers is
+the parent. That assumes the export gives every time in one unit, and it is disclosed under
+`otlp.graph_parent_by_timing` with its own warning line, so `check` treats the edge as heuristic.
+
 The exact Phoenix CLI and server versions used by CI are centrally pinned. See the
 [Phoenix runtime pin maintenance runbook](docs/phoenix-cli-contract.md) for the controlled
 upgrade and contract-verification procedure, and the
@@ -425,6 +434,14 @@ origins, fidelity disclosures, and the digest of the exact artifact bytes. Logic
 comparison keys are JSON-encoded typed paths; consumers should treat them as opaque strings.
 Containment and unknown edges preserve all error investigation candidates, deeper first.
 Explicit causal ancestry supplies context, not proof that an exception propagated.
+When the artifact records that a causal parent was chosen heuristically at ingest
+(`otlp.graph_parent_by_timing` or `otlp.graph_parent_fallback`), `analyze` adds a warning for
+that side and the memo a fidelity disclosure. The record does not say which edge, so a memo of
+a trace with `otlp.graph_parent_by_timing` writes every `graph_parent` edge as "preceded by
+(graph parent, possibly chosen heuristically)" instead of "caused by". `inspect` prints the
+same caveat under its tree, and `explain` and `query --explain` under every chain that has at
+least one cause; there their fan-in note no longer calls the causes real or says to trust the
+chain.
 Explicit OTLP OK takes precedence over handled exception events on new ingestion; old
 artifacts are not reinterpreted.
 A span whose status is UNSET and that carries no exception event (one with a message or

{agent_tracegraph-0.7.0 → agent_tracegraph-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@
 # the schema `kind` constants and the TRACEGRAPH_* environment variables — those are package
 # identity, not distribution identity, and renaming them would break published contracts.
 name = "agent-tracegraph"
-version = "0.7.0"
+version = "0.8.0"
 description = "Time-travel debugging and causal RCA for LangGraph agent traces, on a causal graph."
 readme = "README.md"
 requires-python = ">=3.12"

{agent_tracegraph-0.7.0 → agent_tracegraph-0.8.0}/src/tracegraph/adapters/otlp_spans.py

@@ -376,11 +376,16 @@ class OTLPSpanAdapter:
         causal_fidelity: CausalFidelity | None = None,
         links_preserved: bool | None = None,
         evaluation_channel: str | None = None,
+        start_order_channel: str | None = None,
     ) -> None:
         self._doc = document
         #: Span key carrying pre-sanitized evaluation summaries. Only an adapter that builds
         #: the span dicts itself (Phoenix) sets it; raw OTLP input never supplies evaluations.
         self._evaluation_channel = evaluation_channel
+        #: Span key carrying a start time whose unit is unknown, as a plain number that orders
+        #: spans within one export. Only Phoenix sets it, for a number below the epoch-nanosecond
+        #: floor; the time itself stays unavailable.
+        self._start_order_channel = start_order_channel
         self._source_kind = source_kind
         #: Prefer ``graph.node.parent_id`` (logical agent graph) over ``parentSpanId``.
         self._prefer_graph_parent = prefer_graph_parent
@@ -462,8 +467,18 @@ class OTLPSpanAdapter:
             for sid, span in by_id.items()
             if _parse_nanos(_first(span, "startTimeUnixNano", "start_time_unix_nano")) is None
         }
+        # A unit-unknown start number orders spans that all carry one, with prerank's
+        # tiebreaks; it says nothing about how they relate to a span with a readable time.
+        channel = self._start_order_channel
+        order_key = {
+            sid: (value, depth[sid], sid)
+            for sid, span in by_id.items()
+            if channel is not None and (value := span.get(channel)) is not None
+        }
         disclosures = Disclosures()
-        causes, origins = self._causes(by_id, attrs, prerank, parent_span, untimed, disclosures)
+        causes, origins = self._causes(
+            by_id, attrs, prerank, parent_span, untimed, order_key, disclosures
+        )
         seq = self._topo_seq(by_id, causes, prerank)
 
         steps: list[Step] = []
@@ -725,6 +740,7 @@ class OTLPSpanAdapter:
         prerank: dict[str, int],
         parent_span: dict[str, str | None],
         untimed: set[str],
+        order_key: dict[str, tuple[Any, int, str]],
         disclosures: Disclosures,
     ) -> tuple[dict[str, list[str]], dict[tuple[str, str], EdgeOrigin]]:
         """Reconstruct ``effect -> [causes]`` from declared signals: one parent + links.
@@ -752,12 +768,13 @@ class OTLPSpanAdapter:
             causes[effect].append(cause)
             origins[(effect, cause)] = origin
 
-        by_timing = fallback = 0
+        by_timing = by_order = fallback = 0
         for sid in by_id:
             parent, parent_origin, resolution = self._resolve_parent(
-                sid, attrs, node_index, prerank, parent_span, untimed
+                sid, attrs, node_index, prerank, parent_span, untimed, order_key
             )
             by_timing += resolution == "by_timing"
+            by_order += resolution == "by_order"
             fallback += resolution == "fallback"
             if parent is not None:
                 add(sid, parent, parent_origin)
@@ -789,6 +806,16 @@ class OTLPSpanAdapter:
                 "the nearest preceding one by start time was taken as the parent.",
                 by_timing,
             )
+        if by_order:
+            # Same code as by_timing: a heuristic choice among candidates, which readers since
+            # 0.6 already treat as one.
+            disclosures.add(
+                "otlp.graph_parent_by_timing",
+                f"{by_order} span(s) declare a graph.node.parent_id that several spans carry; "
+                "the nearest preceding one was taken by start-time numbers whose unit is "
+                "unknown, assuming the export gives every time in one unit.",
+                by_order,
+            )
         if fallback:
             disclosures.add(
                 "otlp.graph_parent_fallback",
@@ -826,6 +853,7 @@ class OTLPSpanAdapter:
         prerank: dict[str, int],
         parent_span: dict[str, str | None],
         untimed: set[str],
+        order_key: dict[str, tuple[Any, int, str]],
     ) -> tuple[str | None, EdgeOrigin, str | None]:
         """The single chosen parent cause: the logical graph parent if resolvable, else the
         declared span parent.
@@ -835,7 +863,8 @@ class OTLPSpanAdapter:
 
         * a single span carries that ``graph.node.id`` → trust it outright (unambiguous);
         * several do (a loop) → pick the nearest *preceding* execution, but only when this
-          span and every candidate have a readable start time; otherwise there is no
+          span and every candidate have a readable start time, or else all carry a
+          unit-unknown start number (``order_key``) to compare; otherwise there is no
           evidence of order and the parent is ambiguous.
 
         If ``graph.node.parent_id`` is declared but resolves to no in-trace span, or is
@@ -846,7 +875,7 @@ class OTLPSpanAdapter:
         ``None`` only when the span truly has no declared parent of either kind.
 
         The third value says how a declared logical parent was resolved when that was not
-        unambiguous: ``"by_timing"`` or ``"fallback"``; otherwise ``None``.
+        unambiguous: ``"by_timing"``, ``"by_order"`` or ``"fallback"``; otherwise ``None``.
         """
         pid = parent_span.get(sid)
         if self._prefer_graph_parent:
@@ -859,6 +888,10 @@ class OTLPSpanAdapter:
                 preceding = [c for c in candidates if timed and prerank[c] < prerank[sid]]
                 if preceding:
                     return max(preceding, key=lambda c: prerank[c]), EdgeOrigin.GRAPH_PARENT, "by_timing"
+                ordered = not timed and all(s in order_key for s in (sid, *candidates))
+                preceding = [c for c in candidates if ordered and order_key[c] < order_key[sid]]
+                if preceding:
+                    return max(preceding, key=lambda c: order_key[c]), EdgeOrigin.GRAPH_PARENT, "by_order"
                 if pid is None:
                     detail = "no in-trace span" if not candidates else "multiple ambiguous spans"
                     raise ValueError(

{agent_tracegraph-0.7.0 → agent_tracegraph-0.8.0}/src/tracegraph/adapters/phoenix_export.py

@@ -79,6 +79,38 @@ def _nanos(value: Any) -> Any:
     return str(int(parsed.timestamp() * 1_000_000_000))
 
 
+def _start_order(value: Any) -> int | float | None:
+    """A start time below the epoch-nanosecond floor, as the number it is, or ``None``.
+
+    Its unit is unknown, so it is no time, but within one export it still orders spans: the
+    span builder uses it only to choose among several candidate loop parents, and discloses
+    that it did. It follows ``_nanos``'s branches, so an ISO string (a compact one such as
+    ``20260714_123456`` included) never reaches the number path. A bool or bytes value is not
+    taken as a number here, although ``_nanos`` refuses those as times too.
+    """
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, float):
+        return value if math.isfinite(value) and int(value) < _MIN_EPOCH_NANOS else None
+    if isinstance(value, int):
+        return value if value < _MIN_EPOCH_NANOS else None
+    if not isinstance(value, str):
+        return None
+    number: int | None
+    if value.isdigit():
+        try:
+            number = int(value)
+        except ValueError:  # a non-ASCII digit, or past the interpreter's int-string limit
+            return None
+    else:
+        try:
+            datetime.fromisoformat(value.replace("Z", "+00:00"))
+            return None
+        except ValueError:
+            number = _parse_nanos(value)
+    return number if number is not None and number < _MIN_EPOCH_NANOS else None
+
+
 _OPERATION_NAME = re.compile(r"[A-Za-z0-9_.:/#@-]{1,200}")
 
 
@@ -202,6 +234,7 @@ class PhoenixExportAdapter:
             include_error_messages=False,
             preserve_unset_status=True,
             evaluation_channel="_tracegraph_evaluations",
+            start_order_channel="_tracegraph_start_order",
         ).ingest(trace_id)
         if unreadable_scores:
             disclosures = Disclosures()
@@ -257,4 +290,5 @@ class PhoenixExportAdapter:
             "attributes": _attrs(span),
             "events": _span_array(span, "events"),
             "_tracegraph_evaluations": _evaluations(span),
+            "_tracegraph_start_order": _start_order(_first(span, "start_time", "startTime")),
         }

{agent_tracegraph-0.7.0 → agent_tracegraph-0.8.0}/src/tracegraph/analysis/check.py

@@ -34,6 +34,7 @@ from tracegraph.analysis.diagnose import _ALIAS, _digest, _display_name, _safe
 from tracegraph.analysis.patterns import PRESETS, PathPattern, StepPredicate, build_index, find_matches
 from tracegraph.model import (
     CAPTURE_GAP_CODES,
+    HEURISTIC_EDGE_GAP_CODES,
     NormalizedTrace,
     Step,
     StepStatus,
@@ -66,7 +67,7 @@ _MAY_OMIT_STEPS = frozenset({
 #: is unaffected, so only the count rules read this set.
 _REWRITTEN_ERRORS = frozenset({"langgraph.rewritten_error_channel"})
 _MAY_HIDE_FAILURES = _MAY_OMIT_STEPS | _REWRITTEN_ERRORS
-_HEURISTIC_EDGES = frozenset({"otlp.graph_parent_by_timing", "otlp.graph_parent_fallback"})
+_HEURISTIC_EDGES = HEURISTIC_EDGE_GAP_CODES
 
 LANGGRAPH_LIMITATION = (
     "LangGraph checkpoint layouts this adapter does not recognize record no failure, so a "

{agent_tracegraph-0.7.0 → agent_tracegraph-0.8.0}/src/tracegraph/analysis/diagnose.py

@@ -29,6 +29,7 @@ from tracegraph.model import (
     EXPLICIT_ORIGINS,
     MAX_COST_CHARS,
     CausalFidelity,
+    HEURISTIC_EDGE_GAP_CODES,
     EdgeType,
     NormalizedTrace,
     Step,
@@ -54,6 +55,16 @@ LANGGRAPH_FIDELITY_WARNING = (
 LINKS_PRESERVED_FIDELITY_WARNING = (
     "Link preservation covers valid in-trace links only; foreign or unresolved links are omitted."
 )
+HEURISTIC_PARENT_FIDELITY_WARNING = (
+    "Some causal parents were chosen heuristically at ingest, by start order or by falling back "
+    "to the span parent; a chain through them is inferred, not declared."
+)
+
+
+def has_heuristic_edges(nt: NormalizedTrace) -> bool:
+    """Whether the trace's capture record discloses a causal parent chosen heuristically."""
+    capture = nt.trace.capture
+    return capture is not None and any(gap.code in HEURISTIC_EDGE_GAP_CODES for gap in capture.gaps)
 
 
 def _clause(sentence: str) -> str:
@@ -677,6 +688,8 @@ def analyze(nt: NormalizedTrace, *, baseline: NormalizedTrace | None = None) ->
         if trace.trace.links_preserved:
             # Mid-sentence after the label, so the shared sentence starts in lower case here.
             warnings.append(f"{label}: {_clause(LINKS_PRESERVED_FIDELITY_WARNING)}")
+        if has_heuristic_edges(trace):
+            warnings.append(f"{label}: {_clause(HEURISTIC_PARENT_FIDELITY_WARNING)}")
     if primary or propagated:
         warnings.append(INCIDENT_FIDELITY_WARNING)
     if any(getattr(metrics, field) is not None for field in ("prompt_tokens", "completion_tokens", "total_tokens", "total_cost")):

{agent_tracegraph-0.7.0 → agent_tracegraph-0.8.0}/src/tracegraph/analysis/memo.py

@@ -7,10 +7,12 @@ from pathlib import Path
 
 from tracegraph._atomic_write import write_text_atomic
 from tracegraph.analysis.diagnose import (
+    HEURISTIC_PARENT_FIDELITY_WARNING,
     INCIDENT_FIDELITY_WARNING,
     LANGGRAPH_FIDELITY_WARNING,
     LINKS_PRESERVED_FIDELITY_WARNING,
     PARENT_ONLY_FIDELITY_WARNING,
+    has_heuristic_edges,
     pattern_findings,
 )
 from tracegraph.model import (
@@ -43,7 +45,11 @@ def _format_origin(origin: EdgeOrigin | None) -> str:
     return f"origin: {origin.value}"
 
 
-def _relation_phrase(origin: EdgeOrigin | None) -> str:
+def _relation_phrase(origin: EdgeOrigin | None, *, timed_graph_parents: bool) -> str:
+    # The capture record says a graph parent was chosen by start order somewhere in the trace,
+    # not which one, so no graph-parent edge there is presented as a declared cause.
+    if origin is EdgeOrigin.GRAPH_PARENT and timed_graph_parents:
+        return "preceded by (graph parent, possibly chosen heuristically)"
     if origin in EXPLICIT_ORIGINS:
         return "caused by"
     if origin is EdgeOrigin.SPAN_PARENT_FALLBACK:
@@ -161,12 +167,16 @@ def build_incident_memo(
             if edge.src in reachable_step_ids
         ]
 
+        capture = nt.trace.capture
+        timed_graph_parents = capture is not None and any(
+            gap.code == "otlp.graph_parent_by_timing" for gap in capture.gaps
+        )
         if ancestry_edges:
             lines.append("### Causal Ancestry Graph")
             for edge in ancestry_edges:
                 eff_alias = alias_by_id[edge.src]
                 cause_alias = alias_by_id[edge.dst]
-                rel = _relation_phrase(edge.origin)
+                rel = _relation_phrase(edge.origin, timed_graph_parents=timed_graph_parents)
                 origin_str = f" [{_format_origin(edge.origin)}]"
                 lines.append(f"- `{eff_alias}` {rel} `{cause_alias}`{origin_str}")
             lines.append("")
@@ -182,6 +192,8 @@ def build_incident_memo(
         disclosures.append(LANGGRAPH_FIDELITY_WARNING)
     if nt.trace.links_preserved:
         disclosures.append(LINKS_PRESERVED_FIDELITY_WARNING)
+    if has_heuristic_edges(nt):
+        disclosures.append(HEURISTIC_PARENT_FIDELITY_WARNING)
 
     lines.append("## Fidelity Disclosures")
     for d in disclosures:

{agent_tracegraph-0.7.0 → agent_tracegraph-0.8.0}/src/tracegraph/cli.py

@@ -33,7 +33,8 @@ from tracegraph import artifact
 from tracegraph.input_validation import loads as load_json
 from tracegraph.analysis import PRESETS
 from tracegraph.analysis import check as regression_check
-from tracegraph.analysis.diagnose import AnalysisReport
+from tracegraph.analysis.diagnose import HEURISTIC_PARENT_FIDELITY_WARNING, AnalysisReport
+from tracegraph.analysis.diagnose import has_heuristic_edges
 from tracegraph.analysis.diagnose import analyze as build_analysis
 from tracegraph.analysis.diagnose import save_atomic as save_analysis_report
 from tracegraph.analysis import motifs
@@ -1278,6 +1279,10 @@ def _render_tree(nt: NormalizedTrace) -> None:
         f"\n[dim]{len(nt.steps)} steps · {n_tool} tool · "
         f"{n_err} error · {n_lossy} lossy-projection{paused}{scheduled}[/]"
     )
+    # The tree projects CAUSED_BY, so a heuristic parent can place a step whether or not
+    # any step is lossy.
+    if has_heuristic_edges(nt):
+        console.print(f"[yellow]⚠ {HEURISTIC_PARENT_FIDELITY_WARNING}[/]")
 
 
 _REDACT_ERRORS_HELP = (
@@ -1626,7 +1631,9 @@ def explain(
     """Trace a step's raw causal chain back toward its root cause."""
     store = _store_from_artifact(artifact_path, backend)
     try:
-        steps = store.trace().steps_by_id()
+        trace = store.trace()
+        steps = trace.steps_by_id()
+        heuristic = has_heuristic_edges(trace)
         # An exact full-id match always wins — even when that id is also a *suffix* of a longer
         # namespaced id (e.g. "abc" vs "ns:abc"). Only fall back to suffix matching when the
         # input isn't itself a full step id, so a valid id is never rejected as "ambiguous".
@@ -1651,11 +1658,20 @@ def explain(
     for s in result.chain:
         flag = " [yellow]⚠ projection-lossy[/]" if s.projection_lossy else ""
         console.print(f"  ← {escape(s.name or s.kind.value)} (step {s.seq}){flag}")
-    if result.is_lossy:
+    # Where the capture record says a parent may have been chosen heuristically, the chain is
+    # not called real or trustworthy; elsewhere the wording is unchanged.
+    if result.is_lossy and heuristic:
+        console.print(
+            "\n[yellow]Some steps had more than one recorded cause; the single-parent tree view "
+            "drops some of them, and this raw chain lists every recorded ancestor.[/]"
+        )
+    elif result.is_lossy:
         console.print(
             "\n[yellow]Some steps had multiple real causes; the single-parent tree view "
             "is lossy for them — trust this raw chain, not the tree.[/]"
         )
+    if heuristic and result.chain:
+        console.print(f"\n[yellow]⚠ {HEURISTIC_PARENT_FIDELITY_WARNING}[/]")
 
 
 @app.command()
@@ -1786,16 +1802,26 @@ def query(
                     # Same fallback label as `tracegraph explain` and the tree renderers.
                     console.print(f"    ← {escape(s.name or s.kind.value)} (step {s.seq}){flag}")
                 # Causal-honesty signal: when the matched effect (or anything in the chain)
-                # has more than one real cause, the single-parent tree projection dropped
+                # has more than one recorded cause, the single-parent tree projection dropped
                 # at least one. `tracegraph explain` surfaces this same warning — `query
                 # --explain` must too, or a fan-in effect's lossiness becomes invisible
                 # (target lossiness doesn't show up in the per-step ⚠ flags above, since
                 # we only flag chain ancestors there).
-                if result.is_lossy:
+                # A lossy step can be an ancestor outside the matched path, hence "chain".
+                heuristic = has_heuristic_edges(traces_by_id[m.trace_id])
+                if result.is_lossy and heuristic:
+                    console.print(
+                        "    [yellow]⚠ some steps in this chain had more than one recorded cause — "
+                        "the single-parent tree drops some of them; this raw chain lists every "
+                        "recorded ancestor.[/]"
+                    )
+                elif result.is_lossy:
                     console.print(
                         "    [yellow]⚠ some steps in this match had multiple real causes — "
                         "trust this raw chain, not the tree.[/]"
                     )
+                if heuristic and result.chain:
+                    console.print(f"    [yellow]⚠ {HEURISTIC_PARENT_FIDELITY_WARNING}[/]")
 
         n_traces = len({m.trace_id for m in matches})
         suffix = f" — truncated from {total}" if truncated else ""

{agent_tracegraph-0.7.0 → agent_tracegraph-0.8.0}/src/tracegraph/model.py

@@ -284,6 +284,10 @@ CAPTURE_GAP_CODES = frozenset(
         "phoenix.unreadable_evaluation_score",
     }
 )
+#: The gaps that say a causal parent was chosen heuristically at ingest: among several spans by
+#: start order, or by falling back to the span parent. ``check``, ``summarize``, ``analyze`` and the
+#: incident memo read this set.
+HEURISTIC_EDGE_GAP_CODES = frozenset({"otlp.graph_parent_by_timing", "otlp.graph_parent_fallback"})
 
 
 class CaptureGap(BaseModel):