@intentius/chant 0.124.33 → 0.124.35

package/src/components/release-gate.test.ts

@@ -13,6 +13,7 @@ import {
   emptyVerifier,
   gateNamesOf,
   planReleaseChangeSet,
+  planReleaseSet,
   provisionalMembers,
   RELEASE_GATE_OP,
 } from "./release-gate";
@@ -162,6 +163,52 @@ describe("planReleaseChangeSet", () => {
   });
 });
 
+describe("planReleaseSet: a dependent plans against its upstream's planned outputs (#4168 step 4)", () => {
+  const r1 = release(sha("7"));
+  const reg = () => {
+    const r = registry();
+    r.register({
+      kind: "tf",
+      async run() { return {}; },
+      async plan(_ctx: unknown, input: { name: string; vpc?: unknown }) {
+        return {
+          member: input.name,
+          planDigest: sha(input.vpc === "vpc-new" ? "b" : input.vpc === undefined ? "c" : "a"),
+          outputs: input.name === "net" ? { known: { id: "vpc-new" }, unknown: ["arn"] } : undefined,
+        };
+      },
+      async outputs() { return { id: "vpc-old", arn: "arn:old" }; },
+    } as never);
+    return r;
+  };
+  const net: DriverComponent = { name: "net", deploy: [{ phase: "Apply", steps: [{ kind: "gate", gate: "prod-release" }, { kind: "tf", name: "net" }] }] };
+  const svc = (ref: string): DriverComponent => ({
+    name: "svc",
+    dependsOn: ["net"],
+    deploy: [{ phase: "Apply", steps: [{ kind: "gate", gate: "prod-release" }, { kind: "tf", name: "svc", vpc: { stackOutput: { stack: "net", name: ref } } }] }],
+  });
+
+  test("an upstream the promote plans is read from its plan, and the read is kept", async () => {
+    const set = await planReleaseSet({ release: r1, env: "prod", components: [svc("id"), net], digests: new Map(), registry: reg(), current: new Map() });
+    expect(set.doc.members.find((m) => m.member === "svc")?.planDigest).toBe(sha("b"));
+    expect(set.reads.svc).toEqual({ net: { id: "vpc-new" } });
+    expect(set.plannedOutputs).toEqual({ net: ["id"] });
+    expect(set.unknownInputs).toBeUndefined();
+  });
+
+  test("an output the upstream's plan can't say is an unknown input", async () => {
+    const set = await planReleaseSet({ release: r1, env: "prod", components: [svc("arn"), net], digests: new Map(), registry: reg(), current: new Map() });
+    expect(set.unknownInputs).toEqual({ svc: ["net.arn"] });
+  });
+
+  test("an upstream outside the promote is read as it stands", async () => {
+    const set = await planReleaseSet({ release: r1, env: "prod", components: [svc("id"), net], digests: new Map(), registry: reg(), current: new Map(), only: new Set(["svc"]), seededOutputs: { net: { id: "vpc-old" } } });
+    expect(set.doc.members.map((m) => m.member)).toEqual(["svc"]);
+    expect(set.reads.svc).toEqual({ net: { id: "vpc-old" } });
+    expect(set.plannedOutputs).toBeUndefined();
+  });
+});
+
 describe("empty change sets", () => {
   const r1 = release(sha("7"));
   const emptyDoc = (): ChangeSetDocument =>

package/src/components/release-gate.ts

@@ -39,6 +39,14 @@
  * planned by that capability, as a pull request's plan is. A plan that
  * returns no change-set part is a hole, since nothing says what it changes.
  *
+ * A dependency the promote also deploys is read from its plan, not from the
+ * estate (#4168 step 4, the rule #3999 gave a pull request): a dependent is
+ * planned against the outputs its upstream's plan says it will expose, and a
+ * reference the plan can't say is listed in `unknownInputs`. Any other
+ * dependency is read as it stands. What each component was planned against is
+ * kept in `reads`, so the promote can hold it back when an upstream applies
+ * as another value (`./promote-rounds.ts`).
+ *
  * Any other component is a `chant` member compared with what the
  * environment runs now: its latest deploy record and the release that record
  * names. The artifact digest, each template the release's target records for
@@ -52,8 +60,8 @@
  * recorded since (#4035): its record names what ran before that run.
  */
 
-import type { CapabilityRegistry } from "./capability";
-import { deployContext, resolveComponentGraph, resolveStepInput, type DriverComponent, type DriverGate, type DriverPhase, type DriverStep } from "./driver";
+import type { CapabilityRegistry, PlannedOutputs } from "./capability";
+import { deployContext, resolveComponentGraph, resolveStepInput, unresolvedWiringReferences, type DriverComponent, type DriverGate, type DriverPhase, type DriverStep } from "./driver";
 import { componentPlanDigest } from "./gate-plan";
 import { gateName, RELEASE_GATE_OP } from "../op/gate-name";
 import { capabilitySteps, planContext, readComponentOutputs } from "./wave-plan";
@@ -123,6 +131,23 @@ export interface ReleaseChangeSetInput {
   seededOutputs?: Record<string, Record<string, unknown>>;
   /** The chant version to record in the document. */
   chant?: string;
+  /**
+   * Plan only these components (a later round or wave, ./promote-rounds.ts).
+   * The others are not planned; a dependency among them is read from
+   * `seededOutputs`, which then holds what the run left. Default: every one.
+   */
+  only?: ReadonlySet<string>;
+}
+
+/** A release's change set for an environment, and what each component was planned against. */
+export interface ReleasePlan {
+  doc: ChangeSetDocument;
+  /** Per planned component, the outputs of its dependencies as its plan read them. */
+  reads: Record<string, Record<string, Record<string, unknown>>>;
+  /** Per dependency read from its plan, the names of the outputs the plan knows, sorted. Absent when none. */
+  plannedOutputs?: Record<string, string[]>;
+  /** Per component, the references to a promoted upstream that no value stands for until it applies, sorted. Absent when none. */
+  unknownInputs?: Record<string, string[]>;
 }
 
 const byString = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
@@ -240,65 +265,105 @@ export function chantComponentPart(input: {
  * that fails to plan: it becomes a failed member.
  */
 export async function planReleaseChangeSet(input: ReleaseChangeSetInput): Promise<ChangeSetDocument> {
+  return (await planReleaseSet(input)).doc;
+}
+
+/**
+ * {@link planReleaseChangeSet}, with what each component read. Components are
+ * planned a wave at a time, so a dependency the promote deploys has planned
+ * before its dependents read its outputs.
+ */
+export async function planReleaseSet(input: ReleaseChangeSetInput): Promise<ReleasePlan> {
   const { release, env, registry } = input;
   const components = [...input.components];
   const byName = new Map(components.map((c) => [c.name, c]));
   const outputs: Record<string, Record<string, unknown>> = { ...(input.seededOutputs ?? {}) };
   const read = new Set(Object.keys(outputs));
   const parts: ChangeSetPart[] = [];
-  const { order } = resolveComponentGraph(components.map((c) => ({ ...c, dependsOn: (c.dependsOn ?? []).filter((d) => byName.has(d)) })));
-  for (const name of order) {
-    const component = byName.get(name)!;
-    const digest = input.digests.get(name) ?? "";
-    const plannable = capabilitySteps(component.deploy).filter((s) => registry.has(s.kind) && registry.resolve(s.kind).plan !== undefined);
-    if (plannable.length === 0) {
-      parts.push(chantComponentPart({ component, release, env, digest, current: input.current.get(name), unsettled: input.unsettled?.get(name) }));
-      continue;
-    }
-    const ctx = deployContext({ env }, name);
-    try {
-      for (const dep of component.dependsOn ?? []) {
-        if (read.has(dep) || !byName.has(dep)) continue;
-        read.add(dep);
-        const found = await readComponentOutputs(byName.get(dep)!, registry, deployContext({ env }, dep), outputs);
-        if (found) outputs[dep] = found;
+  const plannedBy = new Map<string, PlannedOutputs | undefined>();
+  const planned: Record<string, string[]> = {};
+  const unknownInputs: Record<string, string[]> = {};
+  const reads: ReleasePlan["reads"] = {};
+  const inPlan = (name: string): boolean => input.only === undefined || input.only.has(name);
+  const isPlannable = (c: DriverComponent): boolean =>
+    capabilitySteps(c.deploy).some((s) => registry.has(s.kind) && registry.resolve(s.kind).plan !== undefined);
+  const { waves } = resolveComponentGraph(components.map((c) => ({ ...c, dependsOn: (c.dependsOn ?? []).filter((d) => byName.has(d)) })));
+  for (const wave of waves) {
+    const planning = wave.filter(inPlan);
+    for (const name of planning) {
+      const component = byName.get(name)!;
+      const digest = input.digests.get(name) ?? "";
+      const plannable = capabilitySteps(component.deploy).filter((s) => registry.has(s.kind) && registry.resolve(s.kind).plan !== undefined);
+      if (plannable.length === 0) {
+        parts.push(chantComponentPart({ component, release, env, digest, current: input.current.get(name), unsettled: input.unsettled?.get(name) }));
+        continue;
       }
-      for (const step of plannable) {
-        const { kind, ...rest } = step;
-        const planned = await registry.resolve(kind).plan!(planContext(ctx, rest, outputs), resolveStepInput(rest, {}, outputs) as never);
-        parts.push(
-          planned.changeSet ?? {
-            member: {
-              member: planned.member,
-              lexicon: "chant",
-              planner: "chant",
-              status: "planned",
-              planDigest: planned.planDigest,
-              holes: [{ address: planned.member, reason: `its ${kind} plan describes no changes, so what it changes is unknown` }],
+      const ctx = deployContext({ env }, name);
+      try {
+        for (const dep of component.dependsOn ?? []) {
+          if (read.has(dep) || !byName.has(dep)) continue;
+          read.add(dep);
+          // A dependency this promote plans exposes what its plan says (#3999).
+          if (plannedBy.has(dep) && isPlannable(byName.get(dep)!)) {
+            const known = plannedBy.get(dep)?.known ?? {};
+            outputs[dep] = { ...known };
+            planned[dep] = Object.keys(known).sort();
+            continue;
+          }
+          const found = await readComponentOutputs(byName.get(dep)!, registry, deployContext({ env }, dep), outputs);
+          if (found) outputs[dep] = found;
+        }
+        reads[name] = Object.fromEntries((component.dependsOn ?? []).filter((d) => d in outputs).map((d) => [d, structuredClone(outputs[d])]));
+        const unknown = new Set<string>();
+        let exposes: PlannedOutputs | undefined;
+        for (const step of plannable) {
+          const { kind, ...rest } = step;
+          for (const r of unresolvedWiringReferences(rest, outputs)) if (plannedBy.has(r.source) && !r.publish) unknown.add(r.ref);
+          const result = await registry.resolve(kind).plan!(planContext(ctx, rest, outputs), resolveStepInput(rest, {}, outputs) as never);
+          if (result.outputs) exposes = { known: { ...(exposes?.known ?? {}), ...result.outputs.known }, unknown: [...new Set([...(exposes?.unknown ?? []), ...result.outputs.unknown])].sort() };
+          parts.push(
+            result.changeSet ?? {
+              member: {
+                member: result.member,
+                lexicon: "chant",
+                planner: "chant",
+                status: "planned",
+                planDigest: result.planDigest,
+                holes: [{ address: result.member, reason: `its ${kind} plan describes no changes, so what it changes is unknown` }],
+              },
+              entries: [],
             },
-            entries: [],
+          );
+        }
+        plannedBy.set(name, exposes);
+        if (unknown.size > 0) unknownInputs[name] = [...unknown].sort();
+      } catch (err) {
+        plannedBy.set(name, undefined);
+        parts.push({
+          member: {
+            member: name,
+            lexicon: "chant",
+            planner: "chant",
+            status: "failed",
+            error: err instanceof Error ? err.message : String(err),
+            planDigest: null,
+            holes: [],
           },
-        );
+          entries: [],
+        });
       }
-    } catch (err) {
-      parts.push({
-        member: {
-          member: name,
-          lexicon: "chant",
-          planner: "chant",
-          status: "failed",
-          error: err instanceof Error ? err.message : String(err),
-          planDigest: null,
-          holes: [],
-        },
-        entries: [],
-      });
     }
   }
-  return composeChangeSet(parts, {
+  const doc = composeChangeSet(parts, {
     ...(input.chant !== undefined ? { chant: input.chant } : {}),
     planned: { releaseDigest: release.releaseDigest, environment: env },
   });
+  return {
+    doc,
+    reads,
+    ...(Object.keys(planned).length > 0 ? { plannedOutputs: planned } : {}),
+    ...(Object.keys(unknownInputs).length > 0 ? { unknownInputs } : {}),
+  };
 }
 
 /** The members a release gate refuses: provisional ones, which no approval of the document covers (`change-set.mdx`). */

package/src/components/release-promote.test.ts

@@ -7,7 +7,7 @@ import { describe, test, expect } from "vitest";
 import { contentDigest } from "../content-digest";
 import { makeRelease, templateBytesDigest } from "../lifecycle/release-store";
 import type { DriverComponent } from "./driver";
-import { isImplicitRelease, pinReleaseTemplates, releaseArtifactMismatches, removePinnedTemplates, targetFiles, targetFor, writePinnedTemplates, RELEASE_TEMPLATES_DIR } from "./release-promote";
+import { isImplicitRelease, pinReleaseTemplates, releaseTemplatesDigest, releaseArtifactMismatches, removePinnedTemplates, targetFiles, targetFor, writePinnedTemplates, RELEASE_TEMPLATES_DIR } from "./release-promote";
 import type { ReleaseRecord } from "../lifecycle/release-ledger";
 import type { BuildArchiveManifest } from "./verbs/build-archive";
 import { withTestDir } from "@intentius/chant-test-utils";
@@ -210,3 +210,26 @@ describe("removePinnedTemplates (#4045)", () => {
     });
   });
 });
+
+describe("releaseTemplatesDigest (#4222)", () => {
+  const target = {
+    env: "staging",
+    params: [],
+    templates: [
+      { component: "infra", path: "b.json", digest: "sha256:b" },
+      { component: "infra", path: "a.json", digest: "sha256:a" },
+      { component: "app", path: "c.json", digest: "sha256:c" },
+    ],
+  };
+
+  test("digests the component's templates sorted by path, whatever order the target lists them", () => {
+    const reordered = { ...target, templates: [target.templates[1], target.templates[2], target.templates[0]] };
+    expect(releaseTemplatesDigest(target, "infra")).toBe(contentDigest("a.json\tsha256:a\nb.json\tsha256:b\n"));
+    expect(releaseTemplatesDigest(reordered, "infra")).toBe(releaseTemplatesDigest(target, "infra"));
+    expect(releaseTemplatesDigest(target, "app")).not.toBe(releaseTemplatesDigest(target, "infra"));
+  });
+
+  test("is null for a component the target records no template for", () => {
+    expect(releaseTemplatesDigest(target, "worker")).toBeNull();
+  });
+});

package/src/components/release-promote.ts

@@ -31,6 +31,7 @@ import { templateBytesDigest, type Release, type ReleaseTarget } from "../lifecy
 import { computePlanDigest } from "../lifecycle/plan-digest";
 import type { ReleaseRecord } from "../lifecycle/release-ledger";
 import type { BuildArchiveManifest } from "./verbs/build-archive";
+import { contentDigest } from "../content-digest";
 
 /** Where a promote under a release writes the recorded templates, relative to the member's directory. */
 export const RELEASE_TEMPLATES_DIR = ".chant/release-templates";
@@ -56,6 +57,20 @@ export function targetFor(release: Release, env: string): { target: ReleaseTarge
   };
 }
 
+/**
+ * The digest a release record carries for a component with no artifact
+ * (#4222): `sha256:` over the paths and digests of the templates `target`
+ * records for `component`, sorted by path. A template-only component (a
+ * `cfn-deploy` with no publish step) deployed under a release is recorded with
+ * it, so promote and rollback under a release find what the environment runs.
+ * Null when the target records no template for the component.
+ */
+export function releaseTemplatesDigest(target: ReleaseTarget, component: string): string | null {
+  const own = target.templates.filter((t) => t.component === component).map((t) => `${t.path}\t${t.digest}`).sort();
+  if (own.length === 0) return null;
+  return contentDigest(`${own.join("\n")}\n`);
+}
+
 /** Whether a release is of a project with no components (#4046): no artifact, and every template it records has `component: null`. */
 export function isImplicitRelease(release: Release): boolean {
   const templates = release.targets.flatMap((t) => t.templates);

package/src/deep-observation.ts

@@ -334,6 +334,14 @@ export interface DeepNormalizationHooks {
    * or a value-derived hash.
    */
   mask?(node: DeepNode): boolean;
+  /**
+   * Rewrite one raw property tree before anything else reads it, on both
+   * sides. For a difference no per-node hook can reach, such as a map whose
+   * keys are references: an ARM `identity.userAssignedIdentities` is keyed by
+   * `[resourceId(...)]` in source and by the evaluated resource id live
+   * (#4231). Return the tree to compare; leave anything else as it was.
+   */
+  prepare?(tree: Record<string, unknown>, context: { entityType: string; side: DeepSide }): Record<string, unknown>;
 }
 
 /** Everything the pass needs besides the tree itself. */

package/src/graph-declared-exports.test.ts

@@ -0,0 +1,40 @@
+import { describe, test, expect, vi } from "vitest";
+
+/**
+ * Side-by-side stacks keep their exports and imports (#4202). The live overlay
+ * builds the declared canvas per stack, and that canvas dropped the member's
+ * exports, so a workspace viewer had nothing to join another member's import
+ * to once an environment was picked.
+ */
+vi.mock("./discovery/index", () => ({ discover: vi.fn(async () => ({ entities: new Map(), errors: [] })) }));
+vi.mock("./graph-ir", () => ({
+  buildGraphIr: vi.fn(() => ({
+    nodes: [
+      { id: "webAlb", kind: "AWS::ElasticLoadBalancingV2::LoadBalancer", lexicon: "aws" },
+      { id: "zoneId", kind: "AWS::CloudFormation::Parameter", lexicon: "aws" },
+    ],
+    edges: [],
+    groups: {},
+    exports: [{ name: "awsEndpoint", node: "webAlb", attr: "DNSName" }],
+    imports: [{ name: "zoneId", node: "zoneId" }],
+  })),
+}));
+
+const { buildDeclaredPerStack } = await import("./graph-declared");
+
+describe("buildDeclaredPerStack keeps exports and imports (#4202)", () => {
+  test("an export's node is qualified like the nodes, and its name is unchanged", async () => {
+    const ir = await buildDeclaredPerStack([{ name: "three-cloud-aws", src: "src" }], "/project");
+    expect(ir.nodes.map((n) => n.id)).toContain("three-cloud-aws::webAlb");
+    expect(ir.exports).toEqual([{ name: "awsEndpoint", node: "three-cloud-aws::webAlb", attr: "DNSName" }]);
+    expect(ir.imports).toEqual([{ name: "zoneId", node: "three-cloud-aws::zoneId" }]);
+    const ids = new Set(ir.nodes.map((n) => n.id));
+    for (const e of ir.exports ?? []) expect(ids.has(e.node!)).toBe(true);
+  });
+
+  test("a stack without src brings no exports", async () => {
+    const ir = await buildDeclaredPerStack([{ name: "unbuilt" }], "/project");
+    expect(ir.exports).toBeUndefined();
+    expect(ir.imports).toBeUndefined();
+  });
+});

package/src/graph-declared.test.ts

@@ -84,3 +84,21 @@ describe("buildDeclaredPerStack groups by declared stack (#1433)", () => {
     }
   });
 });
+
+describe("buildDeclaredPerStack takes edges from the lexicon hooks (#4232)", () => {
+  test("withEdges sees each stack's entities by bare key, and its edges are qualified with the stack", async () => {
+    const seen: string[][] = [];
+    const ir = await buildDeclaredPerStack(
+      [{ name: "network", src: "network/src" }, { name: "app", src: "app/src" }],
+      dir,
+      (g, entities) => {
+        seen.push([...entities.keys()].sort());
+        const [only] = g.nodes;
+        return only ? { ...g, edges: [...g.edges, { from: only.id, to: only.id, kind: "ref", viaAttr: "self" }] } : g;
+      },
+    );
+    expect(seen).toEqual([["vpc"], ["service"]]);
+    expect(ir.edges).toContainEqual({ from: "network::vpc", to: "network::vpc", kind: "ref", viaAttr: "self" });
+    expect(ir.edges).toContainEqual({ from: "app::service", to: "app::service", kind: "ref", viaAttr: "self" });
+  });
+});

package/src/graph-declared.ts

@@ -1,5 +1,6 @@
 import { resolve } from "node:path";
 import { discover } from "./discovery/index";
+import type { Declarable } from "./declarable";
 import { buildGraphIr, type GraphIR, type IRNode } from "./graph-ir";
 
 /**
@@ -13,15 +14,25 @@ import { buildGraphIr, type GraphIR, type IRNode } from "./graph-ir";
  * that live side, build each stack's `src` in isolation and qualify its node ids
  * and edge endpoints the same way. Stacks are merged into one graph.
  *
+ * Each stack's exports and imports come along with their `node` qualified the
+ * same way (#4202), so a workspace viewer can still match an import in another
+ * member to an export here once an environment is picked.
+ *
  * A stack without `src` contributes nothing here — it has no declared source to
  * scope to (its live nodes still show as foreign in the overlay).
+ *
+ * `withEdges` adds what the lexicons' `graphEdges` hooks resolve to each
+ * stack's graph before its ids are qualified (#4232).
  */
 export async function buildDeclaredPerStack(
   stacks: Array<{ name: string; src?: string }>,
   projectPath: string,
+  withEdges?: (ir: GraphIR, entities: Map<string, Declarable>) => GraphIR,
 ): Promise<GraphIR> {
   const nodes: IRNode[] = [];
   const edges: GraphIR["edges"] = [];
+  const exports: NonNullable<GraphIR["exports"]> = [];
+  const imports: NonNullable<GraphIR["imports"]> = [];
   // Which nodes belong to which stack (#1433). This is not derived or guessed:
   // the stack is declared in config and every node here is being renamed with
   // its name on the line below. The membership was always known and thrown
@@ -30,7 +41,9 @@ export async function buildDeclaredPerStack(
   const byStack: Record<string, string[]> = {};
   for (const st of stacks) {
     if (!st.src) continue;
-    const g = buildGraphIr((await discover(resolve(projectPath, st.src))).entities, projectPath);
+    const { entities } = await discover(resolve(projectPath, st.src));
+    const built = buildGraphIr(entities, projectPath);
+    const g = withEdges ? withEdges(built, entities) : built;
     const q = (id: string) => `${st.name}::${id}`;
     for (const n of g.nodes) {
       const id = q(n.id);
@@ -38,8 +51,10 @@ export async function buildDeclaredPerStack(
       (byStack[st.name] ??= []).push(id);
     }
     for (const e of g.edges) edges.push({ ...e, from: q(e.from), to: q(e.to) });
+    for (const e of g.exports ?? []) exports.push({ ...e, ...(e.node ? { node: q(e.node) } : {}) });
+    for (const i of g.imports ?? []) imports.push({ ...i, node: q(i.node) });
   }
   for (const ids of Object.values(byStack)) ids.sort();
   const groups: GraphIR["groups"] = Object.keys(byStack).length ? { byStack } : {};
-  return { nodes, edges, groups };
+  return { nodes, edges, groups, ...(exports.length ? { exports } : {}), ...(imports.length ? { imports } : {}) };
 }

package/src/graph-detail.test.ts

@@ -1,6 +1,6 @@
 import { describe, test, expect } from "vitest";
 import { applyDetail, DETAIL, detailInertNotice } from "./graph-detail";
-import type { GraphIR } from "./graph-ir";
+import { overlayGraphs, sourceOverlayGraphs, type GraphIR } from "./graph-ir";
 
 // A small graph: a gcp vpc/subnet pair plus a k8s namespace and deployment that
 // came from one composite instance ("db"), with the deployment referencing the
@@ -294,3 +294,70 @@ describe("detailInertNotice (#1489)", () => {
     expect(detailInertNotice(edgeless, detailed)).toContain("no edges at all");
   });
 });
+
+describe("T1 rolls a composite's overlay status up from its members (#4227)", () => {
+  // Two stacks' worth of one FargateAlb, keyed `${stack}::${logicalId}` as a
+  // multi-stack live read keys them (#1162).
+  const member = (id: string, attrs: Record<string, unknown> = {}) => ({
+    id: `three-cloud-aws::${id}`,
+    kind: "Resource",
+    lexicon: "aws",
+    compositeParent: "FargateAlb",
+    compositeInstance: "web",
+    attrs,
+  });
+  const declared: GraphIR = {
+    nodes: [member("webAlb"), member("webService"), member("webTaskDef")],
+    edges: [],
+    groups: { byLexicon: {} },
+  };
+  const live = (ids: string[], extra: GraphIR["nodes"] = []): GraphIR => ({
+    nodes: [...ids.map((id) => ({ id: `three-cloud-aws::${id}`, kind: "Resource", lexicon: "aws", attrs: {} })), ...extra],
+    edges: [],
+    groups: { byLexicon: {} },
+  });
+  const web = (ir: GraphIR) => applyDetail(ir, DETAIL.COMPOSITES).nodes.find((n) => n.id === "web")!;
+  const all = ["webAlb", "webService", "webTaskDef"];
+
+  test("every member good gives good, on either anchor", () => {
+    for (const ir of [sourceOverlayGraphs(declared, live(all)), overlayGraphs(live(all), declared)]) {
+      expect(web(ir).attrs).toEqual({ members: 3, _status: "good" });
+    }
+  });
+
+  test("an absent member makes the composite pending, and is named", () => {
+    for (const ir of [sourceOverlayGraphs(declared, live(["webAlb", "webTaskDef"])), overlayGraphs(live(["webAlb", "webTaskDef"]), declared)]) {
+      expect(web(ir).attrs).toEqual({ members: 3, _status: "accent", _memberStatus: { accent: ["three-cloud-aws::webService"] } });
+    }
+  });
+
+  test("an unobserved member gives neutral, and an absent one outranks it", () => {
+    const unobserved = { "three-cloud-aws::webTaskDef": { reason: "unsupported-kind" } } as never;
+    expect(web(sourceOverlayGraphs(declared, live(["webAlb", "webService"]), { unobserved })).attrs).toEqual({
+      members: 3,
+      _status: "neutral",
+      _memberStatus: { neutral: ["three-cloud-aws::webTaskDef"] },
+    });
+    expect(web(sourceOverlayGraphs(declared, live(["webAlb"]), { unobserved })).attrs).toEqual({
+      members: 3,
+      _status: "accent",
+      _memberStatus: { accent: ["three-cloud-aws::webService"], neutral: ["three-cloud-aws::webTaskDef"] },
+    });
+  });
+
+  test("a foreign resource stays its own node and leaves the composite good", () => {
+    const foreign = { id: "three-cloud-aws::strayBucket", kind: "Bucket", lexicon: "aws", attrs: {} };
+    const ir = applyDetail(sourceOverlayGraphs(declared, live(all, [foreign])), DETAIL.COMPOSITES);
+    expect(ir.nodes.find((n) => n.id === "web")!.attrs).toEqual({ members: 3, _status: "good" });
+    expect(ir.nodes.find((n) => n.id === foreign.id)!.attrs).toEqual({ _status: "warn" });
+  });
+
+  test("a member painted with a status the rollup does not know is never hidden", () => {
+    const ir: GraphIR = { ...declared, nodes: [member("webAlb", { _status: "good" }), member("webService", { _status: "drifted" })] };
+    expect(web(ir).attrs).toEqual({ members: 2, _status: "drifted", _memberStatus: { drifted: ["three-cloud-aws::webService"] } });
+  });
+
+  test("a graph read without --overlay carries no _status on the composite", () => {
+    expect(web(declared).attrs).toEqual({ members: 3 });
+  });
+});

package/src/graph-detail.ts

@@ -124,6 +124,34 @@ function toDeclarables(ir: GraphIR): GraphIR {
   return { ...ir, nodes: ir.nodes.map((n) => ({ ...n, attrs: resourceAttrs(n.attrs) })) };
 }
 
+/** Overlay statuses from the least to the most in need of attention: a
+ * composite takes its worst member's (#4227). An unknown status ranks above
+ * `warn`, so a status this list does not know yet is never hidden. */
+const STATUS_RANK = ["good", "runtime", "neutral", "accent", "warn"];
+
+function statusRank(status: string): number {
+  const i = STATUS_RANK.indexOf(status);
+  return i === -1 ? STATUS_RANK.length : i;
+}
+
+/** A collapsed composite's overlay paint, rolled up from its members (#4227):
+ * `_status` is the worst member status, and `_memberStatus` lists the members
+ * that are not `good` under their status. Nothing when no member carries a
+ * `_status`, as in a graph read without `--overlay`. */
+function rollupStatus(members: IRNode[]): Record<string, unknown> {
+  const painted = members.filter((m) => typeof m.attrs._status === "string");
+  if (painted.length === 0) return {};
+  let worst = "good";
+  const notGood: Record<string, string[]> = {};
+  for (const m of painted) {
+    const status = m.attrs._status as string;
+    if (statusRank(status) > statusRank(worst)) worst = status;
+    if (status !== "good") (notGood[status] ??= []).push(m.id);
+  }
+  for (const ids of Object.values(notGood)) ids.sort();
+  return { _status: worst, ...(Object.keys(notGood).length > 0 ? { _memberStatus: notGood } : {}) };
+}
+
 /** T1 — collapse each composite instance to one node; internal edges disappear.
  * Topology view: surviving plain nodes keep only overlay paint, not properties. */
 function toComposites(ir: GraphIR): GraphIR {
@@ -169,7 +197,7 @@ function toComposites(ir: GraphIR): GraphIR {
       id: collapsedId.get(key)!,
       kind: types.size === 1 ? [...types][0] : "Composite",
       lexicon: lexicons.size === 1 ? [...lexicons][0] : "multi",
-      attrs: { members: members.length },
+      attrs: { members: members.length, ...rollupStatus(members) },
     });
   }
 

package/src/graph-ir.ts

@@ -1078,13 +1078,21 @@ function tagStatus(n: IRNode, status: OverlayNodeStatus, unobserved?: Unobserved
  * no live edges). Sorted; the live groups pass through unchanged.
  */
 export function overlayGraphs(live: GraphIR, declared: GraphIR, opts?: OverlayOptions): GraphIR {
-  const declaredIds = new Set(declared.nodes.map((n) => n.id));
+  const declaredById = new Map(declared.nodes.map((n) => [n.id, n]));
   const liveIds = new Set(live.nodes.map((n) => n.id));
   const unobserved = opts?.unobserved ?? {};
 
-  const nodes: IRNode[] = live.nodes.map((n) =>
-    tagStatus(n, declaredIds.has(n.id) ? "good" : n.runtimeOwner ? "runtime" : "warn"),
-  );
+  const nodes: IRNode[] = live.nodes.map((n) => {
+    const d = declaredById.get(n.id);
+    if (!d) return tagStatus(n, n.runtimeOwner ? "runtime" : "warn");
+    // A managed node keeps the composite it was declared in, so `--detail 1`
+    // collapses it with its siblings and rolls their status up (#4227).
+    const membership = {
+      ...(d.compositeInstance ? { compositeInstance: d.compositeInstance } : {}),
+      ...(d.compositeParent ? { compositeParent: d.compositeParent } : {}),
+    };
+    return tagStatus({ ...n, ...membership }, "good");
+  });
   for (const n of declared.nodes) {
     if (liveIds.has(n.id)) continue;
     const u = unobserved[n.id];

package/src/lifecycle/__fixtures__/publish-fakes.ts

@@ -168,7 +168,8 @@ const { execFileSync } = require("child_process");
 const args = process.argv.slice(2);
 const token = process.env.NODE_AUTH_TOKEN || "";
 const regFile = ${JSON.stringify(log)} + ".registry.json";
-fs.appendFileSync(${JSON.stringify(log)}, JSON.stringify({ args, tokenSet: token !== "" }) + "\\n");
+const userconfig = process.env.NPM_CONFIG_USERCONFIG ? fs.readFileSync(process.env.NPM_CONFIG_USERCONFIG, "utf-8") : "";
+fs.appendFileSync(${JSON.stringify(log)}, JSON.stringify({ args, tokenSet: token !== "", ...(userconfig ? { userconfig } : {}) }) + "\\n");
 console.log("npm notice using //registry.example/:_authToken=" + token);
 console.error("npm notice token " + token);
 const reg = fs.existsSync(regFile) ? JSON.parse(fs.readFileSync(regFile, "utf-8")) : { packages: {} };
@@ -177,6 +178,9 @@ const flag = (name) => { const i = args.indexOf(name); return i < 0 ? null : arg
 const split = (spec) => { const at = spec.lastIndexOf("@"); return [spec.slice(0, at), spec.slice(at + 1)]; };
 if (args[0] === "publish") {
   if (process.env.FAKE_NPM_FAIL && args[1] && args[1].includes(process.env.FAKE_NPM_FAIL)) { console.error("npm error 403 Forbidden"); process.exit(1); }
+  // A package whose trusted-publisher record is broken: only a token in the user config publishes it.
+  if (process.env.FAKE_NPM_NEEDAUTH && args[1] && args[1].includes(process.env.FAKE_NPM_NEEDAUTH) && !userconfig.includes("_authToken=")) { console.error("npm error code ENEEDAUTH"); process.exit(1); }
+  if (process.env.FAKE_NPM_TOKEN_NO_PROVENANCE && userconfig && args.includes("--provenance")) { console.error("npm error 422 Unprocessable Entity - provenance statement does not match the publisher"); process.exit(1); }
   const text = fs.statSync(args[1]).isDirectory() ? fs.readFileSync(path.join(args[1], "package.json"), "utf-8") : execFileSync("tar", ["-xzOf", args[1], "package/package.json"], { encoding: "utf-8" });
   const { name, version } = JSON.parse(text);
   const p = reg.packages[name] || (reg.packages[name] = { versions: [], distTags: {} });