mandrel-platform 1.11.0 → 1.13.0

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

@@ -0,0 +1,343 @@
+#!/usr/bin/env node
+/**
+ * check-semgrep-lockfile.test.mjs — guards the SAST toolchain lockfile
+ * (Story #477).
+ *
+ * What this pins, and why each part earned a test:
+ *
+ * 1. **The advisories stay gone.** The lockfile carried protobuf 4.25.9
+ *    (CVE-2026-0994, CVSS 8.2) and setuptools 80.9.0 (GHSA-h35f-9h28-mq5c).
+ *    Neither could be fixed in place: every protobuf 4.x is affected, and
+ *    semgrep 1.97.0's `opentelemetry-*~=1.25.0` pin capped protobuf below
+ *    every patched release. A future bump that lands back inside an affected
+ *    range would reintroduce a high with no other signal until the next
+ *    scheduled OSV scan.
+ *
+ * 2. **The pin sites cannot drift.** The semgrep version lives in THREE
+ *    places — this lockfile, `SEMGREP_PIN` in pr-quality.yml, and
+ *    `DEFAULT_SEMGREP_PIN` in update-semgrep-rules.mjs — plus the
+ *    `SEMGREP_HASHES` map that must carry digests for whatever the default is.
+ *    Nothing detected disagreement between them before this file.
+ *
+ * 3. **`--require-hashes` stays satisfiable.** Every entry must be `==`-pinned
+ *    with a sha256, or the install fails at CI time rather than here.
+ *
+ * The end-to-end proof (a real `pip install --require-hashes` on linux/cp312)
+ * cannot run in this suite — it needs that platform and a network. It is a
+ * `verify[]` step on the Story instead; these are the invariants checkable
+ * from the tree.
+ *
+ * Run: node --test scripts/check-semgrep-lockfile.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { readFileSync } from "node:fs";
+
+const LOCKFILE = "scripts/semgrep-requirements.txt";
+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
+ * continuations. Keyed by lowercased name.
+ */
+function requirements(text) {
+  /** @type {Map<string, string>} */
+  const out = new Map();
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#") || trimmed.startsWith("--hash")) {
+      continue;
+    }
+    const m = trimmed.match(/^([A-Za-z0-9._-]+)==([^\s\\]+)/);
+    if (m) {
+      out.set(m[1].toLowerCase(), m[2]);
+    }
+  }
+  return out;
+}
+
+const REQS = requirements(lockfile);
+
+/** Compare dotted release segments numerically. Returns -1 / 0 / 1. */
+function compareVersions(a, b) {
+  const pa = a.split(".").map((n) => Number.parseInt(n, 10));
+  const pb = b.split(".").map((n) => Number.parseInt(n, 10));
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const x = Number.isNaN(pa[i]) || pa[i] === undefined ? 0 : pa[i];
+    const y = Number.isNaN(pb[i]) || pb[i] === undefined ? 0 : pb[i];
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// 1. The advisories that put this Story on the board
+// ---------------------------------------------------------------------------
+
+test("protobuf is outside every CVE-2026-0994 affected range", () => {
+  // Affected: `< 5.29.6` and `>= 6.30.0rc1, <= 6.33.4`. Patched: 5.29.6, 6.33.5.
+  // A DoS in google.protobuf.json_format.ParseDict — 8.2, and the finding that
+  // opened tracking issue #472.
+  const version = REQS.get("protobuf");
+  assert.ok(version, `${LOCKFILE}: protobuf must be pinned`);
+  assert.doesNotMatch(version, /[a-zA-Z]/, "expected a final release, not a pre-release");
+
+  assert.ok(
+    compareVersions(version, "5.29.6") >= 0,
+    `protobuf ${version} is below the 5.29.6 patch — inside the "< 5.29.6" affected range`,
+  );
+  const inSixLine = compareVersions(version, "6.0.0") >= 0;
+  if (inSixLine) {
+    assert.ok(
+      compareVersions(version, "6.33.5") >= 0,
+      `protobuf ${version} is inside the ">= 6.30.0rc1, <= 6.33.4" affected range`,
+    );
+  }
+});
+
+test("setuptools is absent from the closure", () => {
+  // It was pinned to 80.9.0 only because semgrep 1.97.0's transitive
+  // opentelemetry-instrumentation imported pkg_resources at load. 0.58b0 does
+  // not, so the package — and its own advisory — leaves the graph entirely.
+  assert.equal(
+    REQS.has("setuptools"),
+    false,
+    "setuptools carries its own advisories and is no longer needed; do not re-add it without a stated reason",
+  );
+});
+
+// ---------------------------------------------------------------------------
+// 2. Drift between the three pin sites
+// ---------------------------------------------------------------------------
+
+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 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");
+
+  const updater = readFileSync(UPDATER, "utf8");
+  const up = updater.match(/const DEFAULT_SEMGREP_PIN = "semgrep==([^"]+)";/);
+  assert.ok(up, `${UPDATER}: DEFAULT_SEMGREP_PIN not found`);
+  assert.equal(up[1], lockVersion, "updater DEFAULT_SEMGREP_PIN disagrees with the lockfile");
+});
+
+test("the rules updater carries artifact hashes for the version it defaults to", () => {
+  // SEMGREP_HASHES is a fail-fast supply-chain guard: a version with no entry
+  // is rejected rather than installed unverified. A bump that moved the default
+  // without adding digests would turn that guard into a hard stop.
+  const updater = readFileSync(UPDATER, "utf8");
+  const version = REQS.get("semgrep");
+  const map = updater.slice(updater.indexOf("const SEMGREP_HASHES = {"));
+  const block = map.slice(0, map.indexOf("\n};"));
+  assert.ok(
+    block.includes(`"${version}": [`),
+    `${UPDATER}: SEMGREP_HASHES has no entry for ${version}`,
+  );
+});
+
+// ---------------------------------------------------------------------------
+// 3. --require-hashes remains satisfiable
+// ---------------------------------------------------------------------------
+
+test("every requirement is == pinned and carries a sha256 hash", () => {
+  const pins = lockfile
+    .split("\n")
+    .filter((l) => /^[A-Za-z0-9._-]+==/.test(l.trim())).length;
+  const hashes = lockfile.split("\n").filter((l) => l.trim().startsWith("--hash=sha256:")).length;
+
+  assert.ok(pins > 0, "expected at least one pinned requirement");
+  assert.equal(REQS.size, pins, "every pinned line must parse to a requirement");
+  assert.ok(
+    hashes >= pins,
+    `${hashes} hash line(s) for ${pins} requirement(s) — --require-hashes needs at least one each`,
+  );
+});
+
+test("no requirement is pinned with a loose operator", () => {
+  // `--require-hashes` rejects these at install time; catching it here names
+  // the offending line instead of failing inside CI's pip.
+  //
+  // The operator is matched by string comparison, NOT by a regex alternating
+  // `<` and `>`. CodeQL reads such a pattern as an attempted HTML-tag filter
+  // and raises js/bad-tag-filter at HIGH — which blocks the merge, since
+  // code-scanning gates on high. Comparing prefixes says the same thing with
+  // nothing for that query to match on.
+  const LOOSE_OPERATORS = [">=", "<=", "~=", "!=", ">", "<"];
+  for (const line of lockfile.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#") || trimmed.startsWith("--hash")) continue;
+    const name = trimmed.match(/^[A-Za-z0-9._-]+/);
+    if (!name) continue;
+    const operator = trimmed.slice(name[0].length).trimStart();
+    for (const loose of LOOSE_OPERATORS) {
+      assert.ok(
+        !operator.startsWith(loose),
+        `loose pin (${loose}) — --require-hashes needs an exact ==: ${trimmed}`,
+      );
+    }
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 4. The regeneration trap
+// ---------------------------------------------------------------------------
+
+test("the header warns about the manylinux_2_34 wheel tag", () => {
+  // semgrep moved its Linux wheel tag after 1.157.0. A `pip download` whose
+  // --platform list omits the new tag resolves NOTHING newer and reports only
+  // "No matching distribution found", never naming the tag as the cause.
+  const header = lockfile.slice(0, lockfile.indexOf("\n\n\n") + 1 || 4000);
+  assert.match(header, /manylinux_2_34_x86_64/, "the header must name the current wheel tag");
+  assert.match(header, /1\.157\.0/, "the header must say which version the tag changed after");
+  assert.match(
+    lockfile,
+    /pip download semgrep/,
+    "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(