@intentius/chant-lexicon-aws 0.15.2 → 0.16.0

package/src/generated/lexicon-aws.json

@@ -8672,6 +8672,16 @@
     "kind": "property",
     "lexicon": "aws"
   },
+  "AzureProviderConfiguration": {
+    "resourceType": "AWS::SecurityHub::Connector.AzureProviderConfiguration",
+    "kind": "property",
+    "lexicon": "aws"
+  },
+  "AzureScopeConfiguration": {
+    "resourceType": "AWS::SecurityHub::Connector.AzureScopeConfiguration",
+    "kind": "property",
+    "lexicon": "aws"
+  },
   "B2BICapability": {
     "resourceType": "AWS::B2BI::Capability",
     "kind": "resource",
@@ -18201,6 +18211,9 @@
     "resourceType": "AWS::Config::ConformancePack",
     "kind": "resource",
     "lexicon": "aws",
+    "attrs": {
+      "ConformancePackArn": "ConformancePackArn"
+    },
     "propertyConstraints": {
       "ConformancePackName": {
         "pattern": "[a-zA-Z][-a-zA-Z0-9]*",
@@ -18235,13 +18248,23 @@
     ],
     "primaryIdentifier": [
       "ConformancePackName"
-    ]
+    ],
+    "tagging": {
+      "taggable": true,
+      "tagOnCreate": true,
+      "tagUpdatable": true
+    }
   },
   "ConformancePack_ConformancePackInputParameter": {
     "resourceType": "AWS::Config::ConformancePack.ConformancePackInputParameter",
     "kind": "property",
     "lexicon": "aws"
   },
+  "ConformancePack_Tag": {
+    "resourceType": "AWS::Config::ConformancePack.Tag",
+    "kind": "property",
+    "lexicon": "aws"
+  },
   "ConnectAction": {
     "resourceType": "AWS::SES::ReceiptRule.ConnectAction",
     "kind": "property",
@@ -19800,7 +19823,10 @@
       "ConnectorStatus": "ConnectorStatus",
       "LastUpdatedAt": "LastUpdatedAt",
       "LastCheckedAt": "LastCheckedAt",
-      "CreatedAt": "CreatedAt"
+      "CreatedAt": "CreatedAt",
+      "EnablementStatus": "EnablementStatus",
+      "EnablementStatusReason": "EnablementStatusReason",
+      "Issues": "Issues"
     },
     "propertyConstraints": {
       "Name": {
@@ -19818,14 +19844,6 @@
         "minLength": 20,
         "maxLength": 2048
       },
-      "ConnectorStatus": {
-        "enum": [
-          "CONNECTED",
-          "FAILED_TO_CONNECT",
-          "PENDING_AUTHORIZATION",
-          "PENDING_CONFIGURATION"
-        ]
-      },
       "ConnectorArn": {
         "pattern": "^arn:aws\\S*:securityhub:[a-z0-9-]+:[0-9]{12}:connectorv2/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
       },
@@ -19836,7 +19854,8 @@
     "createOnly": [
       "Name",
       "KmsKeyArn",
-      "Provider/ServiceNow/InstanceName"
+      "Provider/ServiceNow/InstanceName",
+      "Provider/Azure/AWSConfigConnectorArn"
     ],
     "primaryIdentifier": [
       "ConnectorArn"
@@ -19847,6 +19866,11 @@
       "tagUpdatable": true
     }
   },
+  "ConnectorV2_HealthIssue": {
+    "resourceType": "AWS::SecurityHub::ConnectorV2.HealthIssue",
+    "kind": "property",
+    "lexicon": "aws"
+  },
   "ConnectorVpcLatticeEgressConfig": {
     "resourceType": "AWS::Transfer::Connector.ConnectorVpcLatticeEgressConfig",
     "kind": "property",
@@ -87621,6 +87645,63 @@
     "kind": "property",
     "lexicon": "aws"
   },
+  "SecurityHubConnector": {
+    "resourceType": "AWS::SecurityHub::Connector",
+    "kind": "resource",
+    "lexicon": "aws",
+    "attrs": {
+      "ConnectorArn": "ConnectorArn",
+      "ConnectorId": "ConnectorId",
+      "ConnectorStatus": "ConnectorStatus",
+      "Message": "Message",
+      "LastCheckedAt": "LastCheckedAt",
+      "CreatedAt": "CreatedAt",
+      "LastUpdatedAt": "LastUpdatedAt",
+      "CreatedBy": "CreatedBy",
+      "EnablementStatus": "EnablementStatus",
+      "Issues": "Issues"
+    },
+    "propertyConstraints": {
+      "ConnectorArn": {
+        "pattern": "^arn:aws\\S*:securityhub:[a-z0-9-]+:[0-9]{12}:connector/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+      },
+      "ConnectorId": {
+        "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+      }
+    },
+    "createOnly": [
+      "Name",
+      "Provider/Azure/AWSConfigConnectorArn"
+    ],
+    "primaryIdentifier": [
+      "ConnectorArn"
+    ],
+    "tagging": {
+      "taggable": true,
+      "tagOnCreate": true,
+      "tagUpdatable": true
+    }
+  },
+  "SecurityHubConnector_AzureProviderConfiguration": {
+    "resourceType": "AWS::SecurityHub::Connector.AzureProviderConfiguration",
+    "kind": "property",
+    "lexicon": "aws"
+  },
+  "SecurityHubConnector_AzureScopeConfiguration": {
+    "resourceType": "AWS::SecurityHub::Connector.AzureScopeConfiguration",
+    "kind": "property",
+    "lexicon": "aws"
+  },
+  "SecurityHubConnector_HealthIssue": {
+    "resourceType": "AWS::SecurityHub::Connector.HealthIssue",
+    "kind": "property",
+    "lexicon": "aws"
+  },
+  "SecurityHubConnector_Provider": {
+    "resourceType": "AWS::SecurityHub::Connector.Provider",
+    "kind": "property",
+    "lexicon": "aws"
+  },
   "SecurityHubHub": {
     "resourceType": "AWS::SecurityHub::Hub",
     "kind": "resource",
@@ -97964,6 +98045,32 @@
     "kind": "property",
     "lexicon": "aws"
   },
+  "TransitGatewayPolicyTable": {
+    "resourceType": "AWS::EC2::TransitGatewayPolicyTable",
+    "kind": "resource",
+    "lexicon": "aws",
+    "attrs": {
+      "TransitGatewayPolicyTableId": "TransitGatewayPolicyTableId",
+      "State": "State",
+      "CreationTime": "CreationTime"
+    },
+    "createOnly": [
+      "TransitGatewayId"
+    ],
+    "primaryIdentifier": [
+      "TransitGatewayPolicyTableId"
+    ],
+    "tagging": {
+      "taggable": true,
+      "tagOnCreate": true,
+      "tagUpdatable": true
+    }
+  },
+  "TransitGatewayPolicyTable_Tag": {
+    "resourceType": "AWS::EC2::TransitGatewayPolicyTable.Tag",
+    "kind": "property",
+    "lexicon": "aws"
+  },
   "TransitGatewayRegistration": {
     "resourceType": "AWS::NetworkManager::TransitGatewayRegistration",
     "kind": "resource",

package/src/live-attrs.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect } from "vitest";
+import { resolveTemplateAttrs } from "./live-attrs";
+import { reconstructEdges } from "@intentius/chant/graph-refs";
+import type { IRNode } from "@intentius/chant/graph-ir";
+import { awsReferenceCatalog } from "./reference-catalog";
+import type { ExportedTemplate } from "@intentius/chant/lexicon";
+
+const tmpl = (resources: Array<{ logicalId: string; type: string; properties: Record<string, unknown> }>): ExportedTemplate =>
+  ({ resources, parameters: [], outputs: {} }) as unknown as ExportedTemplate;
+
+describe("resolveTemplateAttrs", () => {
+  it("resolves {Ref} and {Fn::GetAtt} intrinsics to bare logical ids", () => {
+    const attrs = resolveTemplateAttrs(
+      tmpl([
+        { logicalId: "Subnet", type: "AWS::EC2::Subnet", properties: { VpcId: { Ref: "Vpc" }, CidrBlock: "10.0.1.0/24" } },
+        { logicalId: "Listener", type: "AWS::ElasticLoadBalancingV2::Listener", properties: { LoadBalancerArn: { "Fn::GetAtt": ["Alb", "Arn"] } } },
+      ]),
+    );
+    expect(attrs.Subnet).toEqual({ VpcId: "Vpc", CidrBlock: "10.0.1.0/24" });
+    expect(attrs.Listener).toEqual({ LoadBalancerArn: "Alb" });
+  });
+
+  it("resolves intrinsics nested in arrays and objects", () => {
+    const attrs = resolveTemplateAttrs(
+      tmpl([
+        { logicalId: "Inst", type: "AWS::EC2::Instance", properties: { SecurityGroupIds: [{ Ref: "SgA" }, { Ref: "SgB" }], Nested: { SubnetId: { Ref: "Sn" } } } },
+      ]),
+    );
+    expect(attrs.Inst.SecurityGroupIds).toEqual(["SgA", "SgB"]);
+    expect(attrs.Inst.Nested).toEqual({ SubnetId: "Sn" });
+  });
+});
+
+describe("live edges from a CloudFormation template (#784)", () => {
+  it("reconstructs containment + edges from resolved template attrs", () => {
+    const template = tmpl([
+      { logicalId: "Vpc", type: "AWS::EC2::VPC", properties: { CidrBlock: "10.0.0.0/16" } },
+      { logicalId: "Subnet", type: "AWS::EC2::Subnet", properties: { VpcId: { Ref: "Vpc" } } },
+      { logicalId: "Sg", type: "AWS::EC2::SecurityGroup", properties: { VpcId: { Ref: "Vpc" } } },
+      { logicalId: "Inst", type: "AWS::EC2::Instance", properties: { SubnetId: { Ref: "Subnet" }, SecurityGroupIds: [{ Ref: "Sg" }] } },
+    ]);
+    const attrsById = resolveTemplateAttrs(template);
+    const nodes: IRNode[] = template.resources.map((r) => ({ id: r.logicalId, kind: r.type, lexicon: "aws", attrs: attrsById[r.logicalId] }));
+
+    const { edges, containment, dangling } = reconstructEdges(nodes, awsReferenceCatalog);
+    // containment: subnet and sg are inside the VPC; the instance is inside the subnet
+    expect(containment).toContainEqual({ child: "Subnet", parent: "Vpc", label: "in VPC" });
+    expect(containment).toContainEqual({ child: "Sg", parent: "Vpc", label: "in VPC" });
+    expect(containment).toContainEqual({ child: "Inst", parent: "Subnet", label: "in subnet" });
+    // edge: the instance references the security group
+    expect(edges).toContainEqual({ from: "Inst", to: "Sg", kind: "ref", viaAttr: "sg" });
+    expect(dangling).toEqual([]);
+  });
+});

package/src/live-attrs.ts

@@ -0,0 +1,40 @@
+import type { ExportedTemplate } from "@intentius/chant/lexicon";
+
+/**
+ * Resolve a live CloudFormation template's per-resource properties into flat
+ * attributes for `chant graph --live` edge reconstruction (#784).
+ *
+ * `describeResources()` returns thin metadata (stack outputs), so the reference
+ * resolver (#778) had nothing to match on. `exportResources()` returns the
+ * deployed template, where resources reference each other by **logical id** via
+ * `{Ref: LogicalId}` / `{Fn::GetAtt: [LogicalId, …]}`. Logical id == the IR node
+ * id (both keyed by the CloudFormation logical name), so resolving those
+ * intrinsics to the bare logical-id string turns each reference into a value the
+ * resolver matches directly (it indexes every node by its own id).
+ */
+function resolveIntrinsics(v: unknown): unknown {
+  if (Array.isArray(v)) return v.map(resolveIntrinsics);
+  if (v && typeof v === "object") {
+    const o = v as Record<string, unknown>;
+    const keys = Object.keys(o);
+    if (keys.length === 1 && typeof o.Ref === "string") return o.Ref;
+    if (keys.length === 1 && o["Fn::GetAtt"] !== undefined) {
+      const g = o["Fn::GetAtt"];
+      if (Array.isArray(g) && typeof g[0] === "string") return g[0]; // ["LogicalId", "Attr"]
+      if (typeof g === "string") return g.split(".")[0]; // "LogicalId.Attr"
+    }
+    const out: Record<string, unknown> = {};
+    for (const [k, val] of Object.entries(o)) out[k] = resolveIntrinsics(val);
+    return out;
+  }
+  return v;
+}
+
+/** logical id → resolved properties (references become bare logical-id strings). */
+export function resolveTemplateAttrs(template: ExportedTemplate): Record<string, Record<string, unknown>> {
+  const out: Record<string, Record<string, unknown>> = {};
+  for (const r of template.resources) {
+    out[r.logicalId] = resolveIntrinsics(r.properties) as Record<string, unknown>;
+  }
+  return out;
+}

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

@@ -0,0 +1,143 @@
+import { describe, test, expect } from "vitest";
+import { writeFileSync, unlinkSync } from "node:fs";
+import {
+  awsApply,
+  awsDelete,
+  cfnUrl,
+  cfnForm,
+  capabilityParams,
+  xmlField,
+  stackStatus,
+  stackId,
+  isStackMissing,
+  isNoUpdates,
+  isSuccessStatus,
+  isFailureStatus,
+  isTerminalStatus,
+  type AwsHttp,
+} from "./aws-apply";
+
+const CREATE_OK = "<CreateStackResponse><CreateStackResult><StackId>arn:stack/s</StackId></CreateStackResult></CreateStackResponse>";
+const UPDATE_OK = "<UpdateStackResponse><UpdateStackResult><StackId>arn:stack/s</StackId></UpdateStackResult></UpdateStackResponse>";
+const MISSING = "<ErrorResponse><Error><Code>ValidationError</Code><Message>Stack with id s does not exist</Message></Error></ErrorResponse>";
+const NO_UPDATES = "<ErrorResponse><Error><Message>No updates are to be performed.</Message></Error></ErrorResponse>";
+const describe_ = (status: string) => `<DescribeStacksResponse><Stacks><member><StackId>arn:stack/s</StackId><StackStatus>${status}</StackStatus></member></Stacks></DescribeStacksResponse>`;
+
+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/");
+  });
+
+  test("cfnForm stamps Action + Version", () => {
+    expect(cfnForm("CreateStack", { StackName: "s" })).toEqual({ Action: "CreateStack", Version: "2010-05-15", StackName: "s" });
+  });
+
+  test("capabilityParams → Capabilities.member.N", () => {
+    expect(capabilityParams(["CAPABILITY_NAMED_IAM", "CAPABILITY_IAM"])).toEqual({
+      "Capabilities.member.1": "CAPABILITY_NAMED_IAM",
+      "Capabilities.member.2": "CAPABILITY_IAM",
+    });
+  });
+
+  test("xml parsing + status classification", () => {
+    expect(xmlField(describe_("CREATE_COMPLETE"), "StackStatus")).toBe("CREATE_COMPLETE");
+    expect(stackStatus(describe_("UPDATE_COMPLETE"))).toBe("UPDATE_COMPLETE");
+    expect(stackId(CREATE_OK)).toBe("arn:stack/s");
+    expect(isStackMissing(MISSING)).toBe(true);
+    expect(isNoUpdates(NO_UPDATES)).toBe(true);
+    expect(isSuccessStatus("CREATE_COMPLETE")).toBe(true);
+    expect(isSuccessStatus("UPDATE_COMPLETE_CLEANUP_IN_PROGRESS")).toBe(false); // transient, not settled
+    expect(isFailureStatus("ROLLBACK_COMPLETE")).toBe(true);
+    expect(isFailureStatus("CREATE_FAILED")).toBe(true);
+    expect(isTerminalStatus("CREATE_IN_PROGRESS")).toBe(false);
+    expect(isTerminalStatus("DELETE_COMPLETE")).toBe(true);
+  });
+});
+
+function tmpl(): string {
+  const p = `/tmp/chant-cfn-${process.pid}-${Math.round(performance.now())}.json`;
+  writeFileSync(p, JSON.stringify({ Resources: { B: { Type: "AWS::S3::Bucket" } } }));
+  return p;
+}
+
+describe("awsApply flow (#awsApply)", () => {
+  test("create path: absent stack → CreateStack → poll to CREATE_COMPLETE", async () => {
+    const calls: string[] = [];
+    let described = 0;
+    const http: AwsHttp = async (_url, form) => {
+      calls.push(form.Action);
+      if (form.Action === "DescribeStacks") return described++ === 0 ? { status: 400, text: MISSING } : { status: 200, text: describe_("CREATE_COMPLETE") };
+      return { status: 200, text: CREATE_OK };
+    };
+    const p = tmpl();
+    const res = await awsApply({ templatePath: p, stackName: "s", endpoint: "http://x", intervalMs: 1 }, undefined, http);
+    unlinkSync(p);
+    expect(res).toEqual({ stackName: "s", status: "CREATE_COMPLETE", action: "created" });
+    expect(calls).toEqual(["DescribeStacks", "CreateStack", "DescribeStacks"]);
+  });
+
+  test("update path: existing stack → UpdateStack → UPDATE_COMPLETE", async () => {
+    let described = 0;
+    const http: AwsHttp = async (_url, form) => {
+      if (form.Action === "DescribeStacks") return { status: 200, text: describe_(described++ === 0 ? "CREATE_COMPLETE" : "UPDATE_COMPLETE") };
+      return { status: 200, text: UPDATE_OK };
+    };
+    const p = tmpl();
+    const res = await awsApply({ templatePath: p, stackName: "s", endpoint: "http://x", intervalMs: 1 }, undefined, http);
+    unlinkSync(p);
+    expect(res.action).toBe("updated");
+    expect(res.status).toBe("UPDATE_COMPLETE");
+  });
+
+  test("no-op update (real-AWS error) → unchanged, no poll", async () => {
+    const http: AwsHttp = async (_url, form) => {
+      if (form.Action === "DescribeStacks") return { status: 200, text: describe_("CREATE_COMPLETE") };
+      return { status: 400, text: NO_UPDATES }; // UpdateStack
+    };
+    const p = tmpl();
+    const res = await awsApply({ templatePath: p, stackName: "s", endpoint: "http://x" }, undefined, http);
+    unlinkSync(p);
+    expect(res).toEqual({ stackName: "s", status: "UPDATE_COMPLETE", action: "unchanged" });
+  });
+
+  test("throws when the stack settles to a failure state", async () => {
+    let described = 0;
+    const http: AwsHttp = async (_url, form) => {
+      if (form.Action === "DescribeStacks") return described++ === 0 ? { status: 400, text: MISSING } : { status: 200, text: describe_("ROLLBACK_COMPLETE") };
+      return { status: 200, text: CREATE_OK };
+    };
+    const p = tmpl();
+    await expect(
+      awsApply({ templatePath: p, stackName: "s", endpoint: "http://x", intervalMs: 1 }, undefined, http),
+    ).rejects.toThrow(/created → ROLLBACK_COMPLETE/);
+    unlinkSync(p);
+  });
+
+  test("surfaces a CreateStack API error", async () => {
+    const http: AwsHttp = async (_url, form) =>
+      form.Action === "DescribeStacks" ? { status: 400, text: MISSING } : { status: 400, text: "<Error><Message>bad template</Message></Error>" };
+    const p = tmpl();
+    await expect(
+      awsApply({ templatePath: p, stackName: "s", endpoint: "http://x" }, undefined, http),
+    ).rejects.toThrow(/CreateStack failed \(400\): bad template/);
+    unlinkSync(p);
+  });
+});
+
+describe("awsDelete (#awsApply)", () => {
+  test("DeleteStack then polls until the stack is gone", async () => {
+    const calls: string[] = [];
+    let described = 0;
+    const http: AwsHttp = async (_url, form) => {
+      calls.push(form.Action);
+      if (form.Action === "DescribeStacks") return described++ === 0 ? { status: 200, text: describe_("DELETE_IN_PROGRESS") } : { status: 400, text: MISSING };
+      return { status: 200, text: "<DeleteStackResponse/>" };
+    };
+    const p = tmpl();
+    const res = await awsDelete({ templatePath: p, stackName: "s", endpoint: "http://x", intervalMs: 1 }, undefined, http);
+    unlinkSync(p);
+    expect(res).toEqual({ stackName: "s", deleted: true });
+    expect(calls[0]).toBe("DeleteStack");
+  });
+});

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

@@ -0,0 +1,194 @@
+import { readFileSync } from "node:fs";
+import { safeHeartbeat, sleep } from "@intentius/chant/op";
+
+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. */
+  endpoint?: string;
+  /** Region (real CFN host + `Version` context). Default: `us-east-1`. */
+  region?: string;
+  /** Capabilities to acknowledge. Default: `["CAPABILITY_NAMED_IAM"]`. */
+  capabilities?: string[];
+  /** Stack-settle timeout in ms. Default: `300000`. */
+  timeoutMs?: number;
+  /** Poll interval in ms. Default: `3000`. */
+  intervalMs?: number;
+}
+
+/** Injectable CFN transport — a form POST returning the raw XML. Mirrors the az/gcp appliers so tests avoid the network. */
+export type AwsHttp = (url: string, form: Record<string, string>, signal?: AbortSignal) => Promise<{ status: number; text: string }>;
+
+const defaultHttp: AwsHttp = async (url, form, signal) => {
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams(form).toString(),
+    signal,
+  });
+  return { status: res.status, text: await res.text() };
+};
+
+// ── 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(/\/$/, "")}/`;
+}
+
+/** A CFN Query-protocol form body: `Action` + `Version` + params. */
+export function cfnForm(action: string, params: Record<string, string>): Record<string, string> {
+  return { Action: action, Version: CFN_API_VERSION, ...params };
+}
+
+/** Capabilities as the CFN `Capabilities.member.N` list params. */
+export function capabilityParams(capabilities: string[]): Record<string, string> {
+  const out: Record<string, string> = {};
+  capabilities.forEach((c, i) => (out[`Capabilities.member.${i + 1}`] = c));
+  return out;
+}
+
+/**
+ * First `<tag>…</tag>` text in a CFN XML response.
+ *
+ * Assumes flat scalar fields — the CloudFormation Query API returns simple
+ * `<StackStatus>…</StackStatus>` style leaves, so `[^<]*` is sufficient. It does
+ * NOT handle nested tags or XML entities in the value; if a field ever carries
+ * either, replace this with a real XML parser.
+ */
+export function xmlField(xml: string, tag: string): string | undefined {
+  return xml.match(new RegExp(`<${tag}>([^<]*)</${tag}>`))?.[1];
+}
+
+export const stackStatus = (xml: string): string | undefined => xmlField(xml, "StackStatus");
+export const stackId = (xml: string): string | undefined => xmlField(xml, "StackId");
+export const cfnErrorMessage = (xml: string): string | undefined => xmlField(xml, "Message");
+
+/** A DescribeStacks error for an absent stack (drives create-vs-update). */
+export const isStackMissing = (xml: string): boolean => /does not exist/i.test(xml);
+/** The real-AWS UpdateStack no-op error (Floci returns 200 instead). */
+export const isNoUpdates = (xml: string): boolean => /No updates are to be performed/i.test(xml);
+
+const SUCCESS_STATUS = new Set(["CREATE_COMPLETE", "UPDATE_COMPLETE", "IMPORT_COMPLETE"]);
+export const isSuccessStatus = (status: string): boolean => SUCCESS_STATUS.has(status);
+export const isFailureStatus = (status: string): boolean => /FAILED|ROLLBACK/.test(status);
+/** A settled stack state — success, failure, or deleted. Transient `*_IN_PROGRESS` states aren't. */
+export const isTerminalStatus = (status: string): boolean =>
+  isSuccessStatus(status) || isFailureStatus(status) || status === "DELETE_COMPLETE";
+
+// ── Poll ──────────────────────────────────────────────────────────────────────
+
+/** Poll DescribeStacks until the stack reaches a terminal state; returns that status. */
+export async function waitForStackSettled(
+  url: string,
+  stackName: string,
+  http: AwsHttp,
+  opts: { timeoutMs: number; intervalMs: number },
+  signal?: AbortSignal,
+): Promise<string> {
+  const deadline = Date.now() + opts.timeoutMs;
+  while (Date.now() < deadline) {
+    if (signal?.aborted) throw new Error("awsApply aborted");
+    safeHeartbeat({ step: "awsApply", stack: stackName });
+    const res = await http(url, cfnForm("DescribeStacks", { StackName: stackName }), signal);
+    const status = stackStatus(res.text);
+    if (status && isTerminalStatus(status)) return status;
+    await sleep(opts.intervalMs, signal);
+  }
+  throw new Error(`CloudFormation stack ${stackName} did not settle within ${opts.timeoutMs}ms`);
+}
+
+// ── Apply / delete ──────────────────────────────────────────────────────────
+
+/**
+ * The native AWS applier — deploy a built CloudFormation template by calling the
+ * 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.
+ */
+export async function awsApply(
+  args: AwsApplyArgs,
+  signal?: AbortSignal,
+  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 timeoutMs = args.timeoutMs ?? 300_000;
+  const intervalMs = args.intervalMs ?? 3_000;
+
+  const desc = await http(url, cfnForm("DescribeStacks", { StackName: args.stackName }), signal);
+  if (desc.status >= 300 && !isStackMissing(desc.text)) {
+    throw new Error(`CloudFormation DescribeStacks failed (${desc.status}): ${cfnErrorMessage(desc.text) ?? desc.text}`);
+  }
+  const exists = desc.status < 300;
+
+  const params = { StackName: args.stackName, TemplateBody: templateBody, ...capabilityParams(capabilities) };
+  let action: "created" | "updated";
+  if (!exists) {
+    const res = await http(url, cfnForm("CreateStack", params), signal);
+    if (res.status >= 300) {
+      throw new Error(`CloudFormation CreateStack failed (${res.status}): ${cfnErrorMessage(res.text) ?? res.text}`);
+    }
+    action = "created";
+  } else {
+    const res = await http(url, cfnForm("UpdateStack", params), signal);
+    if (res.status >= 300) {
+      if (isNoUpdates(res.text)) {
+        console.log(`unchanged: ${args.stackName} (no updates)`);
+        return { stackName: args.stackName, status: "UPDATE_COMPLETE", action: "unchanged" };
+      }
+      throw new Error(`CloudFormation UpdateStack failed (${res.status}): ${cfnErrorMessage(res.text) ?? res.text}`);
+    }
+    action = "updated";
+  }
+
+  const status = await waitForStackSettled(url, args.stackName, http, { timeoutMs, intervalMs }, signal);
+  if (isFailureStatus(status)) {
+    throw new Error(`CloudFormation stack ${args.stackName} ${action} → ${status}`);
+  }
+  console.log(`${action}: ${args.stackName} (${status}) [${url}]`);
+  return { stackName: args.stackName, status, action };
+}
+
+/**
+ * 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,
+  signal?: AbortSignal,
+  http: AwsHttp = defaultHttp,
+): Promise<{ stackName: string; deleted: boolean }> {
+  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("DeleteStack", { StackName: args.stackName }), signal);
+  if (res.status >= 300 && !isStackMissing(res.text)) {
+    throw new Error(`CloudFormation DeleteStack failed (${res.status}): ${cfnErrorMessage(res.text) ?? res.text}`);
+  }
+
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (signal?.aborted) throw new Error("awsDelete aborted");
+    safeHeartbeat({ step: "awsDelete", stack: args.stackName });
+    const d = await http(url, cfnForm("DescribeStacks", { StackName: args.stackName }), signal);
+    if (d.status >= 300 && isStackMissing(d.text)) return { stackName: args.stackName, deleted: true };
+    const status = stackStatus(d.text);
+    if (status === "DELETE_COMPLETE") return { stackName: args.stackName, deleted: true };
+    if (status === "DELETE_FAILED") throw new Error(`CloudFormation stack ${args.stackName} delete → DELETE_FAILED`);
+    await sleep(intervalMs, signal);
+  }
+  throw new Error(`CloudFormation stack ${args.stackName} delete did not complete within ${timeoutMs}ms`);
+}