@intentius/chant-lexicon-aws 0.45.0 → 0.46.0

package/src/serializer.ts

@@ -2,7 +2,7 @@ import type { Declarable, CoreParameter } from "@intentius/chant/declarable";
 import { isPropertyDeclarable, isResourceDeclarable } from "@intentius/chant/declarable";
 import type { Serializer, SerializerResult, SerializeContext } from "@intentius/chant/serializer";
 import { ownershipEntries, type OwnershipMarker } from "@intentius/chant/ownership";
-import { AWS_TAG_OWNERSHIP_KEYS } from "./ownership";
+import { AWS_TAG_OWNERSHIP_KEYS, OWNERSHIP_METADATA_KEY } from "./ownership";
 import type { LexiconOutput } from "@intentius/chant/lexicon-output";
 import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-walker";
 import { isChildProject, type ChildProjectInstance } from "@intentius/chant/child-project";
@@ -26,6 +26,7 @@ function isCoreParameter(entity: Declarable): entity is CoreParameter {
 interface CFTemplate {
   AWSTemplateFormatVersion: "2010-09-09";
   Description?: string;
+  Metadata?: Record<string, unknown>;
   Transform?: string | string[];
   Parameters?: Record<string, CFParameter>;
   Resources: Record<string, CFResource>;
@@ -187,6 +188,13 @@ function serializeToTemplate(
     for (const [Key, Value] of Object.entries(ownershipEntries(AWS_TAG_OWNERSHIP_KEYS, ownership))) {
       defaultTagEntries.push({ Key, Value });
     }
+    // Also carry the marker at the template level (#1222): stack tags are a
+    // CreateStack/UpdateStack API parameter, not a template section, so the
+    // apply paths read this Metadata block and stamp it as the stack's own
+    // tags — what stack-level teardown verifies ownership on.
+    template.Metadata = {
+      [OWNERSHIP_METADATA_KEY]: ownershipEntries(AWS_TAG_OWNERSHIP_KEYS, ownership),
+    };
   }
   for (const [, entity] of entities) {
     if (isDefaultTags(entity)) {

package/src/teardown.test.ts

@@ -0,0 +1,258 @@
+/**
+ * aws stack-level env teardown (#1222) — unit tests over fake Query-API
+ * transports, in the style of aws-apply.test.ts: no network, the fakes answer
+ * DescribeStacks/DeleteStack by parsing the form body.
+ */
+import { describe, test, expect } from "vitest";
+import { teardownOwned, executeTeardown, resolveTeardownStacks, STACK_TYPE } from "./teardown";
+import type { AwsReadHttp } from "./api/read-client";
+import type { AwsHttp } from "./op/activities/aws-apply";
+import type { OwnershipMarker } from "@intentius/chant/ownership";
+
+const MARKER: OwnershipMarker = { stack: "shop", env: "dev" };
+
+const MISSING =
+  "<ErrorResponse><Error><Code>ValidationError</Code><Message>Stack with id x does not exist</Message></Error></ErrorResponse>";
+
+/** A DescribeStacks response for one stack carrying the given tags. */
+function stackXml(name: string, tags: Record<string, string>, status = "CREATE_COMPLETE"): string {
+  const members = Object.entries(tags)
+    .map(([k, v]) => `<member><Key>${k}</Key><Value>${v}</Value></member>`)
+    .join("");
+  return (
+    `<DescribeStacksResponse><DescribeStacksResult><Stacks><member>` +
+    `<StackId>arn:aws:cloudformation:us-east-1:0:stack/${name}/uuid</StackId>` +
+    `<StackName>${name}</StackName><StackStatus>${status}</StackStatus>` +
+    `<Tags>${members}</Tags>` +
+    `</member></Stacks></DescribeStacksResult></DescribeStacksResponse>`
+  );
+}
+
+const OWNED_TAGS = { "chant:managed-by": "chant", "chant:stack": "shop", "chant:env": "dev" };
+const FOREIGN_ENV_TAGS = { "chant:managed-by": "chant", "chant:stack": "shop", "chant:env": "prod" };
+
+/**
+ * A fake read transport: answers DescribeStacks per stack name from `stacks`;
+ * names not present answer "does not exist".
+ */
+function fakeRead(stacks: Record<string, string>): AwsReadHttp {
+  return async (_url, init) => {
+    const form = new URLSearchParams(init.body);
+    expect(form.get("Action")).toBe("DescribeStacks");
+    const name = form.get("StackName") ?? "";
+    const xml = stacks[name];
+    return xml ? { status: 200, text: xml } : { status: 400, text: MISSING };
+  };
+}
+
+describe("resolveTeardownStacks — stacks[] else the env-named default (#932)", () => {
+  test("declared stacks win", () => {
+    expect(
+      resolveTeardownStacks({
+        environment: "dev",
+        marker: MARKER,
+        stacks: [{ name: "net" }, { name: "app", region: "eu-west-1" }],
+      }),
+    ).toEqual([{ name: "net" }, { name: "app", region: "eu-west-1" }]);
+  });
+
+  test("explicit stack option, else the stack named after the environment", () => {
+    expect(resolveTeardownStacks({ environment: "dev", marker: MARKER, stack: "s1" })).toEqual([{ name: "s1" }]);
+    expect(resolveTeardownStacks({ environment: "dev", marker: MARKER })).toEqual([{ name: "dev" }]);
+  });
+});
+
+describe("teardownOwned — marker-verified stack enumeration", () => {
+  test("a stack whose own tags carry the requested identity is a candidate", async () => {
+    const result = await teardownOwned(
+      { environment: "dev", marker: MARKER },
+      { read: { http: fakeRead({ dev: stackXml("dev", OWNED_TAGS) }) } },
+    );
+    expect(result.candidates).toEqual([
+      {
+        name: "dev",
+        type: STACK_TYPE,
+        physicalId: "arn:aws:cloudformation:us-east-1:0:stack/dev/uuid",
+        marker: { stack: "shop", env: "dev" },
+      },
+    ]);
+    expect(result.holes).toBeUndefined();
+  });
+
+  test("an untagged stack is a loud unverified-ownership hole, never a candidate", async () => {
+    const result = await teardownOwned(
+      { environment: "dev", marker: MARKER },
+      { read: { http: fakeRead({ dev: stackXml("dev", {}) }) } },
+    );
+    expect(result.candidates).toEqual([]);
+    expect(result.holes).toHaveLength(1);
+    expect(result.holes![0]).toMatchObject({ name: "dev", type: STACK_TYPE, reason: "filtered" });
+    expect(result.holes![0].detail).toMatch(/unverified-ownership/);
+  });
+
+  test("a stack verifiably carrying ANOTHER identity is out of scope — no candidate, no hole", async () => {
+    const result = await teardownOwned(
+      { environment: "dev", marker: MARKER },
+      { read: { http: fakeRead({ dev: stackXml("dev", FOREIGN_ENV_TAGS) }) } },
+    );
+    expect(result.candidates).toEqual([]);
+    expect(result.holes).toBeUndefined();
+  });
+
+  test("an absent stack is knowledge: nothing to tear down, no hole", async () => {
+    const result = await teardownOwned(
+      { environment: "dev", marker: MARKER },
+      { read: { http: fakeRead({}) } },
+    );
+    expect(result.candidates).toEqual([]);
+    expect(result.holes).toBeUndefined();
+  });
+
+  test("a failed DescribeStacks is a hole (#1089), never absence", async () => {
+    const http: AwsReadHttp = async () => ({ status: 500, text: "boom" });
+    const result = await teardownOwned({ environment: "dev", marker: MARKER }, { read: { http } });
+    expect(result.candidates).toEqual([]);
+    expect(result.holes).toHaveLength(1);
+    expect(result.holes![0]).toMatchObject({ name: "dev", type: STACK_TYPE, reason: "read-failed" });
+  });
+
+  test("multi-stack: every declared stack is checked, only verified ones are candidates", async () => {
+    const result = await teardownOwned(
+      {
+        environment: "dev",
+        marker: MARKER,
+        stacks: [{ name: "net" }, { name: "app" }, { name: "gone" }],
+      },
+      {
+        read: {
+          http: fakeRead({
+            net: stackXml("net", OWNED_TAGS),
+            app: stackXml("app", FOREIGN_ENV_TAGS),
+          }),
+        },
+      },
+    );
+    expect(result.candidates.map((c) => c.name)).toEqual(["net"]);
+    expect(result.holes).toBeUndefined();
+  });
+});
+
+describe("executeTeardown — re-verify, then DeleteStack to DELETE_COMPLETE", () => {
+  const CANDIDATE = { name: "dev", type: STACK_TYPE, marker: { stack: "shop", env: "dev" } };
+
+  /** A stateful fake pair: reads see the stack until DeleteStack lands. */
+  function fakeTarget(initialTags: Record<string, string> | undefined) {
+    const deletes: string[] = [];
+    let present = initialTags !== undefined;
+    const read: AwsReadHttp = async (_url, init) => {
+      const form = new URLSearchParams(init.body);
+      const name = form.get("StackName") ?? "";
+      if (!present) return { status: 400, text: MISSING };
+      return { status: 200, text: stackXml(name, initialTags ?? {}) };
+    };
+    const apply: AwsHttp = async (_url, form) => {
+      if (form.Action === "DeleteStack") {
+        deletes.push(form.StackName ?? "");
+        present = false;
+        return { status: 200, text: "<DeleteStackResponse/>" };
+      }
+      if (form.Action === "DescribeStacks") {
+        return present
+          ? { status: 200, text: stackXml(form.StackName ?? "", initialTags ?? {}) }
+          : { status: 400, text: MISSING };
+      }
+      throw new Error(`unexpected action ${form.Action}`);
+    };
+    return { read, apply, deletes };
+  }
+
+  test("a marker-verified stack is deleted and polled gone", async () => {
+    const target = fakeTarget(OWNED_TAGS);
+    const result = await executeTeardown(
+      { environment: "dev", marker: MARKER, candidates: [CANDIDATE] },
+      { read: { http: target.read }, applyHttp: target.apply, timeoutMs: 1000, intervalMs: 1 },
+    );
+    expect(result.outcomes).toEqual([{ name: "dev", type: STACK_TYPE, outcome: "deleted" }]);
+    expect(target.deletes).toEqual(["dev"]);
+  });
+
+  test("an identity that no longer matches is not-prunable — DeleteStack is never sent", async () => {
+    const target = fakeTarget(FOREIGN_ENV_TAGS);
+    const result = await executeTeardown(
+      { environment: "dev", marker: MARKER, candidates: [CANDIDATE] },
+      { read: { http: target.read }, applyHttp: target.apply, timeoutMs: 1000, intervalMs: 1 },
+    );
+    expect(result.outcomes[0]).toMatchObject({ name: "dev", outcome: "not-prunable" });
+    expect(result.outcomes[0].detail).toMatch(/unverified-ownership/);
+    expect(target.deletes).toEqual([]);
+  });
+
+  test("an untagged stack at execution time is not-prunable too", async () => {
+    const target = fakeTarget({});
+    const result = await executeTeardown(
+      { environment: "dev", marker: MARKER, candidates: [CANDIDATE] },
+      { read: { http: target.read }, applyHttp: target.apply, timeoutMs: 1000, intervalMs: 1 },
+    );
+    expect(result.outcomes[0]).toMatchObject({ name: "dev", outcome: "not-prunable" });
+    expect(target.deletes).toEqual([]);
+  });
+
+  test("an already-absent stack is deleted (teardown is idempotent)", async () => {
+    const target = fakeTarget(undefined);
+    const result = await executeTeardown(
+      { environment: "dev", marker: MARKER, candidates: [CANDIDATE] },
+      { read: { http: target.read }, applyHttp: target.apply, timeoutMs: 1000, intervalMs: 1 },
+    );
+    expect(result.outcomes).toEqual([
+      { name: "dev", type: STACK_TYPE, outcome: "deleted", detail: "already absent" },
+    ]);
+    expect(target.deletes).toEqual([]);
+  });
+
+  test("a failed DeleteStack is a failed outcome, never silence", async () => {
+    const target = fakeTarget(OWNED_TAGS);
+    const apply: AwsHttp = async (_url, form) => {
+      if (form.Action === "DeleteStack") return { status: 500, text: "<ErrorResponse><Error><Message>throttled</Message></Error></ErrorResponse>" };
+      return target.apply(_url, form);
+    };
+    const result = await executeTeardown(
+      { environment: "dev", marker: MARKER, candidates: [CANDIDATE] },
+      { read: { http: target.read }, applyHttp: apply, timeoutMs: 1000, intervalMs: 1 },
+    );
+    expect(result.outcomes[0]).toMatchObject({ name: "dev", outcome: "failed" });
+    expect(result.outcomes[0].detail).toMatch(/throttled/);
+  });
+
+  test("a candidate's region comes from the declared stacks", async () => {
+    // The URL is only regional when no ambient endpoint override is set.
+    const saved = {
+      all: process.env.AWS_ENDPOINT_URL,
+      cfn: process.env.AWS_ENDPOINT_URL_CLOUDFORMATION,
+    };
+    delete process.env.AWS_ENDPOINT_URL;
+    delete process.env.AWS_ENDPOINT_URL_CLOUDFORMATION;
+    const urls: string[] = [];
+    const target = fakeTarget(OWNED_TAGS);
+    const apply: AwsHttp = async (url, form) => {
+      urls.push(url);
+      return target.apply(url, form);
+    };
+    const read: AwsReadHttp = async (url, init) => {
+      urls.push(url);
+      return target.read(url, init);
+    };
+    await executeTeardown(
+      {
+        environment: "dev",
+        marker: MARKER,
+        candidates: [{ ...CANDIDATE, name: "app" }],
+        stacks: [{ name: "app", region: "eu-west-1" }],
+      },
+      { read: { http: read }, applyHttp: apply, timeoutMs: 1000, intervalMs: 1 },
+    );
+    if (saved.all !== undefined) process.env.AWS_ENDPOINT_URL = saved.all;
+    if (saved.cfn !== undefined) process.env.AWS_ENDPOINT_URL_CLOUDFORMATION = saved.cfn;
+    expect(urls.length).toBeGreaterThan(0);
+    expect(urls.every((u) => u.includes("eu-west-1"))).toBe(true);
+  });
+});

package/src/teardown.ts

@@ -0,0 +1,276 @@
+/**
+ * Env teardown for the aws lexicon (chant #1222) — both halves of the
+ * `teardownOwned` / `executeTeardown` capability pair, at STACK granularity.
+ *
+ * Per-resource selection is impossible here by construction: the thin read
+ * (`describeResources`) is sourced from `describe-stack-resources`, which
+ * returns no tags, so no resource-level marker can be read on the teardown
+ * path. The stack is aws's ownership boundary anyway — the applier deploys
+ * whole stacks and deletes ride CloudFormation — so teardown enumerates the
+ * environment's stacks and verifies the marker on each STACK's own tags
+ * (`DescribeStacks` → `Tags`), stamped there by the apply paths from the
+ * template's `Metadata["chant:ownership"]` block.
+ *
+ * Which stacks are the environment's: the project's declared `stacks[]` when
+ * it is a multi-stack project, else the single-stack convention — the explicit
+ * `stack` option, else the stack named after the environment (the same rule
+ * `describeResources` and `exportResources` apply, see chant #932).
+ *
+ * Verification is tag-reading, never name-trusting. A resolved stack whose
+ * tags carry exactly the requested identity (managed-by + stack + env) is a
+ * candidate of type `AWS::CloudFormation::Stack`. A stack carrying a DIFFERENT
+ * marker identity verifiably belongs to another project or env — out of scope,
+ * silently, the way another env's resources are. A stack carrying NO marker at
+ * all is unknowable — a legacy chant stack from before stack tagging, or a
+ * foreign stack that happens to hold the env's name — and is reported as a
+ * hole (`filtered` / unverified-ownership), never deleted. An absent stack is
+ * knowledge, not a hole: nothing to tear down.
+ *
+ * Execution re-reads each candidate stack's tags immediately before deleting
+ * (the enumeration is a moment old at best, and a delete is not undoable),
+ * then rides the existing Query-API delete — `awsDelete`, DeleteStack polled
+ * to DELETE_COMPLETE. An identity that no longer matches is `not-prunable:
+ * unverified-ownership`; an already-absent stack is `deleted` (teardown is
+ * idempotent).
+ */
+
+import type {
+  TeardownCandidate,
+  TeardownEnumeration,
+  TeardownExecution,
+  TeardownHole,
+  TeardownOutcome,
+} from "@intentius/chant/lexicon";
+import { readOwnership, type OwnershipMarker } from "@intentius/chant/ownership";
+import { AWS_TAG_OWNERSHIP_KEYS } from "./ownership";
+import {
+  cfnQuery,
+  xmlLeaves,
+  xmlMembers,
+  AwsReadError,
+  type AwsReadClientOptions,
+} from "./api/read-client";
+import { awsDelete, type AwsHttp } from "./op/activities/aws-apply";
+
+/** The one candidate type this lexicon's teardown produces: whole stacks. */
+export const STACK_TYPE = "AWS::CloudFormation::Stack";
+
+export interface AwsTeardownOptions {
+  environment: string;
+  /** The identity to select on: this project's ownership stack + the env being torn down. */
+  marker: OwnershipMarker;
+  /** Explicit deployed stack name (single-stack override). */
+  stack?: string;
+  /** Region that stack is deployed in. */
+  region?: string;
+  /** A multi-stack project's declared stacks (chant.config `stacks[]`). */
+  stacks?: Array<{ name: string; region?: string }>;
+}
+
+/** Injectable transports/timeouts, so tests double the Query API (no network). */
+export interface AwsTeardownDeps {
+  /** Options for the read client's `DescribeStacks` calls (http injection, endpoint). */
+  read?: AwsReadClientOptions;
+  /** The applier transport `awsDelete` polls DeleteStack through. */
+  applyHttp?: AwsHttp;
+  /** DeleteStack settle timeout in ms (default `awsDelete`'s 300000). */
+  timeoutMs?: number;
+  /** DeleteStack poll interval in ms (default `awsDelete`'s 3000). */
+  intervalMs?: number;
+}
+
+/** The stacks an env teardown resolves to: `stacks[]`, else the single-stack convention. */
+export function resolveTeardownStacks(
+  options: AwsTeardownOptions,
+): Array<{ name: string; region?: string }> {
+  if (options.stacks && options.stacks.length > 0) return options.stacks;
+  return [
+    {
+      name: options.stack ?? options.environment,
+      ...(options.region ? { region: options.region } : {}),
+    },
+  ];
+}
+
+/** One live stack, as DescribeStacks answers for it. */
+interface LiveStack {
+  stackId?: string;
+  status?: string;
+  /** The stack's own tags, as a flat map. */
+  tags: Record<string, string>;
+}
+
+/** A DescribeStacks miss — CloudFormation's "does not exist" ValidationError. */
+function isStackMissingError(err: unknown): boolean {
+  return err instanceof AwsReadError && /does not exist/i.test(err.message);
+}
+
+/** `DescribeStacks` for one stack; `undefined` when the stack does not exist. */
+async function describeStack(
+  name: string,
+  region: string | undefined,
+  read: AwsReadClientOptions,
+): Promise<LiveStack | undefined> {
+  let xml: string;
+  try {
+    xml = await cfnQuery("DescribeStacks", { StackName: name }, {
+      ...read,
+      ...(region ? { region } : {}),
+    });
+  } catch (err) {
+    if (isStackMissingError(err)) return undefined;
+    throw err;
+  }
+  // One StackName queried → one stack member; `xmlLeaves` keeps the first
+  // occurrence of each scalar, which is that stack's StackId/StackStatus.
+  const leaves = xmlLeaves(xml);
+  const tags: Record<string, string> = {};
+  for (const m of xmlMembers(xml, "Tags")) {
+    if (m.Key) tags[m.Key] = m.Value ?? "";
+  }
+  return {
+    ...(leaves.StackId ? { stackId: leaves.StackId } : {}),
+    ...(leaves.StackStatus ? { status: leaves.StackStatus } : {}),
+    tags,
+  };
+}
+
+/** True when a live stack's own tags carry exactly the requested identity. */
+function matchesMarker(tags: Record<string, string>, marker: OwnershipMarker): boolean {
+  const read = readOwnership(tags, AWS_TAG_OWNERSHIP_KEYS);
+  return read !== undefined && read.stack === marker.stack && read.env === marker.env;
+}
+
+/**
+ * Enumerate the environment's marker-verified stacks — the aws half of
+ * `chant lifecycle teardown <env>` planning. Read-only.
+ */
+export async function teardownOwned(
+  options: AwsTeardownOptions,
+  deps: AwsTeardownDeps = {},
+): Promise<TeardownEnumeration> {
+  const read = deps.read ?? {};
+  const candidates: TeardownCandidate[] = [];
+  const holes: TeardownHole[] = [];
+
+  for (const ref of resolveTeardownStacks(options)) {
+    let live: LiveStack | undefined;
+    try {
+      live = await describeStack(ref.name, ref.region, read);
+    } catch (err) {
+      holes.push({
+        name: ref.name,
+        type: STACK_TYPE,
+        reason: "read-failed",
+        detail: err instanceof Error ? err.message : String(err),
+      });
+      continue;
+    }
+    // Absent is knowledge: the env-resolved stack does not exist, so there is
+    // nothing to tear down and nothing unknown about it.
+    if (live === undefined) continue;
+
+    const identity = readOwnership(live.tags, AWS_TAG_OWNERSHIP_KEYS);
+    if (identity !== undefined && identity.stack === options.marker.stack && identity.env === options.marker.env) {
+      candidates.push({
+        name: ref.name,
+        type: STACK_TYPE,
+        ...(live.stackId ? { physicalId: live.stackId } : {}),
+        marker: identity,
+      });
+      continue;
+    }
+    if (identity !== undefined) {
+      // A marker for a DIFFERENT identity is verifiably someone else's
+      // (another project's stack, another env's deployment of a shared stack
+      // name) — out of scope, the way any foreign-env resource is.
+      continue;
+    }
+    // No marker at all: a legacy chant stack deployed before stack tagging, or
+    // a foreign stack under the env's name — unknowable either way. Loud, and
+    // never deleted (#1089): unverified ownership reads as "do not touch",
+    // not as "clean".
+    holes.push({
+      name: ref.name,
+      type: STACK_TYPE,
+      reason: "filtered",
+      detail:
+        `unverified-ownership: the stack exists but its tags carry no chant ownership marker ` +
+        `(expected ${AWS_TAG_OWNERSHIP_KEYS.managedBy} + ${AWS_TAG_OWNERSHIP_KEYS.stack}=${options.marker.stack}` +
+        `${options.marker.env ? ` + ${AWS_TAG_OWNERSHIP_KEYS.env}=${options.marker.env}` : ""}) — ` +
+        `a chant stack deployed before stack tagging, or a foreign stack; re-deploy to stamp it, it will not be deleted`,
+    });
+  }
+
+  return { candidates, ...(holes.length > 0 ? { holes } : {}) };
+}
+
+/**
+ * Delete the handed-over stacks: re-verify each stack's own tags, then
+ * DeleteStack via `awsDelete`, polled to DELETE_COMPLETE. One outcome per
+ * candidate, always.
+ */
+export async function executeTeardown(
+  options: AwsTeardownOptions & { candidates: TeardownCandidate[] },
+  deps: AwsTeardownDeps = {},
+): Promise<TeardownExecution> {
+  const read = deps.read ?? {};
+  const regionByStack = new Map<string, string | undefined>(
+    resolveTeardownStacks(options).map((s) => [s.name, s.region]),
+  );
+
+  const outcomes: TeardownOutcome[] = [];
+  for (const candidate of options.candidates) {
+    outcomes.push(await deleteStackCandidate(candidate, regionByStack.get(candidate.name), options.marker, read, deps));
+  }
+  return { outcomes };
+}
+
+async function deleteStackCandidate(
+  candidate: TeardownCandidate,
+  region: string | undefined,
+  marker: OwnershipMarker,
+  read: AwsReadClientOptions,
+  deps: AwsTeardownDeps,
+): Promise<TeardownOutcome> {
+  const base = {
+    name: candidate.name,
+    type: STACK_TYPE,
+    ...(candidate.physicalId ? { physicalId: candidate.physicalId } : {}),
+  };
+
+  // Re-read and re-verify the stack's own tags right before deleting: the
+  // enumeration is a moment old at best, and a DeleteStack is not undoable.
+  let live: LiveStack | undefined;
+  try {
+    live = await describeStack(candidate.name, region, read);
+  } catch (err) {
+    return { ...base, outcome: "failed", detail: err instanceof Error ? err.message : String(err) };
+  }
+  if (live === undefined || live.status === "DELETE_COMPLETE") {
+    return { ...base, outcome: "deleted", detail: "already absent" };
+  }
+  if (!matchesMarker(live.tags, marker)) {
+    return {
+      ...base,
+      outcome: "not-prunable",
+      detail: "unverified-ownership: the live stack's tags no longer carry the requested marker identity",
+    };
+  }
+
+  try {
+    await awsDelete(
+      {
+        stackName: candidate.name,
+        ...(region ? { region } : {}),
+        ...(deps.timeoutMs !== undefined ? { timeoutMs: deps.timeoutMs } : {}),
+        ...(deps.intervalMs !== undefined ? { intervalMs: deps.intervalMs } : {}),
+      },
+      undefined,
+      deps.applyHttp,
+    );
+  } catch (err) {
+    return { ...base, outcome: "failed", detail: err instanceof Error ? err.message : String(err) };
+  }
+  return { ...base, outcome: "deleted" };
+}