falsifyai 0.1.0__py3-none-any.whl

falsifyai/__init__.py

@@ -0,0 +1,3 @@
+"""FalsifyAI — falsification-first reliability testing for AI systems."""
+
+__version__ = "0.1.0"

falsifyai/cli/__init__.py

@@ -0,0 +1,8 @@
+"""``falsifyai`` command-line interface.
+
+The console script entry point ``falsifyai = "falsifyai.cli.main:main"`` is
+wired in ``pyproject.toml``. Import the submodule directly
+(``from falsifyai.cli.main import main``) — no re-export here, because doing
+so would shadow the ``falsifyai.cli.main`` submodule with its ``main``
+function and break ``import falsifyai.cli.main``.
+"""

falsifyai/cli/diff.py

@@ -0,0 +1,237 @@
+"""``falsifyai diff <baseline> <candidate>`` -- the launch wedge.
+
+Loads two stored ``ReplayArtifact``s, compares them case-by-case, surfaces
+verdict transitions in a compressed table, and exits **code 5 (REGRESSION)**
+if any case regressed.
+
+This is the differentiator per [plan.md §22.1](../../plan.md). Competitors
+match an engine that runs perturbations; they do not flag model-migration
+regressions with a single command.
+
+**Invariants:**
+
+- ``cmd_diff`` is strictly read-only. Never modifies either artifact.
+- The diff does NOT re-resolve verdicts under the current resolver. The
+  verdicts compared are the ones assigned at each ``run`` time. Diff is a
+  consumer of already-resolved artifacts; the resolver stays untouched.
+- Regression criterion is **verdict-class downgrade only**: STABLE -> FRAGILE,
+  STABLE -> CONSISTENTLY_WRONG, FRAGILE -> CONSISTENTLY_WRONG. No thresholds,
+  no per-stability deltas as regression signals. Predictable by design.
+- Cases present in only one side are surfaced as ADDED / REMOVED but do NOT
+  trigger exit 5. Specs evolve legitimately.
+"""
+
+import argparse
+from dataclasses import dataclass
+from enum import Enum
+
+from falsifyai.cli import render
+from falsifyai.cli.errors import InfrastructureError
+from falsifyai.replay.in_memory_store import InMemoryStore
+from falsifyai.replay.models import ReplayArtifact
+from falsifyai.replay.protocol import ReplayStore, SessionNotFoundError
+from falsifyai.replay.sqlite_store import SQLiteStore
+from falsifyai.verdict.models import Verdict
+
+
+class TransitionKind(Enum):
+    """How a case's verdict changed between baseline and candidate."""
+
+    UNCHANGED = "unchanged"
+    IMPROVED = "improved"
+    REGRESSED = "regressed"
+    OTHER_CHANGE = "other_change"  # informational; not a regression
+    ADDED = "added"  # in candidate only
+    REMOVED = "removed"  # in baseline only
+
+
+@dataclass(frozen=True)
+class CaseTransition:
+    """One row in the diff: how case <case_id>'s verdict changed."""
+
+    case_id: str
+    baseline_verdict: Verdict | None  # None if ADDED
+    candidate_verdict: Verdict | None  # None if REMOVED
+    baseline_stability_ci_low: float
+    candidate_stability_ci_low: float
+    transition_kind: TransitionKind
+
+
+@dataclass(frozen=True)
+class DiffReport:
+    """Compressed summary of a diff between two ReplayArtifacts."""
+
+    baseline_session_id: str
+    candidate_session_id: str
+    materialized_hash_mismatch: bool
+    transitions: list[CaseTransition]
+    regressed_count: int
+    improved_count: int
+    unchanged_count: int
+    other_change_count: int
+    added_count: int
+    removed_count: int
+
+
+# ---------------------------------------------------------------------------
+# Transition classification
+# ---------------------------------------------------------------------------
+
+
+# Verdict-class downgrades that count as REGRESSED.
+# Read as: baseline_verdict -> {candidate_verdicts that are regressions}.
+_REGRESSION_DOWNGRADES: dict[Verdict, frozenset[Verdict]] = {
+    Verdict.STABLE: frozenset({Verdict.FRAGILE, Verdict.CONSISTENTLY_WRONG}),
+    Verdict.FRAGILE: frozenset({Verdict.CONSISTENTLY_WRONG}),
+}
+
+# Reverse direction: IMPROVED. STABLE is the "good" pole; transitioning toward
+# it (from any worse verdict) counts as improvement.
+_IMPROVEMENT_TARGETS: dict[Verdict, frozenset[Verdict]] = {
+    Verdict.STABLE: frozenset({Verdict.FRAGILE, Verdict.CONSISTENTLY_WRONG, Verdict.INSUFFICIENT})
+}
+
+
+def _classify_transition(baseline: Verdict, candidate: Verdict) -> TransitionKind:
+    """Decide what kind of transition this verdict-pair represents.
+
+    See ``_REGRESSION_DOWNGRADES`` and ``_IMPROVEMENT_TARGETS`` for the
+    canonical mappings. Any other transition (e.g., STABLE -> INSUFFICIENT
+    or anything involving INVALID_EVAL) is OTHER_CHANGE -- informational
+    but not a regression.
+    """
+    if baseline is candidate:
+        return TransitionKind.UNCHANGED
+    if candidate in _REGRESSION_DOWNGRADES.get(baseline, frozenset()):
+        return TransitionKind.REGRESSED
+    # Improvement: candidate is STABLE and baseline was a worse verdict.
+    if baseline in _IMPROVEMENT_TARGETS.get(candidate, frozenset()):
+        return TransitionKind.IMPROVED
+    return TransitionKind.OTHER_CHANGE
+
+
+def compute_diff(baseline: ReplayArtifact, candidate: ReplayArtifact) -> DiffReport:
+    """Pure function: compare two artifacts case-by-case, produce a DiffReport.
+
+    Cases are matched by ``case_id``. Cases in only one side are recorded as
+    ADDED / REMOVED. The regression criterion is verdict-class downgrade
+    per ``_classify_transition``.
+    """
+    baseline_cases = {c.case_id: c for c in baseline.case_results}
+    candidate_cases = {c.case_id: c for c in candidate.case_results}
+
+    all_case_ids = sorted(set(baseline_cases) | set(candidate_cases))
+    transitions: list[CaseTransition] = []
+    regressed = improved = unchanged = other_change = added = removed = 0
+
+    for case_id in all_case_ids:
+        b = baseline_cases.get(case_id)
+        c = candidate_cases.get(case_id)
+        if b is None:
+            transitions.append(
+                CaseTransition(
+                    case_id=case_id,
+                    baseline_verdict=None,
+                    candidate_verdict=c.verdict,
+                    baseline_stability_ci_low=0.0,
+                    candidate_stability_ci_low=c.stability_ci_low,
+                    transition_kind=TransitionKind.ADDED,
+                )
+            )
+            added += 1
+            continue
+        if c is None:
+            transitions.append(
+                CaseTransition(
+                    case_id=case_id,
+                    baseline_verdict=b.verdict,
+                    candidate_verdict=None,
+                    baseline_stability_ci_low=b.stability_ci_low,
+                    candidate_stability_ci_low=0.0,
+                    transition_kind=TransitionKind.REMOVED,
+                )
+            )
+            removed += 1
+            continue
+        kind = _classify_transition(b.verdict, c.verdict)
+        transitions.append(
+            CaseTransition(
+                case_id=case_id,
+                baseline_verdict=b.verdict,
+                candidate_verdict=c.verdict,
+                baseline_stability_ci_low=b.stability_ci_low,
+                candidate_stability_ci_low=c.stability_ci_low,
+                transition_kind=kind,
+            )
+        )
+        if kind is TransitionKind.REGRESSED:
+            regressed += 1
+        elif kind is TransitionKind.IMPROVED:
+            improved += 1
+        elif kind is TransitionKind.UNCHANGED:
+            unchanged += 1
+        else:
+            other_change += 1
+
+    return DiffReport(
+        baseline_session_id=baseline.session_id,
+        candidate_session_id=candidate.session_id,
+        materialized_hash_mismatch=baseline.materialized_hash != candidate.materialized_hash,
+        transitions=transitions,
+        regressed_count=regressed,
+        improved_count=improved,
+        unchanged_count=unchanged,
+        other_change_count=other_change,
+        added_count=added,
+        removed_count=removed,
+    )
+
+
+# ---------------------------------------------------------------------------
+# CLI orchestration
+# ---------------------------------------------------------------------------
+
+
+def _build_store(store_path: str) -> ReplayStore:
+    """Mirror cli/run.py and cli/replay.py's store selection."""
+    if store_path == ":memory:":
+        return InMemoryStore()
+    return SQLiteStore(store_path)
+
+
+def _load_artifact(store: ReplayStore, session_id: str, *, role: str) -> ReplayArtifact:
+    """Load an artifact, converting SessionNotFoundError to a user-facing CLIError."""
+    try:
+        return store.load_session(session_id)
+    except SessionNotFoundError as exc:
+        raise InfrastructureError(f"{role} session not found: {session_id}") from exc
+
+
+def _diff_exit_code(report: DiffReport) -> int:
+    """Exit code 5 (REGRESSION) if any case regressed, else 0."""
+    return 5 if report.regressed_count > 0 else 0
+
+
+def cmd_diff(args: argparse.Namespace) -> int:
+    """Entry point for the ``diff`` subcommand. Returns an exit code."""
+    store = _build_store(args.store_path)
+    try:
+        baseline = _load_artifact(store, args.baseline_session_id, role="baseline")
+        candidate = _load_artifact(store, args.candidate_session_id, role="candidate")
+    finally:
+        close = getattr(store, "close", None)
+        if callable(close):
+            close()
+
+    report = compute_diff(baseline, candidate)
+    render.render_diff(report, store_path=args.store_path)
+    return _diff_exit_code(report)
+
+
+__all__ = [
+    "CaseTransition",
+    "DiffReport",
+    "TransitionKind",
+    "cmd_diff",
+    "compute_diff",
+]

falsifyai/cli/errors.py

@@ -0,0 +1,30 @@
+"""CLI-layer exception hierarchy.
+
+The CLI catches these and maps them to exit codes per
+[plan.md section 16.1](../../plan.md). Code 3 (ERROR) is reserved for
+infrastructure-class failures raised by the CLI layer *before* a verdict
+exists — bad spec, missing API key, network unreachable, etc.
+
+Verdict-derived exit codes (0, 1, 2, 4) come from
+``falsifyai.cli.render.exit_code_for`` and never raise.
+"""
+
+
+class CLIError(Exception):
+    """Base for all CLI-layer failures. Carries the intended exit code."""
+
+    def __init__(self, message: str, *, exit_code: int = 3) -> None:
+        super().__init__(message)
+        self.exit_code = exit_code
+
+
+class SpecError(CLIError):
+    """The spec file cannot be loaded or parsed."""
+
+
+class ConfigError(CLIError):
+    """A configuration / dependency / credential prerequisite is missing."""
+
+
+class InfrastructureError(CLIError):
+    """Network / model-call / store failure during a run."""

falsifyai/cli/main.py

@@ -0,0 +1,105 @@
+"""``falsifyai`` CLI entry point.
+
+Argparse-based dispatch. Three subcommands: ``run`` (execute a spec),
+``replay`` (re-render a stored session), and ``diff`` (compare two
+stored sessions and exit 5 on regression).
+
+Exit codes (per [plan.md section 16.1](../../plan.md)):
+
+- 0 SUCCESS — session verdict STABLE
+- 1 DEGRADED — session verdict FRAGILE
+- 2 FAILURE — session verdict CONSISTENTLY_WRONG / INVALID_EVAL
+- 3 ERROR — infrastructure failure (bad spec, missing credential, model call)
+- 4 INSUFFICIENT — not enough evidence to discriminate
+
+Codes 5 (REGRESSION) and 6 (LOW_FALSIFIABILITY) ship with Week 2 features.
+"""
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from falsifyai.cli import diff as diff_cmd
+from falsifyai.cli import replay as replay_cmd
+from falsifyai.cli import run as run_cmd
+from falsifyai.cli.errors import CLIError
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="falsifyai",
+        description="Falsification-first reliability testing for AI systems.",
+    )
+    subparsers = parser.add_subparsers(dest="command", metavar="<command>")
+
+    run_parser = subparsers.add_parser("run", help="Run a falsification eval against a spec.")
+    run_parser.add_argument("spec_path", help="Path to the YAML spec file.")
+    run_parser.add_argument(
+        "--store-path",
+        default=".falsifyai/replays.db",
+        help="ReplayStore path. Use ':memory:' for an ephemeral run. "
+        "Default: .falsifyai/replays.db",
+    )
+
+    replay_parser = subparsers.add_parser(
+        "replay", help="Load and re-render a previously stored session."
+    )
+    replay_parser.add_argument(
+        "session_id",
+        nargs="?",
+        default=None,
+        help="Session id to load. Omit if using --latest.",
+    )
+    replay_parser.add_argument(
+        "--latest",
+        action="store_true",
+        help="Load the most recent session in the store. Mutually exclusive with session_id.",
+    )
+    replay_parser.add_argument(
+        "--store-path",
+        default=".falsifyai/replays.db",
+        help="ReplayStore path. Default: .falsifyai/replays.db",
+    )
+
+    diff_parser = subparsers.add_parser(
+        "diff",
+        help="Compare two stored sessions case-by-case. Exit 5 if any case regressed.",
+    )
+    diff_parser.add_argument("baseline_session_id", help="Baseline session id.")
+    diff_parser.add_argument("candidate_session_id", help="Candidate session id.")
+    diff_parser.add_argument(
+        "--store-path",
+        default=".falsifyai/replays.db",
+        help="ReplayStore path (both artifacts assumed in same store). "
+        "Default: .falsifyai/replays.db",
+    )
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    try:
+        if args.command == "run":
+            return run_cmd.cmd_run(args)
+        if args.command == "replay":
+            return replay_cmd.cmd_replay(args)
+        if args.command == "diff":
+            return diff_cmd.cmd_diff(args)
+    except CLIError as exc:
+        print(f"falsifyai: error: {exc}", file=sys.stderr)
+        return exc.exit_code
+
+    # Unknown subcommand (argparse would normally have caught this).
+    parser.error(f"unknown command: {args.command}")
+    return 2  # pragma: no cover - parser.error raises SystemExit
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

falsifyai/cli/render.py

@@ -0,0 +1,196 @@
+"""Plain-text terminal output for ``falsifyai run``, ``replay``, and ``diff``.
+
+MVP scope: one row per case + a summary footer + the session id and store
+path so the user can find their saved artifact. No colors, no boxes, no
+JSON. Rich/colored output and ``--json`` land in Week 3 per
+[plan.md section 22.1](../../plan.md).
+
+The ``loaded_from`` parameter on ``render_session`` is what distinguishes
+the replay path: when set, an extra header line indicates the user is
+looking at a stored session rather than a fresh run. The detection of
+legacy artifacts (pre-PR-11, no CI evidence) lives in this module too --
+the artifact shape, not the consumer, determines what's renderable.
+
+``render_diff`` is the diff CLI's render path (PR #14). It consumes a
+``DiffReport`` (consumer-side dataclass from cli/diff.py) and prints a
+compressed transition table: only rows where something changed are shown.
+"""
+
+import sys
+from datetime import datetime
+from typing import TYPE_CHECKING, TextIO
+
+from falsifyai.replay.models import CaseResult, ReplayArtifact
+from falsifyai.verdict.models import Verdict
+
+if TYPE_CHECKING:
+    # Type-only import to avoid a circular import at runtime: cli/diff.py
+    # imports render. The DiffReport dataclass lives in diff.py because it
+    # is a consumer-side structure, not part of the persisted artifact schema.
+    from falsifyai.cli.diff import CaseTransition, DiffReport
+
+# Exit codes mapped to the MVP 5 verdicts per plan.md section 16.1.
+#   STABLE              -> 0  SUCCESS
+#   FRAGILE             -> 1  DEGRADED
+#   CONSISTENTLY_WRONG  -> 2  FAILURE
+#   INVALID_EVAL        -> 2  FAILURE
+#   INSUFFICIENT        -> 4  INSUFFICIENT
+# Code 3 (ERROR) is reserved for infrastructure failures raised by the CLI
+# layer before a verdict exists; code 5 (REGRESSION) and 6 (LOW_FALSIFIABILITY)
+# land with the Week 2 features.
+_EXIT_CODES: dict[Verdict, int] = {
+    Verdict.STABLE: 0,
+    Verdict.FRAGILE: 1,
+    Verdict.CONSISTENTLY_WRONG: 2,
+    Verdict.INVALID_EVAL: 2,
+    Verdict.INSUFFICIENT: 4,
+}
+
+
+def exit_code_for(verdict: Verdict) -> int:
+    """CI exit code for a session-level verdict."""
+    return _EXIT_CODES[verdict]
+
+
+def _is_legacy_case(case: CaseResult) -> bool:
+    """Pre-PR-11 artifact heuristic: nonzero verdict_confidence but no CI evidence.
+
+    The defaults from the dataclass extension (zero CI fields) trigger this
+    only when the case was constructed without PR #11's resolver -- i.e., it
+    was loaded from a pre-PR-11 replay store row. We require
+    ``verdict_confidence > 0`` so an INSUFFICIENT case (all zeros, legitimately)
+    doesn't get the legacy marker.
+    """
+    return (
+        case.verdict_confidence > 0.0
+        and case.stability == 0.0
+        and case.stability_ci_high == 0.0
+        and case.stability_ci_low == 0.0
+    )
+
+
+def render_session(
+    artifact: ReplayArtifact,
+    *,
+    store_path: str,
+    stream: TextIO | None = None,
+    loaded_from: datetime | None = None,
+) -> None:
+    """Print one row per case, then a summary footer.
+
+    Per-case row format:
+        case: <id>  verdict: <V>  confidence: <p> (CI: <lo>-<hi>)  worst: <family>?
+
+    When ``loaded_from`` is set (replay path), an extra header line is
+    prepended indicating the session was loaded from the store.
+
+    Legacy case detection: cases without CI evidence (pre-PR-11 artifacts)
+    omit the misleading ``(CI: 0.00-0.00)`` and append ``(legacy)`` instead.
+    """
+    out = stream if stream is not None else sys.stdout
+
+    if loaded_from is not None:
+        out.write(
+            f"Loaded session {artifact.session_id} · "
+            f"created_at {loaded_from.isoformat()} from {store_path}\n"
+        )
+
+    for case in artifact.case_results:
+        if _is_legacy_case(case):
+            line = (
+                f"case: {case.case_id}  verdict: {case.verdict.value.upper()}  "
+                f"confidence: {case.verdict_confidence:.2f}  (legacy)"
+            )
+        else:
+            line = (
+                f"case: {case.case_id}  verdict: {case.verdict.value.upper()}  "
+                f"confidence: {case.verdict_confidence:.2f} "
+                f"(CI: {case.stability_ci_low:.2f}-{case.stability_ci_high:.2f})"
+            )
+            if case.verdict is Verdict.FRAGILE and case.worst_case_family:
+                line += f"  worst: {case.worst_case_family}"
+        out.write(line + "\n")
+    out.write("=" * 65 + "\n")
+    out.write(f"Session {artifact.session_id} -> {store_path}\n")
+    sv = artifact.session_verdict
+    out.write(
+        f"{sv.case_count} case{'s' if sv.case_count != 1 else ''}, "
+        f"verdict {sv.session_verdict.value.upper()}, "
+        f"{sv.fragile_count} FRAGILE, "
+        f"{sv.consistently_wrong_count} CONSISTENTLY_WRONG, "
+        f"falsifiability {sv.falsifyai_falsifiability_score:.2f}\n"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Diff rendering (PR #14)
+# ---------------------------------------------------------------------------
+
+
+def _format_verdict_with_stability(verdict: Verdict | None, ci_low: float) -> str:
+    """Format ``STABLE (0.92)`` or ``-`` if the case is absent on one side."""
+    if verdict is None:
+        return "-"
+    return f"{verdict.value.upper()} ({ci_low:.2f})"
+
+
+def _format_transition_row(t: "CaseTransition") -> str:
+    """One row of the diff transition table.
+
+    Format: ``case: <id>  baseline: <V> (n.nn)  candidate: <V> (n.nn)  <KIND>``
+    """
+    baseline_str = _format_verdict_with_stability(t.baseline_verdict, t.baseline_stability_ci_low)
+    candidate_str = _format_verdict_with_stability(
+        t.candidate_verdict, t.candidate_stability_ci_low
+    )
+    return (
+        f"case: {t.case_id}  "
+        f"baseline: {baseline_str}  "
+        f"candidate: {candidate_str}  "
+        f"{t.transition_kind.value.upper()}"
+    )
+
+
+def render_diff(
+    report: "DiffReport",
+    *,
+    store_path: str,
+    stream: TextIO | None = None,
+) -> None:
+    """Print a compressed transition table for two stored sessions.
+
+    Only transitions != UNCHANGED are surfaced as rows. The summary footer
+    always shows the full counts (unchanged + regressed + improved + ...).
+    Evidence density: show what changed; report what didn't via counts only.
+    """
+    from falsifyai.cli.diff import TransitionKind
+
+    out = stream if stream is not None else sys.stdout
+
+    out.write(
+        f"Diff: baseline {report.baseline_session_id} -> candidate {report.candidate_session_id}\n"
+    )
+    out.write(f"Store: {store_path}\n")
+    if report.materialized_hash_mismatch:
+        out.write(
+            "note: materialized_hash differs between baseline and candidate; "
+            "comparisons may not be apples-to-apples.\n"
+        )
+    out.write("=" * 65 + "\n")
+
+    surfaced = [t for t in report.transitions if t.transition_kind is not TransitionKind.UNCHANGED]
+    if not surfaced:
+        out.write("(no transitions; all cases unchanged)\n")
+    else:
+        for t in surfaced:
+            out.write(_format_transition_row(t) + "\n")
+
+    out.write("=" * 65 + "\n")
+    out.write(
+        f"{report.regressed_count} regressed, "
+        f"{report.improved_count} improved, "
+        f"{report.unchanged_count} unchanged, "
+        f"{report.other_change_count} other, "
+        f"{report.added_count} added, "
+        f"{report.removed_count} removed\n"
+    )

falsifyai/cli/replay.py

@@ -0,0 +1,76 @@
+"""``falsifyai replay <session_id>`` -- read-only consumer surface.
+
+Loads a stored ``ReplayArtifact`` from the configured ``ReplayStore`` and
+re-renders it via the existing ``cli/render.render_session``. No model
+calls, no resolver invocation, no perturbations -- pure inspection of a
+past run.
+
+Invariants:
+
+- ``cmd_replay`` is strictly read-only. It never modifies the stored
+  artifact. The verdict displayed is the verdict the resolver assigned at
+  ``run`` time -- not a re-resolution under the current resolver.
+- Exit codes mirror ``run``: the verdict-derived exit code lets CI use
+  ``falsifyai replay <known-good-id>`` as a regression gate.
+- ``--store-path :memory:`` is supported for symmetry with ``run``, even
+  though ``InMemoryStore`` is empty on every fresh process. Failure mode
+  is loud: ``SessionNotFoundError`` -> exit 3.
+"""
+
+import argparse
+
+from falsifyai.cli import render
+from falsifyai.cli.errors import InfrastructureError
+from falsifyai.replay.in_memory_store import InMemoryStore
+from falsifyai.replay.protocol import ReplayStore, SessionNotFoundError
+from falsifyai.replay.sqlite_store import SQLiteStore
+
+
+def _build_store(store_path: str) -> ReplayStore:
+    """Mirror cli/run.py's store selection: ``:memory:`` -> InMemoryStore."""
+    if store_path == ":memory:":
+        return InMemoryStore()
+    return SQLiteStore(store_path)
+
+
+def _resolve_target_session_id(store: ReplayStore, args: argparse.Namespace) -> str:
+    """Pick the session_id to load: explicit, or newest if ``--latest``."""
+    if args.latest:
+        if args.session_id is not None:
+            # argparse should already reject this; defensive guard.
+            raise InfrastructureError("--latest is mutually exclusive with a positional session_id")
+        newest = next(iter(store.query_sessions(limit=1)), None)
+        if newest is None:
+            raise InfrastructureError("no sessions in store; cannot resolve --latest")
+        return newest.session_id
+
+    if args.session_id is None:
+        raise InfrastructureError("session_id is required (or pass --latest)")
+    return args.session_id
+
+
+def cmd_replay(args: argparse.Namespace) -> int:
+    """Entry point for the ``replay`` subcommand. Returns an exit code."""
+    store = _build_store(args.store_path)
+    try:
+        session_id = _resolve_target_session_id(store, args)
+        try:
+            artifact = store.load_session(session_id)
+        except SessionNotFoundError as exc:
+            raise InfrastructureError(f"session not found: {session_id}") from exc
+    finally:
+        # InMemoryStore has no close(); SQLiteStore does.
+        close = getattr(store, "close", None)
+        if callable(close):
+            close()
+
+    render.render_session(
+        artifact,
+        store_path=args.store_path,
+        loaded_from=artifact.created_at,
+    )
+
+    return render.exit_code_for(artifact.session_verdict.session_verdict)
+
+
+__all__ = ["cmd_replay"]