mandrel-platform 1.9.0 → 1.10.0

package/package.json

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

package/scripts/env-doctor.mjs

@@ -121,6 +121,8 @@ export const SHAPE_NAMES = Object.freeze(Object.keys(SHAPE_VOCABULARY));
  */
 export const MANIFEST_SCHEMA = Object.freeze({
   environments: "string[] — environment slugs, e.g. ['staging','production']",
+  environmentSlugs:
+    "object? — surface name -> {environment: slug}. Only 'infisical' is honored; an unmapped environment resolves to itself.",
   workers:
     "object? — worker id -> {config, scriptName}. `scriptName` may contain '{env}', substituted per environment.",
   keys: "object[] — one entry per env var / secret (see KEY_SCHEMA)",
@@ -132,12 +134,97 @@ export const KEY_SCHEMA = Object.freeze({
   sensitivity: "'public' | 'secret'",
   residency:
     "object — {local: 'var'|'secret'|'file'|null, github: G|G[]|null where G = {scope,kind,environments?}, cloudflare: {workers,kind}|null}",
-  infisical: "{folder, environments} | 'unmanaged'",
+  infisical:
+    "{folder, environments} | {folders: (string | {folder, environments})[]} | 'unmanaged'",
   shape: `string? — one of ${SHAPE_NAMES.join(", ")}`,
   placeholderPattern: "string? — literal, case-insensitive substring marking an unset placeholder value",
   note: "string? — free text",
 });
 
+/**
+ * The surfaces whose environment namespace can be remapped.
+ *
+ * `manifest.environments` names DEPLOY environments, and until Story #464 that
+ * one list was substituted verbatim into three namespaces that are not the
+ * same namespace — the Worker script name, the GitHub Environment API path,
+ * and the Infisical environment slug. A project whose Infisical slugs differ
+ * from its deploy names (`prod` against a `production` environment) could not
+ * be probed at all: the surface went to `error`, which is deliberately
+ * unsuppressable, so the lane was permanently red with no downstream fix.
+ *
+ * Only `infisical` is remappable, and deliberately so. Cloudflare already has
+ * its own escape hatch — `resolveScriptName` substitutes `{env}` into
+ * `workers[].scriptName`, so `acme-site-{env}` resolves whatever the deploy
+ * name is — and giving it a slug map too would be two mechanisms for one job.
+ * The GitHub Environment API is read at `manifest.environments` verbatim and
+ * no divergence has been observed there. The CONTAINER is nonetheless keyed by
+ * surface rather than being an Infisical-only field, so a surface that ever
+ * does diverge adopts it without inventing a second idiom.
+ */
+export const SLUG_MAPPED_SURFACES = Object.freeze(["infisical"]);
+
+/**
+ * Normalize `manifest.environmentSlugs` to a total map over the slug-mapped
+ * surfaces, so a caller never has to distinguish "absent" from "empty".
+ *
+ * Validation fails closed, matching this module's posture on an unknown
+ * `shape`: silently ignoring a misspelled surface or environment is how a
+ * manifest author comes to believe they have remapped something they have not,
+ * and the symptom — a 404 from the store — looks nothing like the cause.
+ *
+ * @param {unknown} raw
+ * @param {string[]} environments
+ * @returns {Record<string, Record<string, string>>}
+ */
+function normalizeEnvironmentSlugs(raw, environments) {
+  const out = {};
+  for (const surface of SLUG_MAPPED_SURFACES) out[surface] = {};
+  if (raw === undefined || raw === null) return out;
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("manifest.environmentSlugs must be an object mapping a surface name -> {environment: slug}");
+  }
+
+  for (const [surface, map] of Object.entries(raw)) {
+    if (!SLUG_MAPPED_SURFACES.includes(surface)) {
+      throw new Error(
+        `manifest.environmentSlugs."${surface}" is not a slug-mapped surface — supported: ` +
+          `${SLUG_MAPPED_SURFACES.join(", ")}. Cloudflare resolves each environment through the ` +
+          `"{env}" substitution in workers[].scriptName, and the GitHub Environment API is read at ` +
+          `manifest.environments verbatim, so neither takes a slug map.`
+      );
+    }
+    if (!map || typeof map !== "object" || Array.isArray(map)) {
+      throw new Error(`manifest.environmentSlugs.${surface} must be an object mapping environment -> slug`);
+    }
+    for (const [environment, slug] of Object.entries(map)) {
+      if (!environments.includes(environment)) {
+        throw new Error(
+          `manifest.environmentSlugs.${surface} maps "${environment}", absent from manifest.environments`
+        );
+      }
+      if (typeof slug !== "string" || !slug) {
+        throw new Error(`manifest.environmentSlugs.${surface}["${environment}"] must be a non-empty slug string`);
+      }
+      out[surface][environment] = slug;
+    }
+  }
+  return out;
+}
+
+/**
+ * Resolve the slug one surface uses for a manifest environment. Identity for
+ * any environment the manifest does not remap, which is what keeps an absent
+ * `environmentSlugs` a no-op for every manifest written before Story #464.
+ *
+ * @param {object} manifest  A parsed manifest.
+ * @param {string} surface
+ * @param {string} environment
+ * @returns {string}
+ */
+export function resolveSurfaceEnvironment(manifest, surface, environment) {
+  return manifest?.environmentSlugs?.[surface]?.[environment] ?? environment;
+}
+
 /**
  * Parse and validate a raw manifest object. Throws with an actionable message
  * on any violation — a manifest is authored by hand, so a vague error costs a
@@ -175,10 +262,12 @@ export function parseManifest(raw) {
     throw new Error("manifest.keys must be a non-empty array");
   }
 
+  const environmentSlugs = normalizeEnvironmentSlugs(raw.environmentSlugs, environments);
+
   const seen = new Set();
   const keys = raw.keys.map((entry, i) => validateKeyEntry(entry, i, workers, environments, seen));
 
-  return { environments: [...environments], workers, keys };
+  return { environments: [...environments], environmentSlugs, workers, keys };
 }
 
 /**
@@ -271,6 +360,102 @@ function normalizeGitHubResidency(raw, { at, name, environments }) {
   });
 }
 
+/**
+ * Normalize `infisical` residency to its canonical `{folders: [...]}` form.
+ *
+ * The field accepts EITHER a single `{folder, environments}` object — the shape
+ * every manifest written before Story #464 uses — or `{folders: [...]}` whose
+ * entries are a bare folder path or a `{folder, environments}` object, because
+ * two residencies that occur in practice cannot be said with one folder:
+ *
+ *   1. **Multi-folder residency.** A key can legitimately be resident in more
+ *      than one folder, and folder IMPORTS are what make that normal rather
+ *      than sloppy: when `/cloudflare` imports `/shared`, a value entering at
+ *      `/shared` is genuinely read through `/cloudflare` as well. Both
+ *      statements are true and one field could hold only one, so the same
+ *      misplacement was counted TWICE — `missing` from the declared folder and
+ *      `orphan` in the folder that actually held it.
+ *   2. **Per-environment residency.** A key can live in a different folder per
+ *      environment (an operator-held credential that arrives via `/github` in
+ *      staging only). With no per-entry `environments`, one of the two folders
+ *      was always wrong.
+ *
+ * Both authored shapes normalize to one array of `{folder, environments}` with
+ * `environments` defaulted and materialized to `manifest.environments`, so
+ * `probeInfisical` has exactly one shape to read — the same normalize-at-parse
+ * treatment `residency.github` received in Story #459, so there is one
+ * precedent for expressive residency rather than two idioms.
+ *
+ * @param {unknown} raw
+ * @param {{at: string, name: string, environments: string[]}} ctx
+ * @returns {"unmanaged" | {folders: Array<{folder: string, environments: string[]}>}}
+ */
+function normalizeInfisicalResidency(raw, { at, name, environments }) {
+  if (raw === undefined || raw === null || raw === "unmanaged") return "unmanaged";
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`${at}.infisical must be "unmanaged", {folder, environments} or {folders: [...]} (key ${name})`);
+  }
+
+  const hasFolder = raw.folder !== undefined;
+  const hasFolders = raw.folders !== undefined;
+  if (hasFolder && hasFolders) {
+    throw new Error(`${at}.infisical declares both "folder" and "folders" — use one or the other (key ${name})`);
+  }
+  if (!hasFolder && !hasFolders) {
+    throw new Error(`${at}.infisical must declare "folder" or "folders", or be "unmanaged" (key ${name})`);
+  }
+
+  let authored;
+  if (hasFolder) {
+    authored = [{ folder: raw.folder, environments: raw.environments, where: `${at}.infisical` }];
+  } else {
+    if (!Array.isArray(raw.folders) || raw.folders.length === 0) {
+      throw new Error(
+        `${at}.infisical.folders must be a non-empty array — use "unmanaged" when the key does not ` +
+          `belong in Infisical (key ${name})`
+      );
+    }
+    if (raw.environments !== undefined) {
+      throw new Error(
+        `${at}.infisical.environments is meaningful only beside a single "folder" — under "folders" ` +
+          `each entry carries its own environments (key ${name})`
+      );
+    }
+    authored = raw.folders.map((folderEntry, j) => {
+      const where = `${at}.infisical.folders[${j}]`;
+      if (typeof folderEntry === "string") return { folder: folderEntry, environments: undefined, where };
+      if (!folderEntry || typeof folderEntry !== "object" || Array.isArray(folderEntry)) {
+        throw new Error(`${where} must be a folder path string or {folder, environments} (key ${name})`);
+      }
+      return { folder: folderEntry.folder, environments: folderEntry.environments, where };
+    });
+  }
+
+  const seenFolders = new Set();
+  const folders = authored.map(({ folder, environments: authoredEnvs, where }) => {
+    if (typeof folder !== "string" || !folder) {
+      throw new Error(`${where}.folder must be a non-empty folder path string (key ${name})`);
+    }
+    if (seenFolders.has(folder)) {
+      throw new Error(`${at}.infisical repeats the folder "${folder}" — declare one entry per folder (key ${name})`);
+    }
+    seenFolders.add(folder);
+
+    const envs = authoredEnvs ?? environments;
+    if (!Array.isArray(envs) || !envs.every((e) => typeof e === "string")) {
+      throw new Error(`${at}.infisical.environments must be an array of environment slugs (key ${name})`);
+    }
+    for (const e of envs) {
+      if (!environments.includes(e)) {
+        throw new Error(`${at}.infisical.environments names "${e}", absent from manifest.environments (key ${name})`);
+      }
+    }
+    return { folder, environments: [...envs] };
+  });
+
+  return { folders };
+}
+
 /**
  * @param {unknown} entry
  * @param {number} index
@@ -324,21 +509,7 @@ function validateKeyEntry(entry, index, workers, environments, seen) {
     }
   }
 
-  const infisical = entry.infisical ?? "unmanaged";
-  if (infisical !== "unmanaged") {
-    if (!infisical || typeof infisical !== "object" || typeof infisical.folder !== "string") {
-      throw new Error(`${at}.infisical must be "unmanaged" or {folder, environments} (key ${name})`);
-    }
-    const envs = infisical.environments ?? environments;
-    if (!Array.isArray(envs) || !envs.every((e) => typeof e === "string")) {
-      throw new Error(`${at}.infisical.environments must be an array of environment slugs (key ${name})`);
-    }
-    for (const e of envs) {
-      if (!environments.includes(e)) {
-        throw new Error(`${at}.infisical.environments names "${e}", absent from manifest.environments (key ${name})`);
-      }
-    }
-  }
+  const infisical = normalizeInfisicalResidency(entry.infisical, { at, name, environments });
 
   if (entry.shape !== undefined) {
     if (typeof entry.shape !== "string" || !Object.hasOwn(SHAPE_VOCABULARY, entry.shape)) {
@@ -361,10 +532,7 @@ function validateKeyEntry(entry, index, workers, environments, seen) {
       github,
       cloudflare: cloudflare ? { workers: [...cloudflare.workers], kind: cloudflare.kind } : null,
     },
-    infisical:
-      infisical === "unmanaged"
-        ? "unmanaged"
-        : { folder: infisical.folder, environments: [...(infisical.environments ?? environments)] },
+    infisical,
     shape: entry.shape ?? null,
     placeholderPattern: entry.placeholderPattern ?? null,
     note: typeof entry.note === "string" ? entry.note : null,
@@ -1305,6 +1473,48 @@ async function probeCloudflare({ manifest, environments, cloudflare, surfaces, f
   }
 }
 
+/**
+ * Does a key declare residency at this folder in this environment?
+ *
+ * @param {object} key   A parsed manifest key with normalized infisical residency.
+ * @param {string} folder
+ * @param {string} environment
+ * @returns {boolean}
+ */
+function residentAt(key, folder, environment) {
+  return key.infisical.folders.some((f) => f.folder === folder && f.environments.includes(environment));
+}
+
+/**
+ * Names declared in a SIBLING declared folder of the same environment.
+ *
+ * Infisical is probed once per (environment, folder) pair, so a key resident
+ * in two folders is read in two partitions — and reporting it as an orphan in
+ * the one the manifest happens not to be reconciling is the false positive the
+ * `folders` array exists to remove. Suppression is deliberately no wider:
+ *
+ * - **Cross-folder, same environment** is suppressed: that is multi-folder
+ *   residency, including the folder-import case.
+ * - **Cross-environment is NOT suppressed.** A key declared for staging only
+ *   but present in production is undeclared presence in that environment —
+ *   the most interesting thing this surface can find — so it still orphans.
+ *
+ * A name declared in no folder at all orphans exactly as before, which is what
+ * keeps `--strict-orphans` worth enabling once a manifest is correct. This is
+ * the `declaredElsewhere` treatment `probeGitHub` has had since Story #459;
+ * its absence here is why a single misplacement was reported twice.
+ *
+ * @param {object[]} managed
+ * @param {string} folder
+ * @param {string} environment
+ * @returns {string[]}
+ */
+function infisicalNamesElsewhere(managed, folder, environment) {
+  return managed
+    .filter((k) => k.infisical.folders.some((f) => f.folder !== folder && f.environments.includes(environment)))
+    .map((k) => k.name);
+}
+
 /**
  * The Infisical probe, plus the shape stage — the only place a value is read.
  *
@@ -1321,27 +1531,39 @@ async function probeInfisical({ manifest, environments, infisical, surfaces, fin
     return;
   }
   try {
-    const folders = new Set(managed.map((k) => k.infisical.folder));
+    const folders = new Set(managed.flatMap((k) => k.infisical.folders.map((f) => f.folder)));
     const shapeChecked = [];
+    // A key resident in several folders is READ in each of them, but its value
+    // is one value — so it earns at most one shape verdict per environment.
+    // Scoring it once per folder would re-introduce, in the shape stage, the
+    // very double-reporting this Story removes from the residency stage.
+    const shapeSeen = new Set();
     for (const environment of environments) {
+      // The store's own environment slug, which need not be the deploy name.
+      const slug = resolveSurfaceEnvironment(manifest, "infisical", environment);
       for (const folder of folders) {
-        const expected = managed
-          .filter((k) => k.infisical.folder === folder && k.infisical.environments.includes(environment))
-          .map((k) => k.name);
-        const present = await infisical.listNames({ environment, folder });
+        const expected = managed.filter((k) => residentAt(k, folder, environment)).map((k) => k.name);
+        const present = await infisical.listNames({ environment: slug, folder });
         findings.push(
-          ...reconcileNames({ expected, present, surface: "infisical", environment, scope: `folder ${folder}` })
+          ...reconcileNames({
+            expected,
+            present,
+            surface: "infisical",
+            environment,
+            scope: `folder ${folder}`,
+            declaredElsewhere: infisicalNamesElsewhere(managed, folder, environment),
+          })
         );
 
         // Shape stage. Values enter this scope and leave it as verdicts.
         const needShape = managed.filter(
           (k) =>
-            k.infisical.folder === folder &&
-            k.infisical.environments.includes(environment) &&
-            (k.shape || k.placeholderPattern)
+            residentAt(k, folder, environment) &&
+            (k.shape || k.placeholderPattern) &&
+            !shapeSeen.has(`${environment}\u241f${k.name}`)
         );
         if (needShape.length === 0) continue;
-        const values = await infisical.listValues({ environment, folder });
+        const values = await infisical.listValues({ environment: slug, folder });
         for (const key of needShape) {
           if (!values.has(key.name)) continue;
           const verdict = checkShape({
@@ -1350,6 +1572,7 @@ async function probeInfisical({ manifest, environments, infisical, surfaces, fin
             placeholderPattern: key.placeholderPattern,
           });
           shapeChecked.push(key.name);
+          shapeSeen.add(`${environment}\u241f${key.name}`);
           if (!verdict.ok) {
             findings.push({
               severity: "fail",

package/scripts/env-doctor.test.mjs

@@ -31,7 +31,9 @@ import { promisify } from "node:util";
 import { test } from "node:test";
 
 import {
+  KEY_SCHEMA,
   MANIFEST_SCHEMA,
+  SLUG_MAPPED_SURFACES,
   SHAPE_NAMES,
   SHAPE_VOCABULARY,
   applyExceptions,
@@ -49,6 +51,7 @@ import {
   redactUrl,
   renderReport,
   resolveScriptName,
+  resolveSurfaceEnvironment,
   runDoctor,
   runOfflineChecks,
 } from "./env-doctor.mjs";
@@ -1043,6 +1046,388 @@ test("no secret VALUE reaches stdout or stderr on a real run against a mock Infi
   }
 });
 
+// ---------------------------------------------------------------------------
+// Infisical environment slugs and folder residency (Story #464)
+// ---------------------------------------------------------------------------
+
+/**
+ * A manifest with no local residency and no GitHub residency, so every finding
+ * under test comes from the Infisical probe. One Worker is kept so the
+ * Cloudflare surface can be asserted to keep the DEPLOY name while Infisical
+ * is asked for the mapped slug.
+ */
+function infisicalOnlyManifest(infisical, { environmentSlugs, keys } = {}) {
+  return parseManifest({
+    environments: ["staging", "production"],
+    ...(environmentSlugs ? { environmentSlugs } : {}),
+    workers: { site: { scriptName: "acme-site-{env}" } },
+    keys:
+      keys ??
+      [
+        {
+          name: "SHARED_TOKEN",
+          kind: "secret",
+          sensitivity: "secret",
+          residency: { local: null, github: null, cloudflare: null },
+          infisical,
+        },
+      ],
+  });
+}
+
+/**
+ * Run the Infisical probe against a `{ "<environment-slug><folder>": [names] }`
+ * map, recording every (environment, folder) pair the client was asked for.
+ * The map is keyed by the slug the CLIENT sees, which is the whole point: a
+ * remapped environment must be looked up under its store slug.
+ */
+async function infisicalRun({ manifest, present, environments = ["staging", "production"], cloudflare = null }) {
+  const root = makeRepo({});
+  const asked = [];
+  try {
+    const report = await runDoctor({
+      manifest,
+      repoRoot: root,
+      environments,
+      cloudflare,
+      infisical: {
+        listNames: async ({ environment, folder }) => {
+          asked.push(`${environment}${folder}`);
+          return present[`${environment}${folder}`] ?? [];
+        },
+        listValues: async () => new Map(),
+      },
+    });
+    return { asked, findings: report.findings.filter((f) => f.surface === "infisical"), report };
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+test("a remapped Infisical slug is probed at the slug while Cloudflare keeps the deploy name", async () => {
+  // The motivating case: deploy environments are staging/production, but the
+  // Infisical project's slugs are staging/prod. Before this, `production`
+  // reached Infisical verbatim and 404'd the whole surface into `error`.
+  const scripts = [];
+  const { asked } = await infisicalRun({
+    manifest: infisicalOnlyManifest(
+      { folder: "/shared" },
+      { environmentSlugs: { infisical: { production: "prod" } } }
+    ),
+    present: { "staging/shared": ["SHARED_TOKEN"], "prod/shared": ["SHARED_TOKEN"] },
+    cloudflare: {
+      secretNames: async (scriptName) => {
+        scripts.push(scriptName);
+        return [];
+      },
+    },
+  });
+
+  assert.deepEqual(asked, ["staging/shared", "prod/shared"]);
+  assert.ok(!asked.some((a) => a.startsWith("production")), "the deploy name must not reach Infisical");
+  // The Cloudflare surface resolves {env} from the DEPLOY name, unmapped —
+  // which is why it needs no slug map of its own.
+  assert.deepEqual(scripts, []);
+});
+
+test("a manifest declaring a Cloudflare secret still resolves {env} from the unmapped deploy name", async () => {
+  const scripts = [];
+  await infisicalRun({
+    manifest: infisicalOnlyManifest(undefined, {
+      environmentSlugs: { infisical: { production: "prod" } },
+      keys: [
+        {
+          name: "SHARED_TOKEN",
+          kind: "secret",
+          sensitivity: "secret",
+          residency: { local: null, github: null, cloudflare: { workers: ["site"], kind: "secret" } },
+          infisical: { folder: "/shared" },
+        },
+      ],
+    }),
+    present: {},
+    cloudflare: {
+      secretNames: async (scriptName) => {
+        scripts.push(scriptName);
+        return ["SHARED_TOKEN"];
+      },
+    },
+  });
+  assert.deepEqual(scripts, ["acme-site-staging", "acme-site-production"]);
+});
+
+test("environmentSlugs rejects a surface that is not slug-mapped, and names it", () => {
+  assert.throws(
+    () =>
+      infisicalOnlyManifest({ folder: "/" }, { environmentSlugs: { cloudflare: { production: "prod" } } }),
+    (err) => {
+      assert.match(err.message, /"cloudflare" is not a slug-mapped surface/);
+      assert.match(err.message, /infisical/);
+      // The message must say WHY, or the author re-files the same request.
+      assert.match(err.message, /scriptName/);
+      return true;
+    }
+  );
+});
+
+test("environmentSlugs rejects an unmapped environment and a slug that is not a non-empty string", () => {
+  assert.throws(
+    () => infisicalOnlyManifest({ folder: "/" }, { environmentSlugs: { infisical: { preview: "prev" } } }),
+    /maps "preview", absent from manifest.environments/
+  );
+  assert.throws(
+    () => infisicalOnlyManifest({ folder: "/" }, { environmentSlugs: { infisical: { production: "" } } }),
+    /must be a non-empty slug string/
+  );
+  assert.throws(
+    () => infisicalOnlyManifest({ folder: "/" }, { environmentSlugs: { infisical: { production: 7 } } }),
+    /must be a non-empty slug string/
+  );
+  assert.throws(
+    () => infisicalOnlyManifest({ folder: "/" }, { environmentSlugs: { infisical: ["prod"] } }),
+    /must be an object mapping environment -> slug/
+  );
+});
+
+test("with no environmentSlugs every environment resolves to itself", async () => {
+  const manifest = infisicalOnlyManifest({ folder: "/shared" });
+  // The container is normalized to a total-but-empty map, so no caller has to
+  // distinguish "absent" from "empty".
+  assert.deepEqual(manifest.environmentSlugs, { infisical: {} });
+  assert.equal(resolveSurfaceEnvironment(manifest, "infisical", "production"), "production");
+  const { asked } = await infisicalRun({ manifest, present: { "staging/shared": ["SHARED_TOKEN"] } });
+  assert.deepEqual(asked, ["staging/shared", "production/shared"]);
+});
+
+test("parseManifest normalizes the single-object infisical form to a one-entry folders array", () => {
+  // The pre-#464 authored shape, parsed: one shape reaches probeInfisical, the
+  // same treatment residency.github received in #459.
+  const m = infisicalOnlyManifest({ folder: "/shared", environments: ["production"] });
+  assert.deepEqual(m.keys[0].infisical, { folders: [{ folder: "/shared", environments: ["production"] }] });
+
+  const defaulted = infisicalOnlyManifest({ folder: "/shared" });
+  assert.deepEqual(defaulted.keys[0].infisical, {
+    folders: [{ folder: "/shared", environments: ["staging", "production"] }],
+  });
+});
+
+test("the folders array accepts bare paths and per-entry environments", () => {
+  const m = infisicalOnlyManifest({
+    folders: ["/shared", { folder: "/github", environments: ["staging"] }],
+  });
+  assert.deepEqual(m.keys[0].infisical, {
+    folders: [
+      { folder: "/shared", environments: ["staging", "production"] },
+      { folder: "/github", environments: ["staging"] },
+    ],
+  });
+});
+
+test("a key resident in two folders and present in both reports no finding", async () => {
+  // The folder-import case: /cloudflare imports /shared, so the value is
+  // genuinely readable through both. Both statements are true.
+  const { findings } = await infisicalRun({
+    manifest: infisicalOnlyManifest({ folders: ["/shared", "/cloudflare"] }),
+    present: {
+      "staging/shared": ["SHARED_TOKEN"],
+      "staging/cloudflare": ["SHARED_TOKEN"],
+      "production/shared": ["SHARED_TOKEN"],
+      "production/cloudflare": ["SHARED_TOKEN"],
+    },
+  });
+  assert.deepEqual(findings, []);
+});
+
+test("a misplacement across two declared folders is reported ONCE, as the missing", async () => {
+  // Declared in /shared, actually resident in /cloudflare. Before #464 this
+  // was two findings for one fact — a missing AND an orphan — and the orphan
+  // was unsuppressable by an exception, so --strict-orphans could never go
+  // green on a manifest that was merely imprecise about placement.
+  const { findings } = await infisicalRun({
+    manifest: infisicalOnlyManifest({ folders: ["/shared", "/cloudflare"] }),
+    present: {
+      "staging/cloudflare": ["SHARED_TOKEN"],
+      "production/cloudflare": ["SHARED_TOKEN"],
+    },
+    environments: ["staging"],
+  });
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].kind, "missing");
+  assert.equal(findings[0].key, "SHARED_TOKEN");
+  assert.match(findings[0].detail, /folder \/shared/);
+  assert.equal(
+    findings.filter((f) => f.kind === "orphan").length,
+    0,
+    "the sibling declared folder must not also orphan the same key"
+  );
+});
+
+test("suppression does not cross environment — a staging-only key found in production orphans", async () => {
+  // SHARED_TOKEN is declared in /github for staging only. Finding it in
+  // /shared in production is undeclared presence in that environment, which
+  // is the most interesting thing this surface can report.
+  const { findings } = await infisicalRun({
+    manifest: infisicalOnlyManifest({
+      folders: [{ folder: "/github", environments: ["staging"] }, { folder: "/shared", environments: ["staging"] }],
+    }),
+    present: {
+      "staging/github": ["SHARED_TOKEN"],
+      "staging/shared": ["SHARED_TOKEN"],
+      "production/shared": ["SHARED_TOKEN"],
+    },
+  });
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].kind, "orphan");
+  assert.equal(findings[0].environment, "production");
+});
+
+test("a per-environment folder entry reports no missing for an environment it never names", async () => {
+  const { findings } = await infisicalRun({
+    manifest: infisicalOnlyManifest({ folders: [{ folder: "/operator", environments: ["production"] }] }),
+    present: { "production/operator": ["SHARED_TOKEN"] },
+  });
+  assert.deepEqual(findings, []);
+});
+
+test("infisical folder residency fails closed on every malformed shape", () => {
+  const bad = (infisical) => () => infisicalOnlyManifest(infisical);
+  assert.throws(bad({ folders: [] }), /folders must be a non-empty array/);
+  assert.throws(bad({ folders: ["/shared", "/shared"] }), /repeats the folder "\/shared"/);
+  assert.throws(bad({ folders: [{ folder: "/s", environments: ["preview"] }] }), /absent from manifest.environments/);
+  assert.throws(bad({ folder: "/s", folders: ["/t"] }), /declares both "folder" and "folders"/);
+  assert.throws(bad({ folders: ["/s"], environments: ["staging"] }), /meaningful only beside a single "folder"/);
+  assert.throws(bad({}), /must declare "folder" or "folders"/);
+  assert.throws(bad({ folders: [""] }), /must be a non-empty folder path string/);
+  assert.throws(bad({ folders: [42] }), /must be a folder path string or \{folder, environments\}/);
+  assert.throws(bad("nope"), /must be "unmanaged", \{folder, environments\} or \{folders: \[\.\.\.\]\}/);
+  // Unchanged from before #464: the single-object form's own env validation.
+  assert.throws(bad({ folder: "/s", environments: ["preview"] }), /absent from manifest.environments/);
+});
+
+test("a multi-folder key with a shape earns ONE verdict per environment, not one per folder", async () => {
+  // A key resident in two folders is READ twice, but it is one value — so
+  // scoring it per folder would re-introduce double-reporting in the shape
+  // stage, the very defect #464 removes from the residency stage.
+  const root = makeRepo({});
+  try {
+    const manifest = infisicalOnlyManifest(undefined, {
+      keys: [
+        {
+          name: "SHARED_TOKEN",
+          kind: "var",
+          sensitivity: "public",
+          residency: { local: null, github: null, cloudflare: null },
+          infisical: { folders: ["/shared", "/cloudflare"] },
+          shape: "url",
+        },
+      ],
+    });
+    const report = await runDoctor({
+      manifest,
+      repoRoot: root,
+      environments: ["staging"],
+      infisical: {
+        listNames: async () => ["SHARED_TOKEN"],
+        listValues: async () => new Map([["SHARED_TOKEN", "example.test"]]),
+      },
+    });
+    const shapeFails = report.findings.filter((f) => f.kind === "shape-fail");
+    assert.equal(shapeFails.length, 1, "one value, one verdict");
+    assert.equal(shapeFails[0].key, "SHARED_TOKEN");
+  } 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/);
+  assert.match(KEY_SCHEMA.infisical, /folders/);
+  assert.deepEqual(SLUG_MAPPED_SURFACES, ["infisical"]);
+});
+
+test("the documented manifest schema block names the new shapes", () => {
+  // The script exports the schema so the doc and the code describe one shape;
+  // this asserts the DOC kept its half of that bargain.
+  const doc = readFileSync(join(HERE, "..", "docs", "reusable-workflows.md"), "utf8");
+  assert.match(doc, /"environmentSlugs"/);
+  assert.match(doc, /"folders"/);
+});
+
+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
+  // low-entropy dictionary canaries as the sibling leak test, for the same
+  // reason (a key-shaped fixture is a true positive for gitleaks).
+  const INJECTED = {
+    PUBLIC_SITE_URL: "example.test/no-scheme-here",
+    TURSO_AUTH_TOKEN: "second-canary-that-must-never-be-printed",
+  };
+  const requested = [];
+
+  const server = createServer((req, res) => {
+    if (req.method === "POST" && req.url.startsWith("/api/v1/auth/universal-auth/login")) {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ accessToken: "mock-token", expiresIn: 3600, tokenType: "Bearer" }));
+      return;
+    }
+    if (req.url.startsWith("/api/v4/secrets")) {
+      const params = new URL(req.url, "http://localhost").searchParams;
+      requested.push(`${params.get("environment")}${params.get("secretPath")}`);
+      const withValues = params.get("viewSecretValue") === "true";
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify({
+          secrets: Object.entries(INJECTED).map(([secretKey, secretValue]) => ({
+            secretKey,
+            ...(withValues ? { secretValue } : {}),
+          })),
+        })
+      );
+      return;
+    }
+    res.writeHead(404).end("{}");
+  });
+  await new Promise((r) => server.listen(0, "127.0.0.1", r));
+  const site = `http://127.0.0.1:${server.address().port}`;
+
+  const raw = singleWorkerManifest();
+  raw.environmentSlugs = { infisical: { production: "prod" } };
+  for (const key of raw.keys) key.infisical = { folders: ["/", "/shared"] };
+
+  const root = makeRepo(CONSISTENT_REPO);
+  const manifestPath = join(root, "env.manifest.json");
+  writeFileSync(manifestPath, JSON.stringify(raw));
+
+  try {
+    const run = await runCli(
+      [
+        "--manifest", manifestPath,
+        "--repo-root", root,
+        "--environments", "production",
+        "--infisical-project", "proj-1",
+        "--infisical-site", site,
+        "--json",
+      ],
+      { env: { INFISICAL_CLIENT_ID: "id", INFISICAL_CLIENT_SECRET: "sec", ENV_DRIFT_GITHUB_TOKEN: "", CLOUDFLARE_API_TOKEN: "" } }
+    );
+
+    // End-to-end proof that the slug reaches the wire through the real CLI:
+    // every request names `prod`, never the `production` deploy name.
+    assert.ok(requested.length > 0, "the mock store should have been asked for something");
+    assert.deepEqual([...new Set(requested.map((r) => r.split("/")[0]))], ["prod"]);
+
+    const captured = run.stdout + run.stderr;
+    assert.ok(captured.includes("PUBLIC_SITE_URL"), "the failing key's NAME should be reported");
+    for (const [name, value] of Object.entries(INJECTED)) {
+      assert.ok(!captured.includes(value), `the VALUE of ${name} leaked into the doctor's output`);
+    }
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+    await new Promise((r) => server.close(r));
+  }
+});
+
 // ---------------------------------------------------------------------------
 // Shipped workflow shape
 // ---------------------------------------------------------------------------