agent-tracegraph 0.2.0__py3-none-any.whl

tracegraph/input_validation.py

@@ -0,0 +1,19 @@
+"""Shape checks at untrusted JSON boundaries; diagnostics never echo field values."""
+
+import json
+from typing import Any
+
+
+def loads(text: str) -> Any:
+    try:
+        return json.loads(text)
+    except RecursionError as exc:
+        raise ValueError("JSON nesting too deep") from exc
+
+
+def object_field(value: Any, path: str) -> dict:
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise ValueError(f"{path} must be an object")
+    return value

tracegraph/model.py

@@ -0,0 +1,225 @@
+"""The frozen contract: the normalized causal-graph data model.
+
+This module is the *contract* the rest of tracegraph is built against. Two rules,
+fixed here in Phase 0, must never drift:
+
+1. **Edge direction is effect → cause.** Every causal edge points from a step to
+   one of its predecessors, so traversing outbound edges walks *backward* toward
+   root causes.
+
+2. **Two layers, one vocabulary.**
+   - ``CAUSED_BY`` is the *raw* layer and the system of record: it keeps **every**
+     real predecessor of a step (fan-in, retries, nested tool/LLM calls). Nothing
+     is dropped. Root-cause analysis reads this layer.
+   - ``TREE_PARENT`` is the *derived* layer: a computed projection that picks
+     exactly one parent per non-root step, yielding the single-parent forest the
+     structural (AHU) diff needs. It is **not** asserted to be "the cause" — it is
+     a projection parent for diffing. A step that had more than one ``CAUSED_BY``
+     is flagged ``projection_lossy=True`` so the lossiness is always visible.
+
+See ``normalize.py`` for how the derived layer is computed from the raw layer.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class StepKind(str, Enum):
+    """What a causal-event step represents.
+
+    Mirrors OpenInference span kinds so the OTLP adapter maps cleanly, plus ``DATA`` for
+    state/data nodes. LangGraph super-steps that can't be classified more precisely default
+    to ``CHAIN``.
+    """
+
+    AGENT = "AGENT"
+    CHAIN = "CHAIN"
+    TOOL = "TOOL"
+    LLM = "LLM"
+    RETRIEVER = "RETRIEVER"
+    EMBEDDING = "EMBEDDING"
+    RERANKER = "RERANKER"
+    GUARDRAIL = "GUARDRAIL"
+    EVALUATOR = "EVALUATOR"
+    PROMPT = "PROMPT"
+    UNKNOWN = "UNKNOWN"
+    DATA = "DATA"
+
+
+class StepSource(str, Enum):
+    """How the step entered the trace (mirrors LangGraph ``metadata.source``).
+
+    ``TASK`` is the one value that does *not* come from ``metadata.source``: it marks a step
+    derived from a checkpoint's **pending writes** (one LangGraph task) rather than from a
+    checkpoint itself. It is explicit provenance, not a naming convention — ``step_id`` is an
+    unrestricted string, so nothing about an id may be read as evidence of how a step was made.
+    """
+
+    INPUT = "input"
+    LOOP = "loop"
+    UPDATE = "update"
+    FORK = "fork"
+    TASK = "task"
+
+
+class StepStatus(str, Enum):
+    OK = "ok"
+    ERROR = "error"
+    UNSET = "unset"
+
+
+class EdgeOrigin(str, Enum):
+    """Declared evidence behind a raw causal edge."""
+
+    CHECKPOINT_PARENT = "checkpoint_parent"
+    GRAPH_PARENT = "graph_parent"
+    SPAN_LINK = "span_link"
+    SPAN_PARENT_FALLBACK = "span_parent_fallback"
+    LEGACY_UNKNOWN = "legacy_unknown"
+
+
+class CausalFidelity(str, Enum):
+    """How much of the source system's causal vocabulary survived export."""
+
+    DECLARED_DAG = "declared_dag"
+    PARENT_ONLY = "parent_only"
+    LEGACY_UNKNOWN = "legacy_unknown"
+
+
+class EvaluationSummary(BaseModel):
+    """Body-free Phoenix/OpenInference annotation evidence."""
+
+    name: str
+    label: str | None = None
+    score: float | None = None
+
+
+class StepEvidence(BaseModel):
+    """Allowlisted operational telemetry; never prompt/output bodies."""
+
+    end_ts: str | None = None
+    duration_ms: float | None = None
+    prompt_tokens: int | None = None
+    completion_tokens: int | None = None
+    total_tokens: int | None = None
+    prompt_cost: str | None = None
+    completion_cost: str | None = None
+    total_cost: str | None = None
+    cost_currency: str | None = None
+    artifact_digest: str | None = Field(default=None, pattern=r"^sha256:[0-9a-f]{64}$")
+    evaluations: list[EvaluationSummary] = Field(default_factory=list)
+
+
+class DecisionEvidence(BaseModel):
+    """Body-free evidence from an external pre-execution policy decision.
+
+    It is trace metadata, never a causal edge: a preflight can constrain a run without
+    proving that it caused a later outcome.
+    """
+
+    source: Literal["toolgraph_preflight"] = "toolgraph_preflight"
+    artifact_digest: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")
+    graph_generation: int = Field(ge=0)
+    verdict: str = Field(min_length=1, max_length=64, pattern=r"^[a-z][a-z0-9_-]*$")
+
+
+class EdgeType(str, Enum):
+    """The frozen edge vocabulary. Direction is effect → cause for causal edges."""
+
+    CAUSED_BY = "CAUSED_BY"      # raw layer: step -> a real predecessor (keep ALL)
+    TREE_PARENT = "TREE_PARENT"  # derived layer: step -> its single chosen parent
+    BELONGS_TO = "BELONGS_TO"    # step -> trace
+    WROTE = "WROTE"              # step -> channel (optional, flagged)
+    READ = "READ"               # step -> channel (optional, flagged)
+
+
+class Step(BaseModel):
+    """A causal-event node: one LangGraph super-step/checkpoint or one OTLP span."""
+
+    step_id: str
+    trace_id: str
+    seq: int = Field(description="Monotonic execution order within the trace.")
+    ts: str | None = Field(default=None, description="ISO-8601 timestamp, when available.")
+    kind: StepKind = StepKind.CHAIN
+    source: StepSource = StepSource.LOOP
+    name: str | None = None
+    status: StepStatus = StepStatus.OK
+    error_msg: str | None = None
+    evidence: StepEvidence | None = None
+    #: Set during normalization: True iff this step had >1 raw CAUSED_BY edge and
+    #: the derived TREE_PARENT projection therefore dropped at least one real cause.
+    projection_lossy: bool = False
+
+
+class Edge(BaseModel):
+    """A typed, directed edge. For causal edges, ``src`` is the effect and ``dst`` the cause."""
+
+    type: EdgeType
+    src: str
+    dst: str
+    origin: EdgeOrigin | None = None
+
+
+class Trace(BaseModel):
+    """One agent run / thread."""
+
+    trace_id: str
+    source_kind: str = Field(description="Which adapter produced this trace, e.g. 'langgraph'.")
+    run_id: str | None = Field(
+        default=None,
+        description="Optional cross-system run identifier (for example, a SyncMill run_id).",
+    )
+    thread_id: str | None = None
+    status: StepStatus = StepStatus.OK
+    causal_fidelity: CausalFidelity = CausalFidelity.LEGACY_UNKNOWN
+    links_preserved: bool | None = None
+    decision_evidence: list[DecisionEvidence] = Field(default_factory=list)
+
+
+class RawTrace(BaseModel):
+    """What an adapter emits: a trace, its steps, and the RAW causal edges only.
+
+    ``causal_edges`` must all be ``CAUSED_BY`` (effect → cause) — the system of record,
+    keeping every real predecessor. Adapters never compute the derived tree; they hand a
+    ``RawTrace`` to :func:`tracegraph.normalize.normalize`, which validates it and returns
+    a :class:`NormalizedTrace`. Keeping the two as **distinct types** is the contract
+    guard: an un-normalized trace (no ``TREE_PARENT`` layer) cannot reach ``diff``/
+    ``inspect`` by accident.
+    """
+
+    trace: Trace
+    steps: list[Step] = Field(default_factory=list)
+    causal_edges: list[Edge] = Field(default_factory=list)
+    #: Disclosures that are only knowable while reading the source (e.g. a checkpoint whose
+    #: task writes could not be attributed to a node). They describe the *ingestion*, not the
+    #: run, so they never reach ``NormalizedTrace`` or the artifact — the CLI prints them.
+    ingest_warnings: list[str] = Field(default_factory=list)
+
+    def steps_by_id(self) -> dict[str, Step]:
+        return {s.step_id: s for s in self.steps}
+
+
+class NormalizedTrace(BaseModel):
+    """The portable bundle: a trace plus its steps and BOTH edge layers.
+
+    Produced **only** by :func:`tracegraph.normalize.normalize` — never constructed
+    directly by adapters. It is what ``artifact.py`` (de)serializes and what the stores
+    load. The raw ``CAUSED_BY`` edges are the system of record; the derived
+    ``TREE_PARENT`` edges (one per non-root step) are recorded alongside them.
+    """
+
+    trace: Trace
+    steps: list[Step] = Field(default_factory=list)
+    edges: list[Edge] = Field(default_factory=list)
+
+    # --- convenience views (no business logic; just typed filters) ---
+
+    def steps_by_id(self) -> dict[str, Step]:
+        return {s.step_id: s for s in self.steps}
+
+    def edges_of(self, edge_type: EdgeType) -> list[Edge]:
+        return [e for e in self.edges if e.type is edge_type]

tracegraph/normalize.py

@@ -0,0 +1,248 @@
+"""The correctness core: validate the raw causal graph, then derive the tree.
+
+Adapters emit a :class:`~tracegraph.model.RawTrace` carrying steps and the **raw**
+``CAUSED_BY`` edges (every real predecessor of every step). :func:`normalize`:
+
+* **validates** the raw graph (:func:`validate_raw`) — endpoints exist, edges are
+  ``CAUSED_BY``, no self-edges, and every cause precedes its effect (which also makes
+  the raw graph acyclic by construction),
+* derives the ``TREE_PARENT`` layer — exactly one parent per non-root step — by picking
+  each step's *temporally-earliest* cause,
+* flags ``projection_lossy=True`` on any step whose real causality had to be collapsed
+  (more than one ``CAUSED_BY``), and
+* re-checks the derived layer is a forest (:func:`validate_tree`).
+
+The raw layer is never mutated. This is the boundary Codex flagged: keep the lossy
+projection *explicit and inspectable* so root-cause analysis (which reads the raw layer)
+never silently trusts a fabricated single parent — and reject malformed input here rather
+than letting it become a malformed artifact downstream.
+"""
+
+from __future__ import annotations
+
+from tracegraph.model import Edge, EdgeType, NormalizedTrace, RawTrace, Step, StepStatus
+
+
+def _check_steps(trace_id: str, steps: list[Step]) -> None:
+    ids = [s.step_id for s in steps]
+    if len(ids) != len(set(ids)):
+        raise ValueError("duplicate step_id in trace")
+    for s in steps:
+        if s.trace_id != trace_id:
+            raise ValueError(
+                f"step {s.step_id!r} has trace_id {s.trace_id!r}, expected {trace_id!r}"
+            )
+
+
+def _check_caused_by(steps: dict[str, Step], edges: list[Edge]) -> None:
+    """Validate the raw CAUSED_BY layer: typed, endpoints known/distinct, cause precedes effect.
+
+    Also rejects duplicate edges — a repeated ``(src, dst)`` would double-count in pattern
+    matches and child traversals.
+    """
+    seen: set[tuple[str, str]] = set()
+    for e in edges:
+        if e.type is not EdgeType.CAUSED_BY:
+            raise ValueError(f"raw causal edges must all be CAUSED_BY, got {e.type.value}")
+        if e.src not in steps:
+            raise ValueError(f"CAUSED_BY src {e.src!r} is not a known step")
+        if e.dst not in steps:
+            raise ValueError(f"CAUSED_BY dst {e.dst!r} is not a known step")
+        if e.src == e.dst:
+            raise ValueError(f"self-causal edge on step {e.src!r}")
+        if (e.src, e.dst) in seen:
+            raise ValueError(f"duplicate CAUSED_BY edge {e.src!r} -> {e.dst!r}")
+        seen.add((e.src, e.dst))
+        if not steps[e.dst].seq < steps[e.src].seq:
+            raise ValueError(
+                f"cause {e.dst!r} (seq {steps[e.dst].seq}) does not precede effect "
+                f"{e.src!r} (seq {steps[e.src].seq})"
+            )
+
+
+def validate_raw(raw: RawTrace) -> None:
+    """Assert a :class:`RawTrace` is well-formed before projection. Raises ``ValueError``.
+
+    Checks: unique step ids; steps belong to the trace; every edge is ``CAUSED_BY`` with
+    both endpoints known and distinct; and each cause's ``seq`` strictly precedes its
+    effect's. The seq rule both encodes "a cause happens before its effect" and guarantees
+    the raw graph has no cycles (so traversal always terminates).
+    """
+    _check_steps(raw.trace.trace_id, raw.steps)
+    _check_caused_by(raw.steps_by_id(), raw.causal_edges)
+
+
+def validate_structure(nt: NormalizedTrace) -> None:
+    """Assert a :class:`NormalizedTrace` is structurally sound, raising ``ValueError``.
+
+    The subset of :func:`validate_normalized` that every *reader* depends on: unique step ids,
+    a well-formed raw ``CAUSED_BY`` layer (known endpoints, cause precedes effect) and a
+    ``TREE_PARENT`` forest. Analyses index steps by id and rely on ``seq`` ordering to walk
+    causes in one pass, so on a malformed trace they would otherwise fail with a raw
+    ``KeyError`` — neither ``OSError`` nor ``ValueError``, and therefore straight past every
+    load-boundary handler. This is the cheap check a library entry point can afford; it
+    deliberately does *not* re-derive the artifact, so a caller holding a consistent but
+    non-canonical trace (an appended step, say) can still analyze it.
+    """
+    _check_steps(nt.trace.trace_id, nt.steps)
+    _check_caused_by(nt.steps_by_id(), nt.edges_of(EdgeType.CAUSED_BY))
+    validate_tree(nt)
+
+
+def validate_normalized(nt: NormalizedTrace) -> None:
+    """Validate a :class:`NormalizedTrace` end to end: raw layer **and** that the whole
+    artifact is *exactly* what :func:`normalize` would produce from its raw layer.
+
+    The strong check — re-deriving and comparing — is what makes the artifact a true
+    system of record. Without it, a hand-edited or partly-corrupt artifact (missing
+    ``BELONGS_TO``, missing ``TREE_PARENT``, wrong ``projection_lossy``, or simply edges
+    in non-canonical order) would pass the cheap structural checks and then silently
+    drift: a backend rebuilding from the raw layer would emit different artifact bytes
+    on the next save. Rejecting here keeps every loader (InMemoryStore, LadybugStore, future
+    caches) honest about "the JSON is what normalize() produces, full stop."
+    """
+    validate_structure(nt)
+
+    # The trace header is part of the system of record: a stored status that disagrees with
+    # the steps would let a "clean" artifact hide a failed run. normalize() derives it, so an
+    # honest artifact always matches — we check it explicitly here for a clear error message
+    # (the re-derive below would also catch it, but only as a generic "not canonical").
+    any_error = any(s.status is StepStatus.ERROR for s in nt.steps)
+    expected_status = StepStatus.ERROR if any_error else StepStatus.OK
+    if nt.trace.status is not expected_status:
+        raise ValueError(
+            f"trace.status {nt.trace.status.value!r} disagrees with its steps (expected "
+            f"{expected_status.value!r}: {'a' if any_error else 'no'} step has status=error)"
+        )
+
+    # Reconstruct what the canonical form should look like from the raw layer alone. We
+    # strip projection_lossy from the steps so normalize() resets it from scratch —
+    # otherwise a corrupt input flag would survive into the "expected" side and the
+    # check would tautologically pass.
+    raw = RawTrace(
+        trace=nt.trace,
+        steps=[s.model_copy(update={"projection_lossy": False}) for s in nt.steps],
+        causal_edges=nt.edges_of(EdgeType.CAUSED_BY),
+    )
+    expected = normalize(raw)
+    if expected != nt:
+        raise ValueError(
+            "normalized trace is not in canonical form: derived edges, projection_lossy "
+            "flags, or step/edge ordering do not match what normalize() produces from "
+            "the raw CAUSED_BY layer. The JSON artifact must be the output of normalize() "
+            "verbatim — anything else would drift on the next save."
+        )
+
+
+def _parents_by_step(caused_by: list[Edge]) -> dict[str, list[str]]:
+    """Raw causes per effect step (CAUSED_BY points effect → cause), built in one pass.
+
+    Preserves the order of ``caused_by``, so feeding it the canonically sorted edge
+    list yields each step's parents in canonical order.
+    """
+    parents: dict[str, list[str]] = {}
+    for e in caused_by:
+        parents.setdefault(e.src, []).append(e.dst)
+    return parents
+
+
+def _primary_parent(parent_ids: list[str], steps: dict[str, Step]) -> str:
+    """Pick the single TREE_PARENT: the temporally-earliest cause.
+
+    Ordering key is ``(seq, ts, step_id)`` so the choice is deterministic even when
+    seq or ts collide. The chosen parent is the one that happened first.
+    """
+
+    def key(pid: str) -> tuple[int, str, str]:
+        p = steps[pid]
+        return (p.seq, p.ts or "", p.step_id)
+
+    return min(parent_ids, key=key)
+
+
+def normalize(raw: RawTrace) -> NormalizedTrace:
+    """Validate a raw trace and return its normalized form (raw + derived layers).
+
+    Deterministic and **canonically ordered**: the returned trace's steps and edges are
+    in a fixed, input-independent order so two semantically-equivalent ``RawTrace`` inputs
+    (e.g. the same trace from two adapters, or the same artifact reloaded through any
+    backend) produce byte-identical artifacts. The canonical layout is:
+
+    * **steps** — sorted by ``(seq, step_id)``;
+    * **CAUSED_BY** edges — sorted by ``(effect.seq, cause.seq, src, dst)`` (the order a
+      walk-forward-in-time would discover them);
+    * **BELONGS_TO** then **TREE_PARENT** for each step, emitted in the canonical step order.
+
+    This guarantee — not "the adapter happened to enumerate canonically" — is what makes
+    the optional LadybugDB cache a true accelerator: any backend that rebuilds a trace from
+    its raw layer lands on the same artifact bytes.
+    """
+    validate_raw(raw)
+    steps_by_id = raw.steps_by_id()
+
+    # Canonicalize the raw inputs ONCE; derived edges then fall out in canonical order
+    # naturally because they're emitted per-step in the same loop.
+    steps_canonical = sorted(raw.steps, key=lambda s: (s.seq, s.step_id))
+    caused_by = sorted(
+        raw.causal_edges,
+        key=lambda e: (steps_by_id[e.src].seq, steps_by_id[e.dst].seq, e.src, e.dst),
+    )
+
+    edges: list[Edge] = list(caused_by)  # carry the raw layer through unchanged
+    parents_by_step = _parents_by_step(caused_by)
+    new_steps: list[Step] = []
+    for step in steps_canonical:
+        parents = parents_by_step.get(step.step_id, [])
+        # Flag lossiness on a copy so we never mutate the caller's objects.
+        step = step.model_copy(update={"projection_lossy": len(parents) > 1})
+        new_steps.append(step)
+
+        edges.append(Edge(type=EdgeType.BELONGS_TO, src=step.step_id, dst=raw.trace.trace_id))
+        if parents:
+            chosen = _primary_parent(parents, steps_by_id)
+            edges.append(Edge(type=EdgeType.TREE_PARENT, src=step.step_id, dst=chosen))
+
+    # The trace-level status is a derived view of its steps, not independent data: make it
+    # canonical here so the artifact header can never lie about whether the run errored.
+    any_error = any(s.status is StepStatus.ERROR for s in new_steps)
+    trace = raw.trace.model_copy(
+        update={"status": StepStatus.ERROR if any_error else StepStatus.OK}
+    )
+    nt = NormalizedTrace(trace=trace, steps=new_steps, edges=edges)
+    validate_tree(nt)
+    return nt
+
+
+def validate_tree(nt: NormalizedTrace) -> None:
+    """Assert the **derived** ``TREE_PARENT`` layer is a forest. Never touches the raw layer.
+
+    Raises ``ValueError`` if any step has more than one ``TREE_PARENT``, an edge
+    references an unknown step, or following parents reveals a cycle.
+    """
+    ids = {s.step_id for s in nt.steps}
+    seq_of = {s.step_id: s.seq for s in nt.steps}
+    parent_of: dict[str, str] = {}
+    for e in nt.edges_of(EdgeType.TREE_PARENT):
+        if e.src not in ids or e.dst not in ids:
+            raise ValueError(f"TREE_PARENT edge references unknown step: {e.src} -> {e.dst}")
+        if e.src in parent_of:
+            raise ValueError(f"step {e.src!r} has more than one TREE_PARENT (not a forest)")
+        parent_of[e.src] = e.dst
+
+    # Cycle check: walking parents from any node must terminate at a root. Nodes on an
+    # already-proven-acyclic path are skipped, keeping the whole check O(n) overall.
+    proven: set[str] = set()
+    # Iterate steps in canonical (seq, step_id) order, not set order: which member of a cycle
+    # the error names would otherwise vary with PYTHONHASHSEED, making the message — and any
+    # test or bug report quoting it — irreproducible. The raise/no-raise decision is unaffected.
+    for start in sorted(ids, key=lambda sid: (seq_of[sid], sid)):
+        path: list[str] = []
+        on_path: set[str] = set()
+        cur: str | None = start
+        while cur is not None and cur not in proven:
+            if cur in on_path:
+                raise ValueError(f"cycle in TREE_PARENT layer involving step {cur!r}")
+            path.append(cur)
+            on_path.add(cur)
+            cur = parent_of.get(cur)
+        proven.update(path)

tracegraph/review_candidates.py

@@ -0,0 +1,136 @@
+"""Versioned, body-free review candidates produced from pattern matches."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from tracegraph.analysis.patterns import Match, PathPattern
+from tracegraph.model import NormalizedTrace, Step, StepKind, StepStatus
+
+
+REVIEW_CANDIDATE_SCHEMA_VERSION = 1
+REVIEW_CANDIDATE_KIND = "tracegraph.review-candidates"
+
+
+class ReviewCandidate(BaseModel):
+    """One minimal governance-review input; no trace body or local path is retained."""
+
+    model_config = ConfigDict(extra="allow")
+
+    run_id: str = Field(min_length=1, max_length=256, pattern=r"^\S+$")
+    pattern_id: str = Field(pattern=r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+    pattern_version: int = Field(ge=1)
+    tool_key: str = Field(min_length=4, max_length=512, pattern=r"^\S+::\S+$")
+    artifact_digest: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")
+
+
+class ReviewCandidateReport(BaseModel):
+    """Schema-v1 deterministic envelope for zero or more review candidates."""
+
+    model_config = ConfigDict(extra="allow")
+
+    schema_version: Literal[1] = REVIEW_CANDIDATE_SCHEMA_VERSION
+    kind: Literal["tracegraph.review-candidates"] = REVIEW_CANDIDATE_KIND
+    candidates: list[ReviewCandidate] = Field(default_factory=list)
+
+
+def is_review_exportable(pattern: PathPattern) -> bool:
+    """A review candidate must end at an unconstrained, explicitly failing TOOL.
+
+    Operational pseudo-tools such as ``gate:*`` use a name constraint and are diagnosis
+    signals, not server-qualified governance candidates.
+    """
+    if not pattern.review_eligible or not pattern.steps:
+        return False
+    endpoint = pattern.steps[-1]
+    return (
+        endpoint.kind is StepKind.TOOL
+        and endpoint.status is StepStatus.ERROR
+        and endpoint.name is None
+        and endpoint.name_prefix is None
+    )
+
+
+def build_report(
+    pattern: PathPattern,
+    matches: list[Match],
+    traces: dict[str, NormalizedTrace],
+    artifact_digests: dict[str, str],
+) -> ReviewCandidateReport:
+    """Build a sorted, de-duplicated report from matches and their exact artifacts."""
+    if pattern.pattern_id is None or pattern.pattern_version is None:
+        raise ValueError("review export requires a versioned preset pattern")
+    if not is_review_exportable(pattern):
+        raise ValueError(f"preset {pattern.pattern_id!r} is not review-exportable")
+
+    steps_by_trace: dict[str, dict[str, Step]] = {}
+    unique: dict[tuple[str, str, int, str, str], ReviewCandidate] = {}
+    for match in matches:
+        trace = traces[match.trace_id]
+        run_id = trace.trace.run_id
+        if run_id is None:
+            raise ValueError(f"trace {match.trace_id!r} has no run_id")
+        steps = steps_by_trace.get(match.trace_id)
+        if steps is None:
+            steps = trace.steps_by_id()
+            steps_by_trace[match.trace_id] = steps
+        endpoint = steps[match.step_ids[-1]]
+        if endpoint.kind is not StepKind.TOOL or not endpoint.name:
+            raise ValueError(f"trace {match.trace_id!r} matched an unnamed or non-TOOL endpoint")
+        tool_key = endpoint.name
+        if any(ch.isspace() for ch in tool_key) or "::" not in tool_key:
+            raise ValueError(
+                f"trace {match.trace_id!r} matched a TOOL without a server-qualified tool_key"
+            )
+        server, tool = tool_key.split("::", 1)
+        if not server or not tool:
+            raise ValueError(
+                f"trace {match.trace_id!r} matched a TOOL without a server-qualified tool_key"
+            )
+        digest = artifact_digests[match.trace_id]
+        candidate = ReviewCandidate(
+            run_id=run_id,
+            pattern_id=pattern.pattern_id,
+            pattern_version=pattern.pattern_version,
+            tool_key=tool_key,
+            artifact_digest=digest,
+        )
+        key = (
+            candidate.run_id,
+            candidate.pattern_id,
+            candidate.pattern_version,
+            candidate.tool_key,
+            candidate.artifact_digest,
+        )
+        unique[key] = candidate
+
+    return ReviewCandidateReport(candidates=[unique[key] for key in sorted(unique)])
+
+
+def dumps(report: ReviewCandidateReport) -> str:
+    """Stable JSON representation used by the CLI and contract goldens."""
+    return json.dumps(report.model_dump(mode="json"), indent=2, sort_keys=True) + "\n"
+
+
+def save_atomic(report: ReviewCandidateReport, path: str | Path) -> None:
+    """Atomically replace ``path`` without leaving a partial report on failure."""
+    target = Path(path)
+    # Same contract as artifact.save_atomic / diagnose.save_atomic: create the parent
+    # directory so `--out newdir/report.json` works instead of failing inside mkstemp.
+    target.parent.mkdir(parents=True, exist_ok=True)
+    fd, temporary = tempfile.mkstemp(prefix=f".{target.name}.", suffix=".tmp", dir=target.parent)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as handle:
+            handle.write(dumps(report))
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, target)
+    except BaseException:
+        Path(temporary).unlink(missing_ok=True)
+        raise