feat(storage): copy-on-write Overlay backend for sound, preview-gated effects

[ivarvong]

What

Pyex.Storage.Overlay — a staging backend that read-throughs to an inner backend while accumulating writes/deletes in an overlay that isn't committed until the caller chooses. It's the storage half of a dry-run.

overlay = Pyex.Storage.Overlay.new(real_backend)
{:ok, _v, ctx} = Pyex.run(agent_code, storage: overlay, seed: 1)

Pyex.Storage.Overlay.pending(ctx.storage)   # the writes/deletes it WOULD do
Pyex.Turn.render(ctx)                        # the ledger of every store op

# gate on the above, then:
{:ok, committed} = Pyex.Storage.Overlay.commit(ctx.storage)   # apply for real
# ...or drop ctx.storage to discard the run entirely.

Run untrusted (agent-generated) code against an overlay and you get back two things the program cannot forge: the capability ledger of what it intended to do, and the staged effects it would apply. A human or policy engine gates them, then commit/1 applies them.

Why it matters — soundness, not best-effort

Preview-then-commit ("show me what it'll do, I approve, then run it") is normally unsound: in a nondeterministic runtime the program can branch on the clock/RNG, so what you approved in the preview isn't guaranteed to be what runs at commit — a TOCTOU hole at the heart of every "agent asks permission" system.

The overlay gives read-your-writes exactly as a real backend does, so the program executes identically whether its writes are staged or applied. Combined with deterministic execution (seed:), the run you previewed is byte-for-byte the run that commits. No gap between what you approved and what happens.

This is what only a processless, deterministic, capability-ledgered interpreter can offer — it turns pyex from "a safer sandbox" into a verifiable effect system for agent compute.

The proof

test/pyex/storage/overlay_test.exs asserts, for a program that reads, writes (including a read-your-writes update over a staged value), deletes, and lists a prefix:

• runtime_spans(dry-run) == runtime_spans(committed-run) — the previewed ledger is the committed ledger.
• the dry-run touches the real backend only on commit/1, and committing produces the identical final state as having run for real.
• reads pass through; writes/deletes/listing reflect the overlay; the inner backend is untouched until commit.

Scope

A library primitive — callers compose plan → gate → commit; pyex owns the value, not the workflow.

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

🤖 Generated with Claude Code

https://claude.ai/code/session_019NokzcR7BiAigPgC78zpk9