@intentius/chant-lexicon-aws 0.45.0 → 0.46.0

package/src/lint/post-synth/waw060.test.ts

@@ -0,0 +1,131 @@
+import { describe, test, expect } from "vitest";
+import { createPostSynthContext } from "@intentius/chant-test-utils";
+import { waw060, checkPolicyUnattached } from "./waw060";
+
+function makeCtx(template: object) {
+  return createPostSynthContext({ aws: template });
+}
+
+const ALLOW_S3_READ = {
+  Version: "2012-10-17",
+  Statement: [{ Effect: "Allow", Action: ["s3:GetObject"], Resource: "arn:aws:s3:::data/*" }],
+};
+
+function managedPolicy(extra?: Record<string, unknown>) {
+  return {
+    Type: "AWS::IAM::ManagedPolicy",
+    Properties: { PolicyDocument: ALLOW_S3_READ, ...extra },
+  };
+}
+
+function inlinePolicy(extra?: Record<string, unknown>) {
+  return {
+    Type: "AWS::IAM::Policy",
+    Properties: { PolicyName: "read", PolicyDocument: ALLOW_S3_READ, ...extra },
+  };
+}
+
+function role(extra?: Record<string, unknown>) {
+  return {
+    Type: "AWS::IAM::Role",
+    Properties: {
+      AssumeRolePolicyDocument: {
+        Version: "2012-10-17",
+        Statement: [{ Effect: "Allow", Principal: { Service: "lambda.amazonaws.com" }, Action: "sts:AssumeRole" }],
+      },
+      ...extra,
+    },
+  };
+}
+
+describe("WAW060: IAM policy attached to no principal", () => {
+  test("check metadata", () => {
+    expect(waw060.id).toBe("WAW060");
+    expect(waw060.description).toContain("principal");
+  });
+
+  test("flags an unattached IAM::Policy", () => {
+    const ctx = makeCtx({ Resources: { Orphan: inlinePolicy() } });
+    const diags = checkPolicyUnattached(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WAW060");
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].entity).toBe("Orphan");
+    expect(diags[0].message).toContain("grants nothing");
+  });
+
+  test("flags an unattached ManagedPolicy and one with empty principal lists", () => {
+    const ctx = makeCtx({
+      Resources: {
+        Orphan: managedPolicy(),
+        EmptyLists: managedPolicy({ Roles: [], Users: [], Groups: [] }),
+      },
+    });
+    const diags = checkPolicyUnattached(ctx);
+    expect(diags.map((d) => d.entity).sort()).toEqual(["EmptyLists", "Orphan"]);
+  });
+
+  test("quiet when a role's ManagedPolicyArns references the policy", () => {
+    const ctx = makeCtx({
+      Resources: {
+        ReadPolicy: managedPolicy(),
+        AppRole: role({ ManagedPolicyArns: [{ Ref: "ReadPolicy" }] }),
+      },
+    });
+    expect(checkPolicyUnattached(ctx)).toHaveLength(0);
+  });
+
+  test("quiet when the policy declares a Roles list", () => {
+    const ctx = makeCtx({
+      Resources: {
+        AppRole: role(),
+        ReadPolicy: managedPolicy({ Roles: [{ Ref: "AppRole" }] }),
+        InlineRead: inlinePolicy({ Roles: [{ Ref: "AppRole" }] }),
+      },
+    });
+    expect(checkPolicyUnattached(ctx)).toHaveLength(0);
+  });
+
+  test("AWS-managed ARN strings elsewhere do not attach the template's own policy", () => {
+    const ctx = makeCtx({
+      Resources: {
+        Orphan: managedPolicy(),
+        AppRole: role({ ManagedPolicyArns: ["arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"] }),
+      },
+    });
+    const diags = checkPolicyUnattached(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].entity).toBe("Orphan");
+  });
+
+  test("quiet on attachment-style resources and GetAtt edges", () => {
+    const ctx = makeCtx({
+      Resources: {
+        ReadPolicy: managedPolicy(),
+        Attachment: {
+          Type: "AWS::SSO::PermissionSet",
+          Properties: { ManagedPolicies: [{ "Fn::GetAtt": ["ReadPolicy", "PolicyArn"] }] },
+        },
+      },
+    });
+    expect(checkPolicyUnattached(ctx)).toHaveLength(0);
+  });
+
+  test("an Output exporting the policy counts as a reference", () => {
+    const ctx = makeCtx({
+      Resources: { SharedPolicy: managedPolicy() },
+      Outputs: { SharedPolicyArn: { Value: { Ref: "SharedPolicy" }, Export: { Name: "shared-read" } } },
+    });
+    expect(checkPolicyUnattached(ctx)).toHaveLength(0);
+  });
+
+  test("intrinsic principal lists are skipped, and non-policy IAM types are ignored", () => {
+    const ctx = makeCtx({
+      Resources: {
+        Conditional: managedPolicy({ Roles: { "Fn::If": ["UseRole", [{ Ref: "AppRole" }], []] } }),
+        AppRole: role(),
+      },
+    });
+    expect(checkPolicyUnattached(ctx)).toHaveLength(0);
+  });
+});

package/src/lint/post-synth/waw060.ts

@@ -0,0 +1,91 @@
+/**
+ * WAW060: IAM Policy Attached to No Principal
+ *
+ * Flags AWS::IAM::Policy / AWS::IAM::ManagedPolicy resources with empty or
+ * absent Roles, Users, and Groups that no other part of the template
+ * references. A policy attached to no principal grants nothing — the same
+ * detached-guardrail shape WAW057 catches for SCPs. Any Ref/GetAtt edge to
+ * the policy (a role's ManagedPolicyArns, an attachment-style resource, a
+ * stack Output exporting it for another stack to attach) keeps it quiet;
+ * plain AWS-managed ARN strings elsewhere are not references to the
+ * template's own policy.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseCFTemplate, findResourceRefs, isIntrinsic, type CFTemplate } from "./cf-refs";
+
+const POLICY_TYPES = new Set(["AWS::IAM::Policy", "AWS::IAM::ManagedPolicy"]);
+const PRINCIPAL_PROPS = ["Roles", "Users", "Groups"] as const;
+
+/**
+ * Collect every logical id referenced via Ref/Fn::GetAtt from anywhere in the
+ * template except the policy resources themselves — other resources'
+ * properties and the Outputs section. An Output edge counts as attachment
+ * evidence: the policy may be exported for a consuming stack to attach.
+ */
+function collectExternalRefs(template: CFTemplate, excludeIds: Set<string>): Set<string> {
+  const refs = new Set<string>();
+  for (const [logicalId, resource] of Object.entries(template.Resources ?? {})) {
+    if (excludeIds.has(logicalId)) continue;
+    for (const ref of findResourceRefs(resource)) refs.add(ref);
+  }
+  for (const ref of findResourceRefs(template.Outputs)) refs.add(ref);
+  return refs;
+}
+
+export function checkPolicyUnattached(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [_lexicon, output] of ctx.outputs) {
+    const template = parseCFTemplate(output);
+    if (!template?.Resources) continue;
+
+    const policyIds = new Set(
+      Object.entries(template.Resources)
+        .filter(([, resource]) => POLICY_TYPES.has(resource.Type))
+        .map(([logicalId]) => logicalId),
+    );
+    if (policyIds.size === 0) continue;
+
+    const externalRefs = collectExternalRefs(template, policyIds);
+
+    for (const logicalId of policyIds) {
+      const resource = template.Resources[logicalId];
+      const props = resource.Properties ?? {};
+
+      // Any declared principal list keeps the policy quiet. An intrinsic
+      // can't be statically evaluated, so it counts as attached.
+      let attached = false;
+      for (const prop of PRINCIPAL_PROPS) {
+        const value = props[prop];
+        if (isIntrinsic(value)) attached = true;
+        else if (Array.isArray(value) && value.length > 0) attached = true;
+      }
+      if (attached) continue;
+
+      // Reverse lookup: anything else in the template holding a Ref/GetAtt
+      // edge to this policy attaches (or exports) it.
+      if (externalRefs.has(logicalId)) continue;
+
+      const kind = resource.Type === "AWS::IAM::ManagedPolicy" ? "Managed policy" : "Policy";
+      diagnostics.push({
+        checkId: "WAW060",
+        severity: "warning",
+        message: `${kind} "${logicalId}" is attached to no principal — no Roles/Users/Groups and nothing in the template references it; an unattached policy grants nothing`,
+        entity: logicalId,
+        lexicon: "aws",
+      });
+    }
+  }
+
+  return diagnostics;
+}
+
+export const waw060: PostSynthCheck = {
+  id: "WAW060",
+  description: "IAM policy attached to no principal — it grants nothing",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkPolicyUnattached(ctx);
+  },
+};

package/src/op/activities/aws-apply.test.ts

@@ -3,6 +3,7 @@ import { writeFileSync, unlinkSync } from "node:fs";
 import {
   awsApply,
   awsDelete,
+  rollbackStack,
   cfnUrl,
   cfnForm,
   capabilityParams,
@@ -113,6 +114,54 @@ describe("awsApply flow (#awsApply)", () => {
     expect(sent[2]["Capabilities.member.2"]).toBeUndefined();
   });
 
+  test("the template's ownership Metadata becomes the STACK's own tags on create AND update (#1222)", async () => {
+    const sent: Array<Record<string, string>> = [];
+    let described = 0;
+    const createHttp: AwsHttp = async (_url, form) => {
+      if (form.Action === "DescribeStacks") return described++ === 0 ? { status: 400, text: MISSING } : { status: 200, text: describe_("CREATE_COMPLETE") };
+      sent.push(form);
+      return { status: 200, text: CREATE_OK };
+    };
+    const p = tmpl({
+      Metadata: { "chant:ownership": { "chant:managed-by": "chant", "chant:stack": "shop", "chant:env": "dev" } },
+    });
+    await awsApply({ templatePath: p, stackName: "s", endpoint: "http://x", intervalMs: 1 }, undefined, createHttp);
+
+    expect(sent[0].Action).toBe("CreateStack");
+    expect(sent[0]["Tags.member.1.Key"]).toBe("chant:env");
+    expect(sent[0]["Tags.member.1.Value"]).toBe("dev");
+    expect(sent[0]["Tags.member.2.Key"]).toBe("chant:managed-by");
+    expect(sent[0]["Tags.member.2.Value"]).toBe("chant");
+    expect(sent[0]["Tags.member.3.Key"]).toBe("chant:stack");
+    expect(sent[0]["Tags.member.3.Value"]).toBe("shop");
+
+    // Update path re-stamps the same tags.
+    let updDescribed = 0;
+    const updateHttp: AwsHttp = async (_url, form) => {
+      if (form.Action === "DescribeStacks") return { status: 200, text: describe_(updDescribed++ === 0 ? "CREATE_COMPLETE" : "UPDATE_COMPLETE") };
+      sent.push(form);
+      return { status: 200, text: UPDATE_OK };
+    };
+    await awsApply({ templatePath: p, stackName: "s", endpoint: "http://x", intervalMs: 1 }, undefined, updateHttp);
+    unlinkSync(p);
+    expect(sent[1].Action).toBe("UpdateStack");
+    expect(sent[1]["Tags.member.2.Key"]).toBe("chant:managed-by");
+  });
+
+  test("a template without the ownership Metadata sends no Tags parameter at all", async () => {
+    const sent: Array<Record<string, string>> = [];
+    let described = 0;
+    const http: AwsHttp = async (_url, form) => {
+      if (form.Action === "DescribeStacks") return described++ === 0 ? { status: 400, text: MISSING } : { status: 200, text: describe_("CREATE_COMPLETE") };
+      sent.push(form);
+      return { status: 200, text: CREATE_OK };
+    };
+    const p = tmpl();
+    await awsApply({ templatePath: p, stackName: "s", endpoint: "http://x", intervalMs: 1 }, undefined, http);
+    unlinkSync(p);
+    expect(Object.keys(sent[0]).some((k) => k.startsWith("Tags."))).toBe(false);
+  });
+
   test("update path: existing stack → UpdateStack → UPDATE_COMPLETE", async () => {
     let described = 0;
     const http: AwsHttp = async (_url, form) => {
@@ -177,3 +226,65 @@ describe("awsDelete (#awsApply)", () => {
     expect(calls[0]).toBe("DeleteStack");
   });
 });
+
+describe("rollbackStack (#1449)", () => {
+  test("RollbackStack then polls to UPDATE_ROLLBACK_COMPLETE", async () => {
+    const calls: string[] = [];
+    const http: AwsHttp = async (_url, form) => {
+      calls.push(form.Action);
+      if (form.Action === "DescribeStacks") return { status: 200, text: describe_("UPDATE_ROLLBACK_COMPLETE") };
+      return { status: 200, text: "<RollbackStackResponse/>" };
+    };
+    const res = await rollbackStack({ stackName: "s", endpoint: "http://x", intervalMs: 1 }, undefined, http);
+    expect(res).toEqual({ stackName: "s", rolledBack: true, status: "UPDATE_ROLLBACK_COMPLETE" });
+    expect(calls[0]).toBe("RollbackStack");
+    expect(calls[0]).not.toBe("DescribeStacks"); // no probe first — the action itself answers
+  });
+
+  test("posts the stack name on the Query API form", async () => {
+    const forms: Record<string, string>[] = [];
+    const http: AwsHttp = async (_url, form) => {
+      forms.push(form);
+      if (form.Action === "DescribeStacks") return { status: 200, text: describe_("ROLLBACK_COMPLETE") };
+      return { status: 200, text: "<RollbackStackResponse/>" };
+    };
+    await rollbackStack({ stackName: "prod", endpoint: "http://x", intervalMs: 1 }, undefined, http);
+    expect(forms[0]).toMatchObject({ Action: "RollbackStack", StackName: "prod" });
+    expect(forms[0].Version).toBeDefined();
+  });
+
+  test("an absent stack is nothing to roll back — rolledBack: false, no throw", async () => {
+    const http: AwsHttp = async () => ({ status: 400, text: MISSING });
+    const res = await rollbackStack({ stackName: "s", endpoint: "http://x" }, undefined, http);
+    expect(res).toEqual({ stackName: "s", rolledBack: false });
+  });
+
+  test("a target without RollbackStack (Floci's UnknownAction, #947) degrades, not crashes", async () => {
+    const http: AwsHttp = async () => ({
+      status: 400,
+      text: "<ErrorResponse><Error><Code>UnknownAction</Code><Message>Action RollbackStack is not supported.</Message></Error></ErrorResponse>",
+    });
+    const res = await rollbackStack({ stackName: "s", endpoint: "http://x" }, undefined, http);
+    expect(res).toEqual({ stackName: "s", rolledBack: false });
+  });
+
+  test("any other API error throws — a compensation must not fail silently", async () => {
+    const http: AwsHttp = async () => ({
+      status: 400,
+      text: "<ErrorResponse><Error><Message>Rollback requires a stack in UPDATE_FAILED state</Message></Error></ErrorResponse>",
+    });
+    await expect(rollbackStack({ stackName: "s", endpoint: "http://x" }, undefined, http)).rejects.toThrow(
+      /RollbackStack failed \(400\): Rollback requires/,
+    );
+  });
+
+  test("throws when the stack settles anywhere but *ROLLBACK_COMPLETE", async () => {
+    const http: AwsHttp = async (_url, form) => {
+      if (form.Action === "DescribeStacks") return { status: 200, text: describe_("UPDATE_ROLLBACK_FAILED") };
+      return { status: 200, text: "<RollbackStackResponse/>" };
+    };
+    await expect(rollbackStack({ stackName: "s", endpoint: "http://x", intervalMs: 1 }, undefined, http)).rejects.toThrow(
+      /rollback → UPDATE_ROLLBACK_FAILED/,
+    );
+  });
+});

package/src/op/activities/aws-apply.ts

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { safeHeartbeat, sleep } from "@intentius/chant/op";
 import { awsDeployCapabilitiesForBody } from "../../components/cloud-executor.js";
 import { resolveEndpointOverride } from "../../api/read-client.js";
+import { ownershipStackTagsForBody } from "../../ownership.js";
 
 const DEFAULT_REGION = "us-east-1";
 const CFN_API_VERSION = "2010-05-15";
@@ -70,6 +71,22 @@ export function capabilityParams(capabilities: string[]): Record<string, string>
   return out;
 }
 
+/**
+ * Stack tags as the CFN `Tags.member.N.Key/Value` list params (#1222). Sorted
+ * so the request is deterministic. Empty in, empty out — a template without an
+ * ownership marker adds no `Tags` parameter at all.
+ */
+export function tagParams(tags: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  Object.keys(tags)
+    .sort()
+    .forEach((key, i) => {
+      out[`Tags.member.${i + 1}.Key`] = key;
+      out[`Tags.member.${i + 1}.Value`] = tags[key];
+    });
+  return out;
+}
+
 /**
  * First `<tag>…</tag>` text in a CFN XML response.
  *
@@ -127,10 +144,10 @@ export async function waitForStackSettled(
  * CloudFormation API directly (create-or-update + poll to a settled stack),
  * targeting a local Floci emulator or real AWS by endpoint override. The direct
  * twin of `azApply`/`gcpApply`: it speaks the CloudFormation Query API over HTTP
- * rather than shelling `aws cloudformation deploy` (that CLI path is still
- * available via `nativeApply({ target: "cloudformation" })`). The stack is the
- * ownership boundary, so deletes ride CloudFormation itself — no separate prune.
- * `http` is injectable for tests.
+ * rather than shelling `aws cloudformation deploy` — and since chant #1449 it is
+ * also what `nativeApply({ target: "cloudformation" })` runs, so no CLI path
+ * remains. The stack is the ownership boundary, so deletes ride CloudFormation
+ * itself — no separate prune. `http` is injectable for tests.
  */
 export async function awsApply(
   args: AwsApplyArgs,
@@ -149,7 +166,17 @@ export async function awsApply(
   }
   const exists = desc.status < 300;
 
-  const params = { StackName: args.stackName, TemplateBody: templateBody, ...capabilityParams(capabilities) };
+  // Stamp the template's ownership marker as the STACK's own tags (#1222):
+  // stack-level teardown verifies ownership on DescribeStacks tags, and this
+  // is the write that makes every future stack teardown-eligible. A template
+  // carrying no marker adds nothing.
+  const stackTags = ownershipStackTagsForBody(templateBody);
+  const params = {
+    StackName: args.stackName,
+    TemplateBody: templateBody,
+    ...capabilityParams(capabilities),
+    ...tagParams(stackTags),
+  };
   let action: "created" | "updated";
   if (!exists) {
     const res = await http(url, cfnForm("CreateStack", params), signal);
@@ -177,12 +204,18 @@ export async function awsApply(
   return { stackName: args.stackName, status, action };
 }
 
+/** {@link awsDelete}'s arguments: {@link AwsApplyArgs} minus the template — a
+ * delete needs no body, so teardown (#1222) can call it with a stack name
+ * alone. Op builders that thread `templatePath` through keep working; it is
+ * simply unused here. */
+export type AwsDeleteArgs = Omit<AwsApplyArgs, "templatePath"> & { templatePath?: string };
+
 /**
  * The inverse of {@link awsApply} — DeleteStack, then poll until the stack is
  * gone. Idempotent: an already-absent stack is a no-op. `http` is injectable.
  */
 export async function awsDelete(
-  args: AwsApplyArgs,
+  args: AwsDeleteArgs,
   signal?: AbortSignal,
   http: AwsHttp = defaultHttp,
 ): Promise<{ stackName: string; deleted: boolean }> {
@@ -208,3 +241,64 @@ export async function awsDelete(
   }
   throw new Error(`CloudFormation stack ${args.stackName} delete did not complete within ${timeoutMs}ms`);
 }
+
+export interface RollbackStackArgs {
+  /** CloudFormation stack name to roll back. */
+  stackName: string;
+  /** CFN endpoint override — same resolution rule as {@link AwsApplyArgs.endpoint} (#1694). */
+  endpoint?: string;
+  /** Region (real CFN host). Default: `us-east-1`. */
+  region?: string;
+  /** Stack-settle timeout in ms. Default: `300000`. */
+  timeoutMs?: number;
+  /** Poll interval in ms. Default: `3000`. */
+  intervalMs?: number;
+}
+
+/**
+ * The saga compensation for {@link awsApply} — CloudFormation `RollbackStack`
+ * via the same Query-API client, then poll until the stack settles. Returns the
+ * stack to its last known stable state after a failed update (#1449 — this
+ * replaces the Temporal lexicon exec-ing `aws cloudformation rollback-stack`).
+ *
+ * Degrades rather than crashes in two cases where there is nothing to do:
+ * an absent stack (nothing applied, nothing to revert) and a target that does
+ * not implement the action — Floci answers `UnknownAction` (#947). Both return
+ * `rolledBack: false` with a logged warning; every other API error throws,
+ * because a compensation that silently fails leaves partial state looking
+ * reverted when it isn't. `http` is injectable for tests.
+ */
+export async function rollbackStack(
+  args: RollbackStackArgs,
+  signal?: AbortSignal,
+  http: AwsHttp = defaultHttp,
+): Promise<{ stackName: string; rolledBack: boolean; status?: string }> {
+  const url = cfnUrl(args.endpoint, args.region);
+  const timeoutMs = args.timeoutMs ?? 300_000;
+  const intervalMs = args.intervalMs ?? 3_000;
+
+  const res = await http(url, cfnForm("RollbackStack", { StackName: args.stackName }), signal);
+  if (res.status >= 300) {
+    if (isStackMissing(res.text)) {
+      console.warn(`rollbackStack: stack ${args.stackName} does not exist — nothing to roll back`);
+      return { stackName: args.stackName, rolledBack: false };
+    }
+    // Local emulators (Floci) don't implement RollbackStack → `UnknownAction` (#947).
+    if (/UnknownAction|not supported/i.test(res.text)) {
+      console.warn(
+        `rollbackStack: the target doesn't support RollbackStack (a local emulator such as Floci) — skipping automated rollback of ${args.stackName}`,
+      );
+      return { stackName: args.stackName, rolledBack: false };
+    }
+    throw new Error(`CloudFormation RollbackStack failed (${res.status}): ${cfnErrorMessage(res.text) ?? res.text}`);
+  }
+
+  const status = await waitForStackSettled(url, args.stackName, http, { timeoutMs, intervalMs }, signal);
+  // A settled rollback ends in `ROLLBACK_COMPLETE`/`UPDATE_ROLLBACK_COMPLETE` —
+  // classified a failure by the deploy-path matcher, but the success state here.
+  if (!/ROLLBACK_COMPLETE$/.test(status)) {
+    throw new Error(`CloudFormation stack ${args.stackName} rollback → ${status}`);
+  }
+  console.log(`rolled back: ${args.stackName} (${status}) [${url}]`);
+  return { stackName: args.stackName, rolledBack: true, status };
+}

package/src/op/activities/index.ts

@@ -2,8 +2,9 @@
  * AWS Op activities — resolved by the core activity registry when a project's
  * `chant.config.ts` lists the `aws` lexicon. Contributes the local Floci AWS
  * emulator lifecycle (`flociUp`/`flociDown`) and the native CloudFormation
- * applier (`awsApply`), which calls the CloudFormation API directly rather than
- * shelling `aws` — the direct twin of `azApply`/`gcpApply`.
+ * applier (`awsApply`, with `awsDelete` and the `rollbackStack` compensation),
+ * which calls the CloudFormation API directly rather than shelling `aws` — the
+ * direct twin of `azApply`/`gcpApply`.
  *
  * The registry keys every exported *function* here by its name, so only the
  * activities themselves belong in this barrel. `awsAgentCoreFetchTrace`'s
@@ -28,6 +29,7 @@ export type { FlociUpArgs, FlociDownArgs } from "./floci";
 export {
   awsApply,
   awsDelete,
+  rollbackStack,
   waitForStackSettled,
   cfnUrl,
   cfnForm,
@@ -42,7 +44,7 @@ export {
   isFailureStatus,
   isTerminalStatus,
 } from "./aws-apply";
-export type { AwsApplyArgs, AwsHttp } from "./aws-apply";
+export type { AwsApplyArgs, RollbackStackArgs, AwsHttp } from "./aws-apply";
 
 export { awsAgentCoreFetchTrace } from "../../agentcore/trace-fetch";
 export type {

package/src/ownership.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "vitest";
 import { ownershipEntries } from "@intentius/chant/ownership";
-import { AWS_TAG_OWNERSHIP_KEYS } from "./ownership";
+import { AWS_TAG_OWNERSHIP_KEYS, OWNERSHIP_METADATA_KEY, ownershipStackTagsForBody } from "./ownership";
 
 describe("AWS_TAG_OWNERSHIP_KEYS", () => {
   test("uses AWS colon-form tag keys", () => {
@@ -16,3 +16,26 @@ describe("AWS_TAG_OWNERSHIP_KEYS", () => {
     expect(e).toEqual({ "chant:managed-by": "chant", "chant:stack": "billing", "chant:env": "prod" });
   });
 });
+
+describe("ownershipStackTagsForBody (#1222)", () => {
+  test("reads the flat tag map under Metadata[chant:ownership]", () => {
+    const body = JSON.stringify({
+      Metadata: { [OWNERSHIP_METADATA_KEY]: { "chant:managed-by": "chant", "chant:stack": "shop", "chant:env": "dev" } },
+      Resources: {},
+    });
+    expect(ownershipStackTagsForBody(body)).toEqual({
+      "chant:managed-by": "chant",
+      "chant:stack": "shop",
+      "chant:env": "dev",
+    });
+  });
+
+  test("total on bad input: non-JSON, no Metadata, no marker, non-string values", () => {
+    expect(ownershipStackTagsForBody("Resources:\n  B:\n")).toEqual({});
+    expect(ownershipStackTagsForBody(JSON.stringify({ Resources: {} }))).toEqual({});
+    expect(ownershipStackTagsForBody(JSON.stringify({ Metadata: {}, Resources: {} }))).toEqual({});
+    expect(
+      ownershipStackTagsForBody(JSON.stringify({ Metadata: { [OWNERSHIP_METADATA_KEY]: { a: 1, b: "x" } } })),
+    ).toEqual({ b: "x" });
+  });
+});

package/src/ownership.ts

@@ -13,3 +13,40 @@ export const AWS_TAG_OWNERSHIP_KEYS: ChannelKeys = {
   stack: "chant:stack",
   env: "chant:env",
 };
+
+/**
+ * Template-level `Metadata` key the serializer stamps the ownership marker
+ * under (#1222). Stack-level teardown verifies ownership on the *stack's own*
+ * tags, and CloudFormation stack tags are an API parameter, not a template
+ * section — so the template carries the marker here and the apply paths
+ * (`awsApply`, the `cfn-deploy` change set) turn it into stack tags on
+ * create/update. One source: the same build that stamps resource tags decides
+ * the stack tags.
+ */
+export const OWNERSHIP_METADATA_KEY = "chant:ownership";
+
+/**
+ * The stack tags a template body asks for: the flat tag map under
+ * `Metadata["chant:ownership"]`, or nothing. Total on bad input — a body that
+ * is not JSON (a YAML template, a handwritten one) or carries no marker
+ * returns `{}`, and the stack simply stays untagged, which teardown reports
+ * as unverified rather than deleting.
+ */
+export function ownershipStackTagsForBody(body: string): Record<string, string> {
+  let template: unknown;
+  try {
+    template = JSON.parse(body);
+  } catch {
+    return {};
+  }
+  if (typeof template !== "object" || template === null) return {};
+  const metadata = (template as { Metadata?: unknown }).Metadata;
+  if (typeof metadata !== "object" || metadata === null) return {};
+  const marker = (metadata as Record<string, unknown>)[OWNERSHIP_METADATA_KEY];
+  if (typeof marker !== "object" || marker === null) return {};
+  const tags: Record<string, string> = {};
+  for (const [key, value] of Object.entries(marker as Record<string, unknown>)) {
+    if (typeof value === "string") tags[key] = value;
+  }
+  return tags;
+}

package/src/plugin.ts

@@ -656,6 +656,9 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
         // this path cannot read the ownership marker. Say `unknown` explicitly
         // rather than leaving the field off and letting each consumer guess —
         // the change set never escalates `unknown` to a delete.
+        // For the same reason `marker` (#1222) stays absent here: no tags, no
+        // stack/env identity to read, and absent means absent — never a guess.
+        // aws teardown is stack-level and reads the stack's own tags instead.
         ownership: "unknown",
       };
     }
@@ -803,6 +806,21 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
     return { stack: options.stack, present: true, status, healthy };
   },
 
+  // Env teardown at STACK granularity (#1222): `describeResources` carries no
+  // tags, so per-resource marker selection is impossible here — the env's
+  // stacks are enumerated instead (`stacks[]`, else the env-named default) and
+  // ownership is verified on each stack's own DescribeStacks tags. Execution
+  // is DeleteStack via the applier's `awsDelete`. See ./teardown.ts.
+  async teardownOwned(options) {
+    const { teardownOwned } = await import("./teardown");
+    return teardownOwned(options);
+  },
+
+  async executeTeardown(options) {
+    const { executeTeardown } = await import("./teardown");
+    return executeTeardown(options);
+  },
+
   async exportResources(options: {
     environment: string;
     stack?: string;

package/src/serializer-ownership.test.ts

@@ -34,4 +34,22 @@ describe("awsSerializer ownership stamping (#119)", () => {
     const tags = (template.Resources.MyBucket.Properties?.Tags ?? []) as Array<{ Key: string }>;
     expect(tags.some((t) => t.Key.startsWith("chant:"))).toBe(false);
   });
+
+  test("carries the marker at the template level too — Metadata[chant:ownership], the stack-tag source (#1222)", () => {
+    const entities = new Map<string, Declarable>([["MyBucket", new MockBucket({ BucketName: "b" })]]);
+    const out = awsSerializer.serialize(entities, [], { ownership: { stack: "billing", env: "prod" } });
+    const template = JSON.parse(out as string);
+    expect(template.Metadata["chant:ownership"]).toEqual({
+      "chant:managed-by": "chant",
+      "chant:stack": "billing",
+      "chant:env": "prod",
+    });
+  });
+
+  test("no ownership context → no template Metadata block", () => {
+    const entities = new Map<string, Declarable>([["MyBucket", new MockBucket({ BucketName: "b" })]]);
+    const out = awsSerializer.serialize(entities, []);
+    const template = JSON.parse(out as string);
+    expect(template.Metadata).toBeUndefined();
+  });
 });