trace-to-fixture 0.1.0__tar.gz

trace_to_fixture-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Faultline-lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

trace_to_fixture-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: trace-to-fixture
+Version: 0.1.0
+Summary: Turn real agent runs into safe, small, repeatable tests: scrub private data, keep one example of each behaviour, write pytest fixtures for faultgate-zero.
+Author: Faultline-lab
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Faultline-lab/trace-to-fixture
+Keywords: ai,agents,testing,fixtures,opentelemetry,pytest
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: faultgate<0.5,>=0.4.2
+Requires-Dist: faultgate-zero<0.2,>=0.1
+Requires-Dist: pytest>=8
+Provides-Extra: pii
+Requires-Dist: faultgate[pii]<0.5,>=0.4.2; extra == "pii"
+Provides-Extra: dev
+Requires-Dist: pytest-xdist>=3; extra == "dev"
+Dynamic: license-file
+
+# Trace-to-Fixture
+
+Turn real agent runs into safe, small, repeatable tests.
+
+Read a trace export, mask the private data it can detect, keep one example of each distinct behaviour, and write
+tests that run in CI with [faultgate-zero](https://github.com/Faultline-lab/faultgate-zero). The offline tests pass on
+day one with no model calls. The live tests re-run your agent on each real prompt and check it.
+
+```
+T2F_SALT=<a secret> trace-to-fixture build export.json --out tests/agent_fixtures
+```
+
+Free and MIT-licensed. Runs on your machine and sends nothing anywhere.
+
+> **What it does and does not do.** It *masks the private data its detectors can find* (secrets, emails, US SSNs,
+> card numbers, IP addresses, phone numbers; names and places with the `pii` extra), plus anything you list in a
+> deny file or as a sensitive key. It is not an anonymisation or compliance product, and detectors miss things such as
+> internal customer ids. Always run `scan`, read what it found, and review the output before you commit it.
+
+## Install
+
+```bash
+pip install trace-to-fixture            # needs Python 3.11+
+pip install 'trace-to-fixture[pii]'     # adds Presidio for names and places
+```
+
+It builds on `faultgate` (0.4.2 or newer) (format loaders, private-data detectors) and `faultgate-zero` (the checks).
+
+## Quickstart (5 minutes)
+
+The `examples/` folder holds a small refund agent, a "production" export of three of its runs, and a policy.
+
+```bash
+git clone https://github.com/Faultline-lab/trace-to-fixture && cd trace-to-fixture
+pip install -e .
+cd examples
+
+# 1. See what is in the export. Nothing is written (scan needs no salt).
+trace-to-fixture scan export.otlp.json
+
+# 2. Build the fixture set. build needs a salt: a secret in real use, never committed.
+#    On Windows PowerShell use  $env:T2F_SALT = "quickstart-demo-salt"  or pass --salt-file FILE.
+export T2F_SALT="quickstart-demo-salt"
+trace-to-fixture build export.otlp.json --out ../tests_out --policy policy.json --agent refund_agent:run
+
+# 3. Run the offline tests. No model calls, free.
+pytest ../tests_out
+```
+
+`tests_out/` now holds `manifest.json`, `fixtures/*.otlp.json`, `test_agent_fixtures.py` and `substitutions.json`.
+
+### Live replay
+
+Live tests re-run your agent on each real prompt, so they need a test-environment value for every placeholder:
+
+```bash
+pytest ../tests_out -m agent_live -rs      # skipped: "needs substitutions for <EMAIL_b1beab65>, <PHONE_29a793ca>"
+```
+
+Put test data (never real values) in `substitutions.json`, then run again:
+
+```json
+{ "<EMAIL_b1beab65>": "test.user1@example.com", "<PHONE_29a793ca>": "+1 555 0100" }
+```
+
+The known failure (a $900 refund over the $500 limit) now **xfails**: it still fails like production. Fix the bug
+(`FIXED = True` in `refund_agent.py`) and the test fails with:
+
+```
+f-xxxxxxxx no longer fails. Promote it to a guard:
+  trace-to-fixture promote ../tests_out f-xxxxxxxx
+```
+
+After `promote`, the fixture is a guard: if the bug ever comes back the test fails with the policy reason.
+Live tests run only with `-m agent_live` or `T2F_LIVE=1`, so a plain `pytest` never spends tokens.
+
+## Commands
+
+| Command | What it does | Writes |
+|---|---|---|
+| `scan INPUT` | Format, precheck, counts of detected values by kind and by field, dropped attribute keys. | nothing |
+| `build INPUT --out DIR` | Load, precheck, scrub, prove verdicts are unchanged, group, select, write, leak scan. | `DIR` |
+| `verify DIR` | Leak scan of every file, hash checks, loading in faultgate-zero and faultgate, snapshot verdicts. | nothing |
+| `explain INPUT --trace ID` | One trace: changed fields (path, kind, lengths, never values), raw vs scrubbed verdicts, signature, why kept. | nothing |
+| `promote DIR ID` | Change a fixture from `known_failure` to `guard`. | `manifest.json` |
+
+Options: `--format` (default `auto`; OTLP, OpenInference, Langfuse, LangSmith, Braintrust), `--policy FILE`
+(faultgate-zero policy format), `--checks a,b,c`, `--agent module:function`, `--per-group N` (1), `--max-clean N` (20),
+`--pii builtin|presidio`, `--deny-literals FILE`, `--sensitive-key NAME` (repeatable), `--salt-file FILE` or `T2F_SALT`,
+`--drop-mismatched`, `--bundle FILE`, `-v` / `T2F_DEBUG=1` (stage counts and timings on stderr, never values).
+
+Exit codes: `0` success, `1` a problem was found (a leak, a verdict mismatch, snapshot drift), `2` a usage or input
+error (a bad file, a missing salt, precheck errors).
+
+## How it works
+
+1. **Load** the export with faultgate's readers; precheck errors stop the build.
+2. **Scrub.** Each detected value becomes `<KIND_xxxxxxxx>`, an HMAC of the exact value under your secret salt: the same
+   value always gets the same placeholder, so checks that compare values keep working. Attributes the checks never read
+   are dropped; trace and span ids are remapped; time is rebased. JSON inside strings (up to two levels) is walked.
+3. **Prove nothing changed.** Every check runs on each trace before and after scrubbing; verdicts must match.
+4. **Select.** Runs with the same behaviour (tool path, fired checks, outcome, tool errors, size) form a group. Every
+   group where a check fired is kept; the largest clean groups fill the rest. Selection is deterministic.
+5. **Write** fixtures, a manifest, a generated pytest file, and a leak scan of what was written.
+
+Same input, same salt and same options give byte-identical output. Use one stable salt per project (a different salt
+changes every placeholder and fixture id). `manifest.json` records only a fingerprint of the salt.
+
+## Privacy rules
+
+- Raw values live only in memory: never in files, logs, exceptions or the manifest.
+- The salt is a secret. Keep it in a secret store or CI secret, never in git. One salt per customer audit.
+- `substitutions.json` holds test data only.
+- If a detector misses something, add it to `--deny-literals` (one literal per line) or `--sensitive-key`.
+
+## Develop
+
+```bash
+pip install -e '.[dev]'
+pytest                   # unit tests
+python evals/run.py      # acceptance table (add --perf for the 5,000-trace speed row)
+```
+
+## Limits
+
+Multi-turn conversations are kept as offline fixtures only (`replayable: false`). Tool responses are not mocked:
+live replay calls your own tools in your own test environment. Input is an export file; there is no vendor API puller.

trace_to_fixture-0.1.0/README.md

@@ -0,0 +1,127 @@
+# Trace-to-Fixture
+
+Turn real agent runs into safe, small, repeatable tests.
+
+Read a trace export, mask the private data it can detect, keep one example of each distinct behaviour, and write
+tests that run in CI with [faultgate-zero](https://github.com/Faultline-lab/faultgate-zero). The offline tests pass on
+day one with no model calls. The live tests re-run your agent on each real prompt and check it.
+
+```
+T2F_SALT=<a secret> trace-to-fixture build export.json --out tests/agent_fixtures
+```
+
+Free and MIT-licensed. Runs on your machine and sends nothing anywhere.
+
+> **What it does and does not do.** It *masks the private data its detectors can find* (secrets, emails, US SSNs,
+> card numbers, IP addresses, phone numbers; names and places with the `pii` extra), plus anything you list in a
+> deny file or as a sensitive key. It is not an anonymisation or compliance product, and detectors miss things such as
+> internal customer ids. Always run `scan`, read what it found, and review the output before you commit it.
+
+## Install
+
+```bash
+pip install trace-to-fixture            # needs Python 3.11+
+pip install 'trace-to-fixture[pii]'     # adds Presidio for names and places
+```
+
+It builds on `faultgate` (0.4.2 or newer) (format loaders, private-data detectors) and `faultgate-zero` (the checks).
+
+## Quickstart (5 minutes)
+
+The `examples/` folder holds a small refund agent, a "production" export of three of its runs, and a policy.
+
+```bash
+git clone https://github.com/Faultline-lab/trace-to-fixture && cd trace-to-fixture
+pip install -e .
+cd examples
+
+# 1. See what is in the export. Nothing is written (scan needs no salt).
+trace-to-fixture scan export.otlp.json
+
+# 2. Build the fixture set. build needs a salt: a secret in real use, never committed.
+#    On Windows PowerShell use  $env:T2F_SALT = "quickstart-demo-salt"  or pass --salt-file FILE.
+export T2F_SALT="quickstart-demo-salt"
+trace-to-fixture build export.otlp.json --out ../tests_out --policy policy.json --agent refund_agent:run
+
+# 3. Run the offline tests. No model calls, free.
+pytest ../tests_out
+```
+
+`tests_out/` now holds `manifest.json`, `fixtures/*.otlp.json`, `test_agent_fixtures.py` and `substitutions.json`.
+
+### Live replay
+
+Live tests re-run your agent on each real prompt, so they need a test-environment value for every placeholder:
+
+```bash
+pytest ../tests_out -m agent_live -rs      # skipped: "needs substitutions for <EMAIL_b1beab65>, <PHONE_29a793ca>"
+```
+
+Put test data (never real values) in `substitutions.json`, then run again:
+
+```json
+{ "<EMAIL_b1beab65>": "test.user1@example.com", "<PHONE_29a793ca>": "+1 555 0100" }
+```
+
+The known failure (a $900 refund over the $500 limit) now **xfails**: it still fails like production. Fix the bug
+(`FIXED = True` in `refund_agent.py`) and the test fails with:
+
+```
+f-xxxxxxxx no longer fails. Promote it to a guard:
+  trace-to-fixture promote ../tests_out f-xxxxxxxx
+```
+
+After `promote`, the fixture is a guard: if the bug ever comes back the test fails with the policy reason.
+Live tests run only with `-m agent_live` or `T2F_LIVE=1`, so a plain `pytest` never spends tokens.
+
+## Commands
+
+| Command | What it does | Writes |
+|---|---|---|
+| `scan INPUT` | Format, precheck, counts of detected values by kind and by field, dropped attribute keys. | nothing |
+| `build INPUT --out DIR` | Load, precheck, scrub, prove verdicts are unchanged, group, select, write, leak scan. | `DIR` |
+| `verify DIR` | Leak scan of every file, hash checks, loading in faultgate-zero and faultgate, snapshot verdicts. | nothing |
+| `explain INPUT --trace ID` | One trace: changed fields (path, kind, lengths, never values), raw vs scrubbed verdicts, signature, why kept. | nothing |
+| `promote DIR ID` | Change a fixture from `known_failure` to `guard`. | `manifest.json` |
+
+Options: `--format` (default `auto`; OTLP, OpenInference, Langfuse, LangSmith, Braintrust), `--policy FILE`
+(faultgate-zero policy format), `--checks a,b,c`, `--agent module:function`, `--per-group N` (1), `--max-clean N` (20),
+`--pii builtin|presidio`, `--deny-literals FILE`, `--sensitive-key NAME` (repeatable), `--salt-file FILE` or `T2F_SALT`,
+`--drop-mismatched`, `--bundle FILE`, `-v` / `T2F_DEBUG=1` (stage counts and timings on stderr, never values).
+
+Exit codes: `0` success, `1` a problem was found (a leak, a verdict mismatch, snapshot drift), `2` a usage or input
+error (a bad file, a missing salt, precheck errors).
+
+## How it works
+
+1. **Load** the export with faultgate's readers; precheck errors stop the build.
+2. **Scrub.** Each detected value becomes `<KIND_xxxxxxxx>`, an HMAC of the exact value under your secret salt: the same
+   value always gets the same placeholder, so checks that compare values keep working. Attributes the checks never read
+   are dropped; trace and span ids are remapped; time is rebased. JSON inside strings (up to two levels) is walked.
+3. **Prove nothing changed.** Every check runs on each trace before and after scrubbing; verdicts must match.
+4. **Select.** Runs with the same behaviour (tool path, fired checks, outcome, tool errors, size) form a group. Every
+   group where a check fired is kept; the largest clean groups fill the rest. Selection is deterministic.
+5. **Write** fixtures, a manifest, a generated pytest file, and a leak scan of what was written.
+
+Same input, same salt and same options give byte-identical output. Use one stable salt per project (a different salt
+changes every placeholder and fixture id). `manifest.json` records only a fingerprint of the salt.
+
+## Privacy rules
+
+- Raw values live only in memory: never in files, logs, exceptions or the manifest.
+- The salt is a secret. Keep it in a secret store or CI secret, never in git. One salt per customer audit.
+- `substitutions.json` holds test data only.
+- If a detector misses something, add it to `--deny-literals` (one literal per line) or `--sensitive-key`.
+
+## Develop
+
+```bash
+pip install -e '.[dev]'
+pytest                   # unit tests
+python evals/run.py      # acceptance table (add --perf for the 5,000-trace speed row)
+```
+
+## Limits
+
+Multi-turn conversations are kept as offline fixtures only (`replayable: false`). Tool responses are not mocked:
+live replay calls your own tools in your own test environment. Input is an export file; there is no vendor API puller.

trace_to_fixture-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "trace-to-fixture"
+version = "0.1.0"
+description = "Turn real agent runs into safe, small, repeatable tests: scrub private data, keep one example of each behaviour, write pytest fixtures for faultgate-zero."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "Faultline-lab" }]
+keywords = ["ai", "agents", "testing", "fixtures", "opentelemetry", "pytest"]
+classifiers = ["Development Status :: 3 - Alpha", "Framework :: Pytest", "Programming Language :: Python :: 3"]
+dependencies = ["faultgate>=0.4.2,<0.5", "faultgate-zero>=0.1,<0.2", "pytest>=8"]
+
+[project.optional-dependencies]
+pii = ["faultgate[pii]>=0.4.2,<0.5"]
+dev = ["pytest-xdist>=3"]
+
+[project.scripts]
+trace-to-fixture = "trace_to_fixture.cli:main"
+
+[project.entry-points.pytest11]
+trace_to_fixture = "trace_to_fixture.pytest_plugin"
+
+[project.urls]
+Homepage = "https://github.com/Faultline-lab/trace-to-fixture"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["slow: performance tests, run nightly"]

trace_to_fixture-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

trace_to_fixture-0.1.0/src/trace_to_fixture/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

trace_to_fixture-0.1.0/src/trace_to_fixture/build.py

@@ -0,0 +1,279 @@
+"""scan, build and explain pipelines (spec sections 4, 6, 9, 10, 11)."""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from typing import Callable
+
+from faultgate_zero import otlp
+from faultgate_zero.checks import DEFAULT_CHECKS, Options, resolve
+from faultgate_zero.policy import Policy
+from faultgate_zero.runner import Settings
+from faultgate_zero.trace import Trace, messages, parts
+
+from . import __version__, load, preserve, write
+from .scrub import PLACEHOLDER_RE, Scrubber, ScrubReport, salt_id, presidio_find
+from .select import Candidate, Selection, select, signature
+
+
+class BuildError(Exception):
+    """Exit code 1: a problem was found (leak, verdict mismatch)."""
+
+
+@dataclass
+class Options_:
+    input: Path
+    out: Path | None = None
+    fmt: str = "auto"
+    policy: Path | None = None
+    checks: str | None = None
+    agent: str | None = None
+    per_group: int = 1
+    max_clean: int = 20
+    pii: str = "builtin"
+    deny_literals: list[str] = field(default_factory=list)
+    sensitive_keys: list[str] = field(default_factory=list)
+    salt: bytes = b""
+    drop_mismatched: bool = False
+    bundle: Path | None = None
+
+
+def make_scrubber(o: Options_) -> Scrubber:
+    extra = [presidio_find()] if o.pii == "presidio" else []
+    return Scrubber(o.salt, deny_literals=o.deny_literals, sensitive_keys=o.sensitive_keys, extra_finders=extra)
+
+
+def make_settings(o: Options_) -> Settings:
+    names = resolve([c.strip() for c in o.checks.split(",")]) if o.checks else DEFAULT_CHECKS
+    return Settings(checks=names, policy=Policy.load(o.policy) if o.policy else Policy(),
+                    options=Options(), redact=make_scrubber(o).scrub_text)
+
+
+@dataclass
+class ScanResult:
+    fmt: str
+    traces: int
+    tool_steps: int
+    warnings: list
+    report: ScrubReport
+
+
+def scan(o: Options_) -> ScanResult:
+    fmt, traces, warnings = load.load(o.input, o.fmt)
+    sc = make_scrubber(o)
+    for t in traces:
+        sc.scrub_trace(t)
+    return ScanResult(fmt, len(traces), sum(len(t.steps) for t in traces), warnings, sc.report)
+
+
+def user_messages(trace: Trace) -> set[str]:
+    out: set[str] = set()
+    spans = [trace.root] if trace.root else []
+    for s in [*spans, *trace.model_calls]:
+        for m in messages(s.attrs.get("gen_ai.input.messages")):
+            if m.get("role") == "user":
+                text = "".join(str(p.get("content", "")) for p in parts(m) if p.get("type") == "text")
+                if text.strip():
+                    out.add(text)
+    return out
+
+
+def placeholders_in(text: str) -> list[str]:
+    return sorted(set(PLACEHOLDER_RE.findall(text)))
+
+
+@dataclass
+class Processed:
+    trace_hash: str
+    scrubbed: Trace
+    fixture_id: str
+    fired: frozenset[str]
+    reasons: dict[str, str]
+    expected: dict[str, bool]
+    json_size: int
+    mismatch: list[str]
+
+
+def _mask_denied(text: str, patterns) -> str:
+    """A policy reason can quote the denied text; the policy's own words must not travel into the manifest."""
+    for pat in patterns:
+        if pat:
+            text = re.sub(re.escape(pat), "<DENIED>", text, flags=re.IGNORECASE)
+    return text
+
+
+def process(traces: list[Trace], sc: Scrubber, settings: Settings,
+            progress: Callable[[str], None] | None = None) -> list[Processed]:
+    from faultgate_zero import runner
+    out = []
+    for t in traces:
+        raw = preserve.verdicts(t, settings)
+        s = sc.scrub_trace(t)
+        fid = write.canonical_id(s)
+        root = s.root
+        if root is not None:
+            root.attrs["faultgate.scenario"] = fid
+        s.scenario = fid
+        res = runner.check(s, settings)
+        got = {v.check: v.fired for v in res.verdicts}
+        mism = sorted(k for k in raw.keys() | got.keys() if raw.get(k) != got.get(k))
+        out.append(Processed(
+            trace_hash=hashlib.sha256(t.trace_id.encode()).hexdigest()[:12], scrubbed=s, fixture_id=fid,
+            fired=frozenset(k for k, v in got.items() if v), reasons={v.check: _mask_denied(v.reason, settings.policy.deny) for v in res.fired},
+            expected=dict(sorted(got.items())), json_size=len(write.fixture_bytes(s)), mismatch=mism))
+    if progress:
+        progress(f"scrubbed {len(out)} traces")
+    return out
+
+
+@dataclass
+class BuildResult:
+    fmt: str
+    loaded: int
+    scrubbed_values: int
+    identical: int
+    mismatches: list[tuple[str, list[str]]]
+    dropped: int
+    selection: Selection
+    removed: list[str]
+    leaks: list
+    out: Path
+    warnings: list = field(default_factory=list)
+
+    def summary_lines(self) -> list[str]:
+        sel = self.selection
+        failing = sum(1 for _, _, s in sel.kept if s == "known_failure")
+        guards = len(sel.kept) - failing
+        lines = [
+            f"loaded      {self.loaded:,} traces ({self.fmt})",
+            f"scrubbed    {self.scrubbed_values:,} values in {self.loaded:,} traces",
+            f"verdicts    {self.identical:,} of {self.loaded:,} identical before and after scrubbing",
+        ]
+        if self.mismatches:
+            lines.append(f"mismatch    {len(self.mismatches)} traces changed verdicts"
+                         + (f"; {self.dropped} dropped" if self.dropped else ""))
+        lines += [
+            f"grouped     {len(sel.groups)} behaviours, {sel.failure_groups} with a failing check",
+            f"kept        {len(sel.kept)} fixtures: {failing} known failures, {guards} guards "
+            f"(they stand for {sel.traces_represented:,} of {self.loaded - self.dropped:,} traces)",
+        ]
+        if self.removed:
+            lines.append(f"removed     {len(self.removed)} fixtures no longer selected: {', '.join(self.removed)}")
+        lines += [f"leak scan   {len(self.leaks)} findings", f"wrote       {self.out}"]
+        return lines
+
+
+def build(o: Options_, progress: Callable[[str], None] | None = None) -> BuildResult:
+    from .verify import scan_files
+    fmt, traces, warnings = load.load(o.input, o.fmt)
+    settings = make_settings(o)
+    sc = make_scrubber(o)
+    done = process(traces, sc, settings, progress)
+    mism = [(p.trace_hash, p.mismatch) for p in done if p.mismatch]
+    if mism and not o.drop_mismatched:
+        raise BuildError("verdicts changed by scrubbing for "
+                         + "; ".join(f"{h}: {','.join(c)}" for h, c in mism[:10])
+                         + " (see 'trace-to-fixture explain'; --drop-mismatched continues without them)")
+    good = [p for p in done if not p.mismatch]
+    selection = select([Candidate(p.fixture_id, p.scrubbed, p.fired, p.json_size, [p.trace_hash]) for p in good],
+                       o.per_group, o.max_clean)
+    by_id = {p.fixture_id: p for p in good}
+    out = Path(o.out)
+    old = write.read_manifest(out) or {}
+    old_status = {f["id"]: f["status"] for f in old.get("fixtures", [])}
+
+    entries, kept_traces = [], {}
+    for cand, group, status in selection.kept:
+        p = by_id[cand.fixture_id]
+        status = old_status.get(cand.fixture_id, status)
+        user = p.scrubbed.user_id
+        entries.append({
+            "id": cand.fixture_id, "file": f"{write.FIXTURE_DIR}/{cand.fixture_id}.otlp.json",
+            "sha256": write.sha256_bytes(write.fixture_bytes(p.scrubbed)), "status": status,
+            "signature": group.signature, "group_size": group.size, "expected": p.expected,
+            "reasons": dict(sorted(p.reasons.items())), "replayable": len(user_messages(p.scrubbed)) == 1
+            and bool(p.scrubbed.prompt.strip()),
+            "prompt_placeholders": placeholders_in(p.scrubbed.prompt), "user": user,
+        })
+        kept_traces[cand.fixture_id] = p.scrubbed
+    entries.sort(key=lambda e: e["id"])
+    opts = {"loop_min_steps": settings.options.loop_min_steps, "loop_empty_share": settings.options.loop_empty_share,
+            "repeat_threshold": settings.options.repeat_threshold}
+    manifest = {
+        "schema": write.SCHEMA, "tool": f"trace-to-fixture {__version__}", "engine": _engine(),
+        "source": {"format": fmt, "traces": len(traces), "sha256": load.file_sha256(o.input)},
+        "salt_id": salt_id(o.salt), "checks": list(settings.checks),
+        "policy": ({"path": write.rel_policy(str(Path(o.policy).resolve()), out.resolve()),
+                    "sha256": write.sha256_file(o.policy)} if o.policy else None),
+        "options": opts, "agent": o.agent, "selection": {"per_group": o.per_group, "max_clean": o.max_clean},
+        "coverage": {"groups": len(selection.groups), "failure_groups": selection.failure_groups,
+                     "kept": len(entries), "traces_represented": selection.traces_represented},
+        "fixtures": entries,
+    }
+    if manifest["policy"] is None:
+        del manifest["policy"]
+    pending = {f["file"]: write.fixture_bytes(kept_traces[f["id"]]) for f in entries}
+    pending["manifest.json"] = write.dumps(manifest)
+    pending[write.TEST_FILE] = write.generated_test(o.agent).encode("utf-8")
+    leaks = scan_files(pending, o.deny_literals, [presidio_find()] if o.pii == "presidio" else [])
+    removed: list[str] = []
+    if not leaks:                                   # nothing reaches the disk if the scan finds a value
+        removed = write.write_all(out, entries, kept_traces, manifest, o.agent, o.bundle)
+    return BuildResult(fmt, len(traces), sc.report.total, len(good), mism, len(done) - len(good),
+                       selection, removed, leaks, out, warnings)
+
+
+def _engine() -> str:
+    from importlib import metadata
+    try:
+        return f"faultgate-zero {metadata.version('faultgate-zero')}"
+    except metadata.PackageNotFoundError:
+        return "faultgate-zero"
+
+
+@dataclass
+class Explanation:
+    trace_hash: str
+    changes: list[tuple[str, str, int, int]]
+    raw: dict[str, bool]
+    scrubbed: dict[str, bool]
+    signature: str
+    group_size: int
+    selected: bool
+    why: str
+    fixture_id: str
+
+
+def explain(o: Options_, trace_id: str) -> Explanation:
+    fmt, traces, _ = load.load(o.input, o.fmt)
+    settings = make_settings(o)
+    sc = make_scrubber(o)
+    done = process(traces, sc, settings)
+    want = trace_id.strip()
+    idx = next((i for i, t in enumerate(traces)
+                if t.trace_id == want or done[i].fixture_id == want or done[i].trace_hash == want), None)
+    if idx is None:
+        raise load.InputError(f"no trace with id {want!r} in the export")
+    one = make_scrubber(o)
+    one.scrub_trace(traces[idx])
+    cands = [Candidate(p.fixture_id, p.scrubbed, p.fired, p.json_size) for p in done if not p.mismatch]
+    sel = select(cands, o.per_group, o.max_clean)
+    p = done[idx]
+    sig = signature(p.scrubbed, p.fired)
+    group = next((g for g in sel.groups if g.signature == sig), None)
+    kept = {c.fixture_id for c, _, _ in sel.kept}
+    selected = p.fixture_id in kept
+    if selected:
+        why = "kept: " + ("it fired a check" if p.fired else "shortest run of a large clean group")
+    elif group is None or p.mismatch:
+        why = "not selected: verdicts changed by scrubbing" if p.mismatch else "not selected"
+    elif not p.fired:
+        why = "not selected: its clean group is outside --max-clean, or another run of the group is shorter"
+    else:
+        why = "not selected: another run of its failing group is shorter (--per-group)"
+    return Explanation(p.trace_hash, one.report.changes,
+                       preserve.verdicts(traces[idx], settings), p.expected, sig, group.size if group else 1,
+                       selected, why, p.fixture_id)