feat: WAL time-travel snapshots

[mvanhorn]

Walkthrough

HyperFrames walkthrough of this PR.

mp4

What this does

The WAL already keeps every state a repository has ever been in, and walgit wal materialize --at-seq already rebuilds one. That rewind was reachable only from a terminal with bucket credentials, because the code lived in crates/walgit-cli/src/wal_cmd.rs. This exposes the same replay over HTTP.

1. The replay moved into walgit-wal (crates/walgit-wal/src/snapshot.rs), the crate the CLI and the server already share — not copy-pasted into ops.rs. On the way it gained the shape a non-terminal caller needs: it returns a Snapshot (at_seq, head_seq, from_seq, replayed entries, git_dir, refs/ref_count, packs with per-pack source) instead of printing; narration goes to an Arc<dyn Fn(String)> sink so the CLI prints and a server task emits notices; errors are WalError rather than anyhow; and no unwrap is left on the path. The whole replay runs on the bulk runtime (sync::on_bulk_runtime) so downloads, 32 MiB copies and git index-pack waits never sit on a caller's request workers (principle VI).

2. POST /{owner}/{repo}/api/ops/snapshot?at_seq=<n> — a new OPS entry, id = "snapshot", params = ["at_seq"], mutating: false. It runs walgit_wal::snapshot_at as an ordinary task (narrated, attachable, interrupted by the D31 drain like every other unit) and writes to <cache.dir>/snapshots/<owner>/<name>/<seq>/. snapshot.json is written last, so a tree carrying it is complete and one without it is a partial run that gets rebuilt: the op is idempotent and answers {built: bool, snapshot: {…}}.

3. GET /{owner}/{repo}/api/snapshot/{seq} — reads that rewind back with the overview's auth (require_read), no-store, 404 naming the op when this host has not built one. An unparsable {seq} is a 400 from the route itself.

4. WAL tab: the ops table renders at_seq as a number field (defaulting to the head) plus a link to the JSON, because it is a value parameter and not a flag. Running, streaming and the recent-runs table are the existing runOp/SSE path, unchanged.

5. SDK + docs: repo.snapshot(seq) and the Snapshot types in web/sdk/repos.ts; the endpoint, the op, the 404 and the ref cap in web/API.md (plus snapshot in the task-kinds list and the conformance checklist); the walgit_wal::snapshot surface in docs/CONTRACT.md; a budget row in docs/ROUNDTRIPS.md; the provenance line in AGENTS.md §2.4.

What it does not do

• Live refs and the serving copy never move. Nothing is published, no WAL entry is written, no lease is taken. The answer carries head_seq so a caller can see where the serving copy still is, and the test asserts it (refs endpoint, manifest head, applied seq and the local copy's refs/heads/main all stay at seq 2 after a rewind to seq 1).
• rematerialize is untouched. It has no at_seq and still means "catch this instance's copy up to the head".
• No tar/archive endpoint (no such helper exists in the tree), no bundle-uri historical families, no smart-HTTP clone of a past sequence, no new store backend, no new auth path, no new webhook event, no new config key.
• No retention for snapshot trees: they are a cache under cache.dir that an operator creates deliberately, and snapshot_at refuses to build one on an instance whose cache budget cannot hold even the live pack set (WalError::TooLarge → 503 with the existing message). Bounding them across sequences would be a separate change.
• refs in the JSON is capped at 1000 entries with ref_count alongside, so a 466 k-ref repository does not turn a request path into a 30 MB document. The rebuilt copy at git_dir has all of them.

File pointers

Where	What
crates/walgit-wal/src/snapshot.rs	the replay (materialize_at), the cache-dir form (snapshot_at), snapshot_dir/read_snapshot, Snapshot/SnapshotRef/SnapshotPack, both unit tests
crates/walgit-wal/src/lib.rs	pub mod snapshot + re-exports
crates/walgit-cli/src/wal_cmd.rs	WalAction::Materialize now calls the shared function and prints the summary; 348 lines of replay and its test left the CLI
crates/walgit-server/src/ops.rs	the snapshot OpSpec and arm; run takes the narrator as an owned Arc and derives the borrowed Log from it
crates/walgit-server/src/web/ui.rs	the snapshot/{seq} route and handler
crates/walgit-server/src/web/v1.rs	the route in /api/v1 discovery
crates/walgit-server/tests/snapshot.rs	the server test (wired into just test)
web/sdk/repos.ts, web/src/pages/OverviewPage.tsx, web/src/styles.css	SDK method + types, the at_seq field, its input style
web/API.md, web/sdk/README.md, docs/CONTRACT.md, docs/ROUNDTRIPS.md, AGENTS.md	the contracts

Round trips

No hot path changes; docs/ROUNDTRIPS.md §2 gained one row for the rewind, which is operator-driven: one conditional manifest GET (the refs sync that validates at_seq against the head), then the checkpoint and its refs (2 GETs when one is at or before the cut), the log segments through the cut, and per pack not already local a striped pack ∥ idx ∥ advertised side-files. A sequence already materialized on the host costs nothing past the freshness GET. The sim suite's request budgets are unchanged and pass.

Tests

• crates/walgit-wal/src/snapshot.rs: the existing cold-rewind test moved with the code (not deleted) and grew the assertions the returned Snapshot makes possible — pack provenance (store vs local), the replay start, the refs, and that the writer's copy kept its packs and its head. A second test covers the snapshot_at layout, idempotency (same built_at on the second call), rebuild of a tree whose marker is gone, and rejection of seq 0 and past-the-head sequences without leaving a tree behind.
• crates/walgit-server/tests/snapshot.rs: two pushes (head seq 2) → POST ops/snapshot?at_seq=1 → the result's refs are the first commit, head_seq is 2, the rewound copy is a real repository at the first commit that does not contain the second, info/refs + manifest + applied seq + the local copy are all still at seq 2, GET snapshot/1 round-trips, GET snapshot/2 is a 404 naming the op, GET snapshot/nope is a 400, the second op run rebuilds nothing, and each bad at_seq (missing, empty, abc, 0, 99) is refused with its reason.

Run here on the pinned toolchain: cargo fmt --check clean; cargo test --workspace --lib --bins, cargo test -p walgit-store -p walgit-git -p walgit-wal -p walgit-bundle --tests, the walgit-server fast tier (now including --test snapshot), and --test sim all green; cargo build --workspace --all-targets has no rustc warnings; web pnpm run build (oxlint --deny-warnings + tsc --noEmit + both vite builds) passes.

Two pre-existing failures on this branch are also present on main at the same commit and are unrelated: e2e::lfs_roundtrip_when_available (verified failing on 6d8fa54 in a clean worktree here) and e2e::fetch_from_front_that_serves_the_base_remotely (the flake AGENTS.md documents; passes alone). cargo clippy -- -D warnings is also red on main with the pinned 1.97.1 toolchain — newer pedantic lints in walgit-proto, walgit-config and walgit-server/build.rs, ~1800 workspace-wide. The files this PR touches contribute none: crates/walgit-wal/src/snapshot.rs is clippy-clean, and crates/walgit-server/tests/snapshot.rs has 6 findings of the classes every sibling test file already carries (indexing may panic etc.: 70 in sim.rs, 61 in web_api.rs). Fixing the pre-existing set would be a separate change.

[mvanhorn]

HyperFrames walkthrough of this PR.

mp4