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

{agent_tracegraph-0.7.0 → agent_tracegraph-0.9.0}/.gitignore

@@ -12,3 +12,7 @@ wheels/
 # Local Codex/dev-trio review artifacts (logs, manifests, run metadata).
 .dev-trio/
 .DS_Store
+
+# memtomem local artifacts (ADR-0011 project_local tier)
+.memtomem/*.local/
+.memtomem/.staging/

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

@@ -6,6 +6,264 @@ 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.9.0 - 2026-10-24
+
+### Changed
+
+- **JSON nested more than 9000 levels deep is refused on every Python version** (#167). Whether
+  deep input was refused depended on the interpreter: 3.12 and 3.13's `json` refuse at about
+  10,000 levels less the C frames already on the stack (9,984 through the CLI), while 3.14's
+  parses far deeper, so 3.14 accepted input that 3.12 refused. `input_validation.MAX_JSON_DEPTH`
+  (9000) is now checked on the text before it is parsed, wherever tracegraph parses JSON:
+  artifacts, OTLP JSON and JSONL, Phoenix exports and `px` output. It counts the text rather
+  than the parsed value, so a deep value that a later duplicate key overwrites still counts, and
+  brackets inside strings do not. `ingest --sqlite` checks each checkpoint's metadata, each
+  checkpoint body stored as JSON, and each JSON write the saver reads in the same way, before
+  decoding, and refuses with `checkpoint history cannot be decoded (JSON nesting too deep)`. The
+  scan counts against the snapshot `timeout`. The message for text input is unchanged,
+  `JSON nesting too deep`. On 3.12 and 3.13 this newly refuses nesting from 9001 levels up to
+  their own limit; on 3.14 it refuses everything above 9000. Objects already decoded by the
+  caller (`artifact.from_obj`, the adapter constructors, a caller-supplied checkpoint saver) are
+  not checked (#168). The scan adds about 2.4 s to `ingest-otlp` on a 120 MB input dense with
+  brackets and quotes (3.5 s before); the artifact is byte-identical.
+- **The Phoenix + SyncMill E2E runs against Phoenix server 20.24.0** (#129), pinned by its index
+  digest in `contracts/phoenix-runtime.json`; it was 18.0.0. The body-free evidence (diagnosis
+  `tool-retry-failure@v2`, the diff, one review candidate and the board import) is the same under
+  both servers once run-specific ids and timings are masked. The Phoenix CLI pin stays 1.18.8.
+- **CI runs the suite on Python 3.13 and 3.14** (#128), which `requires-python = ">=3.12"` already
+  allowed, and the package now lists both classifiers. A new `full suite (Python 3.13|3.14)` job
+  runs the `[cypher]` suite on each; the existing jobs and their names are unchanged and stay on
+  3.12. Both versions failed before: a test docstring with a lone-surrogate escape does not compile
+  on 3.13 and later, and Python 3.14's `json` parses nesting that earlier versions refuse with
+  `RecursionError`; the explicit nesting cap above makes every version refuse the same input.
+- **`analyze` and `export-incident-memo` show recorded task markers** (#127). A run paused by
+  `interrupt()` or stopped by the recursion limit has trace status `ok` unless a step failed,
+  because the status reports whether a recorded step failed; `inspect` marked the recorded ones
+  (a recursion stop has a marker only when ingest is given the graph), but `analyze` and the
+  memo said nothing. When a trace records any, `analyze` adds the warning `<label>: recorded
+  task markers: 1 interrupted · 1 scheduled · 1 undecided interrupt; trace status reports
+  whether a recorded step failed, not whether the run completed.` (non-zero parts only, for the
+  current trace and the baseline), and the memo adds a `Recorded Task Markers` line after Trace
+  Status. `undecided interrupt` counts the `langgraph.undecided_interrupt` capture gap. The
+  markers are records, not completion: see README. This change leaves the artifact, its schema
+  version, the trace status and the report schema as they were, and adds nothing to a report or
+  memo of a trace without markers.
+- **`ReviewCandidateReport` and `ReviewCandidate` drop fields they do not know** (#126). Both
+  kept them, so reading a review-candidate document that carried, say, a `prompt` or `error_msg`
+  and writing it back with `dumps` passed the text through. They now discard unknown fields at
+  both levels, as the SyncMill and Toolgraph readers do, and a `ValidationError` from either model
+  no longer prints the rejected input; `errors()` still includes it unless called with
+  `include_input=False`. From the same artifacts, `export-review-candidates` writes the same
+  output; re-ingesting a source can change the artifact, and with it each candidate's
+  `artifact_digest`. The contract schema stays at version 1 and still allows additional fields.
+  When `build_report` builds a candidate that fails model validation, it still raises
+  `ValidationError`, now titled with that candidate's trace, since the rejected value is no
+  longer shown.
+- **A LangGraph subgraph return is recorded on its edge** (#150). When the parent graph continues
+  after a subgraph, LangGraph declares the checkpoint that launched the subgraph as the
+  continuation's parent, and ingest links the continuation to a subgraph checkpoint instead. That
+  edge used to say `checkpoint_parent`, like a parent LangGraph declared. It now has origin
+  `checkpoint_subgraph_return`. `analyze` still counts it as explicit ancestry and the derived
+  tree ranks it as a declared checkpoint parent, so the new origin by itself changes neither
+  classification nor the tree (the return-edge entries under Fixed can);
+  the memo prints the new origin, and `summarize` groups it apart from a declared checkpoint
+  parent.
+- **Artifact schema 9.** An artifact with a `checkpoint_subgraph_return` edge declares
+  `schema_version` 9, so 0.8.0 and earlier refuse it by version instead of failing on the new
+  origin value. An artifact written by 0.8.0 keeps its version and bytes when it is loaded and
+  saved again, and its return edges still say `checkpoint_parent`; a schema 1 artifact is still
+  migrated when it is loaded.
+  This entry changes nothing else in a fresh ingest; the OTLP and LangGraph entries in this release
+  can.
+- **`explain` and `query --explain` describe fan-in as "more than one recorded cause" for every
+  lossy chain** (#143). A trace without a heuristic-parent disclosure used to print "multiple real
+  causes … trust this raw chain, not the tree", and `query --explain` said the lossy step was "in
+  this match" although it can be an ancestor outside the match. Both now print the wording that
+  traces with `otlp.graph_parent_by_timing` or `otlp.graph_parent_fallback` have printed since
+  0.8.0, because a recorded cause may have been reconstructed by the adapter without a mark. The
+  heuristic-parent caveat itself is unchanged and still appears only for those traces.
+- **A loop parent chosen by start order is recorded on its edge, and `analyze` no longer treats
+  it as declared ancestry** (#142). When several spans carry the `graph.node.id` a span names as
+  its `graph.node.parent_id`, OTLP and Phoenix ingest take the nearest preceding one by start
+  time or start number. That edge used to say `graph_parent`, like a parent with one candidate,
+  so a failing loop run that happened to be picked made the child's failure "propagated" instead
+  of primary. The edge now has origin `graph_parent_heuristic`: `analyze` splits primary and
+  propagated failures only through declared origins, the edge still appears among a finding's
+  causal steps and edges with that origin, the memo writes it "preceded by (graph parent, chosen
+  heuristically)", and `summarize` groups it apart from a declared graph parent. The derived tree
+  is unchanged (the origin ranks as a graph parent does). When the span also links to the parent
+  that was picked, the link declares the edge: it stays `graph_parent` and is not counted under
+  `otlp.graph_parent_by_timing`, so a trace whose every timed choice is linked no longer carries
+  that code, and loses its heuristic-parent warnings unless it also has
+  `otlp.graph_parent_fallback`. The `otlp.graph_parent_by_timing` gap is otherwise recorded as
+  before.
+- **Artifact schema 8.** An artifact with a `graph_parent_heuristic` edge declares
+  `schema_version` 8, or 9 if it also has a `checkpoint_subgraph_return` edge, so 0.8.0 and
+  earlier refuse it by version instead of failing on the new origin value. As far as this change
+  goes, every other artifact keeps the version it had, and its bytes too, except a fresh ingest
+  whose timed choices are all linked, which drops that gap as above. Artifacts written by
+  earlier releases are read as before: their timed edges say `graph_parent`, so `analyze`
+  classifies them as it did, and the memo keeps qualifying every graph parent in a trace with
+  `otlp.graph_parent_by_timing`.
+
+### Fixed
+
+- **`--backend ladybug` no longer hangs on gap patterns or slows down on long ones** (#176,
+  #173). `LadybugStore` ran every pattern the Cypher compiler accepts as one native query. A
+  bounded gap compiles to a variable-length relationship, and LadybugDB enumerates every causal
+  path within it, exponentially many once steps have several causes: `query
+  tool-retry-failure-near --backend ladybug` (`gap=(2, 30)`) gave no result within 120 s on a
+  200-step trace with two causes per step, where the default backend takes 0.02 s. A large
+  result could also end in `RuntimeError: Buffer manager exception`. Planning cost also grows
+  with the predicate count: 17.5 s for 32 predicates on a one-step trace, and a `RuntimeError`
+  at 1000. `LadybugStore` now runs a pattern as Cypher only if it has no gap after its first
+  predicate and at most six predicates (`MAX_NATIVE_PREDICATES`); every other pattern runs on
+  the pure-Python matcher, with the same matches, and `fell_back_to_python` is set.
+  `compile_to_cypher` is unchanged and still compiles bounded gaps.
+  - `query tool-retry-failure-near --backend ladybug` now prints the fallback note on stderr.
+    It used to run as Cypher without one. The other presets behave as before: the strict ones
+    run as Cypher, and the two with an unbounded gap already fell back.
+  - The note now reads `LadybugDB does not run patterns with a gap or more than 6 predicates;
+    ran the pure-Python matcher over the raw causal graph — the results are the same.` It
+    said `pattern not Cypher-compilable (unbounded gap)`.
+- **A `PathPattern` of about 1000 or more predicates no longer fails with `RecursionError`**
+  (#170). The pure-Python matcher behind `find_matches`, `iter_matches` and `search` recursed
+  once per predicate; it now walks the predicates with an explicit stack. Matches and the order
+  `iter_matches` yields them in are unchanged. CLI `query` and `analyze` run short presets and
+  were not affected. `LadybugStore` runs long patterns on the same matcher (#173).
+- **Deeply nested input no longer crashes ingestion with `RecursionError`** (#168). An entry point
+  that reads a document now reports a `RecursionError` raised while reading it as the
+  `ValueError` it promises, so the CLI exits with a usage error (2) instead of a traceback.
+  - The entry points are `artifact.from_obj`, `OTLPSpanAdapter.from_documents`, `.discover` and
+    `.ingest`, `PhoenixExportAdapter(document)` and `.ingest`, and
+    `LangGraphCheckpointAdapter.discover` and `.ingest`, which `ingest --sqlite` runs.
+  - Messages: `artifact cannot be read: recursion limit exceeded`, `trace document cannot be
+    read: recursion limit exceeded` (OTLP and Phoenix), and `checkpoint history cannot be read:
+    recursion limit exceeded`. They name the limit, not a cause, because a caller-supplied saver,
+    graph or object can recurse on its own.
+  - Reached from the CLI: `ingest --sqlite` on a crafted checkpoint body that decodes to a value
+    nested past the recursion limit, which then crashed while the error channel value was
+    formatted. The limit is about 10,000 levels on 3.12 and 3.13 and about 70,000 on 3.14,
+    where it is the C stack.
+  - Reached from the library: documents the caller decoded, which the #167 text cap does not see,
+    with a deep `exception.message`, a deep `schema_version` (formatted into the refusal),
+    a deep error channel or pending-write value, or a schedule graph whose `get_state` returns a
+    deep config.
+  - Decoded documents still have no explicit depth cap: within the recursion limit they are read
+    as before. The analysis functions are outside this guarantee.
+- **A copy written after an edit inside a LangGraph subgraph no longer returns through the edit**
+  (#158). 0.8.0 returned a `__copy__` of a checkpoint that applied a subgraph's output through
+  the invocation's last subgraph checkpoint when that checkpoint preceded the copy, so an edit
+  made in between, which the copied checkpoint never saw, could become its cause, with any error
+  that edit wrote. A copy now returns through that checkpoint only when every earlier return
+  recorded from the same launcher into the same subgraph namespace went through it too, or none
+  was recorded. Otherwise nothing records which result it holds: it keeps its declared parent
+  without that return, and ingest records the new gap `langgraph.ambiguous_subgraph_return` (one
+  per return left out), which makes `check`'s multi-step path rules and `topology-unchanged`
+  insufficient evidence; the failure count rule is unaffected, since a copy records no new error.
+  The rule applies only to copies: loop checkpoints, which run the subgraph on from its latest
+  checkpoint, and `update_state` checkpoints, which apply the caller's values or the launcher's
+  stored output, are not withheld, though the other LangGraph entries here change how they
+  return. The gap needs no newer schema by itself, but a history that records it also has return
+  edges, so its artifact declares schema 9, which 0.8.0 and earlier refuse.
+- **A later run of a LangGraph persistent subgraph is in its continuation's ancestry** (#154). A
+  subgraph compiled with `checkpointer=True` keeps one checkpoint namespace across the parent's
+  runs, so a later run's input checkpoint declares the previous run's last checkpoint as its
+  parent. Ingest treated that run as part of the first one: the parent graph's continuation was
+  linked straight to the checkpoint that launched the subgraph, and the later run was missing
+  from its ancestry. A subgraph checkpoint whose `metadata.parents` names a launcher the
+  namespace has not had yet now begins a new run, which gets that launcher as a second
+  `checkpoint_parent` (an error the launcher held is not counted as inherited), and the
+  continuation returns through the run's own checkpoints with origin
+  `checkpoint_subgraph_return`. This also covers a loop calling the subgraph again, a resume
+  after a root `update_state`, and time travel into a subgraph checkpoint. One case is still
+  missed: a run finished by editing a subgraph checkpoint after a root `update_state` records
+  the original launcher, so the continuation, which declares the root edit, is not linked
+  through the run. A persistent subgraph inside a plain subgraph has a namespace without the
+  enclosing call's task id (`mid|inner`); it is now linked to that call's checkpoint, which
+  launched it, instead of the root's, so the enclosing subgraph's continuation returns through
+  it, on the first run too. A replay or edit of a persistent subgraph's launcher is judged by
+  `versions_seen` as for other subgraphs (#155). Re-ingesting such a history adds these edges. A
+  caller's edit of an earlier run's checkpoint still joins the run in progress, since LangGraph
+  resumes from the namespace's latest checkpoint.
+- **LangGraph time travel from a subgraph's launching checkpoint no longer gains the subgraph**
+  (#155). An `update_state` of the checkpoint that launched a subgraph as another node, or the
+  fork a replay from it writes, holds the state from before the subgraph ran, but ingest linked
+  it to the subgraph's last checkpoint. Such a checkpoint now returns through the subgraph only
+  if its `versions_seen` shows it applied the subgraph node's task, as an
+  `update_state(..., as_node=END)` applying the finished subgraph's output or a copy of the
+  continuation does; otherwise it keeps its declared parent. An `update_state` there that writes
+  the error channel is therefore recorded as introducing the error even when the subgraph had
+  failed. Such a checkpoint has no return edge, so it does not by itself make an artifact
+  declare schema 9. `Send`-launched invocations, and nodes whose task id the adapter cannot
+  recompute (a plain-channel trigger, some barrier configurations), skip this check; the
+  return-checkpoint choice in the #150 entry below still applies to them.
+- **A later edit of a subgraph checkpoint no longer rewrites an earlier return** (#150). The
+  return used to go through the subgraph invocation's last checkpoint overall, so an
+  `update_state` of one of its checkpoints after the run made the original continuation lose
+  the subgraph from its ancestry on the next ingest. A continuation that returns through the
+  subgraph under the rules in the entries above now returns through the last subgraph checkpoint
+  written before it, which is also what LangGraph resumes from after an interrupted subgraph is
+  edited.
+
+## 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.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-tracegraph
-Version: 0.7.0
+Version: 0.9.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
@@ -15,6 +15,8 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Debuggers
 Classifier: Typing :: Typed
@@ -38,7 +40,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.
 
@@ -68,15 +70,26 @@ uvx --from agent-tracegraph tracegraph --version
 `tracegraph`.** The plain name was already taken on PyPI by an unrelated project, so only the
 name you install differs — you still run `tracegraph` and still `import tracegraph`.
 
-Requires Python 3.12. CI exercises 3.12 on Linux; other versions and platforms are untested
-rather than unsupported.
+Requires Python 3.12 or newer. CI exercises 3.12, 3.13 and 3.14 on Linux; other versions and
+platforms are untested rather than unsupported.
 
 ## Design commitment: causality is never faked
 
 We persist the **raw multi-parent causal graph** as the system of record (`CAUSED_BY`,
-keeping *every* real predecessor) and treat the single-parent tree (`TREE_PARENT`) as an
-explicitly **derived, lossy projection**. Any step whose causality is collapsed for the
-tree view is flagged `projection_lossy`, so RCA never silently presents a fabricated cause.
+keeping *every* recorded predecessor — every edge the ingest adapter emitted) and treat the
+single-parent tree (`TREE_PARENT`) as an explicitly **derived, lossy projection**. Any step
+whose causality is collapsed for the tree view is flagged `projection_lossy`, so RCA never
+silently presents the tree's single parent as "the" cause.
+
+Recorded is not the same as declared by the source. Adapters reconstruct some edges: OTLP and
+Phoenix pick which run of a looped node is the parent by start time or start order, or fall back
+to `parentSpanId`; LangGraph routes a subgraph's return through the last checkpoint that
+subgraph invocation wrote before the parent graph continued. Some sources lose edges: OTLP span links that resolve to no span in the trace,
+and every link in a Phoenix export, which is ingested parents only. `projection_lossy` measures
+projection loss (more than one recorded parent), not capture fidelity. Some known limitations are
+disclosed per trace (`trace.capture` gaps, `causal_fidelity`, `links_preserved`) or per edge (its
+`origin`, such as `checkpoint_subgraph_return` for the LangGraph return edge), and an empty gap
+list does not mean the capture is complete.
 
 | analysis | reads |
 |---|---|
@@ -221,6 +234,17 @@ 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.
+Either way the chosen edge has origin `graph_parent_heuristic` rather than `graph_parent`, unless
+the span also links to that parent, which declares it.
+
 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
@@ -304,8 +328,10 @@ The official `tool-retry-failure@v2` matches three consecutive causal steps:
 retry marker and the endpoint must name the same tool. This strict pattern is review-exportable.
 `tool-repeat-failure-heuristic` uses an unbounded gap and
 `tool-retry-failure-near` a bounded gap (up to 30); both are query-only heuristics.
-The generic matcher still supports gaps and back-references. Unbounded or oversized
-Cypher patterns fall back to the Python matcher without truncating results.
+The generic matcher still supports gaps and back-references. With `--backend ladybug`, only
+patterns without a gap and of at most six predicates run as Cypher; every other pattern runs
+on the Python matcher, with the same results. A gap makes LadybugDB enumerate every causal
+path within it, which grows exponentially once steps have several causes.
 
 Every shipped preset has a stable `pattern_id` and positive integer `pattern_version`, shown
 as `pattern-id@vN` by `presets` and `query`. Increment the version when match semantics or
@@ -317,8 +343,10 @@ A group is one observed shape. Two matches share a group when, for every matched
 status, source and safe-v1 name agree, and for every edge between them the `CAUSED_BY` origin
 agrees, under the same source kind, causal fidelity and link setting, and the same answer to
 whether the trace discloses causal edges chosen heuristically at ingest (`motif-signature/v1`).
-That last answer is per trace: an OTLP export records a parent picked by timing with the same
-origin as an unambiguous one, and says only that some edge was picked that way, not which. The
+That last answer is per trace: the gap says only that some edge was picked heuristically, not
+which. (A parent picked by start order now has its own origin, `graph_parent_heuristic`, so the
+edge comparison already separates it; an artifact written before that records it as
+`graph_parent`, like an unambiguous one, and a fallback edge is `span_parent_fallback`.) The
 answer is `disclosed` whenever a recognized heuristic-edge gap is present, else `not_disclosed`.
 It is `unknown` for a trace with no capture record, or with a gap code this build does not know
 and no recognized heuristic-edge gap. It is `not_applicable` for a single-step preset, which has
@@ -354,7 +382,13 @@ A `*.json` file in a directory that is not a valid artifact is skipped with a wa
 `query`; pass `--strict` to fail the batch instead.
 The public schema is a repository-vendored contract (not wheel package data) at
 [`contracts/review-candidates.schema.json`](contracts/review-candidates.schema.json); G3
-consumers should vendor that file explicitly.
+consumers should vendor that file explicitly. The schema allows additional fields at both
+levels so that version 1 can grow, which means a document that validates can still carry text
+tracegraph never writes, such as a prompt or an error message. A consumer must ignore fields it
+does not know and must not store, display or forward them, as SyncMill and Toolgraph do; a field
+that carries trace body text would need a new major version. `ReviewCandidateReport` in the
+`tracegraph.review_candidates` module reads that way too: it drops unknown fields and keeps rejected
+input out of the `ValidationError` message.
 
 SyncMill can consume the report without importing this package:
 
@@ -394,16 +428,59 @@ Known limits:
   it such a run reads `ok` unless some other step recorded an error. Trace status stays `ok`
   either way. A task paused by `interrupt()` is reported without a graph. Both are reported
   only at the root graph: the subgraph node is named, not the node inside it.
+- Trace status reports whether a recorded step failed, not whether the run completed: a
+  paused or stopped run reads `ok` unless a step failed. Next to it, `analyze` (as a warning,
+  also in `--json-out`) and `export-incident-memo` show the recorded task markers:
+  `interrupted`, `scheduled`, and `undecided interrupt` (an interrupt recorded with a resume or
+  an error and no result; it gets no interrupt or scheduled step and is counted from its
+  capture gap).
+  `inspect` shows the first two. They count what the newest root checkpoint records, per root
+  task: an interrupt record outlives a revised graph that finished without writing a
+  checkpoint, a resumed subgraph can leave its parent's record, several paused inner tasks
+  count as one subgraph task, and `scheduled` is the answer for the graph you passed. A
+  malformed pending write is ignored and disclosed, so it can hide a marker; with `--graph`,
+  unapplied `Command(goto=...)` input and `Send` packets to a node the graph lacks are
+  disclosed rather than counted as scheduled. `check` judges each rule's evidence, not
+  completion.
 - Phoenix exports carry no span links, so their artifacts are parent-only; additional fan-in
   causes may be missing.
 - Report privacy (`safe-v1`) applies to reports; OTLP and LangGraph artifacts keep the
   producer's names, and its error messages unless ingested with `--redact-errors`.
-- CI covers Python 3.12 on Linux.
+- CI covers Python 3.12, 3.13 and 3.14 on Linux.
 
 Caveat for the checkpoint adapter: it is a **checkpoint-level** view (one node per
 super-step), and node names/kinds are best-effort metadata. Phoenix/OTLP adapters are
 span-level. Subgraph checkpoints are namespaced, but cross-namespace causality remains
-limited to parent links declared by LangGraph checkpoint metadata.
+limited to parent links declared by LangGraph checkpoint metadata, plus the return edge the
+adapter reconstructs when the parent namespace continues after a subgraph invocation. That edge
+runs through the last checkpoint the invocation wrote before the continuation (a resumed
+subgraph continues from, and returns, its namespace's latest checkpoint) and has origin
+`checkpoint_subgraph_return`, which `analyze` counts as explicit ancestry and the derived tree
+ranks as a declared checkpoint parent. A checkpoint a caller wrote from the checkpoint that
+launched the subgraph (`update_state`, a replay's fork) is linked this way only if its
+`versions_seen` shows it applied the subgraph node's task, so an edit as another node or a
+replay keeps its declared parent, while `update_state(..., as_node=END)` applying the finished
+subgraph's output, or a copy of the continuation, returns through the subgraph. Checkpoints do
+not show everything, so the edge can still be wrong where they cannot: an `update_state` as the
+subgraph node itself (metadata does not record `as_node`), clearing tasks with
+`as_node=END` while the subgraph itself is interrupted, fresh input on that launcher, time
+travel around a `Send` or a node whose task id the adapter cannot recompute (one triggered by a
+plain channel, some barrier configurations), and a subgraph checkpoint written
+after the subgraph finished but before the parent graph continued (a node editing its own
+subgraph while it is still running, or an outside `update_state` of a finished subgraph while a
+sibling task is interrupted). A persistent subgraph (`compile(checkpointer=True)`) keeps one
+namespace across the parent graph's runs; each run is told apart by the launcher its
+checkpoints record in `metadata.parents`. A caller's edit of an earlier run's checkpoint joins
+the run in progress, because the subgraph resumes from its namespace's latest checkpoint. A
+`__copy__` of a continuation holds output an earlier checkpoint applied, and nothing records
+which one: when earlier checkpoints from that launcher returned through a different subgraph
+checkpoint than the last one written before the copy (a subgraph checkpoint was edited in
+between, or the launcher was resumed twice), the copy keeps its declared parent without that
+return, and the gap `langgraph.ambiguous_subgraph_return` is recorded, which makes `check`'s
+multi-step path rules and topology rules insufficient evidence. An `update_state` from the launcher still returns
+through the last subgraph checkpoint written before it, edited or not. When an interrupted run is
+finished by an `update_state` of the subgraph after the launcher itself was edited, the
+continuation keeps the edited launcher as its parent and does not return through the subgraph.
 
 ## Develop
 
@@ -456,6 +533,18 @@ 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. A loop parent picked by start order has origin
+`graph_parent_heuristic`: `analyze` does not count it as explicit ancestry when it splits primary
+from propagated failures, and the memo writes it "preceded by (graph parent, chosen
+heuristically)". An artifact written before that origin existed does not say which edge, so a
+memo of such 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", and
+`analyze` classifies it as before. `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
@@ -525,7 +614,9 @@ managed values, cache-key functions — though no node runs. It is never inferre
 Every ingest records what the adapter could not observe: `trace.capture` is an object whose
 `gaps` list holds a fixed code and count per ingest disclosure (empty when there was none),
 and a step's `unknown_fields` names a kind, name or error message the adapter substituted. That
-record makes a fresh artifact declare `schema_version` 7. The envelope otherwise follows
+record makes a fresh artifact declare `schema_version` 7, 8 when a causal edge has origin
+`graph_parent_heuristic`, or 9 when one has origin `checkpoint_subgraph_return`. The envelope
+otherwise follows
 content, which is what an artifact written by an earlier release keeps when it is loaded and
 saved again: a graph read (`--graph`) needs 6, interrupt steps 5, a derived tree that relies on
 EdgeOrigin precedence 4, derived task steps 3, and anything else 2, byte for byte (a v1 file is
@@ -546,7 +637,7 @@ withheld, and a single unparseable cost withholds the whole total instead of und
 An OTLP or Phoenix import records an unreadable total cost as `unreadable` for that reason, and
 reports token counts, other costs, currencies and evaluation scores it cannot read as
 unavailable, disclosing each on stderr; the producer's value is never kept. File input, stdin
-and Phoenix `px` output share one size limit (`TRACEGRAPH_MAX_ARTIFACT_BYTES`). `query` reads
+and Phoenix `px` output share one size limit (`TRACEGRAPH_MAX_ARTIFACT_BYTES`). JSON nested more than 9000 levels deep is refused as `JSON nesting too deep` on every Python version, counted on the text before it is parsed; `ingest --sqlite` checks the JSON in the thread's checkpoint rows the same way. A document the caller decoded and passes to the library is not depth-capped, but reading one too deep to process is refused as `ValueError` (`... cannot be read: recursion limit exceeded`), not a crash. `query` reads
 artifacts one after another and keeps only the matches it prints (plus the traces `--explain`
 renders). With `--limit`, its peak memory therefore grows with the number of artifacts only
 by a small per-file record (path, trace id); without it, by the matches it prints. Inside one
@@ -554,16 +645,18 @@ trace, too, it keeps only the matches that still fit under `--limit`, but it sti
 and counts every match to report the exact total, so time grows with the match count: one
 2500-step trace with 3.1M matches takes about 3 s at `--limit 1`, in 70 MiB. The search's own
 working state (steps reached at each distance of a gap) does not depend on `--limit`. With
-`--backend ladybug` on a pattern that compiles to Cypher, LadybugDB itself buffers the
+`--backend ladybug` on a pattern that runs as Cypher, LadybugDB itself buffers the
 query's full result set: a 3001-step trace with 2.25M `tool-retry-failure` matches peaked
 at 757 MiB, where the store alone takes about 300 MiB. A plain read, `count(*)` and
-`ORDER BY … LIMIT` all buffered it in our measurements.
+`ORDER BY … LIMIT` all buffered it in our measurements. The six-predicate limit on Cypher
+bounds the query's planning, not its result: a short strict pattern over a graph where steps
+have many effects can still have a large result, and LadybugDB buffers all of it.
 
 Both stores isolate returned mutable objects. InMemory node upsert replaces by ID;
 Ladybug's existing insertion semantics are unchanged. Use `is_isomorphic` or `diff` for
 deep-tree equality; `canonical()` preserves nested tuples, whose external Python equality
-can still reach the interpreter recursion limit. CI currently covers Python 3.12/Linux;
-other supported Python versions and platforms require separate validation.
+can still reach the interpreter recursion limit. CI currently covers Python 3.12–3.14/Linux;
+other Python versions and platforms require separate validation.
 
 ## Contributing, security, and license