@intentius/chant 0.34.1 → 0.37.0

package/src/cli/handlers/graph.test.ts

@@ -572,6 +572,67 @@ describe("runGraph", () => {
       expect((opts as { owned: boolean }).owned).toBe(true);
     });
 
+    // #1158: a project that declares its stacks in `ChantConfig.stacks` — rather
+    // than deriving them from `*.component.ts` — must observe each declared
+    // stack, the same contract `resolveStackTargets` gives lifecycle
+    // snapshot/diff. Every other test here passes `stacks: []`, so without this
+    // the declared-stack path is implemented and unguarded.
+    test("ChantConfig.stacks: observeResources gets every declared stack, with its region and src", async () => {
+      resolveLexMock.mockResolvedValue(["aws"]);
+      loadPluginsMock.mockResolvedValue([
+        { name: "aws", serializer: {}, describeResources: () => Promise.resolve({}) },
+      ]);
+      loadChantConfigMock.mockResolvedValue({
+        config: {
+          stacks: [
+            { name: "estate-east", region: "us-east-1", src: "east/src" },
+            { name: "estate-west", region: "us-west-2", src: "west/src" },
+          ],
+        },
+      });
+      observeMock.mockResolvedValue({ observations: [], errors: [], warnings: [] });
+      const exit = await runGraph({ args: makeArgs({ format: "ir", live: true, env: "prod" }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      expect(observeMock).toHaveBeenCalledTimes(1);
+      const [, , , opts] = observeMock.mock.calls[0];
+      // The region/src carry through — a multi-region estate observes each
+      // stack in its own region, not all of them in the ambient default.
+      expect((opts as { stacks: Array<{ name: string; region?: string; src?: string }> }).stacks).toEqual([
+        { name: "estate-east", region: "us-east-1", src: "east/src" },
+        { name: "estate-west", region: "us-west-2", src: "west/src" },
+      ]);
+    });
+
+    // A stack can be both component-derived and declared. It must be observed
+    // once — `describeResources` is a live API call per stack, so a duplicate
+    // is a wasted round trip and a doubled node set to reconcile.
+    test("ChantConfig.stacks: a stack also derived from a component is not observed twice", async () => {
+      resolveLexMock.mockResolvedValue(["aws"]);
+      loadPluginsMock.mockResolvedValue([
+        { name: "aws", serializer: {}, describeResources: () => Promise.resolve({}) },
+      ]);
+      discoverComponentsMock.mockResolvedValue({
+        errors: [],
+        sourceFiles: [],
+        components: new Map([
+          ["loom-db", { component: { name: "loom-db", dependsOn: [], deploy: [
+            { phase: "deploy", steps: [{ kind: "cfn-deploy", stack: "shared-estate" }] },
+          ] }, exportName: "loomDb", filePath: "components/loom-db.component.ts" }],
+        ]),
+      });
+      loadChantConfigMock.mockResolvedValue({
+        config: { stacks: [{ name: "shared-estate" }, { name: "estate-west" }] },
+      });
+      observeMock.mockResolvedValue({ observations: [], errors: [], warnings: [] });
+      const exit = await runGraph({ args: makeArgs({ format: "ir", live: true, env: "prod" }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      const [, , , opts] = observeMock.mock.calls[0];
+      expect((opts as { stacks: Array<{ name: string }> }).stacks.map((s) => s.name)).toEqual([
+        "shared-estate",
+        "estate-west",
+      ]);
+    });
+
     test("component discovery errors: falls back to the single-stack path with a warning", async () => {
       resolveLexMock.mockResolvedValue(["aws"]);
       loadPluginsMock.mockResolvedValue([

package/src/cli/handlers/lifecycle.ts

@@ -273,11 +273,18 @@ export async function runLifecycleRollback(ctx: CommandContext): Promise<number>
   const { config } = await loadChantConfig(resolve("."));
   const sourceDir = config.sourceDir ?? ".";
   try {
-    const result = await rollbackToRevision({ ref, env: environment, sourceDir, cwd: resolve(".") });
+    const result = await rollbackToRevision({ ref, env: environment, sourceDir, cwd: resolve("."), dryRun: args.dryRun });
     if (result.noop) {
       console.error(formatSuccess(`${sourceDir} already matches ${ref} — nothing to roll back`));
       return 0;
     }
+    if (args.dryRun) {
+      // The delta on stdout, so it pipes and diffs like any other patch; the
+      // summary on stderr, matching the PR path's split.
+      process.stdout.write(result.diff ?? "");
+      console.error(formatSuccess(`Rollback delta for ${ref} computed — no PR opened, nothing pushed`));
+      return 0;
+    }
     console.log(result.prUrl); // the PR URL — the consumer (behold) reads this from stdout
     console.error(formatSuccess(`Opened rollback PR on ${result.branch}`));
     return 0;

package/src/cli/main.ts

@@ -211,6 +211,8 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.migrateTo = args[++i];
     } else if (arg === "--emit") {
       result.emit = args[++i];
+    } else if (arg === "--dry-run") {
+      result.dryRun = true;
     } else if (arg === "--strict") {
       result.strict = true;
     } else if (arg === "--validate") {

package/src/cli/registry.ts

@@ -63,6 +63,8 @@ export interface ParsedArgs {
   selectName?: string;
   /** `chant import --owned` — restrict live import to chant-owned resources */
   owned?: boolean;
+  /** `chant lifecycle rollback --dry-run` — compute the rollback delta and print it; open no PR, push nothing, leave no branch. */
+  dryRun?: boolean;
   /** `chant import --verbatim` — keep server-defaulted fields in live import */
   verbatim?: boolean;
   /** `chant lifecycle … --src <dir>` — build root override for lifecycle commands */

package/src/codegen/docs-sections.ts

@@ -95,7 +95,7 @@ export function generateIntrinsics(
     "",
     `The ${config.displayName} lexicon provides **${intrinsics.length}** intrinsic functions.`,
     "",
-    `**Tag?** shows how an intrinsic is authored: a genuine tagged template (\`Sub\\\`...\\\`\`) or a plain function call (\`Ref(...)\`). **Folds?** shows whether [\`chant build --fold\`](/chant/concepts/typescript-as-data/#folded-vs-run) can reduce a use of this intrinsic today, without running the file — generated directly from this lexicon's registration, not restated by hand. A tagged template folds once it is registered. A plain call folds only where this lexicon has opted that intrinsic in one at a time (\`foldsAsCall\`), so a \`No\` in this column means this intrinsic has not been opted in, not that calls in general cannot fold.`,
+    `**Tag?** shows how an intrinsic is authored: a genuine tagged template (\`Sub\\\`...\\\`\`) or a plain function call (\`Ref(...)\`). **Folds?** shows whether [folding](/chant/concepts/typescript-as-data/#folded-vs-run) — the default \`chant build\` path — can reduce a use of this intrinsic today, without running the file — generated directly from this lexicon's registration, not restated by hand. A tagged template folds once it is registered. A plain call folds only where this lexicon has opted that intrinsic in one at a time (\`foldsAsCall\`), so a \`No\` in this column means this intrinsic has not been opted in, not that calls in general cannot fold.`,
     "",
     "| Function | Description | Output Key | Tag? | Folds? |",
     "|----------|-------------|------------|------|--------|",

package/src/codegen/docs.ts

@@ -7,7 +7,7 @@
  * (service grouping, resource type URLs, custom overview content).
  */
 
-import { copyFileSync, readFileSync, writeFileSync, mkdirSync, rmSync } from "fs";
+import { copyFileSync, existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, rmSync } from "fs";
 import { join } from "path";
 import { fileURLToPath } from "url";
 
@@ -71,6 +71,7 @@ export function docsPipeline(config: DocsConfig): DocsResult {
   }
   pages.set("index.mdx", overviewContent);
   const suppress = new Set(config.suppressPages ?? []);
+  const extraSlugs = new Set((config.extraPages ?? []).map((p) => p.slug));
 
   // Extra pages from lexicon config
   if (config.extraPages) {
@@ -96,12 +97,28 @@ export function docsPipeline(config: DocsConfig): DocsResult {
     }
   }
 
-  if (!suppress.has("intrinsics") && manifest.intrinsics && manifest.intrinsics.length > 0) {
+  // A generated page must not overwrite one the lexicon explicitly declared.
+  // The extraPages above are written into `pages` first, so an unguarded
+  // `pages.set` below silently discards them: helm declared its own
+  // "Intrinsics Reference" and pre-synth rules pages and shipped neither for
+  // as long as both slugs collided (#1312). Explicit authorship wins, and the
+  // collision is reported rather than resolved in silence.
+  const claimed = (slug: string): boolean => {
+    if (suppress.has(slug)) return true;
+    if (!extraSlugs.has(slug)) return false;
+    console.warn(
+      `[docs:${config.name}] extraPages declares "${slug}", which is also a generated page — keeping the declared one.\n` +
+        `  Add "${slug}" to suppressPages to make that explicit, or rename the extraPage if both are wanted.`,
+    );
+    return true;
+  };
+
+  if (!claimed("intrinsics") && manifest.intrinsics && manifest.intrinsics.length > 0) {
     pages.set("intrinsics.mdx", generateIntrinsics(config, manifest));
   }
 
   if (
-    !suppress.has("pseudo-parameters") &&
+    !claimed("pseudo-parameters") &&
     manifest.pseudoParameters &&
     Object.keys(manifest.pseudoParameters).length > 0
   ) {
@@ -111,14 +128,23 @@ export function docsPipeline(config: DocsConfig): DocsResult {
     );
   }
 
-  if (!suppress.has("rules") && rules.length > 0) {
+  if (!claimed("rules") && rules.length > 0) {
     pages.set("rules.mdx", generateRules(config, rules));
   }
 
-  if (!suppress.has("serialization")) {
+  if (!claimed("serialization")) {
     pages.set("serialization.mdx", generateSerialization(config));
   }
 
+  // Stamp every emitted page with its provenance. These files look exactly
+  // like the hand-written pages sitting beside them, and without a marker they
+  // get edited directly — the k8s "Live Cluster" sidebar group and the AWS
+  // intrinsics guide's #1044 claim were both fixed in the emitted `.mdx` and
+  // silently reverted by the next regen (#1312).
+  for (const [filename, content] of pages) {
+    pages.set(filename, withGeneratedMarker(config, content));
+  }
+
   return {
     pages,
     stats: {
@@ -131,6 +157,66 @@ export function docsPipeline(config: DocsConfig): DocsResult {
   };
 }
 
+/**
+ * Insert a provenance comment directly after a page's frontmatter.
+ *
+ * MDX parses `<!-- -->` as JSX rather than a comment, so this uses the
+ * `{/* … *\/}` form the rest of the docs already use for generated markers.
+ */
+function withGeneratedMarker(config: DocsConfig, content: string): string {
+  const marker = `{/* ${GENERATED_MARKER_TAG} by \`npm run docs -w @intentius/chant-lexicon-${config.name}\` — DO NOT EDIT.\n    Edit lexicons/${config.name}/src/codegen/docs.ts instead; changes here are overwritten. */}`;
+  const lines = content.split("\n");
+  // Frontmatter is the leading `---` … `---` block; the marker goes after it.
+  if (lines[0] === "---") {
+    const close = lines.indexOf("---", 1);
+    if (close > 0) {
+      lines.splice(close + 1, 0, "", marker);
+      return lines.join("\n");
+    }
+  }
+  return `${marker}\n\n${content}`;
+}
+
+/**
+ * Marks a page as pipeline output. Used both to warn readers off editing the
+ * file and, in {@link writeDocsSite}, to tell a page this pipeline owns from a
+ * hand-written one when reaping pages it no longer emits.
+ */
+export const GENERATED_MARKER_TAG = "GENERATED-BY-CHANT-DOCS";
+
+/**
+ * Every slug a Starlight sidebar reaches, including nested group items.
+ */
+export function collectSidebarSlugs(items: Array<Record<string, unknown>>): Set<string> {
+  const slugs = new Set<string>();
+  const walk = (list: Array<Record<string, unknown>>): void => {
+    for (const item of list) {
+      if (typeof item.slug === "string") slugs.add(item.slug);
+      if (Array.isArray(item.items)) walk(item.items as Array<Record<string, unknown>>);
+    }
+  };
+  walk(items);
+  return slugs;
+}
+
+/**
+ * Content pages that no sidebar entry points at.
+ *
+ * `index` is always the site root and never needs an entry of its own.
+ */
+export function unreachablePages(
+  contentDir: string,
+  sidebar: Array<Record<string, unknown>>,
+): string[] {
+  if (!existsSync(contentDir)) return [];
+  const slugs = collectSidebarSlugs(sidebar);
+  return readdirSync(contentDir)
+    .filter((f) => f.endsWith(".mdx") || f.endsWith(".md"))
+    .map((f) => f.replace(/\.mdx?$/, ""))
+    .filter((slug) => slug !== "index" && !slugs.has(slug))
+    .sort();
+}
+
 /**
  * Write generated docs pages to disk.
  */
@@ -161,6 +247,23 @@ export function writeDocsSite(config: DocsConfig, result: DocsResult): void {
     const filePath = join(contentDir, filename);
     rmSync(filePath, { force: true });
   }
+
+  // Reap pages this pipeline used to emit and no longer does. Suppressing a
+  // page only stops it being written; the copy from the last run stayed on
+  // disk, unreferenced by the sidebar and indistinguishable from a
+  // hand-written page — which is how azure, gcp and helm each kept a `rules`
+  // page after adopting their own (#1312). The provenance marker is what makes
+  // this safe: only a file this pipeline stamped is ever removed.
+  if (existsSync(contentDir)) {
+    for (const filename of readdirSync(contentDir)) {
+      if (!filename.endsWith(".mdx") && !filename.endsWith(".md")) continue;
+      if (result.pages.has(filename)) continue;
+      const filePath = join(contentDir, filename);
+      if (readFileSync(filePath, "utf-8").includes(GENERATED_MARKER_TAG)) {
+        rmSync(filePath, { force: true });
+      }
+    }
+  }
   rmSync(join(outDir, ".astro"), { recursive: true, force: true });
   rmSync(join(outDir, "node_modules", ".astro"), { recursive: true, force: true });
 
@@ -170,6 +273,20 @@ export function writeDocsSite(config: DocsConfig, result: DocsResult): void {
   // Build sidebar from generated pages
   const sidebar = buildSidebar(config, result);
 
+  // Starlight does not auto-discover pages, so a page absent from the sidebar
+  // is reachable only by typing its URL. The pipeline deliberately preserves
+  // hand-written pages it did not emit (above), which makes it easy to add one
+  // and never wire it up — azure, temporal, helm and github each accumulated
+  // several that way (#1312). Report them; `chant dev check-lexicon` gates on
+  // the same condition.
+  const unreachable = unreachablePages(contentDir, sidebar);
+  if (unreachable.length > 0) {
+    console.warn(
+      `[docs:${config.name}] ${unreachable.length} page(s) in no sidebar entry — reachable only by direct URL: ${unreachable.join(", ")}.\n` +
+        `  Declare them in this lexicon's DocsConfig \`sidebarExtra\` (or \`extraPages\`) to surface them.`,
+    );
+  }
+
   // package.json
   writeFileSync(
     join(outDir, "package.json"),

package/src/codegen/fetch.test.ts

@@ -182,12 +182,26 @@ describe("fetchWithRetry", () => {
     expect(fetchMock).toHaveBeenCalledTimes(3);
   });
 
-  test("calls fetch with no init argument when none is given", async () => {
+  test("bounds an attempt with a signal even when no init is given", async () => {
     const fetchMock = vi.fn().mockResolvedValue(ok());
     vi.stubGlobal("fetch", fetchMock);
 
     await fetchWithRetry("https://example.test/x", 4, 1);
-    expect(fetchMock).toHaveBeenCalledWith("https://example.test/x");
+    // A hung connect would otherwise wait on the OS default, which is long
+    // enough to run a CI job past its timeout.
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://example.test/x",
+      expect.objectContaining({ signal: expect.any(AbortSignal) }),
+    );
+  });
+
+  test("a caller's own signal wins over the attempt bound", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(ok());
+    vi.stubGlobal("fetch", fetchMock);
+
+    const controller = new AbortController();
+    await fetchWithRetry("https://example.test/x", 4, 1, { signal: controller.signal });
+    expect(fetchMock.mock.calls[0][1].signal).toBe(controller.signal);
   });
 
   test("passes request init through to fetch", async () => {
@@ -196,7 +210,10 @@ describe("fetchWithRetry", () => {
 
     const init = { headers: { Accept: "application/vnd.github+json" } };
     await fetchWithRetry("https://example.test/x", 4, 1, init);
-    expect(fetchMock).toHaveBeenCalledWith("https://example.test/x", init);
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://example.test/x",
+      expect.objectContaining({ headers: init.headers, signal: expect.any(AbortSignal) }),
+    );
   });
 
   test("preserves init across retries on a transient status", async () => {
@@ -210,8 +227,10 @@ describe("fetchWithRetry", () => {
     const resp = await fetchWithRetry("https://example.test/x", 4, 1, init);
     expect(resp.ok).toBe(true);
     expect(fetchMock).toHaveBeenCalledTimes(2);
-    expect(fetchMock).toHaveBeenNthCalledWith(1, "https://example.test/x", init);
-    expect(fetchMock).toHaveBeenNthCalledWith(2, "https://example.test/x", init);
+    for (const call of fetchMock.mock.calls) {
+      expect(call[0]).toBe("https://example.test/x");
+      expect(call[1]).toEqual(expect.objectContaining({ headers: init.headers, signal: expect.any(AbortSignal) }));
+    }
   });
 
   test("does not retry a permanent status when init is given", async () => {

package/src/codegen/fetch.ts

@@ -30,6 +30,20 @@ const RETRYABLE_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
 
 const DEFAULT_RETRIES = 4;
 const DEFAULT_BACKOFF_MS = 1000;
+/**
+ * Per-attempt ceiling, so an upstream that accepts a connection and then stops
+ * answering cannot hold a build open.
+ *
+ * Without one, a hung connect waits on the OS default — which on Linux is over
+ * a minute — and five of those plus back-off is enough to run a CI job past its
+ * timeout. That is not hypothetical: it is what pushed chant's `check` job from
+ * ~9m30s to a cancellation at 10m, twice, on two unreachable spec endpoints
+ * whose results are only ever a fallback to a committed snapshot anyway.
+ *
+ * Generous enough for a slow-but-alive endpoint; the point is a bound, not
+ * speed.
+ */
+const DEFAULT_ATTEMPT_TIMEOUT_MS = 15_000;
 /** Hard cap on Retry-After delays so a rogue header cannot stall CI indefinitely. */
 const MAX_RETRY_AFTER_MS = 60_000;
 
@@ -85,6 +99,7 @@ export async function fetchWithRetry(
   retries = DEFAULT_RETRIES,
   backoffMs = DEFAULT_BACKOFF_MS,
   init?: RequestInit,
+  attemptTimeoutMs = DEFAULT_ATTEMPT_TIMEOUT_MS,
 ): Promise<Response> {
   let lastStatus: number | undefined;
   let lastError: Error | undefined;
@@ -101,8 +116,11 @@ export async function fetchWithRetry(
     }
 
     let response: Response;
+    // A caller's own signal still wins; this only bounds an attempt that would
+    // otherwise hang with no signal at all.
+    const signal = init?.signal ?? AbortSignal.timeout(attemptTimeoutMs);
     try {
-      response = init === undefined ? await fetch(url) : await fetch(url, init);
+      response = await fetch(url, { ...(init ?? {}), signal });
     } catch (e) {
       // Network-level failure (DNS, connection reset, timeout). Transient.
       lastError = e instanceof Error ? e : new Error(String(e));

package/src/deep-observation.test.ts

@@ -84,6 +84,54 @@ describe("normalizeDeepProperties", () => {
     expect(out).toEqual({ Name: "n" });
   });
 
+  // A container the rules emptied is not a container the source declared empty.
+  // Keeping the husk turns a suppressed default into drift-shaped noise —
+  // `SecurityGroupEgress[#{}]: <undeclared> → {}` was the case that found this.
+  test("an object whose every field was pruned is dropped, not left as {}", () => {
+    const hooks: DeepNormalizationHooks = { prune: (n) => n.key === "CidrIp" || n.key === "IpProtocol" };
+    const out = normalizeDeepProperties(
+      { Egress: [{ CidrIp: "0.0.0.0/0", IpProtocol: "-1" }], Name: "n" },
+      { entityType: "T", side: "live", hooks },
+    );
+    expect(out).toEqual({ Name: "n" });
+  });
+
+  test("an object the source declared empty survives", () => {
+    const hooks: DeepNormalizationHooks = { prune: () => false };
+    const out = normalizeDeepProperties(
+      { Spec: {}, Items: [], Name: "n" },
+      { entityType: "T", side: "live", hooks },
+    );
+    expect(out).toEqual({ Spec: {}, Items: [], Name: "n" });
+  });
+
+  test("a partly pruned object keeps what survived", () => {
+    const hooks: DeepNormalizationHooks = { prune: (n) => n.key === "Arn" };
+    const out = normalizeDeepProperties(
+      { Role: { Arn: "arn:…", Path: "/" } },
+      { entityType: "T", side: "live", hooks },
+    );
+    expect(out).toEqual({ Role: { Path: "/" } });
+  });
+
+  test("emptiness propagates up as far as the pruning reaches", () => {
+    const hooks: DeepNormalizationHooks = { prune: (n) => n.key === "Gone" };
+    const out = normalizeDeepProperties(
+      { Outer: { Inner: { Gone: 1 } }, Name: "n" },
+      { entityType: "T", side: "live", hooks },
+    );
+    expect(out).toEqual({ Name: "n" });
+  });
+
+  test("an array keeps the elements pruning did not empty", () => {
+    const hooks: DeepNormalizationHooks = { prune: (n) => n.key === "Default" };
+    const out = normalizeDeepProperties(
+      { Rules: [{ Default: true }, { Port: 443 }] },
+      { entityType: "T", side: "live", hooks },
+    );
+    expect(out).toEqual({ Rules: [{ Port: 443 }] });
+  });
+
   test("hooks see an index-erased pattern alongside the exact path", () => {
     const seen: Array<[string, string]> = [];
     const hooks: DeepNormalizationHooks = {
@@ -232,3 +280,106 @@ describe("deepValueEqual", () => {
     expect(deepValueEqual(1, 1)).toBe(true);
   });
 });
+
+// #1314 — a nested property authored through a lexicon's generated constructor
+// is authored data, not an opaque class instance. Collapsing it to UNRESOLVED
+// left the declared side empty while the live side held the real value, so
+// every field of it reported `<undeclared>` on a clean apply.
+describe("normalizeDeepProperties — property-kind declarables (#1314)", () => {
+  /** Shaped like a generated property constructor's instance. */
+  const propertyDeclarable = (entityType: string, props: Record<string, unknown>) => ({
+    entityType,
+    kind: "property",
+    props,
+  });
+
+  test("unwraps a property-kind declarable to its authored props", () => {
+    const out = normalizeDeepProperties(
+      {
+        GroupDescription: "sg",
+        SecurityGroupIngress: [
+          propertyDeclarable("AWS::EC2::SecurityGroup.Ingress", {
+            IpProtocol: "tcp",
+            FromPort: 443,
+            ToPort: 443,
+            CidrIp: "10.42.0.0/16",
+          }),
+        ],
+      },
+      { entityType: "AWS::EC2::SecurityGroup", side: "declared" },
+    );
+    expect(out).toEqual({
+      GroupDescription: "sg",
+      SecurityGroupIngress: [{ CidrIp: "10.42.0.0/16", FromPort: 443, IpProtocol: "tcp", ToPort: 443 }],
+    });
+  });
+
+  test("produces the same tree as the equivalent plain object — the two authoring forms must not differ", () => {
+    const viaConstructor = normalizeDeepProperties(
+      { Ingress: [propertyDeclarable("T.Ingress", { IpProtocol: "tcp", FromPort: 443 })] },
+      { entityType: "T", side: "declared" },
+    );
+    const viaLiteral = normalizeDeepProperties(
+      { Ingress: [{ IpProtocol: "tcp", FromPort: 443 }] },
+      { entityType: "T", side: "declared" },
+    );
+    expect(viaConstructor).toEqual(viaLiteral);
+  });
+
+  test("unwraps nested property declarables all the way down", () => {
+    const out = normalizeDeepProperties(
+      {
+        Logging: propertyDeclarable("T.Logging", {
+          CloudWatch: propertyDeclarable("T.CloudWatch", { Enabled: true, LogGroup: "g" }),
+        }),
+      },
+      { entityType: "T", side: "declared" },
+    );
+    expect(out).toEqual({ Logging: { CloudWatch: { Enabled: true, LogGroup: "g" } } });
+  });
+
+  test("still collapses a RESOURCE-kind declarable — it is a reference with no source-side value", () => {
+    // A class instance, as a lexicon actually constructs one: a resource-kind
+    // declarable in another resource's props is a Ref, and there is nothing on
+    // the source side to compare a live value against.
+    class VpcDeclarable {
+      readonly entityType = "AWS::EC2::VPC";
+      readonly kind = "resource";
+      readonly props = { CidrBlock: "10.0.0.0/16" };
+    }
+    const out = normalizeDeepProperties(
+      { VpcId: new VpcDeclarable() },
+      { entityType: "AWS::EC2::SecurityGroup", side: "declared" },
+    );
+    expect(out).toEqual({ VpcId: UNRESOLVED });
+  });
+
+  test("unwraps a property-kind declarable that is a class instance, which is how a lexicon builds one", () => {
+    class IngressDeclarable {
+      readonly entityType = "AWS::EC2::SecurityGroup.Ingress";
+      readonly kind = "property";
+      constructor(readonly props: Record<string, unknown>) {}
+    }
+    const out = normalizeDeepProperties(
+      { Ingress: [new IngressDeclarable({ IpProtocol: "tcp", FromPort: 443 })] },
+      { entityType: "AWS::EC2::SecurityGroup", side: "declared" },
+    );
+    expect(out).toEqual({ Ingress: [{ FromPort: 443, IpProtocol: "tcp" }] });
+  });
+
+  test("still collapses a genuine class instance, which is what the branch is for", () => {
+    class Sub {
+      constructor(readonly template: string) {}
+    }
+    const out = normalizeDeepProperties({ Name: new Sub("${AWS::StackName}-x") }, { entityType: "T", side: "declared" });
+    expect(out).toEqual({ Name: UNRESOLVED });
+  });
+
+  test("masks a secret inside an unwrapped property declarable, same as in a plain object", () => {
+    const out = normalizeDeepProperties(
+      { Auth: propertyDeclarable("T.Auth", { Username: "u", Password: "hunter2" }) },
+      { entityType: "T", side: "declared" },
+    );
+    expect(out).toEqual({ Auth: { Password: MASKED, Username: "u" } });
+  });
+});

package/src/deep-observation.ts

@@ -324,6 +324,36 @@ export function deepPathSet(tree: Record<string, unknown>): Set<string> {
  * on every read; array order is canonicalized only where the lexicon says the
  * array is a set, because list order often *is* semantic.
  */
+/**
+ * A container whose every member the rules pruned.
+ *
+ * The distinction it carries is between a value that was empty in the source
+ * and one this pass emptied: `{}` a lexicon actually declared is a fact worth
+ * diffing, while `{}` left behind after both of a rule's fields were subtracted
+ * as provider defaults is a husk. Reporting the husk turns a suppressed default
+ * into `SecurityGroupEgress[#{}]: <undeclared> → {}` — noise wearing the shape
+ * of drift, which is the one thing the noise rules exist to prevent.
+ *
+ * Module-private: it never leaves this function's recursion.
+ */
+const EMPTIED = Symbol("emptied-by-pruning");
+
+/**
+ * A property-kind Declarable — a nested property authored through a lexicon's
+ * generated constructor rather than as a plain object (#1314).
+ *
+ * Duck-typed on the same three facts `declarable.ts` defines it by
+ * (`entityType`, `kind === "property"`, `props`) rather than imported, keeping
+ * this module free of a dependency on the authoring types it only ever
+ * inspects. A resource-kind Declarable deliberately does not match.
+ */
+function isPropertyDeclarableValue(value: unknown): boolean {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as { entityType?: unknown; kind?: unknown; props?: unknown };
+  return typeof v.entityType === "string" && v.kind === "property" && typeof v.props === "object" && v.props !== null;
+}
+
+
 export function normalizeDeepProperties(
   tree: Record<string, unknown>,
   options: NormalizeDeepOptions,
@@ -351,27 +381,61 @@ export function normalizeDeepProperties(
     if (isSensitiveKey(key)) return MASKED;
     if (isJsonPrimitive(value)) return value;
 
+    // A PROPERTY-kind Declarable is authored data wearing a class, not an
+    // opaque instance (#1314). The generated property constructors —
+    // `SecurityGroup_Ingress`, `Role_Policy`, `MicrovmImage_Logging` — are the
+    // typed way to write a nested property, and the serializer inlines their
+    // `.props` (serializer-walker.ts `visitor.propertyDeclarable`). The
+    // declared tree has to do the same, or the two sides disagree about a
+    // property the author did write: without this the declared side held
+    // UNRESOLVED while the live side held the real rule, so every one of its
+    // fields reported `<undeclared> → <value>` on a clean apply, and the noise
+    // scaled with how strictly a project typed its properties.
+    //
+    // Checked ahead of the array/object branches rather than in the non-JSON
+    // fallback below, so it holds whether the declarable arrives as a class
+    // instance (what a lexicon constructs) or as an equivalent plain object.
+    //
+    // Deliberately property-kind only. A RESOURCE-kind Declarable in another
+    // resource's props is a reference, which has no source-side value to
+    // compare against a live one, so UNRESOLVED stays correct for it — and a
+    // resource-kind instance falls through to that fallback unchanged.
+    if (isPropertyDeclarableValue(value)) {
+      return normalizeValue((value as { props?: unknown }).props ?? {}, path, pattern, key);
+    }
+
     if (Array.isArray(value)) {
       const elements: unknown[] = [];
       for (let i = 0; i < value.length; i++) {
         const elPath = joinIndex(path, i);
         const elPattern = joinPattern(pattern);
         if (prune(elPath, elPattern, String(i), value[i])) continue;
-        elements.push(normalizeValue(value[i], elPath, elPattern, String(i)));
+        const element = normalizeValue(value[i], elPath, elPattern, String(i));
+        if (element === EMPTIED) continue;
+        elements.push(element);
       }
+      // An array that had elements and has none left was emptied by pruning,
+      // not declared empty. Reporting `[]` for it is reporting the husk of a
+      // value the rules just decided was noise.
+      if (elements.length === 0 && value.length > 0) return EMPTIED;
       return orderElements(elements, path, pattern);
     }
 
     if (isPlainObject(value)) {
       const out: Record<string, unknown> = {};
+      let had = 0;
       for (const childKey of Object.keys(value).sort()) {
         const childPath = joinPath(path, childKey);
         const childPattern = joinPath(pattern, childKey);
         const childValue = value[childKey];
         if (childValue === undefined) continue;
+        had += 1;
         if (prune(childPath, childPattern, childKey, childValue)) continue;
-        out[childKey] = normalizeValue(childValue, childPath, childPattern, childKey);
+        const child = normalizeValue(childValue, childPath, childPattern, childKey);
+        if (child === EMPTIED) continue;
+        out[childKey] = child;
       }
+      if (Object.keys(out).length === 0 && had > 0) return EMPTIED;
       return out;
     }