mandrel-platform 1.12.0 → 1.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
   "license": "MIT",
   "repository": {

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

@@ -39,6 +39,18 @@ const WORKFLOW = ".github/workflows/pr-quality.yml";
 const UPDATER = "scripts/update-semgrep-rules.mjs";
 
 const lockfile = readFileSync(LOCKFILE, "utf8");
+const workflow = readFileSync(WORKFLOW, "utf8");
+
+// 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
+// install the 1.176.1 pin at all (issue #480).
+//
+// This table is what makes the floor in pr-quality.yml checkable without a
+// network call: a bump to a release with no entry here fails loudly, so
+// "look up the new requires_python" becomes a step of the bump rather than
+// something discovered by a consumer's red CI.
+const SEMGREP_PYTHON_FLOORS = new Map([["1.176.1", "3.10"]]);
 
 /**
  * Parse `name==version` requirement lines, ignoring comments and hash
@@ -118,7 +130,6 @@ test("the lockfile, the workflow, and the rules updater pin the same semgrep", (
   const lockVersion = REQS.get("semgrep");
   assert.ok(lockVersion, `${LOCKFILE}: semgrep must be pinned`);
 
-  const workflow = readFileSync(WORKFLOW, "utf8");
   const wf = workflow.match(/SEMGREP_PIN='semgrep==([^']+)'/);
   assert.ok(wf, `${WORKFLOW}: SEMGREP_PIN not found`);
   assert.equal(wf[1], lockVersion, "workflow SEMGREP_PIN disagrees with the lockfile");
@@ -203,3 +214,130 @@ test("the header warns about the manylinux_2_34 wheel tag", () => {
     "the header must carry a regeneration command",
   );
 });
+
+// ---------------------------------------------------------------------------
+// 5. The interpreter floor on the non-lockfile install path (Story #482)
+// ---------------------------------------------------------------------------
+
+test("pr-quality.yml declares an interpreter floor matching the pinned semgrep", () => {
+  const version = REQS.get("semgrep");
+  const declared = workflow.match(/SEMGREP_PYTHON_FLOOR='([^']+)'/);
+  assert.ok(
+    declared,
+    `${WORKFLOW}: SEMGREP_PYTHON_FLOOR must be declared beside SEMGREP_PIN — without it the SAST step cannot tell a too-old interpreter from a working one`,
+  );
+
+  const recorded = SEMGREP_PYTHON_FLOORS.get(version);
+  assert.ok(
+    recorded,
+    `no requires_python floor recorded for semgrep ${version} — read it off PyPI and add it to SEMGREP_PYTHON_FLOORS before bumping SEMGREP_PIN`,
+  );
+  assert.equal(
+    declared[1],
+    recorded,
+    `SEMGREP_PYTHON_FLOOR is ${declared[1]} but semgrep ${version} requires Python >= ${recorded}`,
+  );
+});
+
+test("the selector rides the same side-checkout as the lockfile", () => {
+  // The sparse-checkout is NON-CONE and lists exact paths, so a script the
+  // SAST step sources is absent at run time unless it is named here — and a
+  // missing `source` target kills the security tier for every consumer at
+  // once. Both files must sit in the one list.
+  const start = workflow.indexOf("- name: Checkout Semgrep lockfile");
+  assert.notEqual(start, -1, `${WORKFLOW}: the Semgrep side-checkout step was renamed or removed`);
+  const step = workflow.slice(start, workflow.indexOf("path: _mandrel-platform-semgrep", start));
+
+  assert.ok(
+    step.includes("scripts/semgrep-requirements.txt"),
+    "the side-checkout must still carry the lockfile",
+  );
+  assert.ok(
+    step.includes("scripts/select-semgrep-python.sh"),
+    "the side-checkout must carry the interpreter selector the SAST step sources",
+  );
+  assert.ok(
+    step.includes("sparse-checkout-cone-mode: false"),
+    "non-cone mode is what makes the exact-path list meaningful",
+  );
+});
+
+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");
+
+  assert.ok(
+    workflow.includes('"${SEMGREP_PYTHON}" -m venv'),
+    "the venv must be built from the selected interpreter, not from bare python3",
+  );
+});
+
+test("the non-lockfile path installs exactly SEMGREP_PIN, never a resolved older release", () => {
+  // Downgrading to fit an old interpreter re-admits CVE-2026-0994: the newest
+  // py3.9-compatible semgrep (1.136.0) pins opentelemetry ~=1.25.0, which caps
+  // protobuf below 5.0, and every protobuf 4.x is affected. This path is not
+  // hash-pinned and its closure is not OSV-scanned, so it would be silent.
+  assert.ok(
+    workflow.includes('--retries 3 "${SEMGREP_PIN}"'),
+    "the fallback must install the exact pin",
+  );
+
+  // Matched as literal substrings rather than a regex alternating the
+  // comparison operators: CodeQL reads such a pattern as an attempted HTML-tag
+  // filter and raises js/bad-tag-filter at HIGH, which blocks the merge.
+  const LOOSE = ["semgrep<", "semgrep>", "semgrep~=", "semgrep!=", 'semgrep=="${'];
+  for (const loose of LOOSE) {
+    assert.ok(
+      !workflow.includes(loose),
+      `${WORKFLOW}: '${loose}' would let pip resolve a semgrep other than the pin`,
+    );
+  }
+});
+
+test("the Linux hash-pinned branch keeps its exact cp312 equality", () => {
+  // Widening this to a `>=` (proposed in issue #480) would route a cp313
+  // interpreter onto the lockfile's cp312-only wheels under
+  // `--only-binary :all:`, with no sdist fallback — the fleet-red the fallback
+  // exists to avoid. The equality is the guard, not the oversight.
+  assert.ok(
+    workflow.includes('[ "${pyver}" = "312" ]'),
+    `${WORKFLOW}: the cp312 test must stay an equality`,
+  );
+  assert.ok(
+    workflow.includes('The `= "312"` below is an EQUALITY on purpose'),
+    "the equality must carry a comment saying why a >= test would be wrong",
+  );
+  assert.ok(
+    workflow.includes("sdist fallback"),
+    "that comment must name the missing sdist fallback as the mechanism",
+  );
+});
+
+test("the floor added no workflow_call input and no new job permission", () => {
+  // A consumer-set semgrep pin would re-open the same un-scanned downgrade
+  // hole operator-side; `enable-sast: false` is the escape hatch. And a new
+  // job-level permission is a COMPILE-TIME break for every caller of this
+  // reusable workflow, not a runtime one.
+  assert.ok(!workflow.includes("semgrep-pin:"), "no semgrep-pin input — see the Story's non-goals");
+  assert.ok(!workflow.includes("python-version:"), "no python-version input — see the Story's non-goals");
+
+  const start = workflow.indexOf("name: Security (secret scan + SAST)");
+  assert.notEqual(start, -1, `${WORKFLOW}: the security job was renamed`);
+  const header = workflow.slice(start, workflow.indexOf("steps:", start));
+  const granted = header
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l === "contents: read" || l === "actions: write");
+  assert.equal(
+    granted.length,
+    2,
+    "the security job's permissions must remain exactly contents: read + actions: write",
+  );
+  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");
+});

package/scripts/env-doctor.mjs

@@ -133,7 +133,7 @@ export const KEY_SCHEMA = Object.freeze({
   kind: "'var' | 'secret'",
   sensitivity: "'public' | 'secret'",
   residency:
-    "object — {local: 'var'|'secret'|'file'|null, github: G|G[]|null where G = {scope,kind,environments?}, cloudflare: {workers,kind}|null}",
+    "object — {local: 'var'|'secret'|'file'|null, github: G|G[]|null where G = {scope,kind,environments?}, cloudflare: {workers: (string | {worker, environments})[], kind}|null}",
   infisical:
     "{folder, environments} | {folders: (string | {folder, environments})[]} | 'unmanaged'",
   shape: `string? — one of ${SHAPE_NAMES.join(", ")}`,
@@ -456,6 +456,103 @@ function normalizeInfisicalResidency(raw, { at, name, environments }) {
   return { folders };
 }
 
+/**
+ * Normalize `residency.cloudflare` to its canonical
+ * `{workers: [{worker, environments}], kind}` form.
+ *
+ * `workers` accepts a bare worker id — the shape every manifest written before
+ * Story #483 uses — or a `{worker, environments}` object, because a key can be
+ * deliberately resident on one Worker in one environment only: a peer-database
+ * credential scoped that tightly to bound its blast radius, or a recipient
+ * allowlist that exists only where non-production sending is gated. With no
+ * per-entry `environments`, `probeCloudflare` reconciled ONE expected-name list
+ * against EVERY environment, so a deliberate single-environment placement had
+ * to report `missing` from the others — ten findings on one consumer's correct
+ * manifest, every one of them false (Story #481).
+ *
+ * A bare entry keeps meaning "every environment". That is the load-bearing
+ * constraint rather than a convenience: every manifest in existence declares
+ * `workers` as a bare string array, so any other reading would break them all.
+ *
+ * Both authored shapes normalize to one array of `{worker, environments}` with
+ * `environments` defaulted and materialized to `manifest.environments`, so
+ * `probeCloudflare` has exactly one shape to read — the same
+ * normalize-at-parse treatment `residency.github` received in Story #459 and
+ * `infisical` in Story #464. Cloudflare is the surface that never got it, and
+ * matching them matters more than the field shape itself: three expressive
+ * residencies with one idiom, not three.
+ *
+ * One deliberate divergence from those two: an **empty** `environments` array
+ * is rejected rather than read as "resident nowhere". That state is
+ * indistinguishable from omitting the residency altogether, and silently
+ * accepting it is precisely how a manifest author comes to believe they have
+ * scoped something they have not — the same fail-closed posture this module
+ * takes on an unknown `shape`.
+ *
+ * @param {unknown} raw
+ * @param {{at: string, name: string, workers: Record<string, object>, environments: string[]}} ctx
+ * @returns {{workers: Array<{worker: string, environments: string[]}>, kind: string} | null}
+ */
+function normalizeCloudflareResidency(raw, { at, name, workers, environments }) {
+  if (raw === undefined || raw === null) return null;
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`${at}.residency.cloudflare must be an object with {workers, kind} (key ${name})`);
+  }
+  if (!Array.isArray(raw.workers) || raw.workers.length === 0) {
+    throw new Error(`${at}.residency.cloudflare.workers must be a non-empty array of worker ids (key ${name})`);
+  }
+  if (raw.kind !== "secret" && raw.kind !== "var") {
+    throw new Error(`${at}.residency.cloudflare.kind must be "secret" or "var" (key ${name})`);
+  }
+
+  const seenWorkers = new Set();
+  const normalized = raw.workers.map((entry, j) => {
+    const where = `${at}.residency.cloudflare.workers[${j}]`;
+    let worker;
+    let authoredEnvs;
+    if (typeof entry === "string") {
+      worker = entry;
+    } else if (entry && typeof entry === "object" && !Array.isArray(entry)) {
+      worker = entry.worker;
+      authoredEnvs = entry.environments;
+    } else {
+      throw new Error(`${where} must be a worker id string or {worker, environments} (key ${name})`);
+    }
+
+    if (typeof worker !== "string" || !Object.hasOwn(workers, worker)) {
+      throw new Error(
+        `${at}.residency.cloudflare.workers references unknown worker id ${JSON.stringify(worker)} (key ${name})`
+      );
+    }
+    if (seenWorkers.has(worker)) {
+      throw new Error(
+        `${at}.residency.cloudflare repeats the worker "${worker}" — declare one entry per worker (key ${name})`
+      );
+    }
+    seenWorkers.add(worker);
+
+    if (authoredEnvs !== undefined) {
+      if (!Array.isArray(authoredEnvs) || !authoredEnvs.every((e) => typeof e === "string")) {
+        throw new Error(`${where}.environments must be an array of environment slugs (key ${name})`);
+      }
+      if (authoredEnvs.length === 0) {
+        throw new Error(
+          `${where}.environments must not be empty — omit it to mean every environment, or drop the entry (key ${name})`
+        );
+      }
+      for (const e of authoredEnvs) {
+        if (!environments.includes(e)) {
+          throw new Error(`${where}.environments names "${e}", absent from manifest.environments (key ${name})`);
+        }
+      }
+    }
+
+    return { worker, environments: authoredEnvs ? [...authoredEnvs] : [...environments] };
+  });
+
+  return { workers: normalized, kind: raw.kind };
+}
+
 /**
  * @param {unknown} entry
  * @param {number} index
@@ -494,20 +591,7 @@ function validateKeyEntry(entry, index, workers, environments, seen) {
 
   const github = normalizeGitHubResidency(residency.github, { at, name, environments });
 
-  const cloudflare = residency.cloudflare ?? null;
-  if (cloudflare !== null) {
-    if (!Array.isArray(cloudflare.workers) || cloudflare.workers.length === 0) {
-      throw new Error(`${at}.residency.cloudflare.workers must be a non-empty array of worker ids (key ${name})`);
-    }
-    for (const id of cloudflare.workers) {
-      if (!Object.hasOwn(workers, id)) {
-        throw new Error(`${at}.residency.cloudflare.workers references unknown worker id "${id}" (key ${name})`);
-      }
-    }
-    if (cloudflare.kind !== "secret" && cloudflare.kind !== "var") {
-      throw new Error(`${at}.residency.cloudflare.kind must be "secret" or "var" (key ${name})`);
-    }
-  }
+  const cloudflare = normalizeCloudflareResidency(residency.cloudflare, { at, name, workers, environments });
 
   const infisical = normalizeInfisicalResidency(entry.infisical, { at, name, environments });
 
@@ -530,7 +614,7 @@ function validateKeyEntry(entry, index, workers, environments, seen) {
     residency: {
       local,
       github,
-      cloudflare: cloudflare ? { workers: [...cloudflare.workers], kind: cloudflare.kind } : null,
+      cloudflare,
     },
     infisical,
     shape: entry.shape ?? null,
@@ -980,7 +1064,13 @@ export function runOfflineChecks({ manifest, repoRoot }) {
     checked.push(`wrangler:${id}`);
     const present = new Set(parseWranglerVars(readFileSync(configPath, "utf8"), configPath));
     const expected = manifest.keys.filter(
-      (k) => k.residency.cloudflare?.kind === "var" && k.residency.cloudflare.workers.includes(id)
+      // Environment-agnostic by design: this check reports `environment: null`
+      // and `parseWranglerVars` flattens `[env.X.vars]` into one set, so there
+      // is no environment axis to narrow against. A var declared for ANY
+      // environment stays expected in that worker's config.
+      (k) =>
+        k.residency.cloudflare?.kind === "var" &&
+        k.residency.cloudflare.workers.some((w) => w.worker === id)
     );
     for (const key of expected) {
       if (!present.has(key.name)) {
@@ -1417,10 +1507,37 @@ async function probeGitHub({ manifest, environments, github, surfaces, findings,
 }
 
 /**
+ * Reconcile the Cloudflare surface per `(worker, environment)` pair.
+ *
+ * `expected` is narrowed to the keys whose residency names BOTH this worker
+ * and this environment, so a deliberate single-environment placement no longer
+ * reports `missing` from the environments it never claimed (Story #481).
+ *
+ * Two consequences of that narrowing are load-bearing, and neither is
+ * incidental:
+ *
+ *   1. **A worker is still probed in an environment it expects nothing in**,
+ *      as long as it expects something SOMEWHERE. Skipping it would take the
+ *      surface's most interesting finding with it: a production-only key
+ *      turning up in staging is undeclared presence, and only an
+ *      empty-`expected` reconcile against a non-empty `present` reports it.
+ *      Cross-environment orphans go unsuppressed here exactly as they do on
+ *      the GitHub and Infisical surfaces. A worker that declares nothing in
+ *      any environment is still skipped entirely — that is the manifest
+ *      saying it has no opinion, which is not the same statement.
+ *   2. **A 404 is only a finding where something WAS expected.** A worker
+ *      deployed to one environment by design 404s in the other, and with
+ *      nothing declared there that agrees with the manifest rather than
+ *      contradicting it. Reporting it would re-introduce, one layer down, the
+ *      same false failure this narrowing removes.
+ *
  * @param {object} ctx
  */
 async function probeCloudflare({ manifest, environments, cloudflare, surfaces, findings, unavailability = {} }) {
   const cfKeys = manifest.keys.filter((k) => k.residency.cloudflare?.kind === "secret");
+  /** Does any key declare this worker in any environment at all? */
+  const declaresWorker = (id) =>
+    cfKeys.some((k) => k.residency.cloudflare.workers.some((w) => w.worker === id));
   if (!cloudflare) {
     surfaces.push({
       surface: "cloudflare",
@@ -1432,8 +1549,12 @@ async function probeCloudflare({ manifest, environments, cloudflare, surfaces, f
   try {
     for (const environment of environments) {
       for (const [id, worker] of Object.entries(manifest.workers)) {
-        const expected = cfKeys.filter((k) => k.residency.cloudflare.workers.includes(id)).map((k) => k.name);
-        if (expected.length === 0) continue;
+        const expected = cfKeys
+          .filter((k) =>
+            k.residency.cloudflare.workers.some((w) => w.worker === id && w.environments.includes(environment))
+          )
+          .map((k) => k.name);
+        if (!declaresWorker(id)) continue;
         const scriptName = resolveScriptName(worker.scriptName, environment);
         let present;
         try {
@@ -1441,15 +1562,20 @@ async function probeCloudflare({ manifest, environments, cloudflare, surfaces, f
         } catch (err) {
           if (!isAbsentStatus(err)) throw err;
           // A 404 is the one status that legitimately means "absent": the
-          // Worker has not been deployed to this environment yet.
-          findings.push({
-            severity: "fail",
-            kind: "missing",
-            key: null,
-            surface: "cloudflare",
-            environment,
-            detail: `Worker script "${scriptName}" does not exist (404) — ${expected.length} declared secret(s) cannot be verified`,
-          });
+          // Worker has not been deployed to this environment yet. That is only
+          // drift where the manifest expected something here; a worker
+          // deliberately absent from an environment it declares nothing in is
+          // agreement, not a finding.
+          if (expected.length > 0) {
+            findings.push({
+              severity: "fail",
+              kind: "missing",
+              key: null,
+              surface: "cloudflare",
+              environment,
+              detail: `Worker script "${scriptName}" does not exist (404) — ${expected.length} declared secret(s) cannot be verified`,
+            });
+          }
           continue;
         }
         findings.push(

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");
+});