feat(api): carry the capability ledger + footprint on a failed run's error

[ivarvong]

Why

The library gap we hit while building the sandbox example: to audit a failed run — what did the program touch before it crashed, and how much did it spend — you had to attach a :telemetry handler and correlate it back to the run. That's plumbing the library should make unnecessary. Auditing, policy-gating, and billing a failed run should be a value on the return, not a side channel.

What

{:error, %Pyex.Error{}} now carries:

• runtime_spans — the capability ledger of every storage/IO op the program performed before it broke (the same unforgeable, host-rendered spans you get on success).
• footprint — the resource usage at the point of failure (steps, compute, duration_ms, memory_bytes, output_bytes).

Both are []/nil for errors raised before execution (e.g. syntax) — correct, since nothing ran. On success the same is read off ctx via Pyex.Turn/Pyex.Ctx.runtime_spans, so the ledger is now first-class on every outcome.

The error path already computed both for the [:pyex, :run, :exception] telemetry event — this just stops discarding them. Consistent with the boundary we've held all along: the library exposes the value; the caller composes audit / policy / billing.

Payoff, demonstrated

examples/sandbox_server.exs drops its per-worker telemetry-capture handler entirely and reads the ledger straight off the error. Verified over curl — an erroring program still returns its db.set/db.get ledger + usage:

verdict: error  usage.steps: 3
── runtime · scope=pyex · 2 spans ──
━━━━━━━━     db.set   bytes=1 db.collection.name="k" db.operation.name="set" …
        ━━━━ db.get   hit=true …

Compatibility

Pre-release; additive struct fields. Existing {:error, %Pyex.Error{}} matchers are unaffected.

Gate

mix format ✅ · mix compile --warnings-as-errors ✅ · mix test (6185) ✅ · mix dialyzer ✅

🤖 Generated with Claude Code

https://claude.ai/code/session_019NokzcR7BiAigPgC78zpk9