@intentius/chant 0.29.0 → 0.31.0

package/src/fold/subset.test.ts

@@ -258,18 +258,49 @@ describe("documented divergences — NOT unified by design (see subset.ts module
     expect(evl001NonLiteralExpressionRule.check(context)).toHaveLength(0);
   });
 
-  test("nested resource construction: fold rejects a nested `new Type()` used as a value (falls back to run); EVL001 allows it statically", () => {
-    // A top-level `new Type()` folds (fold-import constructs a real Declarable),
-    // but a NESTED one as a property value can only fold to a {__resource,props}
-    // envelope that is never constructed, so it would serialize wrong (real
-    // fold-vs-run drift, caught by the #1025 differential on gitlab). fold()
-    // therefore rejects it, falling the file back to run; EVL allows it (a valid
-    // TS constructor call), so this is an inherent, out-of-scope divergence.
+  test("nested resource construction: NO LONGER a divergence (chant #1169) — both fold and EVL001 accept it", () => {
+    // This was the largest divergence in the table until #1169: a nested
+    // `new Type()` as a property value could only fold to a {__resource, props}
+    // envelope nothing constructed, so it would have serialized wrong (real
+    // fold-vs-run drift, caught by the #1025 differential on gitlab), and fold()
+    // rejected it while EVL allowed it.
+    //
+    // fold() now produces the envelope and ../discovery/fold-import.ts revives
+    // it into a REAL instance of the class the file imported, so the two sides
+    // agree. Kept as a test rather than deleted: it is the assertion that the
+    // divergence stays closed, and that the envelope carries the nested
+    // constructor's own name and props for the bridge to build from.
     const source = `const bad = new Thing({ x: new Inner({ y: 1 }) });`;
     const sourceFile = ts.createSourceFile("t.ts", source, ts.ScriptTarget.Latest, true);
     const consts = collectConsts(sourceFile);
     const badInit = consts.get("bad") as ts.NewExpression;
 
+    expect(foldResource(badInit, consts, [])).toEqual({
+      __resource: "Thing",
+      props: { x: { __resource: "Inner", props: { y: 1 } } },
+    });
+
+    const context: LintContext = { sourceFile, entities: [], filePath: "t.ts", lexicon: undefined };
+    expect(evl001NonLiteralExpressionRule.check(context)).toHaveLength(0);
+  });
+
+  test("same-file resource used as a bare value: fold rejects it (would build a duplicate); EVL001 allows it statically", () => {
+    // chant #1169's own new divergence, in the same safe direction as every
+    // other one here. `DependsOn: [dbCluster]` hands the run path THE instance
+    // this file already exported; folding the identifier would construct a
+    // SECOND one, which discovery never registers and whose AttrRefs can never
+    // be named. Rejected, so the file falls back to run — where both references
+    // are the same object by construction. EVL sees a plain identifier and has
+    // no binding resolver (subset.ts module doc, point 1), so it stays
+    // permissive.
+    const source = `
+      const db = new DbCluster({ engine: "aurora" });
+      const bad = new Instance({ x: 1 }, { DependsOn: [db] });
+    `;
+    const sourceFile = ts.createSourceFile("t.ts", source, ts.ScriptTarget.Latest, true);
+    const consts = collectConsts(sourceFile);
+    const badInit = consts.get("bad") as ts.NewExpression;
+
     expect(() => foldResource(badInit, consts, [])).toThrow(FoldError);
 
     const context: LintContext = { sourceFile, entities: [], filePath: "t.ts", lexicon: undefined };

package/src/fold/subset.ts

@@ -35,6 +35,15 @@ import { intrinsicCallFolds, type IntrinsicDef } from "../lexicon";
  *      intentional asymmetry, not a bug: it can only ever be a *false
  *      negative* on EVL's part (EVL passes something `fold()` might later
  *      reject for being unresolved), never the reverse.
+ *
+ *      chant #1169 adds one more resolution-dependent rejection in the same
+ *      direction: an identifier bound to a same-file `const x = new T(...)`,
+ *      used as a VALUE. It is shape-valid here; `fold()` answers it only when
+ *      its caller pre-resolved that const to the one real instance the file
+ *      built (`../discovery/fold-import.ts`), and rejects otherwise, because
+ *      re-folding the initializer would construct a duplicate of a resource
+ *      discovery has already registered. Shape cannot see the difference, and
+ *      the rejection is a fall-back-to-run, never a wrong value.
  *   2. Tagged-template *tag registration* — needs a lexicon's intrinsics
  *      manifest, which isn't available to a syntax-only lint rule. `fold()`
  *      alone checks it; this module treats any tag name as shape-valid and

package/src/graph-ir.ts

@@ -124,6 +124,51 @@ export interface IRImport {
   node: string;
 }
 
+/**
+ * One generated CI job in the pipeline projection (`chant graph --components
+ * --format ir --projection <lexicon>`, #989) — the same job a CI-provider
+ * lexicon's `generateComponentPipeline` synthesizes for `chant build
+ * --components --generate <lexicon>` (see `ComponentPipelineJob`,
+ * ./lexicon.ts), reshaped into the IR's node vocabulary.
+ */
+export interface IRPipelineNode {
+  /** CI job name (the generator's job id — a safe YAML/workflow key). */
+  id: string;
+  kind: "CIJob";
+  /** The component this job triggers. */
+  component: string;
+  /** The stage/wave this job runs in — the same wave index as the component
+   * graph's `groups.byWave` (one CI stage/`needs:`-level per wave). */
+  stage: string;
+}
+
+/** A `needs:` dependency between two generated CI jobs — mirrors the
+ * `dependsOn` edge it derives from, consumer job → producer job. */
+export interface IRPipelineEdge {
+  from: string;
+  to: string;
+  kind: "needs";
+}
+
+/**
+ * The CI/pipeline projection of a component graph (#989): the stages/jobs/
+ * `needs` a CI-provider lexicon (gitlab, github, forgejo, or any lexicon
+ * implementing `generateComponentPipeline`) would synthesize for `chant build
+ * --components --generate <lexicon>`, reused here — never re-derived — as
+ * first-class IR nodes/edges. A consumer (e.g. behold) reads this alongside
+ * the component graph's `nodes`/`edges`/`groups.byWave` to render the CI
+ * shape without parsing generated YAML. Present only when `chant graph
+ * --components --format ir` is invoked with `--projection <lexicon>`.
+ */
+export interface IRPipeline {
+  /** The CI-provider lexicon that produced this projection (e.g. "gitlab"). */
+  provider: string;
+  /** Wave-ordered stage names — 1:1 with the component graph's `groups.byWave` keys. */
+  stages: string[];
+  nodes: IRPipelineNode[];
+  edges: IRPipelineEdge[];
+}
+
 /** The full graph IR for a project at the default (declarable) detail level. */
 export interface GraphIR {
   nodes: IRNode[];
@@ -135,6 +180,8 @@ export interface GraphIR {
    * `name` to another stack's export `name` to draw the cross-stack edge; the
    * parameter's in-stack consumers are ordinary `$ref` edges to it (#513). */
   imports?: IRImport[];
+  /** The CI/pipeline projection alongside the component graph (#989) — see {@link IRPipeline}. */
+  pipeline?: IRPipeline;
 }
 
 /** A node is anything that serializes to a resource — not a property or output. */

package/src/index.ts

@@ -49,6 +49,7 @@ export * from "./import/parser";
 export * from "./import/generator";
 export * from "./lexicon";
 export * from "./observation";
+export * from "./deep-observation";
 export * from "./lexicon-integrity";
 export * from "./lexicon-manifest";
 export * from "./lexicon-schema";

package/src/kubectl-context.ts

@@ -72,8 +72,18 @@ export interface ResolvedClusterTarget {
   source: "bound" | "ambient";
 }
 
+/**
+ * How the resolver learns which context is ambient. The default shells
+ * `kubectl config current-context`; the k8s lexicon's typed API client
+ * (chant #1074) supplies one that reads the parsed kubeconfig instead, so a
+ * client that never needs the `kubectl` binary does not acquire a dependency
+ * on it just to check the binding. Both answer the same question, so the
+ * refusal semantics below are identical either way.
+ */
+export type AmbientContextReader = () => Promise<string | undefined>;
+
 /** Reads `kubectl config current-context`. Returns undefined if unset or kubectl fails. */
-async function currentAmbientContext(): Promise<string | undefined> {
+const currentAmbientContext: AmbientContextReader = async () => {
   try {
     const { stdout } = await execAsync("kubectl config current-context");
     const trimmed = stdout.trim();
@@ -81,6 +91,15 @@ async function currentAmbientContext(): Promise<string | undefined> {
   } catch {
     return undefined;
   }
+};
+
+/** Options for {@link resolveClusterTarget}. */
+export interface ResolveClusterTargetOptions {
+  /**
+   * Override how the ambient context is read. Defaults to
+   * `kubectl config current-context`.
+   */
+  ambientContext?: AmbientContextReader;
 }
 
 /**
@@ -105,6 +124,7 @@ export async function resolveClusterTarget(
   config: Record<string, unknown>,
   environment: string,
   lexiconName: string,
+  options: ResolveClusterTargetOptions = {},
 ): Promise<ResolvedClusterTarget> {
   const k8sConfig = config.k8s as K8sConfigShape | undefined;
   const bound = k8sConfig?.profiles?.[environment]?.context;
@@ -118,7 +138,7 @@ export async function resolveClusterTarget(
     return { source: "ambient" };
   }
 
-  const ambient = await currentAmbientContext();
+  const ambient = await (options.ambientContext ?? currentAmbientContext)();
   if (ambient && ambient !== bound) {
     throw new ClusterBindingMismatchError(environment, bound, ambient);
   }

package/src/lexicon.ts

@@ -12,6 +12,7 @@ import type { EmulatorCapability } from "./op/emulator-lifecycle";
 import type { RuleMeta } from "./audit/catalog";
 import type { ReferenceCatalog } from "./graph-refs";
 import type { DescribeResourcesResult } from "./observation";
+import type { DeepNormalizationHooks, DeepObservationResult } from "./deep-observation";
 
 // Re-exported so lexicons can author a reference catalog (#778) from the same
 // `@intentius/chant/lexicon` entry they import the plugin contract from.
@@ -28,6 +29,20 @@ export type {
   UnobservedReason,
 } from "./observation";
 
+// The deep observation contract (#1014), re-exported for the same reason: a
+// lexicon authoring `observeResourcesDeep` + its pruning/ordering hooks types
+// them from the same entry. Runtime helpers live in
+// `@intentius/chant/deep-observation`.
+export type {
+  DeepObservationResult,
+  DeepResourceObservation,
+  NormalizedDeepObservation,
+  DeepNormalizationHooks,
+  DeepNode,
+  DeepArrayElement,
+  DeepSide,
+} from "./deep-observation";
+
 /**
  * Manifest for a packaged lexicon — metadata embedded in the tarball.
  *
@@ -571,6 +586,50 @@ export interface LexiconPlugin {
     owned?: boolean;
   }): Promise<DescribeResourcesResult>;
 
+  /**
+   * Read the full live *property tree* for each declared entity (#1014). Opt-in,
+   * and strictly deeper than {@link describeResources}, which reports existence
+   * plus a handful of scrubbed outputs. A lexicon that implements neither, or
+   * only the thin one, is unaffected — `lifecycle diff --live` gains
+   * property-level entries only where this exists.
+   *
+   * The result is keyed by chant entity name, exactly like the thin read, and
+   * carries the same NOT-OBSERVED map. That is the composition rule with #1089:
+   * a deep read that fails for one entity says so with a total
+   * {@link UnobservedReason}. It never returns a thin-but-clean tree, because a
+   * clean tree is a claim that nothing drifted.
+   *
+   * Properties must be normalized before they are returned — run
+   * `normalizeDeepProperties` (../deep-observation.ts) with this lexicon's own
+   * {@link deepNormalizationHooks}, so the trees a consumer sees are already
+   * free of arns, timestamps, status subtrees and unstable orderings.
+   *
+   * Throwing is the whole-lexicon failure, same as the thin read: core turns it
+   * into `read-failed` for every declared entity.
+   */
+  observeResourcesDeep?(options: {
+    environment: string;
+    buildOutput: string;
+    entityNames: string[];
+    entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+    /** Deployed stack to observe, for a multi-stack project (see `stacks` in {@link ChantConfig}). */
+    stack?: string;
+    /** Restrict to chant-owned resources (#119). A lexicon with no marker channel on this path says so. */
+    owned?: boolean;
+  }): Promise<DeepObservationResult>;
+
+  /**
+   * This lexicon's noise rules for deep observation (#1014): which fields are
+   * read-only / server-populated / controller-managed / provider-defaulted, and
+   * which arrays are sets. Data, not a method — core applies the same rules to
+   * the *declared* tree, which no reader ever touches, and the two sides have
+   * to be normalized identically to be comparable.
+   *
+   * Ships alongside {@link observeResourcesDeep}; a reader without hooks
+   * produces a diff made almost entirely of noise.
+   */
+  deepNormalizationHooks?: DeepNormalizationHooks;
+
   /**
    * Report the live status of one deploy unit by its deployed name. Opt-in.
    *

package/src/lifecycle/deep-diff.test.ts

@@ -0,0 +1,157 @@
+import { describe, test, expect } from "vitest";
+import { countPropertyDrift, diffDeep } from "./deep-diff";
+import { UNRESOLVED, type NormalizedDeepObservation } from "../deep-observation";
+import type { BaselineLexicon } from "./observation-baseline";
+
+const live = (
+  resources: Record<string, { type: string; properties: Record<string, unknown> }>,
+  unobserved: NormalizedDeepObservation["unobserved"] = {},
+): NormalizedDeepObservation => ({ resources, unobserved });
+
+describe("diffDeep", () => {
+  test("identical trees are unchanged", () => {
+    const result = diffDeep({
+      declared: { b: { type: "AWS::S3::Bucket", properties: { BucketName: "x" } } },
+      live: live({ b: { type: "AWS::S3::Bucket", properties: { BucketName: "x" } } }),
+    });
+    expect(result.unchanged).toEqual(["b"]);
+    expect(result.drifted).toEqual([]);
+  });
+
+  test("a changed property reports declared and live", () => {
+    const result = diffDeep({
+      declared: { b: { type: "AWS::S3::Bucket", properties: { Versioning: { Status: "Enabled" } } } },
+      live: live({ b: { type: "AWS::S3::Bucket", properties: { Versioning: { Status: "Suspended" } } } }),
+    });
+    expect(result.drifted).toEqual([
+      {
+        name: "b",
+        type: "AWS::S3::Bucket",
+        changes: [{ path: "Versioning.Status", kind: "changed", declared: "Enabled", live: "Suspended" }],
+      },
+    ]);
+    expect(countPropertyDrift(result)).toBe(1);
+  });
+
+  test("a property only the cloud has is undeclared drift", () => {
+    const result = diffDeep({
+      declared: { b: { type: "T", properties: {} } },
+      live: live({ b: { type: "T", properties: { LoggingConfiguration: { TargetBucket: "logs" } } } }),
+    });
+    expect(result.drifted[0].changes).toEqual([
+      { path: "LoggingConfiguration.TargetBucket", kind: "undeclared", live: "logs" },
+    ]);
+  });
+
+  test("a declared property the cloud does not carry is absent", () => {
+    const result = diffDeep({
+      declared: { b: { type: "T", properties: { A: 1 } } },
+      live: live({ b: { type: "T", properties: {} } }),
+    });
+    expect(result.drifted[0].changes).toEqual([{ path: "A", kind: "absent", declared: 1 }]);
+  });
+
+  test("an unevaluated intrinsic on the declared side is never drift", () => {
+    const result = diffDeep({
+      declared: { b: { type: "T", properties: { BucketName: UNRESOLVED, Other: "x" } } },
+      live: live({ b: { type: "T", properties: { BucketName: "prod-data", Other: "x" } } }),
+    });
+    expect(result.drifted).toEqual([]);
+    expect(result.unchanged).toEqual(["b"]);
+  });
+
+  test("an entity the deep read could not look at is a hole, not drift", () => {
+    const result = diffDeep({
+      declared: { b: { type: "T", properties: { A: 1 } } },
+      live: live({}, { b: { type: "T", reason: "unsupported-kind", detail: "no reader" } }),
+    });
+    expect(result.drifted).toEqual([]);
+    expect(result.unobserved).toEqual([
+      { name: "b", type: "T", reason: "unsupported-kind", detail: "no reader" },
+    ]);
+  });
+
+  test("present beats not-observed", () => {
+    const result = diffDeep({
+      declared: { b: { type: "T", properties: { A: 1 } } },
+      live: live({ b: { type: "T", properties: { A: 1 } } }, { b: { reason: "read-failed" } }),
+    });
+    expect(result.unobserved).toEqual([]);
+  });
+
+  test("an entity absent from the deep read reports no property drift at all", () => {
+    // The thin diff already calls this `missing`; restating every declared
+    // property as `absent` would bury that one line.
+    const result = diffDeep({
+      declared: { b: { type: "T", properties: { A: 1, B: 2 } } },
+      live: live({}),
+    });
+    expect(result.drifted).toEqual([]);
+    expect(result.unchanged).toEqual([]);
+  });
+
+  test("a live entity nobody declared is reported separately", () => {
+    const result = diffDeep({
+      declared: {},
+      live: live({ ghost: { type: "T", properties: { A: 1 } } }),
+    });
+    expect(result.undeclaredEntities).toEqual(["ghost"]);
+    expect(result.drifted).toEqual([]);
+  });
+});
+
+describe("diffDeep with an accepted baseline", () => {
+  const baseline: BaselineLexicon = {
+    b: {
+      type: "AWS::S3::Bucket",
+      accepted: [{ path: "Tags[0].Value", value: "platform", note: "set by the platform team" }],
+    },
+  };
+
+  test("an accepted deviation is not drift", () => {
+    const result = diffDeep({
+      declared: { b: { type: "AWS::S3::Bucket", properties: {} } },
+      live: live({ b: { type: "AWS::S3::Bucket", properties: { Tags: [{ Value: "platform" }] } } }),
+      baseline,
+    });
+    expect(result.drifted).toEqual([]);
+    expect(result.accepted[0].changes[0]).toEqual({
+      path: "Tags[0].Value",
+      kind: "undeclared",
+      live: "platform",
+      baseline: "platform",
+    });
+  });
+
+  test("a value that moved away from the accepted one is drift again, and shows all three axes", () => {
+    const result = diffDeep({
+      declared: { b: { type: "AWS::S3::Bucket", properties: {} } },
+      live: live({ b: { type: "AWS::S3::Bucket", properties: { Tags: [{ Value: "someone-else" }] } } }),
+      baseline,
+    });
+    expect(result.drifted[0].changes[0]).toEqual({
+      path: "Tags[0].Value",
+      kind: "undeclared",
+      live: "someone-else",
+      baseline: "platform",
+    });
+  });
+
+  test("an entity with only accepted deviations is not counted as unchanged", () => {
+    const result = diffDeep({
+      declared: { b: { type: "AWS::S3::Bucket", properties: {} } },
+      live: live({ b: { type: "AWS::S3::Bucket", properties: { Tags: [{ Value: "platform" }] } } }),
+      baseline,
+    });
+    expect(result.unchanged).toEqual([]);
+  });
+
+  test("the baseline never suppresses a different path", () => {
+    const result = diffDeep({
+      declared: { b: { type: "AWS::S3::Bucket", properties: {} } },
+      live: live({ b: { type: "AWS::S3::Bucket", properties: { Tags: [{ Value: "platform" }], Extra: 1 } } }),
+      baseline,
+    });
+    expect(result.drifted[0].changes.map((c) => c.path)).toEqual(["Extra"]);
+  });
+});

package/src/lifecycle/deep-diff.ts

@@ -0,0 +1,213 @@
+/**
+ * Property-level live drift (#1014) — declared vs live vs accepted baseline.
+ *
+ * The thin diff (./live-diff.ts) compares whole entities on status, physical id
+ * and a few outputs. This compares their property trees, path by path, which is
+ * where a console edit actually shows up. Pure function; the reading happens in
+ * ./deep-observe.ts and the CLI.
+ *
+ * Three axes, and all three matter:
+ *
+ *   - **declared** — the property tree chant synthesized, normalized with the
+ *     lexicon's own hooks so it is in the same shape as the live tree.
+ *   - **live** — what the provider returned, normalized with the same hooks.
+ *   - **baseline** — the value somebody accepted (./observation-baseline.ts). A
+ *     deviation whose live value matches the accepted value is not drift; one
+ *     that has moved away from the accepted value is drift again, and the
+ *     report shows all three so the reader can see what changed and from what.
+ *
+ * A path is skipped entirely when the declared value is
+ * {@link UNRESOLVED} — an unevaluated intrinsic (`Fn::Sub`, `Ref`) has no
+ * source-side value to compare, and reporting one as drift would light up every
+ * interpolated property forever.
+ */
+
+import {
+  UNRESOLVED,
+  deepValueEqual,
+  flattenDeepProperties,
+  type DeepNormalizationHooks,
+  type NormalizedDeepObservation,
+} from "../deep-observation";
+import type { UnobservedResource } from "./live-diff";
+import { acceptedDeviation, type BaselineLexicon } from "./observation-baseline";
+
+/**
+ * How a property differs.
+ *
+ * - `changed` — declared and live both have the path, with different values.
+ * - `undeclared` — live has it, source never did. cdk-real-drift's whole reason
+ *   to exist: the console-added property CloudFormation itself will not report.
+ * - `absent` — source declares it and the live tree does not carry it. Weaker
+ *   than the other two: a provider that omits a property it considers unset is
+ *   common, which is what the lexicon's pruning hook is for.
+ */
+export type PropertyDriftKind = "changed" | "undeclared" | "absent";
+
+/** One property-level difference. */
+export interface PropertyDrift {
+  /** Path within the normalized property tree (`Tags[0].Value`). */
+  path: string;
+  kind: PropertyDriftKind;
+  /** Value in source. Absent for `undeclared`. */
+  declared?: unknown;
+  /** Value in the cloud. Absent for `absent`. */
+  live?: unknown;
+  /**
+   * The accepted value from the baseline, when this path has one. Present on a
+   * reported drift too — that is the "accepted X, now Y" case, and hiding the
+   * accepted value there would lose the most useful column in the report.
+   */
+  baseline?: unknown;
+}
+
+/** Property-level drift for one declared entity. */
+export interface DeepEntityDrift {
+  name: string;
+  type: string;
+  changes: PropertyDrift[];
+}
+
+export interface DeepDiffResult {
+  /** Entities with at least one reportable property difference. Sorted by name. */
+  drifted: DeepEntityDrift[];
+  /**
+   * Differences suppressed by the baseline — reported separately rather than
+   * dropped, so `--json` consumers and `--update-baseline` can see what is
+   * being held back and the count never silently changes meaning.
+   */
+  accepted: DeepEntityDrift[];
+  /** Entities whose property trees matched. Sorted. */
+  unchanged: string[];
+  /** Declared entities whose *properties* could not be read (#1089). Sorted. */
+  unobserved: UnobservedResource[];
+  /** Entities the deep reader returned that were never declared. Sorted. */
+  undeclaredEntities: string[];
+}
+
+/** A declared entity's property tree, already normalized with the lexicon's hooks. */
+export interface DeclaredDeepEntity {
+  type: string;
+  properties: Record<string, unknown>;
+}
+
+export interface DiffDeepInput {
+  /** Normalized declared property trees, keyed by chant entity name. */
+  declared: Record<string, DeclaredDeepEntity>;
+  /** Normalized live observation, as returned by `observeResourcesDeep()`. */
+  live: NormalizedDeepObservation;
+  /** Accepted deviations for this lexicon. Omit for "nothing accepted". */
+  baseline?: BaselineLexicon;
+  /**
+   * The lexicon's hooks, so set-like arrays are addressed by key rather than by
+   * position (see `flattenDeepProperties`). Omit and paths are positional,
+   * which still diffs correctly but shifts every path after an inserted
+   * element.
+   */
+  hooks?: DeepNormalizationHooks;
+}
+
+/**
+ * Compare declared and live property trees path by path, subtracting accepted
+ * deviations. Deterministic: every list is sorted.
+ */
+export function diffDeep(input: DiffDeepInput): DeepDiffResult {
+  const baseline = input.baseline ?? {};
+  const drifted: DeepEntityDrift[] = [];
+  const accepted: DeepEntityDrift[] = [];
+  const unchanged: string[] = [];
+  const unobserved: UnobservedResource[] = [];
+  const undeclaredEntities: string[] = [];
+
+  const liveNames = new Set(Object.keys(input.live.resources));
+
+  for (const [name, entry] of Object.entries(input.live.unobserved)) {
+    // Present beats not-observed, exactly as the thin contract resolves it.
+    if (liveNames.has(name)) continue;
+    unobserved.push({
+      name,
+      ...(entry.type ? { type: entry.type } : {}),
+      reason: entry.reason,
+      ...(entry.detail ? { detail: entry.detail } : {}),
+    });
+  }
+
+  for (const name of liveNames) {
+    if (!(name in input.declared)) undeclaredEntities.push(name);
+  }
+
+  for (const name of Object.keys(input.declared).sort()) {
+    const liveEntity = input.live.resources[name];
+    // Not observed deeply → already recorded above; no properties to compare.
+    // Observed absent by the deep reader is the thin diff's `missing` case and
+    // is not restated here: a resource that does not exist has no property
+    // drift, and reporting every one of its declared properties as `absent`
+    // would bury the one line that matters.
+    if (!liveEntity) continue;
+
+    const declaredEntity = input.declared[name];
+    const type = liveEntity.type || declaredEntity.type;
+    const declaredFlat = flattenDeepProperties(declaredEntity.properties, {
+      entityType: type,
+      side: "declared",
+      hooks: input.hooks,
+    });
+    const liveFlat = flattenDeepProperties(liveEntity.properties, {
+      entityType: type,
+      side: "live",
+      hooks: input.hooks,
+    });
+
+    const paths = [...new Set([...declaredFlat.keys(), ...liveFlat.keys()])].sort();
+    const reported: PropertyDrift[] = [];
+    const suppressed: PropertyDrift[] = [];
+
+    for (const path of paths) {
+      const hasDeclared = declaredFlat.has(path);
+      const hasLive = liveFlat.has(path);
+      const declaredValue = declaredFlat.get(path);
+      const liveValue = liveFlat.get(path);
+
+      // An unevaluated intrinsic has no source-side value to compare against.
+      if (hasDeclared && declaredValue === UNRESOLVED) continue;
+      if (hasDeclared && hasLive && deepValueEqual(declaredValue, liveValue)) continue;
+
+      const kind: PropertyDriftKind = !hasDeclared ? "undeclared" : !hasLive ? "absent" : "changed";
+      const drift: PropertyDrift = {
+        path,
+        kind,
+        ...(hasDeclared ? { declared: declaredValue } : {}),
+        ...(hasLive ? { live: liveValue } : {}),
+      };
+
+      const acceptedEntry = acceptedDeviation(baseline, name, path);
+      if (acceptedEntry) {
+        drift.baseline = acceptedEntry.value;
+        // Value-bound acceptance: the accepted value is not drift, a different
+        // one is drift again.
+        if (hasLive && deepValueEqual(liveValue, acceptedEntry.value)) {
+          suppressed.push(drift);
+          continue;
+        }
+      }
+      reported.push(drift);
+    }
+
+    if (suppressed.length > 0) accepted.push({ name, type, changes: suppressed });
+    if (reported.length > 0) drifted.push({ name, type, changes: reported });
+    else if (suppressed.length === 0) unchanged.push(name);
+  }
+
+  return {
+    drifted: drifted.sort((a, b) => a.name.localeCompare(b.name)),
+    accepted: accepted.sort((a, b) => a.name.localeCompare(b.name)),
+    unchanged: unchanged.sort(),
+    unobserved: unobserved.sort((a, b) => a.name.localeCompare(b.name)),
+    undeclaredEntities: undeclaredEntities.sort(),
+  };
+}
+
+/** Total reported property differences across every entity. */
+export function countPropertyDrift(result: DeepDiffResult): number {
+  return result.drifted.reduce((n, e) => n + e.changes.length, 0);
+}