Add configurable checkpointing to the larch2 optimization loop

[matsen]

Closes #39

Summary

• New CLI flags --checkpoint-after <N>, --checkpoint-prefix <P>, and --resume <path> add configurable checkpoint/resume to the larch2 optimization loop.
• Phased per the issue: Phase 1 writes DAG-only checkpoints (--resume is functionally equivalent to --dag-pb); Phase 2 writes a full-state larch_checkpoint (DAG + RNG + patience + results + git SHA + args fingerprint) so a resumed run is canonical-equivalent to an uninterrupted run with the same seeds.
• Args fingerprint is SHA-256 over a JSON payload of the trajectory-affecting flags. The payload itself is also stored alongside the digest so a mismatch on resume names the conflicting field. Resume rejects every input flag (--dag-pb, --tree-pb, --fasta, --newick, --refseq, --vcf) since the checkpoint is self-describing.

Implementation notes

• proto/checkpoint.proto + include/larch/checkpoint.hpp define the larch_checkpoint message family. C++ proto-mirror structs use the existing reflection-based encoder, plus new std::optional<int64_t> overloads so optional uint64 fields distinguish 0 from "unset".
• mt19937 (de)serialization uses std::ostringstream / operator<< (the C++ standard guarantees byte-exact round-trip).
• SHA-256 is a self-contained FIPS 180-4 implementation in src/checkpoint.cpp (no new dep).
• Atomic write: <path>.tmp then rename.
• Format detection: a larch_checkpoint always starts with the byte 0x08 (tag for schema_version, varint), distinguishing it from raw dag_data files (0x0a or other length-delimited fields).
• Determinism fix to build_phylo_dag_from_proto: walk proto IDs in sorted order and append edges in edge_id order so a save+load round trip preserves the in-memory phylo_dag's node/edge layout. The previous unordered_map iteration and parent-sort silently broke determinism for resume because sampling traverses the DAG by node-index and children-list order.

Tests added

• test/checkpoint_test.cpp — mt19937 round-trip, larch_checkpoint proto round-trip (incl. nested dag_data, results vector, patience state, RNG state), SHA-256 known-answer tests, optional<int64_t> zero-vs-absent presence semantics.
• test/checkpoint_integration.sh — end-to-end CLI: Phase 2 deterministic resume for K∈{1,2,3} with canonical-equal final output; multi-resume chain (catches RNG-state non-idempotency); Phase 1 score-not-worse-than-baseline; args fingerprint mismatch refused with the conflicting field named; --resume + --vcf refused; pre-drift checkpoint emission with --patience 2 --drift 1; future schema_version rejected with a clear error.
• test/dag_canonical_equal.cpp — content-keyed canonical comparison helper used by the integration test (uses sample_id for leaves and the compact-genome string for inner nodes; edge tuples as a multiset). Stronger than the issue's suggested proto-id sort, which would fail when merge state differs across runs and reorders proto-id assignments even though the DAGs are logically equivalent.

Test plan

• ctest --test-dir build — all 21 tests pass (19 existing + 2 new).
• Manual verification: 6-iter run with --checkpoint-after 1 writes out.ckpt-{1..6}.pb.gz and the final output canonical-equals a baseline uninterrupted run for every checkpoint K.
• Pre-drift checkpoint manually verified with --patience 2 --drift 1 on data/testcase/full_dag.pb.gz.

🤖 Generated with Claude Code

[matsen]

Issue Lead (final review)

Category: completed
Scope check: on-track. Every CLI flag, proto field, integration scenario, and success criterion in the issue body has a corresponding implementation and test. No scope drift, no premature deferral.

Assessment:

• Phase 1 and Phase 2 both ship as specified. The issue's Phase 2 gate ("two runs with identical --seed, one uninterrupted and one interrupted+resumed, produce final outputs that match under canonical comparison and identical per-iteration parsimony scores") is verified by checkpoint_integration_test for K in {1..5} on a 6-iteration run, which is the full N-1 every-iteration interrupt property test from the issue's test plan Fix sampled trees dropping leaves from inconsistent DAGs #9 (stronger than the {3,7,13} sample originally suggested).
• All 9 items in the issue's test plan are covered: RNG round-trip, checkpoint round-trip, Phase 1 score-not-worse, Phase 2 determinism, pre-drift checkpoint, args fingerprint mismatch (names the conflicting field), multi-resume chain, forbidden input flag, every-iteration interrupt.
• The determinism fix to build_phylo_dag_from_proto (sorted proto-id walk, edges in edge_id order) is the right kind of root-cause fix — it identifies and resolves the unordered_map iteration that would have silently broken Phase 2 byte-equivalence even with otherwise-correct save/load.
• Args fingerprint stores both the SHA-256 digest and the underlying JSON payload so a mismatch can name the conflicting field. Schema version is guarded by a static_assert against the magic-byte detection. Atomic write via .tmp + rename. mt19937 via operator<<. All match the issue's design choices.
• 21/21 tests pass (full ctest run, integration test 38.6s).

Follow-ups filed: none. The PR body has no DEFERRED section and the changed files have no TODO/FIXME/"defer"/"future work" markers. The reviewer-flagged A4/N3 nits in load_proto_dag.hpp and the drift_escape switch are pre-existing code untouched by this PR — fixing them here would be scope drift.

Action: Phase set to completed. PR #40 is ready to merge.