@intentius/chant 0.124.32 → 0.124.34

package/src/components/release-promote.ts

@@ -11,14 +11,24 @@
  * under `.chant/release-templates/<digest>/` in the member's directory and the
  * step reads them from there. The path is relative and fixed by the digest,
  * so a gate approval bound to the promote's plan still matches on a re-run.
+ *
+ * A release cut since #4155 (a target with `trees`) records every local path
+ * a deploy step names (`recordedInputRefs`), directories file by file. A
+ * promote points each of them at the recorded copy: a directory is written
+ * under `.chant/release-templates/<digest>/<name>/`, its digest taken over its
+ * files the way a gate's directory digest is (`./deploy-inputs.ts`). A path
+ * outside the template fields that the release does not record, such as a
+ * chart named from a repository, is left as written. A target cut before
+ * #4155 is pinned as it was then: template fields only, other paths read from
+ * the checkout.
  */
 
 import { mkdirSync, readdirSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
-import { contentDigest } from "../content-digest";
 import type { DriverComponent, DriverGate, DriverPhase, DriverStep } from "./driver";
-import { TEMPLATE_FIELDS, templateRefs } from "./release-compile";
-import type { Release, ReleaseTarget } from "../lifecycle/release-store";
+import { recordedFields, recordedInputRefs, TEMPLATE_FIELDS, templateRefs, type RecordedInputRef } from "./release-compile";
+import { templateBytesDigest, type Release, type ReleaseTarget } from "../lifecycle/release-store";
+import { computePlanDigest } from "../lifecycle/plan-digest";
 import type { ReleaseRecord } from "../lifecycle/release-ledger";
 import type { BuildArchiveManifest } from "./verbs/build-archive";
 
@@ -29,9 +39,14 @@ export const RELEASE_TEMPLATES_DIR = ".chant/release-templates";
 export interface PinnedTemplate {
   /** Relative to the member's directory. */
   path: string;
+  /** The text, or the base64 of the bytes under `encoding: "base64"`. */
   content: string;
+  encoding?: "base64";
 }
 
+/** Reads a recorded template's stored copy by digest: its text, or its base64 under `base64`. */
+export type TemplateReader = (digest: string, encoding?: "base64") => Promise<string | null>;
+
 /** The release's target for `env`, or an error naming the environments it has. */
 export function targetFor(release: Release, env: string): { target: ReleaseTarget } | { error: string } {
   const target = release.targets.find((t) => t.env === env);
@@ -65,37 +80,45 @@ export async function pinReleaseTemplates(
   components: readonly DriverComponent[],
   release: Release,
   target: ReleaseTarget,
-  readTemplate: (digest: string) => Promise<string | null>,
+  readTemplate: TemplateReader,
 ): Promise<{ components: DriverComponent[]; files: PinnedTemplate[] } | { errors: string[] }> {
   const errors: string[] = [];
   const files: PinnedTemplate[] = [];
   const out: DriverComponent[] = [];
+  // #4155: a target with `trees` records every deploy input; one without was cut before and records template fields only.
+  const full = target.trees !== undefined;
   for (const component of components) {
     const replace = new Map<string, string>();
-    for (const ref of templateRefs(component)) {
+    const refs: RecordedInputRef[] = full ? recordedInputRefs(component) : templateRefs(component).map((r) => ({ ...r, required: true }));
+    for (const ref of refs) {
       if (replace.has(ref.value)) continue;
+      const dir = ref.path.replace(/\/+$/, "");
+      const tree = full ? target.trees!.find((t) => t.component === component.name && t.path === dir) : undefined;
+      if (tree) {
+        const pinned = await pinTree(component.name, tree.path, target, readTemplate);
+        if ("errors" in pinned) errors.push(...pinned.errors);
+        else {
+          files.push(...pinned.files);
+          replace.set(ref.value, pinned.path);
+        }
+        continue;
+      }
       const recorded = target.templates.find((t) => t.component === component.name && t.path === ref.path);
       if (!recorded) {
+        if (!ref.required) continue;
         errors.push(
           `component "${component.name}" reads ${ref.field} "${ref.value}", which release ${release.releaseDigest} does not record for "${target.env}"; ` +
             `this checkout's deploy is not the one the release was compiled from (commit ${release.commit.slice(0, 12)})`,
         );
         continue;
       }
-      const content = await readTemplate(recorded.digest);
-      if (content === null) {
-        errors.push(`component "${component.name}": the bytes of template "${ref.path}" (${recorded.digest}) are not on the chant/lifecycle branch; fetch it and try again`);
-        continue;
-      }
-      const got = contentDigest(content);
-      if (got !== recorded.digest) {
-        errors.push(
-          `component "${component.name}": template "${ref.path}" hashes to ${got}, but the release's target for "${target.env}" records ${recorded.digest}; refusing to deploy it`,
-        );
+      const read = await readChecked(component.name, ref.path, recorded, target, readTemplate);
+      if ("error" in read) {
+        errors.push(read.error);
         continue;
       }
       const path = join(RELEASE_TEMPLATES_DIR, recorded.digest.replace(/:/g, "_"), basename(ref.path));
-      files.push({ path, content });
+      files.push({ path, content: read.content, ...(recorded.encoding ? { encoding: recorded.encoding } : {}) });
       replace.set(ref.value, path);
     }
     const rewrite = (phase: DriverPhase): DriverPhase => ({
@@ -104,7 +127,7 @@ export async function pinReleaseTemplates(
         if (isPhase(step)) return rewrite(step);
         if (isGate(step)) return step;
         const next: DriverStep = { ...step };
-        for (const field of TEMPLATE_FIELDS) {
+        for (const field of full ? recordedFields(step.kind) : TEMPLATE_FIELDS) {
           const v = next[field];
           if (typeof v === "string" && replace.has(v)) next[field] = replace.get(v);
           else if (Array.isArray(v)) next[field] = v.map((x) => (typeof x === "string" && replace.has(x) ? replace.get(x) : x));
@@ -117,6 +140,51 @@ export async function pinReleaseTemplates(
   return errors.length > 0 ? { errors } : { components: out, files };
 }
 
+/** One recorded template's stored copy, checked against its digest. */
+async function readChecked(
+  component: string | null,
+  path: string,
+  recorded: ReleaseTarget["templates"][number],
+  target: ReleaseTarget,
+  readTemplate: TemplateReader,
+): Promise<{ content: string } | { error: string }> {
+  const who = component === null ? "" : `component "${component}": `;
+  const content = await readTemplate(recorded.digest, recorded.encoding);
+  if (content === null) return { error: `${who}the bytes of template "${path}" (${recorded.digest}) are not on the chant/lifecycle branch; fetch it and try again` };
+  const got = templateBytesDigest(content, recorded.encoding);
+  if (got !== recorded.digest) {
+    return { error: `${who}template "${path}" hashes to ${got}, but the release's target for "${target.env}" records ${recorded.digest}; refusing to deploy it` };
+  }
+  return { content };
+}
+
+/**
+ * A recorded directory's files, under `.chant/release-templates/<digest>/<name>/`
+ * (#4155). The digest is taken over the files' paths from the directory and
+ * their bytes, as a gate's directory digest is, so the path names the tree.
+ */
+async function pinTree(
+  component: string,
+  dir: string,
+  target: ReleaseTarget,
+  readTemplate: TemplateReader,
+): Promise<{ path: string; files: PinnedTemplate[] } | { errors: string[] }> {
+  const prefix = `${dir}/`;
+  const entries = target.templates.filter((t) => t.component === component && t.path.startsWith(prefix));
+  const errors: string[] = [];
+  const read: Array<{ rel: string; content: string; encoding?: "base64"; digest: string }> = [];
+  for (const e of entries) {
+    const got = await readChecked(component, e.path, e, target, readTemplate);
+    if ("error" in got) errors.push(got.error);
+    else read.push({ rel: e.path.slice(prefix.length), content: got.content, digest: e.digest, ...(e.encoding ? { encoding: e.encoding } : {}) });
+  }
+  if (errors.length > 0) return { errors };
+  read.sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
+  const digest = computePlanDigest("directory", read.map(({ rel, digest }) => ({ path: rel, digest })));
+  const path = join(RELEASE_TEMPLATES_DIR, digest.replace(/:/g, "_"), basename(dir));
+  return { path, files: read.map((r) => ({ path: join(path, r.rel), content: r.content, ...(r.encoding ? { encoding: r.encoding } : {}) })) };
+}
+
 /**
  * The files a release's target records, read back by digest and checked, for
  * `chant release export` (#4046). A project with no components has no deploy
@@ -129,7 +197,7 @@ export async function pinReleaseTemplates(
 export async function targetFiles(
   release: Release,
   target: ReleaseTarget,
-  readTemplate: (digest: string) => Promise<string | null>,
+  readTemplate: TemplateReader,
 ): Promise<{ files: PinnedTemplate[] } | { errors: string[] }> {
   const errors: string[] = [];
   const files: PinnedTemplate[] = [];
@@ -139,12 +207,12 @@ export async function targetFiles(
       errors.push(`${who}template "${t.path}" is not a path inside the member's directory; refusing to write it`);
       continue;
     }
-    const content = await readTemplate(t.digest);
+    const content = await readTemplate(t.digest, t.encoding);
     if (content === null) {
       errors.push(`${who}the bytes of template "${t.path}" (${t.digest}) are not on the chant/lifecycle branch; fetch it and try again`);
       continue;
     }
-    const got = contentDigest(content);
+    const got = templateBytesDigest(content, t.encoding);
     if (got !== t.digest) {
       errors.push(`${who}template "${t.path}" hashes to ${got}, but release ${release.releaseDigest} records ${t.digest} for "${target.env}"; refusing to write it`);
       continue;
@@ -154,7 +222,7 @@ export async function targetFiles(
       if (same.content !== content) errors.push(`two components record different bytes at "${t.path}" for "${target.env}", so they can't both be written there`);
       continue;
     }
-    files.push({ path: t.path, content });
+    files.push({ path: t.path, content, ...(t.encoding ? { encoding: t.encoding } : {}) });
   }
   return errors.length > 0 ? { errors } : { files };
 }
@@ -164,7 +232,7 @@ export function writePinnedTemplates(dir: string, files: readonly PinnedTemplate
   for (const f of files) {
     const full = join(dir, f.path);
     mkdirSync(dirname(full), { recursive: true });
-    writeFileSync(full, f.content);
+    writeFileSync(full, f.encoding === "base64" ? Buffer.from(f.content, "base64") : f.content);
   }
 }
 
@@ -175,7 +243,9 @@ export function writePinnedTemplates(dir: string, files: readonly PinnedTemplate
  * again from the release.
  */
 export function removePinnedTemplates(dir: string, files: readonly PinnedTemplate[]): void {
-  for (const f of files) rmSync(dirname(join(dir, f.path)), { recursive: true, force: true });
+  // Each file sits under `.chant/release-templates/<digest>/`, a recorded tree's deeper; that digest directory goes.
+  const prefix = RELEASE_TEMPLATES_DIR.split("/").length;
+  for (const f of files) rmSync(join(dir, ...f.path.split(/[\\/]/).slice(0, prefix + 1)), { recursive: true, force: true });
   const root = join(dir, RELEASE_TEMPLATES_DIR);
   try {
     if (readdirSync(root).length === 0) rmdirSync(root);

package/src/components/verbs/bom-writer.ts

@@ -72,7 +72,7 @@ export interface BomPackage {
   /** Version string, when known. Omitted for resources with no version concept (e.g. a CFN resource). */
   version?: string;
   /** Package manager / ecosystem this entry came from (e.g. "npm", "maven"), surfaced in SPDX's `externalRefs`/CycloneDX's `purl` when derivable. */
-  type?: "npm" | "maven" | "config" | "external-reference";
+  type?: "npm" | "maven" | "cargo" | "config" | "external-reference";
   /** Package URL (purl), when derivable — e.g. `pkg:npm/left-pad@1.3.0`. */
   purl?: string;
   /** SPDX download location, when known. Defaults to `"NOASSERTION"` per the SPDX spec's requirement that every package declare one. */

package/src/components/verbs/lockfile-sbom-generator.test.ts

@@ -11,6 +11,7 @@ import { describe, expect, it, afterEach } from "vitest";
 import {
   parseNpmPackageLock,
   parsePomXml,
+  parseCargoLock,
   createLockfileSbomGenerator,
   sbomOutputPath,
 } from "./lockfile-sbom-generator";
@@ -193,3 +194,38 @@ describe("createLockfileSbomGenerator (#613) — hermetic SbomGenerator backend"
     expect(docA.bytes).toBe(docB.bytes);
   });
 });
+
+describe("parseCargoLock (#4168)", () => {
+  const LOCK = [
+    "version = 4",
+    "",
+    "[[package]]",
+    'name = "app"',
+    'version = "0.1.0"',
+    "dependencies = [",
+    ' "serde",',
+    ' "tokio 1.40.0",',
+    "]",
+    "",
+    "[[package]]",
+    'name = "serde"',
+    'version = "1.0.210"',
+    'source = "registry+https://github.com/rust-lang/crates.io-index"',
+    "",
+    "[[package]]",
+    'name = "tokio"',
+    'version = "1.40.0"',
+    'source = "registry+https://github.com/rust-lang/crates.io-index"',
+    "dependencies = [",
+    ' "pin-project-lite",',
+    "]",
+    "",
+  ].join("\n");
+
+  it("lists every package with a source, with its purl and dependencies, and leaves out the workspace's own crates", () => {
+    expect(parseCargoLock(LOCK)).toEqual([
+      { name: "serde", version: "1.0.210", type: "cargo", purl: "pkg:cargo/serde@1.0.210", dependsOn: undefined },
+      { name: "tokio", version: "1.40.0", type: "cargo", purl: "pkg:cargo/tokio@1.40.0", dependsOn: ["pin-project-lite"] },
+    ]);
+  });
+});

package/src/components/verbs/lockfile-sbom-generator.ts

@@ -148,6 +148,44 @@ export function parsePomXml(content: string): BomPackage[] {
   return packages.sort((a, b) => a.name.localeCompare(b.name));
 }
 
+// ── Cargo.lock (Rust, #4168 decision 12) ────────────────────────────────────
+
+/**
+ * Parse a `Cargo.lock` (version 3 or 4) into a flat `BomPackage[]`: one
+ * entry per `[[package]]` with a `source`, so the workspace's own crates,
+ * which have none, are left out as the npm parser leaves out the root.
+ * A dependency is named `name` or `name version` in the lock; only the name
+ * is kept. A small line reader, not a TOML parser: the lock is written by
+ * cargo in one fixed shape.
+ */
+export function parseCargoLock(content: string): BomPackage[] {
+  const seen = new Map<string, BomPackage>();
+  const blocks = content.split(/^\[\[package\]\]\s*$/m).slice(1);
+  for (const block of blocks) {
+    const body = block.split(/^\[/m)[0] ?? "";
+    const field = (key: string) => new RegExp(`^${key}\\s*=\\s*"([^"]*)"`, "m").exec(body)?.[1];
+    const name = field("name");
+    const version = field("version");
+    if (!name || field("source") === undefined) continue;
+    const deps = /^dependencies\s*=\s*\[([\s\S]*?)\]/m.exec(body)?.[1];
+    const dependsOn = deps ? [...deps.matchAll(/"([^"\s]+)[^"]*"/g)].map((m) => m[1]!) : [];
+    const key = `${name}@${version ?? ""}`;
+    if (seen.has(key)) continue;
+    seen.set(key, {
+      name,
+      version,
+      type: "cargo",
+      purl: version ? `pkg:cargo/${encodeURIComponent(name)}@${version}` : undefined,
+      dependsOn: dependsOn.length ? [...new Set(dependsOn)] : undefined,
+    });
+  }
+  return [...seen.values()].sort((a, b) => a.name.localeCompare(b.name) || (a.version ?? "").localeCompare(b.version ?? ""));
+}
+
+/** Each lockfile kind's parser and file name. */
+export const LOCKFILE_PARSERS = { npm: parseNpmPackageLock, maven: parsePomXml, cargo: parseCargoLock } as const;
+export const LOCKFILE_NAMES = { npm: "package-lock.json", maven: "pom.xml", cargo: "Cargo.lock" } as const;
+
 // ── hermetic SbomGenerator backend ───────────────────────────────────────────
 
 export interface LockfileSbomGeneratorOptions {
@@ -158,8 +196,8 @@ export interface LockfileSbomGeneratorOptions {
 }
 
 /** Locate the first readable lockfile/manifest under `dir` this generator knows how to parse, in preference order (npm before Maven — most chant components are Node-first). Returns `undefined` if none is found. */
-function findManifest(dir: string): { kind: "npm" | "maven"; path: string } | undefined {
-  for (const [kind, filename] of [["npm", "package-lock.json"], ["maven", "pom.xml"]] as const) {
+function findManifest(dir: string): { kind: "npm" | "maven" | "cargo"; path: string } | undefined {
+  for (const [kind, filename] of [["npm", "package-lock.json"], ["maven", "pom.xml"], ["cargo", "Cargo.lock"]] as const) {
     const candidate = join(dir, filename);
     try {
       readFileSync(candidate, "utf-8");
@@ -195,13 +233,13 @@ export function createLockfileSbomGenerator(options: LockfileSbomGeneratorOption
     const manifest = findManifest(dir);
     if (!manifest) {
       throw new Error(
-        `no supported lockfile/manifest found under "${dir}" (looked for package-lock.json, pom.xml) — ` +
+        `no supported lockfile/manifest found under "${dir}" (looked for package-lock.json, pom.xml, Cargo.lock) — ` +
           `the hermetic lockfile SBOM backend requires a lockfile on disk; use the deep-scan path (#610) for images with no lockfile`,
       );
     }
     const content = readFileSync(manifest.path, "utf-8");
-    const packages = manifest.kind === "npm" ? parseNpmPackageLock(content) : parsePomXml(content);
-    const generatorName = manifest.kind === "npm" ? "chant-lockfile-sbom/package-lock.json" : "chant-lockfile-sbom/pom.xml";
+    const packages = LOCKFILE_PARSERS[manifest.kind](content);
+    const generatorName = `chant-lockfile-sbom/${LOCKFILE_NAMES[manifest.kind]}`;
 
     const doc = writeBom(
       format,

package/src/components/wave-plan.ts

@@ -13,6 +13,14 @@
  * (`componentPlanDigest`, ./gate-plan.ts, #2574), so a wave mixing roots and
  * other components still has one digest that moves when any of them does.
  *
+ * The files a step without a `plan` deploys from are bound too (#4155,
+ * ./deploy-inputs.ts). A component with no plannable step folds them into its
+ * composition digest. A component with one gets a member more,
+ * `<component>#inputs`, over its other steps' files, so a `lambda-deploy`
+ * source or a Helm chart beside a `cfn-deploy` moves the wave's digest. A step
+ * whose content chant can't name is a hole on that member, so the plan note
+ * lists it as unbound.
+ *
  * Known limit: a step input that reads an earlier step of the same
  * component (`@Phase.field`) has no value before the component runs, so it
  * plans as `undefined`. Cross-component wiring (`stackOutput()`,
@@ -21,6 +29,8 @@
 
 import { resolveStepInput, unresolvedWiringSources, type DriverComponent, type DriverPhase, type DriverStep } from "./driver";
 import { componentPlanDigest } from "./gate-plan";
+import { componentDeployInputs, type ComponentDeployInputs } from "./deploy-inputs";
+import { computePlanDigest } from "../lifecycle/plan-digest";
 import type { CapabilityRegistry, DeployContext, PlannedOutputs } from "./capability";
 import type { WaveMember } from "../gated-waves";
 import type { ChangeSetPart } from "../change-set";
@@ -37,14 +47,18 @@ export type WaveComponentPlan =
   | { component: string; members: WaveMember[]; plans: Record<string, unknown>; parts: ChangeSetPart[]; outputs?: PlannedOutputs }
   | { component: string; error: string };
 
-/** A part with no entries, for a member whose planner describes no changes. */
-function emptyPart(member: WaveMember): ChangeSetPart {
+/** A part with no entries, for a member whose planner describes no changes. `unbound` steps become its holes (#4155). */
+function emptyPart(member: WaveMember, unbound: ComponentDeployInputs["unbound"] = []): ChangeSetPart {
+  const holes = unbound.map((u) => ({ address: `${u.phase}/${u.kind}`, type: u.kind, reason: `unbound: ${u.reason}` }));
   return {
-    member: { member: member.member, lexicon: "chant", planner: "chant", status: "planned", planDigest: member.planDigest, holes: [] },
+    member: { member: member.member, lexicon: "chant", planner: "chant", status: "planned", planDigest: member.planDigest, holes },
     entries: [],
   };
 }
 
+/** The member a planning component's other steps add (#4155): their files, under the component's name. */
+export const inputsMemberName = (component: string): string => `${component}#inputs`;
+
 /** Every capability step in a composition, nested phases included, gates left out. */
 export function capabilitySteps(phases: readonly DriverPhase[]): DriverStep[] {
   const out: DriverStep[] = [];
@@ -99,17 +113,31 @@ export async function planWaveComponent(
       if (planned.artifact !== undefined) plans[planned.member] = planned.artifact;
       if (planned.outputs) outputs = mergePlannedOutputs(outputs, planned.outputs);
     }
+    // #4155: the steps without a plan, which no member above covers.
+    const planless = (step: DriverStep): boolean => !registry.has(step.kind) || registry.resolve(step.kind).plan === undefined;
     if (members.length === 0) {
+      const read = componentDeployInputs(component.deploy, process.cwd());
       const member = {
         member: component.name,
         planDigest: componentPlanDigest({
           environment: ctx.env,
           component,
           ...(ctx.vars ? { vars: ctx.vars } : {}),
+          inputs: read.inputs,
         }),
       };
       members.push(member);
-      parts.push(emptyPart(member));
+      parts.push(emptyPart(member, read.unbound));
+    } else {
+      const read = componentDeployInputs(component.deploy, process.cwd(), planless);
+      if (read.inputs.length > 0 || read.unbound.length > 0) {
+        const member = {
+          member: inputsMemberName(component.name),
+          planDigest: computePlanDigest("component-inputs", { environment: ctx.env, component: component.name, inputs: read.inputs }),
+        };
+        members.push(member);
+        parts.push(emptyPart(member, read.unbound));
+      }
     }
     return { component: component.name, members, plans, parts, ...(outputs ? { outputs } : {}) };
   } catch (err) {

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.ts

@@ -13,6 +13,10 @@ 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).
  */
@@ -22,6 +26,8 @@ export async function buildDeclaredPerStack(
 ): 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
@@ -38,8 +44,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

@@ -87,6 +87,63 @@ describe("applyDetail", () => {
     expect(ir.imports).toEqual([{ name: "pClusterArn", node: "pClusterArn" }]);
   });
 
+  test("T1 keeps exports, each on the node that now holds its producer (#4178)", () => {
+    const withExports: GraphIR = {
+      ...base,
+      version: 2,
+      meta: { _behaviour: { engine: "x" } },
+      exports: [
+        { name: "DbEndpoint", node: "dbDeployment", attr: "status" },
+        { name: "SubnetLink", node: "subnet", attr: "selfLink" },
+        { name: "Literal" },
+      ],
+    };
+    const ir = applyDetail(withExports, DETAIL.COMPOSITES);
+    expect(ir.exports).toEqual([
+      { name: "DbEndpoint", node: "db", attr: "status" },
+      { name: "SubnetLink", node: "subnet", attr: "selfLink" },
+      { name: "Literal" },
+    ]);
+    expect(ir.version).toBe(2);
+    expect(ir.meta).toEqual({ _behaviour: { engine: "x" } });
+  });
+
+  test("T1 keeps two same-named composites from different composite types apart (#4178)", () => {
+    const twoWebs: GraphIR = {
+      nodes: [
+        { id: "webAlb", kind: "AWS::ElasticLoadBalancingV2::LoadBalancer", lexicon: "aws", compositeParent: "FargateAlb", compositeInstance: "web", attrs: {} },
+        { id: "webService", kind: "AWS::ECS::Service", lexicon: "aws", compositeParent: "FargateAlb", compositeInstance: "web", attrs: {} },
+        { id: "webRun", kind: "RunService", lexicon: "gcp", compositeParent: "CloudRunServiceComposite", compositeInstance: "web", attrs: {} },
+        { id: "record", kind: "AWS::Route53::RecordSet", lexicon: "aws", attrs: {} },
+      ],
+      edges: [
+        { from: "record", to: "webAlb", kind: "ref", viaAttr: "AliasTarget" },
+        { from: "record", to: "webRun", kind: "ref", viaAttr: "ResourceRecords" },
+        { from: "webService", to: "webAlb", kind: "ref", viaAttr: "LoadBalancers" },
+      ],
+      groups: {},
+      exports: [{ name: "WebUri", node: "webRun", attr: "uri" }],
+    };
+    const ir = applyDetail(twoWebs, DETAIL.COMPOSITES);
+    expect(ir.nodes.map((n) => n.id)).toEqual(["record", "web@CloudRunServiceComposite", "web@FargateAlb"]);
+    expect(ir.nodes.find((n) => n.id === "web@FargateAlb")).toMatchObject({ kind: "FargateAlb", lexicon: "aws", attrs: { members: 2 } });
+    expect(ir.nodes.find((n) => n.id === "web@CloudRunServiceComposite")).toMatchObject({ kind: "CloudRunServiceComposite", lexicon: "gcp", attrs: { members: 1 } });
+    expect(ir.edges).toEqual(expect.arrayContaining([
+      { from: "record", to: "web@FargateAlb", kind: "ref" },
+      { from: "record", to: "web@CloudRunServiceComposite", kind: "ref" },
+    ]));
+    expect(ir.edges).toHaveLength(2);
+    expect(ir.exports).toEqual([{ name: "WebUri", node: "web@CloudRunServiceComposite", attr: "uri" }]);
+  });
+
+  test("T1 keeps one composite whose members span lexicons as one node", () => {
+    const ir = applyDetail({
+      ...base,
+      nodes: base.nodes.map((n) => (n.id === "dbNamespace" ? { ...n, lexicon: "gcp" } : n)),
+    }, DETAIL.COMPOSITES);
+    expect(ir.nodes.find((n) => n.id === "db")).toMatchObject({ kind: "DbStack", lexicon: "multi", attrs: { members: 2 } });
+  });
+
   test("T1 node count is between T0 and T2", () => {
     const t0 = applyDetail(base, DETAIL.STACKS).nodes.length;
     const t1 = applyDetail(base, DETAIL.COMPOSITES).nodes.length;

package/src/graph-detail.ts

@@ -127,27 +127,46 @@ function toDeclarables(ir: GraphIR): GraphIR {
 /** 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 {
-  const idMap = new Map<string, string>();
-  for (const n of ir.nodes) idMap.set(n.id, n.compositeInstance ?? n.id);
-
+  // A composite instance is its export name plus the composite that made it:
+  // an AWS FargateAlb and a GCP CloudRunServiceComposite both exported as
+  // `web` are two instances (#4178). One composite whose members span
+  // lexicons stays one instance.
+  const instanceKey = (n: IRNode) => `${n.compositeInstance}\0${n.compositeParent ?? ""}`;
   const instances = new Map<string, IRNode[]>();
   const plain: IRNode[] = [];
   for (const n of ir.nodes) {
     if (n.compositeInstance) {
-      const arr = instances.get(n.compositeInstance) ?? [];
+      const key = instanceKey(n);
+      const arr = instances.get(key) ?? [];
       arr.push(n);
-      instances.set(n.compositeInstance, arr);
+      instances.set(key, arr);
     } else {
       plain.push({ ...n, attrs: paintAttrs(n.attrs) });
     }
   }
 
+  // The collapsed id is the instance name, or `<instance>@<composite>` when
+  // two composites share the name.
+  const sharing = new Map<string, number>();
+  for (const members of instances.values()) {
+    const inst = members[0].compositeInstance!;
+    sharing.set(inst, (sharing.get(inst) ?? 0) + 1);
+  }
+  const collapsedId = new Map<string, string>();
+  for (const [key, members] of instances) {
+    const { compositeInstance: inst, compositeParent: parent } = members[0];
+    collapsedId.set(key, sharing.get(inst!)! > 1 && parent ? `${inst}@${parent}` : inst!);
+  }
+
+  const idMap = new Map<string, string>();
+  for (const n of ir.nodes) idMap.set(n.id, n.compositeInstance ? collapsedId.get(instanceKey(n))! : n.id);
+
   const nodes: IRNode[] = [...plain];
-  for (const [inst, members] of instances) {
+  for (const [key, members] of instances) {
     const types = new Set(members.map((m) => m.compositeParent).filter(Boolean) as string[]);
     const lexicons = new Set(members.map((m) => m.lexicon));
     nodes.push({
-      id: inst,
+      id: collapsedId.get(key)!,
       kind: types.size === 1 ? [...types][0] : "Composite",
       lexicon: lexicons.size === 1 ? [...lexicons][0] : "multi",
       attrs: { members: members.length },
@@ -197,11 +216,18 @@ function toComposites(ir: GraphIR): GraphIR {
     }
     if (Object.keys(byPipeline).length) groups.byPipeline = byPipeline;
   }
+  // Exports (#4178) stay at this tier, each on the node that now holds its
+  // producer, so a viewer can still match another member's import to it.
+  const exports = ir.exports?.map((x) => (x.node ? { ...x, node: idMap.get(x.node) ?? x.node } : { ...x }));
   return {
+    ...(ir.version !== undefined ? { version: ir.version } : {}),
     nodes,
     edges: sortEdges([...seen.values()]),
     groups,
+    ...(ir.meta ? { meta: ir.meta } : {}),
+    ...(exports && exports.length ? { exports } : {}),
     ...(imports && imports.length ? { imports } : {}),
+    ...(ir.pipeline ? { pipeline: ir.pipeline } : {}),
     ...(dangling && dangling.length ? { dangling } : {}),
   };
 }