Skip to content

trace-format.md

Latest commit

 

History

History
97 lines (75 loc) · 2.68 KB

trace-format.md

File metadata and controls

97 lines (75 loc) · 2.68 KB
Raw

Stepfork Trace Format

Stepfork stores traces as UTF-8 directory bundles with the .sftrace suffix. The v0.1 layout is:

example.sftrace/
├── manifest.json
├── events.jsonl
├── redactions.json
└── integrity.json

integrity.json was added after the initial v0.1 storage work. Older bundles without it remain loadable but are reported as unverified_legacy.

Manifest

manifest.json contains bundle-level metadata:

  • format: always stepfork
  • schema_version: currently 0.1
  • run_id
  • agent_name
  • created_at
  • status: running, completed, or failed
  • failure: required for failed runs
  • environment
  • totals

Events

events.jsonl stores one complete JSON event per non-blank line. Blank lines are invalid. Event order is significant and preserved by Trace.load().

Supported event types:

  • run_start
  • llm_request
  • llm_response
  • tool_call
  • tool_result
  • state_change
  • error
  • run_end

Events share structural fields such as id, run_id, parent_id, step, timestamp, status, and replay_policy. Payload hashes are stored in input_hash and output_hash where applicable.

input_hash and output_hash are SHA-256 digests over Stepfork's canonical JSON profile after redaction has been applied. During replay, dependency inputs are re-normalized, redacted, canonicalized, and compared against the recording. For LLM requests this means prompt payload changes, model changes, and provider changes are treated as replay divergence.

Redactions

redactions.json stores non-secret metadata describing redactions:

{
  "schema_version": "0.1",
  "entries": [
    {
      "event_id": "evt_002",
      "path": "/input/api_key",
      "reason": "sensitive_key",
      "replacement": "[REDACTED]"
    }
  ]
}

Paths use JSON Pointer escaping for ~ and /. Redaction metadata must never store original secrets, reversible encodings, or hashes of secret values.

Integrity

integrity.json stores SHA-256 digests of the exact persisted bytes of:

  • manifest.json
  • events.jsonl
  • redactions.json

It does not include itself. This detects accidental modification and ordinary tampering when the expected integrity record is trusted. It is not a digital signature.

Compatibility

The schema version is currently 0.1. New readers should keep loading older valid v0.1 bundles where possible. Missing integrity metadata means unverified legacy, not verified. Older or hand-built events may also lack payload hashes; they can still replay if their stored inputs exactly match the live calls, but Stepfork reports computed fingerprints in diagnostics rather than silently treating them as integrity-verified.