@intentius/chant-lexicon-aws 0.44.14 → 0.46.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,
@@ -25,8 +26,16 @@ const describe_ = (status: string) => `<DescribeStacksResponse><Stacks><member><
 
 describe("CFN pure helpers (#awsApply)", () => {
   test("cfnUrl: endpoint override vs real regional host", () => {
-    expect(cfnUrl("http://localhost:4566")).toBe("http://localhost:4566/");
-    expect(cfnUrl(undefined, "eu-west-1")).toBe("https://cloudformation.eu-west-1.amazonaws.com/");
+    expect(cfnUrl("http://localhost:4566", undefined, {})).toBe("http://localhost:4566/");
+    expect(cfnUrl(undefined, "eu-west-1", {})).toBe("https://cloudformation.eu-west-1.amazonaws.com/");
+  });
+
+  test("cfnUrl: AWS_ENDPOINT_URL[_CLOUDFORMATION] is an override too, the same rule as the read client (#1694)", () => {
+    expect(cfnUrl(undefined, "eu-west-1", { AWS_ENDPOINT_URL: "http://localhost:4566" })).toBe("http://localhost:4566/");
+    expect(
+      cfnUrl(undefined, "eu-west-1", { AWS_ENDPOINT_URL: "http://all:1", AWS_ENDPOINT_URL_CLOUDFORMATION: "http://cfn:2" }),
+    ).toBe("http://cfn:2/");
+    expect(cfnUrl("http://opt:3", "eu-west-1", { AWS_ENDPOINT_URL: "http://all:1" })).toBe("http://opt:3/");
   });
 
   test("cfnForm stamps Action + Version", () => {
@@ -55,9 +64,9 @@ describe("CFN pure helpers (#awsApply)", () => {
   });
 });
 
-function tmpl(): string {
+function tmpl(extra: Record<string, unknown> = {}): string {
   const p = `/tmp/chant-cfn-${process.pid}-${Math.round(performance.now())}.json`;
-  writeFileSync(p, JSON.stringify({ Resources: { B: { Type: "AWS::S3::Bucket" } } }));
+  writeFileSync(p, JSON.stringify({ ...extra, Resources: { B: { Type: "AWS::S3::Bucket" } } }));
   return p;
 }
 
@@ -77,6 +86,82 @@ describe("awsApply flow (#awsApply)", () => {
     expect(calls).toEqual(["DescribeStacks", "CreateStack", "DescribeStacks"]);
   });
 
+  test("capabilities follow the template: NAMED_IAM alone, plus AUTO_EXPAND for a Transform (#980)", async () => {
+    const sent: Record<string, string>[] = [];
+    let described = 0;
+    const http: AwsHttp = async (_url, form) => {
+      if (form.Action === "DescribeStacks") return described++ % 2 === 0 ? { status: 400, text: MISSING } : { status: 200, text: describe_("CREATE_COMPLETE") };
+      sent.push(form);
+      return { status: 200, text: CREATE_OK };
+    };
+    const plain = tmpl();
+    await awsApply({ templatePath: plain, stackName: "s", endpoint: "http://x", intervalMs: 1 }, undefined, http);
+    unlinkSync(plain);
+    expect(sent[0]["Capabilities.member.1"]).toBe("CAPABILITY_NAMED_IAM");
+    expect(sent[0]["Capabilities.member.2"]).toBeUndefined();
+
+    const macro = tmpl({ Transform: "AWS::SecretsManager-2020-07-23" });
+    await awsApply({ templatePath: macro, stackName: "s", endpoint: "http://x", intervalMs: 1 }, undefined, http);
+    unlinkSync(macro);
+    expect(sent[1]["Capabilities.member.1"]).toBe("CAPABILITY_NAMED_IAM");
+    expect(sent[1]["Capabilities.member.2"]).toBe("CAPABILITY_AUTO_EXPAND");
+
+    // An explicit list still wins.
+    const explicit = tmpl({ Transform: "AWS::Serverless-2016-10-31" });
+    await awsApply({ templatePath: explicit, stackName: "s", endpoint: "http://x", intervalMs: 1, capabilities: ["CAPABILITY_IAM"] }, undefined, http);
+    unlinkSync(explicit);
+    expect(sent[2]["Capabilities.member.1"]).toBe("CAPABILITY_IAM");
+    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) => {
@@ -141,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

@@ -1,20 +1,29 @@
 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";
-const DEFAULT_CAPABILITIES = ["CAPABILITY_NAMED_IAM"];
 
 export interface AwsApplyArgs {
   /** Path to a built CloudFormation template (JSON/YAML). */
   templatePath: string;
   /** CloudFormation stack name — the deploy boundary. */
   stackName: string;
-  /** CFN endpoint override (e.g. Floci `http://localhost:4566`). Default: real CloudFormation. */
+  /**
+   * CFN endpoint override (e.g. Floci `http://localhost:4566`). Omitted,
+   * `AWS_ENDPOINT_URL_CLOUDFORMATION` then `AWS_ENDPOINT_URL` answer — the same
+   * rule the read client applies (#1694). With neither: real CloudFormation.
+   */
   endpoint?: string;
   /** Region (real CFN host + `Version` context). Default: `us-east-1`. */
   region?: string;
-  /** Capabilities to acknowledge. Default: `["CAPABILITY_NAMED_IAM"]`. */
+  /**
+   * Capabilities to acknowledge. Default: `CAPABILITY_NAMED_IAM`, plus
+   * `CAPABILITY_AUTO_EXPAND` when the template has a top-level `Transform` (#980).
+   */
   capabilities?: string[];
   /** Stack-settle timeout in ms. Default: `300000`. */
   timeoutMs?: number;
@@ -37,9 +46,17 @@ const defaultHttp: AwsHttp = async (url, form, signal) => {
 
 // ── Pure helpers (CFN Query protocol) ─────────────────────────────────────────
 
-/** The CloudFormation endpoint URL — the override, or the real regional host. */
-export function cfnUrl(endpoint?: string, region = DEFAULT_REGION): string {
-  return `${(endpoint ?? `https://cloudformation.${region}.amazonaws.com`).replace(/\/$/, "")}/`;
+/**
+ * The CloudFormation endpoint URL — the override, or the real regional host.
+ * `env` is what the ambient-variable fallback reads; injectable for tests.
+ */
+export function cfnUrl(
+  endpoint?: string,
+  region = DEFAULT_REGION,
+  env: Record<string, string | undefined> = process.env,
+): string {
+  const override = resolveEndpointOverride("cloudformation", endpoint, env);
+  return `${(override ?? `https://cloudformation.${region}.amazonaws.com`).replace(/\/$/, "")}/`;
 }
 
 /** A CFN Query-protocol form body: `Action` + `Version` + params. */
@@ -54,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.
  *
@@ -111,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,
@@ -122,8 +155,8 @@ export async function awsApply(
   http: AwsHttp = defaultHttp,
 ): Promise<{ stackName: string; status: string; action: "created" | "updated" | "unchanged" }> {
   const url = cfnUrl(args.endpoint, args.region);
-  const capabilities = args.capabilities ?? DEFAULT_CAPABILITIES;
   const templateBody = readFileSync(args.templatePath, "utf8");
+  const capabilities = args.capabilities ?? awsDeployCapabilitiesForBody(templateBody);
   const timeoutMs = args.timeoutMs ?? 300_000;
   const intervalMs = args.intervalMs ?? 3_000;
 
@@ -133,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);
@@ -161,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 }> {
@@ -192,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

@@ -47,8 +47,14 @@ export { stackDoesNotExist } from "./stack-errors";
  * Provides serializer, lint rules, template detection,
  * import parsing, and code generation for AWS CloudFormation.
  */
-/** #1265 — the ownership notice is about the environment, so it is said once. */
-let warnedOwnership = false;
+/**
+ * describe-stack-resources returns no tags, so the ownership filter cannot be
+ * applied on this read path. Returned as a run-level note rather than printed
+ * (#1265): core says it once per run, after the answer, however many stacks
+ * were read. The text is the contract consumers grep for.
+ */
+const OWNERSHIP_UNAVAILABLE_NOTE =
+  "ownership filter unavailable on describeResources (no tags from describe-stack-resources) — returning all, each with an explicit `unknown` verdict; use `chant import --from <env> --owned` for ownership-filtered export";
 
 export const awsPlugin: LexiconPlugin = {
   name: "aws",
@@ -558,25 +564,17 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
     // The applier's own transport, pointed at the read APIs (#1206). Multi-region
     // estates target this stack's region, not the ambient one.
     const client: AwsReadClientOptions = {
-      ...(process.env.AWS_ENDPOINT_URL ? { endpoint: process.env.AWS_ENDPOINT_URL } : {}),
       ...(options.region ? { region: options.region } : {}),
     };
 
-    if (options.owned) {
-      // describe-stack-resources does not return tags, so ownership cannot be
-      // determined here. Degrade to detect-only rather than silently filtering.
-      //
-      // Once per process, not once per stack (#1265). It is a property of the
-      // environment, not of each stack, and a four-stack project printed four
-      // identical copies ahead of every answer — enough that an agent piping
-      // `graph --format ir` with `2>&1` had to skip lines to find the JSON.
-      warnedOwnership ||
-        // eslint-disable-next-line no-console
-        console.warn(
-        "[aws] ownership filter unavailable on describeResources (no tags from describe-stack-resources) — returning all, each with an explicit `unknown` verdict; use `chant import --from <env> --owned` for ownership-filtered export",
-        );
-      warnedOwnership = true;
-    }
+    // describe-stack-resources does not return tags, so ownership cannot be
+    // determined here. Degrade to detect-only rather than silently filtering,
+    // and say so as a note on the observation. It is a property of the
+    // environment, not of each stack: a four-stack project once printed four
+    // identical copies ahead of every answer (#1265) — enough that an agent
+    // piping `graph --format ir` with `2>&1` had to skip lines to find the
+    // JSON. Core dedupes the note across stacks and prints it with the footer.
+    const notes = options.owned ? [OWNERSHIP_UNAVAILABLE_NOTE] : undefined;
 
     // Derive stack name. A multi-stack project passes the explicit CloudFormation
     // stack this observation targets (see `stacks` in ChantConfig); otherwise the
@@ -600,7 +598,7 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
       if (err instanceof AwsReadError && stackDoesNotExist(err.message)) {
         const { observeByIdentity } = await import("./identity-observe");
         const identity = await observeByIdentity(options.entityNames, options.entities, resources, client);
-        return observation({ ...resources, ...identity.resources }, undefined, identity.queried);
+        return observation({ ...resources, ...identity.resources }, undefined, identity.queried, notes);
       }
       // Any other failure (credentials, throttling, a region that can't be
       // reached) establishes nothing about what is deployed. Reporting every
@@ -617,6 +615,8 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
           reason,
           `DescribeStackResources failed for stack "${stackName}": ${detail}`,
         ),
+        undefined,
+        notes,
       );
     }
 
@@ -633,20 +633,20 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
       stackOutputs = {};
     }
 
+    // The outputs are the stack's, not any member's (#1279). They used to be
+    // copied onto every resource's `attributes`, so a VPC carried the stack's
+    // `expWebIp` and no `CidrBlock`. They ride the envelope once, keyed by the
+    // stack, scrubbed of anything that looks secret.
+    const exports: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(stackOutputs)) {
+      exports[key] = /password|secret|token|key/i.test(key) ? "[REDACTED]" : value;
+    }
+    const stackExports = Object.keys(exports).length > 0 ? { [stackName]: exports } : undefined;
+
     for (const entityName of options.entityNames) {
       const stackResource = stackResourceMap.get(entityName);
       if (!stackResource) continue;
 
-      const attributes: Record<string, unknown> = {};
-      // Include stack outputs as attributes (scrub sensitive ones)
-      for (const [key, value] of Object.entries(stackOutputs)) {
-        if (/password|secret|token|key/i.test(key)) {
-          attributes[key] = "[REDACTED]";
-        } else {
-          attributes[key] = value;
-        }
-      }
-
       resources[entityName] = {
         type: stackResource.type,
         physicalId: stackResource.physicalId ?? "",
@@ -656,8 +656,10 @@ 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",
-        attributes: Object.keys(attributes).length > 0 ? attributes : undefined,
       };
     }
 
@@ -669,9 +671,9 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
     const { observeByIdentity } = await import("./identity-observe");
     const identity = await observeByIdentity(options.entityNames, options.entities, resources, client);
 
-    // Each resource's OWN properties, on top of the stack outputs above (#1279).
-    // Until this, a node's `attrs` were the stack's exports replicated onto
-    // every member, so no instance carried its own `VpcId`.
+    // Each resource's OWN properties (#1279). Until this, a node's `attrs` were
+    // the stack's exports replicated onto every member, so no instance carried
+    // its own `VpcId`.
     const own = await describeOwnProperties(resources, options.region);
     const withProperties = stampProviderDefaults(stampRegion(own.resources, options.region));
 
@@ -701,13 +703,13 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
           detail: `the stack was read, but this resource's own properties were not — ${own.failures.get(type) ?? "the describe call failed"}`,
         };
       }
-      return observation({ ...described, ...identity.resources }, holes, identity.queried);
+      return observation({ ...described, ...identity.resources }, holes, identity.queried, notes, stackExports);
     }
 
     // Every entity the stack answered for was answered for: an entity the
     // template doesn't carry is genuinely not in this stack, which is an
     // absence, not a hole — unless the identity fallback saw it live (#1647).
-    return observation({ ...withProperties, ...identity.resources }, undefined, identity.queried);
+    return observation({ ...withProperties, ...identity.resources }, undefined, identity.queried, notes, stackExports);
   },
 
   /**
@@ -804,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;