@intentius/chant 0.124.33 → 0.124.34

package/dist/components/promote-rounds.d.ts

@@ -0,0 +1,102 @@
+/**
+ * A promote under a release that plans again once an upstream applied, and a
+ * gate per wave (#4168 step 4). Merging deploys nothing since step 1, so what
+ * `pr-apply` did on merge happens here, at promote:
+ *
+ * - **Rounds** (#3999's rule, `../pr-loop.ts`). The release gate approves a
+ *   change set in which each dependent was planned against its upstream's
+ *   planned outputs (`planReleaseSet` in ./release-gate.ts). The promote runs
+ *   a wave at a time. Before a wave runs, a component whose plan read an
+ *   upstream output that the run left as another value
+ *   (`movedWiringReferences`) is planned again against what stands. When the
+ *   approved change set covers the new plan (`waveNotCovered`, the test a
+ *   pull request's resume uses), it applies under the approval it has.
+ *   Otherwise its gates are decided as `<gate>-round-<n>` (`prRoundGate`),
+ *   bound to the new plan's digest.
+ * - **A gate per wave** (`--wave-gate <gate>`, #4157's rule). Every wave
+ *   after the first is planned again against what the waves before it left,
+ *   and a wave the approved change set does not cover waits at
+ *   `<gate>-wave-<k>` (`waveGateName`), one gate for the whole wave, bound to
+ *   that wave's digest.
+ *
+ * A stage whose components declare no gate has nowhere to wait, so the
+ * promote stops there with nothing more deployed.
+ *
+ * A promote that stops at a round's or a wave's gate writes a resume record
+ * ({@link PromoteResume}): the components that applied and the outputs they
+ * left. The same promote run again with it skips what applied and carries on
+ * from the wave it stopped at, so an approval of the round or wave it waits on
+ * is decided against the same plan.
+ */
+import { type DriverComponent, type DriverRunResult, type ReleaseGateBinding } from "./driver.js";
+import type { ChangeSetDocument } from "../change-set.js";
+import type { ReleasePlan } from "./release-gate.js";
+export declare const PROMOTE_RESUME_SCHEMA = "chant-promote-resume/v1";
+/** What a promote that stopped at a round's or a wave's gate leaves for the next attempt. */
+export interface PromoteResume {
+    schema: typeof PROMOTE_RESUME_SCHEMA;
+    env: string;
+    releaseDigest: string;
+    /** The change set the release gate approved before anything applied. */
+    approvedDigest: string;
+    /** Components that applied, in run order. */
+    completed: string[];
+    /** The outputs standing after them. */
+    outputs: Record<string, Record<string, unknown>>;
+    /** ISO 8601. */
+    at: string;
+}
+/** One round or wave that needed its own approval. */
+export interface PromoteStage {
+    kind: "round" | "wave";
+    /** The round number (2 and up) or the wave number (1-based). */
+    number: number;
+    components: string[];
+    /** The plan the stage's gates bind. */
+    digest: string;
+    /** Why the approved change set did not cover it, one line per member. */
+    notCovered: string[];
+    status: "applied" | "waiting" | "failed";
+    /** With `failed` before anything ran: why. */
+    message?: string;
+}
+export interface PromoteRoundsOptions {
+    /** The promoted compositions, in no particular order. */
+    components: DriverComponent[];
+    /** Outputs standing before the run: the seeds, and on a resume the record's. */
+    outputs: Record<string, Record<string, unknown>>;
+    /** The release gate the change set was approved under. */
+    binding: ReleaseGateBinding;
+    /** The approved change set, and what each component's plan read. */
+    approved: ChangeSetDocument;
+    reads: ReleasePlan["reads"];
+    /** Components an earlier attempt applied. Skipped. */
+    completed?: readonly string[];
+    /** `--wave-gate <gate>`: check every wave after the first, not only the components whose inputs moved, and name a wave's gate `<gate>-wave-<k>`. */
+    waveGate?: string;
+    /** Run one subset of the components with `outputs` standing (`runPromotion` with the binding). */
+    run: (components: DriverComponent[], outputs: Record<string, Record<string, unknown>>, binding: ReleaseGateBinding) => Promise<DriverRunResult>;
+    /** Plan `only` again with `outputs` standing (`planReleaseSet`). */
+    replan: (only: ReadonlySet<string>, outputs: Record<string, Record<string, unknown>>) => Promise<ChangeSetDocument>;
+    /** Store a stage's plan and bind its gates (empty resolutions included). */
+    bind: (doc: ChangeSetDocument, gates: string[]) => Promise<ReleaseGateBinding>;
+}
+export interface PromoteRoundsResult {
+    run: DriverRunResult;
+    /** The rounds and waves that needed their own approval. */
+    stages: PromoteStage[];
+    /** Every component that applied, earlier attempts included, in run order. */
+    completed: string[];
+    outputs: Record<string, Record<string, unknown>>;
+}
+/** `component` with each gate renamed by `rename`, nested phases included. */
+export declare function renameGates(component: DriverComponent, rename: (gate: string) => string): DriverComponent;
+/** The references `component`'s steps make that resolve to another value now than when its plan read them. */
+export declare function movedInputs(component: DriverComponent, read: Record<string, Record<string, unknown>> | undefined, now: Record<string, Record<string, unknown>>): string[];
+/**
+ * Run the promote a wave at a time, planning again where an upstream applied
+ * as another value, and with `waveGate`, checking each wave. Stops at the
+ * first wave that fails or waits on a gate.
+ */
+export declare function runPromotionInRounds(options: PromoteRoundsOptions): Promise<PromoteRoundsResult>;
+//# sourceMappingURL=promote-rounds.d.ts.map

package/dist/components/promote-rounds.d.ts.map

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

package/dist/components/promote-rounds.js

@@ -0,0 +1,174 @@
+/**
+ * A promote under a release that plans again once an upstream applied, and a
+ * gate per wave (#4168 step 4). Merging deploys nothing since step 1, so what
+ * `pr-apply` did on merge happens here, at promote:
+ *
+ * - **Rounds** (#3999's rule, `../pr-loop.ts`). The release gate approves a
+ *   change set in which each dependent was planned against its upstream's
+ *   planned outputs (`planReleaseSet` in ./release-gate.ts). The promote runs
+ *   a wave at a time. Before a wave runs, a component whose plan read an
+ *   upstream output that the run left as another value
+ *   (`movedWiringReferences`) is planned again against what stands. When the
+ *   approved change set covers the new plan (`waveNotCovered`, the test a
+ *   pull request's resume uses), it applies under the approval it has.
+ *   Otherwise its gates are decided as `<gate>-round-<n>` (`prRoundGate`),
+ *   bound to the new plan's digest.
+ * - **A gate per wave** (`--wave-gate <gate>`, #4157's rule). Every wave
+ *   after the first is planned again against what the waves before it left,
+ *   and a wave the approved change set does not cover waits at
+ *   `<gate>-wave-<k>` (`waveGateName`), one gate for the whole wave, bound to
+ *   that wave's digest.
+ *
+ * A stage whose components declare no gate has nowhere to wait, so the
+ * promote stops there with nothing more deployed.
+ *
+ * A promote that stops at a round's or a wave's gate writes a resume record
+ * ({@link PromoteResume}): the components that applied and the outputs they
+ * left. The same promote run again with it skips what applied and carries on
+ * from the wave it stopped at, so an approval of the round or wave it waits on
+ * is decided against the same plan.
+ */
+import { movedWiringReferences } from "./driver.js";
+import { resolveComponentGraph } from "./driver.js";
+import { waveNotCovered } from "./pr-run.js";
+import { prRoundGate } from "../pr-loop.js";
+import { waveGateName } from "../gated-waves.js";
+import { capabilitySteps } from "./wave-plan.js";
+export const PROMOTE_RESUME_SCHEMA = "chant-promote-resume/v1";
+function isGate(step) {
+    return step.kind === "gate";
+}
+function isPhase(step) {
+    return typeof step.phase === "string" && Array.isArray(step.steps);
+}
+/** `component` with each gate renamed by `rename`, nested phases included. */
+export function renameGates(component, rename) {
+    const walk = (phase) => ({
+        ...phase,
+        steps: phase.steps.map((step) => {
+            if (isPhase(step))
+                return walk(step);
+            if (!isGate(step))
+                return step;
+            const { signalName: _old, ...rest } = step;
+            return { ...rest, gate: rename(step.gate ?? step.signalName ?? "") };
+        }),
+    });
+    return { ...component, deploy: component.deploy.map(walk) };
+}
+/** The gate names `components` declare, sorted and distinct. */
+function gatesOf(components) {
+    const names = new Set();
+    const walk = (steps) => {
+        for (const step of steps) {
+            if (isPhase(step))
+                walk(step.steps);
+            else if (isGate(step))
+                names.add(step.gate ?? step.signalName ?? "");
+        }
+    };
+    for (const c of components)
+        for (const phase of c.deploy)
+            walk(phase.steps);
+    return [...names].sort();
+}
+/** The references `component`'s steps make that resolve to another value now than when its plan read them. */
+export function movedInputs(component, read, now) {
+    if (!read)
+        return [];
+    const moved = new Set();
+    for (const step of capabilitySteps(component.deploy)) {
+        const { kind: _kind, ...rest } = step;
+        for (const r of movedWiringReferences(rest, read, now))
+            if (!r.publish)
+                moved.add(r.ref);
+    }
+    return [...moved].sort();
+}
+function joinRuns(runs, outputs) {
+    const last = runs[runs.length - 1];
+    const base = {
+        order: runs.flatMap((r) => r.order),
+        waves: runs.flatMap((r) => r.waves),
+        results: runs.flatMap((r) => r.results),
+        ok: runs.every((r) => r.ok),
+        status: "ok",
+        componentOutputs: outputs,
+    };
+    if (!last || last.status === "ok")
+        return base;
+    const { order: _o, waves: _w, results: _r, ok: _ok, componentOutputs: _c, ...stop } = last;
+    return { ...base, ...stop, ok: false };
+}
+/**
+ * Run the promote a wave at a time, planning again where an upstream applied
+ * as another value, and with `waveGate`, checking each wave. Stops at the
+ * first wave that fails or waits on a gate.
+ */
+export async function runPromotionInRounds(options) {
+    const byName = new Map(options.components.map((c) => [c.name, c]));
+    const { waves } = resolveComponentGraph(options.components.map((c) => ({ ...c, dependsOn: (c.dependsOn ?? []).filter((d) => byName.has(d)) })));
+    const completed = [...(options.completed ?? [])];
+    const done = new Set(completed);
+    let outputs = { ...options.outputs };
+    const runs = [];
+    const stages = [];
+    let round = 1;
+    for (const [index, wave] of waves.entries()) {
+        const waveNumber = index + 1;
+        const pending = wave.filter((name) => !done.has(name));
+        if (pending.length === 0)
+            continue;
+        const check = options.waveGate !== undefined && waveNumber > 1
+            ? pending
+            : pending.filter((name) => movedInputs(byName.get(name), options.reads[name], outputs).length > 0);
+        const batches = [];
+        const rest = pending.filter((name) => !check.includes(name));
+        if (check.length > 0) {
+            const fresh = await options.replan(new Set(check), outputs);
+            const notCovered = waveNotCovered(options.approved, fresh);
+            if (notCovered.length === 0) {
+                rest.push(...check);
+            }
+            else {
+                const kind = options.waveGate !== undefined ? "wave" : "round";
+                if (kind === "round")
+                    round += 1;
+                const number = kind === "wave" ? waveNumber : round;
+                const base = options.waveGate;
+                const rename = (g) => (base !== undefined ? waveGateName(base, number) : prRoundGate(g, number));
+                const renamed = check.map((name) => renameGates(byName.get(name), rename));
+                const gates = gatesOf(renamed);
+                const stage = { kind, number, components: check, digest: fresh.digest, notCovered, status: "waiting" };
+                stages.push(stage);
+                if (gates.length === 0) {
+                    stage.status = "failed";
+                    stage.message = `${check.join(", ")} planned again past the approved change set and declare${check.length === 1 ? "s" : ""} no gate to approve the new plan on`;
+                    const stop = { order: [], waves: [], results: [], ok: false, status: "fail", failedComponent: check[0], componentOutputs: outputs };
+                    return { run: joinRuns([...runs, stop], outputs), stages, completed, outputs };
+                }
+                const binding = await options.bind(fresh, gates);
+                batches.push({ names: check, binding, stage, rename });
+            }
+        }
+        if (rest.length > 0)
+            batches.unshift({ names: pending.filter((n) => rest.includes(n)), binding: options.binding });
+        for (const batch of batches) {
+            const components = batch.names.map((name) => (batch.rename ? renameGates(byName.get(name), batch.rename) : byName.get(name)));
+            const run = await options.run(components, outputs, batch.binding);
+            runs.push(run);
+            outputs = { ...outputs, ...run.componentOutputs };
+            for (const r of run.results) {
+                if (r.status === "ok" && !done.has(r.component)) {
+                    done.add(r.component);
+                    completed.push(r.component);
+                }
+            }
+            if (batch.stage)
+                batch.stage.status = run.status === "ok" ? "applied" : run.status === "gated" ? "waiting" : "failed";
+            if (run.status !== "ok")
+                return { run: joinRuns(runs, outputs), stages, completed, outputs };
+        }
+    }
+    return { run: joinRuns(runs, outputs), stages, completed, outputs };
+}

package/dist/components/release-gate.d.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
@@ -91,6 +99,22 @@ 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[]>;
 }
 /**
  * A component no capability plans, as a `chant` member: what the release
@@ -112,6 +136,12 @@ export declare function chantComponentPart(input: {
  * that fails to plan: it becomes a failed member.
  */
 export declare function planReleaseChangeSet(input: ReleaseChangeSetInput): Promise<ChangeSetDocument>;
+/**
+ * {@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 declare function planReleaseSet(input: ReleaseChangeSetInput): Promise<ReleasePlan>;
 /** The members a release gate refuses: provisional ones, which no approval of the document covers (`change-set.mdx`). */
 export declare function provisionalMembers(doc: ChangeSetDocument): string[];
 /**

package/dist/components/release-gate.d.ts.map

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

package/dist/components/release-gate.js

@@ -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
@@ -51,7 +59,7 @@
  * component a promote, rollback or redeploy left failed or gated with nothing
  * recorded since (#4035): its record names what ran before that run.
  */
-import { deployContext, resolveComponentGraph, resolveStepInput } from "./driver.js";
+import { deployContext, resolveComponentGraph, resolveStepInput, unresolvedWiringReferences } from "./driver.js";
 import { componentPlanDigest } from "./gate-plan.js";
 import { gateName, RELEASE_GATE_OP } from "../op/gate-name.js";
 import { capabilitySteps, planContext, readComponentOutputs } from "./wave-plan.js";
@@ -187,66 +195,108 @@ export function chantComponentPart(input) {
  * that fails to plan: it becomes a failed member.
  */
 export async function planReleaseChangeSet(input) {
+    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) {
     const { release, env, registry } = input;
     const components = [...input.components];
     const byName = new Map(components.map((c) => [c.name, c]));
     const outputs = { ...(input.seededOutputs ?? {}) };
     const read = new Set(Object.keys(outputs));
     const parts = [];
-    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();
+    const planned = {};
+    const unknownInputs = {};
+    const reads = {};
+    const inPlan = (name) => input.only === undefined || input.only.has(name);
+    const isPlannable = (c) => 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;
+            }
+            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();
+                let exposes;
+                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));
+                    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: [],
+                    });
+                }
+                plannedBy.set(name, exposes);
+                if (unknown.size > 0)
+                    unknownInputs[name] = [...unknown].sort();
             }
-            for (const step of plannable) {
-                const { kind, ...rest } = step;
-                const planned = await registry.resolve(kind).plan(planContext(ctx, rest, outputs), resolveStepInput(rest, {}, outputs));
-                parts.push(planned.changeSet ?? {
+            catch (err) {
+                plannedBy.set(name, undefined);
+                parts.push({
                     member: {
-                        member: planned.member,
+                        member: name,
                         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` }],
+                        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`). */
 export function provisionalMembers(doc) {

package/dist/graph-declared.d.ts

@@ -10,6 +10,10 @@ import { type GraphIR } from "./graph-ir.js";
  * 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).
  */

package/dist/graph-declared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph-declared.d.ts","sourceRoot":"","sources":["../src/graph-declared.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,KAAK,OAAO,EAAe,MAAM,YAAY,CAAC;AAErE;;;;;;;;;;;;;GAaG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EAC7C,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,OAAO,CAAC,CAuBlB"}
+{"version":3,"file":"graph-declared.d.ts","sourceRoot":"","sources":["../src/graph-declared.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,KAAK,OAAO,EAAe,MAAM,YAAY,CAAC;AAErE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EAC7C,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,OAAO,CAAC,CA2BlB"}

package/dist/graph-declared.js

@@ -12,6 +12,10 @@ import { buildGraphIr } from "./graph-ir.js";
  * 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).
  */
@@ -19,6 +23,8 @@ export async function buildDeclaredPerStack(stacks, projectPath) {
     var _a;
     const nodes = [];
     const edges = [];
+    const exports = [];
+    const 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
@@ -37,9 +43,13 @@ export async function buildDeclaredPerStack(stacks, projectPath) {
         }
         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 = Object.keys(byStack).length ? { byStack } : {};
-    return { nodes, edges, groups };
+    return { nodes, edges, groups, ...(exports.length ? { exports } : {}), ...(imports.length ? { imports } : {}) };
 }