tracefork 0.1.0__py3-none-any.whl

tracefork/__init__.py

@@ -0,0 +1,6 @@
+"""tracefork — time-travel debugger for AI agents."""
+
+from .recorder import AsyncRecorder, Recorder
+from .tape import Tape
+
+__all__ = ["Recorder", "AsyncRecorder", "Tape"]

tracefork/blame.py

@@ -0,0 +1,296 @@
+"""Blame engine: rank each exchange by causal flip-rate with Wilson CIs.
+
+The causal question is "if step *i* had gone differently, how often would the
+run's *outcome* change?" Answering it honestly requires re-running the agent,
+not just rewriting the tape: perturbing step *i*'s response changes every
+request the agent makes afterward. So for each candidate step we:
+
+  1. fork the recorded run at *i* with a perturbed response — the prefix is
+     replayed from the parent tape for $0 and the agent is re-run from there
+     (`ForkEngine.fork`);
+  2. grade the resulting outcome with an `Oracle`;
+  3. count it as a *flip* when the graded outcome differs from the parent run's.
+
+`flip_rate = flips / k` over `k` trials, with a Wilson score 95% interval so a
+small *k* doesn't masquerade as certainty. `BudgetGovernor` estimates the
+fork count and dollar cost before any spend.
+
+The engine is agent- and domain-agnostic: the caller supplies `agent_fn` (the
+same agent that produced the tape) and a `perturb_factory(step) -> (response,
+tail_transport)`. In tests and the offline validation suite, `tail_transport`
+is a scripted fake (zero cost); for a live run it is `None`, so the
+counterfactual tail hits the real API under the budget cap.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Protocol, cast
+
+import httpx
+
+from .constants import PRICING_TABLE, SONNET
+from .fork import BranchSpec, ForkEngine
+from .tape import Tape
+
+# ── Wilson score CI ────────────────────────────────────────────────────────
+
+
+def wilson_ci(successes: int, n: int, z: float = 1.96) -> tuple[float, float]:
+    """95% Wilson score confidence interval for a proportion."""
+    if n == 0:
+        return (0.0, 1.0)
+    p = successes / n
+    denom = 1 + z**2 / n
+    centre = (p + z**2 / (2 * n)) / denom
+    spread = (z * math.sqrt(p * (1 - p) / n + z**2 / (4 * n**2))) / denom
+    return (max(0.0, centre - spread), min(1.0, centre + spread))
+
+
+# ── Oracle protocol ─────────────────────────────────────────────────────────
+
+
+class Oracle(Protocol):
+    def grade(self, output: str) -> bool | None: ...
+
+
+class StringMatchOracle:
+    """Grades by regex match: True=success, False=failure, None=ambiguous."""
+
+    def __init__(self, *, success_re: str, failure_re: str) -> None:
+        import re
+
+        self._success = re.compile(success_re)
+        self._failure = re.compile(failure_re)
+
+    def grade(self, output: str) -> bool | None:
+        if self._success.search(output):
+            return True
+        if self._failure.search(output):
+            return False
+        return None
+
+
+# ── Result types ────────────────────────────────────────────────────────────
+
+
+@dataclass
+class FlipRateResult:
+    step_index: int
+    flip_rate: float
+    ci_lo: float
+    ci_hi: float
+    flips: int
+    trials: int
+    interpretation: str = ""
+
+
+@dataclass
+class BlameReport:
+    results: list[FlipRateResult]
+    k: int
+    total_forks: int
+    parent_outcome: bool | None = None
+    est_cost_usd: float = 0.0
+
+    def top(self) -> FlipRateResult | None:
+        if not self.results:
+            return None
+        return max(self.results, key=lambda r: r.flip_rate)
+
+
+@dataclass
+class BlameEstimate:
+    n_candidates: int
+    n_forks: int
+    est_usd: float
+
+
+# ── BudgetGovernor ──────────────────────────────────────────────────────────
+
+
+class BudgetExceededError(RuntimeError):
+    """Raised when a blame run's estimated cost exceeds the caller's budget."""
+
+
+def _detect_model(tape: Tape) -> str:
+    """Best-effort model id from the first recorded request (defaults to Sonnet)."""
+    for req, _ in tape.exchanges:
+        try:
+            m = json.loads(req).get("model")
+        except Exception:
+            m = None
+        if m:
+            return m
+    return SONNET
+
+
+def _avg_tokens(tape: Tape) -> tuple[float, float]:
+    """Average (input, output) tokens per exchange — from recorded ``usage`` when
+    present, else a ~4-bytes-per-token estimate from the raw bytes."""
+    if not tape.exchanges:
+        return (0.0, 0.0)
+    ins: list[float] = []
+    outs: list[float] = []
+    for req, resp in tape.exchanges:
+        usage: dict = {}
+        try:
+            d = json.loads(resp)
+            if isinstance(d, dict):
+                usage = d.get("usage") or {}
+        except Exception:
+            usage = {}
+        ins.append(usage.get("input_tokens") or max(1, len(req) // 4))
+        outs.append(usage.get("output_tokens") or max(1, len(resp) // 4))
+    n = len(tape.exchanges)
+    return (sum(ins) / n, sum(outs) / n)
+
+
+class BudgetGovernor:
+    @staticmethod
+    def estimate(
+        tape: Tape,
+        *,
+        k: int,
+        model: str | None = None,
+        cost_per_fork_usd: float | None = None,
+    ) -> BlameEstimate:
+        """Estimate the dollar cost of a blame run.
+
+        Only the counterfactual *tail* hits the API — the replayed prefix and the
+        mutated step itself cost $0. Forking step ``i`` records ``n-1-i`` tail
+        calls, so total billed calls = ``sum_i (n-1-i) * k``. Each call is priced
+        with the model's real per-token rates (``constants.PRICING_TABLE``) against
+        the tape's recorded token usage. Pass ``cost_per_fork_usd`` to override with
+        a flat per-fork figure instead.
+        """
+        n_candidates = len(tape.exchanges)
+        n_forks = n_candidates * k
+        if cost_per_fork_usd is not None:
+            est_usd = n_forks * cost_per_fork_usd
+        else:
+            billed_calls = sum(n_candidates - 1 - i for i in range(n_candidates)) * k
+            in_rate, out_rate = PRICING_TABLE.get(
+                model or _detect_model(tape), PRICING_TABLE[SONNET]
+            )
+            avg_in, avg_out = _avg_tokens(tape)
+            est_usd = billed_calls * (avg_in * in_rate + avg_out * out_rate)
+        return BlameEstimate(n_candidates=n_candidates, n_forks=n_forks, est_usd=est_usd)
+
+
+# ── outcome extraction ────────────────────────────────────────────────────────
+
+
+def _outcome_text(resp_bytes: bytes) -> str:
+    """Extract the assistant's text from a recorded response (JSON or SSE)."""
+    try:
+        d = json.loads(resp_bytes)
+    except Exception:
+        return resp_bytes.decode(errors="replace")
+    if isinstance(d, dict):
+        for block in d.get("content", []):
+            if block.get("type") == "text":
+                return block.get("text", "")
+    return ""
+
+
+def _interpret(flip_rate: float) -> str:
+    if flip_rate >= 0.7:
+        return "decisive — this step caused it"
+    if flip_rate >= 0.3:
+        return "suggestive"
+    return "diffuse — not the cause"
+
+
+# ── BlameEngine ─────────────────────────────────────────────────────────────
+
+
+class BlameEngine:
+    """Ranks exchanges by causal flip-rate."""
+
+    @staticmethod
+    def rank(
+        tape: Tape,
+        agent_fn,  # Callable[[anthropic.Anthropic], Any] — the SAME agent
+        oracle: Oracle,
+        *,
+        perturb_factory: Callable[[int], tuple[bytes, object]],
+        k: int = 10,
+        budget_usd: float = 5.0,
+        api_key: str = "sk-ant-blame",
+    ) -> BlameReport:
+        """Fork each exchange `k` times with a perturbed response and measure how
+        often the graded outcome flips relative to the parent run.
+
+        `perturb_factory(step_idx)` returns `(mutated_response_bytes,
+        tail_transport)`, where `tail_transport` serves the counterfactual tail
+        (a scripted fake offline, or `None` to use the real API).
+        """
+        est = BudgetGovernor.estimate(tape, k=k)
+        if est.est_usd > budget_usd:
+            raise BudgetExceededError(
+                f"estimated blame cost ${est.est_usd:.2f} exceeds budget "
+                f"${budget_usd:.2f} ({est.n_forks} forks at k={k}); raise the budget "
+                f"or lower k"
+            )
+
+        parent_outcome: bool | None = None
+        if tape.exchanges:
+            parent_outcome = oracle.grade(_outcome_text(tape.exchanges[-1][1]))
+
+        results: list[FlipRateResult] = []
+        total_forks = 0
+
+        for step_idx in range(len(tape.exchanges)):
+            flips = 0
+            for _trial in range(k):
+                mutated_resp, tail_transport_obj = perturb_factory(step_idx)
+                tail_transport = cast("httpx.BaseTransport | None", tail_transport_obj)
+                spec = BranchSpec(divergence_step=step_idx, mutated_response=mutated_resp)
+                try:
+                    branch = ForkEngine.fork(
+                        tape,
+                        spec,
+                        agent_fn,
+                        post_fork_transport=tail_transport,
+                        api_key=api_key,
+                    )
+                    total_forks += 1
+                except Exception:
+                    # A divergent fork (e.g. agent not deterministic up to the
+                    # step) counts as cost spent but no observed flip.
+                    total_forks += 1
+                    continue
+
+                if branch.delta_tape.exchanges:
+                    graded = oracle.grade(_outcome_text(branch.delta_tape.exchanges[-1][1]))
+                else:
+                    graded = None
+                if graded is not None and graded != parent_outcome:
+                    flips += 1
+
+            flip_rate = flips / k if k > 0 else 0.0
+            ci_lo, ci_hi = wilson_ci(flips, k)
+            results.append(
+                FlipRateResult(
+                    step_index=step_idx,
+                    flip_rate=flip_rate,
+                    ci_lo=ci_lo,
+                    ci_hi=ci_hi,
+                    flips=flips,
+                    trials=k,
+                    interpretation=_interpret(flip_rate),
+                )
+            )
+
+        results.sort(key=lambda r: r.flip_rate, reverse=True)
+        return BlameReport(
+            results=results,
+            k=k,
+            total_forks=total_forks,
+            parent_outcome=parent_outcome,
+            est_cost_usd=est.est_usd,
+        )

tracefork/cli.py

@@ -0,0 +1,367 @@
+"""tracefork CLI — entry point for all commands.
+
+    tracefork <command> [args]
+
+Commands: replay, verify, fork, report, serve, blame, validate.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+app = typer.Typer(name="tracefork", help="Time-travel debugger for AI agents.")
+
+
+@app.command()
+def replay(
+    tape_path: Path = typer.Argument(..., help="Path to a .tape.sqlite file"),  # noqa: B008
+    agent: str = typer.Option(..., "--agent", "-a", help="Import path of agent fn (pkg.mod:fn)"),
+) -> None:
+    """Replay a tape and print the verification receipt."""
+    import importlib
+
+    from tracefork.replay import ReplayVerifier
+    from tracefork.tape import Tape
+
+    tape = Tape.load(str(tape_path))
+
+    module_path, fn_name = agent.rsplit(":", 1)
+    mod = importlib.import_module(module_path)
+    agent_fn = getattr(mod, fn_name)
+
+    result = ReplayVerifier(tape, agent_fn).verify()
+    _print_receipt(tape_path, result)
+    raise typer.Exit(0 if result.bit_exact else 1)
+
+
+@app.command()
+def verify(
+    tape_path: Path = typer.Argument(None, help="Single tape to verify"),  # noqa: B008
+    agent: str = typer.Option(None, "--agent", "-a", help="Import path of agent fn"),
+    corpus: bool = typer.Option(
+        False, "--corpus", help="Verify all tapes in experiments/validation_tapes/"
+    ),
+) -> None:
+    """Verify bit-exact replay. Exit 1 on drift."""
+    import importlib
+
+    from tracefork.replay import ReplayVerifier
+    from tracefork.tape import Tape
+
+    if corpus:
+        corpus_dir = Path("experiments/validation_tapes")
+        tapes = list(corpus_dir.glob("*.tape.sqlite"))
+        if not tapes:
+            typer.echo("No tapes found in experiments/validation_tapes/")
+            raise typer.Exit(1)
+        for tp in sorted(tapes):
+            typer.echo(f"  {tp.name}: skipped (agent not specified per-tape)")
+        typer.echo(f"Corpus: {len(tapes)} tapes scanned")
+        raise typer.Exit(0)
+
+    if tape_path is None or agent is None:
+        typer.echo("Provide --agent and a tape path, or use --corpus")
+        raise typer.Exit(1)
+
+    tape = Tape.load(str(tape_path))
+    module_path, fn_name = agent.rsplit(":", 1)
+    mod = importlib.import_module(module_path)
+    agent_fn = getattr(mod, fn_name)
+    result = ReplayVerifier(tape, agent_fn).verify()
+    _print_receipt(tape_path, result)
+    raise typer.Exit(0 if result.bit_exact else 1)
+
+
+@app.command()
+def fork(
+    run_id: str = typer.Argument(..., help="Parent run_id to fork from"),
+    step: int = typer.Option(..., "--step", "-s", help="Exchange index to diverge at"),
+    response_file: Path = typer.Option(  # noqa: B008
+        ..., "--response", "-r", help="Path to .bytes file containing mutated response"
+    ),
+    agent: str = typer.Option(..., "--agent", "-a", help="Import path of post-fork agent fn"),
+    store: Path = typer.Option(Path("store.db"), "--store", help="Path to store.db"),  # noqa: B008
+    desc: str = typer.Option("", "--desc", "-d", help="Human description of mutation"),
+) -> None:
+    """Fork a run at a step with a mutated response, record the new branch."""
+    import importlib
+
+    from tracefork.fork import BranchSpec, ForkEngine
+    from tracefork.store import TapeStore
+
+    db = TapeStore(str(store))
+    parent_tape = db.load_tape(run_id)
+
+    mutated_response = response_file.read_bytes()
+
+    module_path, fn_name = agent.rsplit(":", 1)
+    mod = importlib.import_module(module_path)
+    agent_fn = getattr(mod, fn_name)
+
+    spec = BranchSpec(
+        divergence_step=step,
+        mutated_response=mutated_response,
+        mutation_desc=desc,
+    )
+
+    branch = ForkEngine.fork(parent_tape, spec, agent_fn)
+
+    branch_id = db.save_branch(
+        parent_run_id=run_id,
+        divergence_step=step,
+        delta_tape=branch.delta_tape,
+        mutation_desc=desc,
+    )
+
+    typer.echo("\n  Fork created")
+    typer.echo(f"  branch_id       {branch_id}")
+    typer.echo(f"  parent_run_id   {run_id}")
+    typer.echo(f"  divergence_step {step}")
+    typer.echo(f"  delta_exchanges {len(branch.delta_tape.exchanges)}")
+    typer.echo(f"  description     {desc or '(none)'}\n")
+
+
+@app.command()
+def report(
+    run_id: str = typer.Argument(None, help="run_id to report on (from store)"),
+    tape_path: Path = typer.Option(  # noqa: B008
+        None, "--tape", "-t", help="Path to a .tape.sqlite file"
+    ),
+    output: Path = typer.Option(  # noqa: B008
+        Path("report.html"), "--output", "-o", help="Output HTML file"
+    ),
+    store: Path = typer.Option(  # noqa: B008
+        Path("store.db"), "--store", help="Path to store.db"
+    ),
+) -> None:
+    """Generate a self-contained HTML report from a tape."""
+    from tracefork.report import generate_report
+    from tracefork.tape import Tape
+
+    if tape_path:
+        tape = Tape.load(str(tape_path))
+    elif run_id:
+        from tracefork.store import TapeStore
+
+        db = TapeStore(str(store))
+        tape = db.load_tape(run_id)
+    else:
+        typer.echo("Provide a run_id or --tape path")
+        raise typer.Exit(1)
+
+    generate_report(tape, output)
+    typer.echo(f"Report written to {output}")
+
+
+@app.command()
+def serve(
+    store: Path = typer.Option(  # noqa: B008
+        Path("store.db"), "--store", help="Path to store.db"
+    ),
+    port: int = typer.Option(7777, "--port", "-p", help="Port to listen on"),
+) -> None:
+    """Start the tracefork web UI server on port 7777."""
+    import uvicorn
+
+    from tracefork.server import app as fastapi_app
+    from tracefork.server import init_store
+
+    init_store(str(store))
+    typer.echo(f"  tracefork serve → http://127.0.0.1:{port}")
+    uvicorn.run(fastapi_app, host="127.0.0.1", port=port, workers=1, log_level="warning")
+
+
+@app.command()
+def blame(
+    run_id: str = typer.Argument(..., help="run_id to analyze"),
+    agent: str = typer.Option(
+        ...,
+        "--agent",
+        "-a",
+        help="Import path of the agent fn (pkg.mod:fn) that produced this run; "
+        "it is re-run for each fork and must be deterministic up to the fork point",
+    ),
+    k: int = typer.Option(10, "--k", help="Forks per candidate step"),
+    budget: float = typer.Option(5.0, "--budget", help="USD spend cap"),
+    perturbation: str = typer.Option(
+        "[tracefork] this step did not complete as recorded",
+        "--perturbation",
+        help="Text injected as the counterfactual response",
+    ),
+    success_re: str = typer.Option("SUCCESS", "--success-re", help="Regex for success outcome"),
+    failure_re: str = typer.Option("FAIL", "--failure-re", help="Regex for failure outcome"),
+    store: Path = typer.Option(  # noqa: B008
+        Path("store.db"), "--store", help="Path to store.db"
+    ),
+) -> None:
+    """Run causal blame analysis on a recorded run.
+
+    For each exchange, the agent is re-run with that step's response perturbed
+    and the counterfactual tail recorded against the real API (budget-capped).
+    The offline, $0 proof that blame correctly fingers known faults is
+    `tracefork validate`.
+    """
+    if not run_id or not all(c.isalnum() or c in "-_" for c in run_id):
+        raise typer.BadParameter("run_id must be alphanumeric (with '-' or '_')")
+
+    import importlib
+    import json
+    import os
+
+    from tracefork.blame import BlameEngine, BudgetGovernor, StringMatchOracle
+    from tracefork.store import TapeStore
+    from tracefork.wire import make_text_response
+
+    db = TapeStore(str(store))
+    tape = db.load_tape(run_id)
+
+    module_path, fn_name = agent.rsplit(":", 1)
+    agent_fn = getattr(importlib.import_module(module_path), fn_name)
+
+    oracle = StringMatchOracle(success_re=success_re, failure_re=failure_re)
+    est = BudgetGovernor.estimate(tape, k=k)
+
+    typer.echo(f"\n  Blame estimate: {est.n_forks} forks, ~${est.est_usd:.2f}")
+    if est.est_usd > budget:
+        typer.echo(f"  Estimated cost ${est.est_usd:.2f} exceeds budget ${budget:.2f}.")
+        typer.echo("  Use --budget to increase or --k to reduce trials.")
+        raise typer.Exit(1)
+
+    mutated = make_text_response(perturbation)
+
+    def perturb_factory(step_idx: int):
+        # tail_transport=None → the counterfactual tail hits the real API.
+        return mutated, None
+
+    report = BlameEngine.rank(
+        tape,
+        agent_fn,
+        oracle,
+        perturb_factory=perturb_factory,
+        k=k,
+        budget_usd=budget,
+        api_key=os.environ.get("ANTHROPIC_API_KEY", ""),
+    )
+
+    typer.echo(f"\n  run-{run_id} · blame analysis · k={k} · {report.total_forks} forks\n")
+    typer.echo(f"  {'rank':<5} {'step':<8} {'flip-rate':<12} {'95% CI':<22} interpretation")
+    typer.echo(f"  {'─' * 70}")
+    for rank, r in enumerate(report.results, 1):
+        ci_str = f"[{r.ci_lo:.2f}, {r.ci_hi:.2f}]"
+        typer.echo(
+            f"  {rank:<5} step-{r.step_index:<3} {r.flip_rate:<12.2f} "
+            f"{ci_str:<22} {r.interpretation}"
+        )
+    typer.echo("")
+
+    report_path = Path(f"blame_{run_id}.json")
+    report_path.write_text(
+        json.dumps(
+            {
+                "run_id": run_id,
+                "k": k,
+                "results": [
+                    {
+                        "step_index": r.step_index,
+                        "flip_rate": r.flip_rate,
+                        "ci_lo": r.ci_lo,
+                        "ci_hi": r.ci_hi,
+                        "interpretation": r.interpretation,
+                    }
+                    for r in report.results
+                ],
+            },
+            indent=2,
+        )
+    )
+    typer.echo(f"  Report saved to {report_path}")
+
+
+@app.command()
+def validate(
+    k: int = typer.Option(3, "--k", help="Forks per candidate step per run"),
+    n_runs: int = typer.Option(5, "--n-runs", help="Runs per fault class"),
+    output: Path = typer.Option(  # noqa: B008
+        Path("validation_report.json"), "--output", "-o"
+    ),
+    check: bool = typer.Option(False, "--check", help="Diff vs committed report (regression gate)"),
+) -> None:
+    """Run fault-injection validation suite; produce validation_report.json."""
+    import json as _json
+
+    from tracefork.validate import run_all_fault_classes
+
+    typer.echo(f"\n  tracefork validate — k={k}, n_runs={n_runs} per class")
+    typer.echo(f"  {'─' * 50}")
+
+    results = run_all_fault_classes(k=k, n_runs=n_runs)
+
+    overall_precision = sum(r["top1_precision"] for r in results.values()) / len(results)
+    max_ctrl = max(r["negative_control_max_flip"] for r in results.values())
+
+    report_data = {
+        "top1_precision_by_class": {fc: v["top1_precision"] for fc, v in results.items()},
+        "overall_top1_precision": overall_precision,
+        "negative_control_max_flip": max_ctrl,
+        "n_runs_per_class": n_runs,
+        "k": k,
+        "reproduce_cmd": f"tracefork validate --k {k} --n-runs {n_runs}",
+    }
+
+    for fault_class, data in results.items():
+        status = "PASS" if data["top1_precision"] >= 0.7 else "WARN"
+        typer.echo(f"  [{status}] {fault_class:<35} top-1: {data['top1_precision']:.2f}")
+
+    typer.echo(f"\n  overall top-1 precision: {overall_precision:.2f}")
+    typer.echo(f"  negative control max flip: {max_ctrl:.2f} (threshold 0.30)")
+
+    output.write_text(_json.dumps(report_data, indent=2))
+    typer.echo(f"\n  Report saved to {output}\n")
+
+    control_threshold = 0.30
+    if max_ctrl >= control_threshold:
+        typer.echo(
+            f"  [FAIL] negative control max flip {max_ctrl:.2f} ≥ {control_threshold:.2f} "
+            "— blame is firing on no-op perturbations; the precision number is not trustworthy."
+        )
+        raise typer.Exit(1)
+
+    if check:
+        committed = Path("experiments/validation_report_committed.json")
+        if not committed.exists():
+            typer.echo("  No committed report found — run without --check to create one.")
+            raise typer.Exit(1)
+        old = _json.loads(committed.read_text())
+        regressions = []
+        for fc, new_prec in report_data["top1_precision_by_class"].items():
+            old_prec = old.get("top1_precision_by_class", {}).get(fc, 0.0)
+            if new_prec < old_prec - 0.15:
+                regressions.append(f"{fc}: {old_prec:.2f} → {new_prec:.2f}")
+        old_ctrl = old.get("negative_control_max_flip", 0.0)
+        if max_ctrl > old_ctrl + 0.15:
+            regressions.append(f"negative_control_max_flip: {old_ctrl:.2f} → {max_ctrl:.2f}")
+        if regressions:
+            typer.echo("  REGRESSION detected:")
+            for r_str in regressions:
+                typer.echo(f"    {r_str}")
+            raise typer.Exit(1)
+        typer.echo("  No regressions vs committed report.")
+
+
+def _print_receipt(tape_path: Path, result) -> None:
+    from tracefork.replay import DriftDoctor
+
+    status = "PASS" if result.bit_exact else "FAIL"
+    typer.echo("\n  tracefork — replay receipt")
+    typer.echo(f"  {'─' * 40}")
+    typer.echo(f"  tape            {tape_path.name}")
+    typer.echo(f"  exchanges       {result.matched}/{result.total} matched")
+    typer.echo(f"  fingerprint     {'match' if result.fingerprints_match else 'MISMATCH'}")
+    typer.echo(f"  result          {status}")
+    if result.divergence:
+        cause = DriftDoctor.classify(result.divergence)
+        typer.echo(f"  drift cause     {cause.value}")
+        typer.echo(f"  at exchange     #{result.divergence.step_index}")
+    typer.echo("")

tracefork/constants.py

@@ -0,0 +1,24 @@
+"""Centralised constants — model IDs, pricing, determinism boundary."""
+
+BOUNDARY_V1 = "single-process-asyncio-v1"
+
+# Model IDs (consult claude-api skill before editing)
+SONNET = "claude-sonnet-4-6"
+HAIKU = "claude-haiku-4-5-20251001"
+OPUS = "claude-opus-4-8"
+
+# Pricing per token (USD), list price per 1M tokens — update PRICING_VERSION when
+# changed. Source: the `claude-api` skill (current Anthropic list pricing).
+PRICING_VERSION = "2026-06b"
+SONNET_INPUT_PER_TOKEN = 3.00 / 1_000_000
+SONNET_OUTPUT_PER_TOKEN = 15.00 / 1_000_000
+HAIKU_INPUT_PER_TOKEN = 1.00 / 1_000_000
+HAIKU_OUTPUT_PER_TOKEN = 5.00 / 1_000_000
+OPUS_INPUT_PER_TOKEN = 5.00 / 1_000_000
+OPUS_OUTPUT_PER_TOKEN = 25.00 / 1_000_000
+
+PRICING_TABLE: dict[str, tuple[float, float]] = {
+    SONNET: (SONNET_INPUT_PER_TOKEN, SONNET_OUTPUT_PER_TOKEN),
+    HAIKU: (HAIKU_INPUT_PER_TOKEN, HAIKU_OUTPUT_PER_TOKEN),
+    OPUS: (OPUS_INPUT_PER_TOKEN, OPUS_OUTPUT_PER_TOKEN),
+}