batch(manual-1615): fold 6 ready branches (#5735 #5592 #5586 #5657 #5672 #5762)

.claude/skills/apr-dogfood/SKILL.md

@@ -1594,7 +1594,7 @@ The nine clusters at zero, largest first: `http-orchestrate-banco` (95),
 `test-harness` (49), `rag-eval` (44), `qa-cgp` (37), `simulation` (18),
 `orchestrate-pacha-secrets` (17).
 
-**Report both numbers or neither (T2).** "5 of 14 clusters gated (35.7%)" without "144 of 907 features gated (15.9%)" beside it is a proxy masquerading as coverage, and the gate refuses to emit it — *on this line too*.
+**Report both numbers or neither (T2).** "5 of 14 clusters gated (35.7%)" without "144 of 911 features gated (15.8%)" beside it is a proxy masquerading as coverage, and the gate refuses to emit it — *on this line too*.
 
 The rule is about the NUMBER, not about a phrasing, and it is enforced on every
 surface that can emit one: the gate's own report, the receipt, the output of

README.md

@@ -114,7 +114,7 @@ publishing — all backed by YAML provable contracts that fail CI on drift.
 | Metric | Count | Source of truth |
 |-------:|------:|---|
 | Workspace crates | **81** workspace crates | `cargo metadata --no-deps` (NOT `ls crates/` — 4 are `exclude`d, 1 has no Cargo.toml) |
-| Provable contracts | **<!-- CONTRACT_COUNT_START -->1989<!-- CONTRACT_COUNT_END -->** provable contracts | `contracts/census.json` `.n_files` — the set `pv lint` walks (`pv census`, ONT-001 ONT-1; regenerated by `make contracts`, written by `make readme-sync`, guarded by `scripts/check_readme_claims.sh`) |
+| Provable contracts | **<!-- CONTRACT_COUNT_START -->1993<!-- CONTRACT_COUNT_END -->** provable contracts | `contracts/census.json` `.n_files` — the set `pv lint` walks (`pv census`, ONT-001 ONT-1; regenerated by `make contracts`, written by `make readme-sync`, guarded by `scripts/check_readme_claims.sh`) |
 | CLI commands | **113** CLI commands | `contracts/apr-cli-commands-v1.yaml` §`commands` (parse the list; `apr --help` also lists `help` itself, and `grep -c '^  - name:'` gives 119 — other same-indent `name:` keys exist in the file) |
 | Book CLI chapters | **114** chapters | `ls book/src/cli/*.md` |
 | Book lib chapters | **73** chapters | `ls book/src/lib/*.md` (parity with `pub mod`) |
@@ -403,7 +403,7 @@ falsification_tests:
   prediction: apr validate bad-model.apr exits non-zero
 ```
 
-The tree carries <!-- CONTRACT_COUNT_START -->1989<!-- CONTRACT_COUNT_END --> contracts across inference, training, quantization, attention, FFN,
+The tree carries <!-- CONTRACT_COUNT_START -->1993<!-- CONTRACT_COUNT_END --> contracts across inference, training, quantization, attention, FFN,
 tokenization, model formats, CLI safety — and this README itself.
 
 ## Migration from old crates

contracts/apr-cli-operations-v1.yaml

@@ -270,6 +270,11 @@ falsification_tests:
   prediction: print_json and print_reverse_lookup complete on every table and report launches/layer x layers
   test: commands::ptx_map::tests::print_json_and_reverse_lookup_cover_every_branch
   if_fails: ptx-map JSON or reverse-lookup output panics or miscounts launches
+- id: FALSIFY-OPS-012
+  rule: apr run prints every output mode and derives tok/s as documented
+  prediction: print_run_output succeeds for stream, json, benchmark and text; effective_tok_per_sec prefers the reported rate, else tokens/duration, else 0.0
+  test: commands::run::tests::print_run_output_serves_every_mode_and_derives_the_rate
+  if_fails: apr run output errors on a finished run or reports a wrong rate
 kani_harnesses:
 - id: KANI-OPS-001
   obligation: ReadOnly commands have no side effects
@@ -324,7 +329,7 @@ qa_gate:
   - progress_reporting
   - concurrent_model_access
   - tokenizer_consistency
-  pass_criteria: All 11 falsification tests pass
+  pass_criteria: All 12 falsification tests pass
   falsification: >
     Run read-only command with filesystem watcher to detect mutations.
     Force inference error and measure GPU memory leak.

contracts/apr-dogfood-coverage-v1.yaml

@@ -3,7 +3,7 @@ metadata:
   created: '2026-08-22'
   author: PAIML Engineering
   references:
-  - 'docs/audits/surface_audit.csv — 142 of 830 features gated, across 28 binaries and 14 clusters, measured 2026-08-22 @ 4bbfeb07f; 142 of 832 features gated after the PERF-046 partial re-audit (PR #2742); 143 of 833 features gated after the PP-LLAMA-001 re-audit (GET /v1/effective-config added and swept by the dogfood route enumeration, router.rs rows re-pointed); 144 of 837 features gated after PP-066 L0-1b added the three `apr parity` flag rows (--per-op, --out, --threshold), which the dogfood sweep does not reach -- the denominator grew and the numerator did not; 144 of 838 features gated after #3726 added `apr tokenize encode` (the tokenizer-parity gate''s id source), which the dogfood sweep does not reach either; 144 of 839 features gated after ONT-10 S19 ledgered the bare `aprender-cbtop` root surface (interactive TUI / --headless), which the dogfood sweep does not reach; 144 of 851 features gated after ONT-4g (#4476) added the twelve pv/apr command rows the binary snapshot found unledgered, none of them gated; 144 of 853 features gated after the ONT-4g bin gate (surface_audit_bins_gate.sh) found `pv-sat` shipping with no row and its two surfaces were ledgered, neither gated; 144 of 857 features gated after ONT-10 S4 ledgered the 4 hf_* tools `aprender-orchestrate mcp` lists, none of them gated; 144 of 868 features gated after ONT-10 S9/S7 mirrored the eleven ONT-4g pv rows as `apr pv` rows (the apr node joins binary=apr), none of them gated; 144 of 894 features gated once main (with #4219''s 26 `<bin> --version` rows, each run and observed printing its SHA, which the dogfood sweep does not reach) merged into ONT-10''s 868; 144 of 904 features gated after the bin gate found `aprender-ci-tools` (the C301 port of the CI helpers) shipping with no row and its ten surfaces (nine subcommands and --version) were ledgered, none of them gated (#5170); 144 of 906 features gated after #5382 added the `pv ontology readme` and `apr pv ontology readme` rows, ungated; 144 of 907 features gated after #5225 added the `aprender-ci-tools ladder-cells-produce` row, ungated'
+  - 'docs/audits/surface_audit.csv — 142 of 830 features gated, across 28 binaries and 14 clusters, measured 2026-08-22 @ 4bbfeb07f; 142 of 832 features gated after the PERF-046 partial re-audit (PR #2742); 143 of 833 features gated after the PP-LLAMA-001 re-audit (GET /v1/effective-config added and swept by the dogfood route enumeration, router.rs rows re-pointed); 144 of 837 features gated after PP-066 L0-1b added the three `apr parity` flag rows (--per-op, --out, --threshold), which the dogfood sweep does not reach -- the denominator grew and the numerator did not; 144 of 838 features gated after #3726 added `apr tokenize encode` (the tokenizer-parity gate''s id source), which the dogfood sweep does not reach either; 144 of 839 features gated after ONT-10 S19 ledgered the bare `aprender-cbtop` root surface (interactive TUI / --headless), which the dogfood sweep does not reach; 144 of 851 features gated after ONT-4g (#4476) added the twelve pv/apr command rows the binary snapshot found unledgered, none of them gated; 144 of 853 features gated after the ONT-4g bin gate (surface_audit_bins_gate.sh) found `pv-sat` shipping with no row and its two surfaces were ledgered, neither gated; 144 of 857 features gated after ONT-10 S4 ledgered the 4 hf_* tools `aprender-orchestrate mcp` lists, none of them gated; 144 of 868 features gated after ONT-10 S9/S7 mirrored the eleven ONT-4g pv rows as `apr pv` rows (the apr node joins binary=apr), none of them gated; 144 of 894 features gated once main (with #4219''s 26 `<bin> --version` rows, each run and observed printing its SHA, which the dogfood sweep does not reach) merged into ONT-10''s 868; 144 of 904 features gated after the bin gate found `aprender-ci-tools` (the C301 port of the CI helpers) shipping with no row and its ten surfaces (nine subcommands and --version) were ledgered, none of them gated (#5170); 144 of 906 features gated after #5382 added the `pv ontology readme` and `apr pv ontology readme` rows, ungated; 144 of 907 features gated after #5225 added the `aprender-ci-tools ladder-cells-produce` row, ungated; 144 of 911 features gated after the `sim repo-flow` and `sim course-flow` rows (apr and aprender-simulate, four rows) were ledgered, each run on x86_64, ungated'
   - 'docs/audits/surface_audit_elbow.png — k-selection evidence: inertia knee and silhouette over k in [2,45]'
   - 'scripts/dogfood_cluster.py — the k-sweep that produced the elbow plot (k-selection ONLY; it does not write the columns)'
   - 'scripts/check_no_cluster_id_keys.sh — T1 enforcement: nothing may key on `cluster_id`'
@@ -87,9 +87,9 @@ metadata:
 
     overall:
       command: "python3 scripts/dogfood_baseline.py  # section: totals"
-      rows: 907
+      rows: 911
       covered: 144
-      ratio: 0.1588            # 144/907 -- 15.9%, NOT "about 16%"
+      ratio: 0.1581            # 144/911 -- 15.8%, NOT "about 16%"
       binaries: 30
       binaries_at_zero_coverage: 29
       clusters: 14
@@ -104,7 +104,7 @@ metadata:
       note: >
         covered may never DECREASE for any binary; total may never decrease
         without a reconciliation finding recording which direction moved.
-      apr: {total: 388, covered: 144}
+      apr: {total: 390, covered: 144}
       aprender-orchestrate: {total: 189, covered: 0}
       aprender-test-cli: {total: 40, covered: 0}
       pv: {total: 50, covered: 0}
@@ -114,7 +114,7 @@ metadata:
       apr-qa: {total: 16, covered: 0}
       aprender-rag: {total: 14, covered: 0}
       aprender-train-shell: {total: 14, covered: 0}
-      aprender-simulate: {total: 13, covered: 0}
+      aprender-simulate: {total: 15, covered: 0}
       aprender-verify: {total: 12, covered: 0}
       aprender-explain: {total: 8, covered: 0}
       aprender-present: {total: 8, covered: 0}
@@ -182,7 +182,7 @@ metadata:
       profiling: {total: 46, covered: 1}                    # 2.2% of cluster,  0.7% of gate effort
       rag-eval: {total: 46, covered: 0}                     #  ZERO
       qa-cgp: {total: 38, covered: 0}                       #  ZERO
-      simulation: {total: 19, covered: 0}                   #  ZERO
+      simulation: {total: 23, covered: 0}                   #  ZERO
       orchestrate-pacha-secrets: {total: 17, covered: 0}    #  ZERO
 
     per_band:
@@ -195,7 +195,7 @@ metadata:
         the 4.3% coverage of that band is why.
       q1_2: {total: 80, covered: 58}     # 72.5%
       q3_4: {total: 49, covered: 27}     # 55.1%
-      q5_6: {total: 719, covered: 29}    # 4.1%
+      q5_6: {total: 723, covered: 29}    # 4.1%
       q7_8: {total: 38, covered: 10}      # 26.3%
       q9_10: {total: 21, covered: 20}    # 95.2%
 
@@ -306,7 +306,7 @@ equations:
     codomain: bool
     invariants:
     - "T2. Cluster coverage is a PROXY: one gate in a 95-member cluster is 1%, not covered"
-    - "5/14 clusters (35.7%) and 144/907 features (15.9%) are reported together, always"
+    - "5/14 clusters (35.7%) and 144/911 features (15.8%) are reported together, always"
     - "Enforced mechanically by enforce_pairing(); deleting the feature fraction from the emitter turns the gate RED"
     - "This is the single most important trap: reporting the proxy alone is how a coverage gate becomes theatre while looking stricter"
 
@@ -695,7 +695,7 @@ falsification_tests:
     Every emitted line stating a CLUSTER-level ratio also states the underlying
     FEATURE-level ratio, on EVERY channel one can be emitted through: this gate's
     report, the receipt, scripts/dogfood_baseline.py and
-    .claude/skills/apr-dogfood/SKILL.md. 5 of 14 clusters (35.7%) is a proxy and 144 of 907 features (15.9%) is the thing.
+    .claude/skills/apr-dogfood/SKILL.md. 5 of 14 clusters (35.7%) is a proxy and 144 of 911 features (15.8%) is the thing.
     One gate in a 95-member cluster is
     1%. The rule keys on the NUMBER -- a denominator equal to the cluster count
     -- not on a phrase, because a phrase can be reworded and a denominator cannot;

contracts/aprender-registry-download-progress-v1.yaml

@@ -0,0 +1,47 @@
+metadata:
+  id: C-REGISTRY-DOWNLOAD-PROGRESS
+  version: 1.0.0
+  created: '2026-10-18'
+  author: PAIML Engineering
+  kind: pattern
+  status: ACTIVE_ALGORITHM_LEVEL
+  description: |
+    Pins the human-readable accessors of aprender-registry's DownloadProgress:
+    eta_human formats seconds, minutes and hours; downloaded_human reads the
+    downloaded byte count and total_human reads the total, never each other's.
+  references:
+    - 'crates/aprender-registry/src/cache.rs (DownloadProgress::eta_human, downloaded_human, total_human)'
+
+equations:
+  progress_human_accessors:
+    formula: |
+      eta_human = format_duration(eta_secs); downloaded_human = format_bytes(downloaded_bytes);
+      total_human = format_bytes(total_bytes)
+    domain: DownloadProgress values
+    invariants:
+    - 'downloaded_human depends only on downloaded_bytes; total_human only on total_bytes'
+
+proof_obligations:
+- id: RDP-INV-001
+  type: invariant
+  property: each human accessor reads its own field
+  formal: "∀ t ∈ {progress_human_tests}: exit(t) = 0"
+  applies_to: progress_human_accessors
+
+falsification_tests:
+- id: FALSIFY-REGISTRY-DOWNLOAD-PROGRESS-001
+  rule: eta_human, downloaded_human and total_human render their own fields
+  prediction: 'eta 42.9/125/3725 s -> "42s"/"2m 5s"/"1h 2m"; 1536 B downloaded -> "1.50 KB"; 5 MiB total -> "5.00 MB"'
+  test: cargo test -p aprender-registry --lib cache::progress_human_tests
+  if_fails: progress lines show the wrong size or ETA to users during model pulls
+  ship_blocking: false
+  mutation: 'make downloaded_human format total_bytes; must turn RED'
+
+qa_gate:
+  id: QA-REGISTRY-DOWNLOAD-PROGRESS-001
+  name: Registry download progress accessors gate
+  description: human-readable accessors read their own fields
+  checks:
+  - progress_human_accessors
+  pass_criteria: FALSIFY-REGISTRY-DOWNLOAD-PROGRESS-001 passes
+  falsification: Any failure fails the gate