stepfork 0.1.0a2__py3-none-any.whl

stepfork/cli/replay.py

@@ -0,0 +1,221 @@
+"""`stepfork replay` command."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from stepfork.export.entrypoint import EntrypointError, resolve_entrypoint
+from stepfork.replay import (
+    RecordedDependencyError,
+    ReplayError,
+    ReplaySession,
+)
+from stepfork.trace import RunStatus, Trace, TraceStorageError
+from stepfork.trace.canonical import canonical_json_bytes
+from stepfork.trace.jsonable import TraceSerializationError, to_json_value
+from stepfork.trace.redaction import redact_json
+from stepfork.trace.replay_policy import ReplayPolicy
+
+console = Console()
+PREVIEW_LIMIT = 400
+
+
+def replay_command(
+    path: Annotated[
+        Path,
+        typer.Argument(
+            help="Path to a .sftrace directory bundle.",
+            exists=False,
+            file_okay=False,
+            dir_okay=True,
+            readable=True,
+        ),
+    ],
+    entrypoint: Annotated[
+        str,
+        typer.Option(
+            "--entrypoint",
+            help="Trusted local MODULE:FUNCTION to execute under replay.",
+        ),
+    ],
+    mode: Annotated[
+        str,
+        typer.Option(
+            "--mode",
+            help="Replay mode: frozen, live, forbidden, manual, or derived.",
+        ),
+    ] = "frozen",
+) -> None:
+    """Execute a trusted entrypoint with dependencies replayed from a trace.
+
+    Only the entrypoint you name is imported and run. Trace bundles are data:
+    Stepfork never executes code embedded in a trace.
+    """
+    try:
+        ReplayPolicy(mode)
+    except ValueError:
+        console.print(f"[red]Invalid replay mode {mode!r}.[/red]")
+        raise typer.Exit(2) from None
+
+    try:
+        trace = Trace.load(path)
+    except TraceStorageError as exc:
+        console.print("[red]Unable to read trace.[/red]")
+        console.print(_sanitize_text(str(exc)))
+        raise typer.Exit(2) from exc
+
+    try:
+        entry = resolve_entrypoint(entrypoint, import_root=Path.cwd())
+    except EntrypointError as exc:
+        console.print("[red]Unable to resolve entrypoint.[/red]")
+        console.print(_sanitize_text(str(exc)))
+        raise typer.Exit(2) from exc
+
+    divergence: str | None = None
+    result_value: Any = None
+    agent_exc: BaseException | None = None
+
+    try:
+        with ReplaySession.from_trace(trace, mode=mode) as replay:
+            try:
+                result_value = entry()
+            except ReplayError as exc:
+                divergence = _sanitize_text(str(exc))
+            except Exception as exc:
+                agent_exc = exc
+            if divergence is None:
+                try:
+                    replay.verify_complete()
+                except ReplayError as exc:
+                    divergence = _sanitize_text(str(exc))
+            matched = replay.matched
+            remaining = replay.pending
+    except ReplayError as exc:
+        console.print("[red]Replay failed before execution.[/red]")
+        console.print(_sanitize_text(str(exc)))
+        raise typer.Exit(1) from exc
+
+    status = "completed"
+    if divergence is None and agent_exc is not None:
+        failure_type = trace.failure.type if trace.failure else None
+        raised_type = type(agent_exc).__name__
+        if (trace.status is RunStatus.FAILED and raised_type == failure_type) or (
+            isinstance(agent_exc, RecordedDependencyError)
+            and trace.status is RunStatus.FAILED
+            and agent_exc.error_type == failure_type
+        ):
+            status = "reproduced_failure"
+        else:
+            recorded = f"status {trace.status.value}"
+            if failure_type:
+                recorded += f" (failure {failure_type})"
+            divergence = (
+                f"entrypoint raised {raised_type}: "
+                f"{_sanitize_text(str(agent_exc))} but the trace recorded "
+                f"{recorded}"
+            )
+    elif divergence is None and agent_exc is None:
+        if trace.status is RunStatus.FAILED:
+            divergence = (
+                "trace recorded a failed run but the entrypoint completed "
+                "without raising"
+            )
+
+    _print_report(
+        trace=trace,
+        path=path,
+        entrypoint=entrypoint,
+        mode=mode,
+        matched=matched,
+        remaining=remaining,
+        status=status,
+        divergence=divergence,
+        result_value=result_value,
+        agent_exc=agent_exc,
+    )
+
+    raise typer.Exit(1 if divergence is not None else 0)
+
+
+def _print_report(
+    *,
+    trace: Trace,
+    path: Path,
+    entrypoint: str,
+    mode: str,
+    matched: list[Any],
+    remaining: int,
+    status: str,
+    divergence: str | None,
+    result_value: Any,
+    agent_exc: BaseException | None,
+) -> None:
+    console.print("[bold]Stepfork Replay[/bold]")
+    console.print()
+
+    table = Table.grid(padding=(0, 4))
+    table.add_column(style="bold")
+    table.add_column()
+    table.add_row("Trace", str(path))
+    table.add_row("Agent", trace.agent_name)
+    table.add_row("Entrypoint", entrypoint)
+    table.add_row("Mode", mode)
+    console.print(table)
+    console.print()
+
+    console.print("[bold]Dependency Calls[/bold]")
+    if not matched:
+        console.print("  (no dependency calls matched)")
+    else:
+        for item in matched:
+            console.print(
+                f"  {item.index + 1}. {item.kind} {item.label} "
+                f"[green]({item.action})[/green]"
+            )
+    if remaining:
+        console.print(f"  [yellow]{remaining} recorded call(s) unmatched[/yellow]")
+    console.print()
+
+    if divergence is not None:
+        console.print("Status: [red]DIVERGED[/red]")
+        console.print(_sanitize_text(divergence))
+        console.print()
+        return
+
+    if status == "reproduced_failure" and agent_exc is not None:
+        console.print(
+            f"Status: [yellow]REPRODUCED FAILURE[/yellow] ({type(agent_exc).__name__})"
+        )
+    else:
+        console.print("Status: [green]COMPLETED[/green]")
+
+    console.print(f"Final result: {_result_preview(result_value)}")
+    console.print()
+
+
+def _result_preview(value: Any) -> str:
+    if value is None:
+        return "None"
+    try:
+        payload = to_json_value(value)
+        text = canonical_json_bytes(payload).decode("utf-8", errors="replace")
+    except TraceSerializationError:
+        return f"<non-serializable {type(value).__name__}>"
+    except TypeError:
+        return "<non-serializable>"
+    sanitized = _sanitize_text(text)
+    if len(sanitized) > PREVIEW_LIMIT:
+        return f"{sanitized[: PREVIEW_LIMIT - 1]}…"
+    return sanitized
+
+
+def _sanitize_text(value: str) -> str:
+    sanitized = redact_json(value).value
+    if isinstance(sanitized, str):
+        return sanitized
+    return str(sanitized)

stepfork/cli/validate.py

@@ -0,0 +1,160 @@
+"""`stepfork validate` command."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from stepfork.trace import TraceStorageError, ValidationResult, validate_bundle
+from stepfork.trace.integrity import IntegrityStatus, verify_bundle_integrity
+from stepfork.trace.storage import load_trace
+
+console = Console()
+
+UNREADABLE_CODES = {
+    "missing_file",
+    "invalid_json",
+    "invalid_manifest",
+    "invalid_event",
+    "unsupported_schema",
+    "integrity_metadata_invalid",
+    "integrity_algorithm_unsupported",
+}
+
+
+def validate_command(
+    path: Annotated[
+        Path,
+        typer.Argument(
+            help="Path to a .sftrace directory bundle.",
+            exists=False,
+            file_okay=False,
+            dir_okay=True,
+            readable=True,
+        ),
+    ],
+    partial: Annotated[
+        bool,
+        typer.Option(
+            "--partial",
+            help="Allow incomplete in-progress traces without run_start checks.",
+        ),
+    ] = False,
+    verify_integrity: Annotated[
+        bool,
+        typer.Option(
+            "--verify-integrity",
+            help="Verify per-event payload hashes and bundle integrity metadata.",
+        ),
+    ] = False,
+) -> None:
+    """Validate a `.sftrace` bundle."""
+    strict = not partial
+    structure_result = validate_bundle(path, strict=strict)
+    result = validate_bundle(
+        path,
+        strict=strict,
+        verify_integrity=verify_integrity,
+    )
+
+    _print_header(path, strict=strict)
+    _print_metadata(path, strict=strict)
+    if verify_integrity and structure_result.valid:
+        _print_integrity(path)
+
+    if result.valid:
+        console.print("[green]✓[/green] Manifest valid")
+        console.print("[green]✓[/green] Event structure valid")
+        console.print("[green]✓[/green] Event IDs unique")
+        console.print("[green]✓[/green] Parent references valid")
+        console.print("[green]✓[/green] Run IDs consistent")
+        console.print("[green]✓[/green] Event count matches")
+        console.print()
+        console.print("[green]Validation passed.[/green]")
+        raise typer.Exit(0)
+
+    for issue in result.issues:
+        console.print(f"[red]✗[/red] {issue.code}")
+        console.print(f"  {issue.message}")
+        if issue.location:
+            console.print(f"  [dim]{issue.location}[/dim]")
+        console.print()
+
+    console.print(f"[red]Validation failed: {len(result.issues)} issues.[/red]")
+    if verify_integrity and _has_legacy_integrity_issue(result):
+        raise typer.Exit(3)
+    has_unreadable_issue = any(
+        issue.code in UNREADABLE_CODES for issue in result.issues
+    )
+    exit_code = 2 if has_unreadable_issue else 1
+    raise typer.Exit(exit_code)
+
+
+def _print_header(path: Path, *, strict: bool) -> None:
+    console.print("[bold]Stepfork Trace Validation[/bold]")
+    console.print()
+
+    table = Table.grid(padding=(0, 4))
+    table.add_column(style="bold")
+    table.add_column()
+    table.add_row("Trace", str(path))
+    if not path.exists():
+        table.add_row("Mode", "strict" if strict else "partial")
+    console.print(table)
+    console.print()
+
+
+def _print_metadata(path: Path, *, strict: bool) -> None:
+    try:
+        trace = load_trace(path)
+    except TraceStorageError:
+        return
+
+    table = Table.grid(padding=(0, 4))
+    table.add_column(style="bold")
+    table.add_column()
+    table.add_row("Schema", "0.1")
+    table.add_row("Events", str(len(trace.events)))
+    table.add_row("Mode", "strict" if strict else "partial")
+    console.print(table)
+    console.print()
+
+
+def _print_integrity(path: Path) -> None:
+    result = verify_bundle_integrity(path)
+    status_label = (
+        "UNVERIFIED (legacy bundle)"
+        if result.status is IntegrityStatus.UNVERIFIED_LEGACY
+        else result.status.value.upper()
+    )
+    console.print("Structure: [green]PASS[/green]")
+    style = "green" if result.status is IntegrityStatus.VERIFIED else "yellow"
+    if result.status is IntegrityStatus.MISMATCH:
+        style = "red"
+    console.print(f"Integrity: [{style}]{status_label}[/{style}]")
+    console.print()
+
+    table = Table.grid(padding=(0, 4))
+    table.add_column()
+    table.add_column()
+    for filename in ("manifest.json", "events.jsonl", "redactions.json"):
+        if filename in result.verified_files:
+            table.add_row(filename, "verified")
+            continue
+        issue = next((item for item in result.issues if item.file == filename), None)
+        table.add_row(filename, issue.message if issue else "unverified")
+    if result.status is IntegrityStatus.UNVERIFIED_LEGACY:
+        table.add_row("integrity.json", "missing legacy metadata")
+    console.print(table)
+    console.print()
+
+
+def _has_legacy_integrity_issue(result: ValidationResult) -> bool:
+    return any(
+        issue.code == "integrity_unverified" and issue.location == "integrity.json"
+        for issue in result.issues
+    )

stepfork/diff/__init__.py

@@ -0,0 +1,25 @@
+"""Behavioral trace comparison."""
+
+from stepfork.diff.compare import collect_field_changes, first_difference, values_equal
+from stepfork.diff.engine import BehaviorStep, diff_traces, extract_behavior
+from stepfork.diff.models import (
+    ChangeKind,
+    DiffResult,
+    FieldChange,
+    StepDiff,
+    TraceSummary,
+)
+
+__all__ = [
+    "BehaviorStep",
+    "ChangeKind",
+    "DiffResult",
+    "FieldChange",
+    "StepDiff",
+    "TraceSummary",
+    "collect_field_changes",
+    "diff_traces",
+    "extract_behavior",
+    "first_difference",
+    "values_equal",
+]

stepfork/diff/compare.py

@@ -0,0 +1,144 @@
+"""Deep comparison helpers for JSON trace payloads.
+
+Comparisons use Stepfork's canonical JSON profile so ``1`` and ``1.0`` are
+never treated as equal and dictionary key order never matters.
+"""
+
+from __future__ import annotations
+
+from stepfork.diff.models import FieldChange
+from stepfork.trace.canonical import canonical_json_bytes
+from stepfork.trace.models import JsonValue
+
+
+def values_equal(expected: JsonValue, actual: JsonValue) -> bool:
+    """Return True when both values are canonically identical."""
+    try:
+        return canonical_json_bytes(expected) == canonical_json_bytes(actual)
+    except TypeError:
+        return False
+
+
+def first_difference(
+    expected: JsonValue,
+    actual: JsonValue,
+    *,
+    path: str = "",
+) -> tuple[str, JsonValue, JsonValue] | None:
+    """Return the first differing leaf as ``(path, expected, actual)``."""
+    if values_equal(expected, actual):
+        return None
+
+    if isinstance(expected, dict) and isinstance(actual, dict):
+        for key in sorted(set(expected) | set(actual)):
+            child_path = f"{path}.{key}" if path else key
+            if key not in expected:
+                return child_path, None, actual[key]
+            if key not in actual:
+                return child_path, expected[key], None
+            nested = first_difference(
+                expected[key],
+                actual[key],
+                path=child_path,
+            )
+            if nested is not None:
+                return nested
+        return path, expected, actual
+
+    if isinstance(expected, list) and isinstance(actual, list):
+        shared = min(len(expected), len(actual))
+        for index in range(shared):
+            nested = first_difference(
+                expected[index],
+                actual[index],
+                path=f"{path}[{index}]",
+            )
+            if nested is not None:
+                return nested
+        if len(expected) > len(actual):
+            return f"{path}[{shared}]", expected[shared], None
+        if len(actual) > len(expected):
+            return f"{path}[{shared}]", None, actual[shared]
+        return path, expected, actual
+
+    return path or "$", expected, actual
+
+
+def collect_field_changes(
+    expected: JsonValue,
+    actual: JsonValue,
+    *,
+    path: str,
+    output: list[FieldChange],
+) -> None:
+    """Append every differing leaf between two payloads to ``output``."""
+    if values_equal(expected, actual):
+        return
+
+    if isinstance(expected, dict) and isinstance(actual, dict):
+        for key in sorted(set(expected) | set(actual)):
+            child_path = f"{path}.{key}" if path else key
+            if key not in expected:
+                output.append(
+                    FieldChange(
+                        path=child_path,
+                        kind="added",
+                        expected=None,
+                        actual=actual[key],
+                    )
+                )
+            elif key not in actual:
+                output.append(
+                    FieldChange(
+                        path=child_path,
+                        kind="removed",
+                        expected=expected[key],
+                        actual=None,
+                    )
+                )
+            else:
+                collect_field_changes(
+                    expected[key],
+                    actual[key],
+                    path=child_path,
+                    output=output,
+                )
+        return
+
+    if isinstance(expected, list) and isinstance(actual, list):
+        shared = min(len(expected), len(actual))
+        for index in range(shared):
+            collect_field_changes(
+                expected[index],
+                actual[index],
+                path=f"{path}[{index}]",
+                output=output,
+            )
+        for index in range(shared, len(expected)):
+            output.append(
+                FieldChange(
+                    path=f"{path}[{index}]",
+                    kind="removed",
+                    expected=expected[index],
+                    actual=None,
+                )
+            )
+        for index in range(shared, len(actual)):
+            output.append(
+                FieldChange(
+                    path=f"{path}[{index}]",
+                    kind="added",
+                    expected=None,
+                    actual=actual[index],
+                )
+            )
+        return
+
+    output.append(
+        FieldChange(
+            path=path,
+            kind="changed",
+            expected=expected,
+            actual=actual,
+        )
+    )