mandrel-platform 1.13.0 → 1.13.1

package/scripts/check-husky-hook-modes.test.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+/**
+ * check-husky-hook-modes.test.mjs — regression guard for the mode bit that
+ * decides whether this repository's git hooks run at all.
+ *
+ * The bug this pins: `.husky/pre-commit` was tracked at mode 100644. Git
+ * 2.36+ refuses to execute a hook that is not marked executable, and the way
+ * it refuses is the problem — it prints
+ *
+ *     hint: The '.../.husky/pre-commit' hook was ignored because it's not
+ *           set as executable.
+ *
+ * to stderr and then lets the commit SUCCEED with exit 0. So the quality gate
+ * the hook exists to run (`quality-preview.js`, which blocks MI/CRAP drift at
+ * commit time) never ran for anybody, in any clone, from the day it was
+ * added — and nothing anywhere went red to say so. An inert gate and a
+ * passing gate are indistinguishable from the outside.
+ *
+ * Why the mode is asserted against the INDEX and not the filesystem. `chmod`
+ * on the working copy is not the fix and would not be caught here: git stores
+ * only two file modes, 100644 and 100755, and it is the tracked one that
+ * every fresh clone and every `git checkout` materializes. A working tree can
+ * be executable while the committed mode is not (and vice versa), so a
+ * `statSync` check would go green on the maintainer's machine and ship the
+ * defect to everyone else. `git ls-files -s` reads the index, which is the
+ * mode that actually propagates.
+ *
+ * Why this is not a one-line assertion on one path. The upstream cause is
+ * still live: the hook is installed by the vendored bootstrap
+ * (`.agents/scripts/lib/bootstrap/quality-bootstrap.js`) with a bare
+ * `fs.writeFileSync` and no `chmod`, so a hook file CREATED by a fresh
+ * bootstrap run is born 0644. (An existing file survives — `writeFileSync`
+ * truncates in place and preserves the mode — which is why fixing the tracked
+ * mode holds.) `.agents/**` is vendored payload re-materialized from the
+ * mandrel package, so that cause cannot be fixed here; this guard is the
+ * compensating control, and it therefore covers every hook the directory may
+ * grow, not just the one that was broken.
+ *
+ * Run: node --test scripts/check-husky-hook-modes.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { execFileSync } from "node:child_process";
+
+const HOOKS_DIR = ".husky";
+const EXECUTABLE = "100755";
+
+/**
+ * Every client-side hook name git will invoke. A file in `.husky/` whose name
+ * is not on this list is never run by git no matter what its mode is, so a
+ * typo (`pre_commit`, `precommit`) is the same silent no-op as a missing
+ * executable bit and is asserted against below.
+ *
+ * Source: `githooks(5)`, client-side hooks only — server-side hooks
+ * (`pre-receive`, `update`, `post-receive`) cannot fire from a clone.
+ */
+const GIT_CLIENT_HOOKS = new Set([
+  "applypatch-msg",
+  "pre-applypatch",
+  "post-applypatch",
+  "pre-commit",
+  "pre-merge-commit",
+  "prepare-commit-msg",
+  "commit-msg",
+  "post-commit",
+  "pre-rebase",
+  "post-checkout",
+  "post-merge",
+  "pre-push",
+  "pre-auto-gc",
+  "post-rewrite",
+  "sendemail-validate",
+  "post-index-change",
+  "reference-transaction",
+  "push-to-checkout",
+]);
+
+/**
+ * Tracked entries directly under `.husky/`, as `{ mode, path, name }`.
+ *
+ * `git ls-files -s` emits `<mode> <object> <stage>\t<path>`. Husky's own
+ * `_/` shim directory and dotfiles (`.gitignore`) are not hooks and are
+ * excluded; everything else in the directory is one by convention.
+ */
+function trackedHooks() {
+  const out = execFileSync("git", ["ls-files", "-s", "--", HOOKS_DIR], {
+    encoding: "utf8",
+  });
+
+  return out
+    .split("\n")
+    .filter((line) => line.length > 0)
+    .map((line) => {
+      const [meta, path] = line.split("\t");
+      return { mode: meta.split(" ")[0], path, name: path.slice(HOOKS_DIR.length + 1) };
+    })
+    .filter(({ name }) => !name.startsWith(".") && !name.startsWith("_/"));
+}
+
+test("the quality-gate pre-commit hook is still tracked", () => {
+  // Without this the mode assertion below passes vacuously the moment the
+  // hook is deleted — which is the same outcome (no gate) by another route.
+  const names = trackedHooks().map((h) => h.name);
+  assert.ok(
+    names.includes("pre-commit"),
+    `${HOOKS_DIR}/pre-commit is not tracked; the commit-time quality gate would not run. Tracked: ${names.join(", ") || "(none)"}`,
+  );
+});
+
+test("every tracked hook under .husky/ is executable in the index", () => {
+  const hooks = trackedHooks();
+  assert.ok(hooks.length > 0, `no tracked hooks found under ${HOOKS_DIR}/`);
+
+  const nonExecutable = hooks.filter((h) => h.mode !== EXECUTABLE);
+  assert.deepEqual(
+    nonExecutable.map((h) => `${h.path} (${h.mode})`),
+    [],
+    `git 2.36+ silently IGNORES a non-executable hook and lets the commit succeed with exit 0. ` +
+      `Fix the tracked mode with: git update-index --chmod=+x <path>  (a bare chmod does not change it).`,
+  );
+});
+
+test("every tracked hook under .husky/ has a name git will actually invoke", () => {
+  const unknown = trackedHooks()
+    .map((h) => h.name)
+    .filter((name) => !GIT_CLIENT_HOOKS.has(name));
+
+  assert.deepEqual(
+    unknown,
+    [],
+    `git invokes hooks by exact filename; a name outside githooks(5) never runs, as silently as a non-executable one.`,
+  );
+});

package/scripts/check-runner-runs-on.test.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
- * check-runner-runs-on.test.mjs — regression guard for the `runner` input's
- * two documented shapes (Story #421).
+ * check-runner-runs-on.test.mjs — regression guard for every shape the
+ * `runner` input can arrive in (Stories #421, #493).
  *
  * The bug this pins: every `runs-on:` site consumed the input raw as
  * `${{ inputs.runner }}`. GitHub does not parse a JSON-array *string* in that
@@ -21,6 +21,25 @@
  * expression from the workflow and EVALUATES it under Actions semantics, the
  * same read-then-execute approach as check-toolchain-cache-default.test.mjs.
  *
+ * The same failure had a second door, closed by #493: `runner: ''`. A
+ * workflow_call `default:` fires only when the key is ABSENT, so a caller
+ * who passes the key with an empty value — threading an unset input or a
+ * matrix value through — got the label `""` rather than `ubuntu-latest`, and
+ * with it the identical never-scheduled job. The fallback therefore lives at
+ * the `runs-on` site, and the byte-identical assertion below is what stops a
+ * fix that reaches six of the seven workflows from shipping as if it reached
+ * all seven.
+ *
+ * Story #493 also left a downstream door open, closed here: `runs-on` was not
+ * the only site reading `inputs.runner`. `pr-quality.yml`'s harden-runner
+ * egress-audit step gates on `startsWith(inputs.runner, 'ubuntu-')`, which was
+ * unreachable-but-consistent while `runner: ''` never scheduled a job. Once the
+ * empty value resolved to the hosted default, the job ran on ubuntu-latest
+ * while the gate read the raw `''` and skipped — a SECURITY step opting itself
+ * out with nothing red to show for it. So the gate is asserted the same way:
+ * extracted and EVALUATED, and required to AGREE with what `runs-on` resolves
+ * to for the same input.
+ *
  * Run: node --test scripts/check-runner-runs-on.test.mjs
  */
 
@@ -28,6 +47,7 @@ import assert from "node:assert/strict";
 import { test } from "node:test";
 import { readFileSync, readdirSync } from "node:fs";
 import { evaluate } from "./lib/actions-expression.mjs";
+import { stepByName } from "./lib/yaml-step.mjs";
 
 const WORKFLOW_DIR = ".github/workflows";
 
@@ -58,6 +78,28 @@ function runsOnExpressions(text) {
   return out;
 }
 
+/**
+ * The `default:` this workflow declares for its `runner` workflow_call input.
+ *
+ * Read from the YAML rather than hardcoded so the empty-input assertion below
+ * pins the real contract: whatever label a caller gets by omitting `runner`
+ * is the label an explicitly-empty `runner` must get too. Scanned line by
+ * line — the block boundary is indentation, and a dynamically-constructed
+ * regex is a SAST finding that buys nothing here.
+ */
+function declaredRunnerDefault(text) {
+  const lines = text.split("\n");
+  const start = lines.indexOf("      runner:");
+  assert.notEqual(start, -1, "no `runner:` workflow_call input found");
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() !== "" && !line.startsWith("        ")) break;
+    const m = line.match(/^\s+default:\s*'([^']*)'\s*$/);
+    if (m) return m[1];
+  }
+  return assert.fail("the `runner` input declares no `default:` to fall back to");
+}
+
 const WORKFLOWS = runnerWorkflows();
 
 test("every workflow taking a `runner` input is covered by this guard", () => {
@@ -127,6 +169,38 @@ for (const { file, text } of WORKFLOWS) {
     }
   });
 
+  test(`${file}: an empty runner resolves to this workflow's documented default`, () => {
+    // The silent-queue shape #421 left behind. `runner: ''` is not exotic — a
+    // caller threading `runner: ${{ inputs.runner }}` or a matrix value that
+    // resolves to nothing passes it without meaning to, and `format('"{0}"',
+    // '')` yielded the label `""`. An empty label matches no runner, so the
+    // job sat `queued` with no logs and no red, exactly as the JSON-array
+    // string did. The fallback belongs at the `runs-on` site because the
+    // input `default:` only fires when the key is ABSENT, never when it is
+    // present and empty.
+    const fallback = declaredRunnerDefault(text);
+    assert.notEqual(fallback, "", `${file}: the declared default is itself empty`);
+    for (const { line, expr } of sites) {
+      const resolved = evaluate(expr, { runner: "" });
+      assert.equal(
+        typeof resolved,
+        "string",
+        `${file}:${line}: an empty runner must resolve to a single label, not ${JSON.stringify(resolved)}`,
+      );
+      assert.notEqual(
+        resolved,
+        "",
+        `${file}:${line}: an empty runner resolves to an empty label — no runner ` +
+          `carries it, so the job queues until the 24-hour timeout with nothing to read`,
+      );
+      assert.equal(
+        resolved,
+        fallback,
+        `${file}:${line}: an empty runner must land on the input's documented default`,
+      );
+    }
+  });
+
   test(`${file}: every runs-on site resolves identically`, () => {
     // One workflow must not drift into two dialects of the same decision.
     const rendered = sites.map(({ expr }) =>
@@ -136,6 +210,25 @@ for (const { file, text } of WORKFLOWS) {
   });
 }
 
+
+test("every runs-on expression across the seven workflows is byte-identical", () => {
+  // The per-workflow tests above each score one file, so a fix applied to six
+  // of the seven passes every one of them and ships the seventh still broken.
+  // This is the assertion a partial edit cannot survive: one decision, spelled
+  // one way, everywhere it is made.
+  const distinct = new Map();
+  for (const { file, text } of WORKFLOWS) {
+    for (const { line, expr } of runsOnExpressions(text)) {
+      if (!distinct.has(expr)) distinct.set(expr, []);
+      distinct.get(expr).push(`${file}:${line}`);
+    }
+  }
+  const report = [...distinct.entries()]
+    .map(([expr, at]) => `${expr}  @ ${at.join(", ")}`)
+    .join("\n  ");
+  assert.equal(distinct.size, 1, `runs-on expressions have drifted apart:\n  ${report}`);
+});
+
 test("the documented array form resolves AND derives toolchain-cache 'false'", () => {
   // The coupling the gap report found: before this fix the only `runner` value
   // that derived the correct cache posture was the one that never reached a
@@ -152,3 +245,131 @@ test("the documented array form resolves AND derives toolchain-cache 'false'", (
   assert.ok(cache, "no `cache: ${{ … }}` value found at the setup-toolchain call site");
   assert.equal(evaluate(cache[1].trim(), { runner, "toolchain-cache": "auto" }), "false");
 });
+
+// ---------------------------------------------------------------------------
+// The harden-runner egress-audit gate (`pr-quality.yml`)
+//
+// `runs-on` was not the only expression reading `inputs.runner`. Anything that
+// branches on the runner class has to resolve the input the SAME way, or the
+// job and the step disagree about which machine they are on. This section
+// pins that agreement behaviourally — extract the real `if:` and run it.
+// ---------------------------------------------------------------------------
+
+/**
+ * The `${{ … }}` body of the harden-runner step's `if:` gate.
+ *
+ * Keyed off the step, not off a line pattern that happens to contain
+ * `startsWith` — the point is to score whatever expression actually guards
+ * that step, including one a future edit spells differently.
+ */
+function hardenRunnerGate(text) {
+  const block = stepByName(text, "Harden runner (egress audit)");
+  assert.match(
+    block,
+    /uses: step-security\/harden-runner@/,
+    "the extracted block is not the harden-runner step",
+  );
+  const m = block.match(/^\s*if:\s*\$\{\{(.+)\}\}\s*$/m);
+  assert.ok(m, "the harden-runner step has no single-expression `if:` gate to score");
+  return m[1].trim();
+}
+
+/**
+ * What `runs-on` resolves to for `runner`, as a hosted-ubuntu predicate.
+ *
+ * A single string label starting with `ubuntu-` is a GitHub-hosted ubuntu
+ * image — the one environment where harden-runner installs its own monitor.
+ * An ARRAY (the documented self-hosted form) is not, regardless of the labels
+ * inside it: harden-runner ships its agent in a self-hosted runner image, so
+ * the step is correctly a no-op there.
+ */
+function resolvesToHostedUbuntu(runsOnExpr, runner) {
+  const resolved = evaluate(runsOnExpr, { runner });
+  return typeof resolved === "string" && resolved.startsWith("ubuntu-");
+}
+
+const QUALITY_FILE = `${WORKFLOW_DIR}/pr-quality.yml`;
+const QUALITY_TEXT = readFileSync(QUALITY_FILE, "utf8");
+
+test("pr-quality.yml: the harden-runner gate reaches every tier through one anchor", () => {
+  // The gate is written once (`&harden-runner`) and aliased into the other
+  // tiers. A second literal copy could carry a stale expression that every
+  // behavioural assertion below would miss, because they score the anchor.
+  assert.match(QUALITY_TEXT, /^ {6}- &harden-runner$/m, "the harden-runner anchor is missing");
+  assert.ok(
+    (QUALITY_TEXT.match(/^ {6}- \*harden-runner$/gm) ?? []).length > 0,
+    "expected the harden-runner anchor to be aliased into the other tiers",
+  );
+  assert.equal(
+    (QUALITY_TEXT.match(/uses: step-security\/harden-runner@/g) ?? []).length,
+    1,
+    "expected exactly one harden-runner step — a second one would bypass the anchor",
+  );
+});
+
+test("pr-quality.yml: an empty runner keeps the egress audit ON", () => {
+  // The regression. `runner: ''` resolves to the hosted ubuntu-latest default
+  // at `runs-on` (#493), so the job DOES run on a GitHub-hosted machine — but
+  // a gate reading the raw input saw `startsWith('', 'ubuntu-')` → false and
+  // skipped. Nothing goes red when a step is skipped, so the egress baseline
+  // silently disappears for exactly the callers who never asked to opt out.
+  const gate = hardenRunnerGate(QUALITY_TEXT);
+  assert.equal(
+    evaluate(gate, { runner: "", "enable-harden-runner": true }),
+    true,
+    "an empty runner lands on hosted ubuntu-latest, so the egress audit must run there",
+  );
+});
+
+test("pr-quality.yml: the gate agrees with what runs-on resolves to", () => {
+  // The real contract, and the one that survives a respelling of either
+  // expression: the step runs precisely when the job is on a hosted ubuntu
+  // image. Scoring both sides against the same input is what makes a future
+  // change to one of them fail here instead of shipping a silent divergence.
+  const gate = hardenRunnerGate(QUALITY_TEXT);
+  const [runsOn] = runsOnExpressions(QUALITY_TEXT);
+  for (const runner of [
+    "",
+    "ubuntu-latest",
+    "ubuntu-24.04",
+    "ubuntu-22.04",
+    "ubuntu-latest-8-cores",
+    "macos-14",
+    "windows-latest",
+    '["self-hosted","beestera-runner"]',
+    '["ubuntu-latest"]',
+  ]) {
+    assert.equal(
+      evaluate(gate, { runner, "enable-harden-runner": true }),
+      resolvesToHostedUbuntu(runsOn.expr, runner),
+      `runner ${JSON.stringify(runner)}: the gate and the resolved runs-on disagree ` +
+        `about whether this job is on a GitHub-hosted ubuntu image`,
+    );
+  }
+});
+
+test("pr-quality.yml: `enable-harden-runner: false` still opts out everywhere", () => {
+  // The documented escape hatch. A fallback added to the runner half of the
+  // gate must not make the boolean half unreachable — `false && …` yields
+  // `false`, but only if the operands stayed in that order.
+  const gate = hardenRunnerGate(QUALITY_TEXT);
+  for (const runner of ["", "ubuntu-latest", "ubuntu-24.04", '["self-hosted","x"]']) {
+    assert.equal(
+      evaluate(gate, { runner, "enable-harden-runner": false }),
+      false,
+      `runner ${JSON.stringify(runner)}: opting out must win regardless of the runner`,
+    );
+  }
+});
+
+test("pr-quality.yml: the toolchain-cache derivation reads an empty runner as hosted", () => {
+  // The sibling `inputs.runner` reader, checked rather than assumed. It is
+  // correct as written for `runner: ''` — but only incidentally, because
+  // `contains('', 'self-hosted')` is false and the derivation is
+  // self-hosted-side. Pinning it here means a future inversion to a
+  // hosted-side test (`contains(runner, 'ubuntu')`) trips instead of quietly
+  // disabling the cache for every empty-runner caller.
+  const cache = QUALITY_TEXT.match(/^\s*cache:\s*\$\{\{(.+)\}\}\s*$/m);
+  assert.ok(cache, "no `cache: ${{ … }}` value found at the setup-toolchain call site");
+  assert.equal(evaluate(cache[1].trim(), { runner: "", "toolchain-cache": "auto" }), "true");
+});

package/scripts/check-semgrep-lockfile.test.mjs

@@ -38,9 +38,51 @@ const LOCKFILE = "scripts/semgrep-requirements.txt";
 const WORKFLOW = ".github/workflows/pr-quality.yml";
 const UPDATER = "scripts/update-semgrep-rules.mjs";
 
+const DOCS = "docs/reusable-workflows.md";
+
 const lockfile = readFileSync(LOCKFILE, "utf8");
 const workflow = readFileSync(WORKFLOW, "utf8");
 
+const SAST_STEP_HEADER = "- name: SAST (Semgrep, blocking, no SARIF upload)";
+
+/**
+ * Return the SAST step's `run:` body — from its `- name:` line to the next
+ * step at the same indentation — with comment-only lines stripped.
+ *
+ * Both halves earn their place. Scoping to the step is what stops a whole-file
+ * `indexOf` from resolving an anchor against an unrelated tier a thousand
+ * lines away; dropping comments is what stops it from resolving against PROSE
+ * ABOUT the code instead of the code. The selector-before-venv guard below did
+ * both: its `select-semgrep-python.sh` hit landed in the side-checkout step's
+ * comment block and its `-m venv` hit in a paragraph explaining venvs, so the
+ * ordering it asserted was the ordering of two comments.
+ */
+function sastStepCode(text = workflow) {
+  const start = text.indexOf(SAST_STEP_HEADER);
+  if (start === -1) return "";
+  const rest = text.slice(start + SAST_STEP_HEADER.length);
+  const end = rest.indexOf("\n      - ");
+  const step = end === -1 ? rest : rest.slice(0, end);
+  return step
+    .split("\n")
+    .filter((line) => !line.trimStart().startsWith("#"))
+    .join("\n");
+}
+
+/**
+ * True when the SAST step chooses its interpreter before it builds the venv.
+ * A predicate rather than a bare assertion so the guard can be exercised
+ * against a MUTATED workflow — a test that only ever sees the passing input
+ * cannot show it would notice the failure.
+ */
+function selectorPrecedesVenv(text) {
+  const code = sastStepCode(text);
+  const select = code.indexOf('source "${SELECT_PYTHON}"');
+  const venv = code.indexOf('"${SEMGREP_PYTHON}" -m venv');
+  if (select === -1 || venv === -1) return false;
+  return select < venv;
+}
+
 // semgrep's own `requires_python`, recorded per release. Verified on PyPI
 // 2026-09-10: 1.97.0 was `>=3.8`, 1.136.0 `>=3.9`, and 1.137.0 raised it to
 // `>=3.10` — which is why a runner on macOS system Python (3.9.6) could not
@@ -265,16 +307,38 @@ test("the selector rides the same side-checkout as the lockfile", () => {
 test("the SAST step selects an interpreter before it creates the venv", () => {
   // A venv inherits the interpreter that built it, so a floor enforced after
   // `-m venv` cannot fix anything. Order is the whole guarantee.
-  const select = workflow.indexOf("select-semgrep-python.sh");
-  const venv = workflow.indexOf("-m venv");
-  assert.notEqual(select, -1, `${WORKFLOW}: the SAST step must source the interpreter selector`);
-  assert.notEqual(venv, -1, `${WORKFLOW}: the SAST step must still create a venv`);
-  assert.ok(select < venv, "the selector must be sourced BEFORE the venv is created");
-
+  const code = sastStepCode();
+  assert.notEqual(code, "", `${WORKFLOW}: the SAST step was renamed or removed`);
+  assert.ok(
+    code.includes('source "${SELECT_PYTHON}"'),
+    `${WORKFLOW}: the SAST step must source the interpreter selector`,
+  );
   assert.ok(
-    workflow.includes('"${SEMGREP_PYTHON}" -m venv'),
+    code.includes('"${SEMGREP_PYTHON}" -m venv'),
     "the venv must be built from the selected interpreter, not from bare python3",
   );
+  assert.ok(selectorPrecedesVenv(workflow), "the selector must be sourced BEFORE the venv");
+});
+
+test("the selector-before-venv guard fails when the two are swapped", () => {
+  // The mutation the guard exists to catch, performed on a copy: move the venv
+  // line above the `source` line and the check must go red. Without this, the
+  // guard could be resolving anchors that no reordering of the real step would
+  // ever move — which is precisely how it passed while comparing two comments.
+  const VENV_LINE = '          "${SEMGREP_PYTHON}" -m venv "${venv_dir}"\n';
+  const SOURCE_LINE = '          source "${SELECT_PYTHON}"\n';
+  assert.ok(workflow.includes(VENV_LINE), `${WORKFLOW}: the venv line changed shape`);
+  assert.ok(workflow.includes(SOURCE_LINE), `${WORKFLOW}: the source line changed shape`);
+
+  const mutated = workflow
+    .replace(VENV_LINE, "")
+    .replace(SOURCE_LINE, `${VENV_LINE}${SOURCE_LINE}`);
+  assert.notEqual(mutated, workflow, "the mutation must actually change the workflow");
+  assert.equal(
+    selectorPrecedesVenv(mutated),
+    false,
+    "a venv built before the interpreter is chosen must fail the guard",
+  );
 });
 
 test("the non-lockfile path installs exactly SEMGREP_PIN, never a resolved older release", () => {
@@ -341,3 +405,170 @@ test("the floor added no workflow_call input and no new job permission", () => {
   assert.ok(!header.includes("id-token:"), "no new permission was needed for an interpreter floor");
   assert.ok(!header.includes("packages:"), "no new permission was needed for an interpreter floor");
 });
+
+// ---------------------------------------------------------------------------
+// 6. The hash-pinned path's real preconditions, and an audible fallback (#495)
+// ---------------------------------------------------------------------------
+
+test("the hash-pinned branch tests architecture as well as OS and ABI", () => {
+  // The lockfile was resolved with `--platform manylinux*_x86_64` only, and
+  // PyPI ships a separate `manylinux_2_34_aarch64` semgrep wheel that no entry
+  // covers. On an arm64 Linux runner the OS+ABI test passed and
+  // `--require-hashes --only-binary` hard-failed on a hash mismatch — a red
+  // that reads like a tampered artifact rather than an unsupported arch.
+  const code = sastStepCode();
+  assert.ok(
+    code.includes('[ "${pyver}" = "312" ]'),
+    `${WORKFLOW}: the cp312 test must stay an equality`,
+  );
+  assert.ok(
+    code.includes('[ "${runner_arch}" = "x86_64" ]'),
+    `${WORKFLOW}: the hash-pinned branch must also require x86_64`,
+  );
+  assert.ok(
+    code.includes('runner_arch="$(uname -m)"'),
+    "the architecture must be read from the runner, not assumed",
+  );
+});
+
+test("the lockfile's declared ABI matches the branch's cp equality", () => {
+  // Two spellings of one fact: `3.12` steers the interpreter probe and `312`
+  // gates the install. A bump that moved one and not the other would probe for
+  // an interpreter the install then rejects.
+  const abi = workflow.match(/export SEMGREP_LOCKFILE_ABI='([^']+)'/);
+  assert.ok(abi, `${WORKFLOW}: SEMGREP_LOCKFILE_ABI must be exported for the selector`);
+  assert.equal(
+    abi[1].replace(".", ""),
+    "312",
+    `SEMGREP_LOCKFILE_ABI is ${abi[1]} but the hash-pinned branch installs only on cp312`,
+  );
+});
+
+test("every reason for leaving the hash-pinned path is warned about by name", () => {
+  // The single line this replaced said "Non-Linux runner (or no lockfile)" on
+  // all four, so the two that actually cost the fleet its supply-chain pin — a
+  // rolled interpreter and an unsupported arch — were reported as neither of
+  // them, at log level, on a green job.
+  const code = sastStepCode();
+  const reasons = code.split("\n").filter((l) => l.includes("fallback_reason="));
+  assert.equal(reasons.length, 4, "expected one named reason per precondition");
+
+  for (const [precondition, phrase] of [
+    ["OS", "not Linux"],
+    ["architecture", "not x86_64"],
+    ["interpreter ABI", "not the lockfile's cp312"],
+    ["missing lockfile", "lockfile is missing"],
+  ]) {
+    assert.ok(
+      reasons.some((line) => line.includes(phrase)),
+      `no fallback reason names the ${precondition} precondition (looked for "${phrase}")`,
+    );
+  }
+
+  const warning = code
+    .split("\n")
+    .find((l) => l.includes("::warning::") && l.includes("${fallback_reason}"));
+  assert.ok(
+    warning,
+    "the fallback must emit a ::warning:: carrying the resolved reason, not a log line",
+  );
+  assert.ok(
+    warning.includes("WITHOUT hash-pinning"),
+    "the warning must say what was actually lost",
+  );
+});
+
+test("the SAST exclude list covers every platform side-checkout", () => {
+  // Two directories are materialized from mandrel-platform's own tree —
+  // `_mandrel-platform-sast` (the ruleset) and `_mandrel-platform-semgrep`
+  // (the lockfile + selector). Only the first was ever excluded, so platform
+  // source could enter a caller's finding set. The glob covers the next one
+  // too.
+  const code = sastStepCode();
+  assert.ok(
+    code.includes("--exclude '_mandrel-platform-*'"),
+    `${WORKFLOW}: the exclude list must cover _mandrel-platform-* , not one checkout by name`,
+  );
+
+  // Both checkout paths must fall under the glob, or the exclude is cosmetic.
+  for (const path of ["_mandrel-platform-sast", "_mandrel-platform-semgrep"]) {
+    assert.ok(
+      workflow.includes(`path: ${path}`),
+      `${WORKFLOW}: expected a side-checkout at ${path}`,
+    );
+    assert.ok(path.startsWith("_mandrel-platform-"), `${path} is not covered by the glob`);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 7. The rules updater shares the selector, and counts its own hashes (#495)
+// ---------------------------------------------------------------------------
+
+test("the rules updater builds its venv from the shared interpreter selector", () => {
+  const updater = readFileSync(UPDATER, "utf8");
+  assert.ok(
+    updater.includes("select-semgrep-python.sh"),
+    `${UPDATER}: the venv interpreter must come from the same selector the SAST step uses`,
+  );
+  assert.ok(
+    !/spawnSync\("python3"/.test(updater),
+    `${UPDATER}: a hard-coded python3 installs nothing on a macOS system interpreter`,
+  );
+});
+
+test("the rules updater no longer installs setuptools", () => {
+  // It was there only because semgrep 1.97.0's transitive
+  // opentelemetry-instrumentation 0.46b0 imported pkg_resources at load.
+  // 0.58b0 does not, and 80.9.0 — the last release shipping pkg_resources —
+  // carries its own advisories.
+  const updater = readFileSync(UPDATER, "utf8");
+  assert.ok(
+    !/["']setuptools["']/.test(updater),
+    `${UPDATER}: setuptools must not be reinstalled into the vendoring venv`,
+  );
+});
+
+test("the SEMGREP_HASHES comment states the artifact count it actually carries", () => {
+  // The comment read "the four platform wheels + the sdist" while the array
+  // held eight. A reader checking whether the hash set is complete is reading
+  // the comment, so a stale count is a supply-chain claim that is not true.
+  const updater = readFileSync(UPDATER, "utf8");
+  const version = REQS.get("semgrep");
+
+  const mapStart = updater.indexOf("const SEMGREP_HASHES = {");
+  assert.notEqual(mapStart, -1, `${UPDATER}: SEMGREP_HASHES not found`);
+  const entryStart = updater.indexOf(`"${version}": [`, mapStart);
+  assert.notEqual(entryStart, -1, `${UPDATER}: SEMGREP_HASHES has no entry for ${version}`);
+  const entry = updater.slice(entryStart, updater.indexOf("],", entryStart));
+  const recorded = entry.split("sha256:").length - 1;
+  assert.ok(recorded > 0, `${UPDATER}: the ${version} entry carries no hashes`);
+
+  const comment = updater.slice(0, mapStart);
+  const claimed = comment.match(/(\d+) artifacts/);
+  assert.ok(
+    claimed,
+    `${UPDATER}: the SEMGREP_HASHES comment must state how many artifacts it pins`,
+  );
+  assert.equal(
+    Number.parseInt(claimed[1], 10),
+    recorded,
+    `the comment claims ${claimed[1]} artifacts but the ${version} entry pins ${recorded}`,
+  );
+});
+
+// ---------------------------------------------------------------------------
+// 8. The documented behaviour is the shipped behaviour (#495)
+// ---------------------------------------------------------------------------
+
+test("the SAST docs describe the ABI-first probe order and the fallback warning", () => {
+  // A consumer debugging a lost hash pin reads this section, not the workflow.
+  const docs = readFileSync(DOCS, "utf8");
+  const start = docs.indexOf("> **Python interpreter floor.**");
+  assert.notEqual(start, -1, `${DOCS}: the SAST interpreter section was renamed or removed`);
+  const section = docs.slice(start, docs.indexOf("#### SAST ruleset provenance", start));
+
+  assert.match(section, /SEMGREP_LOCKFILE_ABI|lockfile.{0,40}ABI/i, "the ABI input must be named");
+  assert.match(section, /probed first|first on Linux/i, "the probe order must be stated");
+  assert.match(section, /::warning::/, "the fallback warning must be documented");
+  assert.match(section, /x86_64/, "the architecture precondition must be documented");
+});