feat: add foundational fork-at-step trace support

[utsab345]

Summary

Implements fork-at-step debugging with typed override system for Stepfork v0.2. Fork traces at specific execution points, optionally modify recorded outputs, and preserve complete provenance metadata.

What's Included

Core Fork Engine

• Fork traces by step number (--at-step N) or event ID (--at-event ID)
• Preserves structural integrity and validates parent-child relationships
• Creates new trace with new run_id but preserved event IDs
• Tracks complete provenance (parent trace, fork point, timestamp)
• Validates fork points prevent broken dependencies

Override System (Python API Only)

• Typed overrides via OverrideSpec(step=N, output={...}) or OverrideSpec(event_id=..., output={...})
• Targets tool_result and llm_response events only
• Validation ensures overrides target valid, overridable events
• Applied during fork creation, reflected in forked trace
• Event ID overrides take priority over step overrides

CLI Command

# Basic fork at step
stepfork fork failure.sftrace --at-step 2 --output forked.sftrace

# Fork at specific event ID
stepfork fork trace.sftrace --at-event evt_abc123 -o forked.sftrace

Note: Overrides are only available through Python API, not CLI.

Python API

from stepfork.fork import fork_trace, ForkPoint, OverrideSpec

# Fork with override
result = fork_trace(
    "failure.sftrace",
    ForkPoint(event_id=None, step=2),
    overrides=[
        OverrideSpec(step=2, output={"count": 100})
    ],
    output_path="forked.sftrace"
)

Implementation Details

• src/stepfork/fork/models.py: ForkInfo, ForkPoint, ForkResult, OverrideSpec
• src/stepfork/fork/engine.py: ForkEngine with validation and override application
• src/stepfork/fork/overrides.py: OverrideRegistry for managing overrides
• src/stepfork/cli/fork.py: CLI interface (no override support)
• tests/: 43 tests (13 engine + 15 override + 5 integration + 10 edge cases)

What's NOT Included

• CLI override support: Overrides only available via Python API
• Replay integration: Does not continue execution from fork point; creates modified trace only
• Divergence detection: No comparison between forked and original execution
• Interactive fork selection: No interactive UI for selecting fork points

How It Works

1. Select fork point: By step number or event ID
2. Extract history: All events up to and including fork point
3. Validate structure: Ensures no broken parent dependencies
4. Apply overrides: Modify tool_result or llm_response outputs if specified
5. Create new trace: New run_id, preserved event IDs, complete provenance
6. Save: Structurally valid .sftrace bundle

Limitations

• No mid-execution replay: Fork creates modified traces; does not resume execution
• Override scope: Only tool_result and llm_response events (not tool_call, llm_request)
• No CLI overrides: Must use Python API for override functionality
• No replay hooks: Overrides applied at fork time, not during replay

Testing

✅ 523 tests pass (43 fork-specific)
✅ mypy strict passes
✅ ruff format & check pass
✅ Forked traces pass validation
✅ CLI smoke tested
✅ Edge cases covered (by event_id, step 0, validation, priority)

Verified Correctness

• Run IDs: Forked trace gets new run_id, all events updated
• Event IDs: Original event IDs preserved in forked trace
• Provenance: ForkInfo tracks parent trace, fork point, overrides
• Dependencies: Validation prevents broken parent references
• Overrides: Applied correctly, validated, counted accurately
• Trace integrity: Forked traces pass strict validation

🤖 Generated with Claude Code