@intentius/chant-lexicon-aws 0.29.0 → 0.31.0

package/dist/deep-observe.d.ts

@@ -0,0 +1,101 @@
+/**
+ * AWS deep observation (#1015) — the reference implementation of the epic's
+ * deep-observe contract (#1014).
+ *
+ * `describeResources` reads `cloudformation describe-stack-resources`, which
+ * returns a status, a physical id and a timestamp per resource. That is
+ * CloudFormation's view of the world, and CloudFormation only compares
+ * properties it was told about. A property somebody edited in the console — an
+ * inline policy, a bucket setting, a security-group rule — is invisible to it.
+ * That gap is why go-to-k/cdk-real-drift exists, and it is what this reader
+ * closes: the live resource model comes from the **Cloud Control API**, which
+ * bypasses CloudFormation entirely and returns the resource as the service
+ * actually holds it.
+ *
+ * Correlation is unchanged: Cloud Control is addressed by the physical id that
+ * `describe-stack-resources` already reports per logical id, so the results
+ * line up with the same IR node ids `live-attrs.ts` relies on.
+ *
+ * ## Scope of the first cut
+ *
+ * Four high-signal types (S3 buckets, IAM roles and managed policies, EC2
+ * security groups) rather than all 30+. The point of the first row is to prove
+ * the contract and the noise rules; widening the type table is additive and
+ * needs no contract change. A declared resource of any other type reports
+ * NOT-OBSERVED with `unsupported-kind` — it may well exist, and saying nothing
+ * about it is the only honest answer.
+ *
+ * ## Nothing here talks to real AWS on its own terms
+ *
+ * Every call goes through the runtime adapter's `spawn` and
+ * `applyAwsEndpointArgv`, so `AWS_ENDPOINT_URL` redirects the whole reader at a
+ * local emulator exactly as the existing describe path does.
+ */
+import type { DeepNormalizationHooks, DeepObservationResult } from "@intentius/chant/lexicon";
+/**
+ * CloudFormation types this reader can read live. Each is addressable in Cloud
+ * Control by the physical id CloudFormation already reports.
+ */
+export declare const DEEP_READABLE_TYPES: ReadonlySet<string>;
+/**
+ * Property names that are server-populated wherever they appear — identifiers
+ * the service mints, timestamps it stamps, counters it maintains. Matched on
+ * the final path segment, because AWS repeats these names at every nesting
+ * depth and a per-type list of full paths would be a maintenance trap.
+ *
+ * Deliberately excludes ambiguous names like `Id` and `Name`: `VpcId` and
+ * `BucketName` are declared inputs, and pruning a declared input is how a
+ * normalization pass starts hiding real drift.
+ */
+export declare const AWS_READ_ONLY_NAMES: ReadonlySet<string>;
+/**
+ * Service defaults, per type, as index-erased property paths. A live value
+ * equal to its default is subtracted **only when source never declared that
+ * property** — cdk-real-drift's default subtraction, and the reason
+ * {@link DeepNode.counterpart} exists. Declaring the default explicitly keeps
+ * the property in the diff, so a later change to it still reports.
+ */
+export declare const AWS_SERVICE_DEFAULTS: Record<string, Record<string, unknown>>;
+/**
+ * The aws lexicon's noise rules. The three classes the epic names for AWS —
+ * server-populated fields, unstable ordering (tags, policy statements), and
+ * provider defaults — plus nothing else: a rule that is not one of those is a
+ * rule that hides drift.
+ */
+export declare const awsDeepNormalizationHooks: DeepNormalizationHooks;
+/** One live resource as `cloudcontrol get-resource` returns it. Exported for tests. */
+export interface CloudControlResource {
+    identifier: string;
+    properties: Record<string, unknown>;
+}
+/**
+ * Parse a `cloudcontrol get-resource` payload. Cloud Control returns the model
+ * as a JSON *string* inside the envelope, so this unwraps twice. Returns null
+ * for anything that does not parse to an object — an unparseable body is a
+ * failed read, not an empty resource.
+ */
+export declare function parseCloudControlResource(stdout: string): CloudControlResource | null;
+/** True when the live property tree carries chant's ownership marker tag. */
+export declare function hasOwnershipMarker(properties: Record<string, unknown>): boolean;
+export interface AwsDeepObserveOptions {
+    environment: string;
+    entityNames: string[];
+    entities?: Map<string, {
+        entityType: string;
+        props: Record<string, unknown>;
+    }>;
+    stack?: string;
+    owned?: boolean;
+}
+/**
+ * Read the live property tree for each declared entity via Cloud Control.
+ *
+ * Two reads per run plus one per readable resource: `describe-stack-resources`
+ * resolves logical id → (type, physical id), then `cloudcontrol get-resource`
+ * fetches each model. The first read's failure modes are the thin path's,
+ * verbatim — a stack that does not exist yet is a real absence (nothing is
+ * deployed, so there are no properties to drift), anything else is a hole for
+ * every declared entity.
+ */
+export declare function observeResourcesDeepAws(options: AwsDeepObserveOptions): Promise<DeepObservationResult>;
+//# sourceMappingURL=deep-observe.d.ts.map

package/dist/deep-observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-observe.d.ts","sourceRoot":"","sources":["../src/deep-observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAGV,sBAAsB,EACtB,qBAAqB,EAItB,MAAM,0BAA0B,CAAC;AAKlC;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAKlD,CAAC;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAkBlD,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgBxE,CAAC;AAkBF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,sBAmDvC,CAAC;AAMF,uFAAuF;AACvF,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAuBrF;AASD,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAI/E;AAED,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,qBAAqB,CAAC,CAwHhC"}

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export type { StackOutput } from "@intentius/chant/stack-output";
 export { output, isLexiconOutput } from "@intentius/chant/lexicon-output";
 export type { LexiconOutput } from "@intentius/chant/lexicon-output";
 export { awsPlugin } from "./plugin.js";
+export { observeResourcesDeepAws, awsDeepNormalizationHooks, parseCloudControlResource, hasOwnershipMarker, DEEP_READABLE_TYPES, AWS_READ_ONLY_NAMES, AWS_SERVICE_DEFAULTS, } from "./deep-observe.js";
 export { Sub, Ref, GetAtt, If, Join, Select, Split, Base64, GetAZs, SubIntrinsic, RefIntrinsic, GetAttIntrinsic, IfIntrinsic, JoinIntrinsic, SelectIntrinsic, SplitIntrinsic, Base64Intrinsic, GetAZsIntrinsic, } from "./intrinsics.js";
 export { AWS, StackName, Region, AccountId, StackId, URLSuffix, NoValue, NotificationARNs, Partition, } from "./pseudo.js";
 export * from "./generated/index.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/integrity.json

@@ -1,8 +1,8 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "eac9b0bddda5b4b10352c04ef292ce7f707f72d7b9fe74a06426331963c8c8c8",
-    "meta.json": "8d6445b7ea5f7803c83cf49daab639b1df66388c1512f466b888b0ad57f60a9a",
+    "manifest.json": "cf84a41274c51c53a2433ad0b20af2dc274b62432ee74de735eb0334df6030e7",
+    "meta.json": "0f5a9d9dc16e57fc2fcc56b7c6e9a50d2f75a3d9c76c5934a4024df0be86f3dc",
     "types/index.d.ts": "da899ff303a18a7fdb270570bce784703283d4081f806e69ac8c9dfd4bac7c50",
     "rules/hardcoded-region.ts": "5a0eaf7ab391231fe6cd51426ece29539cb4b36f31c8dd060956638fed55722a",
     "rules/iam-wildcard.ts": "135d7217d278fef50939e605c5da32603ba35674b8c4b5c4d66a06c77903e945",
@@ -59,5 +59,5 @@
     "skills/chant-aws-eks.md": "8789255709ff004ad0a875fd5999edcdc66fc6e33d710db058d9f42703bcfdfe",
     "skills/chant-aws-carve-terraform.md": "f4c6fe1c702250665f90d82b3bdaba5ea50ae75e380a8ae321dad6eb1c39683e"
   },
-  "composite": "46d41420d193e652b241c1388259670efee2423e1a8026507cd1fd5b2d5175a4"
+  "composite": "5a065810934f3fec09337e1d85137ad4317c44638978a32862baf80b499d48bd"
 }

package/dist/manifest.json

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

package/dist/meta.json

@@ -63656,6 +63656,12 @@
         "pattern": "[0-9]*.[0-9]*.[0-9]*",
         "minLength": 0,
         "maxLength": 16
+      },
+      "CreationTime": {
+        "format": "date-time"
+      },
+      "LastModifiedTime": {
+        "format": "date-time"
       }
     },
     "createOnly": [

package/dist/plugin.d.ts

@@ -1,8 +1,7 @@
 import type { LexiconPlugin } from "@intentius/chant/lexicon";
-/** True when a CloudFormation CLI error means the stack simply isn't there yet
- * (`ValidationError … does not exist`) — the pre-first-apply state, which live
- * queries should treat as "nothing deployed", not a failure. Exported for testing. */
-export declare function stackDoesNotExist(stderr: string): boolean;
+/** Re-exported from ./stack-errors so the long-standing import path (and its
+ * tests) keep working now that the deep reader shares the classifier. */
+export { stackDoesNotExist } from "./stack-errors.js";
 /**
  * AWS CloudFormation lexicon plugin.
  *

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,EAAkI,MAAM,0BAA0B,CAAC;AAwB9L;;sFAEsF;AACtF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,aAyyBvB,CAAC"}
+{"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;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,aAk0BvB,CAAC"}

package/dist/stack-errors.d.ts

@@ -0,0 +1,13 @@
+/**
+ * CloudFormation CLI error classification, shared by every live read path.
+ *
+ * Lives in its own module (rather than in ./plugin.ts, where it started) so the
+ * deep reader (#1015) can classify the same failure the same way without
+ * importing the plugin that imports it. ./plugin.ts re-exports it, so the
+ * original import path is unchanged.
+ */
+/** True when a CloudFormation CLI error means the stack simply isn't there yet
+ * (`ValidationError … does not exist`) — the pre-first-apply state, which live
+ * queries should treat as "nothing deployed", not a failure. */
+export declare function stackDoesNotExist(stderr: string): boolean;
+//# sourceMappingURL=stack-errors.d.ts.map

package/dist/stack-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack-errors.d.ts","sourceRoot":"","sources":["../src/stack-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;gEAEgE;AAChE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEzD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-aws",
-  "version": "0.29.0",
+  "version": "0.31.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.29.0",
+    "@intentius/chant": "^0.31.0",
     "typescript": "^5.9.3"
   }
 }

package/src/deep-observe.test.ts

@@ -0,0 +1,484 @@
+/**
+ * AWS deep observation (#1015) — the reference row of the deep-observe contract
+ * (#1014).
+ *
+ * Every AWS interaction here is a mocked `spawn`. Nothing constructs a client,
+ * reads ambient credentials, or reaches a network: the reader's only edge is
+ * the runtime adapter, and it is replaced wholesale below.
+ */
+import { describe, test, expect, vi, beforeEach } from "vitest";
+
+// Partial mock (`importOriginal`) for the same reason lifecycle-integration.test.ts
+// uses one: this module is reachable from other real exports the plugin path
+// touches, so replacing it wholesale breaks things unrelated to `spawn`.
+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 { awsPlugin } = await import("./plugin");
+const {
+  observeResourcesDeepAws,
+  awsDeepNormalizationHooks,
+  parseCloudControlResource,
+  hasOwnershipMarker,
+} = await import("./deep-observe");
+const { deepDiffForLexicon } = await import("@intentius/chant/lifecycle/deep-observe");
+const { normalizeDeepObservation, normalizeDeepProperties } = await import("@intentius/chant/deep-observation");
+
+const ok = (stdout: string) => ({ stdout, stderr: "", exitCode: 0 });
+const fail = (stderr: string) => ({ stdout: "", stderr, exitCode: 255 });
+
+/** A `cloudcontrol get-resource` envelope — 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(
+    JSON.stringify({
+      StackResources: rows.map(([LogicalResourceId, ResourceType, PhysicalResourceId]) => ({
+        LogicalResourceId,
+        ResourceType,
+        PhysicalResourceId,
+        ResourceStatus: "CREATE_COMPLETE",
+        Timestamp: "2026-01-01T00:00:00Z",
+      })),
+    }),
+  );
+
+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 argvOf = (call: unknown[]): string[] => call[0] as string[];
+
+describe("parseCloudControlResource", () => {
+  test("unwraps the doubly-encoded model", () => {
+    expect(parseCloudControlResource(cloudControl("b", { BucketName: "b" }).stdout)).toEqual({
+      identifier: "b",
+      properties: { BucketName: "b" },
+    });
+  });
+
+  test("an unparseable body is a failed read, not an empty resource", () => {
+    expect(parseCloudControlResource("not json")).toBeNull();
+    expect(parseCloudControlResource(JSON.stringify({ ResourceDescription: {} }))).toBeNull();
+    expect(
+      parseCloudControlResource(JSON.stringify({ ResourceDescription: { Properties: "{oops" } })),
+    ).toBeNull();
+  });
+});
+
+describe("the aws noise rules", () => {
+  test("prunes server-populated names wherever they appear", () => {
+    const out = normalizeDeepProperties(
+      { Arn: "arn:aws:s3:::b", BucketName: "b", Nested: { RegionalDomainName: "x", Keep: 1 } },
+      { entityType: "AWS::S3::Bucket", side: "live", hooks: awsDeepNormalizationHooks },
+    );
+    expect(out).toEqual({ BucketName: "b", Nested: { Keep: 1 } });
+  });
+
+  test("canonicalizes tag order", () => {
+    const out = normalizeDeepProperties(
+      { Tags: [{ Key: "team", Value: "b" }, { Key: "env", Value: "a" }] },
+      { entityType: "AWS::S3::Bucket", side: "live", hooks: awsDeepNormalizationHooks },
+    );
+    expect(out.Tags).toEqual([{ Key: "env", Value: "a" }, { Key: "team", Value: "b" }]);
+  });
+
+  test("canonicalizes policy statement and action order", () => {
+    const out = normalizeDeepProperties(
+      {
+        PolicyDocument: {
+          Statement: [
+            { Sid: "Write", Action: ["s3:PutObject", "s3:DeleteObject"] },
+            { Sid: "Read", Action: ["s3:GetObject"] },
+          ],
+        },
+      },
+      { entityType: "AWS::IAM::ManagedPolicy", side: "live", hooks: awsDeepNormalizationHooks },
+    );
+    const statements = (out.PolicyDocument as { Statement: Array<{ Sid: string; Action: string[] }> }).Statement;
+    expect(statements.map((s) => s.Sid)).toEqual(["Read", "Write"]);
+    expect(statements[1].Action).toEqual(["s3:DeleteObject", "s3:PutObject"]);
+  });
+
+  test("subtracts a service default only where source is silent about the property", () => {
+    const declaredNothing = normalizeDeepProperties(
+      { Path: "/", MaxSessionDuration: 3600, RoleName: "r" },
+      {
+        entityType: "AWS::IAM::Role",
+        side: "live",
+        hooks: awsDeepNormalizationHooks,
+        counterpartPaths: new Set(["RoleName"]),
+      },
+    );
+    expect(declaredNothing).toEqual({ RoleName: "r" });
+
+    const declaredPath = normalizeDeepProperties(
+      { Path: "/", RoleName: "r" },
+      {
+        entityType: "AWS::IAM::Role",
+        side: "live",
+        hooks: awsDeepNormalizationHooks,
+        counterpartPaths: new Set(["Path", "RoleName"]),
+      },
+    );
+    expect(declaredPath).toEqual({ Path: "/", RoleName: "r" });
+  });
+
+  test("a one-sided pass never subtracts defaults — the reader has no declared tree yet", () => {
+    const out = normalizeDeepProperties(
+      { Path: "/", RoleName: "r" },
+      { entityType: "AWS::IAM::Role", side: "live", hooks: awsDeepNormalizationHooks },
+    );
+    expect(out).toEqual({ Path: "/", RoleName: "r" });
+  });
+});
+
+describe("hasOwnershipMarker", () => {
+  test("reads chant's tag out of the live tree", () => {
+    expect(hasOwnershipMarker({ Tags: [{ Key: "chant:managed-by", Value: "chant" }] })).toBe(true);
+    expect(hasOwnershipMarker({ Tags: [{ Key: "env", Value: "prod" }] })).toBe(false);
+    expect(hasOwnershipMarker({})).toBe(false);
+  });
+});
+
+describe("observeResourcesDeepAws", () => {
+  beforeEach(() => {
+    // A bare arrow returning the mock would register the mock itself as
+    // vitest's cleanup hook, and vitest would then call it with no arguments.
+    spawnMock.mockReset();
+  });
+
+  test("reads each resource through cloudcontrol, honoring AWS_ENDPOINT_URL", async () => {
+    const previous = process.env.AWS_ENDPOINT_URL;
+    process.env.AWS_ENDPOINT_URL = "http://127.0.0.1:5566";
+    try {
+      spawnMock.mockImplementation((argv: string[]) =>
+        Promise.resolve(
+          argv.includes("describe-stack-resources")
+            ? stackResources([["Assets", "AWS::S3::Bucket", "acme-assets"]])
+            : cloudControl("acme-assets", { BucketName: "acme-assets" }),
+        ),
+      );
+      const result = normalizeDeepObservation(
+        await observeResourcesDeepAws({ environment: "prod", entityNames: ["Assets"] }),
+      );
+      expect(result.resources.Assets.properties).toEqual({ BucketName: "acme-assets" });
+      expect(result.resources.Assets.physicalId).toBe("acme-assets");
+      for (const call of spawnMock.mock.calls) {
+        expect(argvOf(call)).toContain("--endpoint-url");
+        expect(argvOf(call)).toContain("http://127.0.0.1:5566");
+      }
+    } finally {
+      if (previous === undefined) delete process.env.AWS_ENDPOINT_URL;
+      else process.env.AWS_ENDPOINT_URL = previous;
+    }
+  });
+
+  test("a type with no reader is unsupported-kind, never absent", async () => {
+    spawnMock.mockResolvedValue(stackResources([["Queue", "AWS::SQS::Queue", "q-1"]]));
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepAws({ environment: "prod", entityNames: ["Queue"] }),
+    );
+    expect(result.resources).toEqual({});
+    expect(result.unobserved.Queue.reason).toBe("unsupported-kind");
+  });
+
+  test("an expired token on the deep read is no-credentials, per resource", async () => {
+    spawnMock.mockImplementation((argv: string[]) =>
+      Promise.resolve(
+        argv.includes("describe-stack-resources")
+          ? stackResources([["Assets", "AWS::S3::Bucket", "acme-assets"]])
+          : fail("An error occurred (ExpiredToken) when calling GetResource: The security token expired"),
+      ),
+    );
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepAws({ environment: "prod", entityNames: ["Assets"] }),
+    );
+    expect(result.unobserved.Assets.reason).toBe("no-credentials");
+    expect(result.resources).toEqual({});
+  });
+
+  test("a stack that does not exist yet is a real absence — no properties, no holes", async () => {
+    spawnMock.mockResolvedValue(fail("An error occurred (ValidationError): Stack with id prod does not exist"));
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepAws({ environment: "prod", entityNames: ["Assets"] }),
+    );
+    expect(result).toEqual({ resources: {}, unobserved: {} });
+  });
+
+  test("any other stack-read failure is a hole for every declared entity", async () => {
+    spawnMock.mockResolvedValue(fail("Could not connect to the endpoint URL"));
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepAws({ environment: "prod", entityNames: ["A", "B"] }),
+    );
+    expect(Object.keys(result.unobserved)).toEqual(["A", "B"]);
+    expect(result.unobserved.A.reason).toBe("read-failed");
+  });
+
+  test("--owned withholds an unmarked resource as `filtered`, not as absent", async () => {
+    spawnMock.mockImplementation((argv: string[]) =>
+      Promise.resolve(
+        argv.includes("describe-stack-resources")
+          ? stackResources([
+              ["Ours", "AWS::S3::Bucket", "ours"],
+              ["Theirs", "AWS::S3::Bucket", "theirs"],
+            ])
+          : argv.includes("ours")
+            ? cloudControl("ours", { BucketName: "ours", Tags: [{ Key: "chant:managed-by", Value: "chant" }] })
+            : cloudControl("theirs", { BucketName: "theirs" }),
+      ),
+    );
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepAws({ environment: "prod", entityNames: ["Ours", "Theirs"], owned: true }),
+    );
+    expect(Object.keys(result.resources)).toEqual(["Ours"]);
+    expect(result.unobserved.Theirs.reason).toBe("filtered");
+  });
+
+  test("secret-bearing properties are masked before they reach the tree", async () => {
+    spawnMock.mockImplementation((argv: string[]) =>
+      Promise.resolve(
+        argv.includes("describe-stack-resources")
+          ? stackResources([["Role", "AWS::IAM::Role", "app-role"]])
+          : cloudControl("app-role", { RoleName: "app-role", ClientSecret: "s3cr3t" }),
+      ),
+    );
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepAws({ environment: "prod", entityNames: ["Role"] }),
+    );
+    expect(result.resources.Role.properties.ClientSecret).toBe("[REDACTED]");
+    expect(JSON.stringify(result)).not.toContain("s3cr3t");
+  });
+
+  test("a multi-stack project reads the stack it was handed", async () => {
+    spawnMock.mockResolvedValue(stackResources([]));
+    await observeResourcesDeepAws({ environment: "prod", entityNames: ["A"], stack: "payments-prod" });
+    expect(argvOf(spawnMock.mock.calls[0])).toContain("payments-prod");
+  });
+});
+
+/**
+ * The acceptance test for #1015: the real plugin, a mutated live tree, a
+ * baseline, and exactly the genuine drift.
+ */
+describe("end to end: declared + mutated live + baseline (#1015)", () => {
+  beforeEach(() => {
+    // A bare arrow returning the mock would register the mock itself as
+    // vitest's cleanup hook, and vitest would then call it with no arguments.
+    spawnMock.mockReset();
+  });
+
+  const declared = entities({
+    // Declared with two tags and versioning on.
+    Assets: {
+      entityType: "AWS::S3::Bucket",
+      props: {
+        BucketName: "acme-assets",
+        VersioningConfiguration: { Status: "Enabled" },
+        Tags: [
+          { Key: "env", Value: "prod" },
+          { Key: "team", Value: "payments" },
+        ],
+      },
+    },
+    // Declared with two statements, in source order.
+    AppRole: {
+      entityType: "AWS::IAM::Role",
+      props: {
+        RoleName: "app-role",
+        AssumeRolePolicyDocument: {
+          Version: "2012-10-17",
+          Statement: [
+            { Sid: "Ec2", Effect: "Allow", Action: ["sts:AssumeRole"] },
+            { Sid: "Ci", Effect: "Allow", Action: ["sts:AssumeRole", "sts:TagSession"] },
+          ],
+        },
+      },
+    },
+    // No Cloud Control reader for this type.
+    Jobs: { entityType: "AWS::SQS::Queue", props: { QueueName: "jobs" } },
+    // The deep read of this one fails outright.
+    Perimeter: { entityType: "AWS::EC2::SecurityGroup", props: { GroupDescription: "perimeter" } },
+  });
+
+  const wireMocks = (): void => {
+    spawnMock.mockImplementation((argv: string[]) => {
+      if (argv.includes("describe-stack-resources")) {
+        return Promise.resolve(
+          stackResources([
+            ["Assets", "AWS::S3::Bucket", "acme-assets"],
+            ["AppRole", "AWS::IAM::Role", "app-role"],
+            ["Jobs", "AWS::SQS::Queue", "jobs"],
+            ["Perimeter", "AWS::EC2::SecurityGroup", "sg-01"],
+          ]),
+        );
+      }
+      if (argv.includes("acme-assets")) {
+        return Promise.resolve(
+          cloudControl("acme-assets", {
+            BucketName: "acme-assets",
+            // GENUINE: somebody turned versioning off in the console.
+            VersioningConfiguration: { Status: "Suspended" },
+            // NOISE: tags come back in a different order …
+            Tags: [
+              { Key: "team", Value: "payments" },
+              // … and with one the platform team adds to every bucket.
+              { Key: "cost-center", Value: "platform" },
+              { Key: "env", Value: "prod" },
+            ],
+            // NOISE: server-populated.
+            Arn: "arn:aws:s3:::acme-assets",
+            RegionalDomainName: "acme-assets.s3.us-east-1.amazonaws.com",
+          }),
+        );
+      }
+      if (argv.includes("app-role")) {
+        return Promise.resolve(
+          cloudControl("app-role", {
+            RoleName: "app-role",
+            // NOISE: statements and actions in a different order than source.
+            AssumeRolePolicyDocument: {
+              Version: "2012-10-17",
+              Statement: [
+                { Sid: "Ci", Effect: "Allow", Action: ["sts:TagSession", "sts:AssumeRole"] },
+                { Sid: "Ec2", Effect: "Allow", Action: ["sts:AssumeRole"] },
+              ],
+            },
+            // NOISE: provider defaults nobody declared.
+            Path: "/",
+            MaxSessionDuration: 3600,
+            // NOISE: server-populated.
+            Arn: "arn:aws:iam::111122223333:role/app-role",
+            RoleId: "AROAEXAMPLE",
+            CreateDate: "2026-01-01T00:00:00Z",
+          }),
+        );
+      }
+      if (argv.includes("sg-01")) {
+        return Promise.resolve(fail("An error occurred (ThrottlingException) when calling GetResource"));
+      }
+      return Promise.resolve(fail("unexpected call"));
+    });
+  };
+
+  const baseline = {
+    Assets: {
+      type: "AWS::S3::Bucket",
+      accepted: [
+        { path: "Tags[#cost-center].Key", value: "cost-center" },
+        { path: "Tags[#cost-center].Value", value: "platform" },
+      ],
+    },
+  };
+
+  test("exactly the genuine drift surfaces; noise, defaults and the accepted tag do not", async () => {
+    wireMocks();
+    const result = await deepDiffForLexicon(awsPlugin, {
+      environment: "prod",
+      buildOutput: "",
+      entities: declared,
+      baseline,
+    });
+
+    // One finding, one property: the console-flipped versioning setting.
+    expect(result.drifted).toEqual([
+      {
+        name: "Assets",
+        type: "AWS::S3::Bucket",
+        changes: [
+          {
+            path: "VersioningConfiguration.Status",
+            kind: "changed",
+            declared: "Enabled",
+            live: "Suspended",
+          },
+        ],
+      },
+    ]);
+
+    // The role is clean: reordering, defaults and server-populated fields are
+    // all subtracted.
+    expect(result.unchanged).toEqual(["AppRole"]);
+
+    // The platform team's tag is accepted, so it is reported as suppressed
+    // rather than as drift.
+    expect(result.accepted.map((e) => e.name)).toEqual(["Assets"]);
+    expect(result.accepted[0].changes.map((c) => c.path)).toEqual([
+      "Tags[#cost-center].Key",
+      "Tags[#cost-center].Value",
+    ]);
+
+    // An unreadable deep read is a hole with a reason — never silence, never
+    // noise, and never a create.
+    expect(result.unobserved).toEqual([
+      {
+        name: "Jobs",
+        type: "AWS::SQS::Queue",
+        reason: "unsupported-kind",
+        detail: "no deep reader for AWS::SQS::Queue — Cloud Control coverage is opt-in per type",
+      },
+      {
+        name: "Perimeter",
+        type: "AWS::EC2::SecurityGroup",
+        reason: "read-failed",
+        detail:
+          'cloudcontrol get-resource failed for AWS::EC2::SecurityGroup "sg-01": An error occurred (ThrottlingException) when calling GetResource',
+      },
+    ]);
+  });
+
+  test("without the baseline the platform tag is drift, and accepting it is what silences it", async () => {
+    wireMocks();
+    const result = await deepDiffForLexicon(awsPlugin, {
+      environment: "prod",
+      buildOutput: "",
+      entities: declared,
+    });
+    const assets = result.drifted.find((d) => d.name === "Assets");
+    expect(assets?.changes.map((c) => c.path).sort()).toEqual([
+      "Tags[#cost-center].Key",
+      "Tags[#cost-center].Value",
+      "VersioningConfiguration.Status",
+    ]);
+    expect(result.accepted).toEqual([]);
+  });
+
+  test("an accepted value that later changes is drift again, with all three axes", async () => {
+    wireMocks();
+    const result = await deepDiffForLexicon(awsPlugin, {
+      environment: "prod",
+      buildOutput: "",
+      entities: declared,
+      baseline: {
+        Assets: {
+          accepted: [{ path: "Tags[#cost-center].Value", value: "someone-elses-team" }],
+        },
+      },
+    });
+    const change = result.drifted
+      .find((d) => d.name === "Assets")
+      ?.changes.find((c) => c.path === "Tags[#cost-center].Value");
+    expect(change).toEqual({
+      path: "Tags[#cost-center].Value",
+      kind: "undeclared",
+      live: "platform",
+      baseline: "someone-elses-team",
+    });
+  });
+
+  test("a whole-lexicon failure is a hole for every declared entity, not a clean report", async () => {
+    spawnMock.mockResolvedValue(fail("Unable to locate credentials"));
+    const result = await deepDiffForLexicon(awsPlugin, {
+      environment: "prod",
+      buildOutput: "",
+      entities: declared,
+    });
+    expect(result.drifted).toEqual([]);
+    expect(result.unobserved.map((u) => u.name).sort()).toEqual(["AppRole", "Assets", "Jobs", "Perimeter"]);
+    expect(new Set(result.unobserved.map((u) => u.reason))).toEqual(new Set(["no-credentials"]));
+  });
+});

package/src/deep-observe.ts

@@ -0,0 +1,384 @@
+/**
+ * AWS deep observation (#1015) — the reference implementation of the epic's
+ * deep-observe contract (#1014).
+ *
+ * `describeResources` reads `cloudformation describe-stack-resources`, which
+ * returns a status, a physical id and a timestamp per resource. That is
+ * CloudFormation's view of the world, and CloudFormation only compares
+ * properties it was told about. A property somebody edited in the console — an
+ * inline policy, a bucket setting, a security-group rule — is invisible to it.
+ * That gap is why go-to-k/cdk-real-drift exists, and it is what this reader
+ * closes: the live resource model comes from the **Cloud Control API**, which
+ * bypasses CloudFormation entirely and returns the resource as the service
+ * actually holds it.
+ *
+ * Correlation is unchanged: Cloud Control is addressed by the physical id that
+ * `describe-stack-resources` already reports per logical id, so the results
+ * line up with the same IR node ids `live-attrs.ts` relies on.
+ *
+ * ## Scope of the first cut
+ *
+ * Four high-signal types (S3 buckets, IAM roles and managed policies, EC2
+ * security groups) rather than all 30+. The point of the first row is to prove
+ * the contract and the noise rules; widening the type table is additive and
+ * needs no contract change. A declared resource of any other type reports
+ * NOT-OBSERVED with `unsupported-kind` — it may well exist, and saying nothing
+ * about it is the only honest answer.
+ *
+ * ## Nothing here talks to real AWS on its own terms
+ *
+ * Every call goes through the runtime adapter's `spawn` and
+ * `applyAwsEndpointArgv`, so `AWS_ENDPOINT_URL` redirects the whole reader at a
+ * local emulator exactly as the existing describe path does.
+ */
+
+import type {
+  DeepArrayElement,
+  DeepNode,
+  DeepNormalizationHooks,
+  DeepObservationResult,
+  DeepResourceObservation,
+  UnobservedEntity,
+  UnobservedReason,
+} from "@intentius/chant/lexicon";
+import { applyAwsEndpointArgv } from "./components/cloud-executor";
+import { stackDoesNotExist } from "./stack-errors";
+import { AWS_TAG_OWNERSHIP_KEYS } from "./ownership";
+
+/**
+ * CloudFormation types this reader can read live. Each is addressable in Cloud
+ * Control by the physical id CloudFormation already reports.
+ */
+export const DEEP_READABLE_TYPES: ReadonlySet<string> = new Set([
+  "AWS::S3::Bucket",
+  "AWS::IAM::Role",
+  "AWS::IAM::ManagedPolicy",
+  "AWS::EC2::SecurityGroup",
+]);
+
+/**
+ * Property names that are server-populated wherever they appear — identifiers
+ * the service mints, timestamps it stamps, counters it maintains. Matched on
+ * the final path segment, because AWS repeats these names at every nesting
+ * depth and a per-type list of full paths would be a maintenance trap.
+ *
+ * Deliberately excludes ambiguous names like `Id` and `Name`: `VpcId` and
+ * `BucketName` are declared inputs, and pruning a declared input is how a
+ * normalization pass starts hiding real drift.
+ */
+export const AWS_READ_ONLY_NAMES: ReadonlySet<string> = new Set([
+  "Arn",
+  "RoleId",
+  "PolicyId",
+  "GroupId",
+  "OwnerId",
+  "AttachmentCount",
+  "PermissionsBoundaryUsageCount",
+  "DefaultVersionId",
+  "IsAttachable",
+  "CreateDate",
+  "CreationDate",
+  "UpdateDate",
+  "LastModified",
+  "LastModifiedTime",
+  "DualStackDomainName",
+  "RegionalDomainName",
+  "WebsiteURL",
+]);
+
+/**
+ * Service defaults, per type, as index-erased property paths. A live value
+ * equal to its default is subtracted **only when source never declared that
+ * property** — cdk-real-drift's default subtraction, and the reason
+ * {@link DeepNode.counterpart} exists. Declaring the default explicitly keeps
+ * the property in the diff, so a later change to it still reports.
+ */
+export const AWS_SERVICE_DEFAULTS: Record<string, Record<string, unknown>> = {
+  "AWS::S3::Bucket": {
+    "VersioningConfiguration.Status": "Suspended",
+    "AccelerateConfiguration.AccelerationStatus": "Suspended",
+    "ObjectLockEnabled": false,
+  },
+  "AWS::IAM::Role": {
+    "Path": "/",
+    "MaxSessionDuration": 3600,
+  },
+  "AWS::IAM::ManagedPolicy": {
+    "Path": "/",
+  },
+  "AWS::EC2::SecurityGroup": {
+    "GroupDescription": "default VPC security group",
+  },
+};
+
+/** Stable JSON with sorted keys — the fallback ordering key for a set-like array. */
+function canonicalJson(value: unknown): string {
+  return JSON.stringify(value, (_k, v: unknown) =>
+    v && typeof v === "object" && !Array.isArray(v)
+      ? Object.fromEntries(Object.entries(v as Record<string, unknown>).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+      : v,
+  ) ?? "";
+}
+
+/** The final segment of an index-erased pattern (`Policies[].PolicyName` → `PolicyName`). */
+function lastSegment(pattern: string): string {
+  const withoutIndex = pattern.replace(/\[\]$/, "");
+  const dot = withoutIndex.lastIndexOf(".");
+  return dot === -1 ? withoutIndex : withoutIndex.slice(dot + 1);
+}
+
+/**
+ * The aws lexicon's noise rules. The three classes the epic names for AWS —
+ * server-populated fields, unstable ordering (tags, policy statements), and
+ * provider defaults — plus nothing else: a rule that is not one of those is a
+ * rule that hides drift.
+ */
+export const awsDeepNormalizationHooks: DeepNormalizationHooks = {
+  prune(node: DeepNode): boolean {
+    // Read-only / server-populated. Pruned on both sides: if source somehow
+    // declares an arn-shaped output, comparing it to the live one is still
+    // meaningless.
+    if (AWS_READ_ONLY_NAMES.has(lastSegment(node.pattern))) return true;
+
+    // Provider defaults, on the live side only, and only where source is silent
+    // about the property. `"unknown"` (a one-sided normalization) never prunes:
+    // the reader must not decide this before the declared tree is in hand.
+    if (node.side !== "live" || node.counterpart !== "absent") return false;
+    const defaults = AWS_SERVICE_DEFAULTS[node.entityType];
+    if (!defaults) return false;
+    if (!Object.prototype.hasOwnProperty.call(defaults, node.pattern)) return false;
+    return defaults[node.pattern] === node.value;
+  },
+
+  /**
+   * The key doubles as a path segment (`Tags[#env].Value`), so it is the
+   * element's own identity where AWS gives one — a tag key, a statement Sid, an
+   * action string — and canonical JSON only as a fallback.
+   */
+  orderKey(element: DeepArrayElement): string | undefined {
+    const name = lastSegment(element.pattern);
+    const el = element.element;
+
+    // Tags are a set. AWS returns them in whatever order it likes, and a
+    // reordered tag list is the single loudest false positive in a raw diff.
+    if (name === "Tags") {
+      const key = isRecord(el) ? el.Key : undefined;
+      return typeof key === "string" ? key : canonicalJson(el);
+    }
+
+    // IAM policy statements are a set, and so are the Action/Resource lists
+    // inside them. `Sid` is the natural identity when the author gave one.
+    if (name === "Statement") {
+      const sid = isRecord(el) ? el.Sid : undefined;
+      return typeof sid === "string" ? sid : canonicalJson(el);
+    }
+    if (name === "Action" || name === "NotAction" || name === "Resource" || name === "NotResource") {
+      return typeof el === "string" ? el : canonicalJson(el);
+    }
+
+    // Security-group rules are a set — the console appends, chant declares in
+    // source order, and neither order means anything to EC2.
+    if (name === "SecurityGroupIngress" || name === "SecurityGroupEgress" || name === "IpRanges") {
+      return canonicalJson(el);
+    }
+
+    return undefined;
+  },
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** One live resource as `cloudcontrol get-resource` returns it. Exported for tests. */
+export interface CloudControlResource {
+  identifier: string;
+  properties: Record<string, unknown>;
+}
+
+/**
+ * Parse a `cloudcontrol get-resource` payload. Cloud Control returns the model
+ * as a JSON *string* inside the envelope, so this unwraps twice. Returns null
+ * for anything that does not parse to an object — an unparseable body is a
+ * failed read, not an empty resource.
+ */
+export function parseCloudControlResource(stdout: string): CloudControlResource | null {
+  let envelope: unknown;
+  try {
+    envelope = JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+  if (!isRecord(envelope)) return null;
+  const description = envelope.ResourceDescription;
+  if (!isRecord(description)) return null;
+  const raw = description.Properties;
+  if (typeof raw !== "string") return null;
+  let properties: unknown;
+  try {
+    properties = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!isRecord(properties)) return null;
+  return {
+    identifier: typeof description.Identifier === "string" ? description.Identifier : "",
+    properties,
+  };
+}
+
+/** Classify a failed AWS CLI call the same way the thin read does. */
+function classifyFailure(stderr: string): UnobservedReason {
+  return /credential|token|expired|AccessDenied|not authorized|UnauthorizedOperation/i.test(stderr)
+    ? "no-credentials"
+    : "read-failed";
+}
+
+/** True when the live property tree carries chant's ownership marker tag. */
+export function hasOwnershipMarker(properties: Record<string, unknown>): boolean {
+  const tags = properties.Tags;
+  if (!Array.isArray(tags)) return false;
+  return tags.some((t) => isRecord(t) && t.Key === AWS_TAG_OWNERSHIP_KEYS.managedBy);
+}
+
+export interface AwsDeepObserveOptions {
+  environment: string;
+  entityNames: string[];
+  entities?: Map<string, { entityType: string; props: Record<string, unknown> }>;
+  stack?: string;
+  owned?: boolean;
+}
+
+/**
+ * Read the live property tree for each declared entity via Cloud Control.
+ *
+ * Two reads per run plus one per readable resource: `describe-stack-resources`
+ * resolves logical id → (type, physical id), then `cloudcontrol get-resource`
+ * fetches each model. The first read's failure modes are the thin path's,
+ * verbatim — a stack that does not exist yet is a real absence (nothing is
+ * deployed, so there are no properties to drift), anything else is a hole for
+ * every declared entity.
+ */
+export async function observeResourcesDeepAws(
+  options: AwsDeepObserveOptions,
+): Promise<DeepObservationResult> {
+  const { getRuntime } = await import("@intentius/chant/runtime-adapter");
+  const { deepObservation, normalizeDeepProperties } = await import("@intentius/chant/deep-observation");
+  const { unobservedAll } = await import("@intentius/chant/observation");
+  const rt = getRuntime();
+
+  const stackName = options.stack ?? options.environment;
+  const endpoint = process.env.AWS_ENDPOINT_URL;
+
+  const listResult = await rt.spawn(applyAwsEndpointArgv([
+    "aws", "cloudformation", "describe-stack-resources",
+    "--stack-name", stackName,
+    "--output", "json",
+  ], endpoint));
+
+  if (listResult.exitCode !== 0) {
+    if (stackDoesNotExist(listResult.stderr)) return deepObservation({});
+    return deepObservation(
+      {},
+      unobservedAll(
+        options.entityNames,
+        classifyFailure(listResult.stderr),
+        `describe-stack-resources failed for stack "${stackName}": ${listResult.stderr.trim().split("\n")[0] ?? ""}`,
+      ),
+    );
+  }
+
+  let stackResources: Array<{ LogicalResourceId: string; ResourceType: string; PhysicalResourceId?: string }> = [];
+  try {
+    const parsed = JSON.parse(listResult.stdout) as {
+      StackResources?: Array<{ LogicalResourceId: string; ResourceType: string; PhysicalResourceId?: string }>;
+    };
+    stackResources = parsed.StackResources ?? [];
+  } catch {
+    return deepObservation(
+      {},
+      unobservedAll(options.entityNames, "read-failed", `unparseable describe-stack-resources output for stack "${stackName}"`),
+    );
+  }
+
+  const byLogicalId = new Map(stackResources.map((r) => [r.LogicalResourceId, r]));
+  const resources: Record<string, DeepResourceObservation> = {};
+  const unobserved: Record<string, UnobservedEntity> = {};
+
+  for (const entityName of options.entityNames) {
+    const stackResource = byLogicalId.get(entityName);
+    // Not in the stack at all. The thin read reports that absence; restating it
+    // here as a property hole would turn one finding into two.
+    if (!stackResource) continue;
+
+    const type = stackResource.ResourceType;
+    if (!DEEP_READABLE_TYPES.has(type)) {
+      unobserved[entityName] = {
+        type,
+        reason: "unsupported-kind",
+        detail: `no deep reader for ${type} — Cloud Control coverage is opt-in per type`,
+      };
+      continue;
+    }
+    const identifier = stackResource.PhysicalResourceId;
+    if (!identifier) {
+      unobserved[entityName] = {
+        type,
+        reason: "read-failed",
+        detail: "the stack reports no physical id, so the live resource cannot be addressed",
+      };
+      continue;
+    }
+
+    const getResult = await rt.spawn(applyAwsEndpointArgv([
+      "aws", "cloudcontrol", "get-resource",
+      "--type-name", type,
+      "--identifier", identifier,
+      "--output", "json",
+    ], endpoint));
+
+    if (getResult.exitCode !== 0) {
+      unobserved[entityName] = {
+        type,
+        reason: classifyFailure(getResult.stderr),
+        detail: `cloudcontrol get-resource failed for ${type} "${identifier}": ${getResult.stderr.trim().split("\n")[0] ?? ""}`,
+      };
+      continue;
+    }
+
+    const parsed = parseCloudControlResource(getResult.stdout);
+    if (!parsed) {
+      unobserved[entityName] = {
+        type,
+        reason: "read-failed",
+        detail: `unparseable cloudcontrol get-resource output for ${type} "${identifier}"`,
+      };
+      continue;
+    }
+
+    // Cloud Control *does* return tags, so unlike the thin path this one can
+    // answer the ownership question (#1015's open note). A resource withheld by
+    // the filter is `filtered`, never absent: it exists, it just isn't chant's.
+    const owned = hasOwnershipMarker(parsed.properties);
+    if (options.owned && !owned) {
+      unobserved[entityName] = {
+        type,
+        reason: "filtered",
+        detail: `live resource carries no ${AWS_TAG_OWNERSHIP_KEYS.managedBy} tag`,
+      };
+      continue;
+    }
+
+    resources[entityName] = {
+      type,
+      physicalId: identifier,
+      properties: normalizeDeepProperties(parsed.properties, {
+        entityType: type,
+        side: "live",
+        hooks: awsDeepNormalizationHooks,
+      }),
+    };
+  }
+
+  return deepObservation(resources, unobserved);
+}

package/src/generated/lexicon-aws.json

@@ -63656,6 +63656,12 @@
         "pattern": "[0-9]*.[0-9]*.[0-9]*",
         "minLength": 0,
         "maxLength": 16
+      },
+      "CreationTime": {
+        "format": "date-time"
+      },
+      "LastModifiedTime": {
+        "format": "date-time"
       }
     },
     "createOnly": [

package/src/index.ts

@@ -25,6 +25,18 @@ export type { LexiconOutput } from "@intentius/chant/lexicon-output";
 // Plugin
 export { awsPlugin } from "./plugin";
 
+// Deep observation (#1015): the Cloud Control reader and the noise rules it
+// shares with core's normalization pass.
+export {
+  observeResourcesDeepAws,
+  awsDeepNormalizationHooks,
+  parseCloudControlResource,
+  hasOwnershipMarker,
+  DEEP_READABLE_TYPES,
+  AWS_READ_ONLY_NAMES,
+  AWS_SERVICE_DEFAULTS,
+} from "./deep-observe";
+
 // Intrinsics
 export {
   Sub,

package/src/plugin.ts

@@ -1,6 +1,6 @@
 import { createRequire } from "module";
 import { detectTemplate } from "./detect";
-import type { LexiconPlugin, IntrinsicDef, ObservationResult, ResourceMetadata, ExportedTemplate, ResourceSelector, InitTemplateSet, StackStatusObservation } from "@intentius/chant/lexicon";
+import type { LexiconPlugin, IntrinsicDef, ObservationResult, DeepObservationResult, ResourceMetadata, ExportedTemplate, ResourceSelector, InitTemplateSet, StackStatusObservation } from "@intentius/chant/lexicon";
 const require = createRequire(import.meta.url);
 import type { LintRule } from "@intentius/chant/lint/rule";
 import type { TemplateParser } from "@intentius/chant/import/parser";
@@ -16,6 +16,8 @@ import { fileURLToPath } from "url";
 import { awsSerializer } from "./serializer";
 import { FLOCI_EMULATOR } from "./op/activities/floci";
 import { applyAwsEndpointArgv } from "./components/cloud-executor";
+import { stackDoesNotExist } from "./stack-errors";
+import { awsDeepNormalizationHooks, observeResourcesDeepAws } from "./deep-observe";
 import { awsReferenceCatalog } from "./reference-catalog";
 import { resolveTemplateAttrs } from "./live-attrs";
 import { CFParser } from "./import/parser";
@@ -24,12 +26,9 @@ import { parseStackTemplate } from "./import/live-export";
 import { awsCompletions } from "./lsp/completions";
 import { awsHover } from "./lsp/hover";
 
-/** True when a CloudFormation CLI error means the stack simply isn't there yet
- * (`ValidationError … does not exist`) — the pre-first-apply state, which live
- * queries should treat as "nothing deployed", not a failure. Exported for testing. */
-export function stackDoesNotExist(stderr: string): boolean {
-  return /does not exist/i.test(stderr);
-}
+/** Re-exported from ./stack-errors so the long-standing import path (and its
+ * tests) keep working now that the deep reader shares the classifier. */
+export { stackDoesNotExist } from "./stack-errors";
 
 /**
  * AWS CloudFormation lexicon plugin.
@@ -657,6 +656,31 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
     return observation(resources);
   },
 
+  /**
+   * Property-level live read (#1015) via the Cloud Control API — past
+   * CloudFormation's view of the world, into the resource as the service
+   * actually holds it. Implementation in ./deep-observe.ts.
+   */
+  async observeResourcesDeep(options: {
+    environment: string;
+    buildOutput: string;
+    entityNames: string[];
+    entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+    stack?: string;
+    owned?: boolean;
+  }): Promise<DeepObservationResult> {
+    return observeResourcesDeepAws({
+      environment: options.environment,
+      entityNames: options.entityNames,
+      entities: options.entities,
+      stack: options.stack,
+      owned: options.owned,
+    });
+  },
+
+  /** The noise rules the deep pass applies to both the live and declared trees. */
+  deepNormalizationHooks: awsDeepNormalizationHooks,
+
   async describeStackStatus(options: { environment: string; stack: string }): Promise<StackStatusObservation | null> {
     const { getRuntime } = await import("@intentius/chant/runtime-adapter");
     const rt = getRuntime();

package/src/stack-errors.ts

@@ -0,0 +1,15 @@
+/**
+ * CloudFormation CLI error classification, shared by every live read path.
+ *
+ * Lives in its own module (rather than in ./plugin.ts, where it started) so the
+ * deep reader (#1015) can classify the same failure the same way without
+ * importing the plugin that imports it. ./plugin.ts re-exports it, so the
+ * original import path is unchanged.
+ */
+
+/** True when a CloudFormation CLI error means the stack simply isn't there yet
+ * (`ValidationError … does not exist`) — the pre-first-apply state, which live
+ * queries should treat as "nothing deployed", not a failure. */
+export function stackDoesNotExist(stderr: string): boolean {
+  return /does not exist/i.test(stderr);
+}