@sleepy_panda_srl/portulan 0.1.3 → 0.3.0

package/cli/fuzz-shell.mjs

@@ -1,63 +1,6 @@
 #!/usr/bin/env node
 // Grammar-aware fuzzing over this repository's two shell segmenters.
 //
-// Milestone 8, clause (b), second half. The first half — mutation testing over both matchers — is
-// ./mutants.mjs, and the two are separate because a surviving mutant and a grammar bypass are
-// different verdicts with different repairs.
-//
-// ## Why a grammar, and not a string mutator
-//
-// A mutator that flips bytes in `git push --force origin main` has no idea whether the string it
-// produced is still a command bash would run. It can therefore report neither a bypass nor a false
-// red — only a difference, which somebody then has to adjudicate by hand. That is the review round
-// this clause exists to replace.
-//
-// This generator instead COMPOSES a command from a grammar, and so knows by construction where the
-// payload it embedded ended up:
-//
-//   - a **command position** — bash executes the payload. The matcher must answer `true`.
-//   - a **data position** — bash never executes it. The matcher must answer `false`.
-//
-// That is an exact oracle rather than a statistical one, and it is what makes the word
-// *grammar-aware* mean something here.
-//
-// **The declared ground truth is measured, not asserted.** ./fuzz-shell.ground.test.mjs runs every
-// production under real bash with a NEUTRAL payload — `printf ok`, never a gated command — and fails
-// if a production's declared position disagrees with what bash actually did. Every path spelling is
-// verified the same way, by writing to a throwaway file in a temp directory. A hole list is a claim
-// like any other; so is a grammar.
-//
-// ## Two axes, and only one of them is fuzzed
-//
-// **Positions are ENUMERATED and RECORDED.** There are few of them, each has a name a reader can
-// argue with, and each carries the matcher's answer in `EXPECT`. Where that answer is not the one
-// ground truth demands, the entry names the record that documents the divergence — an entry in
-// `../.portulan/gate-map.md`'s honest-holes list, or, for one case, a decision recorded in
-// `./compile.mjs` itself. Both directions are red, exactly as `documented-hole` is in ./goldens.mjs:
-// a recorded escape that starts being caught is good news the record must absorb.
-//
-// **Spellings are FUZZED.** Within one position the generator writes the same semantic command many
-// different ways — quoting form per word, backslash escapes, line continuations, `$'…'`, and for the
-// write payload the path spellings a shell resolves to one file (`./`, `//`, `/./`, `/../`, quoted,
-// escaped). The invariant is exact and it is the one the segmenters exist to provide: **every
-// spelling of one command in one position must get the same answer.** A spelling that answers
-// differently from its cell is the finding, and it is the shape three of #336's ten review rounds
-// had: a reader narrower than a shell word.
-//
-// ## Deterministic, bounded, and reproducible
-//
-// A verify recipe whose verdict moves between runs is not a rail. The generator draws from a seeded
-// PRNG written into this file — no dependency, no `Math.random` — and the recipe pins the seed. The
-// seed is printed on EVERY run, green included, so a green is as reproducible as a red. `--seed` and
-// `--cases` exist for a session hunting deeper than the pinned budget.
-//
-// ## What it never does
-//
-// **It executes nothing.** The payloads are `git push --force origin main` and a constitution write,
-// by design; there is no code path from this module to a subprocess and ./fuzz-shell.test.mjs asserts
-// it imports no process-spawning API. The bash measurement lives in the ground-truth test, uses a
-// neutral payload, and is a separate file for exactly that reason.
-//
 // Exit 0 green · 1 red · 2 could not run.
 
 import fs from "node:fs";
@@ -67,38 +10,19 @@ import { pathToFileURL } from "node:url";
 import { CompileError, matchesRule } from "./compile.mjs";
 import { CouldNotRun, matcherPath, yieldedRules } from "./goldens.mjs";
 
-/** The pinned budget: spellings generated per (position × payload) cell. */
+/** Spellings generated per (position × payload) cell. */
 export const DEFAULT_CASES = 48;
 
-/** The pinned seed. Changing it changes what is generated, so it is a reviewed edit like any other. */
 export const DEFAULT_SEED = 20260825;
 
-/**
- * The payloads: one per matcher, and TWO for the write matcher because it has two recognitions.
- *
- * `./compile.mjs`'s `shellWrites` docblock puts it plainly — *"Two recognitions, both by table: a
- * `>`/`>>` redirection into the path, and a file-writing command that names it"* — and measurement
- * showed the two do not answer alike everywhere: in the `same-line-comment` position the redirection
- * is caught and the named argument is not, because there the segment's head is `ls`. Folded into one
- * payload that cell would answer two ways and the fuzzer's invariant would have to be weakened to
- * admit it. Split, every cell is exact.
- *
- * Every rule named here must exist in the yielded policy or the run refuses — a fuzzer that skipped a
- * payload whose rule it could not find would report a clean sweep of the part it managed to run.
- */
+/** A payload per recognition: a redirected write and a named one can answer differently in one position. */
 export const PAYLOADS = {
     shell: { rule: "force-push-without-a-lease", tool: "Bash", what: "a gated force-push" },
-    "write-redirect": { rule: "edit-the-constitution", tool: "Bash", what: "a redirection into the constitution" },
-    "write-named": { rule: "edit-the-constitution", tool: "Bash", what: "a writer NAMING the constitution" },
+    "write-redirect": { rule: "change-the-constitution", tool: "Bash", what: "a redirection into the constitution" },
+    "write-named": { rule: "change-the-constitution", tool: "Bash", what: "a writer NAMING the constitution" },
 };
 
-/**
- * mulberry32 — a small, fast, well-distributed 32-bit PRNG.
- *
- * Written out rather than imported because this repository installs nothing, and reached for rather
- * than `Math.random` because a fuzzer whose corpus changes every run cannot be a required check: a
- * red nobody can reproduce is a red nobody fixes.
- */
+/** mulberry32, a seeded 32-bit PRNG. */
 export function prng(seed) {
     let a = seed >>> 0;
     return () => {
@@ -112,18 +36,7 @@ export function prng(seed) {
 
 const pick = (rand, xs) => xs[Math.floor(rand() * xs.length) % xs.length];
 
-/**
- * FNV-1a over a string, for deriving one cell's seed from its full identity.
- *
- * **The first cut mixed in `position.id.length` and `kind.length` instead**, which made every cell
- * whose id happened to be the same length share one stream — most of the grammar did, measured on
- * 2026-08-25 — while the comment beside it claimed each cell had its own. A claim broader than the code
- * it describes is this repository's signature defect and this session had already met it three times
- * in other people's code before writing one of its own. The cells stayed correct (each still drew its
- * full budget) and the spelling space collapsed onto far fewer distinct streams than the budget
- * implies, which is a quiet loss of exactly the diversity this axis exists for. Reported by Copilot,
- * round 1 on #338.
- */
+/** 32-bit FNV-1a. */
 export function hash(text) {
     let h = 0x811c9dc5;
     for (let i = 0; i < text.length; i += 1) {
@@ -137,13 +50,7 @@ export function hash(text) {
 // The spelling axis — many ways to write one command
 // =============================================================================================
 
-/**
- * Quote or escape one word without changing what a shell makes of it.
- *
- * `$'…'` reaches `shellWords` with its `$` dropped and is then read as a single-quoted run, so no
- * ANSI-C escape sequence is generated inside one: `$'\x41'` is `A` to bash and `\x41` to the matcher,
- * which would be a generator that lies about its own ground truth rather than a finding.
- */
+/** No escapes inside `$'…'`: the matcher reads it as plain `'…'`, where bash would decode them. */
 export function respell(word, rand) {
     switch (pick(rand, ["bare", "double", "single", "ansi-c", "escape-one", "split-quote"])) {
         case "double":
@@ -153,14 +60,10 @@ export function respell(word, rand) {
         case "ansi-c":
             return `$'${word}'`;
         case "escape-one": {
-            // A backslash before an ordinary character is that character. Chosen at a position rather
-            // than always the first, so the generator explores the word rather than one index of it.
             const i = Math.floor(rand() * word.length);
             return `${word.slice(0, i)}\\${word.slice(i)}`;
         }
         case "split-quote": {
-            // `do"cs"/vision.md` — one word, two quoting regimes. Bash concatenates adjacent quoted
-            // and unquoted runs into a single word, which is the property being tested.
             const i = 1 + Math.floor(rand() * Math.max(1, word.length - 1));
             return `${word.slice(0, i)}"${word.slice(i)}"`;
         }
@@ -169,14 +72,7 @@ export function respell(word, rand) {
     }
 }
 
-/**
- * Spellings of `docs/vision.md` that a shell resolves to the same file.
- *
- * Every one of these must reach the constitution's write gate. They are the "two path spellings" the
- * 2026-07-28 amendment names among the eight bypasses #60 shipped with, generalised: `normalisePath`
- * exists for exactly this list and `./fuzz-shell.ground.test.mjs` writes each one to a throwaway file
- * under a temp directory to prove bash agrees.
- */
+/** Spellings of `target` that a shell resolves to the same file. */
 export function pathSpellings(target) {
     const parts = target.split("/");
     const head = parts.slice(0, -1).join("/");
@@ -186,13 +82,7 @@ export function pathSpellings(target) {
         `./${target}`,
         `${head}/./${tail}`,
         `${head}//${tail}`,
-        // **A `..` hop names the file only where the directory it hops through EXISTS**, because bash
-        // resolves `..` against the real filesystem while `normalisePath` resolves it lexically. That
-        // difference is fail-CLOSED and deliberate — the matcher answers `true` for a hop through a
-        // directory that is not there, which is a false red on a command bash would refuse anyway —
-        // and ./fuzz-shell.ground.test.mjs creates `sibling` before it measures this spelling, so
-        // the claim being measured is the one the list actually makes. Found by that measurement:
-        // the first spelling here hopped through a directory nothing created and bash refused it.
+        // bash resolves `..` against the filesystem, so the ground test creates `sibling` first.
         `${head}/sibling/../${tail}`,
         `./${head}/./${tail}`,
         // A backslash-newline is a line continuation: both characters vanish and the word continues.
@@ -200,18 +90,6 @@ export function pathSpellings(target) {
     ];
 }
 
-/**
- * The writer shapes, split by which of `shellWrites`' TWO recognitions they reach.
- *
- * **The split is structural, not cosmetic, and measurement is what forced it.** That function's own
- * docblock says *"Two recognitions, both by table: a `>`/`>>` redirection into the path, and a
- * file-writing command that names it"* — and the two do not answer alike in every position, because a
- * redirection is read off the whole segment while a named argument needs the segment's HEAD to be a
- * writer. In the `same-line-comment` position they diverge outright: `ls # echo ok > docs/vision.md`
- * is caught, `ls # cp /tmp/x docs/vision.md` is not, because there the head is `ls`. Keyed as one
- * payload the cell would answer two ways and the invariant would have to be weakened to admit it;
- * keyed as two, each cell is exact and the divergence becomes a recorded fact.
- */
 export const WRITERS = {
     "write-redirect": [(p) => `echo ok > ${p}`, (p) => `echo ok >> ${p}`, (p) => `cat /tmp/x > ${p}`, (p) => `printf ok 1> ${p}`],
     "write-named": [
@@ -225,25 +103,14 @@ export const WRITERS = {
     ],
 };
 
-/** One spelling of the write payload: a writer shape, a path spelling, and quoting over both. */
 export function writePayload(rand, kind, target = "docs/vision.md") {
     const spelling = pick(rand, pathSpellings(target));
-    // A line continuation must not be quoted — inside `"…"` a backslash-newline is still a
-    // continuation, but inside `'…'` it is two literal characters and the word stops being the path.
-    // Generating that would be the generator lying about its own ground truth.
+    // Never requote a continuation: inside `'…'` a backslash-newline is two literal characters.
     const quoted = spelling.includes("\\\n") ? spelling : respell(spelling, rand);
     return pick(rand, WRITERS[kind])(quoted);
 }
 
-/**
- * One spelling of the shell payload.
- *
- * **The gated prefix stays literal, and that is a property of the ORACLE rather than a convenience.**
- * `git push --force` is a command *prefix* and both the compiled permission rule and this matcher
- * compare it literally, so `"git" push --force …` is a spelling no layer claims to catch — hole 1's
- * "spellings neither layer sees". Generating it would produce a finding the gate map already answers.
- * Only the arguments after the prefix are respelt.
- */
+/** Only the arguments are respelt: the prefix is matched literally, and the gate map records that hole. */
 export function shellPayload(rand, target = "git push --force") {
     const args = pick(rand, [[], ["origin", "main"], ["origin", "HEAD"], ["--repo", "o/r"], ["origin", "main", "--quiet"]]);
     return [target, ...args.map((a) => respell(a, rand))].join(" ");
@@ -253,14 +120,7 @@ export function shellPayload(rand, target = "git push --force") {
 // The position axis — enumerated, recorded, and measured under bash
 // =============================================================================================
 
-/**
- * Where the payload sits, and whether bash runs it there.
- *
- * `bashSafe: false` marks a production ./fuzz-shell.ground.test.mjs must not execute even with a
- * neutral payload — `sudo` would prompt for a password on a developer's machine and hang a test
- * suite. Its ground truth is argued in `why` instead of measured, and saying which of the two a
- * production got is the point of the flag.
- */
+/** Where the payload sits: bash executes it in a `command` ground and never in a `data` one. */
 export const POSITIONS = [
     { id: "bare", ground: "command", build: (p) => p },
     { id: "after-semicolon", ground: "command", build: (p) => `ls; ${p}` },
@@ -284,69 +144,16 @@ export const POSITIONS = [
         build: (p) => `sudo ${p}`,
     },
     { id: "leading-redirection", ground: "command", build: (p) => `2> /dev/null ${p}` },
-    // ------------------------------------------------------------------------------------------
-    // **The redirection-TARGET family — session-open adjustment 4, and the class #336 met three
-    // times.** A shell word may hold spaces when it is quoted or escaped, and `LEADING_REDIRECTION`
-    // must consume the whole word or the command behind it escapes ungated. That defect shipped
-    // twice on #336 and was fixed twice at the spelling that was quoted, until the suite stopped
-    // asserting spellings and asserted the rule against `shellWords`. These productions put the same
-    // rule in front of the generator, so a fourth sibling reds here rather than in a review.
-    //
-    // Every one is a COMMAND position: bash redirects stderr to a file and then runs the payload.
     { id: "leading-redirection-quoted-target", ground: "command", build: (p) => `2> "log file.txt" ${p}` },
     { id: "leading-redirection-single-quoted-target", ground: "command", build: (p) => `2> 'log file.txt' ${p}` },
     { id: "leading-redirection-escaped-space-target", ground: "command", build: (p) => `2> log\\ file.txt ${p}` },
     { id: "leading-redirection-escaped-quote-target", ground: "command", build: (p) => `2> "log \\"q\\" file.txt" ${p}` },
-    // ------------------------------------------------------------------------------------------
-    // **A CRLF continuation, which is NOT a continuation.** `shellWords` consumes `\r\n` after a
-    // backslash as a pair and joins the word; **five shells do not, and split the command instead** —
-    // `bash 3.2.57(1)` (arm64-apple-darwin25), `bash 5.2.15(1)` (aarch64-unknown-linux-gnu) and
-    // `bash 5.2.37(1)` (x86_64-pc-linux-gnu), plus `zsh 5.9` and **the measured host's `/bin/sh`**, which
-    // on that macOS host is bash 3.2.57 in POSIX mode — `dash` and `busybox`, the common `/bin/sh` on
-    // Linux, were NOT measured.
-    // The three bash builds are named in full rather than as "bash 5", which would be a claim from two 5.2
-    // patchlevels; no bash 4.x was measured, and neither was any Windows-side bash — git-bash, MSYS2,
-    // Cygwin or WSL — which is the platform the retired reachability claim named. Widened 2026-08-25
-    // from "three shells on this machine", which was the true width until two containers were run.
-    //
-    // **What follows from that is NOT one answer, and an earlier draft of this very comment said it
-    // was.** It read "the matcher answers `true` anyway: a FALSE RED", which is right for one payload
-    // and wrong for another:
-    //
-    //   - `shell` — nothing gated runs. The matcher answers `false`. Correct.
-    //   - `write-named` — the intended write never runs and the target is untouched. The matcher
-    //     answers `true`. (`cp` ITSELF does run, on the fragment before the split, and fails on a
-    //     malformed `\r` argument — the sibling of the cell below, corrected in the same pass after
-    //     shipping the fix to one carrier and not the other. Copilot, round 3 on #342.)
-    //     A false red, fail-closed, and the only one of the three.
-    //   - `write-redirect` — a shell applies a redirection BEFORE it looks the command up, so the
-    //     clobbering redirection on the surviving fragment still fires and TRUNCATES the target to
-    //     zero bytes. The matcher answering `true` is a **true positive**. Measured.
-    //
-    // So the ground truth here is a property of the payload rather than of the position, which is why
-    // `groundByKind` exists and why this is the only production that uses it. `exitsNonZero` is
-    // declared because the fragment left over by the split is run as a command and is not found.
-    //
-    // _The stale sentence survived the correction of the three cells below it — one carrier fixed and
-    // its sibling left, in the block whose subject is that class. Reported by Copilot, round 2 on #341._
+    // `shellWords` joins a backslash-CRLF; bash 3.2.57, 5.2.15 and 5.2.37 and zsh 5.9 split there.
     {
         id: "crlf-continuation-in-the-payload",
         ground: "data",
-        // **The one production whose ground truth is not a property of the position.** bash splits at
-        // the CRLF, so the intended write never runs and a gated command never runs — data. But a
-        // CLOBBERING redirection is applied before the command is looked up, so it fires anyway and
-        // truncates its target to zero bytes. That is the gated effect occurring, and calling it data
-        // would record a destroyed file as an untouched one — which an earlier draft of this entry did,
-        // in all three of its carriers, until the pre-commit checkpoint measured it.
         groundByKind: { "write-redirect": "command" },
-        // `>>` appends and therefore does NOT truncate, so it is the one redirect shape whose ground
-        // truth differs from its siblings'. Refused rather than folded in: a cell whose ground truth
-        // varies with the spelling is a cell whose invariant cannot hold. Measured — `echo \<CRLF>ok >> t`
-        // leaves `t` byte-for-byte unchanged while `> t` and `1> t` leave it empty. Re-measured
-        // 2026-08-25 on bash 5.2.15 and 5.2.37 as well as 3.2.57: identical on all three, so the
-        // refusal is right on **both bash 5.2 builds measured** and not only on the shell it was
-        // written against. Named as builds rather than as "bash 5", which would be the series
-        // inference this production's own comment refuses eight lines up.
+        // `>>` appends rather than truncates, so its ground differs from its siblings' and it is refused.
         carries: (p, kind) => kind !== "write-redirect" || !p.includes(">>"),
         exitsNonZero: true,
         why: "bash splits at the CRLF, so the fragment after it is run as a command and is not found — a non-zero exit is the measurement rather than a failure of it. A clobbering redirection on that fragment still fires, which is why `write-redirect` overrides the ground.",
@@ -360,14 +167,7 @@ export const POSITIONS = [
     {
         id: "wrapper-single-quoted",
         ground: "command",
-        // **A single-quoted wrapper cannot carry a payload holding a `'`**, and this predicate is
-        // here because bash said so. POSIX gives `'…'` no escapes, so `sh -c 'cp /tmp/x $'docs/vision.md''`
-        // closes the wrapper at the payload's own quote and the inner shell then reads
-        // `cp /tmp/x $docs/vision.md` — which writes `/vision.md`, NOT the constitution. The cell
-        // records `true` and bash would not have touched the file: a generator composing a command it
-        // no longer has ground truth for, which is the one failure this whole design is arranged
-        // against. Measured by ./fuzz-shell.ground.test.mjs's wrapper-respelling case, added at the
-        // pre-commit checkpoint after it named this composition as argued-but-unmeasured.
+        // POSIX `'…'` has no escapes, so a payload holding `'` would close the wrapper early.
         carries: (p) => !p.includes("'"),
         build: (p) => `sh -c '${p}'`,
     },
@@ -377,7 +177,6 @@ export const POSITIONS = [
     {
         id: "nested-wrapper",
         ground: "command",
-        // The same limit, for the same reason: the inner wrapper here is single-quoted too.
         carries: (p) => !p.includes("'"),
         build: (p) => `bash -c "sh -c '${p}'"`,
     },
@@ -386,29 +185,10 @@ export const POSITIONS = [
     { id: "heredoc-body", ground: "data", build: (p) => `cat <<'EOF'\n${p}\nEOF` },
     { id: "same-line-comment", ground: "data", build: (p) => `ls # ${p}` },
     { id: "comment-then-separator", ground: "data", build: (p) => `echo ok #; ${p}` },
-    // Added at the pre-commit checkpoint. Its differential of the staged matcher against HEAD's found
-    // that the 2026-08-25 widening inherits the `#` decision one level INTO a wrapper — a new false
-    // red, and the only new false-red class the repair produced. `comment-then-separator` pins the
-    // top-level spelling and could not see the composed one, which is the "two claims that each held
-    // and did not compose" shape this whole session is about, met once more in the fix for it.
     { id: "wrapper-holding-comment", ground: "data", build: (p) => `bash -c "echo ok #; ${p}"` },
 ];
 
-/**
- * What the matcher answers for each cell, and the record that licenses a disagreement with ground
- * truth.
- *
- * **Every entry here was MEASURED against the shipped matcher before it was written, and one round of
- * writing it from the armchair was thrown away first.** Milestone 8 session 0's founding result is
- * ten hand-written expectations refuted on the corpus's first run; an expectation table is a claim
- * like any other and this one is not exempt.
- *
- * `answer` is what `matchesRule` returns. `record` is required whenever `answer` disagrees with what
- * the production's `ground` demands, and it may cite either the gate map's honest-holes list or a
- * decision recorded in `./compile.mjs` — the false red on `#` is the second kind, argued at
- * `commandSegments` and declined on a Copilot review of #60, and it appears in no hole list because
- * it is a choice rather than a gap.
- */
+/** The matcher's measured answer per cell; one that differs from ground truth names its `record`. */
 export const EXPECT = {
     "leading-redirection-quoted-target|shell": { answer: true },
     "leading-redirection-quoted-target|write-redirect": { answer: true },
@@ -616,51 +396,15 @@ export const EXPECT = {
     },
 };
 
-/** The answer ground truth demands, before any record is consulted. */
 export const correctFor = (ground) => ground === "command";
 
-/**
- * What "the payload took effect" MEANS, per payload kind.
- *
- * **A redirection is not a command, and conflating the two hid a true positive as a false red.** A
- * shell applies a redirection BEFORE it looks the command up, so a `>` whose command never runs still
- * truncates its target to zero bytes. For a `write-redirect` payload the gated effect is therefore
- * *the target was written*, not *the command ran* — and measuring it as the latter reports a
- * destroyed file as an untouched one. Measured on bash 3.2.57: a split `printf … 1> target` leaves
- * the target at **0 bytes** where it held content before.
- */
+/** How a payload shows its effect: a redirection truncates its target even when its command never runs. */
 export const EFFECT = { shell: "ran", "write-redirect": "touched", "write-named": "ran" };
 
-/**
- * The ground truth for one cell, which is not always a property of the position alone.
- *
- * Most productions put the payload somewhere bash either runs or does not, whatever the payload is.
- * One does not: a CRLF splits the command, and what survives depends on the payload's SHAPE — a
- * clobbering redirection still fires and destroys the target, while a writer command simply never
- * runs. A single `ground` field cannot say that, so a production may override it per kind. The
- * override is rare by design and every use of it is argued in the production's own `why`.
- */
 export const groundFor = (position, kind) => position.groundByKind?.[kind] ?? position.ground;
 
-/**
- * The ACTION kind a payload kind reaches.
- *
- * Three payload kinds, two action kinds: the write matcher's two recognitions are separate payloads
- * here (see `WRITERS`) and one rule kind there. Anything that hands a payload kind to a consumer
- * expecting an action kind is a bug, and one shipped — see `asCase`.
- */
 export const ruleKind = (kind) => (kind === "shell" ? "shell" : "write");
 
-/**
- * Generate one case: a spelling of one payload in one position.
- *
- * **A position may REFUSE a payload it cannot carry, and the refusal is a redraw rather than a
- * skip.** A single-quoted wrapper holding a `'`-quoted word is not the command it looks like, so
- * emitting one would give the fuzzer an exact answer about a string whose ground truth it no longer
- * knows. Bounded, and a budget that runs out throws rather than returning something unchecked: a
- * generator that quietly gave up would thin the spelling space in exactly the cell whose quoting is
- * hardest, which is the cell that most needs the coverage.
- */
 export function generate(position, kind, rand) {
     const carries = position.carries ?? (() => true);
     for (let attempt = 0; attempt < 64; attempt += 1) {
@@ -674,28 +418,12 @@ export function generate(position, kind, rand) {
     );
 }
 
-/**
- * A finding, rendered as a corpus case ready to paste into evals/goldens/gates/<rule-id>.json.
- *
- * `../evals/README.md` records that clause (a)'s fixture format is clause (b)'s output shape, so a
- * bypass found here becomes a permanent regression pin by paste rather than by retyping. The `expect`
- * written is what the MATCHER ACTUALLY DID — a fixture records behaviour, and the repair belongs in
- * the matcher or in the record, never in a fixture that asserts what somebody wished had happened.
- */
+/** A finding as a case to paste into `evals/goldens/gates/<rule-id>.json`, expecting what the matcher did. */
 export function asCase(position, kind, ruleId, command, actual, index) {
     return {
         id: `fuzz-${position.id}-${kind}-${index}`,
         class: correctFor(groundFor(position, kind)) === actual ? "holds" : "documented-hole",
         tool: PAYLOADS[kind].tool,
-        // **The RULE kind, not the payload kind.** `matcherPath` reads an action kind — `shell` /
-        // `write` / `read` — and this passed it `write-redirect` and `write-named`, which it knows
-        // nothing about, so it fell through to `no-branch` and two of the three payloads emitted a
-        // case `goldens` would refuse as a mislabel. The paste-ready promise this module and
-        // `../evals/README.md` both make was therefore FALSE for the write matcher, which is
-        // `../.portulan/dod.md` condition 4 rather than a preference. Reported by Copilot on #338;
-        // it survived a drill that printed a finding, because the drill exercised the shell payload —
-        // a check written alongside a change inheriting the change's blind spot, for the fifth time
-        // in two sessions.
         path: matcherPath(ruleKind(kind), PAYLOADS[kind].tool),
         expect: actual,
         why: `Generated by cli/fuzz-shell.mjs: ${PAYLOADS[kind].what} in the \`${position.id}\` position, which is a ${groundFor(position, kind)} position for this payload. REVIEW THIS BEFORE COMMITTING IT — a generated case records what the matcher did, not what it should do.`,
@@ -740,8 +468,6 @@ export function run(argv = [], { stdout = process.stdout, stderr = process.stder
                 const flag = argv[i];
                 const raw = argv[i + 1];
                 i += 1;
-                // Refused rather than coerced. `Number("12abc")` is NaN and `Number("")` is 0, and a
-                // fuzzer silently running zero cases is the false green this whole file is against.
                 if (raw === undefined || !/^[0-9]+$/.test(raw)) throw new CouldNotRun(`${flag} needs a non-negative integer, not ${JSON.stringify(raw)}`);
                 const value = Number(raw);
                 if (flag === "--cases" && value === 0) throw new CouldNotRun("--cases 0 would generate nothing and report green having tested nothing");
@@ -766,9 +492,6 @@ export function run(argv = [], { stdout = process.stdout, stderr = process.stder
         for (const u of unresolved) say(`pack    ${u.name} UNRESOLVED — ${u.why}; its gate fragments are not in this run`);
         const byId = new Map(rules.map((r) => [r.id, r]));
 
-        // **A payload whose rule is absent is could-not-run, never a skip.** A fuzzer that quietly
-        // ran one of its two matchers would print a green about half the subject the clause names —
-        // ../.portulan/memory/a-checker-must-refuse-what-it-cannot-check.md.
         for (const [kind, p] of Object.entries(PAYLOADS)) {
             if (!byId.has(p.rule)) {
                 throw new CouldNotRun(
@@ -777,9 +500,6 @@ export function run(argv = [], { stdout = process.stdout, stderr = process.stder
                 );
             }
         }
-        // The table must be total over the grammar, in both directions, and this is checked before a
-        // case is generated: a position with no recorded answer would otherwise be silently skipped,
-        // and a recorded answer for a position nobody generates is a claim about nothing.
         const keys = new Set(Object.keys(EXPECT));
         const missing = [];
         for (const position of POSITIONS) {
@@ -812,11 +532,7 @@ export function run(argv = [], { stdout = process.stdout, stderr = process.stder
             for (const [kind, p] of Object.entries(PAYLOADS)) {
                 const expected = EXPECT[`${position.id}|${kind}`];
                 const rule = byId.get(p.rule);
-                // Per cell, and derived from the cell's FULL identity. Two properties, both wanted:
-                // one cell's budget cannot shift another cell's stream — a case-count change would
-                // otherwise re-roll every later cell and turn one edit into a new corpus — and no two
-                // cells share a stream, so the spelling space is explored once per cell rather than
-                // once per id length. See `hash` for what the first cut got wrong.
+                // Seeded per cell from its full identity, so one cell's budget never re-rolls another's.
                 const rand = prng(seed ^ hash(`${position.id}|${kind}`));
                 for (let i = 0; i < cases; i += 1) {
                     const { command } = generate(position, kind, rand);
@@ -864,8 +580,7 @@ export function run(argv = [], { stdout = process.stdout, stderr = process.stder
     }
 }
 
-// The entry guard, in the ONE form `./rule-carriers.mjs` designates — see ./goldens.mjs for why it is
-// copied rather than re-derived.
+// Compared as URLs so a space in the path still matches, and through realpath for a symlinked launch.
 function isMain() {
     const invoked = process.argv[1];
     if (!invoked) return false;