mandrel-platform 1.11.0 → 1.13.0

package/scripts/env-doctor.test.mjs

@@ -1339,6 +1339,236 @@ test("a multi-folder key with a shape earns ONE verdict per environment, not one
   }
 });
 
+// ---------------------------------------------------------------------------
+// Cloudflare Worker residency — per-environment presence (Story #483)
+// ---------------------------------------------------------------------------
+
+/**
+ * A manifest whose workers carry no `config` and whose keys have no local,
+ * GitHub or Infisical residency, so the offline arm over an empty repo root
+ * contributes nothing and every finding under test comes from the Cloudflare
+ * probe.
+ */
+function cloudflareOnlyManifest({ workers, keys, environments = ["staging", "production"] }) {
+  return parseManifest({
+    environments,
+    workers: Object.fromEntries(workers.map((id) => [id, { scriptName: `swarm-${id}-{env}` }])),
+    keys: keys.map((k) => ({
+      kind: "secret",
+      sensitivity: "secret",
+      residency: { local: null, github: null, cloudflare: { workers: k.workers, kind: "secret" } },
+      infisical: "unmanaged",
+      ...k,
+      workers: undefined,
+    })),
+  });
+}
+
+/** Mock `secretNames` from a `{"<worker>-<env>": [names]}` map. */
+function cloudflareProbe(present) {
+  return {
+    secretNames: async (scriptName) => {
+      const key = scriptName.replace(/^swarm-/, "");
+      return present[key] ?? [];
+    },
+  };
+}
+
+async function cloudflareFindings({ manifest, present, environments = ["staging", "production"] }) {
+  const root = makeRepo({});
+  try {
+    const report = await runDoctor({
+      manifest,
+      repoRoot: root,
+      environments,
+      cloudflare: cloudflareProbe(present),
+    });
+    return report.findings.filter((f) => f.surface === "cloudflare");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+test("a bare worker id still means every environment — every manifest in existence says it that way", () => {
+  const manifest = cloudflareOnlyManifest({
+    workers: ["api"],
+    keys: [{ name: "SHARED_TOKEN", workers: ["api"] }],
+  });
+  assert.deepEqual(manifest.keys[0].residency.cloudflare.workers, [
+    { worker: "api", environments: ["staging", "production"] },
+  ]);
+});
+
+test("the object form narrows one entry while a bare sibling keeps defaulting to every environment", () => {
+  const manifest = cloudflareOnlyManifest({
+    workers: ["staff", "api"],
+    keys: [{ name: "SHARED_TOKEN", workers: [{ worker: "staff", environments: ["production"] }, "api"] }],
+  });
+  assert.deepEqual(manifest.keys[0].residency.cloudflare.workers, [
+    { worker: "staff", environments: ["production"] },
+    { worker: "api", environments: ["staging", "production"] },
+  ]);
+});
+
+test("a production-only key present only in production reports NOTHING — the defect #481 filed", async () => {
+  const findings = await cloudflareFindings({
+    manifest: cloudflareOnlyManifest({
+      workers: ["staff"],
+      keys: [{ name: "PEER_DATABASE_URL", workers: [{ worker: "staff", environments: ["production"] }] }],
+    }),
+    present: { "staff-production": ["PEER_DATABASE_URL"] },
+  });
+  assert.deepEqual(findings, []);
+});
+
+test("cloudflare suppression does not cross environment — a production-only key in staging orphans", async () => {
+  const findings = await cloudflareFindings({
+    manifest: cloudflareOnlyManifest({
+      workers: ["staff"],
+      keys: [{ name: "PEER_DATABASE_URL", workers: [{ worker: "staff", environments: ["production"] }] }],
+    }),
+    present: { "staff-production": ["PEER_DATABASE_URL"], "staff-staging": ["PEER_DATABASE_URL"] },
+  });
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].kind, "orphan");
+  assert.equal(findings[0].key, "PEER_DATABASE_URL");
+  assert.equal(findings[0].environment, "staging");
+});
+
+test("a narrowed entry still reports a REAL absence in the environment it does name", async () => {
+  const findings = await cloudflareFindings({
+    manifest: cloudflareOnlyManifest({
+      workers: ["staff"],
+      keys: [{ name: "PEER_DATABASE_URL", workers: [{ worker: "staff", environments: ["production"] }] }],
+    }),
+    present: {},
+  });
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].kind, "missing");
+  assert.equal(findings[0].environment, "production");
+});
+
+test("cloudflare worker residency fails closed on every malformed shape", () => {
+  const bad = (workers) => () =>
+    cloudflareOnlyManifest({ workers: ["api", "staff"], keys: [{ name: "SHARED_TOKEN", workers }] });
+
+  assert.throws(bad([]), /must be a non-empty array of worker ids/);
+  assert.throws(bad([42]), /must be a worker id string or \{worker, environments\}/);
+  assert.throws(bad(["nope"]), /references unknown worker id "nope"/);
+  assert.throws(bad([{ worker: "nope", environments: ["staging"] }]), /references unknown worker id "nope"/);
+  assert.throws(bad(["api", "api"]), /repeats the worker "api"/);
+  assert.throws(bad(["api", { worker: "api", environments: ["staging"] }]), /repeats the worker "api"/);
+  assert.throws(bad([{ worker: "api", environments: ["preview"] }]), /absent from manifest.environments/);
+  assert.throws(bad([{ worker: "api", environments: [] }]), /must not be empty/);
+  assert.throws(bad([{ worker: "api", environments: "staging" }]), /must be an array of environment slugs/);
+});
+
+test("a worker deployed to one environment by design does not 404-fail in the other", async () => {
+  // The narrowing's second consequence: probing a worker in an environment it
+  // expects nothing in must not turn that worker's deliberate absence into a
+  // finding, or the false failure comes back one layer down.
+  const root = makeRepo({});
+  try {
+    const report = await runDoctor({
+      manifest: cloudflareOnlyManifest({
+        workers: ["staff"],
+        keys: [{ name: "PEER_DATABASE_URL", workers: [{ worker: "staff", environments: ["production"] }] }],
+      }),
+      repoRoot: root,
+      environments: ["staging", "production"],
+      cloudflare: {
+        secretNames: async (scriptName) => {
+          if (scriptName === "swarm-staff-staging") {
+            const err = new Error("not found");
+            err.httpStatus = 404;
+            throw err;
+          }
+          return ["PEER_DATABASE_URL"];
+        },
+      },
+    });
+    assert.deepEqual(
+      report.findings.filter((f) => f.surface === "cloudflare"),
+      []
+    );
+    assert.equal(report.surfaces.find((s) => s.surface === "cloudflare").status, "checked");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("the six single-environment keys from #481 report zero failures on a correct manifest", async () => {
+  // The consumer evidence that filed the gap, reconstructed: ten false
+  // `missing` findings across six keys whose single-environment placement is
+  // deliberate. Every one of them must now be silent.
+  const production = ["production"];
+  const staging = ["staging"];
+  const manifest = cloudflareOnlyManifest({
+    workers: ["staff", "api", "web"],
+    keys: [
+      { name: "PEER_DATABASE_URL", workers: [{ worker: "staff", environments: production }] },
+      { name: "PEER_TURSO_AUTH_TOKEN", workers: [{ worker: "staff", environments: production }] },
+      { name: "SENTRY_WEBHOOK_SIGNING_SECRET", workers: [{ worker: "api", environments: production }] },
+      { name: "GITHUB_INTAKE_TOKEN", workers: [{ worker: "api", environments: production }] },
+      {
+        name: "EMAIL_RECIPIENT_ALLOWLIST",
+        workers: ["api", "web", "staff"].map((worker) => ({ worker, environments: staging })),
+      },
+      {
+        name: "SMS_RECIPIENT_ALLOWLIST",
+        workers: ["api", "web", "staff"].map((worker) => ({ worker, environments: staging })),
+      },
+    ],
+  });
+  const findings = await cloudflareFindings({
+    manifest,
+    present: {
+      "staff-production": ["PEER_DATABASE_URL", "PEER_TURSO_AUTH_TOKEN"],
+      "api-production": ["SENTRY_WEBHOOK_SIGNING_SECRET", "GITHUB_INTAKE_TOKEN"],
+      "api-staging": ["EMAIL_RECIPIENT_ALLOWLIST", "SMS_RECIPIENT_ALLOWLIST"],
+      "web-staging": ["EMAIL_RECIPIENT_ALLOWLIST", "SMS_RECIPIENT_ALLOWLIST"],
+      "staff-staging": ["EMAIL_RECIPIENT_ALLOWLIST", "SMS_RECIPIENT_ALLOWLIST"],
+    },
+  });
+  assert.deepEqual(findings, []);
+});
+
+test("KEY_SCHEMA names the per-environment worker entry so the script and the docs cannot drift", () => {
+  assert.match(KEY_SCHEMA.residency, /worker, environments/);
+});
+
+test("a var-residency key is unaffected by the environment axis at the wrangler [vars] check", () => {
+  // The wrangler check has no environment axis — it reports `environment: null`
+  // and `parseWranglerVars` flattens `[env.X.vars]` into one set — so a var
+  // declared for ONE environment stays expected in that worker's config.
+  const root = makeRepo({ wrangler: '[env.staging.vars]\nSTAGING_ONLY_FLAG = "1"\n' });
+  try {
+    const manifest = parseManifest({
+      environments: ["staging", "production"],
+      workers: { web: { config: "wrangler.toml", scriptName: "swarm-web-{env}" } },
+      keys: [
+        {
+          name: "STAGING_ONLY_FLAG",
+          kind: "var",
+          sensitivity: "public",
+          residency: {
+            local: null,
+            github: null,
+            cloudflare: { workers: [{ worker: "web", environments: ["staging"] }], kind: "var" },
+          },
+          infisical: "unmanaged",
+        },
+      ],
+    });
+    const findings = runOfflineChecks({ manifest, repoRoot: root }).findings.filter(
+      (f) => f.surface === "wrangler"
+    );
+    assert.deepEqual(findings, []);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
 test("MANIFEST_SCHEMA and KEY_SCHEMA describe the slug container and the folders array", () => {
   assert.ok(Object.hasOwn(MANIFEST_SCHEMA, "environmentSlugs"));
   assert.match(MANIFEST_SCHEMA.environmentSlugs, /infisical/);
@@ -1354,6 +1584,19 @@ test("the documented manifest schema block names the new shapes", () => {
   assert.match(doc, /"folders"/);
 });
 
+test("the docs carry a Cloudflare per-environment residency section beside its two siblings", () => {
+  // Same bargain as the test above, for the third surface to take the
+  // treatment: the doc must describe the entry form the script now accepts.
+  const doc = readFileSync(join(HERE, "..", "docs", "reusable-workflows.md"), "utf8");
+  // `includes` + a message, not `assert.match`: a regex miss here dumps the
+  // whole 250KB document into the failure output and buries the reason.
+  assert.ok(
+    doc.includes("#### Cloudflare Worker residency: per-environment presence"),
+    "docs/reusable-workflows.md must carry the Cloudflare per-environment residency section"
+  );
+  assert.ok(doc.includes('"worker": "staff"'), "the manifest-schema block must show the object entry form");
+});
+
 test("no secret VALUE reaches stdout or stderr through the remapped-slug, multi-folder path", async () => {
   // The values-safety guarantee, re-asserted over the shapes #464 adds: a
   // remapped environment slug and a key resident in two folders. Same

package/scripts/select-semgrep-python.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+# select-semgrep-python.sh — choose the interpreter the pr-quality SAST step
+# builds its Semgrep venv from, and refuse to run on one that is too old
+# (Story #482).
+#
+# WHY THIS EXISTS
+# ---------------
+# The SAST step installs Semgrep two ways: a hash-pinned closure from
+# `scripts/semgrep-requirements.txt` on Linux/cp312, and the bare top pin
+# everywhere else. That second branch is deliberate — it is where a Python
+# roll-FORWARD degrades to, so a CI image moving to 3.13 goes
+# unpinned-but-green rather than fleet-red on ABI-incompatible cp312 wheels.
+#
+# But it carried no floor of its own, so an interpreter that is too OLD
+# hard-failed instead. semgrep raised `requires_python` to `>=3.10` at 1.137.0,
+# and macOS ships `/usr/bin/python3` = 3.9.6, so every consumer on a macOS
+# self-hosted runner with system Python went red on `ci-required` with nothing
+# but pip's resolver error:
+#
+#   ERROR: Could not find a version that satisfies the requirement
+#          semgrep==1.176.1 (from versions: ..., 1.135.0, 1.136.0)
+#
+# which reads like a network or registry problem and never names the
+# interpreter as the cause (issue #480, observed in Beestera/swarm-os#2496).
+#
+# WHY IT DOES NOT JUST INSTALL AN OLDER SEMGREP
+# ---------------------------------------------
+# Resolving "the newest semgrep this interpreter supports" is the obvious fix
+# and it is a security regression. The newest release supporting Python 3.9 is
+# 1.136.0, which hard-pins `opentelemetry-*~=1.25.0`; `opentelemetry-proto` at
+# that version requires `protobuf<5.0`, and EVERY protobuf 4.x is affected by
+# CVE-2026-0994 (CVSS 8.2) — the advisory cleared by the 1.176.1 bump
+# (#477/#472). The same downgrade drags back `opentelemetry-instrumentation`
+# 0.46b0, whose `pkg_resources` import is why `setuptools` used to be in the
+# closure at all. And because THIS install path is deliberately not
+# hash-pinned and its closure is not OSV-scanned, the downgrade would be
+# silent. So the floor fails closed: a usable interpreter or a named error,
+# never a quieter, older Semgrep.
+#
+# CONTRACT
+# --------
+# SOURCE this file (do NOT exec it) from a `shell: bash` step, BEFORE the venv
+# is created — the venv inherits whichever interpreter builds it, so a check
+# made afterwards is already too late.
+#
+#   Inputs (read from the caller's shell / the step `env:` block):
+#     SEMGREP_PIN          = the exact pip requirement the step installs,
+#                            e.g. `semgrep==1.176.1` (diagnostics only)
+#     SEMGREP_PYTHON_FLOOR = minimum `major.minor`, e.g. `3.10` — semgrep's
+#                            own `requires_python` for the pinned version
+#
+#   Outputs (set on the caller's shell):
+#     SEMGREP_PYTHON         = the interpreter to build the venv with
+#     SEMGREP_PYTHON_VERSION = its `major.minor`
+#
+# Candidates are probed in order — `python3` first, so a compliant runner
+# behaves exactly as it did before this file existed, then the versioned
+# names newest-first. Returns non-zero after emitting a `::error::` when
+# nothing on PATH qualifies; under the caller's `set -e` that fails the step.
+
+_semgrep_python_probe() {
+  # Echo "<major> <minor>" for the interpreter named by $1, or return non-zero
+  # when it is absent from PATH or not a runnable interpreter.
+  local cmd="$1"
+  command -v "${cmd}" >/dev/null 2>&1 || return 1
+  "${cmd}" -c 'import sys; print("%d %d" % sys.version_info[:2])' 2>/dev/null
+}
+
+select_semgrep_python() {
+  local floor="${SEMGREP_PYTHON_FLOOR:-}"
+  local pin="${SEMGREP_PIN:-<unset>}"
+  local floor_major floor_minor cmd probe major minor system_python
+
+  SEMGREP_PYTHON=""
+  SEMGREP_PYTHON_VERSION=""
+
+  # A missing or malformed floor must not silently degrade to "anything goes":
+  # that is the exact fail-open this file exists to close.
+  case "${floor}" in
+    [0-9]*.[0-9]*) ;;
+    *)
+      echo "::error::SEMGREP_PYTHON_FLOOR is unset or malformed ('${floor}') — it must be a major.minor version such as 3.10. Without it this step cannot tell whether the runner's Python is new enough to install ${pin}, and it will not guess."
+      return 1
+      ;;
+  esac
+  floor_major="${floor%%.*}"
+  floor_minor="${floor#*.}"
+  floor_minor="${floor_minor%%.*}"
+
+  # Reported in the failure message: the interpreter a consumer would expect to
+  # be used, so the error names what they actually have rather than only what
+  # is required.
+  system_python="absent"
+
+  for cmd in python3 python3.13 python3.12 python3.11 python3.10; do
+    probe="$(_semgrep_python_probe "${cmd}")" || continue
+    read -r major minor <<<"${probe}"
+    [ -n "${major:-}" ] && [ -n "${minor:-}" ] || continue
+    if [ "${cmd}" = "python3" ]; then
+      system_python="${major}.${minor}"
+    fi
+    # Compare major and minor as SEPARATE integers. A concatenated "${major}${minor}"
+    # compares wrong across the tens boundary — "39" sorts above "310" as a
+    # string, and as an integer 39 is below 310 only by accident of digit count.
+    if [ "${major}" -gt "${floor_major}" ] ||
+      { [ "${major}" -eq "${floor_major}" ] && [ "${minor}" -ge "${floor_minor}" ]; }; then
+      SEMGREP_PYTHON="${cmd}"
+      SEMGREP_PYTHON_VERSION="${major}.${minor}"
+      echo "Semgrep interpreter: ${cmd} (Python ${SEMGREP_PYTHON_VERSION}); floor ${floor} for ${pin}."
+      return 0
+    fi
+  done
+
+  echo "::error::${pin} requires Python >= ${floor}, but no interpreter on this runner's PATH satisfies it (python3 is ${system_python})."
+  echo "Probed, in order: python3 python3.13 python3.12 python3.11 python3.10."
+  echo "Remedy: put a Python >= ${floor} earlier on the runner's PATH than /usr/bin — e.g. 'brew install python@3.12' plus a python3 symlink in a directory the runner's .path lists first — or set 'enable-sast: false' to skip the Semgrep sub-step."
+  echo "Semgrep is deliberately NOT downgraded to fit an older interpreter: the newest release supporting Python 3.9 (1.136.0) pins opentelemetry ~=1.25.0, which caps protobuf below 5.0, and every protobuf 4.x is affected by CVE-2026-0994 (CVSS 8.2). This install path is not hash-pinned and its closure is not OSV-scanned, so the downgrade would be silent."
+  return 1
+}
+
+# When EXECUTED directly (not sourced) — e.g. by the unit test — echo the
+# selection as `KEY=value` lines and exit with the selection's own status, so
+# both the happy path and the fail-closed path are assertable without a
+# GitHub runner. `BASH_SOURCE[0] == $0` iff the file was run, not sourced.
+if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
+  if select_semgrep_python; then
+    printf 'SEMGREP_PYTHON=%s\n' "${SEMGREP_PYTHON}"
+    printf 'SEMGREP_PYTHON_VERSION=%s\n' "${SEMGREP_PYTHON_VERSION}"
+    exit 0
+  fi
+  exit 1
+fi
+
+select_semgrep_python

package/scripts/select-semgrep-python.test.mjs

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+/**
+ * select-semgrep-python.test.mjs — node:test suite for the SAST interpreter
+ * floor (Story #482).
+ *
+ * The pr-quality SAST step `source`s `select-semgrep-python.sh` before it
+ * creates the Semgrep venv, so this script's decision IS which interpreter
+ * the fleet's blocking SAST tier installs against. The suite executes the
+ * script directly (it echoes `SEMGREP_PYTHON=…` lines and exits with the
+ * selection's status when run rather than sourced) against fixture PATHs
+ * built from stub interpreters, so every branch is assertable without a
+ * macOS runner or a real Python matrix.
+ *
+ * Why stubs rather than the host's real interpreters: the failure this closes
+ * only reproduces on a runner whose `python3` is BELOW the floor, which no CI
+ * tier here provides. A stub that answers `-c` with a chosen `major minor` is
+ * the whole interface the script depends on.
+ *
+ * Run: node --test scripts/select-semgrep-python.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SCRIPT = join(HERE, "select-semgrep-python.sh");
+
+const PIN = "semgrep==1.176.1";
+const FLOOR = "3.10";
+
+/**
+ * Build a directory of stub interpreters and return its path. `versions` maps
+ * an interpreter name to the `major.minor` it should report; a stub ignores
+ * its arguments and echoes `"<major> <minor>"`, which is the only thing the
+ * script asks of it.
+ */
+function stubPath(versions) {
+  const dir = mkdtempSync(join(tmpdir(), "semgrep-python-stubs-"));
+  for (const [name, version] of Object.entries(versions)) {
+    const [major, minor] = version.split(".");
+    writeFileSync(join(dir, name), `#!/bin/sh\necho "${major} ${minor}"\n`, { mode: 0o755 });
+  }
+  return dir;
+}
+
+/**
+ * Execute the selector with the given PATH and env. Returns the exit status
+ * and stdout — the script writes its `::error::` annotation to stdout, which
+ * is where GitHub reads workflow commands from.
+ */
+function select({ path, floor = FLOOR, pin = PIN }) {
+  const env = { PATH: path };
+  if (floor !== null) env.SEMGREP_PYTHON_FLOOR = floor;
+  if (pin !== null) env.SEMGREP_PIN = pin;
+  try {
+    const stdout = execFileSync("/bin/bash", [SCRIPT], { encoding: "utf8", env });
+    return { status: 0, stdout };
+  } catch (err) {
+    return { status: err.status, stdout: err.stdout ?? "" };
+  }
+}
+
+/** Parse the `KEY=value` lines the script emits when it succeeds. */
+function parse(stdout) {
+  const out = {};
+  for (const line of stdout.split("\n")) {
+    const eq = line.indexOf("=");
+    if (eq === -1) continue;
+    out[line.slice(0, eq)] = line.slice(eq + 1);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// 1. The script is a usable, sourceable artifact
+// ---------------------------------------------------------------------------
+
+test("the selector is executable", () => {
+  // The workflow sources it, but the suite executes it, and a non-executable
+  // file would pass `source` while failing every assertion below in a way
+  // that reads as a logic bug rather than a mode bug.
+  const mode = statSync(SCRIPT).mode;
+  assert.ok(mode & 0o111, "scripts/select-semgrep-python.sh must be executable");
+});
+
+// ---------------------------------------------------------------------------
+// 2. Selection order — a compliant runner is unchanged
+// ---------------------------------------------------------------------------
+
+test("a python3 at the floor is selected as-is", () => {
+  const r = select({ path: stubPath({ python3: "3.10" }) });
+  assert.equal(r.status, 0);
+  const out = parse(r.stdout);
+  assert.equal(out.SEMGREP_PYTHON, "python3");
+  assert.equal(out.SEMGREP_PYTHON_VERSION, "3.10");
+});
+
+test("python3 wins even when newer versioned interpreters are also present", () => {
+  // A runner that already works must not silently change interpreter — that
+  // would be a behaviour change shipped to the whole fleet as a side effect.
+  const r = select({ path: stubPath({ python3: "3.12", "python3.13": "3.13" }) });
+  assert.equal(r.status, 0);
+  assert.equal(parse(r.stdout).SEMGREP_PYTHON, "python3");
+});
+
+// ---------------------------------------------------------------------------
+// 3. Discovery — the reported consumer-side remedy, performed by the workflow
+// ---------------------------------------------------------------------------
+
+test("a below-floor python3 falls through to a qualifying python3.N", () => {
+  // The exact shape of issue #480: macOS /usr/bin/python3 is 3.9.6 while a
+  // brew-installed 3.12 sits on PATH under its versioned name.
+  const r = select({ path: stubPath({ python3: "3.9", "python3.12": "3.12" }) });
+  assert.equal(r.status, 0);
+  const out = parse(r.stdout);
+  assert.equal(out.SEMGREP_PYTHON, "python3.12");
+  assert.equal(out.SEMGREP_PYTHON_VERSION, "3.12");
+});
+
+test("versioned candidates are probed newest-first", () => {
+  const r = select({
+    path: stubPath({ python3: "3.9", "python3.11": "3.11", "python3.13": "3.13" }),
+  });
+  assert.equal(r.status, 0);
+  assert.equal(parse(r.stdout).SEMGREP_PYTHON, "python3.13");
+});
+
+test("3.9 is rejected and 3.10 accepted — the floor compares minor numerically", () => {
+  // Guards the tens-boundary trap: as strings "39" sorts ABOVE "310", so a
+  // concatenated comparison would accept 3.9 and reject the floor itself.
+  const rejected = select({ path: stubPath({ python3: "3.9" }) });
+  assert.equal(rejected.status, 1);
+  const accepted = select({ path: stubPath({ python3: "3.10" }) });
+  assert.equal(accepted.status, 0);
+});
+
+test("a future major version satisfies the floor", () => {
+  const r = select({ path: stubPath({ python3: "4.0" }) });
+  assert.equal(r.status, 0);
+  assert.equal(parse(r.stdout).SEMGREP_PYTHON_VERSION, "4.0");
+});
+
+// ---------------------------------------------------------------------------
+// 4. Fail closed, with an actionable message
+// ---------------------------------------------------------------------------
+
+test("no qualifying interpreter fails with an ::error:: naming floor, pin and version found", () => {
+  const r = select({ path: stubPath({ python3: "3.9" }) });
+  assert.equal(r.status, 1, "the step must fail rather than install something older");
+
+  const error = r.stdout.split("\n").find((l) => l.startsWith("::error::"));
+  assert.ok(error, "the failure must be a GitHub ::error:: annotation, not bare output");
+  assert.ok(error.includes(FLOOR), `the annotation must name the floor (${FLOOR}): ${error}`);
+  assert.ok(error.includes(PIN), `the annotation must name the pin (${PIN}): ${error}`);
+  assert.ok(
+    error.includes("3.9"),
+    `the annotation must name the interpreter version actually found: ${error}`,
+  );
+});
+
+test("the failure names the PATH remedy and the enable-sast escape hatch", () => {
+  const r = select({ path: stubPath({ python3: "3.9" }) });
+  assert.ok(r.stdout.includes("PATH"), "the remedy must name PATH");
+  assert.ok(
+    r.stdout.includes("enable-sast"),
+    "the remedy must name the enable-sast escape hatch, since no semgrep-pin input exists",
+  );
+});
+
+test("the failure records why semgrep is not downgraded instead", () => {
+  // The rationale belongs in the runner output: the next person to hit this
+  // reads the log, not the Story, and "just pin an older semgrep" is the
+  // wrong fix for a documented reason.
+  const r = select({ path: stubPath({ python3: "3.9" }) });
+  assert.ok(r.stdout.includes("CVE-2026-0994"), "must name the advisory a downgrade re-admits");
+  assert.ok(r.stdout.includes("1.136.0"), "must name the last py3.9-compatible release");
+});
+
+test("an absent python3 is reported as absent, not as a version", () => {
+  const r = select({ path: stubPath({}) });
+  assert.equal(r.status, 1);
+  const error = r.stdout.split("\n").find((l) => l.startsWith("::error::"));
+  assert.ok(error.includes("absent"), `expected 'absent' in: ${error}`);
+});
+
+test("a non-interpreter on PATH under an interpreter name is skipped, not trusted", () => {
+  // `command -v` finding the name is not proof it answers `-c`. A stub that
+  // exits non-zero must be passed over rather than selected with an empty
+  // version.
+  const dir = mkdtempSync(join(tmpdir(), "semgrep-python-stubs-"));
+  writeFileSync(join(dir, "python3"), "#!/bin/sh\nexit 127\n", { mode: 0o755 });
+  writeFileSync(join(dir, "python3.12"), '#!/bin/sh\necho "3 12"\n', { mode: 0o755 });
+  const r = select({ path: dir });
+  assert.equal(r.status, 0);
+  assert.equal(parse(r.stdout).SEMGREP_PYTHON, "python3.12");
+});
+
+// ---------------------------------------------------------------------------
+// 5. The floor itself cannot go missing quietly
+// ---------------------------------------------------------------------------
+
+test("an unset floor fails closed rather than accepting any interpreter", () => {
+  const r = select({ path: stubPath({ python3: "3.9" }), floor: null });
+  assert.equal(r.status, 1);
+  const error = r.stdout.split("\n").find((l) => l.startsWith("::error::"));
+  assert.ok(error.includes("SEMGREP_PYTHON_FLOOR"), `expected the floor named in: ${error}`);
+});
+
+test("a malformed floor fails closed", () => {
+  const r = select({ path: stubPath({ python3: "3.12" }), floor: "latest" });
+  assert.equal(r.status, 1, "a malformed floor must not be treated as satisfied");
+});