@intentius/chant-lexicon-aws 0.46.0 → 0.49.0

package/src/effect-receipt-row.test.ts

@@ -0,0 +1,164 @@
+import { describe, it, expect } from "vitest";
+import {
+  EffectReceipt,
+  receiptParameterName,
+  AWS_EFFECT_RECEIPT_ENTITY_TYPE,
+  EFFECT_RECEIPTS_METADATA_KEY,
+  RECEIPT_UNRESOLVED_VALUE_NOTE,
+} from "./effect-receipt-row";
+import { awsSerializer } from "./serializer";
+import { AWS_TAG_OWNERSHIP_KEYS } from "./ownership";
+import {
+  EXISTENCE_EXPECTATION,
+  isEffectReceipt,
+  receiptExpectation,
+  EFFECT_RECEIPT_MARKER,
+} from "@intentius/chant/effect-receipt";
+import { receiptCheckInput } from "@intentius/chant/op/receipt-store";
+import { coreReceiptChecks, RECEIPT_PLAIN_STORE_CHECK_ID } from "@intentius/chant/lint/receipt-checks";
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+
+/** A minimal deploy-time reference, for the placeholder-value case. */
+const someRef = { [INTRINSIC_MARKER]: true as const, toJSON: () => ({ Ref: "other" }) };
+
+function serializeReceipts(
+  receipts: Map<string, Declarable>,
+  ownership?: { stack: string; env?: string },
+): { Metadata?: Record<string, unknown>; Resources: Record<string, unknown> } {
+  const out = awsSerializer.serialize(new Map(), [], {
+    ...(ownership ? { ownership } : {}),
+    receipts,
+  });
+  return JSON.parse(typeof out === "string" ? out : out.primary);
+}
+
+function metadataRows(template: { Metadata?: Record<string, unknown> }) {
+  return template.Metadata?.[EFFECT_RECEIPTS_METADATA_KEY] as Record<
+    string,
+    { Type: string; Properties: Record<string, unknown> }
+  >;
+}
+
+describe("EffectReceipt (aws materialization row)", () => {
+  it("declares under the aws lexicon with the real resource kind, carrying the marker", () => {
+    const r = EffectReceipt("seeded", { effect: "db-seed", flavor: "existence" });
+    expect(r.lexicon).toBe("aws");
+    expect(r.entityType).toBe(AWS_EFFECT_RECEIPT_ENTITY_TYPE);
+    expect(isEffectReceipt(r)).toBe(true);
+    expect(r.props.Type).toBe("String");
+  });
+
+  it("is accepted by the effect() step's receiptCheckInput, expectation stamped when static", () => {
+    const r = EffectReceipt("seeded", { effect: "db-seed", flavor: "hash", inputs: { v: 1 } });
+    const input = receiptCheckInput(r);
+    expect(input.receipt.effect).toBe("db-seed");
+    expect(input.expectation).toBe(receiptExpectation(r));
+  });
+
+  it("validates the effect as a path segment at declaration", () => {
+    expect(() => EffectReceipt("bad", { effect: "a/b", flavor: "existence" })).toThrow(/path segment/);
+    expect(() => EffectReceipt("bad", { effect: "", flavor: "existence" })).toThrow(/non-empty/);
+  });
+});
+
+describe("receiptParameterName", () => {
+  it("derives /chant-receipts/<stack>/<env>/<effect>", () => {
+    expect(receiptParameterName("demo", "dev", "db-seed")).toBe("/chant-receipts/demo/dev/db-seed");
+  });
+
+  it("refuses a segment that would deepen the hierarchy", () => {
+    expect(() => receiptParameterName("a/b", "dev", "seed")).toThrow(/stack/);
+    expect(() => receiptParameterName("demo", "", "seed")).toThrow(/env/);
+  });
+});
+
+describe("awsSerializer receipt rows", () => {
+  const ownership = { stack: "demo", env: "dev" };
+
+  it("renders each receipt as a plain-String SSM parameter row at the derived path, ownership-tagged", () => {
+    const seeded = EffectReceipt("seeded", { effect: "db-seed", flavor: "hash", inputs: { v: 1 } });
+    const template = serializeReceipts(new Map([["seeded", seeded]]), ownership);
+    const row = metadataRows(template).seeded;
+    expect(row.Type).toBe("AWS::SSM::Parameter");
+    expect(row.Properties.Name).toBe("/chant-receipts/demo/dev/db-seed");
+    expect(row.Properties.Type).toBe("String");
+    expect(row.Properties.Value).toBe(receiptExpectation(seeded));
+    expect(row.Properties.Tags).toContainEqual({ Key: AWS_TAG_OWNERSHIP_KEYS.managedBy, Value: "chant" });
+    expect(row.Properties.Tags).toContainEqual({ Key: AWS_TAG_OWNERSHIP_KEYS.stack, Value: "demo" });
+    expect(row.Properties.Tags).toContainEqual({ Key: AWS_TAG_OWNERSHIP_KEYS.env, Value: "dev" });
+  });
+
+  it("keeps the receipt out of Resources — the section appliers write from", () => {
+    const seeded = EffectReceipt("seeded", { effect: "db-seed", flavor: "existence" });
+    const template = serializeReceipts(new Map([["seeded", seeded]]), ownership);
+    expect(Object.keys(template.Resources)).toHaveLength(0);
+    expect(metadataRows(template).seeded).toBeDefined();
+  });
+
+  it("renders the existence expectation for an existence receipt", () => {
+    const r = EffectReceipt("booted", { effect: "bootstrap", flavor: "existence" });
+    const template = serializeReceipts(new Map([["booted", r]]), ownership);
+    expect(metadataRows(template).booted.Properties.Value).toBe(EXISTENCE_EXPECTATION);
+  });
+
+  it("renders the placeholder note, never a placeholder digest, for reference inputs", () => {
+    const r = EffectReceipt("wired", { effect: "wire-up", flavor: "hash", inputs: { target: someRef } });
+    const template = serializeReceipts(new Map([["wired", r]]), ownership);
+    expect(metadataRows(template).wired.Properties.Value).toBe(RECEIPT_UNRESOLVED_VALUE_NOTE);
+  });
+
+  it("errors when no ownership marker resolves", () => {
+    const r = EffectReceipt("seeded", { effect: "db-seed", flavor: "existence" });
+    expect(() => serializeReceipts(new Map([["seeded", r]]))).toThrow(/ownership/);
+  });
+
+  it("errors when ownership resolves no env — the segment is explicit, never guessed", () => {
+    const r = EffectReceipt("seeded", { effect: "db-seed", flavor: "existence" });
+    expect(() => serializeReceipts(new Map([["seeded", r]]), { stack: "demo" })).toThrow(/env/);
+  });
+
+  it("emits no receipt block when the context carries no receipts", () => {
+    const out = awsSerializer.serialize(new Map(), [], { ownership });
+    const template = JSON.parse(typeof out === "string" ? out : out.primary);
+    expect(template.Metadata?.[EFFECT_RECEIPTS_METADATA_KEY]).toBeUndefined();
+  });
+});
+
+describe("#1833's plain-store guard over the aws row", () => {
+  const check = coreReceiptChecks().find((c) => c.id === RECEIPT_PLAIN_STORE_CHECK_ID)!;
+
+  function runCheck(entities: Map<string, Declarable>) {
+    const ctx: PostSynthContext = {
+      outputs: new Map(),
+      entities,
+      buildResult: { outputs: new Map(), entities, warnings: [], errors: [], sourceFileCount: 0 },
+    };
+    return check.check(ctx);
+  }
+
+  it("passes the factory's row — SSM plain String", () => {
+    const r = EffectReceipt("seeded", { effect: "db-seed", flavor: "existence" });
+    expect(runCheck(new Map([["seeded", r]]))).toEqual([]);
+  });
+
+  it("fails a SecureString fixture", () => {
+    const secure = {
+      [DECLARABLE_MARKER]: true as const,
+      [EFFECT_RECEIPT_MARKER]: true as const,
+      lexicon: "aws",
+      entityType: "AWS::SSM::Parameter",
+      name: "sneaky",
+      effect: "db-seed",
+      flavor: "existence" as const,
+      inputs: {},
+      props: { Type: "SecureString" },
+    };
+    const diagnostics = runCheck(new Map([["sneaky", secure as unknown as Declarable]]));
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].checkId).toBe(RECEIPT_PLAIN_STORE_CHECK_ID);
+    expect(diagnostics[0].severity).toBe("error");
+    expect(diagnostics[0].message).toMatch(/SecureString/);
+  });
+});

package/src/effect-receipt-row.ts

@@ -0,0 +1,147 @@
+/**
+ * The aws effect-receipt materialization row (#1835, epic #1703): an effect
+ * receipt stored as an `AWS::SSM::Parameter`, plain `String`, at
+ * `/chant-receipts/<stack>/<env>/<effect>`.
+ *
+ * Core's `EffectReceipt` factory (#1831) declares a receipt under the `chant`
+ * pseudo-lexicon, which no serializer claims — the designed shape until a
+ * lexicon materializes it. This module is that materialization for aws: the
+ * {@link EffectReceipt} factory here produces the same declaration shape but
+ * under `lexicon: "aws"`, so the build partitions it to the aws serializer,
+ * #1832's write-exclusion seam withholds it from the apply-bound entity set,
+ * and the serializer renders it for visibility through
+ * `SerializeContext.receipts` (see ./serializer.ts).
+ *
+ * Path identity (epic decision 4): the parameter name derives from the SAME
+ * ownership-block fields that stamp markers — `ownership.stack` and an
+ * explicit `ownership.env` — plus the receipt's `effect`. One derivation,
+ * {@link receiptParameterName}, shared by the serializer (the rendered row),
+ * the receipt store (../receipt-store.ts — what `receiptRead`/`receiptWrite`
+ * actually touch), and the observation leg (plan's live read). No env, no
+ * path: the callers error rather than guessing a segment.
+ *
+ * Plain store (epic decision 7, #1833's COR023): the parameter type is pinned
+ * to `String` at the source — the factory does not take a type, and the
+ * declared `props.Type` is the literal `"String"`. A receipt value is a
+ * witness (an existence marker or a `sha256:` digest), never a secret; a
+ * `SecureString` invites masking and rotation semantics that defeat the
+ * observe-and-compare loop, and the lint guard fails it.
+ */
+
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+import {
+  EffectReceipt as CoreEffectReceipt,
+  EFFECT_RECEIPT_MARKER,
+  type EffectReceiptFlavor,
+  type EffectReceiptOptions,
+} from "@intentius/chant/effect-receipt";
+
+/** The entityType of the aws materialization row — the real resource kind the
+ * receipt is stored as, which is what lint's plain-store guard checks. */
+export const AWS_EFFECT_RECEIPT_ENTITY_TYPE = "AWS::SSM::Parameter";
+
+/** Template-level `Metadata` key the serializer renders receipt rows under.
+ * Beside `chant:ownership` (./ownership.ts) and like it deliberately outside
+ * `Resources` — the applier writes from `Resources`, and a receipt must never
+ * enter the apply-bound document (#1832; the `effect()` step is the sole
+ * writer, epic decision 3). */
+export const EFFECT_RECEIPTS_METADATA_KEY = "chant:effect-receipts";
+
+/** Every receipt parameter lives under this prefix, so read-only IAM can be
+ * scoped to `arn:…:parameter/chant-receipts/*` and nothing else. */
+export const RECEIPT_PATH_PREFIX = "/chant-receipts";
+
+/**
+ * The rendered `Value` of a hash-flavor receipt that still carries reference
+ * inputs at synthesis. References resolve at plan and at run, never at
+ * synthesis (epic decision 5) — so the row carries this note instead of a
+ * digest hashed over placeholders.
+ */
+export const RECEIPT_UNRESOLVED_VALUE_NOTE =
+  "unresolved at synthesis — reference inputs; the expectation resolves at plan and at run (chant #1703, decision 5)";
+
+/** One path segment of the receipt parameter name. SSM hierarchical names are
+ * `/`-separated `[\w.-]+` segments, and the identity must stay one segment per
+ * field — a `/` inside a stack name would silently deepen the hierarchy. */
+const PATH_SEGMENT = /^[\w.-]+$/;
+
+function checkSegment(field: string, value: string): string {
+  if (!PATH_SEGMENT.test(value)) {
+    throw new Error(
+      `receipt path: ${field} "${value}" is not a valid SSM path segment — ` +
+        `use only letters, digits, ".", "_", "-" (the segment becomes one level of ` +
+        `${RECEIPT_PATH_PREFIX}/<stack>/<env>/<effect>)`,
+    );
+  }
+  return value;
+}
+
+/**
+ * The SSM parameter name of one effect's receipt:
+ * `/chant-receipts/<stack>/<env>/<effect>`, from the resolved ownership
+ * marker fields (epic decision 4). The single source of the path identity —
+ * the serializer's rendered row, the receipt store's reads and writes, and
+ * the observation leg all call this.
+ */
+export function receiptParameterName(stack: string, env: string, effect: string): string {
+  return `${RECEIPT_PATH_PREFIX}/${checkSegment("stack", stack)}/${checkSegment("env", env)}/${checkSegment("effect", effect)}`;
+}
+
+/**
+ * An aws-materialized effect receipt: core's declaration shape (so
+ * `isEffectReceipt`, `effect(...)`, lint, and the plan engine all recognize it
+ * through the marker), under the aws lexicon and the real resource kind, with
+ * the store variant pinned plain.
+ */
+export interface AwsEffectReceiptDeclaration extends Declarable {
+  readonly [EFFECT_RECEIPT_MARKER]: true;
+  readonly lexicon: "aws";
+  readonly entityType: typeof AWS_EFFECT_RECEIPT_ENTITY_TYPE;
+  /** The receipt's own name (the export-level identity of the witness). */
+  readonly name: string;
+  /** The effect this receipt witnesses — the path's final segment. */
+  readonly effect: string;
+  /** How the receipt is compared: mere presence, or a digest of the inputs. */
+  readonly flavor: EffectReceiptFlavor;
+  /** The effect's inputs as recorded at synthesis (references as placeholders). */
+  readonly inputs: Readonly<Record<string, unknown>>;
+  /** The declared parameter variant — pinned `String` at the source, which is
+   * the concrete half of #1833's plain-store guard. */
+  readonly props: { readonly Type: "String" };
+}
+
+/**
+ * Declare an aws-materialized effect receipt. Same signature and semantics as
+ * core's `EffectReceipt` (#1831) — the options are validated and frozen by the
+ * core factory — but the declaration lands in the aws partition, so the aws
+ * serializer renders the `AWS::SSM::Parameter` row and the receipt store
+ * (../receipt-store.ts) is its writer. Pass the returned const straight to the
+ * `effect(...)` op step.
+ */
+export function EffectReceipt(name: string, options: EffectReceiptOptions): AwsEffectReceiptDeclaration {
+  // Fail at declaration, not at serialize: the effect is the path's final
+  // segment, and a name that cannot become a segment has no receipt address.
+  if (typeof options?.effect === "string" && options.effect.length > 0) {
+    checkSegment("effect", options.effect);
+  }
+  const core = CoreEffectReceipt(name, options);
+  const decl: AwsEffectReceiptDeclaration = {
+    [DECLARABLE_MARKER]: true,
+    [EFFECT_RECEIPT_MARKER]: true,
+    lexicon: "aws",
+    entityType: AWS_EFFECT_RECEIPT_ENTITY_TYPE,
+    name: core.name,
+    effect: core.effect,
+    flavor: core.flavor,
+    // The same frozen structure the core factory built — intrinsic inputs stay
+    // live so discovery can stamp logical names onto attr-refs.
+    inputs: core.inputs,
+    props: Object.freeze({ Type: "String" as const }),
+  };
+  // Declared fields immutable, object extensible for discovery's own
+  // symbol-keyed metadata — the same lock the core factory applies.
+  for (const key of Object.keys(decl)) {
+    Object.defineProperty(decl, key, { writable: false, configurable: false });
+  }
+  return decl;
+}

package/src/index.ts

@@ -7,6 +7,21 @@ export type { DefaultTags, TagEntry } from "./default-tags";
 export { templateTransform, isTemplateTransform, TEMPLATE_TRANSFORM_MARKER } from "./template-transform";
 export type { TemplateTransform } from "./template-transform";
 
+// Effect receipts (#1835, epic #1703): the aws materialization row
+// (`AWS::SSM::Parameter`, plain String, path derived from the ownership
+// marker) and the SSM-backed receipt store behind the `effect()` op step.
+export {
+  EffectReceipt,
+  receiptParameterName,
+  AWS_EFFECT_RECEIPT_ENTITY_TYPE,
+  EFFECT_RECEIPTS_METADATA_KEY,
+  RECEIPT_PATH_PREFIX,
+  RECEIPT_UNRESOLVED_VALUE_NOTE,
+} from "./effect-receipt-row";
+export type { AwsEffectReceiptDeclaration } from "./effect-receipt-row";
+export { awsReceiptStore, observeReceiptRows, ssmGetParameter, ssmPutParameter } from "./receipt-store";
+export type { AwsReceiptStoreOptions, ReceiptRowObservation } from "./receipt-store";
+
 // Serializer
 export { awsSerializer } from "./serializer";
 
@@ -122,25 +137,31 @@ export {
   LambdaFunction, LambdaNode, LambdaPython, NodeLambda, PythonLambda,
   LambdaApi,
   LambdaScheduled, ScheduledLambda,
-  LambdaSqs, LambdaEventBridge, LambdaDynamoDB, LambdaS3, LambdaSns,
-  VpcDefault, FargateAlb, AlbShared, FargateService, RdsInstance, RdsPostgres,
+  LambdaSqs, LambdaEventBridge, LambdaDynamoDB, DynamoDBTable, EcrRepository, LambdaS3, LambdaSns,
+  VpcDefault, FargateAlb, AlbShared, FargateService, FARGATE_SERVICE_LIMITS, NlbService, RdsInstance, RdsPostgres,
   EfsWithAccessPoint,
-  Ec2InstanceRole, MinimalVpc, EksCluster,
+  Ec2InstanceRole, Ec2InstanceBundle, MinimalVpc, EksCluster,
   SolrFargateService,
   MicrovmApp, MICROVM_LIMITS,
-  AgentCoreAgent, agentCoreDefaultEndpointArn,
+  AgentCoreAgent, agentCoreDefaultEndpointArn, AGENTCORE_LIMITS,
   OrganizationRoot, GovernanceFoundation, RegionRestriction, OrganizationTrail,
+  StepFunctionsWorkflow,
+  MonitoringStack,
+  BucketDeployment,
 } from "./composites/index";
 export type {
   LambdaFunctionProps, LambdaApiProps, ScheduledLambdaProps,
-  LambdaSqsProps, LambdaEventBridgeProps, LambdaDynamoDBProps, LambdaS3Props, LambdaSnsProps,
-  VpcDefaultProps, FargateAlbProps, AlbSharedProps, FargateServiceProps, RdsInstanceProps, RdsPostgresProps,
+  LambdaSqsProps, LambdaEventBridgeProps, LambdaDynamoDBProps, DynamoDBTableProps, DynamoDBKey, DynamoDBCapacity, DynamoDBGlobalSecondaryIndex, EcrRepositoryProps, EcrLifecycleRule, EcrEncryption, LambdaS3Props, LambdaSnsProps,
+  VpcDefaultProps, FargateAlbProps, AlbSharedProps, FargateServiceProps, NlbServiceProps, RdsInstanceProps, RdsPostgresProps,
   EfsWithAccessPointProps,
-  Ec2InstanceRoleProps, MinimalVpcProps, EksClusterProps,
+  Ec2InstanceRoleProps, Ec2InstanceBundleProps, Ec2InstanceBundleIngressRule, MinimalVpcProps, EksClusterProps,
   SolrFargateServiceProps,
   MicrovmAppProps, MicrovmAppResult, MicrovmAppBuildConnectorProps, MicrovmMemoryMiB,
   AgentCoreAgentProps, AgentCoreAgentResult,
   OrganizationRootProps, GovernanceFoundationProps, RegionRestrictionProps, OrganizationTrailProps,
+  StepFunctionsWorkflowProps,
+  MonitoringStackProps, MonitoringMetricSpec,
+  BucketDeploymentProps, BucketDeploymentResult,
 } from "./composites/index";
 
 // Code generation pipeline

package/src/lint/audit-catalog.ts

@@ -72,4 +72,10 @@ export const awsAuditCatalog: Record<string, RuleMeta> = {
   // so no authority citation (those are reserved for merge-worthy entries).
   WAW059: auditRule("WAW059", "report-only", "guidance", "Wildcard Resource where the declared graph enumerates the touched set", "Tighten Resource from \"*\" to the Fn::GetAtt Arn list of the declared resources the role's consumers touch.", { category: "security" }),
   WAW060: auditRule("WAW060", "report-only", "guidance", "IAM policy attached to no principal", "Attach the policy via Roles/Users/Groups or reference it from a principal's ManagedPolicyArns — unattached it grants nothing.", { category: "security" }),
+
+  // #1140 — error-injection benchmark family (companion to epic #1139): static
+  // catches for the deploy-time/runtime failure class stock CDK can't see pre-synth.
+  WAW061: auditRule("WAW061", "merge-worthy", "guidance", "Subnet CidrBlock not contained in its VPC's CidrBlock", "Fix the subnet's CidrBlock so it falls within the VPC's CidrBlock range.", { category: "correctness" }),
+  WAW062: auditRule("WAW062", "merge-worthy", "guidance", "Duplicate export name or explicit resource name within a template", "Give each duplicated Export/name a distinct literal value.", { category: "correctness" }),
+  WAW063: auditRule("WAW063", "merge-worthy", "guidance", "IAM policy denies an action another attached policy on the same role allows", "Remove or narrow the Deny, or move the Allow off this role — the explicit Deny always wins.", { category: "correctness" }),
 };

package/src/lint/post-synth/cf-refs.ts

@@ -169,6 +169,46 @@ export function isFullTierEnv(env: string | undefined): boolean {
   return env === "prod" || env === "production" || env === "full";
 }
 
+/**
+ * Parse an IPv4 CIDR literal ("10.0.0.0/16") into its numeric base address
+ * and prefix length. Returns null for anything that isn't a plain IPv4 CIDR
+ * (IPv6, malformed octets, out-of-range prefix) — callers treat that as
+ * "can't prove statically" rather than an error.
+ */
+export function parseIpv4Cidr(cidr: string): { base: number; prefix: number } | null {
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})\/(\d{1,2})$/.exec(cidr.trim());
+  if (!m) return null;
+  const octets = m.slice(1, 5).map(Number);
+  if (octets.some((o) => o < 0 || o > 255)) return null;
+  const prefix = Number(m[5]);
+  if (prefix < 0 || prefix > 32) return null;
+  const base = ((octets[0] << 24) | (octets[1] << 16) | (octets[2] << 8) | octets[3]) >>> 0;
+  return { base, prefix };
+}
+
+/** [networkAddress, broadcastAddress] for a parsed IPv4 CIDR block. */
+function ipv4Range(cidr: { base: number; prefix: number }): [number, number] {
+  const maskBits = cidr.prefix === 0 ? 0 : (0xffffffff << (32 - cidr.prefix)) >>> 0;
+  const network = (cidr.base & maskBits) >>> 0;
+  const broadcast = (network | (~maskBits >>> 0)) >>> 0;
+  return [network, broadcast];
+}
+
+/**
+ * Whether `inner` (an IPv4 CIDR literal) falls entirely within `outer`.
+ * Returns null — not false — when either literal isn't a plain, parseable
+ * IPv4 CIDR (e.g. IPv6, or a CloudFormation intrinsic already stringified
+ * elsewhere); a null means "statically unprovable", not "violation".
+ */
+export function ipv4CidrContains(outer: string, inner: string): boolean | null {
+  const outerCidr = parseIpv4Cidr(outer);
+  const innerCidr = parseIpv4Cidr(inner);
+  if (!outerCidr || !innerCidr) return null;
+  const [oStart, oEnd] = ipv4Range(outerCidr);
+  const [iStart, iEnd] = ipv4Range(innerCidr);
+  return iStart >= oStart && iEnd <= oEnd;
+}
+
 /**
  * Check if a port range [fromPort, toPort] contains any of the sensitive ports.
  */

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

@@ -52,6 +52,9 @@ import { waw057 } from "./waw057";
 import { waw058 } from "./waw058";
 import { waw059 } from "./waw059";
 import { waw060 } from "./waw060";
+import { waw061 } from "./waw061";
+import { waw062 } from "./waw062";
+import { waw063 } from "./waw063";
 
 export const postSynthChecks: PostSynthCheck[] = [
   cor020,
@@ -106,4 +109,7 @@ export const postSynthChecks: PostSynthCheck[] = [
   waw058,
   waw059,
   waw060,
+  waw061,
+  waw062,
+  waw063,
 ];

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

@@ -0,0 +1,99 @@
+import { describe, test, expect } from "vitest";
+import { createPostSynthContext } from "@intentius/chant-test-utils";
+import { waw061, checkSubnetCidrContainment } from "./waw061";
+
+function makeCtx(template: object) {
+  return createPostSynthContext({ aws: template });
+}
+
+describe("WAW061: Subnet CIDR Not Contained In VPC CIDR", () => {
+  test("check metadata", () => {
+    expect(waw061.id).toBe("WAW061");
+    expect(waw061.description).toContain("CidrBlock");
+  });
+
+  test("subnet CIDR outside the VPC's CIDR range → error", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MyVpc: { Type: "AWS::EC2::VPC", Properties: { CidrBlock: "10.0.0.0/16" } },
+        MySubnet: {
+          Type: "AWS::EC2::Subnet",
+          Properties: { CidrBlock: "10.1.0.0/24", VpcId: { Ref: "MyVpc" } },
+        },
+      },
+    });
+    const diags = checkSubnetCidrContainment(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WAW061");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].entity).toBe("MySubnet");
+    expect(diags[0].message).toContain("10.1.0.0/24");
+    expect(diags[0].message).toContain("10.0.0.0/16");
+    expect(diags[0].lexicon).toBe("aws");
+  });
+
+  test("subnet wider than its VPC → error", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MyVpc: { Type: "AWS::EC2::VPC", Properties: { CidrBlock: "10.0.1.0/24" } },
+        MySubnet: {
+          Type: "AWS::EC2::Subnet",
+          Properties: { CidrBlock: "10.0.0.0/16", VpcId: { Ref: "MyVpc" } },
+        },
+      },
+    });
+    expect(checkSubnetCidrContainment(ctx)).toHaveLength(1);
+  });
+
+  test("subnet CIDR contained in the VPC's CIDR → no diagnostic", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MyVpc: { Type: "AWS::EC2::VPC", Properties: { CidrBlock: "10.0.0.0/16" } },
+        MySubnet: {
+          Type: "AWS::EC2::Subnet",
+          Properties: { CidrBlock: "10.0.1.0/24", VpcId: { Ref: "MyVpc" } },
+        },
+      },
+    });
+    expect(checkSubnetCidrContainment(ctx)).toHaveLength(0);
+  });
+
+  test("intrinsic CidrBlock → no diagnostic (unprovable)", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MyVpc: { Type: "AWS::EC2::VPC", Properties: { CidrBlock: "10.0.0.0/16" } },
+        MySubnet: {
+          Type: "AWS::EC2::Subnet",
+          Properties: {
+            CidrBlock: { "Fn::Select": [0, { "Fn::Cidr": [{ "Fn::GetAtt": ["MyVpc", "CidrBlock"] }, 4, 8] }] },
+            VpcId: { Ref: "MyVpc" },
+          },
+        },
+      },
+    });
+    expect(checkSubnetCidrContainment(ctx)).toHaveLength(0);
+  });
+
+  test("VpcId not resolvable to a declared VPC (imported) → no diagnostic", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MySubnet: {
+          Type: "AWS::EC2::Subnet",
+          Properties: { CidrBlock: "10.1.0.0/24", VpcId: { "Fn::ImportValue": "shared-vpc-id" } },
+        },
+      },
+    });
+    expect(checkSubnetCidrContainment(ctx)).toHaveLength(0);
+  });
+
+  test("multiple subnets in a VPC, all contained → no diagnostic", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MyVpc: { Type: "AWS::EC2::VPC", Properties: { CidrBlock: "10.0.0.0/16" } },
+        SubnetA: { Type: "AWS::EC2::Subnet", Properties: { CidrBlock: "10.0.0.0/24", VpcId: { Ref: "MyVpc" } } },
+        SubnetB: { Type: "AWS::EC2::Subnet", Properties: { CidrBlock: "10.0.1.0/24", VpcId: { Ref: "MyVpc" } } },
+      },
+    });
+    expect(checkSubnetCidrContainment(ctx)).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,67 @@
+/**
+ * WAW061: Subnet CIDR Not Contained In VPC CIDR
+ *
+ * A subnet's CidrBlock must fall entirely inside its VPC's CidrBlock.
+ * Stock CDK does not check this — CloudFormation accepts the template and
+ * only fails the `AWS::EC2::Subnet` resource at deploy time
+ * ("The CIDR ... is invalid" / "does not fall within the CIDR range of the
+ * VPC"), after the rest of the stack may have already started rolling out.
+ * This is a cheap static graph check: follow the subnet's VpcId Ref to a
+ * declared VPC in the same template and do IPv4 CIDR-range math.
+ *
+ * Stays quiet whenever the graph can't prove it: intrinsic CIDR blocks,
+ * IPv6, a VpcId that isn't a simple Ref to a declared AWS::EC2::VPC, or a
+ * VPC whose own CidrBlock isn't a literal string.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseCFTemplate, findResourceRefs, ipv4CidrContains } from "./cf-refs";
+
+export function checkSubnetCidrContainment(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [_lexicon, output] of ctx.outputs) {
+    const template = parseCFTemplate(output);
+    if (!template?.Resources) continue;
+
+    for (const [logicalId, resource] of Object.entries(template.Resources)) {
+      if (resource.Type !== "AWS::EC2::Subnet") continue;
+
+      const props = resource.Properties ?? {};
+      const subnetCidr = props.CidrBlock;
+      if (typeof subnetCidr !== "string") continue;
+
+      const vpcRefs = findResourceRefs(props.VpcId);
+      if (vpcRefs.size !== 1) continue;
+      const [vpcId] = vpcRefs;
+
+      const vpc = template.Resources[vpcId];
+      if (!vpc || vpc.Type !== "AWS::EC2::VPC") continue;
+
+      const vpcCidr = vpc.Properties?.CidrBlock;
+      if (typeof vpcCidr !== "string") continue;
+
+      const contained = ipv4CidrContains(vpcCidr, subnetCidr);
+      if (contained === false) {
+        diagnostics.push({
+          checkId: "WAW061",
+          severity: "error",
+          message: `Subnet "${logicalId}" CidrBlock ${subnetCidr} is not contained within VPC "${vpcId}"'s CidrBlock ${vpcCidr} — CloudFormation rejects this at deploy time`,
+          entity: logicalId,
+          lexicon: "aws",
+        });
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+export const waw061: PostSynthCheck = {
+  id: "WAW061",
+  description: "Subnet CidrBlock falls outside its VPC's CidrBlock — fails at deploy time",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkSubnetCidrContainment(ctx);
+  },
+};