agent-tracegraph 0.4.0__tar.gz → 0.5.0__tar.gz

{agent_tracegraph-0.4.0 → agent_tracegraph-0.5.0}/CHANGELOG.md

@@ -6,6 +6,229 @@ 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.5.0 - 2026-10-18
+
+### Added
+
+- **Dropped OTLP span links are disclosed** (#49). A link the OTLP importer could not record as a
+  cause was skipped silently, while the header still read `causal_fidelity=declared_dag` and
+  `links_preserved=true`. Each kind now prints one stderr line with its count and becomes a
+  capture gap: `otlp.unresolved_span_link` (names this trace but no span in the export,
+  possibly a partial export), `otlp.unscoped_span_link` (names no trace, missing or empty `traceId`; it may
+  refer to a span of this trace, so it is no longer treated as foreign) and
+  `otlp.foreign_trace_link` (names another trace). `check` treats the first two as gaps that may
+  have left a step out (one-sided for the count rules, insufficient for topology) and the third
+  as having no effect. The schema stays v7. Only artifacts ingested from exports with such links
+  change, and with them the digests of reports made from them; every committed fixture resolves
+  all its links. An artifact holding none of these codes reads and checks as before.
+- **`--strict` for `query` and `export-review-candidates`** (#50). A `*.json` file in a directory
+  that is not a valid artifact is skipped with a warning, so a truncated artifact holding the
+  failure let a "pattern must not appear" gate pass with exit 1 ("no matches"), and let
+  `export-review-candidates` write a report without it. With `--strict`, any skipped directory
+  file fails the command with exit 2 (`--strict: N discovered file(s) could not be loaded as
+  tracegraph artifacts`) after the usual skip warning, and no report is written. An explicitly named bad
+  file still fails first, as before; `--strict` is checked before "no valid artifacts" and
+  duplicate trace ids. Without the flag nothing changes, and with it and no strays the output
+  is byte-identical.
+- **`tracegraph check`, an explicit regression verdict** (#59): one current run, one baseline the
+  caller names, and rules the caller names (`failures-not-increased`,
+  `pattern-not-increased:<preset>`, `topology-unchanged[:shape]`; no default set). Exits 0 PASS,
+  1 FAIL, 3 INSUFFICIENT_EVIDENCE, 2 invalid input (no report written). Rules compare counts
+  per step `(kind, name)`; unknown evidence the selected rule depends on — an `unset` status, a
+  substituted value or missing name on a step it could count, a capture gap that may have
+  left a step out of the artifact — blocks PASS on the current side and
+  FAIL on the baseline side instead of counting as zero (a step-omitting gap on either side makes
+  the topology rule insufficient, since it compares trees, not counts). Pairs from different
+  sources, or with either artifact lacking capture provenance (written before artifact v7),
+  are insufficient for every rule, and pairs read with different causal settings for the
+  rules that read causal structure. New contract `tracegraph.check` v1
+  (`contracts/check-report.schema.json`), bound to both canonical artifact digests and each
+  rule's id, version and parameters. `diff`, `query` and `analyze` keep their exit codes.
+- **Capture provenance, artifact schema version 7** (groundwork for #59): every ingest now
+  records in the artifact what the adapter could not observe, so a later comparison can tell
+  "recorded, nothing disclosed" from "not recorded". `trace.capture.gaps` keeps one fixed code and count
+  per ingest disclosure (the stderr text is unchanged and stays out of the artifact; the code
+  carries no checkpoint id, task id or producer value), and `capture` is present with an empty
+  list when the read raised no disclosure; values substituted on one step are recorded
+  separately. `steps[].unknown_fields` names values an adapter substituted:
+  `kind` and `name` (a span without a recognized OpenInference kind or a usable name, including
+  Phoenix names dropped as non-identifiers; an unattributed LangGraph task; and every LangGraph
+  checkpoint step except the input checkpoint and the loop step that applies it, named or not,
+  because a checkpoint does not record its writer and its name is inferred from the parent's
+  routing) and `error_msg` (OTLP's `"error"` fallback, withheld messages, LangGraph's
+  unserialized-exception label). Task, interrupt and scheduled steps named from LangGraph's own
+  task ids are not flagged. Two OTLP parent resolutions that were silent are now recorded too: a `graph.node.parent_id` resolved by start time among
+  several spans, and one not honored in favour of `parentSpanId`; each also prints a new stderr
+  warning. Every newly ingested artifact declares 7 and 0.4.x refuses it by name; an artifact
+  written by an earlier release re-serializes exactly as the previous release wrote it (v2–v6
+  byte for byte, v1 migrated to v2 as before) and never gains provenance. Newly ingested
+  artifacts therefore have new digests, as do analysis reports and incident memos built from
+  them; report and memo shapes, other CLI output and exit codes are unchanged.
+- **`analyze` reads OTLP span exports directly** (#57): a JSON or Collector JSONL export
+  (`resourceSpans`) is diagnosed in memory with the same adapter settings as `ingest-otlp`, so
+  the report is byte-identical to analysing the ingested artifact; `--trace` selects one trace of
+  a multi-trace export and `--baseline` accepts an OTLP export too. Inputs are routed by shape
+  before any adapter runs (`schema_version` → artifact, `resourceSpans` → OTLP, `spans` or a
+  root `traces`/`data` list → Phoenix); record validity stays the adapter's call, so the direct
+  path accepts and rejects what the explicit ingest commands do. A payload carrying both OTLP
+  and Phoenix records exits 2: a single object names the ingest command that reads each format,
+  and a list, JSONL or Phoenix envelope says to extract one format's records first. An unknown
+  shape exits 2 listing the supported ones instead of failing as a Phoenix export.
+  `ingest-otlp --file -` reads stdin, and stdin now goes through the same
+  `TRACEGRAPH_MAX_ARTIFACT_BYTES` ceiling as files for `analyze`, `ingest-otlp` and
+  `ingest-phoenix` (the stdin half of #53; the `px` output half is the "Phoenix `px` output is bounded" entry below);
+  `ingest-phoenix` reads its input with the Phoenix adapter only (its accepted inputs are
+  unchanged). Next investigation steps after a direct OTLP
+  diagnosis print an `ingest-otlp` save template. No file is written without `--json-out`;
+  analysis JSON schemas, exit codes and privacy boundaries are unchanged.
+- **Guided investigation after `analyze` and `phoenix diagnose`** (#58): displayed failure
+  candidates include full step IDs, with POSIX-quoted `explain` commands for existing artifacts
+  or explicitly labelled save/replay templates for exports, stdin, and unsaved Phoenix traces.
+  Evidence IDs, paths and commands preserve literal emoji-like tokens and are not forcibly
+  line-wrapped; consumed pipe inputs and descriptor aliases (`/dev/stdin`, `/dev/fd/N`,
+  `/proc/<pid>/fd/N`, or a symlink to one, including regular-file stdin redirects; a symlink
+  to a directory descriptor is not detected) require replay. Nonprinting arguments are shown as
+  escaped data instead of copyable commands. Hidden
+  candidates show the required `--limit`; report paths are acknowledged only after successful
+  writes, without duplicate report-path notices. Existing edge-origin/fidelity warnings and
+  missing-telemetry disclosures continue to distinguish evidence from causal claims; this
+  change adds navigation, not new causal inference. Analysis JSON schemas, exit codes, and
+  artifact privacy boundaries are unchanged.
+- **`ingest --graph` reports LangGraph tasks that were scheduled but recorded nothing.**
+  Given the compiled graph (`path/to/file.py:attr` or `pkg.module:attr`), LangGraph's
+  `get_state` lists the tasks it schedules at the thread's newest root checkpoint, and each one
+  with no write there becomes an `unset` step with the new source value `scheduled`, linked by
+  `CAUSED_BY` to that checkpoint: the recursion limit, a killed process, a static breakpoint,
+  one step per `Send` packet. Finished, failed and paused tasks are still read from the
+  checkpoint's writes, so these steps never duplicate `task` or `interrupt` steps. The result
+  is LangGraph's answer for the supplied graph; the trace header records its structural
+  fingerprint as `schedule_graph`, also when nothing is scheduled. An unapplied
+  `Command(goto=...)` input and `Send` packets to a node the graph lacks are disclosed at
+  ingest. `--graph` imports the module and runs the graph's state callbacks while reading,
+  but no node. `inspect` marks such a step `◌ scheduled` and adds `· N scheduled` to the
+  summary.
+- **Artifact schema version 6**, stamped by content: an artifact read with `--graph` (it has
+  `schedule_graph`, or a `scheduled` step) declares 6, and 0.4.x refuses it by name. The header
+  field is omitted, not written as `null`. (A fresh ingest by this release declares 7 for its
+  capture record, which outranks 6.)
+- **A hands-on getting-started notebook in Korean**, `examples/getting_started_ko.ipynb`, for
+  first-time users working from a repository checkout. It runs the example agent and the
+  offline commands other than `check` and `export-review-candidates`, interprets each output, and works through two applied scenarios:
+  checking a change against a baseline, and aggregating failures across many runs from
+  `analyze --json-out` reports. Its outputs are committed, and `tests/test_notebooks.py`
+  executes it so its commands and exit codes cannot drift from the CLI. `nbclient` and
+  `ipykernel` join the development dependencies. Nothing ships in the wheel or sdist, and no
+  artifact or report contract changes.
+
+### Changed
+
+- **`artifact.save()` and `artifact.save_atomic()` refuse a trace the readers would reject**
+  (#67). Pydantic does not revalidate on attribute assignment, so a `NormalizedTrace` changed in
+  place could be written in a form tracegraph's own readers refuse: `save()` wrote a mistyped
+  `status`, and both wrote a `CAUSED_BY` edge to a missing step (which `artifact.load` accepted
+  and only `validate` / `analyze` rejected), a trace status that disagrees with its steps, a
+  wrong `projection_lossy` flag, or a missing `TREE_PARENT`. Both writers now round-trip the
+  model and run `validate_normalized`, the check the stores and `validate` apply on load
+  (legacy projections included), before touching the destination, and raise `ValueError`
+  (pydantic's `ValidationError` is one), leaving an existing file untouched. A mistyped `seq` used to escape
+  every writer as a raw `TypeError`; it is now a `ValidationError` too. A valid trace is written
+  byte for byte as before, from the validated copy, so a value the model coerces (`"0"` for a
+  `seq`) is written as it would be read. Cost on a 6000-step chain: `save()` 0.16 s → 0.29 s,
+  `save_atomic()` 0.19 s → 0.30 s; `ingest` already validated before saving, so it now checks
+  twice. Because the model now checks first, a capture-provenance
+  violation reaches a writer's caller as pydantic's `ValidationError` rather than the
+  `check_provenance` message (`artifact.dumps()` still raises the latter). `artifact.dumps()`
+  stays a serializer without the model and structure checks (its `TypeError` on a mistyped
+  `seq` is #82).
+- `inspect` marks a step paused by `interrupt()` as `⏸ interrupted`, in yellow rather than
+  the green used for finished steps, and the summary line gains `· N interrupted` when there
+  is one. The output for every trace with neither interrupted nor scheduled steps is unchanged.
+
+### Fixed
+
+- **A LangGraph node writing the error channel while it is still set is disclosed** (#47). A
+  checkpoint is an error only where the error channel is set and every causal parent's is
+  empty, so a node failing again before the key was cleared stayed `ok`, silently, and the
+  retry presets could not match. The rule is unchanged: a checkpoint does not record which
+  node raised, and both a value-change rule and the issue's version rule were measured to
+  invent failures (a node returning the whole state, a reducer that grows the value, a
+  handler rewording the error). Instead, a node-written checkpoint whose error channel was
+  written again while set (its `channel_versions` entry moved, or without versions its value
+  changed) counts toward a stderr disclosure and the capture gap
+  `langgraph.rewritten_error_channel`. `check` reads it for the count rules (one-sided on that
+  side) and for success-dependent patterns such as `gate-failure-after-success` (insufficient
+  on either side), not for topology. Input, `__start__`, update and fork-copy checkpoints, and
+  parents in another namespace (a subgraph's entry or exit), are not compared, so propagation
+  and a caller's input disclose nothing; a propagated error recorded again at a subgraph's
+  `__start__` is pre-existing and filed as #85. Measured on LangGraph 1.2.2 and 1.2.15 with
+  InMemorySaver and SqliteSaver. Artifacts change only for histories with such writes; the
+  committed fixture has none. Schema stays v7.
+- **`analyze --trace` and `--baseline-trace` no longer ignore the selector on an artifact**
+  (#64). An artifact holds one trace, and a selector naming a different one was accepted: the
+  command exited 0 with a report on the artifact's trace, not the one requested. It now exits 2
+  with `Invalid value for --trace: <input> holds trace '<id>', not '<selector>'` (or
+  `--baseline-trace`) and writes no report, as `check` already did and as a missing trace in an
+  OTLP or Phoenix export does. A selector naming the artifact's own trace is still accepted, and
+  the report is byte-identical to the one without it.
+- **`ingest-phoenix --trace` no longer ignores the selector on a Phoenix-sourced artifact** (#69).
+  Re-ingesting such an artifact with a selector naming another trace exited 0 and re-saved the
+  artifact's own trace. It now exits 2 with the same message as `analyze` and writes nothing, to
+  `--out` or to the default path. A matching selector re-saves the artifact byte for byte, as
+  before. An artifact from any other source keeps its existing error, `--file must contain a
+  Phoenix CLI trace export`.
+- **`phoenix doctor` and `phoenix diagnose` no longer crash when `px` cannot be run** (#56). A
+  `px` on PATH without the exec bit, a directory named `px`, or a file the OS cannot execute
+  raised `PermissionError` or `OSError` with a traceback. They now report that `px` failed with
+  an OS error, naming the operating system's text for the error number and never the exception
+  message: `doctor` prints `FAIL` and exits 1, `diagnose` exits 2, as for their other `px`
+  failures. When the OS refused to launch `px`, the message adds a hint to check that `px` on
+  PATH is an executable file.
+- **Phoenix `px` output is bounded** (#53, the half #63 left open). `phoenix doctor` and
+  `phoenix diagnose` held all of `px`'s stdout and stderr in memory with only a time limit. Stdout
+  now goes to an unlinked temporary file held to the same `TRACEGRAPH_MAX_ARTIFACT_BYTES` ceiling
+  as file and stdin input (default 256 MiB, `0` disables it). `px` is killed and reaped once the
+  file passes the limit, and the command reports `... output exceeded the N-byte limit` without
+  echoing the output: doctor `FAIL` exit 1, diagnose exit 2. Stderr is discarded; it was never
+  shown. Two smaller changes come with it. Output that is not UTF-8 is now reported as such:
+  before, `doctor` printed the codec error and `diagnose` crashed with a traceback. And a
+  descendant of `px` that keeps stdout open no longer holds the call until the timeout, and
+  the capture stops at the size sampled once `px` has exited, read by position on POSIX so a
+  descendant's later writes cannot overwrite it. Such descendants are not
+  stopped: `px` is trusted like any installed executable. Timeout, nonzero-exit and
+  launch-error messages are unchanged.
+- **`SECURITY.md` now states the `ingest --graph` trust boundary** (#55). It said tracegraph
+  "does not execute graphs" and called a checkpoint database the one input that can run code,
+  but `--graph` imports the module you name, running its top-level code, and then runs the
+  graph's state callbacks while reading. A new section says what runs (no node does), that
+  checkpoint payloads stay under the empty serializer allowlist while the named code itself is
+  unsandboxed, and that the graph is never inferred. A table at the top separates JSON parsing,
+  hardened checkpoint deserialization and explicitly supplied graph code. The same file no
+  longer says piped stdin is read without a size cap: since direct OTLP analysis (#63), `-` goes
+  through the same `TRACEGRAPH_MAX_ARTIFACT_BYTES` ceiling as a named file. Documentation only.
+- **`query` no longer keeps every trace and every match in memory** (part of #54). It loaded
+  and validated all artifacts, matched them all, and only then sliced the result to `--limit`,
+  so `--limit 1` over 200 artifacts of 2000 steps (248 MB on disk) peaked at 1374 MiB. It now
+  loads, validates and matches one artifact after another, keeps only the matches it prints
+  (and, with `--explain`, the traces they belong to), and builds labels only for those. With
+  `--limit`, peak memory grows with the number of artifacts only by a small per-file record:
+  70 MiB for the same query. Without `--limit` it holds the matches it prints: 105 MiB. Output, exit codes and error precedence are
+  unchanged: every input is still validated, a later file's load error or a duplicate
+  trace_id still wins over a matching failure, and the footer's total stays exact. Matches past
+  `--limit` are counted but no longer labelled, so a labelling fault there (an internal bug:
+  labels look up step ids the matcher just returned) would no longer surface. One trace
+  with very many matches still enumerates them all (3.1M matches: 971 MiB, down from 986 MiB
+  but 5.4 s instead of 17 s); bounding that needs a decision about the `--limit` total and is
+  tracked as #79. An interrupt or `MemoryError` now surfaces at the artifact being read,
+  after the skip warnings collected so far, rather than after every file has loaded.
+- **`repeated-agent-failure` no longer takes quadratic time when no names can match** (#52).
+  The unbounded two-step matcher it shares with `tool-repeat-failure-heuristic`, and which
+  `analyze` runs on every trace, walked and sorted every failing endpoint's whole causal
+  history before checking the name back-reference: a 2000-step chain of failing agents with distinct names
+  took 1.3s for zero matches, 4x per doubling. It now skips an endpoint no earlier candidate
+  can pair with and walks back only as far as the earliest one (2000 steps: 0.001s; a chain
+  whose only repeats are disjoint adjacent pairs is linear too). The longest-path pass also stopped rescanning a
+  high-fan-out cause once per endpoint. Matches, their order and every report are unchanged.
+
 ## 0.4.0 - 2026-10-14
 
 ### Added

{agent_tracegraph-0.4.0 → agent_tracegraph-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-tracegraph
-Version: 0.4.0
+Version: 0.5.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
@@ -45,7 +45,9 @@ then runs analyses the mainstream observability tools don't:
 It is **not** a checkpointer — a graph-backed `BaseCheckpointSaver` already exists.
 tracegraph is the read-path *analysis* layer. See [`docs/FEASIBILITY.md`](docs/FEASIBILITY.md)
 for the full rationale and competitive landscape. Korean readers can start with
-[`docs/USAGE_KO.md`](docs/USAGE_KO.md).
+[`docs/USAGE_KO.md`](docs/USAGE_KO.md), or run the hands-on notebook
+[`examples/getting_started_ko.ipynb`](examples/getting_started_ko.ipynb) from a repository
+checkout.
 Current delivery evidence, known limitations, and next work are maintained in
 [`docs/HANDOFF.md`](docs/HANDOFF.md).
 
@@ -94,6 +96,7 @@ tracegraph explain A.json <step_id>  # raw causal chain back to the root cause
 tracegraph diff A.json B.json        # structural regression diff (AHU isomorphism)
 tracegraph validate A.json traces/   # validate artifacts before CI/query jobs
 tracegraph analyze A.json            # automatically select and explain failures
+tracegraph check B.json --baseline A.json --rule failures-not-increased   # regression verdict for CI
 
 # Phoenix: one command after configuring the official `px` CLI
 tracegraph phoenix doctor
@@ -119,13 +122,58 @@ Frequently-used options, beyond `--out` / `--json-out`:
 
 | option | commands | effect |
 |---|---|---|
-| `--trace`, `-t` | `ingest-otlp`, `ingest-phoenix`, `analyze` | Pick one trace out of a multi-trace export. |
+| `--trace`, `-t` | `ingest-otlp`, `ingest-phoenix`, `analyze`, `check` | Pick one trace out of a multi-trace export. For `analyze`, `check` and `ingest-phoenix` on an artifact, it must name the artifact's own trace (exit 2 otherwise). |
 | `--error-channel` | `ingest` | LangGraph state channel that signals a step error (default `error`). |
-| `--baseline`, `--baseline-trace` | `analyze`, `phoenix diagnose` | Compare against a known-good run, and pick its trace out of a multi-trace file. |
+| `--baseline` | `analyze`, `check`, `phoenix diagnose` | Compare against a known-good run: a file for `analyze` and `check`, a Phoenix trace id for `phoenix diagnose`. |
+| `--baseline-trace` | `analyze`, `check` | Pick the baseline's trace out of a multi-trace file. On an artifact baseline, it must name its own trace (exit 2 otherwise). |
 | `--limit`, `-l` | `analyze`, `phoenix diagnose`, `query` | Cap how many failure candidates or matches are rendered (default 3 for diagnosis). |
 | `--explain` | `query` | Print each match's raw causal chain back to its root cause. |
 | `--structure` | `diff` | Compare topology only, ignoring labels. |
 | `--backend` | `query` | Use the optional LadybugDB Cypher accelerator instead of the pure-Python matcher. |
+| `--strict` | `query`, `export-review-candidates` | Fail with exit 2 when a directory holds a `*.json` file that is not a valid artifact, instead of skipping it with a warning. Use it in CI gates, where a skipped corrupt run would otherwise read as "no match". |
+| `--rule` | `check` | Rule to evaluate, repeatable; there is no default rule set. |
+
+### Regression check
+
+`check` judges one current run against one baseline you name, with rules you name, and answers
+with an exit code a CI job can use directly:
+
+```bash
+tracegraph check current.json --baseline baseline.json \
+  --rule failures-not-increased --rule pattern-not-increased:tool-retry-failure \
+  --json-out check.json
+```
+
+| exit | verdict |
+|---|---|
+| 0 | `PASS` — every rule held on the recorded evidence |
+| 1 | `FAIL` — some rule was definitely violated (more failures or matches, or a changed tree) |
+| 3 | `INSUFFICIENT_EVIDENCE` — some rule could not decide, and none failed |
+| 2 | invalid input or configuration; no report is written |
+
+Rules: `failures-not-increased` (recorded errors per step `(kind, name)` and in total),
+`pattern-not-increased:<preset>` (confirmed matches of a preset), and `topology-unchanged`
+(derived tree with labels) or `topology-unchanged:shape`. Counts compare step signatures,
+because no source records which step of one run is which step of another; two same-named steps
+trading which one fails is not detected (`analyze --baseline` shows the positional view).
+Evidence that is unknown is never read as zero. When something the selected rule depends on is
+unknown — an `unset` status, a value the adapter substituted (`unknown_fields`) or a missing
+name on a step the rule could count, or a capture gap that may have left a step out of the artifact — it blocks PASS
+on the current side and FAIL on the baseline side, so the rule reports `INSUFFICIENT_EVIDENCE`.
+The topology rule compares trees rather than counts, so such a gap on either side makes it
+insufficient even when the observed trees match. Unknowns a rule cannot count leave it decided: an unset CHAIN does not block
+`pattern-not-increased:tool-failure`, and a withheld error message blocks only `timeout`.
+Pairs from different sources or ingested before capture provenance (artifact version 7) are
+insufficient for every rule; pairs read with different causal settings, or with causal edges
+chosen heuristically at ingest, are insufficient for the rules that read causal structure
+(multi-step presets and topology). A step without a name is
+treated as unknown wherever a rule compares names, and LangGraph checkpoint names are inferred,
+so the labeled topology rule is insufficient for LangGraph runs; the shape rule is not.
+`check` takes exactly one current and one baseline input (artifact, OTLP export, Phoenix export
+or `-`), never a directory, and never picks a baseline. It also assumes each input is a
+complete record of its run: an export missing a failing span cannot be told from a clean one.
+The `--json-out` report is `tracegraph.check` v1 (`contracts/check-report.schema.json`), bound
+to both canonical artifact digests and each rule's id, version and parameters.
 
 ## Phoenix-first workflow
 
@@ -198,10 +246,21 @@ For link-preserving analysis, use the optional Collector fan-out example at
 It sends the normal stream to Phoenix and an allowlisted JSONL copy to tracegraph. Then run:
 
 ```bash
+tracegraph analyze /tmp/tracegraph-otlp.jsonl --trace <trace-id>             # diagnose in memory
 tracegraph ingest-otlp --file /tmp/tracegraph-otlp.jsonl --trace <trace-id> -o full-dag.json
 tracegraph analyze full-dag.json
 ```
 
+`analyze` reads an OTLP span export (JSON or Collector JSONL) directly, with the same adapter
+settings as `ingest-otlp`, so the report is byte-identical to analysing the ingested artifact;
+nothing is written unless `--json-out` asks for a report. The input is identified by shape alone
+(`schema_version` → artifact, `resourceSpans` → OTLP, `spans`/`traces`/`data` → Phoenix); a
+payload carrying both OTLP and Phoenix records is refused, naming the explicit ingest command
+for each format (or, for a list, JSONL or envelope, asking you to extract one format's records). Already have an export? The shortest offline first run is
+`tracegraph analyze your-export.otlp.json` (add `--trace <id>` when the file holds several), then
+copy the `explain` command it prints after saving the artifact it names. The artifact caveat
+above still applies: `ingest-otlp` keeps error text, reports stay `safe-v1`.
+
 The JSON analysis-report contract is versioned at
 [`contracts/analysis-report.schema.json`](contracts/analysis-report.schema.json).
 Schema v2 can also carry body-free Toolgraph preflight evidence: an exact SHA-256 artifact
@@ -253,6 +312,8 @@ id/version, tool key, and the SHA-256 digest of the exact normalized artifact th
 There are no prompts, outputs, errors, step IDs, trace IDs, or local paths, and the command
 never changes a Toolgraph manifest or policy. A matching artifact without `run_id` fails the
 entire batch and leaves an existing output untouched; export never silently drops evidence.
+A `*.json` file in a directory that is not a valid artifact is skipped with a warning, as for
+`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.
@@ -289,11 +350,12 @@ and any change to them is called out in the [changelog](CHANGELOG.md).
 
 Known limits:
 
-- A LangGraph task that was scheduled but never started (a run stopped by the recursion
+- A LangGraph task that was scheduled but recorded nothing (a run stopped by the recursion
   limit, killed, or held at an `interrupt_before`/`interrupt_after` breakpoint) leaves no
-  write and is not reported, so such a run reads `ok` unless some other step recorded an
-  error. A task paused by `interrupt()` *is* reported (below), but only at the root graph:
-  the subgraph node is named, not the node inside it that paused.
+  write. It is reported only when `ingest --graph` names the compiled graph (below); without
+  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.
 - 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
@@ -369,7 +431,14 @@ source; mixing them can report a step whose status differs only by source as a b
 change (`ok` to `unset`, or the reverse).
 
 LangGraph ingestion reads both the configured error state channel and native task failures
-from checkpoint pending writes. A node that raises becomes a derived `task` step under the
+from checkpoint pending writes. A checkpoint is an error where the channel first holds an error.
+A node that writes the channel again while it still holds one may have failed again, or only
+have returned the whole state (and a reducer can change the value either way); the checkpoint
+cannot tell which, so such a write is not recorded as a failure but disclosed as the capture
+gap `langgraph.rewritten_error_channel`. That makes `check`'s count rules one-sided and
+success-dependent patterns such as `gate-failure-after-success` insufficient either way.
+Clear a plain (last-value) error key before retrying (`{"error": None}`) to have every attempt
+recorded; a reducer on the channel decides whether `None` clears it. A node that raises becomes a derived `task` step under the
 checkpoint that scheduled it, never a mark on that checkpoint, whose own name belongs to the
 node that produced it. The failing node is named by recomputing LangGraph's task id from
 checkpoint data; when nothing proves which node ran, the step stays unnamed rather than
@@ -384,23 +453,53 @@ that checkpoint: the recorded history holds no resume and no result for it. That
 history, not whether LangGraph would resume the task today. An interrupt recorded together with
 a resume or an error and no result is ambiguous in the checkpoint itself — under LangGraph 1.2.2
 a task resumed with nothing to write looks exactly like one paused a second time — so it is
-disclosed at ingest, not reported. An artifact carrying interrupt steps declares artifact `schema_version` 5; one
-whose derived tree relies on EdgeOrigin precedence declares 4; otherwise, an artifact carrying
-derived task steps declares `schema_version` 3, and artifacts without them still serialize as
-version 2, byte for byte.
+disclosed at ingest, not reported. Scheduled tasks need the compiled graph: `tracegraph ingest --sqlite trace.db --thread A
+--graph path/to/agent.py:graph` (the `langgraph.json` form) or `--graph pkg.module:graph`.
+LangGraph's own `get_state` then lists the tasks that graph schedules at the thread's newest
+root checkpoint, and each one with no write there becomes an `unset` step with source
+`scheduled`. Whether a task finished, failed or paused is still read from the checkpoint's
+writes, so a `scheduled` step never duplicates a `task` or `interrupt` step. A `scheduled`
+step does not claim that the task never started: a task killed mid-run records nothing
+either. The answer belongs to the graph you pass: a different graph can schedule different
+tasks from the same checkpoint, and nothing in one checkpoint proves which graph wrote it, so
+the artifact records the graph's structural fingerprint (`trace.schedule_graph`) — even when
+nothing is scheduled, which is how "checked, nothing pending" differs from "not checked".
+A `Command(goto=...)` input saved on that checkpoint but not yet applied, and `Send` packets
+addressed to a node the graph lacks, are left out of LangGraph's own answer; ingest discloses
+both instead.
+`--graph` runs code: it imports the module (top-level code runs), and reading the checkpoint
+runs the graph's state callbacks — schema mappers and validators, reducers, custom channels,
+managed values, cache-key functions — though no node runs. It is never inferred.
+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
+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
+migrated to 2 as before).
 Missing observed errors still do not
 prove success: an artifact ingested by an older build, or one using an unrecognized checkpoint
 layout, carries no derived step and looks exactly like a clean run, which is why the capture
 disclosure is unconditional. Link preservation
-means valid in-trace links only. Structural diff compares the derived tree and discloses
+means valid in-trace links only: `declared_dag` and `links_preserved` say how links were read,
+not that every declared link resolved. A link that names this trace but no span in the export,
+names no trace, or names another trace is not recorded as a cause; each kind is disclosed on
+stderr and recorded as a capture gap (`otlp.unresolved_span_link`, `otlp.unscoped_span_link`,
+`otlp.foreign_trace_link`), and `check` treats the first two like a step that may be missing. Structural diff compares the derived tree and discloses
 lossy step counts. Metrics sum available span observations: partial coverage and producer
 aggregation can undercount or double count. Coverage gaps are disclosed rather than absorbed
 — a wall duration derived from a subset of steps says so, one whose end precedes its start is
 withheld, and a single unparseable cost withholds the whole total instead of understating it.
 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 has a size limit, but stdin/Phoenix
-subprocess output and query materialization are not streaming memory guarantees.
+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
+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. It still
+enumerates every match of the trace it is reading, to report the exact total: one trace with
+very many matches is not bounded by `--limit`.
 
 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