@intentius/chant-lexicon-aws 0.33.1 → 0.34.0

package/dist/integrity.json

@@ -1,9 +1,9 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "82f137b9dc9816456d5230a0150bcdd48c79224e6fb237c3bf4951dfe6a7608b",
-    "meta.json": "e991aef2b315b2172b66aaa916ac1ff93a13446ec08f169c6c219aa4850f965a",
-    "types/index.d.ts": "fd13489a9f92b01b620576a283d21423b231e085a0783869c389be9a9c5d9a60",
+    "manifest.json": "3c7b5e21a39f86218b481199f51f2d045af99311e67dbae6d3f4f0a7a3569506",
+    "meta.json": "ffe08a1fc279b969d8760332917ddaa0fdf2eca083f861d608f2c55ee8ec147d",
+    "types/index.d.ts": "cd6ca943e0753ae32530aadad245b72f910990d5ee7244d5e79cf22f9ff0cf1f",
     "rules/hardcoded-region.ts": "5a0eaf7ab391231fe6cd51426ece29539cb4b36f31c8dd060956638fed55722a",
     "rules/iam-wildcard.ts": "135d7217d278fef50939e605c5da32603ba35674b8c4b5c4d66a06c77903e945",
     "rules/s3-encryption.ts": "c4f9f8aa8dc382ed98c7b04e820a600590cc75335a8db2e087cbfbfe4003d09e",
@@ -59,5 +59,5 @@
     "skills/chant-aws-eks.md": "8789255709ff004ad0a875fd5999edcdc66fc6e33d710db058d9f42703bcfdfe",
     "skills/chant-aws-carve-terraform.md": "f4c6fe1c702250665f90d82b3bdaba5ea50ae75e380a8ae321dad6eb1c39683e"
   },
-  "composite": "7b518a1dfe34d3687de1345b606674017c87c7a687ed837870c953ec24841aae"
+  "composite": "b23b837556489ce43cf6d8ba4ebb13ecf700868ac0cd8698be4af926585915c3"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "aws",
-  "version": "0.33.1",
+  "version": "0.34.0",
   "chantVersion": ">=0.1.0",
   "namespace": "AWS",
   "intrinsics": [

package/dist/meta.json

@@ -44553,6 +44553,67 @@
     "kind": "property",
     "lexicon": "aws"
   },
+  "HarnessEndpoint": {
+    "resourceType": "AWS::BedrockAgentCore::HarnessEndpoint",
+    "kind": "resource",
+    "lexicon": "aws",
+    "attrs": {
+      "Arn": "Arn",
+      "HarnessName": "HarnessName",
+      "Status": "Status",
+      "LiveVersion": "LiveVersion",
+      "CreatedAt": "CreatedAt",
+      "UpdatedAt": "UpdatedAt"
+    },
+    "propertyConstraints": {
+      "HarnessId": {
+        "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,39}-[a-zA-Z0-9]{10}$"
+      },
+      "EndpointName": {
+        "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,47}$"
+      },
+      "TargetVersion": {
+        "pattern": "^([1-9][0-9]{0,4})$",
+        "minLength": 1,
+        "maxLength": 5
+      },
+      "LiveVersion": {
+        "pattern": "^([1-9][0-9]{0,4})$",
+        "minLength": 1,
+        "maxLength": 5
+      },
+      "Description": {
+        "minLength": 1,
+        "maxLength": 256
+      },
+      "CreatedAt": {
+        "format": "date-time"
+      },
+      "UpdatedAt": {
+        "format": "date-time"
+      }
+    },
+    "createOnly": [
+      "HarnessId",
+      "EndpointName"
+    ],
+    "writeOnly": [
+      "TargetVersion"
+    ],
+    "primaryIdentifier": [
+      "Arn"
+    ],
+    "tagging": {
+      "taggable": true,
+      "tagOnCreate": true,
+      "tagUpdatable": true
+    }
+  },
+  "HarnessEndpoint_Tag": {
+    "resourceType": "AWS::BedrockAgentCore::HarnessEndpoint.Tag",
+    "kind": "property",
+    "lexicon": "aws"
+  },
   "HarnessEnvironmentArtifact": {
     "resourceType": "AWS::BedrockAgentCore::Harness.HarnessEnvironmentArtifact",
     "kind": "property",
@@ -70884,7 +70945,7 @@
         "maxLength": 256
       },
       "FunctionName": {
-        "pattern": "^(arn:(aws[a-zA-Z-]*)?:lambda:)?((eusc-)?[a-z]{2}((-gov)|(-iso([a-z]?)))?-[a-z]+-\\d{1}:)?(\\d{12}:)?(function:)?([a-zA-Z0-9-_]+)(:(\\$LATEST|[a-zA-Z0-9-_]+))?$",
+        "pattern": "^(arn:(aws[a-zA-Z-]*)?:lambda:)?((eusc-)?[a-z]{2}((-gov)|(-iso([a-z]?)))?-[a-z]+-\\d{1}:)?(\\d{12}:)?(function:)?([a-zA-Z0-9-_]+)(:(\\$LATEST(\\.PUBLISHED)?|[a-zA-Z0-9-_]+))?$",
         "minLength": 1,
         "maxLength": 140
       },

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAyJ,MAAM,0BAA0B,CAAC;AA0BrN;yEACyE;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AA6DnD,eAAO,MAAM,SAAS,EAAE,aAm2BvB,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAgL,MAAM,0BAA0B,CAAC;AA6B5O;yEACyE;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAWnD,eAAO,MAAM,SAAS,EAAE,aAm5BvB,CAAC"}

package/dist/properties.d.ts

@@ -0,0 +1,48 @@
+/**
+ * A managed resource's own properties (#1279).
+ *
+ * `describe-stack-resources` returns identity and status — logical id, physical
+ * id, type, timestamp — and nothing about the resource itself. So the managed
+ * observation filled `attributes` with the *stack's* outputs instead, copied
+ * onto every resource in the stack. Every node in a stack came out carrying the
+ * same `expVpcId`/`expWebIp` keys, and no node carried its own `VpcId`.
+ *
+ * That is invisible until something asks. `search --show VpcId` printed a blank
+ * column for six instances, which reads as "the estate has no VPCs" rather than
+ * "chant never read that". An agent asked which instances were outside the
+ * default VPC concluded all six were, because nothing in the graph said
+ * otherwise.
+ *
+ * A deep read (Cloud Control) answers this properly but is a per-resource call
+ * and is not available on every endpoint. This is the cheap middle: one describe
+ * per kind for the whole observation, joined back by physical id. Stack outputs
+ * are kept — they were the only attributes for a long time and queries lean on
+ * them — but a resource's own properties win a name collision, because they are
+ * the resource's.
+ */
+import type { ResourceMetadata } from "@intentius/chant/lexicon";
+/**
+ * Stamp the region each resource was observed in (#1279).
+ *
+ * The observation is already scoped per stack and each stack declares its
+ * region, so the reader knows this and was throwing it away. Without it the
+ * only route to "which region is this in" was parsing
+ * `Placement.AvailabilityZone` and trimming the last character — a trick that
+ * happens to work for EC2 and for nothing else. Region is a dimension of the
+ * estate, not a substring of an availability zone.
+ */
+export declare function stampRegion(resources: Record<string, ResourceMetadata>, region?: string): Record<string, ResourceMetadata>;
+/** True when this lexicon can read the kind's own properties. */
+export declare function canDescribe(kind: string): boolean;
+/**
+ * Merge each resource's own properties into an observation, in place of nothing.
+ *
+ * Best-effort per kind, and per kind only: an endpoint that cannot answer
+ * `describe-subnets` still yields instance properties, and a total failure
+ * leaves the observation exactly as it arrived. The managed observation is
+ * already complete without any of this — these are additional facts about
+ * resources chant has already identified, so a miss costs detail, never
+ * correctness.
+ */
+export declare function describeOwnProperties(resources: Record<string, ResourceMetadata>, region?: string): Promise<Record<string, ResourceMetadata>>;
+//# sourceMappingURL=properties.d.ts.map

package/dist/properties.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"properties.d.ts","sourceRoot":"","sources":["../src/properties.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAkCjE;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,EAC3C,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAUlC;AAED,iEAAiE;AACjE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,EAC3C,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAgE3C"}

package/dist/reference-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reference-catalog.d.ts","sourceRoot":"","sources":["../src/reference-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,EAAE,gBAoEjC,CAAC"}
+{"version":3,"file":"reference-catalog.d.ts","sourceRoot":"","sources":["../src/reference-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,EAAE,gBAyFjC,CAAC"}

package/dist/types/index.d.ts

@@ -16403,6 +16403,38 @@ export declare class Harness {
   readonly Version: string;
 }
 
+export declare class HarnessEndpoint {
+  constructor(props: {
+    /** The name of the endpoint. Must start with a letter and contain only alphanumeric characters and underscores. */
+    EndpointName: string;
+    /** The ID of the harness that the endpoint belongs to. */
+    HarnessId: string;
+    /** The Amazon Resource Name (ARN) of the endpoint. */
+    Arn?: string;
+    /** The timestamp when the endpoint was created. */
+    CreatedAt?: string;
+    /** The description of the endpoint. */
+    Description?: string;
+    /** The name of the harness that the endpoint belongs to. */
+    HarnessName?: string;
+    /** The harness version that the endpoint is currently serving. */
+    LiveVersion?: string;
+    Status?: HarnessEndpoint_HarnessEndpointStatus;
+    /** Tags to apply to the harness endpoint resource. */
+    Tags?: HarnessEndpoint_Tag[];
+    /** The harness version that the endpoint points to and serves invocations from. */
+    TargetVersion?: string;
+    /** The timestamp when the endpoint was last updated. */
+    UpdatedAt?: string;
+  }, attributes?: CFResourceAttributes);
+  readonly Arn: string;
+  readonly CreatedAt: string;
+  readonly HarnessName: string;
+  readonly LiveVersion: string;
+  readonly Status: HarnessEndpoint_HarnessEndpointStatus;
+  readonly UpdatedAt: string;
+}
+
 export declare class HealthCheck {
   constructor(props: {
     /** A complex type that contains information about the health check. */
@@ -57089,7 +57121,7 @@ export declare class ContainerRecipe_EbsInstanceBlockDeviceSpecification {
     /** Use to override the device's volume size. */
     VolumeSize?: number;
     /** Use to override the device's volume type. */
-    VolumeType?: "gp2" | "gp3" | "io1" | "io2" | "sc1" | "st1" | "standard";
+    VolumeType?: "gp2" | "gp3" | "gp3a" | "io1" | "io2" | "io2a" | "sc1" | "st1" | "standard";
   });
 }
 
@@ -75141,7 +75173,7 @@ export declare class GlobalTable_ReplicaSSESpecification {
 
 export declare class GlobalTable_ReplicaStreamSpecification {
   constructor(props: {
-    ResourcePolicy?: GlobalTable_ResourcePolicy;
+    ResourcePolicy: GlobalTable_ResourcePolicy;
   });
 }
 
@@ -76693,6 +76725,13 @@ export declare class HarnessBedrockModelConfig {
   });
 }
 
+export declare class HarnessEndpoint_Tag {
+  constructor(props: {
+    Key: string;
+    Value: string;
+  });
+}
+
 export declare class HarnessEnvironmentArtifact {
   constructor(props: {
     ContainerConfiguration?: Harness_ContainerConfiguration;
@@ -78724,7 +78763,7 @@ export declare class ImageRecipe_EbsInstanceBlockDeviceSpecification {
     /** Use to override the device's volume size. */
     VolumeSize?: number;
     /** Use to override the device's volume type. */
-    VolumeType?: "gp2" | "gp3" | "io1" | "io2" | "sc1" | "st1" | "standard";
+    VolumeType?: "gp2" | "gp3" | "gp3a" | "io1" | "io2" | "io2a" | "sc1" | "st1" | "standard";
   });
 }
 
@@ -86435,7 +86474,9 @@ export declare class Listener_RedirectConfig {
 
 export declare class Listener_Tag {
   constructor(props: {
+    /** The key of the tag. */
     Key: string;
+    /** The value of the tag. */
     Value: string;
   });
 }
@@ -106283,7 +106324,7 @@ export declare class ReplicaSSESpecification {
 
 export declare class ReplicaStreamSpecification {
   constructor(props: {
-    ResourcePolicy?: GlobalTable_ResourcePolicy;
+    ResourcePolicy: GlobalTable_ResourcePolicy;
   });
 }
 
@@ -112163,6 +112204,8 @@ export declare class Scraper_Destination {
   constructor(props: {
     /** Configuration for Amazon Managed Prometheus metrics destination */
     AmpConfiguration?: Record<string, unknown>;
+    /** Configuration for CloudWatch metrics destination */
+    CloudWatchConfiguration?: Record<string, unknown>;
   });
 }
 
@@ -130350,6 +130393,15 @@ export type Harness_HarnessStatus =
   | "UPDATE_FAILED"
   | "UPDATING";
 
+export type HarnessEndpoint_HarnessEndpointStatus =
+  | "CREATE_FAILED"
+  | "CREATING"
+  | "DELETE_FAILED"
+  | "DELETING"
+  | "READY"
+  | "UPDATE_FAILED"
+  | "UPDATING";
+
 export type HealthImagingDatastore_DatastoreStatus =
   | "ACTIVE"
   | "CREATE_FAILED"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-aws",
-  "version": "0.33.1",
+  "version": "0.34.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.33.1",
+    "@intentius/chant": "^0.34.0",
     "typescript": "^5.9.3"
   }
 }

package/src/ambient.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, 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 { observeAwsAmbient, canEnumerate } = await import("./ambient");
+
+const ok = (body: unknown) => ({ stdout: JSON.stringify(body), stderr: "", exitCode: 0 });
+const GROUPS = {
+  SecurityGroups: [
+    { GroupId: "sg-default", GroupName: "default", VpcId: "vpc-1" },
+    { GroupId: "sg-mine", GroupName: "web", VpcId: "vpc-1" },
+    { GroupId: "sg-stray", GroupName: "leftover", VpcId: "vpc-1" },
+  ],
+};
+
+// #1278 — a resource nothing points at is invisible to both other observation
+// paths, because both resolve outward from what is declared. "Which of my
+// security groups are unused" is a question about exactly those.
+describe("observeAwsAmbient (#1278)", () => {
+  beforeEach(() => spawnMock.mockReset());
+
+  it("reports groups that exist but are not managed", async () => {
+    spawnMock.mockResolvedValue(ok(GROUPS));
+    const found = await observeAwsAmbient({
+      kinds: ["AWS::EC2::SecurityGroup"],
+      observed: { web: { type: "AWS::EC2::SecurityGroup", status: "OK", physicalId: "sg-mine" } },
+    });
+    // sg-mine is managed, so it is not ambient — it would otherwise be counted twice.
+    expect(Object.keys(found).sort()).toEqual(["sg-default", "sg-stray"]);
+    expect(found["sg-default"]).toMatchObject({ ambient: true, ownership: "foreign" });
+  });
+
+  it("carries the whole payload, leaving 'unused' to the graph", async () => {
+    // Deciding attachment in the reader would put a conclusion in the
+    // observation — the mistake liveInternetFacing made and #1271 undid.
+    spawnMock.mockResolvedValue(ok(GROUPS));
+    const found = await observeAwsAmbient({ kinds: ["AWS::EC2::SecurityGroup"], observed: {} });
+    expect(found["sg-default"].attributes).toMatchObject({ GroupName: "default", VpcId: "vpc-1" });
+  });
+
+  it("is bounded by the kinds the project declares", async () => {
+    // A project managing security groups is not made to enumerate the account.
+    const found = await observeAwsAmbient({ kinds: ["AWS::S3::Bucket"], observed: {} });
+    expect(found).toEqual({});
+    expect(spawnMock).not.toHaveBeenCalled();
+  });
+
+  it("targets the stack's region", async () => {
+    spawnMock.mockResolvedValue(ok(GROUPS));
+    await observeAwsAmbient({ kinds: ["AWS::EC2::SecurityGroup"], observed: {}, region: "us-west-2" });
+    const argv = spawnMock.mock.calls[0][0] as string[];
+    expect(argv).toContain("--region");
+    expect(argv).toContain("us-west-2");
+  });
+
+  it("a failed enumeration yields nothing rather than throwing", async () => {
+    spawnMock.mockResolvedValue({ stdout: "", stderr: "denied", exitCode: 255 });
+    await expect(
+      observeAwsAmbient({ kinds: ["AWS::EC2::SecurityGroup"], observed: {} }),
+    ).resolves.toEqual({});
+  });
+
+  it("declares which kinds it can enumerate", () => {
+    expect(canEnumerate("AWS::EC2::SecurityGroup")).toBe(true);
+    expect(canEnumerate("AWS::EC2::Instance")).toBe(false);
+  });
+});

package/src/ambient.ts

@@ -0,0 +1,147 @@
+/**
+ * Resources that are simply *there* (#1278).
+ *
+ * `describeResources` answers "what do I manage" and `observeDependencies`
+ * answers "what do I rely on". Both resolve outward from the declared estate,
+ * so neither can see a resource nothing points at — and "which of my security
+ * groups are unused" is precisely a question about resources nothing points at.
+ *
+ * A state file cannot answer this at all: it knows what it created, and an
+ * unused resource is by definition not something it created and attached. A
+ * lexicon that can enumerate a kind can.
+ *
+ * Bounded by the kinds the project declares. A project managing security groups
+ * is asked about security groups, not about the account.
+ */
+
+import { applyAwsEndpointArgv } from "./components/cloud-executor";
+import type { ResourceMetadata } from "@intentius/chant/lexicon";
+
+/** Enumerable kinds, and how to list them. Extending this is the way to widen. */
+const ENUMERABLE: Record<string, { argv: string[]; key: string; id: string; name?: string }> = {
+  "AWS::EC2::SecurityGroup": {
+    argv: ["ec2", "describe-security-groups"],
+    key: "SecurityGroups",
+    id: "GroupId",
+    name: "GroupName",
+  },
+  // The account's default VPC is the archetype: nothing declares it, nothing
+  // in the declared estate points at it, and "which instances are outside a
+  // default VPC" cannot be answered without it.
+  "AWS::EC2::VPC": {
+    argv: ["ec2", "describe-vpcs"],
+    key: "Vpcs",
+    id: "VpcId",
+  },
+  // Nobody writes a network interface: EC2 creates one per instance. But the
+  // ENI is where a security group is actually attached, so "which of my
+  // security groups are unused" is an ENI question and cannot be answered
+  // without them. Asked exactly that, an agent queried
+  // `kind:EC2::NetworkInterface`, got nothing, and rebuilt the attachment map
+  // by hand from twenty-nine raw provider calls.
+  "AWS::EC2::NetworkInterface": {
+    argv: ["ec2", "describe-network-interfaces"],
+    key: "NetworkInterfaces",
+    id: "NetworkInterfaceId",
+  },
+};
+
+/**
+ * Kinds a declared kind implies, though nobody writes them.
+ *
+ * The scan is bounded by what the project declares — a project managing
+ * security groups is asked about security groups, not about the account. That
+ * bound is right, and it excluded exactly the resource that answers the
+ * question: EC2 creates a network interface per instance, and the ENI is where
+ * a security group is actually attached. So an estate full of instances had no
+ * ENIs recorded, and "which of my security groups are unused" — definitionally
+ * an ENI question — could not be answered from the snapshot at all.
+ *
+ * Declaring an instance is declaring its network interface. This widens the
+ * bound by implication rather than abandoning it: still nothing about the
+ * account at large.
+ */
+const IMPLIED: Record<string, string[]> = {
+  "AWS::EC2::Instance": ["AWS::EC2::NetworkInterface"],
+};
+
+/** The requested kinds, plus the ones they imply. */
+export function withImplied(kinds: string[]): string[] {
+  return [...new Set(kinds.flatMap((k) => [k, ...(IMPLIED[k] ?? [])]))];
+}
+
+/** The kinds this reader can enumerate. Declared so a caller can mention
+ * `--ambient` without paying for a scan to discover it is relevant. */
+export const AMBIENT_KINDS: string[] = Object.keys(ENUMERABLE);
+
+/** True when this lexicon can enumerate the kind, so a caller can say what it skipped. */
+export function canEnumerate(kind: string): boolean {
+  return kind in ENUMERABLE;
+}
+
+/**
+ * List resources of the declared kinds that exist in the account but are
+ * neither managed nor already observed.
+ *
+ * Attachment is deliberately NOT decided here. Whether a security group is
+ * "unused" is a graph question — does anything reference it — and the graph
+ * answers it once the group is a node. Deciding it in the reader would put a
+ * conclusion in the observation, which is the mistake `liveInternetFacing` made
+ * and #1271 undid.
+ */
+export async function observeAwsAmbient(options: {
+  kinds: string[];
+  observed: Record<string, ResourceMetadata>;
+  region?: string;
+}): Promise<Record<string, ResourceMetadata>> {
+  const kinds = withImplied(options.kinds).filter(canEnumerate);
+  if (kinds.length === 0) return {};
+
+  const { getRuntime } = await import("@intentius/chant/runtime-adapter");
+  const rt = getRuntime();
+  const regionArgs = options.region ? ["--region", options.region] : [];
+
+  // Physical ids already accounted for, so a managed resource is never also
+  // reported as ambient.
+  const known = new Set(
+    Object.values(options.observed)
+      .map((m) => m.physicalId)
+      .filter((id): id is string => typeof id === "string"),
+  );
+
+  const ambient: Record<string, ResourceMetadata> = {};
+  for (const kind of kinds) {
+    const spec = ENUMERABLE[kind];
+    try {
+      const result = await rt.spawn(
+        applyAwsEndpointArgv(["aws", ...spec.argv, ...regionArgs, "--output", "json"], process.env.AWS_ENDPOINT_URL),
+      );
+      if (result.exitCode !== 0) continue;
+      const rows = (JSON.parse(result.stdout)[spec.key] ?? []) as Array<Record<string, unknown>>;
+      for (const row of rows) {
+        const id = row[spec.id];
+        if (typeof id !== "string" || known.has(id)) continue;
+        ambient[id] = {
+          type: kind,
+          status: "OBSERVED",
+          physicalId: id,
+          // The whole payload, so the graph can decide what "unused" means
+          // rather than the reader pre-deciding it.
+          attributes: row,
+          ownership: "foreign",
+          ambient: true,
+        };
+      }
+    } catch {
+      // Best-effort per kind: one unreadable kind does not sink the others, and
+      // the managed observation is already complete without any of this.
+      continue;
+    }
+  }
+  // Same stamps the managed path applies, so one query shape works across both
+  // (#1279). Defaults matter most here: a default VPC or security group is
+  // ambient by definition — nobody declared it.
+  const { stampRegion } = await import("./properties");
+  const { stampProviderDefaults } = await import("./defaults");
+  return stampProviderDefaults(stampRegion(ambient, options.region));
+}

package/src/deep-observe.ts

@@ -246,6 +246,11 @@ export interface AwsDeepObserveOptions {
   entityNames: string[];
   entities?: Map<string, { entityType: string; props: Record<string, unknown> }>;
   stack?: string;
+  /** Region this stack is deployed in (#1267). Same reason the thin path takes
+   * one (#1261): without it a multi-region estate reads every stack against the
+   * ambient region, the out-of-region ones come back empty, and a deep snapshot
+   * silently records no properties for them. */
+  region?: string;
   owned?: boolean;
 }
 
@@ -270,9 +275,12 @@ export async function observeResourcesDeepAws(
   const stackName = options.stack ?? options.environment;
   const endpoint = process.env.AWS_ENDPOINT_URL;
 
+  const regionArgs = options.region ? ["--region", options.region] : [];
+
   const listResult = await rt.spawn(applyAwsEndpointArgv([
     "aws", "cloudformation", "describe-stack-resources",
     "--stack-name", stackName,
+    ...regionArgs,
     "--output", "json",
   ], endpoint));
 
@@ -334,6 +342,7 @@ export async function observeResourcesDeepAws(
       "aws", "cloudcontrol", "get-resource",
       "--type-name", type,
       "--identifier", identifier,
+      ...regionArgs,
       "--output", "json",
     ], endpoint));
 

package/src/defaults.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect } from "vitest";
+import { stampProviderDefaults, canDetectDefault, DEFAULT_AWARE_KINDS } from "./defaults";
+import type { ResourceMetadata } from "@intentius/chant/lexicon";
+
+const res = (type: string, attributes: Record<string, unknown>): ResourceMetadata => ({
+  type,
+  status: "OBSERVED",
+  physicalId: "x",
+  attributes,
+});
+
+const flag = (type: string, attributes: Record<string, unknown>) =>
+  stampProviderDefaults({ r: res(type, attributes) }).r.attributes?.providerDefault;
+
+// Every account arrives with resources nobody wrote. Asked which security
+// groups were unused, agents split three ways on the same correct set of four,
+// because chant gave them no way to tell a VPC's default group from one someone
+// created.
+describe("provider defaults (#1278)", () => {
+  it("reads the marker AWS already sets, per kind", () => {
+    expect(flag("AWS::EC2::VPC", { IsDefault: true })).toBe(true);
+    expect(flag("AWS::EC2::Subnet", { DefaultForAz: true })).toBe(true);
+    expect(flag("AWS::EC2::NetworkAcl", { IsDefault: true })).toBe(true);
+    expect(flag("AWS::KMS::Key", { KeyManager: "AWS" })).toBe(true);
+    expect(flag("AWS::IAM::ManagedPolicy", { Arn: "arn:aws:iam::aws:policy/ReadOnlyAccess" })).toBe(true);
+  });
+
+  it("does not mark what the account holder created", () => {
+    expect(flag("AWS::EC2::VPC", { IsDefault: false })).toBeUndefined();
+    expect(flag("AWS::EC2::Subnet", { DefaultForAz: false })).toBeUndefined();
+    expect(flag("AWS::KMS::Key", { KeyManager: "CUSTOMER" })).toBeUndefined();
+    expect(flag("AWS::IAM::ManagedPolicy", { Arn: "arn:aws:iam::000000000000:policy/Mine" })).toBeUndefined();
+  });
+
+  it("treats the reserved group name as the marker it is", () => {
+    // AWS refuses `default` on create, so a group carrying it is the one AWS
+    // made with the VPC.
+    expect(flag("AWS::EC2::SecurityGroup", { GroupName: "default" })).toBe(true);
+    expect(flag("AWS::EC2::SecurityGroup", { GroupName: "default-web" })).toBeUndefined();
+    expect(flag("AWS::EC2::SecurityGroup", { GroupName: "webSecurityGroup" })).toBeUndefined();
+  });
+
+  it("finds the main route table through its associations", () => {
+    expect(flag("AWS::EC2::RouteTable", { Associations: [{ Main: true }] })).toBe(true);
+    expect(flag("AWS::EC2::RouteTable", { Associations: [{ Main: false }, { Main: true }] })).toBe(true);
+    expect(flag("AWS::EC2::RouteTable", { Associations: [{ Main: false }] })).toBeUndefined();
+    expect(flag("AWS::EC2::RouteTable", {})).toBeUndefined();
+  });
+
+  it("leaves a kind it cannot judge unmarked rather than guessing", () => {
+    // Absent means "not a default, or chant cannot tell". A blanket false would
+    // hide the difference.
+    expect(flag("AWS::EC2::Instance", { InstanceId: "i-1" })).toBeUndefined();
+    expect(canDetectDefault("AWS::EC2::Instance")).toBe(false);
+    expect(canDetectDefault("AWS::EC2::VPC")).toBe(true);
+  });
+
+  it("keeps every attribute it was given", () => {
+    const out = stampProviderDefaults({
+      r: res("AWS::EC2::SecurityGroup", { GroupName: "default", GroupId: "sg-1", region: "us-east-1" }),
+    }).r.attributes;
+    expect(out).toMatchObject({ GroupId: "sg-1", region: "us-east-1", providerDefault: true });
+  });
+
+  it("survives a payload it cannot read", () => {
+    expect(flag("AWS::EC2::RouteTable", { Associations: "not-a-list" })).toBeUndefined();
+  });
+
+  it("reports the kinds it can judge, so a caller need not guess", () => {
+    expect(DEFAULT_AWARE_KINDS).toContain("AWS::EC2::SecurityGroup");
+    expect(DEFAULT_AWARE_KINDS.every(canDetectDefault)).toBe(true);
+  });
+});