chore: resync with upstream zblanco/runic PR #9 (snapshot checkpoint policy)

[ty13r]

Summary

Resyncs The-Metagraph/runic with upstream zblanco/runic PR zblanco#9 ("Resume workflows from cursor-aware snapshots" / Snapshot Checkpoint Policy).

Our fork main (0507e11) was a strict ancestor of upstream main (75ed26f) — fork main is byte-identical to upstream's PR zblanco#8 state, with zero fork-local commits on main. The resync is therefore a clean fast-forward integration with no conflicts; the merge brought in exactly PR zblanco#9's +841/-24.

Commits integrated (PR zblanco#9)

• 978d0d7 feat: resume workflows from cursor-aware snapshots
• e0561f6 use stream/3 with opts instead of stream_after/2 for extensibility
• 75ed26f Merge pull request Resume workflows from cursor-aware snapshots zblanco/runic#9 (upstream merge commit)

Files

• lib/runic/runner.ex (+122/-23) — resume/3 now consumes snapshots: supports_snapshots?/1 + supports_stream_options?/1 gate a snapshot+tail path (load_snapshot/2 → stream/3 after_cursor:), with full-stream fallback. Adds encode_snapshot/1 + decode_snapshot/1 (tagged :runic_workflow_snapshot v1).
• lib/runic/runner/store.ex (+43/-1) — optional save_snapshot/4 + load_snapshot/2 callbacks, stream/3 callback, and supports_snapshots?/1 / supports_stream_options?/1 capability predicates.
• test/runner/worker_test.exs (+110), test/support/snapshot_tail_store.ex (+129), test/support/snapshot_store_without_tail.ex (+115) — exercise both resume branches.
• .docs/snapshot-checkpoint-policy-implementation-plan.md (+322) — design doc.

Reconciliation note

No runner.ex reconcile was required — our fork had no Phase-40 customizations on main (verified: git grep for phase/metagraph/ariston markers returns nothing; runner.ex on fork main == upstream pre-zblanco#9 byte-for-byte). The Metagraph-specific Postgres Runner.Store lives in ariston-ui, not in this fork. The pre-zblanco#9 fork-side branch claude/s3-4-inline-durable-emit (404bfdd) is already superseded by what landed on main as PR zblanco#8.

Verification (fork only)

• mix deps.get OK
• mix compile OK (exit 0)
• mix test: 1333 tests + 55 doctests, 0 failures, 13 skipped
• test/runner/worker_test.exs (incl. PR Resume workflows from cursor-aware snapshots zblanco/runic#9 resume-from-snapshot cases): 40 tests, 0 failures

Toolchain: Elixir 1.19.5 / OTP 28 (matches fork's PR zblanco#7 "update for 1.19.5").

⚠️ Scope clarification — what PR zblanco#9 actually ships

PR zblanco#9 implements only the read / resume side of the snapshot policy plus the Store behaviour callbacks and encode/decode_snapshot. The auto-writing Worker :snapshot_strategy option (:never / :on_complete / :every_checkpoint / {:every_n_checkpoints,n} / {:after_events,n}) is documented as a "Draft follow-up" in the .docs plan and is NOT implemented — worker.ex is untouched by this PR and contains no snapshot_strategy / maybe_snapshot / save_snapshot call. So no Worker auto-snapshot behavior changes; default behavior is unchanged regardless.

Downstream (ariston-ui) follow-up — snapshot path is partially inert

ariston-ui's AristonUi.Projects.Workflows.RunnerStore.Postgres already implements save_snapshot/4 + load_snapshot/2 → supports_snapshots?/1 is true. However it implements only stream/2 (no stream/3), so supports_stream_options?/1 is false. Under PR zblanco#9, resume/3 therefore takes the safe full-stream fallback (resume_from_full_stream → stream/2), not the snapshot-accelerated tail path. This is correct and lossless (the store's stream_from_latest_snapshot? defaults to false, returning the full log from seq 0).

Notably, PR zblanco#9 is the upstream change the Postgres store's own comment (lines 21-32, "Opus #585") anticipated — "Default flips back to true once upstream Runic wires load_snapshot into resume." To actually realize snapshot acceleration in ariston, a follow-up should add stream/3 after_cursor: to the Postgres store and re-evaluate the stream_from_latest_snapshot? default. Tracked separately; out of scope for this resync.

Not merged / deferred

• The shared local fork checkout at TheMetagraph/runic was NOT touched (concurrent ariston agents path-dep it). All git work was done in a separate clone.
• The ariston-against-resynced-runic compile is the final pre-merge gate and is deferred to the orchestrator to run once concurrent ariston agents finish (it requires pointing the shared fork at this branch).

Worth upstreaming to zblanco/runic?

Nothing fork-specific to upstream — this is a pure pull-through. The only forward-looking note for upstream is that the Worker :snapshot_strategy write-side policy (their own .docs follow-up) remains unimplemented; that's zblanco's roadmap item, not ours.

🤖 Generated with Claude Code