agent-tracegraph 0.2.0__tar.gz → 0.3.1__tar.gz

agent_tracegraph-0.3.1/CHANGELOG.md

@@ -0,0 +1,329 @@
+# Changelog
+
+All notable changes to Tracegraph are documented here.
+
+The **artifact** schema version and the **report**/**review-candidate** JSON schemas are
+separate contracts from this version number; changes to any of them are called out
+explicitly.
+
+## 0.3.1 - 2026-10-13
+
+### Fixed
+
+- **An unreadable cost no longer understates the run's total.** The importers dropped a
+  `llm.cost.total` that was not a finite non-negative decimal (`"abc"`, `-1`, a boolean), so
+  `analyze` summed the remaining costs and printed a total that was knowably too low, with no
+  warning. The documented rule that a single unparseable cost withholds the whole total only
+  applied to artifacts built by hand. An unreadable total cost is now stored as the fixed
+  marker `"unreadable"`, never the producer's value, and the report withholds `total_cost`
+  and its delta with the existing note.
+- Token counts, prompt and completion costs, cost currencies and Phoenix evaluation scores
+  that cannot be read were dropped without a trace. They are still reported as unavailable,
+  and `ingest-otlp`, `ingest-phoenix`, `analyze` and `phoenix diagnose` now say so on stderr,
+  naming the kind of value and how many spans (for scores, evaluations) carried it, never
+  the value itself. A boolean score still reads as `1.0` or `0.0`, as before.
+- An OTLP `intValue` sent as a fractional JSON number was truncated before validation:
+  `1.5` became `1` and `-0.5` became `0`, so an invalid token count looked valid. It is now
+  validated as sent.
+- **A checkpoint history LangGraph could not have written is a usage error, not a
+  traceback or a different trace.** About half of 64 one-field mutations of a real history
+  (a non-object `metadata` or `channel_values`, a numeric `checkpoint_ns`, a boolean `v`, an
+  unhashable parent checkpoint id, ...) crashed `ingest` with a traceback, and several were
+  read silently as something else: a malformed parent config or `metadata.parents` dropped
+  the declared parent and made the checkpoint a root, and `metadata.step` of `true` or `1.5`
+  was read as step 1. Each checkpoint is now checked against the types LangGraph declares
+  for the fields tracegraph reads, strictly, and rejected with a message naming the field.
+  A config `checkpoint_id` that disagrees with the checkpoint's own id is rejected too.
+- A checkpoint row the saver cannot decode (an unknown serialization type, metadata nested
+  past the recursion limit, a non-string metadata column) crashed `ingest` and `discover`
+  with a traceback, except that `discover` reported an unknown serialization type as "does
+  not support listing all threads". Both now report the history as undecodable.
+- Pending writes that are not a `(task id, channel, value)` triple were skipped without a
+  word, and any 3-character string was unpacked as one (`"abc"` became task `a`). They are
+  still ignored, but `ingest` now says how many on stderr, since one could have carried a
+  task failure.
+
+### Compatibility notes for imports
+
+- An artifact imported from a span with an unreadable total cost now carries
+  `"total_cost": "unreadable"` instead of no cost, and its reports withhold the run's
+  total cost. No schema change: 0.3.0 reads such an artifact and withholds the same way.
+- Because `intValue` is no longer truncated, `llm.cost.total = {"intValue": 1.5}` is stored as
+  `"1.5"` instead of `"1"`, and a `toolgraph.graph_generation` of `{"intValue": 1.5}` is
+  rejected like any other invalid generation instead of being read as `1`.
+- The committed Phoenix fixture carries an unreadable `llm.cost.prompt`; reading it now prints
+  one stderr disclosure. Every committed fixture's artifact, report, memo, candidate file and
+  CLI stdout is unchanged.
+- LangGraph histories that `ingest` used to accept with a malformed field listed above are
+  now refused. Histories written by LangGraph's own savers are unaffected: the checks cover
+  only fields tracegraph reads (`counters_since_delta_snapshot`, which savers return as
+  lists although it is declared as tuples, is not checked), a missing `updated_channels`
+  and a legacy `pending_sends` are accepted, and an unknown `metadata.source` string still
+  reads as a loop. The committed LangGraph fixture is byte-identical.
+
+## 0.3.0 - 2026-10-13
+
+### Fixed
+
+- An artifact whose content was not canonical (for example a stored trace status that
+  disagreed with its steps) was stamped `schema_version` 4 even when it carried no edge
+  origins. Version 4 is now stamped only when the file's TREE_PARENT edges are the
+  origin-priority projection of its causal edges and that differs from the temporal one; the
+  rest of the trace does not affect the stamp. **Digest impact:** canonical artifacts are
+  unchanged, but re-serializing a non-canonical trace (one `validate` rejects) whose tree is
+  not the origin-priority one, such as a trace with its derived edges missing, now writes
+  version 2 or 3 instead of 4. Any digest computed from that re-serialization changes,
+  including the `artifact_digest` that `analyze` reports for such a trace.
+- Loading now rejects an envelope that understates its content: a `schema_version` 2 file
+  holding an origin-priority projection or derived task steps. Every reader that trusts the
+  envelope would have read such a file under the wrong rules, and a re-save rewrote it as a
+  different file. An envelope may still overstate what its content needs.
+- `schema_version` must be an integer. `true`, `1.0`, `2.0` and `4.0` were accepted because
+  they compare equal, and `true` was migrated as a version 1 file.
+- Evidence floats (`duration_ms`, evaluation `score`) must be finite, and the writer refuses
+  to emit `NaN`/`Infinity`, which are not JSON.
+- `--backend ladybug` crashed with a raw traceback on a step `seq` outside the INT64 range
+  the backend stores. It now exits with a usage error naming the limit.
+- `InMemoryStore.upsert_edges` accepted a `CAUSED_BY`/`TREE_PARENT` edge whose endpoint was
+  not a stored step, or a `BELONGS_TO` edge pointing at another trace; the failure surfaced
+  later as a `KeyError` from `ancestors`. It now raises `ValueError` and inserts nothing from
+  that batch, matching the LadybugDB store. `WROTE`/`READ` channel edges are unchecked as
+  before, and node upsert still replaces by ID.
+- OTLP and Phoenix imports crashed with a raw traceback on a timestamp of `Infinity`, `NaN`
+  or a number beyond the representable date range, on a `spanId`/`parentSpanId` given as a
+  list, and on Phoenix `annotations` that were not an array. A timestamp that cannot be read
+  — including garbage text, which was silently dropped before — is now reported as
+  unavailable and disclosed on stderr by `ingest-otlp`, `ingest-phoenix`, `analyze` and
+  `phoenix diagnose`. Malformed ids and annotations are rejected with a usage error.
+- An OTLP `status.code` of `true` was read as OK because `true == 1`, and `false` as UNSET
+  because `false == 0`; both are now rejected, for OTLP and Phoenix imports alike.
+- LangGraph: two derived task steps could receive the same id (checkpoint `A` with task
+  `x#task:y`, checkpoint `A#task:x` with task `y`); the second silently replaced the first
+  and gained a second cause it never had. The collision is now rejected like a collision
+  with a checkpoint.
+- LangGraph: a failed task that no candidate node reproduces is still reported unnamed, and
+  the read now says so on stderr. An unnamed failure is also what a change in LangGraph's
+  task-id algorithm would look like, so it is no longer silent.
+
+- `diff` and `validate` printed producer text through Rich markup: a step named
+  `tool[bold]` showed as `tool`, and an invalid edge naming `ghost[red]X[/red]` showed as
+  `ghostX`. Both now print the text literally, as `inspect`, `explain` and `query` already
+  did. Output paths are printed literally too: an `--out` path containing `[/]` used to
+  raise a markup error after the file had been written, so the command exited 1 for work
+  it had completed.
+- `diff --structure` paired any two leftover subtrees because every label is empty under
+  that option, then reported them under an empty path (`only in B under  > : subtree ·`).
+  An empty label is no longer treated as evidence of correspondence, and the reported
+  subtrees now show step names so they can be found, while the comparison still ignores
+  them. The identical/not-identical verdict and exit code are unchanged.
+- `explain` and `query --explain` labeled a nameless step by its `source`, which for
+  OTLP and Phoenix spans is always `loop` and for LangGraph is checkpoint metadata
+  (`input`, `loop`), not what the step was. They now use the step kind, like every other
+  view.
+- `export-incident-memo` wrote `links_preserved` as `true`/`false`/`null` in its front
+  matter but as `True`/`False`/`None` in its summary. Both now use the front-matter form.
+- The Phoenix CLI version-floor message is derived from the floor constant instead of
+  repeating it.
+
+- `analyze --baseline` published token deltas, and cost deltas, from totals that covered
+  only some steps on one side: with tokens on 3 of 3 steps in the baseline and 1 of 3 in
+  the current run it reported `-200`, although the silent steps could have used any amount.
+  Like the duration delta, these deltas are now withheld with a note unless every step on
+  both sides reports the metric. In traces where only model calls carry token counts this
+  withholds the token delta. A cost total or delta withheld because steps or runs report
+  different or unknown currencies is now disclosed too; before, `analyze` printed
+  `cost=unavailable` with no reason.
+
+- Writing an artifact or an analysis report left a hidden temporary file behind when the
+  write or fsync failed, because the temporary name was recorded only after writing. All
+  four output writers now share one helper that removes it on every failure.
+
+### Compatibility notes for imports
+
+These change what an input that imported successfully before now produces or whether it
+imports at all. No committed fixture is affected.
+
+- An OTLP token count given as a boolean (`true`, or `{"intValue": true}`) was stored as `1`;
+  it is now unavailable, matching how an unusable cost is already treated. A non-finite
+  token count is unavailable too instead of crashing the import. An `intValue` holding a
+  boolean is no longer converted to `0`/`1` for any attribute.
+- Raw OTLP input could inject evaluation summaries through the private
+  `_tracegraph_evaluations` span key, bypassing the length limit the Phoenix importer
+  applies. Only the Phoenix importer reads that key now.
+- An empty-string `traceId` or `spanId` is rejected. A `parentSpanId` of `0`, `false` or
+  `[]` used to be read as "no parent", which made a span with a malformed declared parent a
+  root; it is now rejected. A missing, `null` or empty-string `parentSpanId` still marks a
+  root span.
+- A Phoenix evaluation score too large to represent crashed the import; it is now
+  unavailable, like a non-finite score.
+- When several spans carry the `graph.node.parent_id` a span declares (a loop), the importer
+  picks the nearest execution that started earlier. A span with a missing or unreadable
+  start time sorted as time 0 and could win that choice, so a timestamp nobody recorded
+  decided a causal edge. Such spans no longer take part: the choice is treated as
+  ambiguous, and the span falls back to its declared `parentSpanId`, or the import is
+  rejected if it has none.
+- The CLA workflow refused every pull request from the maintainer's own commit-author
+  account, which is not the account that owns the repository. Both are allowlisted now.
+- The release documentation asked for a personal access token with *read* access to pull
+  requests. Posting the CLA comment failed with that configuration and succeeded after
+  raising it to write; the cause remains unconfirmed, since GitHub documents either Issues
+  write or Pull requests write as sufficient. The documentation now asks for write on
+  Contents, Issues and Pull requests alike and records the observation rather than
+  inferring a rule.
+- It also did not say that a Trusted Publisher's "Environment name" is the GitHub
+  environment rather than the index, which failed the first 0.2.0 rehearsal.
+
+### Dependencies
+
+- The optional `[cypher]` extra now accepts LadybugDB `>=0.18,<0.22` (was `<0.19`), and the
+  lockfile moves to 0.21.2. The full test suite and every fixture's output are unchanged
+  on 0.21.2.
+- CI now tests against Phoenix CLI 1.18.8 (was 1.8.1). The runtime floor stays 1.0.4: this
+  pin is what CI proves, not what tracegraph requires.
+
+### Added
+
+- `tracegraph export-incident-memo <artifact> -o memo.md` writes a Markdown post-mortem
+  intended for long-term memory stores. Its output is a strict allowlist: the run id appears
+  only as a truncated SHA-256 `run_digest`, steps appear as `step_<n>_<kind>` aliases, and
+  no step name, error message, evaluation label or payload is written. Edges that only show
+  containment or have no recorded origin are rendered as "preceded by", never "caused by".
+  The memo carries the SHA-256 of the exact artifact bytes it was built from.
+
+### Changed
+
+- **Artifact schema version 4.** When a step has several causes, its single TREE_PARENT is
+  now chosen by edge origin first — a declared graph or checkpoint parent over span
+  containment, over a span link, over an unknown origin — and only then by time. An artifact
+  whose tree differs from the purely temporal choice is stamped version 4; every other
+  artifact serializes as version 2 or 3, byte for byte as before. **Readers from 0.2.0 and
+  older refuse version 4 files** with an explicit unsupported-version error. This build reads
+  both projections, and the LadybugDB store re-emits a legacy file unchanged. The derived
+  tree feeds `inspect`, `diff`, and `analyze --baseline`, where it decides both the topology
+  changes and how steps are matched between the two runs: a step whose tree parent moved
+  can now appear as one removed and one added behavior change, and its logical step key
+  changes. Raw causal queries (`explain`, `query`) are unaffected.
+- Phoenix timestamps without a timezone are now read as UTC rather than in the local
+  timezone of the machine running the import. **Digest impact:** artifacts built from such
+  exports now hash the same on every machine, and differ from any artifact previously built
+  where the local timezone applied a nonzero offset to those timestamps. Timestamps that
+  carry a `Z` or an offset are unchanged.
+- **Phoenix artifacts no longer carry free-text annotation names or labels.** The Phoenix
+  import is documented as body-free and already kept only identifier-shaped span names, but
+  annotation names and labels were kept as free text (whitespace-collapsed, cut to 200
+  characters), so an evaluator's note such as `user said: my password is hunter2` reached
+  the artifact. They now pass the same identifier filter as span names: an evaluation whose
+  name fails it is dropped, and a label that fails it becomes `null` while the score is
+  kept. **Artifact content change:** a re-import of a Phoenix export with such annotations
+  produces different bytes and digests. Identifier-shaped text, which can still be personal
+  data such as an e-mail address, is kept.
+
+## 0.2.0 - 2026-09-12
+
+First published release. `0.1.0` was tagged but never uploaded.
+
+### Fixed
+
+- **A LangGraph node that raised an exception was reported as a successful run**
+  (`status=ok`, `error_count=0`). LangGraph does not route such a failure through a state
+  channel: it records it in the checkpoint's pending writes and writes no further checkpoint,
+  so reading channel values alone could not see it and no `--error-channel` value recovered
+  it. Each failed task now becomes its own step, hanging off the checkpoint that scheduled it
+  rather than marking that checkpoint — which is named after the node that *produced* it, so
+  marking it reported the wrong node.
+- A task cancelled because a *sibling* failed is no longer counted as a second failure.
+  LangGraph records sibling cancellation through the same `__error__` channel as a genuine
+  fault; those tasks are reported as `unset` with no message, so one fault stays one failure
+  and a healthy node is never a primary candidate.
+
+### Security
+
+- **Reading a checkpoint database no longer executes what it contains.** LangGraph's
+  deserializer revives stored objects by importing a module and calling a name, both taken
+  from the payload, and by default an unrecognized target is logged and then called — so a
+  crafted checkpoint naming `os.system` or `subprocess.run` ran on the machine doing the
+  analysis (both verified against the pinned dependency). `tracegraph ingest` now passes a
+  serializer with an empty allowlist.
+
+  **Behaviour change:** objects outside the framework's registered types no longer revive
+  through `ingest`; they come back as their raw arguments. If you were relying on a custom
+  class being reconstructed from checkpoint state, it will now surface as plain data.
+  Constructing `LangGraphCheckpointAdapter` yourself is unaffected — the serializer is
+  whichever one your saver carries.
+
+### Added
+
+- The failing node's name, recovered by recomputing LangGraph's task id from checkpoint data.
+  The match is self-verifying, so a task nothing identifies keeps no name rather than
+  borrowing a neighbour's.
+- `StepSource.TASK`, marking a step derived from pending writes rather than from a checkpoint.
+- `RawTrace.ingest_warnings`, printed by `ingest` to stderr — disclosures about the *read*
+  (for example `Send` packets that could not be decoded), which are not part of the run and so
+  never enter the artifact.
+- First public release metadata: Apache-2.0 `LICENSE`, `CLA.md`, `CODE_OF_CONDUCT.md`,
+  `CONTRIBUTING.md`, `SECURITY.md`, and PyPI classifiers, keywords, authors and project URLs.
+- `tracegraph --version` (`-V`), which prints the bare version and nothing else. There was no
+  way to ask an installed build what it was.
+- An sdist allowlist. Previously the source distribution shipped everything git tracked —
+  tests, docs, CI workflows, the lockfile and the checkpoint fixtures.
+- A tag-triggered release workflow publishing through PyPI Trusted Publishing: `test-v*`
+  rehearses against TestPyPI, `v*` publishes to PyPI. Only the publishing job holds an OIDC
+  token, and it checks out nothing, installs nothing, and uploads only files whose digests
+  match what the build job recorded. Before any of that, the build refuses a tag whose
+  commit is not on the default branch, has no green `tests` run of its own, disagrees with
+  the packaged version, or has no dated changelog entry.
+- `scripts/verify_artifacts.py`, which checks that the built distributions are exactly the
+  two files that will be uploaded and that the source distribution carries only what the
+  packaging allowlist intends. It also refuses tests, docs, CI configuration and the
+  lockfile outright, so widening that allowlist cannot quietly start shipping them, and
+  refuses any archive member whose path does not go where it reads — a `..` segment is
+  what would let a member satisfy both lists and still land somewhere else, or outside
+  the archive entirely, when someone extracts it.
+- `scripts/require_ci_success.py`, the release gate described above.
+- A [release runbook](docs/releasing.md) and a
+  [public release checklist](docs/public-release-checklist.md).
+- The installed-wheel CI jobs now pin the version they expect and run the artifact
+  verifier, so the release checks are exercised on every pull request rather than first at
+  tag time.
+
+### Changed
+
+- **The distribution is now `agent-tracegraph`.** The plain `tracegraph` name on PyPI belongs
+  to an unrelated project. The import package, the console script, the schema `kind`
+  constants and the `TRACEGRAPH_*` environment variables are **unchanged** — only the name
+  you install differs. Installing from source or from a checkout is unaffected.
+- The build backend version is pinned (`hatchling==1.32.0`), so a release rehearsal and the
+  production tag cannot run *different backend versions* against the same commit. This is
+  drift control, not reproducibility: hatchling's own dependencies still float. The uv
+  version used to build is pinned in the same way.
+- `twine check` is a gate again, pinned to `twine@7.0.0`. It was disabled because twine 6
+  rejected the `Metadata-Version: 2.5` this backend emits; twine 7 accepts it.
+- **Artifact schema version 3**, stamped *by content*: an artifact carrying derived task steps
+  declares 3 so an older reader refuses it by name instead of failing on an enum, while
+  artifacts without them still serialize as version 2 byte for byte. The envelope is inside
+  the digest `export-review-candidates` binds to, so a blanket bump would have invalidated
+  digests already published for unchanged artifacts.
+- The LangGraph capture disclosure in every report now names both the error channel and task
+  pending writes. It remains unconditional: an artifact ingested by an older build, or one
+  using an unrecognized checkpoint layout, carries no derived step and is indistinguishable
+  from a genuinely clean run.
+- `xxhash` is now a direct runtime dependency (LangGraph hashes task ids with it, but
+  `langgraph` itself is only a development dependency here).
+- `langgraph-checkpoint>=4.1` is now declared directly rather than left transitive, because
+  ingestion calls its serializer API. `allowed_msgpack_modules` does not exist before 4.1
+  (4.0.0 raises `TypeError`), so the floor is what makes the hardening above guaranteed
+  rather than incidental.
+
+### Known limitations
+
+- Tasks that were *scheduled but never committed* — a run paused by `interrupt()`, stopped by
+  the recursion limit, or killed — are not reported. Trace `status` still means "did a step
+  error", so such a run reports `ok`.
+- Only the latest persisted error survives per task, so repeated attempts are not
+  reconstructed.
+- `Send` packets can only be named where `langgraph.types` is importable; an ordinary install
+  has only the `langgraph.checkpoint` half of that namespace, and the gap is disclosed.
+
+## 0.1.0 - 2026-05-30
+
+Tagged but never published. Initial read-path causal-graph analysis of LangGraph agent traces.

{agent_tracegraph-0.2.0 → agent_tracegraph-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-tracegraph
-Version: 0.2.0
+Version: 0.3.1
 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
@@ -26,7 +26,7 @@ Requires-Dist: rich>=13
 Requires-Dist: typer>=0.12
 Requires-Dist: xxhash>=3
 Provides-Extra: cypher
-Requires-Dist: ladybug<0.19,>=0.18; extra == 'cypher'
+Requires-Dist: ladybug<0.22,>=0.18; extra == 'cypher'
 Description-Content-Type: text/markdown
 
 # tracegraph
@@ -110,6 +110,9 @@ tracegraph query tool-failure --backend ladybug A.json B.json   # use the option
 
 # 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
+
+# export an allowlisted incident post-mortem (Markdown) for a long-term memory store
+tracegraph export-incident-memo A.json -o incident.md
 ```
 
 Frequently-used options, beyond `--out` / `--json-out`:
@@ -273,17 +276,27 @@ result, blast radius, preflight result, or graph state.
 
 ## Status
 
-**MVP works** — LangGraph/Phoenix/OTLP ingest plus inspect, explain, analyze, diff, and query.
+Alpha (`0.x`): the artifact, report and review-candidate formats are versioned contracts,
+and any change to them is called out in the [changelog](CHANGELOG.md).
 
-- **Phase 0 (frozen contract):** `RawTrace` vs `NormalizedTrace`, portable JSON artifact (system of record), `validate_raw` → projection → `validate_tree`/`validate_normalized`, in-memory store, `explain`.
-- **Phase 1 (ingestion):** `LangGraphCheckpointAdapter` reads any `BaseCheckpointSaver`, including subgraph checkpoint namespaces, and reconstructs declared checkpoint parentage; `examples/tiny_agent.py` generates real traces.
-- **Phase 2 (analysis + CLI):** AHU rooted-tree diff and the Typer CLI.
-- **Phase 3 (cross-trace queries):** backend-neutral `PathPattern` matcher over the raw causal graph + `query`/`presets` CLI — pure-Python, proving the "graph queries" value before any Cypher backend. The official `tool-retry-failure@v2` requires an explicit producer marker; variable-length **gaps** and **back-references** (`same_name_as`) remain available for query-only heuristics. Uncompilable unbounded patterns degrade honestly rather than truncate.
-- **Phase 5 (OTLP/OpenInference adapter):** `OTLPSpanAdapter` ingests Collector JSON/JSONL spans into the same causal model — the source that exercises full link-preserving raw/derived causality.
-- **Phoenix diagnosis:** `PhoenixExportAdapter`, `analyze`, and `phoenix diagnose` provide body-free automatic failure selection, retry detection, telemetry/evaluation summaries, and explicit parent-only fidelity warnings.
-- **Phase 6 (optional Cypher backend):** `agent-tracegraph[cypher]` ships a `LadybugStore` that compiles the **same** `PathPattern` spec to Cypher (`compile_to_cypher`); equivalence with the pure-Python matcher is the test contract, so the Cypher path is an accelerator, never a second source of truth.
-- **Ecosystem T3/P4 review slice:** OTLP `syncmill.run_id` correlation, versioned presets, deterministic body-free `export-review-candidates`, SyncMill human-review board intake, Toolgraph G3 artifact annotation, and the pinned live single-failure review path are complete. Explicit retry causality and SyncMill-to-Phoenix streaming are covered by the controlled E2E workflow; broader operational coverage remains separate.
-- **SyncMill contract completion:** route/pipeline/compete/council/decompose plus cancellation fixtures, stable span naming, body-free artifact digests, fail-open exporter reference behavior, operational failure presets, and non-causal Toolgraph preflight evidence are covered by executable tests.
+| 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` |
+| 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) |
+
+Known limits:
+
+- A LangGraph task that was scheduled but left no result and no recorded error (a run
+  paused by `interrupt()`, stopped by the recursion limit, or killed) is not reported, so
+  such a run reads `ok` unless some other step recorded an error.
+- 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 error messages.
+- CI covers Python 3.12 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
@@ -328,14 +341,30 @@ with deterministic SHA-256 aliases, and disclose in `warnings` when an alias act
 the report. Trace/step identifiers remain; this is not anonymization.
 Raw artifact names and bytes are not rewritten for report privacy or matching, so the
 artifact — unlike the report — can still carry whatever the producer put in a span name or
-error message (Phoenix ingestion excepted; it filters at the source).
+error message. Phoenix ingestion is the exception: it filters at the source, keeping span
+names and annotation names and labels only when they are identifier-shaped, and dropping
+status messages. Identifier-shaped is not the same as anonymous: an e-mail address passes.
 `export-review-candidates` output is not passed through the report redactor: its `tool_key`
-is the raw endpoint span name. Logical
+is the raw endpoint span name. `export-incident-memo` goes further than `safe-v1`: it writes
+no step names, error messages or evaluation labels at all. Steps appear as kind-based
+aliases and the run id as a truncated digest; the rest is structural metadata such as trace
+status, causal fidelity, step and error counts, preset pattern ids and versions, edge
+origins, fidelity disclosures, and the digest of the exact artifact bytes. Logical
 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.
 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
+type makes it `error` in both importers) is read differently by source. `ingest-otlp`
+records it as `ok`, because UNSET is OpenTelemetry's default status and producers such as
+SyncMill leave successful spans unset. Phoenix ingestion keeps it as `unset`. Trace status
+is the same either way, but step statuses differ wherever they are shown, and a preset that
+requires an `ok` step does not match an unset one: a SyncMill run where an agent attempt
+left UNSET directly causes a failing `gate:` tool reports `gate-failure-after-success`
+through `ingest-otlp` and not through Phoenix. Compare a run with a baseline from the same
+source; mixing them can report a step whose status differs only by source as a behavior
+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
@@ -346,9 +375,11 @@ borrowing a neighbour's name. When one task raises, LangGraph
 cancels its siblings and records that through the same channel; a cancelled task is reported
 as an `unset` step with no message, because it was torn down rather than at fault. Only the
 latest persisted error survives per task, so repeated attempts are not reconstructed, and
-`Send` packets are nameable only where `langgraph.types` is importable — an ordinary install discloses them instead. An artifact carrying derived task
-steps declares artifact `schema_version` 3, so an older reader refuses it by name; artifacts
-without them still serialize as version 2, byte for byte. Missing observed errors still do not
+`Send` packets are nameable only where `langgraph.types` is importable — an ordinary install
+discloses them instead. An artifact whose derived tree relies on EdgeOrigin precedence declares
+artifact `schema_version` 4; otherwise, an artifact carrying derived task steps declares
+`schema_version` 3, and artifacts without them still serialize as version 2, byte for byte.
+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
@@ -356,7 +387,10 @@ means valid in-trace links only. Structural diff compares the derived tree and d
 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. File input has a size limit, but stdin/Phoenix
+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.
 
 Both stores isolate returned mutable objects. InMemory node upsert replaces by ID;

{agent_tracegraph-0.2.0 → agent_tracegraph-0.3.1}/README.md

@@ -79,6 +79,9 @@ tracegraph query tool-failure --backend ladybug A.json B.json   # use the option
 
 # 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
+
+# export an allowlisted incident post-mortem (Markdown) for a long-term memory store
+tracegraph export-incident-memo A.json -o incident.md
 ```
 
 Frequently-used options, beyond `--out` / `--json-out`:
@@ -242,17 +245,27 @@ result, blast radius, preflight result, or graph state.
 
 ## Status
 
-**MVP works** — LangGraph/Phoenix/OTLP ingest plus inspect, explain, analyze, diff, and query.
+Alpha (`0.x`): the artifact, report and review-candidate formats are versioned contracts,
+and any change to them is called out in the [changelog](CHANGELOG.md).
 
-- **Phase 0 (frozen contract):** `RawTrace` vs `NormalizedTrace`, portable JSON artifact (system of record), `validate_raw` → projection → `validate_tree`/`validate_normalized`, in-memory store, `explain`.
-- **Phase 1 (ingestion):** `LangGraphCheckpointAdapter` reads any `BaseCheckpointSaver`, including subgraph checkpoint namespaces, and reconstructs declared checkpoint parentage; `examples/tiny_agent.py` generates real traces.
-- **Phase 2 (analysis + CLI):** AHU rooted-tree diff and the Typer CLI.
-- **Phase 3 (cross-trace queries):** backend-neutral `PathPattern` matcher over the raw causal graph + `query`/`presets` CLI — pure-Python, proving the "graph queries" value before any Cypher backend. The official `tool-retry-failure@v2` requires an explicit producer marker; variable-length **gaps** and **back-references** (`same_name_as`) remain available for query-only heuristics. Uncompilable unbounded patterns degrade honestly rather than truncate.
-- **Phase 5 (OTLP/OpenInference adapter):** `OTLPSpanAdapter` ingests Collector JSON/JSONL spans into the same causal model — the source that exercises full link-preserving raw/derived causality.
-- **Phoenix diagnosis:** `PhoenixExportAdapter`, `analyze`, and `phoenix diagnose` provide body-free automatic failure selection, retry detection, telemetry/evaluation summaries, and explicit parent-only fidelity warnings.
-- **Phase 6 (optional Cypher backend):** `agent-tracegraph[cypher]` ships a `LadybugStore` that compiles the **same** `PathPattern` spec to Cypher (`compile_to_cypher`); equivalence with the pure-Python matcher is the test contract, so the Cypher path is an accelerator, never a second source of truth.
-- **Ecosystem T3/P4 review slice:** OTLP `syncmill.run_id` correlation, versioned presets, deterministic body-free `export-review-candidates`, SyncMill human-review board intake, Toolgraph G3 artifact annotation, and the pinned live single-failure review path are complete. Explicit retry causality and SyncMill-to-Phoenix streaming are covered by the controlled E2E workflow; broader operational coverage remains separate.
-- **SyncMill contract completion:** route/pipeline/compete/council/decompose plus cancellation fixtures, stable span naming, body-free artifact digests, fail-open exporter reference behavior, operational failure presets, and non-causal Toolgraph preflight evidence are covered by executable tests.
+| 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` |
+| 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) |
+
+Known limits:
+
+- A LangGraph task that was scheduled but left no result and no recorded error (a run
+  paused by `interrupt()`, stopped by the recursion limit, or killed) is not reported, so
+  such a run reads `ok` unless some other step recorded an error.
+- 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 error messages.
+- CI covers Python 3.12 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
@@ -297,14 +310,30 @@ with deterministic SHA-256 aliases, and disclose in `warnings` when an alias act
 the report. Trace/step identifiers remain; this is not anonymization.
 Raw artifact names and bytes are not rewritten for report privacy or matching, so the
 artifact — unlike the report — can still carry whatever the producer put in a span name or
-error message (Phoenix ingestion excepted; it filters at the source).
+error message. Phoenix ingestion is the exception: it filters at the source, keeping span
+names and annotation names and labels only when they are identifier-shaped, and dropping
+status messages. Identifier-shaped is not the same as anonymous: an e-mail address passes.
 `export-review-candidates` output is not passed through the report redactor: its `tool_key`
-is the raw endpoint span name. Logical
+is the raw endpoint span name. `export-incident-memo` goes further than `safe-v1`: it writes
+no step names, error messages or evaluation labels at all. Steps appear as kind-based
+aliases and the run id as a truncated digest; the rest is structural metadata such as trace
+status, causal fidelity, step and error counts, preset pattern ids and versions, edge
+origins, fidelity disclosures, and the digest of the exact artifact bytes. Logical
 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.
 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
+type makes it `error` in both importers) is read differently by source. `ingest-otlp`
+records it as `ok`, because UNSET is OpenTelemetry's default status and producers such as
+SyncMill leave successful spans unset. Phoenix ingestion keeps it as `unset`. Trace status
+is the same either way, but step statuses differ wherever they are shown, and a preset that
+requires an `ok` step does not match an unset one: a SyncMill run where an agent attempt
+left UNSET directly causes a failing `gate:` tool reports `gate-failure-after-success`
+through `ingest-otlp` and not through Phoenix. Compare a run with a baseline from the same
+source; mixing them can report a step whose status differs only by source as a behavior
+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
@@ -315,9 +344,11 @@ borrowing a neighbour's name. When one task raises, LangGraph
 cancels its siblings and records that through the same channel; a cancelled task is reported
 as an `unset` step with no message, because it was torn down rather than at fault. Only the
 latest persisted error survives per task, so repeated attempts are not reconstructed, and
-`Send` packets are nameable only where `langgraph.types` is importable — an ordinary install discloses them instead. An artifact carrying derived task
-steps declares artifact `schema_version` 3, so an older reader refuses it by name; artifacts
-without them still serialize as version 2, byte for byte. Missing observed errors still do not
+`Send` packets are nameable only where `langgraph.types` is importable — an ordinary install
+discloses them instead. An artifact whose derived tree relies on EdgeOrigin precedence declares
+artifact `schema_version` 4; otherwise, an artifact carrying derived task steps declares
+`schema_version` 3, and artifacts without them still serialize as version 2, byte for byte.
+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
@@ -325,7 +356,10 @@ means valid in-trace links only. Structural diff compares the derived tree and d
 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. File input has a size limit, but stdin/Phoenix
+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.
 
 Both stores isolate returned mutable objects. InMemory node upsert replaces by ID;

{agent_tracegraph-0.2.0 → agent_tracegraph-0.3.1}/contracts/phoenix-runtime.json

@@ -1,5 +1,5 @@
 {
-  "phoenix_cli": "1.8.1",
+  "phoenix_cli": "1.18.8",
   "phoenix_server": {
     "image": "arizephoenix/phoenix",
     "version": "18.0.0",

{agent_tracegraph-0.2.0 → agent_tracegraph-0.3.1}/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.2.0"
+version = "0.3.1"
 description = "Time-travel debugging and causal RCA for LangGraph agent traces, on a causal graph."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -58,7 +58,7 @@ tracegraph = "tracegraph.cli:main"
 # LadybugDB is the actively maintained successor to the archived Kùzu project. The JSON
 # artifact remains authoritative, so an accelerator cache is rebuilt across DB versions.
 [project.optional-dependencies]
-cypher = ["ladybug>=0.18,<0.19"]
+cypher = ["ladybug>=0.18,<0.22"]
 
 [dependency-groups]
 dev = [
@@ -70,6 +70,9 @@ dev = [
     # a dependency bump there would turn that test red for a reason nothing in it names.
     "pyyaml>=6",
 ]
+# Kept out of `dev` so the default environment stays what the test jobs prove; CI's lint
+# job installs it explicitly. Pinned: a new mypy release is a new set of rules.
+typing = ["mypy==1.18.2"]
 
 [build-system]
 # Pinned exactly. A release rehearsal and the production tag are two builds on two days, and
@@ -115,6 +118,15 @@ src = ["src", "tests"]
 select = ["F", "E4", "E7", "E9", "B"]
 ignore = ["B008"]  # typer declares option defaults in the signature by design
 
+[tool.mypy]
+# The wheel ships py.typed, so its annotations are a contract. Not `strict`: the goal is
+# that what is annotated is checked and correct, not that every helper gains a signature.
+python_version = "3.12"
+files = ["src/tracegraph"]
+check_untyped_defs = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 pythonpath = ["examples"]