@intentius/chant-lexicon-aws 0.49.0 → 0.51.0

package/dist/rules/waw067.ts

@@ -0,0 +1,114 @@
+/**
+ * WAW067: Single-AZ NAT Gateway Serves Multi-AZ Private Subnets
+ *
+ * Cross-resource join across four resource kinds: a NAT gateway lives in one
+ * subnet, which lives in one Availability Zone; a route table's default
+ * route names the NAT gateway it forwards to; a subnet is pinned to a route
+ * table by an `AWS::EC2::SubnetRouteTableAssociation`. Follow that chain and
+ * a common reliability gap falls out — private subnets in two or more AZs
+ * all defaulting to the *same* NAT gateway. CloudFormation has no opinion on
+ * this; it deploys cleanly. But a NAT gateway lives entirely inside one AZ,
+ * so if that AZ has an outage, every subnet depending on it loses egress —
+ * including the subnets in AZs that were otherwise healthy. The
+ * Well-Architected fix is one NAT gateway per AZ, each serving only its own
+ * AZ's subnets.
+ *
+ * Only fires when the Availability Zones involved are literal strings —
+ * an `Fn::GetAZs`/`Fn::Select`-derived AZ can't be compared statically, so a
+ * subnet without a literal `AvailabilityZone` is silently excluded rather
+ * than guessed at.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseCFTemplate, findResourceRefs, type CFTemplate } from "./cf-refs";
+
+export function checkNatGatewaySingleAz(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [_lexicon, output] of ctx.outputs) {
+    const template: CFTemplate | null = parseCFTemplate(output);
+    if (!template?.Resources) continue;
+    const resources = template.Resources;
+
+    // NAT gateway id -> its own subnet's literal AZ.
+    const natGatewayAz = new Map<string, string>();
+    for (const [logicalId, resource] of Object.entries(resources)) {
+      if (resource.Type !== "AWS::EC2::NatGateway") continue;
+      const subnetRefs = findResourceRefs(resource.Properties?.SubnetId);
+      if (subnetRefs.size !== 1) continue;
+      const [subnetId] = subnetRefs;
+      const az = resources[subnetId]?.Properties?.AvailabilityZone;
+      if (typeof az === "string") natGatewayAz.set(logicalId, az);
+    }
+    if (natGatewayAz.size === 0) continue;
+
+    // route table id -> the NAT gateway its default route forwards to.
+    const routeTableNatTarget = new Map<string, string>();
+    for (const resource of Object.values(resources)) {
+      if (resource.Type !== "AWS::EC2::Route") continue;
+      const props = resource.Properties ?? {};
+      if (props.DestinationCidrBlock !== "0.0.0.0/0") continue;
+      const natRefs = findResourceRefs(props.NatGatewayId);
+      if (natRefs.size !== 1) continue;
+      const [natId] = natRefs;
+      if (!natGatewayAz.has(natId)) continue;
+      for (const rtId of findResourceRefs(props.RouteTableId)) {
+        routeTableNatTarget.set(rtId, natId);
+      }
+    }
+
+    // subnet id -> route table id, from explicit associations only.
+    const subnetRouteTable = new Map<string, string>();
+    for (const resource of Object.values(resources)) {
+      if (resource.Type !== "AWS::EC2::SubnetRouteTableAssociation") continue;
+      const props = resource.Properties ?? {};
+      const subnetRefs = findResourceRefs(props.SubnetId);
+      const rtRefs = findResourceRefs(props.RouteTableId);
+      if (subnetRefs.size !== 1 || rtRefs.size !== 1) continue;
+      const [subnetId] = subnetRefs;
+      const [rtId] = rtRefs;
+      subnetRouteTable.set(subnetId, rtId);
+    }
+
+    // NAT gateway id -> the set of subnets that default-route through it.
+    const servedSubnets = new Map<string, Set<string>>();
+    for (const [subnetId, rtId] of subnetRouteTable) {
+      const natId = routeTableNatTarget.get(rtId);
+      if (!natId) continue;
+      let set = servedSubnets.get(natId);
+      if (!set) {
+        set = new Set();
+        servedSubnets.set(natId, set);
+      }
+      set.add(subnetId);
+    }
+
+    for (const [natId, subnetIds] of servedSubnets) {
+      const azs = new Set<string>();
+      for (const subnetId of subnetIds) {
+        const az = resources[subnetId]?.Properties?.AvailabilityZone;
+        if (typeof az === "string") azs.add(az);
+      }
+      if (azs.size > 1) {
+        diagnostics.push({
+          checkId: "WAW067",
+          severity: "warning",
+          message: `NAT Gateway "${natId}" (in ${natGatewayAz.get(natId)}) is the default-route egress for private subnets across ${azs.size} Availability Zones (${[...azs].sort().join(", ")}) — a single-AZ NAT gateway is a single point of failure for cross-AZ egress; add one NAT gateway per AZ`,
+          entity: natId,
+          lexicon: "aws",
+        });
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+export const waw067: PostSynthCheck = {
+  id: "WAW067",
+  description: "A single-AZ NAT gateway serves private subnets across multiple Availability Zones — single point of failure for cross-AZ egress",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkNatGatewaySingleAz(ctx);
+  },
+};

package/dist/rules/waw068.ts

@@ -0,0 +1,78 @@
+/**
+ * WAW068: VPN Gateway Has A Single VPN Connection
+ *
+ * An `AWS::EC2::VPNConnection` always gets two tunnels from AWS, but that
+ * redundancy only covers the tunnel pair inside one connection — it does
+ * nothing if the connection's Customer Gateway, on-prem device, or the
+ * single site it terminates at goes down. The reliability boundary that
+ * matters is the connection itself: a `AWS::EC2::VPNGateway` (or a Transit
+ * Gateway used for VPN attachment) with only one `VPNConnection` attached
+ * has no fallback path for hybrid connectivity if that connection's
+ * Customer Gateway or on-prem side fails.
+ *
+ * Cross-resource join: group every declared `VPNConnection` by the gateway
+ * (`VpnGatewayId` or `TransitGatewayId`) it attaches to, and flag any
+ * gateway left with exactly one.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseCFTemplate, findResourceRefs, type CFTemplate } from "./cf-refs";
+
+export function checkVpnGatewayRedundancy(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [_lexicon, output] of ctx.outputs) {
+    const template: CFTemplate | null = parseCFTemplate(output);
+    if (!template?.Resources) continue;
+    const resources = template.Resources;
+
+    // gateway logical id -> the VPNConnection logical ids attached to it.
+    const connectionsByGateway = new Map<string, string[]>();
+
+    for (const [logicalId, resource] of Object.entries(resources)) {
+      if (resource.Type !== "AWS::EC2::VPNConnection") continue;
+      const props = resource.Properties ?? {};
+
+      const gatewayProp = props.VpnGatewayId !== undefined ? props.VpnGatewayId : props.TransitGatewayId;
+      if (gatewayProp === undefined) continue; // no declared gateway target — can't group, stay quiet
+
+      const gwRefs = findResourceRefs(gatewayProp);
+      if (gwRefs.size !== 1) continue;
+      const [gwId] = gwRefs;
+
+      const gw = resources[gwId];
+      if (!gw || (gw.Type !== "AWS::EC2::VPNGateway" && gw.Type !== "AWS::EC2::TransitGateway")) continue;
+
+      let list = connectionsByGateway.get(gwId);
+      if (!list) {
+        list = [];
+        connectionsByGateway.set(gwId, list);
+      }
+      list.push(logicalId);
+    }
+
+    for (const [gwId, connectionIds] of connectionsByGateway) {
+      if (connectionIds.length !== 1) continue;
+
+      const kind = resources[gwId].Type === "AWS::EC2::VPNGateway" ? "VPN Gateway" : "Transit Gateway";
+      diagnostics.push({
+        checkId: "WAW068",
+        severity: "warning",
+        message: `${kind} "${gwId}" has only one VPN connection ("${connectionIds[0]}") attached — no redundant path if this connection, its tunnels, or its Customer Gateway fail; attach a second VPNConnection (ideally to a separate Customer Gateway) for hybrid-connectivity redundancy`,
+        entity: gwId,
+        lexicon: "aws",
+      });
+    }
+  }
+
+  return diagnostics;
+}
+
+export const waw068: PostSynthCheck = {
+  id: "WAW068",
+  description: "VPN Gateway or Transit Gateway has only one attached VPN Connection — no redundant path for hybrid connectivity",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkVpnGatewayRedundancy(ctx);
+  },
+};

package/dist/spec/parse.d.ts

@@ -36,6 +36,13 @@ export interface ParsedResource {
     writeOnly: string[];
     primaryIdentifier: string[];
     deprecatedProperties: string[];
+    /**
+     * The subset of `deprecatedProperties` that no upstream declaration backs.
+     * These names come from {@link DEPRECATION_RE} matching the property
+     * description, so they are an inference rather than a reading. Kept apart so
+     * a consumer can tell the two apart and calibrate what it says (#1701).
+     */
+    inferredDeprecations: string[];
     conditionalCreateOnly: string[];
     replacementStrategy?: "delete_then_create" | "create_then_delete";
     tagging?: {

package/dist/spec/parse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/spec/parse.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAGL,kBAAkB,IAAI,sBAAsB,EAE5C,KAAK,mBAAmB,EAIzB,MAAM,sCAAsC,CAAC;AAG9C,YAAY,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAWhF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,EAAE,mBAAmB,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,cAAc,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,mBAAmB,CAAC,EAAE,oBAAoB,GAAG,oBAAoB,CAAC;IAClE,OAAO,CAAC,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,OAAO,CAAC;QAAC,YAAY,EAAE,OAAO,CAAA;KAAE,CAAC;CAC9E;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,cAAc,CAAC;IACzB,aAAa,EAAE,kBAAkB,EAAE,CAAC;IACpC,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,iBAAiB,CA6IvE;AAiBD,eAAO,MAAM,kBAAkB,+BAAyB,CAAC;AAMzD;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGvD"}
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/spec/parse.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAGL,kBAAkB,IAAI,sBAAsB,EAE5C,KAAK,mBAAmB,EAIzB,MAAM,sCAAsC,CAAC;AAG9C,YAAY,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAkBhF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,EAAE,mBAAmB,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,cAAc,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B;;;;;OAKG;IACH,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,mBAAmB,CAAC,EAAE,oBAAoB,GAAG,oBAAoB,CAAC;IAClE,OAAO,CAAC,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,OAAO,CAAC;QAAC,YAAY,EAAE,OAAO,CAAA;KAAE,CAAC;CAC9E;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,cAAc,CAAC;IACzB,aAAa,EAAE,kBAAkB,EAAE,CAAC;IACpC,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,iBAAiB,CAmJvE;AAiBD,eAAO,MAAM,kBAAkB,+BAAyB,CAAC;AAMzD;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGvD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-aws",
-  "version": "0.49.0",
+  "version": "0.51.0",
   "description": "AWS CloudFormation lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -80,7 +80,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.49.0",
+    "@intentius/chant": "^0.51.0",
     "typescript": "^5.9.3"
   }
 }

package/src/codegen/fallback.ts

@@ -27,6 +27,7 @@ function fallbackLogGroup(): SchemaParseResult {
       writeOnly: [],
       primaryIdentifier: [],
       deprecatedProperties: [],
+      inferredDeprecations: [],
       conditionalCreateOnly: [],
     },
     propertyTypes: [],

package/src/codegen/generate-lexicon.ts

@@ -26,6 +26,11 @@ export interface LexiconEntry {
   writeOnly?: string[];
   primaryIdentifier?: string[];
   deprecatedProperties?: string[];
+  /**
+   * Subset of `deprecatedProperties` that only a regex over the property
+   * description supports; the rest is declared by the Registry schema (#1701).
+   */
+  inferredDeprecations?: string[];
   conditionalCreateOnly?: string[];
   replacementStrategy?: "delete_then_create" | "create_then_delete";
   tagging?: { taggable: boolean; tagOnCreate: boolean; tagUpdatable: boolean };
@@ -72,6 +77,7 @@ export function generateLexiconJSON(
         ...(r.resource.writeOnly.length > 0 && { writeOnly: r.resource.writeOnly }),
         ...(r.resource.primaryIdentifier.length > 0 && { primaryIdentifier: r.resource.primaryIdentifier }),
         ...(r.resource.deprecatedProperties?.length && { deprecatedProperties: r.resource.deprecatedProperties }),
+        ...(r.resource.inferredDeprecations?.length && { inferredDeprecations: r.resource.inferredDeprecations }),
         ...(r.resource.conditionalCreateOnly?.length && { conditionalCreateOnly: r.resource.conditionalCreateOnly }),
         ...(r.resource.replacementStrategy && { replacementStrategy: r.resource.replacementStrategy }),
         ...(r.resource.tagging && { tagging: r.resource.tagging }),

package/src/codegen/sam.ts

@@ -59,6 +59,7 @@ function samFunction(): SchemaParseResult {
       writeOnly: [],
       primaryIdentifier: [],
       deprecatedProperties: [],
+      inferredDeprecations: [],
       conditionalCreateOnly: [],
     },
     propertyTypes: [
@@ -147,6 +148,7 @@ function samApi(): SchemaParseResult {
       writeOnly: [],
       primaryIdentifier: [],
       deprecatedProperties: [],
+      inferredDeprecations: [],
       conditionalCreateOnly: [],
     },
     propertyTypes: [
@@ -200,6 +202,7 @@ function samHttpApi(): SchemaParseResult {
       writeOnly: [],
       primaryIdentifier: [],
       deprecatedProperties: [],
+      inferredDeprecations: [],
       conditionalCreateOnly: [],
     },
     propertyTypes: [
@@ -236,6 +239,7 @@ function samSimpleTable(): SchemaParseResult {
       writeOnly: [],
       primaryIdentifier: [],
       deprecatedProperties: [],
+      inferredDeprecations: [],
       conditionalCreateOnly: [],
     },
     propertyTypes: [
@@ -273,6 +277,7 @@ function samLayerVersion(): SchemaParseResult {
       writeOnly: [],
       primaryIdentifier: [],
       deprecatedProperties: [],
+      inferredDeprecations: [],
       conditionalCreateOnly: [],
     },
     propertyTypes: [],
@@ -306,6 +311,7 @@ function samStateMachine(): SchemaParseResult {
       writeOnly: [],
       primaryIdentifier: [],
       deprecatedProperties: [],
+      inferredDeprecations: [],
       conditionalCreateOnly: [],
     },
     propertyTypes: [
@@ -339,6 +345,7 @@ function samApplication(): SchemaParseResult {
       writeOnly: [],
       primaryIdentifier: [],
       deprecatedProperties: [],
+      inferredDeprecations: [],
       conditionalCreateOnly: [],
     },
     propertyTypes: [],
@@ -360,6 +367,7 @@ function samConnector(): SchemaParseResult {
       writeOnly: [],
       primaryIdentifier: [],
       deprecatedProperties: [],
+      inferredDeprecations: [],
       conditionalCreateOnly: [],
     },
     propertyTypes: [],
@@ -397,6 +405,7 @@ function samGraphQLApi(): SchemaParseResult {
       writeOnly: [],
       primaryIdentifier: [],
       deprecatedProperties: [],
+      inferredDeprecations: [],
       conditionalCreateOnly: [],
     },
     propertyTypes: [],

package/src/components/host-delivery.ts

@@ -73,9 +73,10 @@ function resolveTargets(
  * Deploy a revision to a host (fleet) via AWS CodeDeploy: create the
  * deployment, then wait for a terminal status. Rollback re-invokes
  * `stopAndRollback` against the deployment id this step created (captured in
- * a closure-scoped map keyed by application/deploymentGroup, since the
- * driver's saga rollback calls `rollback(ctx, sameInput)` rather than passing
- * `run`'s output) — riding CodeDeploy's own native automatic rollback to the
+ * a closure-scoped map keyed by application/deploymentGroup; the driver now
+ * also passes `run`'s output as `rollback`'s optional third arg (#1944), but
+ * this capability's input-derived key needs neither channel to resolve
+ * identity) — riding CodeDeploy's own native automatic rollback to the
  * last known-good revision rather than a chant-scripted compensation, the
  * "auto" rollback style the Neo4j pilot's docs comment contrasts with the
  * ALB/ECS pilot's component-declared one.

package/src/disruption.test.ts

@@ -0,0 +1,198 @@
+import { describe, test, expect } from "vitest";
+import { awsDisruption, classifyAwsChange, type DisruptionSpec } from "./disruption";
+import type { DisruptionQuery } from "@intentius/chant/lexicon";
+
+const specs = new Map<string, DisruptionSpec>([
+  [
+    "AWS::EC2::Instance",
+    {
+      resourceType: "AWS::EC2::Instance",
+      kind: "resource",
+      attrs: { InstanceId: "InstanceId", PublicIp: "PublicIp" },
+      createOnly: ["ImageId", "SubnetId", "KeyName"],
+      conditionalCreateOnly: ["InstanceType"],
+    },
+  ],
+  [
+    "AWS::RDS::DBInstance",
+    {
+      resourceType: "AWS::RDS::DBInstance",
+      kind: "resource",
+      createOnly: ["DBInstanceIdentifier"],
+      replacementStrategy: "delete_then_create",
+    },
+  ],
+  [
+    "AWS::S3::BucketPolicy",
+    { resourceType: "AWS::S3::BucketPolicy", kind: "resource" },
+  ],
+  [
+    "AWS::EC2::Instance.BlockDeviceMapping",
+    { resourceType: "AWS::EC2::Instance.BlockDeviceMapping", kind: "property" },
+  ],
+]);
+
+function query(type: string | undefined, paths: string[]): DisruptionQuery {
+  return {
+    name: "thing",
+    ...(type ? { type } : {}),
+    deltas: paths.map((path) => ({ path, oldValue: "a", newValue: "b" })),
+  };
+}
+
+describe("classifyAwsChange (#1665)", () => {
+  test("a create-only property is a replace, and says which one", () => {
+    const v = classifyAwsChange(query("AWS::EC2::Instance", ["attributes.ImageId"]), specs);
+    expect(v.disruption).toBe("replace");
+    expect(v.because).toEqual(["attributes.ImageId"]);
+    expect(v.detail).toContain("ImageId is create-only");
+  });
+
+  // `delete_then_create` is the destructive form: the old resource is gone
+  // before the new one exists.
+  test("delete_then_create replacement is a destroy", () => {
+    const v = classifyAwsChange(
+      query("AWS::RDS::DBInstance", ["attributes.DBInstanceIdentifier"]),
+      specs,
+    );
+    expect(v.disruption).toBe("destroy");
+    expect(v.detail).toContain("deleting first");
+  });
+
+  test("a mutable property is in-place", () => {
+    const v = classifyAwsChange(query("AWS::EC2::Instance", ["attributes.Monitoring"]), specs);
+    expect(v.disruption).toBe("in-place");
+    expect(v.detail).toContain("no create-only property of AWS::EC2::Instance changed");
+  });
+
+  test("replacement wins over an in-place property changing alongside it", () => {
+    const v = classifyAwsChange(
+      query("AWS::EC2::Instance", ["attributes.Monitoring", "attributes.SubnetId"]),
+      specs,
+    );
+    expect(v.disruption).toBe("replace");
+    expect(v.because).toEqual(["attributes.SubnetId"]);
+  });
+
+  // The schema says "depends on the value", which is not an answer. Reporting
+  // that as in-place would be the exact failure the `unknown` level exists for.
+  test("a conditionally create-only property is unknown, not in-place", () => {
+    const v = classifyAwsChange(
+      query("AWS::EC2::Instance", ["attributes.InstanceType"]),
+      specs,
+    );
+    expect(v.disruption).toBe("unknown");
+    expect(v.because).toEqual(["attributes.InstanceType"]);
+    expect(v.detail).toContain("conditionally create-only");
+  });
+
+  test("a type with no schema on record is unknown", () => {
+    const v = classifyAwsChange(query("AWS::Nowhere::Thing", ["attributes.Anything"]), specs);
+    expect(v.disruption).toBe("unknown");
+    expect(v.detail).toContain("no CloudFormation registry schema on record");
+  });
+
+  test("a property-type entry is not a resource, so it is unknown", () => {
+    const v = classifyAwsChange(
+      query("AWS::EC2::Instance.BlockDeviceMapping", ["attributes.Ebs"]),
+      specs,
+    );
+    expect(v.disruption).toBe("unknown");
+  });
+
+  test("an entry with no observed type is unknown", () => {
+    const v = classifyAwsChange(query(undefined, ["attributes.ImageId"]), specs);
+    expect(v.disruption).toBe("unknown");
+    expect(v.detail).toContain("no resource type");
+  });
+
+  // A read-only attribute changing is a symptom of something else, never the
+  // cause of a replacement — a re-created instance reports a new PublicIp.
+  test("read-only attributes are not evidence of anything", () => {
+    const v = classifyAwsChange(query("AWS::EC2::Instance", ["attributes.PublicIp"]), specs);
+    expect(v.disruption).toBe("in-place");
+    expect(v.detail).toContain("only status, identity, or read-only attributes changed");
+  });
+
+  test("core's own observation fields are not properties", () => {
+    const v = classifyAwsChange(
+      query("AWS::EC2::Instance", ["status", "lastUpdated", "physicalId"]),
+      specs,
+    );
+    expect(v.disruption).toBe("in-place");
+    expect(v.detail).toContain("only status, identity, or read-only attributes changed");
+  });
+
+  test("a type whose schema declares no create-only property is in-place", () => {
+    const v = classifyAwsChange(query("AWS::S3::BucketPolicy", ["attributes.PolicyDocument"]), specs);
+    expect(v.disruption).toBe("in-place");
+  });
+
+  // createOnlyProperties can point at a nested pointer path (`Config/Engine`);
+  // the observation reports the top-level property.
+  test("a nested create-only pointer matches on its head segment", () => {
+    const nested = new Map<string, DisruptionSpec>([
+      [
+        "AWS::Fake::Thing",
+        { resourceType: "AWS::Fake::Thing", kind: "resource", createOnly: ["Config/Engine"] },
+      ],
+    ]);
+    const v = classifyAwsChange(query("AWS::Fake::Thing", ["attributes.Config"]), nested);
+    expect(v.disruption).toBe("replace");
+  });
+
+  test("duplicate hits name the property once but keep every path", () => {
+    const v = classifyAwsChange(
+      query("AWS::EC2::Instance", ["attributes.ImageId", "attributes.KeyName"]),
+      specs,
+    );
+    expect(v.because).toEqual(["attributes.ImageId", "attributes.KeyName"]);
+    expect(v.detail).toContain("ImageId, KeyName");
+  });
+});
+
+// The plugin method against the registry the codegen actually compiled — the
+// evidence that the verdicts come from CloudFormation's own schema and not
+// from a table in this file.
+describe("awsDisruption over the generated registry", () => {
+  const change = (name: string, type: string, paths: string[]): DisruptionQuery => ({
+    name,
+    type,
+    deltas: paths.map((path) => ({ path, oldValue: "a", newValue: "b" })),
+  });
+
+  test("classifies a whole batch off the compiled schema", () => {
+    const out = awsDisruption({
+      environment: "prod",
+      changes: [
+        // createOnlyProperties
+        change("web", "AWS::EC2::Instance", ["attributes.ImageId"]),
+        // conditionalCreateOnlyProperties — the schema says "it depends"
+        change("sized", "AWS::EC2::Instance", ["attributes.InstanceType"]),
+        // not create-only for this type
+        change("mon", "AWS::EC2::Instance", ["attributes.Monitoring"]),
+        // no schema on record
+        change("nope", "AWS::Nowhere::Thing", ["attributes.Whatever"]),
+      ],
+    });
+
+    expect(out.web.disruption).toBe("replace");
+    expect(out.web.because).toEqual(["attributes.ImageId"]);
+    expect(out.sized.disruption).toBe("unknown");
+    expect(out.sized.detail).toContain("conditionally create-only");
+    expect(out.mon.disruption).toBe("in-place");
+    expect(out.nope.disruption).toBe("unknown");
+  });
+
+  test("every query gets a verdict, so nothing silently drops out of the plan", () => {
+    const changes = [
+      change("a", "AWS::S3::Bucket", ["attributes.BucketName"]),
+      change("b", "AWS::IAM::Role", ["attributes.RoleName"]),
+    ];
+    const out = awsDisruption({ environment: "prod", changes });
+    expect(Object.keys(out).sort()).toEqual(["a", "b"]);
+    // BucketName and RoleName are both create-only in the Registry schema.
+    expect(out.a.disruption).toBe("replace");
+    expect(out.b.disruption).toBe("replace");
+  });
+});