mlpstorage status: per-result readiness table, post-run recap, runs list SUBMIT token (status-and-submit PR 2)

[FileSystemGuy]

PR 2 of the status / submit series (design agreed 2026-09-23; PR 1 = #879). Adds the habitual per-result view of a results-dir, prints it after every run, and puts the per-run readiness token on runs list.

mlpstorage status

New top-level verb over an initialized results-dir (resolved like runs: --results-dir/-rd > MLPSTORAGE_RESULTS_DIR > the mlpstorage init default). One row per result (Rules.md 1.3), scored by mlpstorage_py/readiness.py from PR 1, which runs the checker behind mlpstorage validate in-process.

$ mlpstorage status
closed/Acme   rules edition 3.0   2 results, 9 runs

SYSTEM  BENCHMARK  MODEL      ACCEL  RUNS  SUBMIT     NOTE
sys-1   training   retinanet  b200   2/6   short      4 more runs needed; run 9 failed (exit status 6); remove it (mlpstorage runs rm 9)
sys-1   training   unet3d     b200   6/6   paperwork  sys-1.yaml: 2 blank fields, sys-1.pdf missing

0 of 2 results ready.
Paperwork for sys-1 (closed): systems/sys-1.yaml: 2 blank fields; systems/sys-1.pdf missing
Next: mlpstorage status --runs   (which runs count, which must go)

• RUNS is n/m, m from the edition's checker.runs_per_result (never hard-coded); checkpointing counts phases.
• SUBMIT precedence short > invalid > paperwork > ready; whatif results sit in their own section and show -, and never count toward "n of m results ready".
• NOTE on a paperwork row is the short form (what); the footer names each system's paperwork once (where), so twelve rows on one system do not read as twelve problems.
• Tree-level problems (nothing to attribute to a run or a system) are listed; checker warnings are counted, not listed, with a pointer to validate.
• "Next:" is status --runs when a result is short or invalid, validate <dir> when there are tree problems or everything is ready (PR 3 swaps that last one for submit --dry-run), "fill in the paperwork" otherwise.
• --runs expands each result into its run rows (ID STATUS STARTED COUNTED NOTE, second indented header line). Paperwork never appears at run level.
• Filters mirror runs list (--mode, --benchmark, --model, --systemname/-sn) plus --submit {short,invalid,paperwork,ready}; --json prints the readiness to_dict() with the selection applied.
• Always exits 0 (a "git status" is not a gate; submit --dry-run will be). Not recorded in history, same initialized-tree refusal as runs.

Printed after every run

run_benchmark prints the same table, restricted to the result the run just joined, after benchmark.run() has returned and the leaf's metadata is written, so it never interleaves with DLIO output (the BACKLOG B-02 lesson). Only for run (not datagen/datasize/configview), not under --quiet, and a failure to score the tree is a single warning that never changes the run's exit code. Output is stdout, like runs list; the logger (stderr) keeps the results-dir line and the recap.

runs list

Gains a SUBMIT column right after STATUS with the per-run token from the same evaluator: ok / failed / running / invalid / extra; - for whatif runs (never packaged) and non-run leaves (datagen/datasize have no result); ? on every row, with one warning, when the evaluator fails, so the listing rm acts on stays usable. JSON rows gain "submit" (null where the table shows - for a non-run leaf, "-" for whatif). The --status {complete,failed,incomplete} filter is unchanged: it stays the ledger state.

Readiness tweaks (mlpstorage_py/readiness.py)

• leaf_key(results_dir, path), result_for_leaf(sub, leaf), run_tokens(sub); evaluate_result now composes the first two.
• Failed / invalid runs sharing one reason collapse into one NOTE clause with one runs rm hint (runs 3, 4, 5 invalid: [2.1.19] ...; remove or redo them (mlpstorage runs rm 3 4 5)). Single-run wording is byte-identical to PR 1.

Help surface

--help_all gains the status synopsis line, tree entry and a STATUS block, and RUNS_LIST documents the new column; the parity suite maps the new leaf. This landed here rather than in PR 4 because test_help_all_parity.py refuses a parser leaf without a block, so PR 4 shrinks to ManPage.md. CLAUDE.md and the README command table get one line each.

Tests

tests/unit/test_status_command.py (56): parser, table (header, columns, tokens, NOTE, whatif section, open division, checkpointing phases, vdb without accelerator, tree problems, warnings, empty tree), --runs, filters, --json, gates, post-run recap (printed for run, failed run keeps its exit code, silent under --quiet and for other commands, evaluator failure is a warning only, no results-dir is a no-op), runs list column and JSON, run_tokens / leaf_key, note grouping, help surface. TDD: RED commit first, then GREEN. test_help_behavior.py root next: fragments updated for the new verb.

All four CI suites green locally. The validator itself is untouched (readiness only reads its findings), so no validator-diff on the frozen v3.0 tree was run for this PR.

Calls worth a look

• runs list column name SUBMIT (per-run token) alongside the per-result SUBMIT in status: same word, one level apart. Alternatives considered: replacing the existing STATUS values (would change what --status filters) or a longer header.
• The post-run recap goes to stdout. The run log files in the leaf are detached before it prints, so it is not in mlpstorage.log; mlpstorage status reproduces it on demand.
• A checkpointing leaf whose metadata carries no num_checkpoints_write/read counts as extra (supplies no phase). That is PR 1's rule surfacing in runs list; the DoD fixture shows it.

[github-actions]

MLCommons CLA bot All contributors have signed the MLCommons CLA ✍️ ✅