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

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

@@ -6,6 +6,203 @@ 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.6.0 - 2026-10-20
+
+### Added
+
+- **`tracegraph summarize <preset> <artifacts...>`** (#60) groups a preset's matches across an
+  artifact batch by observed shape, so an operator can pick the recurring failure shape to look at
+  first. A group's signature (`motif-signature/v1`) is the matched steps' kind, status, source and
+  safe-v1 name, the `CAUSED_BY` origins between them, and the trace's source kind, causal
+  fidelity, link setting and whether it discloses heuristically chosen edges (per trace, not per
+  edge). It has no ids, error text or artifact file paths; an identifier-shaped name that looks
+  like a path is kept, as in `analyze` reports. Each group reports its match count and trace count
+  separately, plus up to three representatives (artifact digest and step ids). Only matches
+  confirmed by `check`'s rule are grouped; the rest are counted as unconfirmed. Fields that are
+  not known are kept as unknown. A coverage section always reports skipped artifacts, traces that
+  may hide a match, disclosed capture gaps, traces with no capture record and unconfirmed matches.
+  `--out` writes the `tracegraph.motif-summary` schema-v1 JSON with the same input protection as
+  `export-review-candidates`. Only strictly adjacent presets are accepted; the three gap presets
+  exit 2. Memory holds one trace and one entry per group, never the matches. A 160-wide retry fan
+  (25,600 matches) adds about 27 KiB over a 40-wide one, where collecting the matches adds about
+  2 MiB. The issue suggested validating demand first; this is the minimal version.
+
+### Changed
+
+- **`query --limit` no longer holds every match of the trace it is reading** (#79). Each
+  trace's matches were collected and sorted in full before the cap was applied, so one trace
+  with millions of matches took about 1 GiB at `--limit 1`. The matchers now produce matches
+  one at a time and `query` keeps only those still under the cap. The footer's total stays
+  exact, so every match is still counted. Measured on macOS/arm64 at `--limit 1` with
+  synthetic traces: a 2500-step chain of failing `x` agents (`repeated-agent-failure`, 3.1M
+  matches), and 1500 tools feeding one `retry:x` step that feeds 1500 failing tools
+  (`tool-retry-failure` and `tool-retry-failure-near`, 2.25M matches each):
+
+  | trace, preset | memory backend | `--backend ladybug` |
+  | --- | --- | --- |
+  | chain, `repeated-agent-failure` | 976 → 70 MiB, 5.5 → 2.8 s | 1226 → 308 MiB (Python fallback) |
+  | fan, `tool-retry-failure` | 1097 → 74 MiB, 2.8 → 1.6 s | 1753 → 757 MiB (Cypher) |
+  | fan, `tool-retry-failure-near` | 927 → 74 MiB, 3.2 → 2.1 s | 1470 → 613 MiB (Cypher) |
+
+  The Cypher rows stay high because LadybugDB buffers the full result set; an empty store
+  already takes about 300 MiB. The matches selected, their order, the footer total, exit codes
+  and error precedence are unchanged, and `find_matches` returns the same list for every caller.
+  Time still grows with the match
+  count. A mode that stops early and reports no total was considered and not built.
+  `LadybugStore` gains `first_matches(pattern, n)`; `tracegraph.analysis.patterns` gains
+  `iter_matches` and `first_matches`.
+
+### Fixed
+
+- **Boundaries that promise `ValueError` no longer leak an error from describing the one they
+  caught** (#109). Naming a caught exception runs caller code: `str(exc)` calls its `__str__`,
+  and a metaclass can make the type's `__name__` a property. When that raised, its error
+  escaped instead: from LangGraph ingest when the saver's listing or a supplied `schedule_graph`
+  fails, and from `--graph` when the module fails to import. The validated copy that
+  `artifact.dumps()` and `analyze()` use since #82 and #93 (both in this release) named its
+  caught exception the same way and is hardened too. These now describe the exception through
+  one internal guard (`tracegraph._errors`) that falls back to fixed text, and uses only a name or
+  message that is a plain `str`.
+  Ordinary exceptions are described exactly as before. `artifact.from_obj()` on a schema-v1
+  payload also refuses, as `ValueError`, an edge sequence that raises `SystemExit` or another
+  `BaseException` (the current schema already did for `SystemExit`), or whose type check
+  raises; `KeyboardInterrupt` still propagates.
+
+- **`--graph` loads a module file whose path is not valid UTF-8** (#110). On POSIX such a path
+  arrives surrogate-escaped, and naming the module from its strict UTF-8 encoding refused it:
+  `ingest --graph` exited 2 with a `UnicodeEncodeError` for a file it could import. Such a path
+  is now named from its file-system bytes, under its own prefix so it cannot take another
+  file's name. Every path that loaded before keeps its module name.
+
+- **Cost totals and their baseline delta are exact** (#111). They were computed at `Decimal`'s
+  default precision of 28 significant digits and rounded without a note, while the total was
+  still reported as complete: a cost of `0.12345678901234567890123456789` was totalled as
+  `0.1234567890123456789012345679`, and `10000000000000000000000000000` plus `0.01` as
+  `10000000000000000000000000000`. They are now computed at a precision of 160, which is exact
+  for any sum of costs within the 64-character bound up to about 10^32 steps. Past that, the total
+  (or only the delta) is withheld with a note instead of rounded. Ordinary costs report the same
+  digits as before (`1.00 + 1.00` is still `2.00`).
+
+- **A cost too long to write out is no longer summed or stored** (#100). A few characters of
+  exponent stand for a number of any size. A model-valid `total_cost` of `"1e1000000"` made
+  `analyze` fail with `decimal.Overflow`, an `ArithmeticError` rather than the promised
+  `ValueError`, with or without a baseline; `"9e999999"` did not overflow but wrote a
+  million-digit total into the report. OTLP ingest wrote such a value out in full, so a 10-byte
+  attribute `"1e99999999"` became a 100,000,000-character `total_cost` in the artifact. A cost is
+  now read only if, written out in full, it is at most 64 characters (`model.MAX_COST_CHARS`),
+  checked from its digits and exponent without writing it out (`model.cost_is_bounded(Decimal)`).
+  `analyze` withholds the total
+  with its own note, as for an unreadable cost; OTLP ingest treats a longer cost as unreadable,
+  so the total and component costs are disclosed as `otlp.unreadable_total_cost` and
+  `otlp.unreadable_component_cost` as before, and a readable alias is still used. Artifacts are
+  not refused at load. The bound is on each cost read, not on the total: summed exactly (#111),
+  two 64-character costs can make a 127-character total, and a million of them 133.
+
+- **A lone surrogate in a producer string no longer ends a command in a traceback** (#101). JSON
+  can carry one (`"\ud800"`), and the artifact loads and validates, but strict UTF-8 refused it
+  in several places: `analyze` (and `check` and the new `summarize`, which share the helper)
+  hashing a name into its `redacted:` alias; `ingest-otlp` without `--out` hashing the trace id
+  into the default file
+  name; `export-incident-memo` hashing the run id; `inspect`, `explain` and `query` writing the
+  name to the terminal; and LangGraph ingest hashing a routing channel into a candidate task id.
+  The three hashes now encode with `surrogatepass`, so every other string hashes to the same
+  alias, file name and digest as before. The LangGraph candidate is skipped, because LangGraph
+  could not have produced a task id from it. The CLI escapes what its output streams cannot
+  encode instead of failing.
+
+- **CLI output prints an emoji code in a producer string as written** (#102). The CLI's Rich
+  consoles kept emoji substitution on, and escaping markup does not turn it off, so a step named
+  `:ok:` printed as 🆗 in `query`, `inspect`, `explain` and `analyze` while the artifact and the
+  JSON reports held `:ok:`. Both consoles now have it off, so the new `summarize` prints the same
+  way. No text the CLI prints itself used an emoji code.
+
+- **`artifact.from_obj()` on a schema-v1 payload raises only `ValueError`** (#103). When reading
+  a caller-supplied lazy edge sequence failed, the migration formatted the exception into its
+  message, so an exception whose `__str__` raises escaped as that error instead. The message no
+  longer formats the exception at all (its type's name can run caller code too, through a
+  metaclass); the original stays on the chain as `__cause__`. `loads()` and the CLI parse JSON
+  into lists, so neither could reach this.
+
+- **`analyze()`, `check.evaluate()` and `build_incident_memo()` raise only `ValueError` on a
+  trace the model refuses** (#93). On a trace changed in place after it was built they raised a
+  raw `TypeError` or `AttributeError` (`seq = "zero"`, `steps = None`, `trace = None`, a step
+  `kind = "bogus"`, an integer `error_msg`), mostly from analysis code past their structural
+  check, and the memo rendered a step `status = "maybe"` without complaint. Each now analyzes the
+  copy the model validates, the same one `artifact.dumps()` and the writers use, so a value the
+  model coerces (`"0"` for a `seq`) is analyzed as it would be read and the caller's trace is
+  left unchanged. `analyze()` and the memo still accept structurally sound but non-canonical
+  traces; `check.evaluate()` still requires the canonical form. The validated copy does not change
+  the report for a valid trace; cost totals change separately in this release (#100, #111). That
+  copy is now made from a Python-mode dump: the JSON-mode dump
+  turned a NaN in `trace.run_id` or `trace.links_preserved` into `null`, which validated, so
+  `dumps()` and both writers erased the value instead of refusing it. It no longer depends on
+  the warnings filter either: under `-W error` a coercible value used to be refused through
+  pydantic's serializer warning. Cost on a 6000-step chain, best of 7, measured in PR #95 against
+  its parent `2eaa403` (which already had #82): `analyze()` 0.25–0.27 s
+  → 0.30–0.32 s, with a baseline 0.57–0.58 s → 0.69–0.70 s, `check.evaluate()` 0.65–0.67 s →
+  0.78–0.79 s, `build_incident_memo()` 0.016 s → 0.044 s.
+
+- **`artifact.dumps()` raises only `ValueError`** (#82). A trace changed in place after it was
+  built (pydantic does not revalidate on attribute assignment) could make it raise a raw
+  `TypeError` (`seq = "zero"`, `steps = None`, `edges = None`) or write a field the readers
+  reject (`status = "maybe"`, an integer `step_id`). `dumps()` now serializes a copy the model
+  has validated, as the writers already did, and raises `ValueError` for anything the model
+  refuses or cannot serialize: pydantic's `ValidationError` for a mistyped field, a
+  serialization error (also a `ValueError`) for a value it cannot dump at all, such as
+  `trace = None`. A value the model coerces (`"0"` for a `seq`) is written as it would be read.
+  A lazy sequence that fails while being serialized, through `dumps()` or either writer, is now
+  reported as a `ValueError` too, instead of whatever it raised. `dumps()` still checks fields,
+  not structure: a dangling edge or a stale trace status is written. Checking structure there
+  would refuse the structurally sound but non-canonical traces that `analyze()` digests, such as
+  one with a stale trace status (`analyze()` itself refuses a dangling edge). Unknown-field flags
+  without a capture record now reach a `dumps()`
+  caller as `ValidationError`, as they already did for the writers. A valid trace is
+  serialized byte for byte as before. Cost on a 6000-step chain, measured in PR #94 (its helper
+  was changed again by #93): `dumps()` 0.15 s → 0.20 s;
+  `analyze()` digests the current trace through it, a baseline comparison and `check` digest
+  both.
+
+- **An error already in the parent graph is no longer recorded again around a subgraph** (#85).
+  A LangGraph checkpoint is an error where the error channel holds one and none of the
+  checkpoints it was built from did, but the check read only a checkpoint's causal parents, and
+  three shapes hid the earlier error from it. A subgraph's `__start__` was compared only with
+  the subgraph's input checkpoint, which holds its values as pending writes. A persistent
+  subgraph (`checkpointer=True`) entered again was compared with its previous invocation, not
+  with the outer checkpoint that launched it. And the parent-graph checkpoint after a subgraph
+  was compared only with the subgraph's exit, so a subgraph whose state has no error channel, or
+  that cleared its own copy, made the outer error look new. One failure was recorded two or more
+  times: three with nested subgraphs, or when the subgraph cleared its copy. The check now also
+  reads each checkpoint's declared parents, and for a `__start__`, its input checkpoint's
+  declared parent and its launch parent (`metadata.parents`). A former duplicate written by a
+  node that rewrote the still-set channel is disclosed as `langgraph.rewritten_error_channel`
+  instead, with its stderr line, as for any such write since #47; `check` reads that gap as
+  before.
+
+- **A fork copy is no longer a second failure.** `update_state(..., as_node="__copy__")`
+  copies a checkpoint and runs no node, but it is linked to the copied checkpoint's parent, so
+  copying the checkpoint where an error first appeared (in the root graph, or a subgraph's
+  `__start__`) recorded that error again. A fork now never records an error.
+
+  For both: steps, edges, names and kinds are unchanged; what changes is which steps are errors
+  (with their `error_msg`) and the disclosure above. An error first written inside a subgraph, a
+  `Send` payload error below a clean state, and an error a caller's `update_state` writes are
+  recorded as before. Artifacts change only for histories that held such a duplicate. The
+  schema stays v7, and the committed fixtures are byte-identical. One shape still records the
+  error twice: a fork copy of a subgraph's *input* checkpoint, then resumed (#90).
+
+### Known limitations
+
+- Resuming after a fork copy of a subgraph's input checkpoint
+  (`update_state(..., as_node="__copy__")` on it) records an error again at the subgraph's next
+  start: one the parent graph held (#90) or one a `Send` payload carried (#96). Four ways of
+  recognizing such a copy were tried. Three classified the fork by its content: an unread
+  `__start__` value, a `__start__` version absent from `versions_seen`, and pending writes from
+  LangGraph's `__start__` task. The fourth matched it to an input checkpoint with identical
+  `channel_values`, `channel_versions` and `versions_seen`, and compared its run with the
+  original's. Each hid a genuine failure on a plain `Pregel` graph, so none shipped. A
+  `Pregel` input's first step can run a user node, and a no-op `update_state(...,
+  as_node="__input__")` can write an input identical to a loop checkpoint.
+
 ## 0.5.0 - 2026-10-18
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-tracegraph
-Version: 0.5.0
+Version: 0.6.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
@@ -110,6 +110,7 @@ tracegraph presets                   # list cross-trace query patterns
 tracegraph query tool-failure A.json B.json   # find a causal pattern across many traces
 tracegraph query tool-retry-failure *.json    # explicit retry marker, then same tool failing
 tracegraph query tool-failure --backend ladybug A.json B.json   # use the optional Cypher accelerator
+tracegraph summarize tool-retry-failure traces/ -o motifs.json  # group matches by observed shape
 
 # export versioned, body-free governance evidence (an empty match set is a valid report)
 tracegraph export-review-candidates tool-retry-failure *.json -o candidates.json
@@ -130,7 +131,7 @@ Frequently-used options, beyond `--out` / `--json-out`:
 | `--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". |
+| `--strict` | `query`, `summarize`, `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
@@ -304,6 +305,37 @@ Every shipped preset has a stable `pattern_id` and positive integer `pattern_ver
 as `pattern-id@vN` by `presets` and `query`. Increment the version when match semantics or
 review-export eligibility changes; wording-only description edits keep the current version.
 
+`summarize` groups one preset's matches across the same file/directory batches. It is meant for
+deciding which recurring failure shape to look at first, without tallying `query` output by hand.
+A group is one observed shape. Two matches share a group when, for every matched step, the kind,
+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
+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
+no edge.
+Trace and step ids, error text and artifact file paths are never part of it. Names pass the same
+safe-v1 rule as `analyze` reports. An identifier-shaped name is kept even when it looks like a path or an
+address, and anything else becomes `redacted:<sha256>`. An operation whose name changes from run
+to run gets one group per name. Each group counts its matches and, separately, the traces they
+come from, and lists up to three representatives, each an artifact digest plus the matched step
+ids. Only *confirmed* matches are grouped, by the same rule as `check`. A match that relies on a
+substituted value (a defaulted kind, an unrecorded status) is counted as unconfirmed instead. A
+field that is not known is written as `null` and listed under the step's `unknown`, never by the
+value that stands in for it. The coverage section is always printed. It shows how many artifacts
+were discovered, valid and skipped; how many traces may hide a match (`check`'s per-preset rule);
+how many disclose any capture gap; how many carry no capture record; and the unconfirmed matches.
+None of it is a rate, and an empty result is not an all-clear. A group does not show a shared root
+cause. Version 1 accepts only strictly adjacent presets: between gap endpoints the matched path
+is not recorded, so `repeated-agent-failure`, `tool-repeat-failure-heuristic` and
+`tool-retry-failure-near` exit 2. `--out` writes the `tracegraph.motif-summary` schema-v1 JSON.
+It must not name an input, is excluded from directory discovery, and is left untouched when the
+run is refused. Exit 0 with at least one group, 1 with none (the report is still written), 2 on
+an input error.
+
 `export-review-candidates` accepts the same artifact-file/directory batches as `query` and
 writes a deterministic schema-v1 envelope. Only presets ending in a failing `TOOL` predicate
 are eligible. The matched endpoint name must already be a qualified `server::tool` key —
@@ -343,7 +375,7 @@ and any change to them is called out in the [changelog](CHANGELOG.md).
 | Area | What exists |
 |---|---|
 | Sources | LangGraph checkpoint savers (including subgraph namespaces and native task failures), OTLP/OpenInference span exports, Phoenix CLI exports |
-| Commands | `ingest`, `ingest-otlp`, `ingest-phoenix`, `inspect`, `validate`, `explain`, `diff`, `analyze`, `presets`, `query`, `export-review-candidates`, `export-incident-memo`, `phoenix doctor`, `phoenix diagnose` |
+| Commands | `ingest`, `ingest-otlp`, `ingest-phoenix`, `inspect`, `validate`, `explain`, `diff`, `analyze`, `presets`, `query`, `summarize`, `export-review-candidates`, `export-incident-memo`, `phoenix doctor`, `phoenix diagnose` |
 | Patterns | Versioned presets matched over the raw causal graph; the governance-eligible `tool-retry-failure@v2` requires an explicit producer retry marker, and repetition-only heuristics are query-only |
 | Backends | Pure-Python in-memory store (default); optional LadybugDB/Cypher accelerator (`[cypher]`), whose results must equal the pure-Python matcher's |
 | Ecosystem | SyncMill run correlation (`syncmill.run_id`), Toolgraph preflight evidence as non-causal metadata, a weekly Phoenix + SyncMill end-to-end workflow (Phoenix CLI and server pinned; SyncMill tracks its default branch) |
@@ -432,6 +464,19 @@ 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 checkpoint is an error where the channel first holds an error.
+An error the parent graph already held is not recorded again where a subgraph receives it, nor
+where the parent graph continues after a subgraph that did not carry it, and a fork copy
+(`update_state(..., as_node="__copy__")`), which runs no node, never records one.
+One time-travel shape still records an error twice: copying a subgraph's *input* checkpoint as a
+fork and resuming. The subgraph's next start records the error again, whether the parent graph
+held it (#90) or a `Send` payload carried it (#96). The copy holds the same channels as the input
+it copies but no link back to it. Each marker tried (an unread `__start__` value, a pending
+`__start__` task) also appears on a fork of a plain `Pregel` graph's loop checkpoint, where
+treating it as an input hid a genuine failure. Matching the copy to an input checkpoint with
+identical channels and versions fails too. A `Pregel` input's first step can run a user node, so
+the original run is no baseline for the copy's run. And a no-op
+`update_state(..., as_node="__input__")` can write an input identical to a loop checkpoint. So
+the duplicate is left in place.
 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
@@ -497,9 +542,15 @@ unavailable, disclosing each on stderr; the producer's value is never kept. File
 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`.
+by a small per-file record (path, trace id); without it, by the matches it prints. Inside one
+trace, too, it keeps only the matches that still fit under `--limit`, but it still enumerates
+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
+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.
 
 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

{agent_tracegraph-0.5.0 → agent_tracegraph-0.6.0}/README.md

@@ -79,6 +79,7 @@ tracegraph presets                   # list cross-trace query patterns
 tracegraph query tool-failure A.json B.json   # find a causal pattern across many traces
 tracegraph query tool-retry-failure *.json    # explicit retry marker, then same tool failing
 tracegraph query tool-failure --backend ladybug A.json B.json   # use the optional Cypher accelerator
+tracegraph summarize tool-retry-failure traces/ -o motifs.json  # group matches by observed shape
 
 # export versioned, body-free governance evidence (an empty match set is a valid report)
 tracegraph export-review-candidates tool-retry-failure *.json -o candidates.json
@@ -99,7 +100,7 @@ Frequently-used options, beyond `--out` / `--json-out`:
 | `--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". |
+| `--strict` | `query`, `summarize`, `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
@@ -273,6 +274,37 @@ Every shipped preset has a stable `pattern_id` and positive integer `pattern_ver
 as `pattern-id@vN` by `presets` and `query`. Increment the version when match semantics or
 review-export eligibility changes; wording-only description edits keep the current version.
 
+`summarize` groups one preset's matches across the same file/directory batches. It is meant for
+deciding which recurring failure shape to look at first, without tallying `query` output by hand.
+A group is one observed shape. Two matches share a group when, for every matched step, the kind,
+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
+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
+no edge.
+Trace and step ids, error text and artifact file paths are never part of it. Names pass the same
+safe-v1 rule as `analyze` reports. An identifier-shaped name is kept even when it looks like a path or an
+address, and anything else becomes `redacted:<sha256>`. An operation whose name changes from run
+to run gets one group per name. Each group counts its matches and, separately, the traces they
+come from, and lists up to three representatives, each an artifact digest plus the matched step
+ids. Only *confirmed* matches are grouped, by the same rule as `check`. A match that relies on a
+substituted value (a defaulted kind, an unrecorded status) is counted as unconfirmed instead. A
+field that is not known is written as `null` and listed under the step's `unknown`, never by the
+value that stands in for it. The coverage section is always printed. It shows how many artifacts
+were discovered, valid and skipped; how many traces may hide a match (`check`'s per-preset rule);
+how many disclose any capture gap; how many carry no capture record; and the unconfirmed matches.
+None of it is a rate, and an empty result is not an all-clear. A group does not show a shared root
+cause. Version 1 accepts only strictly adjacent presets: between gap endpoints the matched path
+is not recorded, so `repeated-agent-failure`, `tool-repeat-failure-heuristic` and
+`tool-retry-failure-near` exit 2. `--out` writes the `tracegraph.motif-summary` schema-v1 JSON.
+It must not name an input, is excluded from directory discovery, and is left untouched when the
+run is refused. Exit 0 with at least one group, 1 with none (the report is still written), 2 on
+an input error.
+
 `export-review-candidates` accepts the same artifact-file/directory batches as `query` and
 writes a deterministic schema-v1 envelope. Only presets ending in a failing `TOOL` predicate
 are eligible. The matched endpoint name must already be a qualified `server::tool` key —
@@ -312,7 +344,7 @@ and any change to them is called out in the [changelog](CHANGELOG.md).
 | Area | What exists |
 |---|---|
 | Sources | LangGraph checkpoint savers (including subgraph namespaces and native task failures), OTLP/OpenInference span exports, Phoenix CLI exports |
-| Commands | `ingest`, `ingest-otlp`, `ingest-phoenix`, `inspect`, `validate`, `explain`, `diff`, `analyze`, `presets`, `query`, `export-review-candidates`, `export-incident-memo`, `phoenix doctor`, `phoenix diagnose` |
+| Commands | `ingest`, `ingest-otlp`, `ingest-phoenix`, `inspect`, `validate`, `explain`, `diff`, `analyze`, `presets`, `query`, `summarize`, `export-review-candidates`, `export-incident-memo`, `phoenix doctor`, `phoenix diagnose` |
 | Patterns | Versioned presets matched over the raw causal graph; the governance-eligible `tool-retry-failure@v2` requires an explicit producer retry marker, and repetition-only heuristics are query-only |
 | Backends | Pure-Python in-memory store (default); optional LadybugDB/Cypher accelerator (`[cypher]`), whose results must equal the pure-Python matcher's |
 | Ecosystem | SyncMill run correlation (`syncmill.run_id`), Toolgraph preflight evidence as non-causal metadata, a weekly Phoenix + SyncMill end-to-end workflow (Phoenix CLI and server pinned; SyncMill tracks its default branch) |
@@ -401,6 +433,19 @@ 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 checkpoint is an error where the channel first holds an error.
+An error the parent graph already held is not recorded again where a subgraph receives it, nor
+where the parent graph continues after a subgraph that did not carry it, and a fork copy
+(`update_state(..., as_node="__copy__")`), which runs no node, never records one.
+One time-travel shape still records an error twice: copying a subgraph's *input* checkpoint as a
+fork and resuming. The subgraph's next start records the error again, whether the parent graph
+held it (#90) or a `Send` payload carried it (#96). The copy holds the same channels as the input
+it copies but no link back to it. Each marker tried (an unread `__start__` value, a pending
+`__start__` task) also appears on a fork of a plain `Pregel` graph's loop checkpoint, where
+treating it as an input hid a genuine failure. Matching the copy to an input checkpoint with
+identical channels and versions fails too. A `Pregel` input's first step can run a user node, so
+the original run is no baseline for the copy's run. And a no-op
+`update_state(..., as_node="__input__")` can write an input identical to a loop checkpoint. So
+the duplicate is left in place.
 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
@@ -466,9 +511,15 @@ unavailable, disclosing each on stderr; the producer's value is never kept. File
 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`.
+by a small per-file record (path, trace id); without it, by the matches it prints. Inside one
+trace, too, it keeps only the matches that still fit under `--limit`, but it still enumerates
+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
+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.
 
 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

{agent_tracegraph-0.5.0 → agent_tracegraph-0.6.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.5.0"
+version = "0.6.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.6.0/src/tracegraph/_errors.py

@@ -0,0 +1,35 @@
+"""Describe an exception raised by code tracegraph does not control, without running more of it.
+
+A boundary that promises ``ValueError`` often names the exception it caught. Doing that runs the
+caller's code again: ``str(exc)`` calls its ``__str__``, and a metaclass can make the type's
+``__name__`` a property. Either can raise, or return a ``str`` subclass whose own methods raise
+while the message is built, and that error would escape in place of the ``ValueError``.
+"""
+
+from __future__ import annotations
+
+#: Stands in for a type name that cannot be read safely.
+_UNNAMED = "exception"
+
+
+def type_name(exc: BaseException) -> str:
+    """The exception's type name, or a fixed text when reading it fails or is not a plain str."""
+    try:
+        name = type(exc).__name__
+    except KeyboardInterrupt:
+        raise
+    except BaseException:
+        return _UNNAMED
+    return name if type(name) is str else _UNNAMED
+
+
+def describe(exc: BaseException) -> str:
+    """``"Type: message"``, or the type alone when the message is empty or cannot be read safely."""
+    name = type_name(exc)
+    try:
+        text = str(exc)
+        return f"{name}: {text}" if type(text) is str and text else name
+    except KeyboardInterrupt:
+        raise
+    except BaseException:  # the composition too: building the text can fail (MemoryError)
+        return name

{agent_tracegraph-0.5.0 → agent_tracegraph-0.6.0}/src/tracegraph/adapters/langgraph_checkpoint.py

@@ -96,6 +96,7 @@ from typing import Any, Iterable, Iterator, get_type_hints
 from langgraph.checkpoint.base import Checkpoint, CheckpointMetadata
 from pydantic import TypeAdapter, ValidationError
 
+from tracegraph._errors import describe, type_name
 from tracegraph.adapters.base import Disclosures
 from tracegraph.input_validation import object_field
 from tracegraph.model import (
@@ -260,6 +261,7 @@ class LangGraphCheckpointAdapter:
         original_seq: dict[str, int] = {}
         steps: dict[str, Step] = {}
         writes_by_step: dict[str, dict[str, list[tuple[str, Any]]]] = {}
+        launch_keys: dict[str, list[_CheckpointKey]] = {}
         malformed_writes = 0
         for t in tuples:
             cfg, cp, md, parent_cfg = _checked(t)
@@ -278,6 +280,7 @@ class LangGraphCheckpointAdapter:
             checkpoints[step_id] = cp
             original_seq[step_id] = md.get("step", 0)
             parent_keys[step_id] = self._declared_parent_keys(parent_cfg, md, ns)
+            launch_keys[step_id] = self._launch_parent_keys(md, ns)
             writes_by_step[step_id], malformed = self._writes_by_task(
                 getattr(t, "pending_writes", None)
             )
@@ -356,9 +359,23 @@ class LangGraphCheckpointAdapter:
                 # both stay display labels and are recorded as unknown, named or not. Task,
                 # interrupt and scheduled steps are named by LangGraph's own task ids instead.
                 step.unknown_fields = ["kind", "name"]
-            causal_parent_ids = parents_by_step.get(step_id, [])
-            error_parent_cps = [checkpoints[parent_id] for parent_id in causal_parent_ids]
-            err = self._error_introduced(checkpoints[step_id], error_parent_cps)
+            # An error is new here only if none of the states this checkpoint was built from held
+            # one, and the causal parents alone can miss them: exit-edge expansion replaces a
+            # same-namespace predecessor with a subgraph's exit, and the input checkpoint a
+            # ``__start__`` applies holds its values as pending writes, so that input's own
+            # parents (the namespace's previous invocation, and the checkpoint that launched the
+            # subgraph) stand in. A fork (``update_state(..., as_node="__copy__")``) copies an
+            # existing checkpoint and runs no node, so whatever error it holds is not new; it is
+            # linked to the copied checkpoint's parent, which need not hold that error.
+            upstream_keys = list(parent_keys.get(step_id, []))
+            if no_producer and step.source is StepSource.LOOP and display_parent_id is not None:
+                upstream_keys += [*parent_keys.get(display_parent_id, []),
+                                  *launch_keys.get(display_parent_id, [])]
+            upstream_ids = [*parents_by_step.get(step_id, []),
+                            *(pid for key in upstream_keys if (pid := step_id_by_key.get(key)))]
+            error_parent_cps = [checkpoints[pid] for pid in dict.fromkeys(upstream_ids)]
+            err = (None if step.source is StepSource.FORK
+                   else self._error_introduced(checkpoints[step_id], error_parent_cps))
             # Only a checkpoint a node wrote can disclose a rewrite: an input, an update and a
             # fork (``update_state(..., as_node="__copy__")`` copies state, linked to the copied
             # checkpoint's parent) carry what the caller supplied. The channel's own history is
@@ -669,9 +686,9 @@ class LangGraphCheckpointAdapter:
         except KeyboardInterrupt:
             raise
         except BaseException as exc:
-            text = str(exc)
-            reason = f"{type(exc).__name__}: {text}" if text else type(exc).__name__
-            raise ValueError(f"the supplied graph could not read checkpoint {cid}: {reason}") from exc
+            raise ValueError(
+                f"the supplied graph could not read checkpoint {cid}: {describe(exc)}"
+            ) from exc
         read = (snapshot.config or {}).get("configurable", {}).get("checkpoint_id")
         if read != cid:
             raise ValueError(
@@ -794,7 +811,12 @@ class LangGraphCheckpointAdapter:
             seed = unhexlify(cid.replace("-", ""))
         except (BinasciiError, AttributeError, ValueError):
             return None
-        joined = b"".join(part.encode() for part in parts)
+        try:
+            joined = b"".join(part.encode() for part in parts)
+        except UnicodeEncodeError:
+            # A lone surrogate has no UTF-8 encoding, so LangGraph could not have hashed this
+            # candidate into any recorded task id. It names nothing; it must not end the ingest.
+            return None
         if legacy:
             digest = sha1(seed, usedforsecurity=False)
             digest.update(joined)
@@ -943,6 +965,13 @@ class LangGraphCheckpointAdapter:
             parent_ns = parent_cfg.get("checkpoint_ns", ns) or _ROOT_NS
             return [(parent_ns, parent_id)]
 
+        return LangGraphCheckpointAdapter._launch_parent_keys(md, ns)
+
+    @staticmethod
+    def _launch_parent_keys(md: dict, ns: str) -> list[_CheckpointKey]:
+        """The closest enclosing-graph checkpoint named in ``metadata.parents``: for a subgraph,
+        the checkpoint it was launched from, recorded even when ``parent_config`` points at
+        the namespace's previous invocation instead."""
         # `_checked` has already established `parents` as a str -> str mapping.
         parents = md.get("parents") or {}
         closest = LangGraphCheckpointAdapter._closest_parent_ns(ns, parents)
@@ -1222,7 +1251,7 @@ def _decoded(listing: Iterable[Any]) -> Iterator[Any]:
             return
         except Exception as exc:
             raise ValueError(
-                f"checkpoint history cannot be decoded ({type(exc).__name__})"
+                f"checkpoint history cannot be decoded ({type_name(exc)})"
             ) from exc
         yield item
 

{agent_tracegraph-0.5.0 → agent_tracegraph-0.6.0}/src/tracegraph/adapters/otlp_spans.py

@@ -73,6 +73,7 @@ from tracegraph.model import (
     StepSource,
     StepStatus,
     Trace,
+    cost_is_bounded,
     UnknownField,
 )
 
@@ -255,7 +256,9 @@ def _as_decimal(value: Any) -> str | None:
         parsed = Decimal(str(value))
     except InvalidOperation:
         return None
-    return format(parsed, "f") if parsed.is_finite() and parsed >= 0 else None
+    if not (parsed.is_finite() and parsed >= 0 and cost_is_bounded(parsed)):
+        return None
+    return format(parsed, "f")
 
 
 def _as_currency(value: Any) -> str | None:

{agent_tracegraph-0.5.0 → agent_tracegraph-0.6.0}/src/tracegraph/analysis/check.py

@@ -37,6 +37,7 @@ from tracegraph.model import (
     NormalizedTrace,
     Step,
     StepStatus,
+    _validated_copy,
 )
 from tracegraph.normalize import ProjectionRule, validate_normalized
 
@@ -540,6 +541,7 @@ def _topology_rule(
 
 def evaluate(current: NormalizedTrace, baseline: NormalizedTrace, rules: list[RuleSpec]) -> CheckReport:
     """Evaluate ``rules`` over the pair. Raises ``ValueError`` for a malformed trace."""
+    current, baseline = _validated_copy(current), _validated_copy(baseline)
     contexts = (_context(current), _context(baseline))
     common = _common_reasons(current, baseline)
     langgraph = "langgraph" in (current.trace.source_kind, baseline.trace.source_kind)