@intentius/chant-lexicon-aws 0.46.0 → 0.49.0

package/src/deep-topology.test.ts

@@ -0,0 +1,392 @@
+/**
+ * Deep-read coverage for the EC2 topology types (#1269).
+ *
+ * The folds' inputs — VPC, subnet, route table, internet gateway, and the
+ * joins between them — were exactly the types the deep reader could not read,
+ * so a snapshot-backed query could answer identity questions and not a single
+ * fold question. These tests drive each added type through the real reader
+ * against faked describes, and close with the fold-level proof: a question
+ * that was previously unanswerable (is this VPC the provider's default?)
+ * answered from the deep read alone.
+ *
+ * Same seams as deep-observe.test.ts: Cloud Control and CloudFormation are
+ * faked at the injected `http` transport, the EC2 describes at the runtime's
+ * `spawn`.
+ */
+import { describe, test, expect, vi, beforeEach } from "vitest";
+
+const spawnMock = vi.fn();
+vi.mock("@intentius/chant/runtime-adapter", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@intentius/chant/runtime-adapter")>();
+  return { ...actual, getRuntime: () => ({ ...actual.getRuntime(), spawn: spawnMock }) };
+});
+
+const { observeResourcesDeepAws, DEEP_READABLE_TYPES, awsDeepNormalizationHooks } = await import("./deep-observe");
+const { vpcToModel, subnetToModel, routeTableToModel, internetGatewayToModel } = await import("./deep-topology");
+const { stampProviderDefaults } = await import("./defaults");
+const { normalizeDeepObservation } = await import("@intentius/chant/deep-observation");
+const { diffDeepObservation } = await import("@intentius/chant/lifecycle/deep-observe");
+
+const ok = (text: string) => ({ status: 200, text });
+
+/** A Cloud Control `GetResource` body — the model arrives as a JSON string. */
+const cloudControl = (identifier: string, properties: Record<string, unknown>) =>
+  ok(JSON.stringify({ ResourceDescription: { Identifier: identifier, Properties: JSON.stringify(properties) } }));
+
+const stackResources = (rows: Array<[string, string, string]>) =>
+  ok(
+    `<DescribeStackResourcesResponse><DescribeStackResourcesResult><StackResources>${rows
+      .map(
+        ([logicalId, type, physicalId]) =>
+          `<member><LogicalResourceId>${logicalId}</LogicalResourceId><ResourceType>${type}</ResourceType>` +
+          `<PhysicalResourceId>${physicalId}</PhysicalResourceId><ResourceStatus>CREATE_COMPLETE</ResourceStatus>` +
+          `<Timestamp>2026-01-01T00:00:00Z</Timestamp></member>`,
+      )
+      .join("")}</StackResources></DescribeStackResourcesResult></DescribeStackResourcesResponse>`,
+  );
+
+type FakeResponse = { status: number; text: string };
+
+/** Route on the Cloud Control identifier; `undefined` is the CloudFormation call. */
+function httpFake(route: (identifier: string | undefined) => FakeResponse) {
+  return async (_url: string, init: { headers: Record<string, string>; body: string }) => {
+    const target = init.headers["x-amz-target"];
+    const identifier = target ? (JSON.parse(init.body) as { Identifier?: string }).Identifier : undefined;
+    return route(identifier);
+  };
+}
+
+/** Route each EC2 bulk describe on its subcommand (`argv[2]`). */
+function ec2Describes(byCommand: Record<string, Record<string, unknown[]>>) {
+  spawnMock.mockImplementation((argv: string[]) => {
+    const body = byCommand[argv[2]];
+    if (!body) return Promise.resolve({ stdout: "", stderr: `no fake for ${argv[2]}`, exitCode: 255 });
+    return Promise.resolve({ stdout: JSON.stringify(body), stderr: "", exitCode: 0 });
+  });
+}
+
+const entities = (
+  record: Record<string, { entityType: string; props: Record<string, unknown> }>,
+): Map<string, { entityType: string; props: Record<string, unknown> }> => new Map(Object.entries(record));
+
+const vpcRow = {
+  VpcId: "vpc-01",
+  State: "available",
+  OwnerId: "111122223333",
+  CidrBlock: "10.0.0.0/16",
+  DhcpOptionsId: "dopt-01",
+  InstanceTenancy: "default",
+  IsDefault: false,
+  CidrBlockAssociationSet: [{ AssociationId: "vpc-cidr-assoc-01", CidrBlock: "10.0.0.0/16" }],
+  Tags: [{ Key: "env", Value: "prod" }],
+};
+
+// Braces matter: `mockReset()` returns the mock, and a function returned from
+// a vitest hook is called as a cleanup hook — the mock invoked with no argv.
+beforeEach(() => {
+  spawnMock.mockReset();
+});
+
+describe("the topology translations", () => {
+  test("a VPC row maps onto the resource model, keeping the provider's default marker", () => {
+    expect(vpcToModel(vpcRow)).toEqual({
+      VpcId: "vpc-01",
+      CidrBlock: "10.0.0.0/16",
+      InstanceTenancy: "default",
+      IsDefault: false,
+      Tags: [{ Key: "env", Value: "prod" }],
+    });
+  });
+
+  test("a subnet row keeps both fold inputs: the VPC hop and MapPublicIpOnLaunch", () => {
+    expect(
+      subnetToModel({
+        SubnetId: "subnet-01",
+        VpcId: "vpc-01",
+        State: "available",
+        OwnerId: "111122223333",
+        CidrBlock: "10.0.1.0/24",
+        AvailabilityZone: "us-east-1a",
+        AvailabilityZoneId: "use1-az1",
+        AvailableIpAddressCount: 250,
+        MapPublicIpOnLaunch: true,
+        AssignIpv6AddressOnCreation: false,
+        DefaultForAz: false,
+        Ipv6Native: false,
+        PrivateDnsNameOptionsOnLaunch: { HostnameType: "ip-name" },
+      }),
+    ).toEqual({
+      SubnetId: "subnet-01",
+      VpcId: "vpc-01",
+      CidrBlock: "10.0.1.0/24",
+      AvailabilityZone: "us-east-1a",
+      AvailabilityZoneId: "use1-az1",
+      MapPublicIpOnLaunch: true,
+      AssignIpv6AddressOnCreation: false,
+      Ipv6Native: false,
+      DefaultForAz: false,
+    });
+  });
+
+  test("a route table's routes and associations are its own declared resources, not carried twice", () => {
+    expect(
+      routeTableToModel({
+        RouteTableId: "rtb-01",
+        VpcId: "vpc-01",
+        Routes: [{ DestinationCidrBlock: "0.0.0.0/0", GatewayId: "igw-01" }],
+        Associations: [{ Main: false, SubnetId: "subnet-01" }],
+        PropagatingVgws: [],
+      }),
+    ).toEqual({ RouteTableId: "rtb-01", VpcId: "vpc-01" });
+  });
+
+  test("an internet gateway is tags and nothing else; an empty tag set is absence, not a value", () => {
+    expect(internetGatewayToModel({ InternetGatewayId: "igw-01", Attachments: [], Tags: [] })).toEqual({
+      InternetGatewayId: "igw-01",
+    });
+  });
+});
+
+describe("deep-reading an EC2 topology stack", () => {
+  const topologyStack = stackResources([
+    ["Net", "AWS::EC2::VPC", "vpc-01"],
+    ["PublicSubnet", "AWS::EC2::Subnet", "subnet-01"],
+    ["PublicRoutes", "AWS::EC2::RouteTable", "rtb-01"],
+    ["Igw", "AWS::EC2::InternetGateway", "igw-01"],
+  ]);
+
+  test("every topology type from #1269 is readable", () => {
+    for (const type of [
+      "AWS::EC2::VPC",
+      "AWS::EC2::Subnet",
+      "AWS::EC2::RouteTable",
+      "AWS::EC2::Route",
+      "AWS::EC2::SubnetRouteTableAssociation",
+      "AWS::EC2::InternetGateway",
+      "AWS::EC2::VPCGatewayAttachment",
+      "AWS::EC2::Instance",
+      "AWS::EC2::LaunchTemplate",
+    ]) {
+      expect(DEEP_READABLE_TYPES.has(type)).toBe(true);
+    }
+  });
+
+  test("one bulk describe per type, and every tree is recorded", async () => {
+    ec2Describes({
+      "describe-vpcs": { Vpcs: [vpcRow] },
+      "describe-subnets": {
+        Subnets: [{ SubnetId: "subnet-01", VpcId: "vpc-01", CidrBlock: "10.0.1.0/24", MapPublicIpOnLaunch: true }],
+      },
+      "describe-route-tables": { RouteTables: [{ RouteTableId: "rtb-01", VpcId: "vpc-01", Routes: [] }] },
+      "describe-internet-gateways": { InternetGateways: [{ InternetGatewayId: "igw-01", Attachments: [] }] },
+    });
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepAws({
+        environment: "prod",
+        entityNames: ["Net", "PublicSubnet", "PublicRoutes", "Igw"],
+        http: httpFake(() => topologyStack),
+      }),
+    );
+
+    expect(Object.keys(result.resources).sort()).toEqual(["Igw", "Net", "PublicRoutes", "PublicSubnet"]);
+    expect(result.unobserved).toEqual({});
+
+    // The containment hop and the public-IP fact the folds read.
+    expect(result.resources.PublicSubnet.properties).toMatchObject({
+      VpcId: "vpc-01",
+      MapPublicIpOnLaunch: true,
+    });
+    // Server-minted ids are pruned by the schema's own readOnlyProperties.
+    expect(result.resources.Net.properties.VpcId).toBeUndefined();
+    expect(result.resources.PublicSubnet.properties.SubnetId).toBeUndefined();
+    // The provider's default marker survives into the snapshot for the fold.
+    expect(result.resources.Net.properties.IsDefault).toBe(false);
+
+    // Four types, four describes — never one call per resource.
+    expect(spawnMock).toHaveBeenCalledTimes(4);
+    const commands = spawnMock.mock.calls.map((c) => (c[0] as string[])[2]).sort();
+    expect(commands).toEqual([
+      "describe-internet-gateways",
+      "describe-route-tables",
+      "describe-subnets",
+      "describe-vpcs",
+    ]);
+  });
+
+  test("the routing-chain joins read through Cloud Control by their physical id", async () => {
+    const http = httpFake((identifier) => {
+      if (identifier === undefined) {
+        return stackResources([
+          ["DefaultRoute", "AWS::EC2::Route", "rtb-01|0.0.0.0/0"],
+          ["SubnetRoutes", "AWS::EC2::SubnetRouteTableAssociation", "rtbassoc-01"],
+          ["IgwAttachment", "AWS::EC2::VPCGatewayAttachment", "IGW|vpc-01"],
+        ]);
+      }
+      if (identifier === "rtb-01|0.0.0.0/0") {
+        return cloudControl(identifier, {
+          RouteTableId: "rtb-01",
+          DestinationCidrBlock: "0.0.0.0/0",
+          GatewayId: "igw-01",
+        });
+      }
+      if (identifier === "rtbassoc-01") {
+        return cloudControl(identifier, { Id: "rtbassoc-01", RouteTableId: "rtb-01", SubnetId: "subnet-01" });
+      }
+      return cloudControl(identifier, { InternetGatewayId: "igw-01", VpcId: "vpc-01" });
+    });
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepAws({
+        environment: "prod",
+        entityNames: ["DefaultRoute", "SubnetRoutes", "IgwAttachment"],
+        http,
+      }),
+    );
+
+    // The `0.0.0.0/0` -> igw edge `internetFacing` walks.
+    expect(result.resources.DefaultRoute.properties).toEqual({
+      RouteTableId: "rtb-01",
+      DestinationCidrBlock: "0.0.0.0/0",
+      GatewayId: "igw-01",
+    });
+    // Subnet -> route table, with the association's own minted id pruned.
+    expect(result.resources.SubnetRoutes.properties).toEqual({
+      RouteTableId: "rtb-01",
+      SubnetId: "subnet-01",
+    });
+    // Igw -> VPC.
+    expect(result.resources.IgwAttachment.properties).toEqual({
+      InternetGatewayId: "igw-01",
+      VpcId: "vpc-01",
+    });
+    expect(spawnMock).not.toHaveBeenCalled();
+  });
+
+  test("a type without a source is still a stated hole, not a silent one", async () => {
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepAws({
+        environment: "prod",
+        entityNames: ["Ip"],
+        http: httpFake(() => stackResources([["Ip", "AWS::EC2::EIP", "203.0.113.7"]])),
+      }),
+    );
+    expect(result.resources).toEqual({});
+    expect(result.unobserved.Ip.reason).toBe("unsupported-kind");
+  });
+});
+
+describe("the fold answers (#1269)", () => {
+  const vpcStack = stackResources([
+    ["Net", "AWS::EC2::VPC", "vpc-01"],
+    ["Legacy", "AWS::EC2::VPC", "vpc-02"],
+  ]);
+
+  test("IsDefault on a VPC — previously unanswerable — answers from the deep read", async () => {
+    ec2Describes({
+      "describe-vpcs": {
+        Vpcs: [vpcRow, { ...vpcRow, VpcId: "vpc-02", CidrBlock: "172.31.0.0/16", IsDefault: true, Tags: [] }],
+      },
+    });
+    const observed = normalizeDeepObservation(
+      await observeResourcesDeepAws({
+        environment: "prod",
+        entityNames: ["Net", "Legacy"],
+        http: httpFake(() => vpcStack),
+      }),
+    );
+
+    // The classification fold reads the provider's own marker off the
+    // recorded properties — nothing to re-fetch, no heuristics.
+    const stamped = stampProviderDefaults(
+      Object.fromEntries(
+        Object.entries(observed.resources).map(([name, r]) => [
+          name,
+          { type: r.type, status: "CREATE_COMPLETE", attributes: r.properties },
+        ]),
+      ),
+    );
+    expect(stamped.Legacy.attributes?.providerDefault).toBe(true);
+    expect(stamped.Net.attributes?.providerDefault).toBeUndefined();
+  });
+
+  test("the marker feeds the fold without surfacing as drift on a declared VPC", async () => {
+    ec2Describes({ "describe-vpcs": { Vpcs: [vpcRow] } });
+    const observed = normalizeDeepObservation(
+      await observeResourcesDeepAws({
+        environment: "prod",
+        entityNames: ["Net"],
+        http: httpFake(() => stackResources([["Net", "AWS::EC2::VPC", "vpc-01"]])),
+      }),
+    );
+    const declared = entities({
+      Net: {
+        entityType: "AWS::EC2::VPC",
+        props: { CidrBlock: "10.0.0.0/16", Tags: [{ Key: "env", Value: "prod" }] },
+      },
+    });
+
+    // In the snapshot for a query to read…
+    expect(observed.resources.Net.properties.IsDefault).toBe(false);
+    // …and subtracted in the diff, where source never declared it.
+    const diff = diffDeepObservation(declared, observed, awsDeepNormalizationHooks);
+    expect(diff.drifted).toEqual([]);
+    expect(diff.unchanged).toEqual(["Net"]);
+  });
+
+  test("declared DNS attributes are a source blind spot, not absence drift; a visible change still reports", async () => {
+    ec2Describes({ "describe-vpcs": { Vpcs: [{ ...vpcRow, CidrBlock: "10.9.0.0/16", Tags: [] }] } });
+    const observed = normalizeDeepObservation(
+      await observeResourcesDeepAws({
+        environment: "prod",
+        entityNames: ["Net"],
+        http: httpFake(() => stackResources([["Net", "AWS::EC2::VPC", "vpc-01"]])),
+      }),
+    );
+    const declared = entities({
+      Net: {
+        entityType: "AWS::EC2::VPC",
+        props: { CidrBlock: "10.0.0.0/16", EnableDnsSupport: true, EnableDnsHostnames: true },
+      },
+    });
+
+    const diff = diffDeepObservation(declared, observed, awsDeepNormalizationHooks);
+    expect(diff.drifted).toEqual([
+      {
+        name: "Net",
+        type: "AWS::EC2::VPC",
+        changes: [
+          { path: "CidrBlock", kind: "changed", declared: "10.0.0.0/16", live: "10.9.0.0/16" },
+        ],
+      },
+    ]);
+  });
+
+  test("an out-of-band MapPublicIpOnLaunch flip reports; the service default does not", async () => {
+    const subnetRow = (mapPublic: boolean) => ({
+      Subnets: [{ SubnetId: "subnet-01", VpcId: "vpc-01", CidrBlock: "10.0.1.0/24", MapPublicIpOnLaunch: mapPublic }],
+    });
+    const declared = entities({
+      PublicSubnet: { entityType: "AWS::EC2::Subnet", props: { VpcId: "vpc-01", CidrBlock: "10.0.1.0/24" } },
+    });
+    const observe = async () =>
+      normalizeDeepObservation(
+        await observeResourcesDeepAws({
+          environment: "prod",
+          entityNames: ["PublicSubnet"],
+          http: httpFake(() => stackResources([["PublicSubnet", "AWS::EC2::Subnet", "subnet-01"]])),
+        }),
+      );
+
+    ec2Describes({ "describe-subnets": subnetRow(false) });
+    expect(diffDeepObservation(declared, await observe(), awsDeepNormalizationHooks).drifted).toEqual([]);
+
+    ec2Describes({ "describe-subnets": subnetRow(true) });
+    const diff = diffDeepObservation(declared, await observe(), awsDeepNormalizationHooks);
+    expect(diff.drifted).toEqual([
+      {
+        name: "PublicSubnet",
+        type: "AWS::EC2::Subnet",
+        changes: [{ path: "MapPublicIpOnLaunch", kind: "undeclared", live: true }],
+      },
+    ]);
+  });
+});

package/src/deep-topology.ts

@@ -0,0 +1,237 @@
+/**
+ * Deep-read sources for the EC2 topology types (#1269).
+ *
+ * chant's distinguishing answers are folds over topology: `internetFacing`
+ * resolves subnet -> route table -> internet gateway, `effectiveIngress`
+ * resolves rules across attached security groups, and the default-VPC
+ * classification (`defaults.ts`) reads the provider's own markers. The inputs
+ * to all of them are the types this file covers — with only the original four
+ * kinds readable, a deep snapshot of an EC2 estate carried almost no
+ * properties, and a snapshot-backed query could answer identity questions but
+ * not a single fold question.
+ *
+ * Two sources, chosen per type:
+ *
+ * - The container types (VPC, subnet, route table, internet gateway) read
+ *   through the EC2 describes. The fold facts live there and nowhere else:
+ *   `IsDefault`, `DefaultForAz` and a subnet's live `MapPublicIpOnLaunch` are
+ *   not part of the CloudFormation resource model, so Cloud Control cannot
+ *   report them. The describes are also bulk (one call per type for the whole
+ *   stack) and are implemented by the emulators that do not serve Cloud
+ *   Control's `GetResource`.
+ *
+ * - The join types (route, association, gateway attachment) and the two whose
+ *   describes do not fit a flat bulk join (instance rows nest inside
+ *   reservations; launch-template data lives in a separate versions call) read
+ *   through Cloud Control, which returns their model in the declared side's
+ *   own shape.
+ *
+ * Each type carries its normalization entries alongside (#1269's note: adding
+ * a type without them trades a hole for a false positive, which is worse).
+ * They are merged into the tables in `deep-observe.ts`.
+ */
+
+import type { DeepSource } from "./deep-observe";
+
+/**
+ * `describe-vpcs` -> the `AWS::EC2::VPC` resource model, plus `IsDefault`.
+ *
+ * `IsDefault` is the provider's own marker for the VPC nobody wrote — the fact
+ * the default classification reads — and it exists only on this surface.
+ * Carried even though the model does not name it; the diff subtracts it as a
+ * service default (`false`, gated on source silence) so a CloudFormation-made
+ * VPC does not report it as undeclared drift.
+ */
+export function vpcToModel(row: Record<string, unknown>): Record<string, unknown> {
+  return {
+    // The schema's readOnlyProperties prune the id after the ownership check.
+    ...(typeof row.VpcId === "string" ? { VpcId: row.VpcId } : {}),
+    ...(typeof row.CidrBlock === "string" ? { CidrBlock: row.CidrBlock } : {}),
+    ...(typeof row.InstanceTenancy === "string" ? { InstanceTenancy: row.InstanceTenancy } : {}),
+    ...(typeof row.IsDefault === "boolean" ? { IsDefault: row.IsDefault } : {}),
+    ...nonEmptyTags(row),
+  };
+}
+
+/**
+ * `describe-subnets` -> the `AWS::EC2::Subnet` resource model, plus
+ * `DefaultForAz`.
+ *
+ * `MapPublicIpOnLaunch` is half of `internetFacing`; `DefaultForAz` is the
+ * provider's default-subnet marker, off the model for the same reason as a
+ * VPC's `IsDefault` and handled the same way.
+ */
+export function subnetToModel(row: Record<string, unknown>): Record<string, unknown> {
+  return {
+    ...(typeof row.SubnetId === "string" ? { SubnetId: row.SubnetId } : {}),
+    ...(typeof row.VpcId === "string" ? { VpcId: row.VpcId } : {}),
+    ...(typeof row.CidrBlock === "string" ? { CidrBlock: row.CidrBlock } : {}),
+    ...(typeof row.AvailabilityZone === "string" ? { AvailabilityZone: row.AvailabilityZone } : {}),
+    ...(typeof row.AvailabilityZoneId === "string" ? { AvailabilityZoneId: row.AvailabilityZoneId } : {}),
+    ...(typeof row.MapPublicIpOnLaunch === "boolean" ? { MapPublicIpOnLaunch: row.MapPublicIpOnLaunch } : {}),
+    ...(typeof row.AssignIpv6AddressOnCreation === "boolean"
+      ? { AssignIpv6AddressOnCreation: row.AssignIpv6AddressOnCreation }
+      : {}),
+    ...(typeof row.EnableDns64 === "boolean" ? { EnableDns64: row.EnableDns64 } : {}),
+    ...(typeof row.Ipv6Native === "boolean" ? { Ipv6Native: row.Ipv6Native } : {}),
+    ...(typeof row.DefaultForAz === "boolean" ? { DefaultForAz: row.DefaultForAz } : {}),
+    ...nonEmptyTags(row),
+  };
+}
+
+/**
+ * `describe-route-tables` -> the `AWS::EC2::RouteTable` resource model.
+ *
+ * The row also carries `Routes` and `Associations`, and this mapping drops
+ * them on purpose: a template declares each route as its own
+ * `AWS::EC2::Route` and each association as its own
+ * `AWS::EC2::SubnetRouteTableAssociation`, both covered below, so carrying
+ * them here would report every declared route twice — once as an undeclared
+ * array on the table and once through its own resource.
+ */
+export function routeTableToModel(row: Record<string, unknown>): Record<string, unknown> {
+  return {
+    ...(typeof row.RouteTableId === "string" ? { RouteTableId: row.RouteTableId } : {}),
+    ...(typeof row.VpcId === "string" ? { VpcId: row.VpcId } : {}),
+    ...nonEmptyTags(row),
+  };
+}
+
+/** `describe-internet-gateways` -> the `AWS::EC2::InternetGateway` model, which is tags and nothing else. */
+export function internetGatewayToModel(row: Record<string, unknown>): Record<string, unknown> {
+  return {
+    ...(typeof row.InternetGatewayId === "string" ? { InternetGatewayId: row.InternetGatewayId } : {}),
+    ...nonEmptyTags(row),
+  };
+}
+
+/**
+ * An empty tag set is the absence of tags, not a value. EC2 always sends the
+ * key, so carrying it through reports `Tags: <undeclared> -> []` on every
+ * untagged resource — agreement rendered as drift. Same rule as the
+ * security-group mapping.
+ */
+function nonEmptyTags(row: Record<string, unknown>): Record<string, unknown> {
+  return Array.isArray(row.Tags) && row.Tags.length > 0 ? { Tags: row.Tags } : {};
+}
+
+/**
+ * The topology types' entries for `DEEP_SOURCES`.
+ *
+ * The routing-chain joins are addressed by their physical id — for a
+ * registry-backed type CloudFormation's physical id *is* the Cloud Control
+ * identifier (`rtb-…|0.0.0.0/0` for a route) — so Cloud Control's
+ * one-get-per-resource shape fits them exactly and returns the declared
+ * model's own field names.
+ */
+export const EC2_TOPOLOGY_SOURCES: Record<string, DeepSource> = {
+  "AWS::EC2::VPC": {
+    via: "ec2",
+    argv: ["ec2", "describe-vpcs"],
+    idFlag: "--vpc-ids",
+    key: "Vpcs",
+    id: "VpcId",
+    toModel: vpcToModel,
+  },
+  "AWS::EC2::Subnet": {
+    via: "ec2",
+    argv: ["ec2", "describe-subnets"],
+    idFlag: "--subnet-ids",
+    key: "Subnets",
+    id: "SubnetId",
+    toModel: subnetToModel,
+  },
+  "AWS::EC2::RouteTable": {
+    via: "ec2",
+    argv: ["ec2", "describe-route-tables"],
+    idFlag: "--route-table-ids",
+    key: "RouteTables",
+    id: "RouteTableId",
+    toModel: routeTableToModel,
+  },
+  "AWS::EC2::InternetGateway": {
+    via: "ec2",
+    argv: ["ec2", "describe-internet-gateways"],
+    idFlag: "--internet-gateway-ids",
+    key: "InternetGateways",
+    id: "InternetGatewayId",
+    toModel: internetGatewayToModel,
+  },
+  // The `0.0.0.0/0` -> igw edge `internetFacing` walks.
+  "AWS::EC2::Route": { via: "cloud-control" },
+  // Subnet -> route table.
+  "AWS::EC2::SubnetRouteTableAssociation": { via: "cloud-control" },
+  // Igw -> VPC.
+  "AWS::EC2::VPCGatewayAttachment": { via: "cloud-control" },
+  // Subnet, security groups, launch template — the instance end of both folds.
+  "AWS::EC2::Instance": { via: "cloud-control" },
+  // The indirect security-group hop `effectiveIngress` resolves through.
+  "AWS::EC2::LaunchTemplate": { via: "cloud-control" },
+};
+
+/**
+ * Service defaults for the topology types, merged into
+ * `AWS_SERVICE_DEFAULTS`. Subtracted on the live side only where source never
+ * declared the property — which is how the fold facts (`IsDefault`,
+ * `DefaultForAz`, a live `MapPublicIpOnLaunch`) stay in the snapshot for a
+ * query to read while never surfacing as drift on a resource CloudFormation
+ * itself created.
+ */
+export const EC2_TOPOLOGY_SERVICE_DEFAULTS: Record<string, Record<string, unknown>> = {
+  "AWS::EC2::VPC": {
+    InstanceTenancy: "default",
+    IsDefault: false,
+  },
+  "AWS::EC2::Subnet": {
+    MapPublicIpOnLaunch: false,
+    AssignIpv6AddressOnCreation: false,
+    EnableDns64: false,
+    Ipv6Native: false,
+    DefaultForAz: false,
+  },
+  "AWS::EC2::Instance": {
+    Tenancy: "default",
+    Monitoring: false,
+    EbsOptimized: false,
+    SourceDestCheck: true,
+    DisableApiTermination: false,
+  },
+};
+
+/**
+ * Values the service picks when the template does not supply one, merged into
+ * `AWS_GENERATED_NAMES`. A subnet that names no availability zone gets one
+ * assigned — a different one is real placement drift only when the template
+ * had an opinion, which is exactly the counterpart gate.
+ */
+export const EC2_TOPOLOGY_GENERATED_NAMES: Record<string, ReadonlySet<string>> = {
+  "AWS::EC2::Subnet": new Set(["AvailabilityZone", "AvailabilityZoneId"]),
+  "AWS::EC2::Instance": new Set(["AvailabilityZone"]),
+};
+
+/**
+ * Declared properties a type's source cannot see (#1269).
+ *
+ * `describe-vpcs` does not return the DNS attributes — they live behind
+ * `describe-vpc-attribute` — and neither describe returns the IPAM inputs,
+ * which are consumed at creation. A declared value for one of these has
+ * nothing live to stand against, so the diff would report `value -> <absent>`
+ * on every clean apply: a blind spot rendered as drift. Pruned on the
+ * declared side, and only where the live tree is silent, so a source that
+ * does report the field (Cloud Control, some day) is still compared.
+ */
+export const AWS_DEEP_BLIND_SPOTS: Record<string, ReadonlySet<string>> = {
+  "AWS::EC2::VPC": new Set([
+    "EnableDnsSupport",
+    "EnableDnsHostnames",
+    "Ipv4IpamPoolId",
+    "Ipv4NetmaskLength",
+  ]),
+  "AWS::EC2::Subnet": new Set([
+    "Ipv6CidrBlock",
+    "Ipv4IpamPoolId",
+    "Ipv4NetmaskLength",
+    "Ipv6IpamPoolId",
+    "Ipv6NetmaskLength",
+  ]),
+};