@intentius/chant-lexicon-aws 0.34.0 → 0.37.0

package/src/generated/index.d.ts

@@ -32891,6 +32891,27 @@ export declare class ServiceProfile {
   readonly LoRaWAN_UlRatePolicy: string;
 }
 
+export declare class ServiceSetting {
+  constructor(props: {
+    /** The ID of the service setting, such as /ssm/parameter-store/high-throughput-enabled. */
+    SettingId: string;
+    /** The value of the service setting. */
+    SettingValue: string;
+    /** The ARN of the service setting. */
+    Arn?: string;
+    /** The last time the service setting was modified. */
+    LastModifiedDate?: string;
+    /** The ARN of the last modified user. */
+    LastModifiedUser?: string;
+    /** The status of the service setting. The value can be Default, Customized or PendingUpdate. */
+    Status?: string;
+  }, attributes?: CFResourceAttributes);
+  readonly Arn: string;
+  readonly LastModifiedDate: string;
+  readonly LastModifiedUser: string;
+  readonly Status: string;
+}
+
 export declare class ServiceTemplate {
   constructor(props: {
     /** <p>The Amazon Resource Name (ARN) of the service template.</p> */

package/src/generated/index.ts

@@ -1356,6 +1356,7 @@ export const ServiceNetworkServiceAssociation = createResource("AWS::VpcLattice:
 export const ServiceNetworkVpcAssociation = createResource("AWS::VpcLattice::ServiceNetworkVpcAssociation", "aws", {"Arn":"Arn","CreatedAt":"CreatedAt","Id":"Id","ServiceNetworkArn":"ServiceNetworkArn","ServiceNetworkId":"ServiceNetworkId","ServiceNetworkName":"ServiceNetworkName","Status":"Status","VpcId":"VpcId"});
 export const ServicePrincipalName = createResource("AWS::PCAConnectorAD::ServicePrincipalName", "aws", {});
 export const ServiceProfile = createResource("AWS::IoTWireless::ServiceProfile", "aws", {"Id":"Id","Arn":"Arn","LoRaWAN_UlRate":"LoRaWAN.UlRate","LoRaWAN_UlBucketSize":"LoRaWAN.UlBucketSize","LoRaWAN_UlRatePolicy":"LoRaWAN.UlRatePolicy","LoRaWAN_DlRate":"LoRaWAN.DlRate","LoRaWAN_DlBucketSize":"LoRaWAN.DlBucketSize","LoRaWAN_DlRatePolicy":"LoRaWAN.DlRatePolicy","LoRaWAN_DevStatusReqFreq":"LoRaWAN.DevStatusReqFreq","LoRaWAN_ReportDevStatusBattery":"LoRaWAN.ReportDevStatusBattery","LoRaWAN_ReportDevStatusMargin":"LoRaWAN.ReportDevStatusMargin","LoRaWAN_DrMin":"LoRaWAN.DrMin","LoRaWAN_DrMax":"LoRaWAN.DrMax","LoRaWAN_ChannelMask":"LoRaWAN.ChannelMask","LoRaWAN_HrAllowed":"LoRaWAN.HrAllowed","LoRaWAN_NwkGeoLoc":"LoRaWAN.NwkGeoLoc","LoRaWAN_TargetPer":"LoRaWAN.TargetPer","LoRaWAN_MinGwDiversity":"LoRaWAN.MinGwDiversity"});
+export const ServiceSetting = createResource("AWS::SSM::ServiceSetting", "aws", {"Status":"Status","LastModifiedDate":"LastModifiedDate","LastModifiedUser":"LastModifiedUser","Arn":"Arn"});
 export const ServiceTemplate = createResource("AWS::Proton::ServiceTemplate", "aws", {"Arn":"Arn"});
 export const SESConfigurationSet = createResource("AWS::SES::ConfigurationSet", "aws", {});
 export const SESConfigurationSetEventDestination = createResource("AWS::SES::ConfigurationSetEventDestination", "aws", {"Id":"Id"});

package/src/generated/lexicon-aws.json

@@ -91208,6 +91208,36 @@
     "kind": "property",
     "lexicon": "aws"
   },
+  "ServiceSetting": {
+    "resourceType": "AWS::SSM::ServiceSetting",
+    "kind": "resource",
+    "lexicon": "aws",
+    "attrs": {
+      "Status": "Status",
+      "LastModifiedDate": "LastModifiedDate",
+      "LastModifiedUser": "LastModifiedUser",
+      "Arn": "Arn"
+    },
+    "propertyConstraints": {
+      "SettingId": {
+        "minLength": 1,
+        "maxLength": 1000
+      },
+      "SettingValue": {
+        "minLength": 1,
+        "maxLength": 4096
+      },
+      "LastModifiedDate": {
+        "format": "date-time"
+      }
+    },
+    "createOnly": [
+      "SettingId"
+    ],
+    "primaryIdentifier": [
+      "Arn"
+    ]
+  },
   "ServiceSoftwareOptions": {
     "resourceType": "AWS::OpenSearchService::Domain.ServiceSoftwareOptions",
     "kind": "property",

package/src/index.ts

@@ -30,13 +30,30 @@ export { awsPlugin } from "./plugin";
 export {
   observeResourcesDeepAws,
   awsDeepNormalizationHooks,
-  parseCloudControlResource,
   hasOwnershipMarker,
   DEEP_READABLE_TYPES,
   AWS_READ_ONLY_NAMES,
   AWS_SERVICE_DEFAULTS,
 } from "./deep-observe";
 
+// The native read transport (#1206) — the applier's own transport, pointed at
+// CloudFormation Query and Cloud Control. `parseCloudControlResource` used to
+// live in ./deep-observe and parsed AWS CLI stdout; the reader no longer speaks
+// that wire format, so `parseResourceDescription` (which takes the API's own
+// `ResourceDescription` object) replaces it.
+export {
+  describeStackResources,
+  describeStackOutputs,
+  getResource,
+  listResources,
+  parseResourceDescription,
+  AwsReadError,
+  type AwsReadHttp,
+  type AwsReadClientOptions,
+  type CloudControlDescription,
+  type StackResource,
+} from "./api/read-client";
+
 // Intrinsics
 export {
   Sub,

package/src/lifecycle-integration.test.ts

@@ -6,7 +6,7 @@
  * cloud edge (the runtime adapter's spawn) mocked. Proves the seam between core
  * and a real lexicon — not a `createMockPlugin` fixture.
  */
-import { describe, test, expect, vi, beforeEach } from "vitest";
+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
 import { mkdtempSync, rmSync, readdirSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -40,8 +40,47 @@ const liveTemplate = {
 
 const ok = (stdout: string) => ({ stdout, stderr: "", exitCode: 0 });
 
+/* The stack reads moved off the CLI onto the CloudFormation Query protocol
+ * (#1206), so they are stubbed at `fetch` rather than at `spawn`. The paths
+ * still on the CLI — `describeStackStatus`, `exportResources`, and the
+ * per-kind property reads — keep using `spawnMock` below. */
+
+const stackResourcesXml = (rows: Array<{ logicalId: string; type: string; physicalId: string }>) =>
+  `<DescribeStackResourcesResponse><StackResources>${rows
+    .map(
+      (r) =>
+        `<member><LogicalResourceId>${r.logicalId}</LogicalResourceId><ResourceType>${r.type}</ResourceType>` +
+        `<PhysicalResourceId>${r.physicalId}</PhysicalResourceId><ResourceStatus>CREATE_COMPLETE</ResourceStatus>` +
+        `<Timestamp>2026-01-01T00:00:00Z</Timestamp></member>`,
+    )
+    .join("")}</StackResources></DescribeStackResourcesResponse>`;
+
+const stackOutputsXml = (outputs: Record<string, string> = {}) =>
+  `<DescribeStacksResponse><Outputs>${Object.entries(outputs)
+    .map(([k, v]) => `<member><OutputKey>${k}</OutputKey><OutputValue>${v}</OutputValue></member>`)
+    .join("")}</Outputs></DescribeStacksResponse>`;
+
+const queryErrorXml = (code: string, message: string) =>
+  `<ErrorResponse><Error><Code>${code}</Code><Message>${message}</Message></Error></ErrorResponse>`;
+
+/** Route a CloudFormation Query call by its `Action`, and answer as CFN would. */
+const stubCfn = (route: (action: string) => { status?: number; text: string }): void => {
+  vi.spyOn(globalThis, "fetch").mockImplementation((async (_url: string, init: { body: string }) => {
+    const action = new URLSearchParams(init.body).get("Action") ?? "";
+    const res = route(action);
+    return { status: res.status ?? 200, text: () => Promise.resolve(res.text) };
+  }) as unknown as typeof fetch);
+};
+
+/** The whole-stack refusal both the credentials and the missing-stack cases use. */
+const stubCfnError = (code: string, message: string): void =>
+  stubCfn(() => ({ status: 400, text: queryErrorXml(code, message) }));
+
 describe("aws lifecycle integration (#163)", () => {
   beforeEach(() => spawnMock.mockReset());
+  // A `fetch` stub left standing would serve the next test's stack read, which
+  // is how a credentials case can come back looking healthy.
+  afterEach(() => vi.restoreAllMocks());
 
   test("live-import driver: real exportResources → IR → generated source", async () => {
     spawnMock.mockResolvedValue(ok(JSON.stringify({ TemplateBody: liveTemplate })));
@@ -65,27 +104,11 @@ describe("aws lifecycle integration (#163)", () => {
   });
 
   test("changeset path: real describeResources → buildChangeSet verdicts", async () => {
-    // describe-stack-resources then describe-stacks.
-    spawnMock.mockImplementation((argv?: string[]) => {
-      if (argv?.includes("describe-stack-resources")) {
-        return Promise.resolve(
-          ok(
-            JSON.stringify({
-              StackResources: [
-                {
-                  LogicalResourceId: "MyBucket",
-                  ResourceType: "AWS::S3::Bucket",
-                  PhysicalResourceId: "my-bucket",
-                  ResourceStatus: "CREATE_COMPLETE",
-                  Timestamp: "2026-01-01T00:00:00Z",
-                },
-              ],
-            }),
-          ),
-        );
-      }
-      return Promise.resolve(ok(JSON.stringify({ Stacks: [{ Outputs: [] }] })));
-    });
+    stubCfn((action) =>
+      action === "DescribeStackResources"
+        ? { text: stackResourcesXml([{ logicalId: "MyBucket", type: "AWS::S3::Bucket", physicalId: "my-bucket" }]) }
+        : { text: stackOutputsXml() },
+    );
 
     const { resources: observedNow } = normalizeObservation(
       await awsPlugin.describeResources!({
@@ -96,7 +119,7 @@ describe("aws lifecycle integration (#163)", () => {
       }),
     );
     expect(observedNow.MyBucket?.type).toBe("AWS::S3::Bucket");
-    // Ownership verdicts are total (#1089): describe-stack-resources carries no
+    // Ownership verdicts are total (#1089): DescribeStackResources carries no
     // tags, so the verdict is an explicit `unknown`, not a missing field.
     expect(observedNow.MyBucket?.ownership).toBe("unknown");
 
@@ -160,7 +183,7 @@ describe("aws lifecycle integration (#163)", () => {
    * NOT-OBSERVED, and that survives describe → plan → component status.
    */
   test("tri-state chain: a failed stack read stays unobserved through describe → plan → status (#1089)", async () => {
-    spawnMock.mockResolvedValue({ stdout: "", stderr: "Unable to locate credentials", exitCode: 255 });
+    stubCfnError("AccessDenied", "Unable to locate credentials");
 
     const observed = normalizeObservation(
       await awsPlugin.describeResources!({
@@ -190,7 +213,7 @@ describe("aws lifecycle integration (#163)", () => {
   });
 
   test("a stack that does not exist is a real absence — every declared entity is a create", async () => {
-    spawnMock.mockResolvedValue({ stdout: "", stderr: "ValidationError: Stack with id prod does not exist", exitCode: 255 });
+    stubCfnError("ValidationError", "Stack with id prod does not exist");
 
     const observed = normalizeObservation(
       await awsPlugin.describeResources!({
@@ -222,7 +245,7 @@ describeObservationConformance({
       declared: ["MyBucket", "MyQueue"],
       expectUnobserved: ["MyBucket", "MyQueue"],
       run: () => {
-        spawnMock.mockResolvedValue({ stdout: "", stderr: "Unable to locate credentials", exitCode: 255 });
+        stubCfnError("AccessDenied", "Unable to locate credentials");
         return awsPlugin.describeResources!({
           environment: "prod",
           buildOutput: "",
@@ -236,7 +259,7 @@ describeObservationConformance({
       declared: ["MyBucket"],
       expectAbsent: ["MyBucket"],
       run: () => {
-        spawnMock.mockResolvedValue({ stdout: "", stderr: "ValidationError: Stack with id prod does not exist", exitCode: 255 });
+        stubCfnError("ValidationError", "Stack with id prod does not exist");
         return awsPlugin.describeResources!({
           environment: "prod",
           buildOutput: "",
@@ -250,24 +273,10 @@ describeObservationConformance({
       declared: ["MyBucket"],
       expectPresent: ["MyBucket"],
       run: () => {
-        spawnMock.mockImplementation((argv?: string[]) =>
-          Promise.resolve(
-            argv?.includes("describe-stack-resources")
-              ? ok(
-                  JSON.stringify({
-                    StackResources: [
-                      {
-                        LogicalResourceId: "MyBucket",
-                        ResourceType: "AWS::S3::Bucket",
-                        PhysicalResourceId: "my-bucket",
-                        ResourceStatus: "CREATE_COMPLETE",
-                        Timestamp: "2026-01-01T00:00:00Z",
-                      },
-                    ],
-                  }),
-                )
-              : ok(JSON.stringify({ Stacks: [{ Outputs: [] }] })),
-          ),
+        stubCfn((action) =>
+          action === "DescribeStackResources"
+            ? { text: stackResourcesXml([{ logicalId: "MyBucket", type: "AWS::S3::Bucket", physicalId: "my-bucket" }]) }
+            : { text: stackOutputsXml() },
         );
         return awsPlugin.describeResources!({
           environment: "prod",

package/src/plugin.ts

@@ -17,10 +17,17 @@ import { awsSerializer } from "./serializer";
 import { FLOCI_EMULATOR } from "./op/activities/floci";
 import { applyAwsEndpointArgv } from "./components/cloud-executor";
 import { stackDoesNotExist } from "./stack-errors";
+import {
+  AwsReadError,
+  describeStackOutputs,
+  describeStackResources,
+  type AwsReadClientOptions,
+  type StackResource,
+} from "./api/read-client";
 import { awsDeepNormalizationHooks, observeResourcesDeepAws } from "./deep-observe";
 import { awsReferenceCatalog } from "./reference-catalog";
 import { AMBIENT_KINDS } from "./ambient";
-import { describeOwnProperties, stampRegion } from "./properties";
+import { canDescribe, describeOwnProperties, stampRegion } from "./properties";
 import { stampProviderDefaults } from "./defaults";
 import { resolveTemplateAttrs } from "./live-attrs";
 import { CFParser } from "./import/parser";
@@ -541,12 +548,14 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
     region?: string;
     owned?: boolean;
   }): Promise<ObservationResult> {
-    const { getRuntime } = await import("@intentius/chant/runtime-adapter");
     const { observation, unobservedAll } = await import("@intentius/chant/observation");
-    const rt = getRuntime();
     const resources: Record<string, ResourceMetadata> = {};
-    // Multi-region estates: target this stack's region, not the ambient one.
-    const regionArgs = options.region ? ["--region", options.region] : [];
+    // The applier's own transport, pointed at the read APIs (#1206). Multi-region
+    // estates target this stack's region, not the ambient one.
+    const client: AwsReadClientOptions = {
+      ...(process.env.AWS_ENDPOINT_URL ? { endpoint: process.env.AWS_ENDPOINT_URL } : {}),
+      ...(options.region ? { region: options.region } : {}),
+    };
 
     if (options.owned) {
       // describe-stack-resources does not return tags, so ownership cannot be
@@ -569,29 +578,26 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
     // single-stack convention is the stack named after the environment (#932).
     const stackName = options.stack ?? `${options.environment}`;
 
-    // Describe stack resources. Inject --endpoint-url from AWS_ENDPOINT_URL so a
+    // Describe stack resources. The endpoint override rides the client, so a
     // local emulator (Floci) is observed instead of real AWS (#926) — behold
     // serve --local relies on this for the overlay.
-    const listResult = await rt.spawn(applyAwsEndpointArgv([
-      "aws", "cloudformation", "describe-stack-resources",
-      "--stack-name", stackName,
-      ...regionArgs,
-      "--output", "json",
-    ], process.env.AWS_ENDPOINT_URL));
-
-    if (listResult.exitCode !== 0) {
+    let stackResources: StackResource[];
+    try {
+      stackResources = await describeStackResources(stackName, client);
+    } catch (err) {
       // A stack that doesn't exist yet is the pre-first-apply state: nothing is
       // deployed for this env, so there are no live resources (every declared
       // resource is "pending") — not an error. That is a real absence, so the
       // empty result is the honest one and `create` is the right proposal.
-      if (stackDoesNotExist(listResult.stderr)) {
+      if (err instanceof AwsReadError && stackDoesNotExist(err.message)) {
         return observation(resources);
       }
       // Any other failure (credentials, throttling, a region that can't be
       // reached) establishes nothing about what is deployed. Reporting every
       // declared entity as NOT-OBSERVED (#1089) is what keeps a broken read
       // from arriving downstream as "none of this exists".
-      const reason = /credential|token|expired|AccessDenied|not authorized|UnauthorizedOperation/i.test(listResult.stderr)
+      const detail = err instanceof AwsReadError && err.code ? `${err.code}: ${err.message}` : String(err instanceof Error ? err.message : err);
+      const reason = /credential|token|expired|AccessDenied|not authorized|Unauthorized/i.test(detail)
         ? "no-credentials"
         : "read-failed";
       return observation(
@@ -599,45 +605,22 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
         unobservedAll(
           options.entityNames,
           reason,
-          `describe-stack-resources failed for stack "${stackName}": ${listResult.stderr.trim().split("\n")[0] ?? ""}`,
+          `DescribeStackResources failed for stack "${stackName}": ${detail}`,
         ),
       );
     }
 
-    const data = JSON.parse(listResult.stdout) as {
-      StackResources: Array<{
-        LogicalResourceId: string;
-        ResourceType: string;
-        PhysicalResourceId: string;
-        ResourceStatus: string;
-        Timestamp: string;
-      }>;
-    };
-
     // Map logical names from build to stack resources
-    const stackResourceMap = new Map<string, typeof data.StackResources[0]>();
-    for (const r of data.StackResources) {
-      stackResourceMap.set(r.LogicalResourceId, r);
-    }
-
-    // Get stack outputs
-    const describeResult = await rt.spawn(applyAwsEndpointArgv([
-      "aws", "cloudformation", "describe-stacks",
-      "--stack-name", stackName,
-      ...regionArgs,
-      "--output", "json",
-    ], process.env.AWS_ENDPOINT_URL));
+    const stackResourceMap = new Map(stackResources.map((r) => [r.logicalId, r]));
 
+    // Get stack outputs. A stack whose resources read fine but whose outputs do
+    // not is still a usable observation, so this failure is swallowed exactly as
+    // the non-zero exit code used to be.
     let stackOutputs: Record<string, string> = {};
-    if (describeResult.exitCode === 0) {
-      const stacks = JSON.parse(describeResult.stdout) as {
-        Stacks: Array<{ Outputs?: Array<{ OutputKey: string; OutputValue: string }> }>;
-      };
-      if (stacks.Stacks[0]?.Outputs) {
-        for (const o of stacks.Stacks[0].Outputs) {
-          stackOutputs[o.OutputKey] = o.OutputValue;
-        }
-      }
+    try {
+      stackOutputs = await describeStackOutputs(stackName, client);
+    } catch {
+      stackOutputs = {};
     }
 
     for (const entityName of options.entityNames) {
@@ -655,10 +638,10 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
       }
 
       resources[entityName] = {
-        type: stackResource.ResourceType,
-        physicalId: stackResource.PhysicalResourceId,
-        status: stackResource.ResourceStatus,
-        lastUpdated: stackResource.Timestamp,
+        type: stackResource.type,
+        physicalId: stackResource.physicalId ?? "",
+        status: stackResource.status ?? "",
+        lastUpdated: stackResource.timestamp ?? "",
         // Total verdict (#1089): describe-stack-resources returns no tags, so
         // this path cannot read the ownership marker. Say `unknown` explicitly
         // rather than leaving the field off and letting each consumer guess —
@@ -671,9 +654,37 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
     // Each resource's OWN properties, on top of the stack outputs above (#1279).
     // Until this, a node's `attrs` were the stack's exports replicated onto
     // every member, so no instance carried its own `VpcId`.
-    const withProperties = stampProviderDefaults(
-      stampRegion(await describeOwnProperties(resources, options.region), options.region),
-    );
+    const own = await describeOwnProperties(resources, options.region);
+    const withProperties = stampProviderDefaults(stampRegion(own.resources, options.region));
+
+    // The own-property read is still a CLI shell-out while the stack reads are
+    // not (#1206), so the two halves can now fail independently. When the
+    // enrichment could not run at all, the resources it would have described are
+    // identified but not described — and `lifecycle diff` compares these
+    // attributes, so presenting them anyway reports every previously-recorded
+    // property as removed. That is a failed read arriving as drift, which is the
+    // shape #1089 exists to prevent, so say it is a hole instead.
+    const undescribed = own.transportFailed
+      ? Object.keys(withProperties).filter((name) => canDescribe(withProperties[name].type))
+      : [];
+    if (undescribed.length > 0) {
+      const described: Record<string, ResourceMetadata> = {};
+      for (const [name, meta] of Object.entries(withProperties)) {
+        if (!undescribed.includes(name)) described[name] = meta;
+      }
+      // Attribute each hole to the call that failed for *its* kind, rather than
+      // to whichever call happened to fail first.
+      const holes: Record<string, { type: string; reason: "read-failed"; detail: string }> = {};
+      for (const name of undescribed) {
+        const type = withProperties[name].type;
+        holes[name] = {
+          type,
+          reason: "read-failed",
+          detail: `the stack was read, but this resource's own properties were not — ${own.failures.get(type) ?? "the describe call failed"}`,
+        };
+      }
+      return observation(described, holes);
+    }
 
     // Every entity the stack answered for was answered for: an entity the
     // template doesn't carry is genuinely not in this stack, which is an

package/src/properties.test.ts

@@ -29,7 +29,7 @@ describe("describeOwnProperties (#1279)", () => {
 
   it("joins each resource's own properties back by physical id", async () => {
     spawnMock.mockResolvedValue(ok(reservations(instance("i-1", "vpc-a"), instance("i-2", "vpc-b"))));
-    const merged = await describeOwnProperties(observed);
+    const { resources: merged } = await describeOwnProperties(observed);
     expect(merged.web.attributes?.VpcId).toBe("vpc-a");
     expect(merged.api.attributes?.VpcId).toBe("vpc-b");
   });
@@ -50,7 +50,7 @@ describe("describeOwnProperties (#1279)", () => {
       },
     };
     spawnMock.mockResolvedValue(ok(reservations(instance("i-1", "vpc-a"))));
-    const merged = await describeOwnProperties(withOutputs);
+    const { resources: merged } = await describeOwnProperties(withOutputs);
     expect(merged.web.attributes?.expVpcId).toBe("vpc-exported");
     expect(merged.web.attributes?.VpcId).toBe("vpc-a");
   });
@@ -64,19 +64,52 @@ describe("describeOwnProperties (#1279)", () => {
       .mockResolvedValueOnce(fail) // the batch, killed by i-2
       .mockResolvedValueOnce(ok(reservations(instance("i-1", "vpc-a"))))
       .mockResolvedValueOnce(fail); // i-2 really is gone
-    const merged = await describeOwnProperties(observed);
+    const { resources: merged } = await describeOwnProperties(observed);
     expect(merged.web.attributes?.VpcId).toBe("vpc-a");
     expect(merged.api.attributes).toBeUndefined();
   });
 
   it("leaves the observation untouched when the kind cannot be read at all", async () => {
     spawnMock.mockResolvedValue(fail);
-    const merged = await describeOwnProperties({ web: observed.web });
+    const { resources: merged } = await describeOwnProperties({ web: observed.web });
     expect(merged.web.attributes).toBeUndefined();
   });
 
+  // #1206: these attributes are compared by `lifecycle diff`, so a read that
+  // fails after the resource is already identified reports every recorded
+  // property as removed. The caller can only avoid that if the failure is told.
+  it("reports a total failure, so a caller can call it a hole rather than thin data", async () => {
+    spawnMock.mockResolvedValue({ stdout: "", stderr: "spawn aws ENOENT", exitCode: 127 });
+    const result = await describeOwnProperties({ web: observed.web });
+    expect(result.transportFailed).toBe(true);
+    expect(result.failures.get("AWS::EC2::Instance")).toContain("ec2 describe-instances");
+    expect(result.failures.get("AWS::EC2::Instance")).toContain("ENOENT");
+  });
+
+  it("a per-id retry that fails for every id is a failed kind, not an empty one", async () => {
+    // The batch dies, then so does every retry. Before #1206 the retry path
+    // replaced the null with `[]`, which read as "the account has nothing".
+    spawnMock.mockResolvedValue(fail);
+    const result = await describeOwnProperties(observed);
+    expect(result.transportFailed).toBe(true);
+  });
+
+  it("a kind that answers keeps the pass best-effort, even when another fails", async () => {
+    // One kind readable, one not: still detail-loss, not a hole. Only a total
+    // failure changes the caller's verdict.
+    spawnMock.mockImplementation((argv?: string[]) =>
+      Promise.resolve(argv?.includes("describe-instances") ? ok(reservations(instance("i-1", "vpc-a"))) : fail),
+    );
+    const result = await describeOwnProperties({
+      web: observed.web,
+      net: { type: "AWS::EC2::Subnet", status: "OK", physicalId: "subnet-1" },
+    });
+    expect(result.transportFailed).toBe(false);
+    expect(result.resources.web.attributes?.VpcId).toBe("vpc-a");
+  });
+
   it("does not call out for a kind it cannot describe", async () => {
-    const merged = await describeOwnProperties({
+    const { resources: merged } = await describeOwnProperties({
       fn: { type: "AWS::Lambda::Function", status: "OK", physicalId: "fn-1" },
     });
     expect(spawnMock).not.toHaveBeenCalled();

package/src/properties.ts

@@ -86,20 +86,37 @@ export function canDescribe(kind: string): boolean {
   return kind in DESCRIBE;
 }
 
+/** What an enrichment pass managed to do, so a caller can tell a miss from a no-op. */
+export interface OwnPropertiesResult {
+  resources: Record<string, ResourceMetadata>;
+  /**
+   * True when enrichment was attempted and *every* kind's read failed — the
+   * transport is unavailable rather than the account being quiet. Callers must
+   * not present the result as a complete observation (#1089).
+   */
+  transportFailed: boolean;
+  /** Why each failed kind failed, keyed by CloudFormation type, so a caller can attribute per resource. */
+  failures: Map<string, string>;
+}
+
 /**
  * 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.
+ * Best-effort per kind: an endpoint that cannot answer `describe-subnets` still
+ * yields instance properties. A miss costs detail — with one exception that used
+ * to be silent and is now reported.
+ *
+ * The exception (#1206): these attributes are compared by `lifecycle diff`, so a
+ * read that fails after the resource is already identified does not degrade to
+ * "less detail", it degrades to *drift* — the snapshot has `GroupId`, the live
+ * read has nothing, and the differ reports the property as removed. A partial
+ * failure still rides the best-effort path, but a total one is a hole the caller
+ * has to declare rather than a thinner set of facts.
  */
 export async function describeOwnProperties(
   resources: Record<string, ResourceMetadata>,
   region?: string,
-): Promise<Record<string, ResourceMetadata>> {
+): Promise<OwnPropertiesResult> {
   // Group the physical ids to look up by kind, so each kind is one call.
   const wanted = new Map<string, Map<string, string[]>>();
   for (const [name, meta] of Object.entries(resources)) {
@@ -108,22 +125,25 @@ export async function describeOwnProperties(
     byId.set(meta.physicalId, [...(byId.get(meta.physicalId) ?? []), name]);
     wanted.set(meta.type, byId);
   }
-  if (wanted.size === 0) return resources;
+  if (wanted.size === 0) return { resources, transportFailed: false, failures: new Map() };
 
   const { getRuntime } = await import("@intentius/chant/runtime-adapter");
   const rt = getRuntime();
   const regionArgs = region ? ["--region", region] : [];
   const merged = { ...resources };
+  const failures = new Map<string, string>();
+  /** The last failure for a kind, phrased for a human — stderr when there is any, the exit status otherwise. */
+  let lastReason = "";
 
   /** One describe for a set of ids. `null` when the call itself failed. */
   const read = async (spec: (typeof DESCRIBE)[string], ids: string[]) => {
-    const result = await rt.spawn(
-      applyAwsEndpointArgv(
-        ["aws", ...spec.argv, spec.idFlag, ...ids, ...regionArgs, "--output", "json"],
-        process.env.AWS_ENDPOINT_URL,
-      ),
-    );
-    if (result.exitCode !== 0) return null;
+    const argv = ["aws", ...spec.argv, spec.idFlag, ...ids, ...regionArgs, "--output", "json"];
+    const result = await rt.spawn(applyAwsEndpointArgv(argv, process.env.AWS_ENDPOINT_URL));
+    if (result.exitCode !== 0) {
+      const stderr = result.stderr.trim().split("\n")[0];
+      lastReason = `${spec.argv.join(" ")} failed${stderr ? `: ${stderr}` : ` (${result.exitCode})`}`;
+      return null;
+    }
     return (JSON.parse(result.stdout)[spec.key] ?? []) as Array<Record<string, unknown>>;
   };
 
@@ -137,10 +157,15 @@ export async function describeOwnProperties(
       // down with it, and the result is indistinguishable from "the account has
       // nothing to say". Retry one at a time so the damage stops at the bad id.
       if (top === null && ids.length > 1) {
-        top = [];
-        for (const id of ids) top.push(...((await read(spec, [id])) ?? []));
+        const perId = await Promise.all(ids.map((id) => read(spec, [id])));
+        // Every retry failing is the kind failing, not the kind being empty —
+        // the distinction the old `top = []` erased.
+        top = perId.every((r) => r === null) ? null : perId.flatMap((r) => r ?? []);
+      }
+      if (top === null) {
+        failures.set(kind, lastReason);
+        continue;
       }
-      if (top === null) continue;
       // `describe-instances` buries instances one level down under reservations;
       // the others return the resources directly.
       const rows = spec.nested
@@ -158,9 +183,10 @@ export async function describeOwnProperties(
           };
         }
       }
-    } catch {
-      continue;
+    } catch (err) {
+      failures.set(kind, `${spec.argv.join(" ")} failed: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
-  return merged;
+
+  return { resources: merged, transportFailed: failures.size === wanted.size, failures };
 }