Module checkpoint 

Directory-based resumable checkpoint storage for long benchmark runs.

Port of benchmarks/checkpoint.py. A checkpoint is a directory:

<checkpoint-dir>/
  manifest.json      pretty (indent 2), sorted-key JSON + trailing "\n",
                      written atomically (tmp file + rename)
  observations.jsonl one compact, sorted-key JSON row per completed
                      agreement observation, appended + flushed per line
  h2h.jsonl           one compact, sorted-key JSON row per completed
                      head-to-head game, appended + flushed per line

Both JSONL files use crate::bench::canonical::canonical_json, the same byte-exact encoder used for dataset/bundle artifacts, so a checkpoint directory written by this crate loads and rehydrates (bundle_from_checkpoint) correctly in Python’s benchmarks.checkpoint module and vice versa. manifest.json uses crate::bench::canonical::canonical_json_pretty, matching Python’s json.dumps(manifest, indent=2, sort_keys=True) + "\n".

Resume validation is intra-language only. validate_resume_manifest compares the run’s config dict against the manifest’s stored config dict, but the two languages’ CLI argument dicts have different key sets and shapes (e.g. track_memory/skip_agreement exist only in the Python CLI) — a checkpoint directory started by one language’s run is not expected to --resume cleanly in the other. Loading and reporting (bundle_from_checkpoint, report --input <dir>) work identically in both languages regardless of which one wrote the directory.

Unlike the single-file .ckpt format this module replaces (PR #10), an invalid JSONL line is a hard error (file path + 1-based line number) — there is no truncated-tail tolerance here, because manifest.json’s atomic tmp+rename write is the integrity anchor: a crash mid-write of an observation/h2h line can only ever leave a trailing partial line (never a torn manifest), and callers that always flush after append_jsonl should not see one in practice, but Python chose to raise rather than silently drop, so this port matches that.

Structs

CheckpointPaths

The paths that make up one checkpoint directory.

Constants

H2H_RECORDS

MANIFEST

OBSERVATIONS

Functions

append_jsonl

Append one JSON object as one compact, sorted-key JSONL row, flushing to the OS immediately.

build_manifest

Build a fresh checkpoint manifest (mirrors Python CLI’s _checkpoint_manifest in examples/cross_engine_benchmark.py, not the library-level _build_manifest in benchmarks/checkpoint.py — the CLI manifest intentionally omits schema_version; that key only lives on the bundle produced by bundle_from_checkpoint, from the bundle::SCHEMA_VERSION constant).

bundle_from_checkpoint

Rehydrate a checkpoint directory into the standard benchmark bundle, including a partial state — an in-progress or preflight-failed checkpoint rehydrates fine, with whatever rows/records/aggregates are available so far. The bundle gains a "checkpoint": {status, counts} block (and h2h_pairs when the manifest carries one).

checkpoint_paths

Resolve the manifest/observations/h2h file paths under root.

key_set

Build the set of stable resume keys already present in checkpoint rows.

load_jsonl

Load a JSONL file; a missing file behaves like an empty stream. Blank lines are skipped. An invalid line is a hard error naming the file and its 1-based line number (no truncated-tail tolerance — see the module doc).

load_manifest

Load the checkpoint manifest, or an empty object if it doesn’t exist yet (mirrors Python’s load_manifest returning {}).

normalize_run_config

Drop volatile fields that must not participate in resume validation.

update_manifest_counts

Update checkpoint progress counters in place (counts, optionally status, always updated_at) and return the resulting manifest.

validate_resume_manifest

Raise a clear error when a resume checkpoint does not match this run: dataset checksum must be equal, and the normalized config signature must be equal (per-key diff in the error message otherwise). allow_skip_h2h_mismatch additionally drops skip_h2h from the signature — the CLI only sets this when the checkpoint’s existing h2h records already equal the expected count, so a differing --skip-h2h this run genuinely doesn’t matter.

write_manifest

Atomically write the checkpoint manifest (tmp file + rename), pretty (indent 2), sorted-key JSON + trailing newline, matching Python’s json.dumps(manifest, indent=2, sort_keys=True) + "\n".