@intentius/chant-lexicon-k8s 0.45.0 → 0.49.0

package/src/sops/encrypted-secret-file.ts

@@ -0,0 +1,264 @@
+/**
+ * Committed SOPS ciphertext as a build artifact (epic lex00/iac-cd-bench#6).
+ *
+ * A `declareSecret({ provenance: "committed-encrypted", file })` names a
+ * repo-relative path to ciphertext that lives in git. This module is the
+ * resolution stage: at `buildRoots()` — chant's one sanctioned impure seam,
+ * the same one the kustomize roots and cedar's `Schema` use — it reads those
+ * bytes, validates the document is what the declaration claims, and wraps
+ * them in an entity the serializer copies out VERBATIM as a sidecar file.
+ *
+ * Three properties this is built to keep:
+ *
+ * - **Never inlined.** The bytes go to `SerializerResult.files`, never into
+ *   the primary multi-document YAML. chant's own appliers read the primary
+ *   output, so "chant pushes an undecrypted Secret into a cluster" is
+ *   structurally impossible rather than merely unlikely. Flux is the only
+ *   thing that applies the sidecar, and Flux decrypts first.
+ * - **Deterministic and offline.** The bytes are copied, not re-serialized:
+ *   no parse-and-re-emit round trip, no key sorting, no digest. No `sops`
+ *   binary is invoked in either direction, so a missing binary and a missing
+ *   age key are not failure modes — the plaintext has no representation here
+ *   at any stage.
+ * - **Fails loudly, not weirdly.** A missing file, a non-Secret document, a
+ *   name mismatch, a missing `sops` block, or a `data`/`stringData` value
+ *   that is not `ENC[...]`-shaped refuses with the declared path in the
+ *   message. That last check is the one that earns the feature: it catches
+ *   "edited the file and forgot to re-encrypt", the exact failure mode that
+ *   puts plaintext into git.
+ *
+ * The entity is deliberately internal — not exported from the package entry
+ * point, not constructible by an author. The authored surface is
+ * `declareSecret`; a public entity taking inline bytes is the one thing this
+ * whole design exists to prevent.
+ *
+ * Design: docs/design/committed-encrypted-sops-provenance.md §3.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { loadAll } from "js-yaml";
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+import {
+  ENCRYPTED_SECRET_ENTITY_PREFIX,
+  ENCRYPTED_SECRET_FILE_MARKER,
+  ENCRYPTED_SECRET_FILE_TYPE,
+  sidecarFilename,
+  type EncryptedSecretFileEntity,
+} from "./entity";
+import type { BuildRootContext, BuildRootContribution } from "@intentius/chant/lexicon";
+import {
+  collectSecretDeclarations,
+  isCommittedEncryptedSecret,
+  type CommittedEncryptedSecretDeclaration,
+} from "@intentius/chant/secret-provenance";
+
+export {
+  ENCRYPTED_SECRET_FILE_MARKER,
+  ENCRYPTED_SECRET_FILE_TYPE,
+  ENCRYPTED_SECRET_ENTITY_PREFIX,
+  isEncryptedSecretFileEntity,
+  sidecarFilename,
+  type EncryptedSecretFileEntity,
+} from "./entity";
+
+/** A parsed ciphertext document, or the reasons it is not one. */
+export interface EncryptedSecretDocument {
+  /** `metadata.name`, when the document had one. */
+  name?: string;
+  /** `metadata.namespace`, when the document had one. */
+  namespace?: string;
+  /** Key names found under `data`/`stringData` — names only, never values. */
+  keys: string[];
+}
+
+/**
+ * Validate one committed ciphertext document against its declaration.
+ *
+ * Returns every problem found, so an author sees all of them at once rather
+ * than one per build. Both consumers share this: the `buildRoots()` stage
+ * turns the list into a refusal, and WK8504 turns it into diagnostics.
+ *
+ * A value is only ever tested for the `ENC[` prefix, inside this one frame,
+ * and only the offending KEY name is reported — the discipline
+ * `declareSecret`'s own runtime guard uses.
+ */
+export function validateEncryptedSecretDocument(
+  text: string,
+  declared: { name: string; file: string },
+): { problems: string[]; document?: EncryptedSecretDocument } {
+  const problems: string[] = [];
+
+  let docs: unknown[];
+  try {
+    docs = loadAll(text);
+  } catch (err) {
+    return {
+      problems: [`${declared.file} is not valid YAML: ${err instanceof Error ? err.message : String(err)}`],
+    };
+  }
+
+  const present = docs.filter((d) => d !== null && d !== undefined);
+  if (present.length === 0) {
+    return { problems: [`${declared.file} contains no YAML document`] };
+  }
+  if (present.length > 1) {
+    // v1 keys a declaration by one `name`; a declaration-per-document sharing
+    // a file, or a `names: string[]` field, is a design change to make
+    // deliberately rather than by accident.
+    return {
+      problems: [
+        `${declared.file} contains ${present.length} YAML documents — ` +
+          `a committed-encrypted declaration covers exactly one Secret`,
+      ],
+    };
+  }
+
+  const doc = present[0];
+  if (typeof doc !== "object" || doc === null || Array.isArray(doc)) {
+    return { problems: [`${declared.file} is not a Kubernetes object`] };
+  }
+  const record = doc as Record<string, unknown>;
+
+  if (record.apiVersion !== "v1" || record.kind !== "Secret") {
+    problems.push(
+      `${declared.file} is not a v1 Secret ` +
+        `(apiVersion "${String(record.apiVersion)}", kind "${String(record.kind)}")`,
+    );
+  }
+
+  const metadata = asRecord(record.metadata);
+  const name = typeof metadata?.name === "string" ? metadata.name : undefined;
+  const namespace = typeof metadata?.namespace === "string" ? metadata.namespace : undefined;
+  if (name !== declared.name) {
+    problems.push(
+      `${declared.file} has metadata.name "${name ?? "(none)"}", ` +
+        `but the declaration names "${declared.name}"`,
+    );
+  }
+
+  // SOPS's own metadata block. Its absence means the file was never encrypted
+  // (or was decrypted in place and committed), which is the whole point of
+  // checking. `sops.mac` is a MAC over the PLAINTEXT — it is carried by the
+  // verbatim copy and must never be read as a semantic value, so nothing here
+  // looks past the block's presence.
+  if (asRecord(record.sops) === undefined) {
+    problems.push(
+      `${declared.file} has no top-level \`sops\` block — it does not look encrypted. ` +
+        `Run \`sops -e -i\` before committing.`,
+    );
+  }
+
+  // Scoped to data/stringData alone: SOPS's `encrypted_regex` leaves
+  // apiVersion, kind and metadata cleartext by design.
+  const keys: string[] = [];
+  for (const field of ["data", "stringData"] as const) {
+    const block = asRecord(record[field]);
+    if (block === undefined) continue;
+    for (const [key, value] of Object.entries(block)) {
+      keys.push(key);
+      if (typeof value !== "string" || !value.startsWith("ENC[")) {
+        problems.push(
+          `${declared.file}: ${field}."${key}" is not encrypted (expected an ENC[...] value) — ` +
+            `re-run \`sops -e -i\` before committing`,
+        );
+      }
+    }
+  }
+
+  return { problems, document: { name, namespace, keys } };
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+/** Options for {@link resolveEncryptedSecrets} — `readFile` is injectable for tests. */
+export interface ResolveEncryptedSecretsOptions {
+  projectRoot: string;
+  declarations: ReadonlyMap<string, CommittedEncryptedSecretDeclaration>;
+  readFile?: (path: string) => string;
+}
+
+/**
+ * Read and validate every committed-encrypted declaration, returning one
+ * entity per resolved file. Throws on the first declaration that does not
+ * resolve, with every problem for that declaration in the message — a build
+ * that would emit a broken or unencrypted Secret must not proceed.
+ */
+export function resolveEncryptedSecrets(
+  options: ResolveEncryptedSecretsOptions,
+): Map<string, Declarable> {
+  const read = options.readFile ?? ((path: string) => readFileSync(path, "utf-8"));
+  const entities = new Map<string, Declarable>();
+  const byFilename = new Map<string, string>();
+
+  for (const decl of options.declarations.values()) {
+    const absolute = resolve(options.projectRoot, decl.file);
+    let text: string;
+    try {
+      text = read(absolute);
+    } catch (err) {
+      throw new Error(
+        `declareSecret("${decl.name}"): committed ciphertext not readable at ${absolute} ` +
+          `(declared as "${decl.file}") — ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+
+    const { problems, document } = validateEncryptedSecretDocument(text, decl);
+    if (problems.length > 0) {
+      throw new Error(
+        `declareSecret("${decl.name}"): committed ciphertext does not resolve —\n  ` +
+          problems.join("\n  "),
+      );
+    }
+
+    const filename = sidecarFilename(decl.file);
+    const collides = byFilename.get(filename);
+    if (collides !== undefined) {
+      throw new Error(
+        `declareSecret("${decl.name}"): sidecar filename "${filename}" collides with the one ` +
+          `"${collides}" already emits — additional files share one flat namespace, so two ` +
+          `declarations whose paths share a basename would silently overwrite each other`,
+      );
+    }
+    byFilename.set(filename, decl.file);
+
+    const entity: EncryptedSecretFileEntity = {
+      lexicon: "k8s",
+      entityType: ENCRYPTED_SECRET_FILE_TYPE,
+      filename,
+      text,
+      secretName: decl.name,
+      ...(document?.namespace !== undefined ? { namespace: document.namespace } : {}),
+      sourcePath: decl.file,
+      [DECLARABLE_MARKER]: true,
+      [ENCRYPTED_SECRET_FILE_MARKER]: true,
+    };
+    entities.set(`${ENCRYPTED_SECRET_ENTITY_PREFIX}${decl.name}`, entity);
+  }
+
+  return entities;
+}
+
+/** Every committed-encrypted declaration in an entity map, keyed by entity name. */
+export function committedEncryptedDeclarations(
+  entities: ReadonlyMap<string, Declarable>,
+): Map<string, CommittedEncryptedSecretDeclaration> {
+  const out = new Map<string, CommittedEncryptedSecretDeclaration>();
+  for (const [name, decl] of collectSecretDeclarations(entities)) {
+    if (isCommittedEncryptedSecret(decl)) out.set(name, decl);
+  }
+  return out;
+}
+
+/**
+ * The `buildRoots` contribution: one entity per committed-encrypted
+ * declaration, holding the file's bytes verbatim.
+ */
+export async function encryptedSecretBuildRoot(ctx: BuildRootContext): Promise<BuildRootContribution> {
+  const declarations = committedEncryptedDeclarations(ctx.entities ?? new Map());
+  if (declarations.size === 0) return { entities: new Map() };
+  return { entities: resolveEncryptedSecrets({ projectRoot: ctx.projectRoot, declarations }) };
+}

package/src/sops/entity.ts

@@ -0,0 +1,53 @@
+/**
+ * The committed-ciphertext entity: marker, shape and type guard only.
+ *
+ * Split from `./encrypted-secret-file.ts` so the serializer can recognise the
+ * entity without pulling `node:fs` and a YAML parser into its module graph —
+ * the resolution stage needs both, the emission stage needs neither.
+ *
+ * Not exported from the package entry point and not constructible by an
+ * author: the authored surface is `declareSecret({ provenance:
+ * "committed-encrypted", file })`. A public entity taking inline bytes is
+ * exactly what this design exists to prevent.
+ */
+import { basename } from "node:path";
+import type { Declarable } from "@intentius/chant/declarable";
+
+/** Marks an entity whose bytes are committed ciphertext, emitted verbatim. */
+export const ENCRYPTED_SECRET_FILE_MARKER = Symbol.for("chant.k8s.encryptedSecretFile");
+
+/**
+ * The entity's type name. Deliberately outside the `K8s::{Group}::{Kind}`
+ * surface a real Secret speaks: an observer must NOT read this against a live
+ * cluster — the ciphertext is not the thing in the cluster, the decrypted
+ * Secret is — so a type with no generated operation surface, reporting the
+ * honest NOT-OBSERVED, is the right answer.
+ */
+export const ENCRYPTED_SECRET_FILE_TYPE = "K8s::Sops::EncryptedSecretFile";
+
+/** Entity-map key prefix, colon-separated so it cannot collide with a TS export name. */
+export const ENCRYPTED_SECRET_ENTITY_PREFIX = "sops:";
+
+export interface EncryptedSecretFileEntity extends Declarable {
+  readonly entityType: typeof ENCRYPTED_SECRET_FILE_TYPE;
+  readonly [ENCRYPTED_SECRET_FILE_MARKER]: true;
+  /** Sidecar filename written beside the primary output. */
+  readonly filename: string;
+  /** The committed bytes, exactly as read. */
+  readonly text: string;
+  /** `metadata.name` of the encrypted Secret — equal to the declaration's name. */
+  readonly secretName: string;
+  /** `metadata.namespace`, cleartext in the file (SOPS encrypts values, not structure). */
+  readonly namespace?: string;
+  /** The declared repo-relative path, for diagnostics. */
+  readonly sourcePath: string;
+}
+
+export function isEncryptedSecretFileEntity(entity: Declarable): entity is EncryptedSecretFileEntity {
+  return (entity as unknown as Record<symbol, unknown>)[ENCRYPTED_SECRET_FILE_MARKER] === true;
+}
+
+/** The sidecar filename a declaration's file is emitted under. */
+export function sidecarFilename(file: string): string {
+  return basename(file);
+}

package/src/teardown.test.ts

@@ -0,0 +1,240 @@
+/**
+ * Env teardown over the fake cluster (chant #1222) — the k8s halves of the
+ * teardownOwned / executeTeardown capability pair, mirroring the typed-prune
+ * tests in op/activities/kubectl.test.ts: a real client over a fake request
+ * layer, so discovery, path construction, and the delete path all run for
+ * real.
+ */
+
+import { describe, test, expect } from "vitest";
+import { LABEL_OWNERSHIP_KEYS, OWNERSHIP_MANAGED_BY_VALUE } from "@intentius/chant/ownership";
+import { statusBody } from "@intentius/chant-k8s-client/testing";
+import { fakeCluster, objectKey, ownedObject } from "./api/fake-cluster";
+import { teardownOwned, executeTeardown } from "./teardown";
+
+const MARKER = { stack: "shop", env: "dev" };
+
+function markerLabels(stack: string, env?: string): Record<string, string> {
+  return {
+    [LABEL_OWNERSHIP_KEYS.managedBy]: OWNERSHIP_MANAGED_BY_VALUE,
+    [LABEL_OWNERSHIP_KEYS.stack]: stack,
+    ...(env ? { [LABEL_OWNERSHIP_KEYS.env]: env } : {}),
+  };
+}
+
+/** A cluster holding this env's estate plus every kind of near-miss. */
+function estateCluster(overrides: Parameters<typeof fakeCluster>[0] = {}) {
+  return fakeCluster({
+    objects: {
+      // Mine: full marker, this stack, this env.
+      [objectKey("apps/v1", "Deployment", "web", "prod-ns")]: ownedObject("apps/v1", "Deployment", "web", "prod-ns", {
+        metadata: { labels: markerLabels("shop", "dev") },
+      }),
+      [objectKey("v1", "Service", "cache", "prod-ns")]: ownedObject("v1", "Service", "cache", "prod-ns", {
+        metadata: { labels: markerLabels("shop", "dev") },
+      }),
+      [objectKey("v1", "Namespace", "dev-ns")]: ownedObject("v1", "Namespace", "dev-ns", undefined, {
+        metadata: { labels: markerLabels("shop", "dev") },
+      }),
+      // Near-misses: foreign stack, foreign env, env-less marker, unmarked.
+      [objectKey("apps/v1", "Deployment", "their-web", "prod-ns")]: ownedObject("apps/v1", "Deployment", "their-web", "prod-ns", {
+        metadata: { labels: markerLabels("blog", "dev") },
+      }),
+      [objectKey("apps/v1", "Deployment", "prod-twin", "prod-ns")]: ownedObject("apps/v1", "Deployment", "prod-twin", "prod-ns", {
+        metadata: { labels: markerLabels("shop", "prod") },
+      }),
+      [objectKey("apps/v1", "Deployment", "no-env", "prod-ns")]: ownedObject("apps/v1", "Deployment", "no-env", "prod-ns", {
+        metadata: { labels: markerLabels("shop") },
+      }),
+      [objectKey("apps/v1", "Deployment", "handmade", "prod-ns")]: {
+        apiVersion: "apps/v1",
+        kind: "Deployment",
+        metadata: { name: "handmade", namespace: "prod-ns", labels: { app: "handmade" } },
+      },
+    },
+    ...overrides,
+  });
+}
+
+describe("teardownOwned — marker-env-scoped enumeration", () => {
+  test("selects exactly the objects carrying this stack + env, nothing near", async () => {
+    const cluster = estateCluster();
+    const enumeration = await teardownOwned({ environment: "dev", marker: MARKER }, cluster.connector);
+    expect(enumeration.candidates.map((c) => c.name).sort()).toEqual(["dev-ns", "prod-ns/cache", "prod-ns/web"]);
+    for (const candidate of enumeration.candidates) {
+      expect(candidate.marker).toEqual(MARKER);
+    }
+    const web = enumeration.candidates.find((c) => c.name === "prod-ns/web")!;
+    expect(web.type).toBe("K8s::Apps::Deployment");
+    expect(web.physicalId).toBe("uid-web");
+    expect(enumeration.holes ?? []).toEqual([]);
+  });
+
+  test("the selector is sent to the server: managed-by + stack + env", async () => {
+    const cluster = estateCluster();
+    await teardownOwned({ environment: "dev", marker: MARKER }, cluster.connector);
+    const listQueries = cluster.layer.requests
+      .filter((r) => r.method === "GET" && r.query.labelSelector !== undefined)
+      .map((r) => r.query.labelSelector);
+    expect(listQueries.length).toBeGreaterThan(0);
+    for (const selector of listQueries) {
+      expect(selector).toBe(
+        `${LABEL_OWNERSHIP_KEYS.managedBy}=${OWNERSHIP_MANAGED_BY_VALUE},` +
+        `${LABEL_OWNERSHIP_KEYS.stack}=shop,${LABEL_OWNERSHIP_KEYS.env}=dev`,
+      );
+    }
+  });
+
+  test("an object already terminating is not a candidate", async () => {
+    const cluster = fakeCluster({
+      objects: {
+        [objectKey("apps/v1", "Deployment", "leaving", "prod-ns")]: ownedObject("apps/v1", "Deployment", "leaving", "prod-ns", {
+          metadata: { labels: markerLabels("shop", "dev"), deletionTimestamp: "2026-08-23T00:00:00Z" } as never,
+        }),
+      },
+    });
+    const enumeration = await teardownOwned({ environment: "dev", marker: MARKER }, cluster.connector);
+    expect(enumeration.candidates).toEqual([]);
+  });
+
+  test("a kind that fails to list is a hole, and the others still enumerate (#1089)", async () => {
+    const cluster = estateCluster({
+      respond: (req) => {
+        if (req.method === "GET" && req.path.endsWith("/deployments") && req.query.labelSelector !== undefined) {
+          return { status: 500, body: statusBody(500, "InternalError", "etcd is unhappy") };
+        }
+        return undefined;
+      },
+    });
+    const enumeration = await teardownOwned({ environment: "dev", marker: MARKER }, cluster.connector);
+    expect(enumeration.candidates.map((c) => c.name).sort()).toEqual(["dev-ns", "prod-ns/cache"]);
+    const hole = (enumeration.holes ?? []).find((h) => h.name === "K8s::Apps::Deployment");
+    expect(hole).toBeDefined();
+    expect(hole!.reason).toBe("read-failed");
+  });
+});
+
+describe("executeTeardown — typed deletes, namespaces last", () => {
+  const candidates = [
+    { name: "dev-ns", type: "K8s::Core::Namespace", marker: MARKER },
+    { name: "prod-ns/web", type: "K8s::Apps::Deployment", physicalId: "uid-web", marker: MARKER },
+    { name: "prod-ns/cache", type: "K8s::Core::Service", marker: MARKER },
+  ];
+
+  test("deletes every candidate through the typed client, namespace last", async () => {
+    const cluster = estateCluster();
+    const execution = await executeTeardown({ environment: "dev", marker: MARKER, candidates }, cluster.connector);
+
+    expect(execution.outcomes.map((o) => ({ name: o.name, outcome: o.outcome }))).toEqual([
+      { name: "prod-ns/web", outcome: "deleted" },
+      { name: "prod-ns/cache", outcome: "deleted" },
+      { name: "dev-ns", outcome: "deleted" },
+    ]);
+    const deletes = cluster.layer.requests.filter((r) => r.method === "DELETE").map((r) => r.path);
+    expect(deletes).toEqual([
+      "/apis/apps/v1/namespaces/prod-ns/deployments/web",
+      "/api/v1/namespaces/prod-ns/services/cache",
+      "/api/v1/namespaces/dev-ns",
+    ]);
+  });
+
+  test("an already-absent candidate is deleted (idempotent), with no DELETE issued", async () => {
+    const cluster = fakeCluster({ objects: {} });
+    const execution = await executeTeardown(
+      { environment: "dev", marker: MARKER, candidates: [candidates[1]] },
+      cluster.connector,
+    );
+    expect(execution.outcomes).toEqual([
+      {
+        name: "prod-ns/web",
+        type: "K8s::Apps::Deployment",
+        physicalId: "uid-web",
+        outcome: "deleted",
+        detail: "already absent",
+      },
+    ]);
+    expect(cluster.layer.requests.filter((r) => r.method === "DELETE")).toEqual([]);
+  });
+
+  test("a live object whose marker changed since planning is not-prunable, never deleted", async () => {
+    const cluster = fakeCluster({
+      objects: {
+        [objectKey("apps/v1", "Deployment", "web", "prod-ns")]: ownedObject("apps/v1", "Deployment", "web", "prod-ns", {
+          metadata: { labels: markerLabels("blog", "dev") }, // re-stamped by someone else
+        }),
+      },
+    });
+    const execution = await executeTeardown(
+      { environment: "dev", marker: MARKER, candidates: [candidates[1]] },
+      cluster.connector,
+    );
+    expect(execution.outcomes[0].outcome).toBe("not-prunable");
+    expect(execution.outcomes[0].detail).toContain("marker identity");
+    expect(cluster.layer.requests.filter((r) => r.method === "DELETE")).toEqual([]);
+  });
+
+  test("a refused delete is a failed outcome with the server's message, not a throw", async () => {
+    const cluster = estateCluster({
+      respond: (req) =>
+        req.method === "DELETE"
+          ? { status: 403, body: statusBody(403, "Forbidden", "RBAC says no") }
+          : undefined,
+    });
+    const execution = await executeTeardown(
+      { environment: "dev", marker: MARKER, candidates: [candidates[1]] },
+      cluster.connector,
+    );
+    expect(execution.outcomes[0].outcome).toBe("failed");
+    expect(execution.outcomes[0].detail).toContain("RBAC says no");
+  });
+
+  test("a generated-once secret survives the env sweep with a retained row; a plain owned secret still deletes (#1830)", async () => {
+    const cluster = fakeCluster({
+      objects: {
+        [objectKey("v1", "Secret", "master-key", "prod-ns")]: ownedObject("v1", "Secret", "master-key", "prod-ns", {
+          metadata: {
+            labels: {
+              ...markerLabels("shop", "dev"),
+              "chant.intentius.io/generated-once": "true",
+            },
+          },
+        }),
+        [objectKey("v1", "Secret", "plain", "prod-ns")]: ownedObject("v1", "Secret", "plain", "prod-ns", {
+          metadata: { labels: markerLabels("shop", "dev") },
+        }),
+      },
+    });
+
+    // Both are owned by this env, so both enumerate — the retained row is the
+    // execution's loud answer, not a silent hole in the plan.
+    const enumeration = await teardownOwned({ environment: "dev", marker: MARKER }, cluster.connector);
+    expect(enumeration.candidates.map((c) => c.name).sort()).toEqual(["prod-ns/master-key", "prod-ns/plain"]);
+
+    const execution = await executeTeardown(
+      { environment: "dev", marker: MARKER, candidates: enumeration.candidates },
+      cluster.connector,
+    );
+    const byName = new Map(execution.outcomes.map((o) => [o.name, o]));
+    expect(byName.get("prod-ns/master-key")!.outcome).toBe("retained");
+    expect(byName.get("prod-ns/master-key")!.detail).toContain("generated-once");
+    expect(byName.get("prod-ns/plain")!.outcome).toBe("deleted");
+
+    // Never deleted: the only DELETE is the plain secret's.
+    const deletes = cluster.layer.requests.filter((r) => r.method === "DELETE").map((r) => r.path);
+    expect(deletes).toEqual(["/api/v1/namespaces/prod-ns/secrets/plain"]);
+  });
+
+  test("a candidate of an unmapped type is not-prunable, not a crash", async () => {
+    const cluster = fakeCluster({ objects: {} });
+    const execution = await executeTeardown(
+      {
+        environment: "dev",
+        marker: MARKER,
+        candidates: [{ name: "mystery", type: "K8s::NotAThing::Widget", marker: MARKER }],
+      },
+      cluster.connector,
+    );
+    expect(execution.outcomes[0].outcome).toBe("not-prunable");
+    expect(execution.outcomes[0].detail).toContain("no operation mapping");
+  });
+});