stepfork 0.1.0a2__py3-none-any.whl

stepfork/trace/__init__.py

@@ -0,0 +1,115 @@
+"""Portable Stepfork trace format and serialization."""
+
+from stepfork.trace.canonical import CANONICAL_JSON_PROFILE, canonical_json_bytes
+from stepfork.trace.hashing import hash_event_payloads, hash_json
+from stepfork.trace.integrity import (
+    IntegrityIssue,
+    IntegrityRecord,
+    IntegrityResult,
+    IntegrityStatus,
+    verify_bundle_integrity,
+)
+from stepfork.trace.jsonable import (
+    Serializer,
+    TraceSerializationError,
+    to_json_value,
+)
+from stepfork.trace.manifest import (
+    EnvironmentInfo,
+    FailureInfo,
+    RunStatus,
+    TraceManifest,
+    TraceTotals,
+)
+from stepfork.trace.models import (
+    ErrorEvent,
+    Event,
+    EventBase,
+    EventStatus,
+    EventType,
+    JsonValue,
+    LLMRequest,
+    LLMResponse,
+    RunEnd,
+    RunStart,
+    StateChange,
+    ToolCall,
+    ToolResult,
+    Trace,
+)
+from stepfork.trace.redaction import (
+    REDACTION_REPLACEMENT,
+    RedactionEntry,
+    RedactionManifest,
+    RedactionResult,
+    redact_json,
+)
+from stepfork.trace.replay_policy import ReplayPolicy
+from stepfork.trace.schema import (
+    event_json_schema,
+    manifest_json_schema,
+    trace_json_schema,
+)
+from stepfork.trace.storage import (
+    TraceStorageError,
+    build_manifest,
+    load_trace,
+    save_trace,
+)
+from stepfork.trace.validation import (
+    ValidationIssue,
+    ValidationResult,
+    validate_bundle,
+    validate_trace,
+)
+
+__all__ = [
+    "CANONICAL_JSON_PROFILE",
+    "REDACTION_REPLACEMENT",
+    "EnvironmentInfo",
+    "ErrorEvent",
+    "Event",
+    "EventBase",
+    "EventStatus",
+    "EventType",
+    "FailureInfo",
+    "IntegrityIssue",
+    "IntegrityRecord",
+    "IntegrityResult",
+    "IntegrityStatus",
+    "JsonValue",
+    "LLMRequest",
+    "LLMResponse",
+    "RedactionEntry",
+    "RedactionManifest",
+    "RedactionResult",
+    "ReplayPolicy",
+    "RunEnd",
+    "RunStart",
+    "RunStatus",
+    "Serializer",
+    "StateChange",
+    "ToolCall",
+    "ToolResult",
+    "Trace",
+    "TraceManifest",
+    "TraceSerializationError",
+    "TraceStorageError",
+    "TraceTotals",
+    "ValidationIssue",
+    "ValidationResult",
+    "build_manifest",
+    "canonical_json_bytes",
+    "event_json_schema",
+    "hash_event_payloads",
+    "hash_json",
+    "load_trace",
+    "manifest_json_schema",
+    "redact_json",
+    "save_trace",
+    "to_json_value",
+    "trace_json_schema",
+    "validate_bundle",
+    "validate_trace",
+    "verify_bundle_integrity",
+]

stepfork/trace/canonical.py

@@ -0,0 +1,55 @@
+"""Deterministic JSON serialization for Stepfork hashes.
+
+Stepfork v0.1 uses a documented Python JSON profile for canonicalization:
+sorted object keys, compact separators, UTF-8 bytes, non-ASCII characters
+preserved, and non-finite floats rejected. This is not full RFC 8785.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from typing import Any
+
+from stepfork.trace.models import JsonValue
+
+CANONICAL_JSON_PROFILE = "stepfork-json-v0.1"
+
+
+class CanonicalJsonError(TypeError):
+    """Raised when a value cannot be canonically serialized as JSON."""
+
+
+def canonical_json_bytes(value: JsonValue) -> bytes:
+    """Return deterministic UTF-8 JSON bytes for a JSON-compatible value."""
+    _validate_json_value(value)
+    try:
+        return json.dumps(
+            value,
+            ensure_ascii=False,
+            sort_keys=True,
+            separators=(",", ":"),
+            allow_nan=False,
+        ).encode("utf-8")
+    except (TypeError, ValueError) as exc:
+        raise CanonicalJsonError("value is not canonical JSON serializable") from exc
+
+
+def _validate_json_value(value: Any) -> None:
+    if value is None or isinstance(value, str | bool | int):
+        return
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise CanonicalJsonError("non-finite floats are not supported")
+        return
+    if isinstance(value, list):
+        for item in value:
+            _validate_json_value(item)
+        return
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if not isinstance(key, str):
+                raise CanonicalJsonError("JSON object keys must be strings")
+            _validate_json_value(item)
+        return
+    raise CanonicalJsonError(f"unsupported JSON value type: {type(value).__name__}")

stepfork/trace/hashing.py

@@ -0,0 +1,75 @@
+"""SHA-256 helpers for sanitized JSON payloads."""
+
+from __future__ import annotations
+
+import hashlib
+
+from stepfork.trace.canonical import canonical_json_bytes
+from stepfork.trace.models import (
+    ErrorEvent,
+    Event,
+    JsonValue,
+    LLMRequest,
+    LLMResponse,
+    RunEnd,
+    RunStart,
+    StateChange,
+    ToolCall,
+    ToolResult,
+)
+
+
+def hash_json(value: JsonValue) -> str:
+    """Return the SHA-256 hex digest for a canonical JSON value."""
+    return hashlib.sha256(canonical_json_bytes(value)).hexdigest()
+
+
+def hash_event_payloads(event: Event) -> Event:
+    """Return an event copy with payload hashes populated where applicable."""
+    updates: dict[str, str | None] = {"input_hash": None, "output_hash": None}
+
+    if isinstance(event, RunStart):
+        if "input" in event.model_fields_set:
+            updates["input_hash"] = hash_json(event.input)
+    elif isinstance(event, LLMRequest | ToolCall):
+        updates["input_hash"] = hash_json(event.input)
+    elif isinstance(event, LLMResponse | ToolResult):
+        updates["output_hash"] = hash_json(event.output)
+    elif isinstance(event, StateChange):
+        if "before" in event.model_fields_set:
+            updates["input_hash"] = hash_json(event.before)
+        if "after" in event.model_fields_set:
+            updates["output_hash"] = hash_json(event.after)
+    elif isinstance(event, ErrorEvent):
+        if event.details is not None or "details" in event.model_fields_set:
+            updates["output_hash"] = hash_json(event.details)
+    elif isinstance(event, RunEnd) and (
+        event.output is not None or "output" in event.model_fields_set
+    ):
+        updates["output_hash"] = hash_json(event.output)
+
+    return event.model_copy(update=updates)
+
+
+def verify_event_payload_hashes(event: Event) -> list[str]:
+    """Return payload hash mismatch issue fields for an event."""
+    expected = hash_event_payloads(event)
+    mismatches: list[str] = []
+
+    if event.input_hash is not None and event.input_hash != expected.input_hash:
+        mismatches.append("input_hash")
+    if event.output_hash is not None and event.output_hash != expected.output_hash:
+        mismatches.append("output_hash")
+
+    return mismatches
+
+
+def event_payload_hash_fields(event: Event) -> set[str]:
+    """Return hash fields that are expected for the event's payload shape."""
+    expected = hash_event_payloads(event)
+    fields: set[str] = set()
+    if expected.input_hash is not None:
+        fields.add("input_hash")
+    if expected.output_hash is not None:
+        fields.add("output_hash")
+    return fields

stepfork/trace/integrity.py

@@ -0,0 +1,196 @@
+"""Tamper-evident integrity records for `.sftrace` bundles."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import re
+from enum import StrEnum
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from stepfork.trace.storage import EVENTS_FILE, MANIFEST_FILE, REDACTIONS_FILE
+
+INTEGRITY_FILE = "integrity.json"
+INTEGRITY_ALGORITHM = "sha256"
+INTEGRITY_FILES = (MANIFEST_FILE, EVENTS_FILE, REDACTIONS_FILE)
+_SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
+
+
+class IntegrityStatus(StrEnum):
+    """Result status for bundle integrity verification."""
+
+    VERIFIED = "verified"
+    MISMATCH = "mismatch"
+    UNVERIFIED_LEGACY = "unverified_legacy"
+
+
+class IntegrityIssue(BaseModel):
+    """Machine-readable integrity issue."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    code: str
+    message: str
+    file: str | None = None
+
+
+class IntegrityRecord(BaseModel):
+    """Persisted integrity metadata for a `.sftrace` bundle."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    schema_version: Literal["0.1"] = "0.1"
+    algorithm: str = INTEGRITY_ALGORITHM
+    files: dict[str, str] = Field(default_factory=dict)
+
+
+class IntegrityResult(BaseModel):
+    """Structured bundle integrity verification result."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    status: IntegrityStatus
+    issues: list[IntegrityIssue] = Field(default_factory=list)
+    verified_files: list[str] = Field(default_factory=list)
+
+
+def write_bundle_integrity(path: Path) -> IntegrityRecord:
+    """Write integrity metadata for the finalized bundle payload files."""
+    record = IntegrityRecord(
+        files={filename: _hash_file(path / filename) for filename in INTEGRITY_FILES}
+    )
+    (path / INTEGRITY_FILE).write_text(
+        record.model_dump_json(indent=2) + "\n",
+        encoding="utf-8",
+    )
+    return record
+
+
+def verify_bundle_integrity(path: str | Path) -> IntegrityResult:
+    """Verify a bundle's integrity record."""
+    bundle_path = Path(path)
+    integrity_path = bundle_path / INTEGRITY_FILE
+    if not integrity_path.exists():
+        return IntegrityResult(
+            status=IntegrityStatus.UNVERIFIED_LEGACY,
+            issues=[
+                IntegrityIssue(
+                    code="integrity_unverified",
+                    message="Bundle has no integrity.json metadata.",
+                    file=INTEGRITY_FILE,
+                )
+            ],
+        )
+    if not integrity_path.is_file():
+        return IntegrityResult(
+            status=IntegrityStatus.MISMATCH,
+            issues=[
+                IntegrityIssue(
+                    code="integrity_metadata_invalid",
+                    message="integrity.json is not a file.",
+                    file=INTEGRITY_FILE,
+                )
+            ],
+        )
+
+    try:
+        payload = json.loads(integrity_path.read_text(encoding="utf-8"))
+        record = IntegrityRecord.model_validate(payload)
+    except json.JSONDecodeError:
+        return _metadata_invalid("integrity.json is not valid JSON.")
+    except ValidationError:
+        return _metadata_invalid("integrity.json metadata is invalid.")
+
+    issues = _validate_record(record)
+    verified_files: list[str] = []
+    if issues:
+        return IntegrityResult(status=IntegrityStatus.MISMATCH, issues=issues)
+
+    for filename in INTEGRITY_FILES:
+        file_path = bundle_path / filename
+        if not file_path.is_file():
+            issues.append(
+                IntegrityIssue(
+                    code="missing_file",
+                    message=f"{filename} is missing.",
+                    file=filename,
+                )
+            )
+            continue
+
+        actual = _hash_file(file_path)
+        expected = record.files[filename]
+        if hmac.compare_digest(actual, expected):
+            verified_files.append(filename)
+        else:
+            issues.append(
+                IntegrityIssue(
+                    code="integrity_mismatch",
+                    message="SHA-256 mismatch.",
+                    file=filename,
+                )
+            )
+
+    return IntegrityResult(
+        status=IntegrityStatus.VERIFIED if not issues else IntegrityStatus.MISMATCH,
+        issues=issues,
+        verified_files=verified_files,
+    )
+
+
+def _validate_record(record: IntegrityRecord) -> list[IntegrityIssue]:
+    issues: list[IntegrityIssue] = []
+    if record.algorithm != INTEGRITY_ALGORITHM:
+        issues.append(
+            IntegrityIssue(
+                code="integrity_algorithm_unsupported",
+                message=f"Unsupported integrity algorithm {record.algorithm!r}.",
+                file=INTEGRITY_FILE,
+            )
+        )
+        return issues
+
+    for filename in INTEGRITY_FILES:
+        digest = record.files.get(filename)
+        if digest is None:
+            issues.append(
+                IntegrityIssue(
+                    code="integrity_metadata_invalid",
+                    message=f"Missing digest for {filename}.",
+                    file=filename,
+                )
+            )
+        elif _SHA256_RE.fullmatch(digest) is None:
+            issues.append(
+                IntegrityIssue(
+                    code="integrity_metadata_invalid",
+                    message=f"Invalid SHA-256 digest for {filename}.",
+                    file=filename,
+                )
+            )
+    return issues
+
+
+def _metadata_invalid(message: str) -> IntegrityResult:
+    return IntegrityResult(
+        status=IntegrityStatus.MISMATCH,
+        issues=[
+            IntegrityIssue(
+                code="integrity_metadata_invalid",
+                message=message,
+                file=INTEGRITY_FILE,
+            )
+        ],
+    )
+
+
+def _hash_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as file:
+        for chunk in iter(lambda: file.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()

stepfork/trace/jsonable.py

@@ -0,0 +1,97 @@
+"""Conversion of runtime values into JSON-compatible trace payloads.
+
+Stepfork never falls back to ``repr()`` when recording payloads. Values must
+already be JSON-compatible (``None``, ``str``, ``bool``, ``int``, finite
+``float``, ``list``/``tuple``, ``dict`` with ``str`` keys) or the caller must
+provide an explicit serializer hook.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable
+from typing import Any, TypeAlias
+
+from stepfork.trace.models import JsonValue
+
+Serializer: TypeAlias = Callable[[Any], Any]
+
+MAX_DEPTH = 100
+
+
+class TraceSerializationError(TypeError):
+    """Raised when a runtime value cannot be represented as JSON."""
+
+
+def to_json_value(
+    value: Any,
+    *,
+    serializer: Serializer | None = None,
+    path: str = "$",
+    depth: int = 0,
+) -> JsonValue:
+    """Convert ``value`` into a JSON-compatible value or raise a clear error.
+
+    Non-JSON values are first passed through the optional ``serializer`` hook.
+    The hook must return a JSON-compatible value; returning the input object
+    unchanged (or another unsupported value) is an error.
+    """
+    if depth > MAX_DEPTH:
+        raise TraceSerializationError(
+            f"value at {path} exceeds the maximum nesting depth of {MAX_DEPTH}; "
+            "this usually means a cyclic structure"
+        )
+
+    if value is None or isinstance(value, str | bool | int):
+        return value
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise TraceSerializationError(
+                f"non-finite float at {path} cannot be recorded as JSON"
+            )
+        return value
+    if isinstance(value, list | tuple):
+        return [
+            to_json_value(
+                item,
+                serializer=serializer,
+                path=f"{path}[{index}]",
+                depth=depth + 1,
+            )
+            for index, item in enumerate(value)
+        ]
+    if isinstance(value, dict):
+        converted: dict[str, JsonValue] = {}
+        for key, item in value.items():
+            if not isinstance(key, str):
+                raise TraceSerializationError(
+                    f"object key at {path} must be a string, got "
+                    f"{type(key).__name__}: {key!r}"
+                )
+            converted[key] = to_json_value(
+                item,
+                serializer=serializer,
+                path=f"{path}.{key}",
+                depth=depth + 1,
+            )
+        return converted
+
+    if serializer is not None:
+        converted_value = serializer(value)
+        if converted_value is value:
+            raise TraceSerializationError(
+                f"serializer returned the original {type(value).__name__} "
+                f"unchanged at {path}"
+            )
+        return to_json_value(
+            converted_value,
+            serializer=serializer,
+            path=path,
+            depth=depth + 1,
+        )
+
+    raise TraceSerializationError(
+        f"cannot serialize {type(value).__name__} at {path}; pass "
+        "JSON-compatible values or provide a serializer hook via "
+        "record(..., serializer=...) or trace_tool(..., serializer=...)"
+    )

stepfork/trace/manifest.py

@@ -0,0 +1,85 @@
+"""Manifest models for the Stepfork `.sftrace` v0.1 contract."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Literal, Self
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+
+class RunStatus(StrEnum):
+    """Lifecycle status for an agent run."""
+
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class FailureInfo(BaseModel):
+    """Failure summary stored in a trace manifest."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: str = Field(min_length=1)
+    message: str = Field(min_length=1)
+    step: int = Field(ge=0)
+
+
+class EnvironmentInfo(BaseModel):
+    """Optional environment metadata captured by future recorders."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    python: str | None = None
+    os: str | None = None
+    stepfork_version: str | None = None
+
+
+class TraceTotals(BaseModel):
+    """Aggregate counters for a trace."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    events: int = Field(default=0, ge=0)
+    llm_calls: int = Field(default=0, ge=0)
+    tool_calls: int = Field(default=0, ge=0)
+    cost_usd: float | None = Field(default=None, ge=0)
+    duration_ms: int | None = Field(default=None, ge=0)
+
+
+class TraceManifest(BaseModel):
+    """Top-level manifest for a portable `.sftrace` directory."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    format: Literal["stepfork"] = "stepfork"
+    schema_version: Literal["0.1"] = "0.1"
+
+    run_id: str = Field(min_length=1)
+    agent_name: str = Field(min_length=1)
+    created_at: datetime
+
+    status: RunStatus
+
+    failure: FailureInfo | None = None
+    environment: EnvironmentInfo = Field(default_factory=EnvironmentInfo)
+    totals: TraceTotals = Field(default_factory=TraceTotals)
+
+    @field_validator("created_at")
+    @classmethod
+    def created_at_must_be_timezone_aware(cls, value: datetime) -> datetime:
+        """Reject naive datetimes instead of assuming UTC."""
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise ValueError("created_at must be timezone-aware")
+        return value
+
+    @model_validator(mode="after")
+    def failure_must_match_status(self) -> Self:
+        """Keep manifest failure details aligned with run status."""
+        if self.status is RunStatus.FAILED and self.failure is None:
+            raise ValueError("failure is required when status is failed")
+        if self.status is not RunStatus.FAILED and self.failure is not None:
+            raise ValueError("failure must be omitted unless status is failed")
+        return self