fix(selfhost): harden AST-parity gates — assert 0 run-failures, non-empty samples, doc release runtime

Addresses three review findings on the AST-parity harness:

- Medium: ast_parity_corpus counted run-failures but never asserted on them, so
  the rss producer could start crashing on many files and the gate would still
  pass as long as the byte-exact floor held (contradicting the "0 run-failures"
  doc claim). Add assert_eq!(run_failures, 0, ...) — a crash now regresses the
  gate regardless of the floor. Verified in --release: 121 byte-exact, 0
  run-failures.

- Low: ast_sample_files() silently returns empty if selfhost/samples/ast is
  missing/unreadable, making ast_parity_samples pass vacuously. Assert
  files.len() >= AST_SAMPLE_MIN (6).

- Low: the ignored corpus gate runs the reg-VM over ~560 files and is slow in a
  debug build (minutes). Document running it in --release (test docstring + plan
  doc) and point at ast_parity_samples as the fast non-ignored inner-loop gate.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: olwang

crates/rsscript/src/selfhost_parity.rs

@@ -1478,6 +1478,14 @@ fn ast_parity_samples() {
     let exe = compile_astdump().expect("rss astdump should compile");
     let mut mismatches: Vec<String> = Vec::new();
     let files = ast_sample_files();
+    // Guard against a vacuous pass: a missing/unreadable samples dir would make
+    // `files` empty and this test green while covering nothing.
+    assert!(
+        files.len() >= AST_SAMPLE_MIN,
+        "expected >= {AST_SAMPLE_MIN} curated AST samples under selfhost/samples/ast/, found {} \
+         (missing or unreadable dir makes this test pass vacuously)",
+        files.len()
+    );
     for file in &files {
         let rel = file
             .strip_prefix(selfhost_dir())
@@ -1507,15 +1515,25 @@ fn ast_parity_samples() {
     );
 }
 
+/// Minimum number of curated AST samples that must exist (guards `ast_parity_samples`
+/// against a vacuous pass if the samples dir goes missing).
+const AST_SAMPLE_MIN: usize = 6;
+
 /// Floor for `ast_parity_corpus` — the number of corpus files whose rss AST dump
 /// already matches the oracle byte-for-byte. Ratchets up as the producer's
 /// coverage grows; a drop signals a regression. (Full parity = files.len().)
 const AST_CORPUS_PARITY_FLOOR: usize = 121;
 
-/// Step-2 measurement gate (ignored by default): how many of the 556 corpus files
-/// the rss producer already reproduces byte-for-byte. Not full parity yet — this
-/// ratchets a floor so coverage can only grow, and prints the current count so
-/// the residual (SH-025) is visible.
+/// Step-2 measurement gate (ignored by default): how many corpus files the rss
+/// producer reproduces byte-for-byte. Not full parity yet — this ratchets a floor
+/// so coverage can only grow, asserts the producer never crashes (0 run-failures),
+/// and prints the current count so the residual (SH-025) is visible.
+///
+/// RUNTIME: this compiles the rss producer once and runs it over all ~560 corpus
+/// files on the reg-VM; in a debug build that is slow (minutes). Run it in release
+/// for a quick measurement:
+/// `cargo test -p rsscript --release --lib selfhost_parity::ast_parity_corpus -- --ignored --nocapture`.
+/// The fast inner-loop gate is `ast_parity_samples` (non-ignored, curated subset).
 #[test]
 #[ignore]
 fn ast_parity_corpus() {
@@ -1550,6 +1568,14 @@ fn ast_parity_corpus() {
     for rel in &sample_mismatches {
         eprintln!("[mismatch] {rel}");
     }
+    // The producer must never crash on corpus input — unsupported constructs are
+    // expected to mismatch (partial/`unknown-*` output), not error. A run-failure
+    // is a real regression even if `ok` still clears the floor.
+    assert_eq!(
+        run_failures, 0,
+        "rss AST producer had {run_failures} run-failures over {total} corpus files \
+         (it must degrade to a mismatch, never crash)"
+    );
     assert!(
         ok >= AST_CORPUS_PARITY_FLOOR,
         "AST corpus parity regressed: {ok} byte-exact < floor {AST_CORPUS_PARITY_FLOOR}"

docs/self-hosting-stress-test-plan.md

@@ -280,9 +280,13 @@ likely want a sampled fast inner-loop gate plus the full corpus pre-push.
 recursive-descent rss parser that STREAMS the canonical dump (no handle-based AST is
 materialized). Parity harness: `ast_parity_tiny_sample` + `ast_parity_samples`
 (non-ignored, byte-exact vs the oracle over curated `samples/ast/*`) and
-`ast_parity_corpus` (`#[ignore]`, ratchets a floor over all 563 files). Current
-reach: **121/563 byte-exact, 0 run-failures** (the producer never crashes;
-unsupported constructs mismatch rather than panic). Covered: fns (generics/effects/
+`ast_parity_corpus` (`#[ignore]`, ratchets a floor over all 563 files and asserts
+**0 run-failures** so a producer crash regresses the gate even if the byte-exact
+count still clears the floor). That corpus gate runs the reg-VM over ~560 files and
+is slow in a debug build — run it in `--release` for a quick measurement; the fast
+non-ignored inner-loop gate is `ast_parity_samples`. Current reach: **121/563
+byte-exact, 0 run-failures** (the producer never crashes; unsupported constructs
+mismatch rather than panic). Covered: fns (generics/effects/
 return/body), struct/class/resource (opaque/generics/derives/handle-weak/defaults/
 drop), sum, const/type-alias/module/use, the core statements, and a precedence-exact
 expression parser (calls, field/index, array, try, effects, literals). Both risks are