@intentius/chant-lexicon-aws 0.45.0 → 0.49.0

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

@@ -0,0 +1,220 @@
+import { describe, test, expect } from "vitest";
+import { createPostSynthContext } from "@intentius/chant-test-utils";
+import { waw063, checkDenyAllowContradiction } from "./waw063";
+
+function makeCtx(template: object) {
+  return createPostSynthContext({ aws: template });
+}
+
+describe("WAW063: IAM Policy Denies An Action It Also Allows", () => {
+  test("check metadata", () => {
+    expect(waw063.id).toBe("WAW063");
+    expect(waw063.description).toContain("Deny");
+  });
+
+  test("guardrail policy denies exactly what a workflow policy allows on the same role → error", () => {
+    // Mirrors the issue's own example: a role used by a StepFunctions workflow
+    // needs ec2:ModifyInstanceAttribute; a separately-attached guardrail policy
+    // denies it. Deploy succeeds; the workflow 403s at runtime.
+    const ctx = makeCtx({
+      Resources: {
+        WorkflowRole: { Type: "AWS::IAM::Role", Properties: { AssumeRolePolicyDocument: { Statement: [] } } },
+        WorkflowPolicy: {
+          Type: "AWS::IAM::Policy",
+          Properties: {
+            PolicyName: "workflow-needs",
+            Roles: [{ Ref: "WorkflowRole" }],
+            PolicyDocument: {
+              Statement: [{ Effect: "Allow", Action: "ec2:ModifyInstanceAttribute", Resource: "*" }],
+            },
+          },
+        },
+        SecurityGuardrailPolicy: {
+          Type: "AWS::IAM::Policy",
+          Properties: {
+            PolicyName: "guardrail",
+            Roles: [{ Ref: "WorkflowRole" }],
+            PolicyDocument: {
+              Statement: [{ Effect: "Deny", Action: "ec2:ModifyInstanceAttribute", Resource: "*" }],
+            },
+          },
+        },
+      },
+    });
+    const diags = checkDenyAllowContradiction(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WAW063");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].entity).toBe("WorkflowRole");
+    expect(diags[0].message).toContain("ec2:ModifyInstanceAttribute");
+    expect(diags[0].message).toContain("SecurityGuardrailPolicy");
+    expect(diags[0].message).toContain("WorkflowPolicy");
+    expect(diags[0].lexicon).toBe("aws");
+  });
+
+  test("wildcarded Deny nullifies a literal Allow on the same role's inline policy → error", () => {
+    const ctx = makeCtx({
+      Resources: {
+        AppRole: {
+          Type: "AWS::IAM::Role",
+          Properties: {
+            AssumeRolePolicyDocument: { Statement: [] },
+            Policies: [
+              {
+                PolicyName: "inline",
+                PolicyDocument: {
+                  Statement: [
+                    { Effect: "Allow", Action: "s3:GetObject", Resource: "*" },
+                    { Effect: "Deny", Action: "s3:*", Resource: "*" },
+                  ],
+                },
+              },
+            ],
+          },
+        },
+      },
+    });
+    expect(checkDenyAllowContradiction(ctx)).toHaveLength(1);
+  });
+
+  test("broad Allow with a narrow safety Deny (intentional guardrail) → no diagnostic", () => {
+    const ctx = makeCtx({
+      Resources: {
+        AppRole: {
+          Type: "AWS::IAM::Role",
+          Properties: {
+            AssumeRolePolicyDocument: { Statement: [] },
+            Policies: [
+              {
+                PolicyName: "inline",
+                PolicyDocument: {
+                  Statement: [
+                    { Effect: "Allow", Action: "ec2:*", Resource: "*" },
+                    { Effect: "Deny", Action: "ec2:TerminateInstances", Resource: "*" },
+                  ],
+                },
+              },
+            ],
+          },
+        },
+      },
+    });
+    expect(checkDenyAllowContradiction(ctx)).toHaveLength(0);
+  });
+
+  test("Deny on a different role than the Allow → no diagnostic", () => {
+    const ctx = makeCtx({
+      Resources: {
+        RoleA: {
+          Type: "AWS::IAM::Role",
+          Properties: {
+            AssumeRolePolicyDocument: { Statement: [] },
+            Policies: [{ PolicyName: "p", PolicyDocument: { Statement: [{ Effect: "Allow", Action: "ec2:ModifyInstanceAttribute", Resource: "*" }] } }],
+          },
+        },
+        RoleB: {
+          Type: "AWS::IAM::Role",
+          Properties: {
+            AssumeRolePolicyDocument: { Statement: [] },
+            Policies: [{ PolicyName: "p", PolicyDocument: { Statement: [{ Effect: "Deny", Action: "ec2:ModifyInstanceAttribute", Resource: "*" }] } }],
+          },
+        },
+      },
+    });
+    expect(checkDenyAllowContradiction(ctx)).toHaveLength(0);
+  });
+
+  test("Deny scoped to a disjoint literal resource → no diagnostic", () => {
+    const ctx = makeCtx({
+      Resources: {
+        AppRole: {
+          Type: "AWS::IAM::Role",
+          Properties: {
+            AssumeRolePolicyDocument: { Statement: [] },
+            Policies: [
+              {
+                PolicyName: "inline",
+                PolicyDocument: {
+                  Statement: [
+                    { Effect: "Allow", Action: "s3:GetObject", Resource: "arn:aws:s3:::bucket-a/*" },
+                    { Effect: "Deny", Action: "s3:GetObject", Resource: "arn:aws:s3:::bucket-b/*" },
+                  ],
+                },
+              },
+            ],
+          },
+        },
+      },
+    });
+    expect(checkDenyAllowContradiction(ctx)).toHaveLength(0);
+  });
+
+  test("conditional Deny is skipped (unprovable statically) → no diagnostic", () => {
+    const ctx = makeCtx({
+      Resources: {
+        AppRole: {
+          Type: "AWS::IAM::Role",
+          Properties: {
+            AssumeRolePolicyDocument: { Statement: [] },
+            Policies: [
+              {
+                PolicyName: "inline",
+                PolicyDocument: {
+                  Statement: [
+                    { Effect: "Allow", Action: "s3:GetObject", Resource: "*" },
+                    {
+                      Effect: "Deny",
+                      Action: "s3:GetObject",
+                      Resource: "*",
+                      Condition: { StringNotEquals: { "aws:SourceVpc": "vpc-123" } },
+                    },
+                  ],
+                },
+              },
+            ],
+          },
+        },
+      },
+    });
+    expect(checkDenyAllowContradiction(ctx)).toHaveLength(0);
+  });
+
+  test("Deny from a managed policy attached via ManagedPolicyArns collides with an inline Allow → error", () => {
+    const ctx = makeCtx({
+      Resources: {
+        AppRole: {
+          Type: "AWS::IAM::Role",
+          Properties: {
+            AssumeRolePolicyDocument: { Statement: [] },
+            ManagedPolicyArns: [{ Ref: "GuardrailManagedPolicy" }],
+            Policies: [{ PolicyName: "inline", PolicyDocument: { Statement: [{ Effect: "Allow", Action: "ec2:ModifyInstanceAttribute", Resource: "*" }] } }],
+          },
+        },
+        GuardrailManagedPolicy: {
+          Type: "AWS::IAM::ManagedPolicy",
+          Properties: {
+            PolicyDocument: { Statement: [{ Effect: "Deny", Action: "ec2:ModifyInstanceAttribute", Resource: "*" }] },
+          },
+        },
+      },
+    });
+    const diags = checkDenyAllowContradiction(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("GuardrailManagedPolicy");
+  });
+
+  test("role with only Allow statements → no diagnostic", () => {
+    const ctx = makeCtx({
+      Resources: {
+        AppRole: {
+          Type: "AWS::IAM::Role",
+          Properties: {
+            AssumeRolePolicyDocument: { Statement: [] },
+            Policies: [{ PolicyName: "p", PolicyDocument: { Statement: [{ Effect: "Allow", Action: "s3:GetObject", Resource: "*" }] } }],
+          },
+        },
+      },
+    });
+    expect(checkDenyAllowContradiction(ctx)).toHaveLength(0);
+  });
+});

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,22 @@ export {
   isFailureStatus,
   isTerminalStatus,
 } from "./aws-apply";
-export type { AwsApplyArgs, AwsHttp } from "./aws-apply";
+export type { AwsApplyArgs, RollbackStackArgs, AwsHttp } from "./aws-apply";
+
+// Effect-receipt activities (#1835) — core's receipt seam (#1834) bound to
+// the SSM store, the way the k8s lexicon binds `ensureSecret` (#1830). The
+// registry keys exported functions by name, so the three bound activities are
+// re-exported individually: `receiptRead`/`receiptWrite` serve the `effect()`
+// step's read-compare-run-write, `receiptStaleness` serves WatchOp's
+// read-only phase. The store resolves its path identity and endpoint lazily
+// at first use, so this module stays cheap to load.
+import { receiptActivities } from "@intentius/chant/op/receipt-store";
+import { awsReceiptStore } from "../../receipt-store";
+
+const boundReceiptActivities = receiptActivities(awsReceiptStore());
+export const receiptRead = boundReceiptActivities.receiptRead;
+export const receiptWrite = boundReceiptActivities.receiptWrite;
+export const receiptStaleness = boundReceiptActivities.receiptStaleness;
 
 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;
+}