@intentius/chant 0.33.0 → 0.34.0

package/src/codegen/lexicon-wiring.test.ts

@@ -0,0 +1,53 @@
+/**
+ * chant — the root package.json lexicon list is hand-maintained, and it drifted.
+ *
+ * `chant dev onboard` adds `@intentius/chant-lexicon-<name>` to the root
+ * `dependencies`, but three lexicons (fly, forgejo, fountain) were never added
+ * and nobody noticed, because nothing checks. That is the same shape as the
+ * lexicon-upgrade miswiring (#1218/#1226) and the missing publish wiring that
+ * stranded two packages: a list a human has to remember, with no gate.
+ *
+ * Resolution itself does not depend on this list — `workspaces: ["lexicons/*"]`
+ * symlinks every lexicon into node_modules regardless, which is why the three
+ * omissions never broke anything. The entry is an explicit declaration, and the
+ * point of this test is that it either applies to every lexicon or to none,
+ * rather than silently landing somewhere in between.
+ */
+
+import { describe, expect, it } from "vitest";
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..");
+
+function publishableLexicons(): string[] {
+  return readdirSync(join(repoRoot, "lexicons"))
+    .filter((name) => {
+      const manifest = join(repoRoot, "lexicons", name, "package.json");
+      if (!existsSync(manifest)) return false;
+      return JSON.parse(readFileSync(manifest, "utf-8")).private !== true;
+    })
+    .sort();
+}
+
+function rootLexiconDeps(): string[] {
+  const root = JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf-8"));
+  return Object.keys(root.dependencies ?? {})
+    .filter((dep) => dep.startsWith("@intentius/chant-lexicon-"))
+    .map((dep) => dep.replace("@intentius/chant-lexicon-", ""))
+    .sort();
+}
+
+describe("root package.json lexicon wiring", () => {
+  it("lists every publishable lexicon", () => {
+    expect(rootLexiconDeps()).toEqual(publishableLexicons());
+  });
+
+  it("lists no lexicon that does not exist", () => {
+    const onDisk = new Set(readdirSync(join(repoRoot, "lexicons")));
+    for (const name of rootLexiconDeps()) {
+      expect(onDisk.has(name), `root package.json depends on a missing lexicon "${name}"`).toBe(true);
+    }
+  });
+});

package/src/codegen/release-wiring.test.ts

@@ -0,0 +1,174 @@
+/**
+ * The release path is two hand-maintained halves that must agree: the
+ * justfile recipes that create and push a tag, and publish.yml's tag
+ * trigger that decides whether pushing it does anything.
+ *
+ * They disagreed. `just release-lexicon <name>` has always tagged
+ * `lexicon-<name>-v<version>`, pushed it, and echoed "publish workflow
+ * triggered" — while publish.yml matched only `chant-v*`. The tag landed,
+ * no workflow ran, and the recipe reported success. fly's 0.33.0 shipped
+ * with zero rules and zero skills and could not be patched by the one
+ * recipe built for patching a single lexicon.
+ *
+ * A release that silently no-ops is worse than one that fails, so this
+ * turns the next divergence into a PR-time failure.
+ */
+
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..");
+
+function publishTagPatterns(): string[] {
+  const workflow = readFileSync(join(repoRoot, ".github", "workflows", "publish.yml"), "utf-8");
+  const match = workflow.match(/^\s*tags:\s*\[([^\]]+)\]/m);
+  if (!match) throw new Error("publish.yml: `tags: [...]` trigger not found");
+  return match[1].split(",").map((s) => s.trim().replace(/^['"]|['"]$/g, ""));
+}
+
+/** Tags the justfile actually creates, as literal-prefix + wildcard shapes. */
+function releaseTagShapes(): Array<{ recipe: string; example: string }> {
+  const justfile = readFileSync(join(repoRoot, "justfile"), "utf-8");
+  const shapes: Array<{ recipe: string; example: string }> = [];
+
+  // `git tag "chant-v$next"` / `git tag "lexicon-{{name}}-v$next"`
+  for (const m of justfile.matchAll(/git tag "([^"]+)"/g)) {
+    const raw = m[1];
+    const example = raw
+      .replace(/\{\{name\}\}/g, "docker")
+      .replace(/\$\{?next\}?/g, "9.9.9");
+    shapes.push({ recipe: raw, example });
+  }
+  return shapes;
+}
+
+/** Minimal glob match for the `prefix*` shapes these patterns use. */
+function matchesGlob(pattern: string, value: string): boolean {
+  const rx = new RegExp(
+    "^" + pattern.split("*").map((s) => s.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$",
+  );
+  return rx.test(value);
+}
+
+describe("release wiring: justfile tags vs publish.yml trigger", () => {
+  it("finds both halves", () => {
+    expect(publishTagPatterns().length).toBeGreaterThan(0);
+    expect(releaseTagShapes().length).toBeGreaterThan(0);
+  });
+
+  it("every tag a release recipe pushes triggers the publish workflow", () => {
+    const patterns = publishTagPatterns();
+
+    for (const { recipe, example } of releaseTagShapes()) {
+      const hit = patterns.some((p) => matchesGlob(p, example));
+      expect(
+        hit,
+        `justfile creates tag "${recipe}" (e.g. ${example}) but publish.yml triggers on ` +
+          `[${patterns.join(", ")}] — pushing it would publish nothing while the recipe ` +
+          `reports success`,
+      ).toBe(true);
+    }
+  });
+
+  it("covers the two shapes the repo releases by", () => {
+    const examples = releaseTagShapes().map((s) => s.example);
+    // Whole-repo release and single-lexicon patch. If a recipe stops
+    // producing one of these, the assertion above would pass vacuously.
+    expect(examples).toContain("chant-v9.9.9");
+    expect(examples).toContain("lexicon-docker-v9.9.9");
+  });
+});
+
+/**
+ * The body of one justfile recipe, up to the next top-level recipe header.
+ * Line-based on purpose: a recipe header sits at column 0 and every body line
+ * is indented, which a regex over the whole file gets wrong (`^` under /m
+ * matches the start of the slice too).
+ */
+const RECIPE_HEADER = /^[a-z_][a-z0-9_-]*(\s+[^:]*)?:/;
+
+function recipeBody(name: string): string {
+  const lines = readFileSync(join(repoRoot, "justfile"), "utf-8").split("\n");
+  const start = lines.findIndex((l) => new RegExp(`^${name}(\\s|:)`).test(l));
+  if (start === -1) throw new Error(`justfile: recipe "${name}" not found`);
+
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (RECIPE_HEADER.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join("\n");
+}
+
+/**
+ * #1255.2 — `just release` rewrites the `@intentius/*` peer ranges alongside
+ * `.version` (added in #411, because ranges frozen at `^0.1.0` break clean
+ * installs). `release-lexicon` only set `.version`, so a single-lexicon patch
+ * needing a newer core silently shipped a stale range.
+ *
+ * The two recipes pin to different things on purpose: a whole-repo release
+ * moves everything together so `^$next` is right, while a single-lexicon
+ * patch leaves core where it is, so the range must track the CURRENT core
+ * version. Pinning it to `$next` would demand a core that does not exist —
+ * which is why this asserts the mechanism, not a shared literal.
+ */
+describe("release wiring: peer ranges stay in lockstep (#1255)", () => {
+  it("the whole-repo release rewrites both @intentius peer ranges", () => {
+    const body = recipeBody("release");
+    expect(body).toMatch(/peerDependencies\["@intentius\/chant"\]/);
+    expect(body).toMatch(/peerDependencies\["@intentius\/chant-lexicon-github"\]/);
+  });
+
+  it("the single-lexicon release rewrites them too", () => {
+    const body = recipeBody("release-lexicon");
+    expect(
+      body.includes('peerDependencies["@intentius/chant"]'),
+      "release-lexicon sets .version without touching the @intentius/chant peer range — " +
+        "a lexicon patch that needs a newer core would ship a stale range (#411, #1255)",
+    ).toBe(true);
+    expect(body).toMatch(/peerDependencies\["@intentius\/chant-lexicon-github"\]/);
+  });
+
+  it("the single-lexicon release pins peers to core, not to its own new version", () => {
+    const body = recipeBody("release-lexicon");
+    // It reads the current core version rather than reusing $next.
+    expect(body).toMatch(/jq -r \.version packages\/core\/package\.json/);
+    expect(
+      /peerDependencies\["@intentius\/chant"\]\s*=\s*"\^"\s*\+\s*\$next/.test(body),
+      "release-lexicon must not pin the core peer range to the lexicon's own new version",
+    ).toBe(false);
+  });
+
+  it("both recipes keep the committed lockfile in step", () => {
+    for (const recipe of ["release", "release-lexicon"]) {
+      expect(recipeBody(recipe)).toMatch(/npm install --package-lock-only/);
+    }
+  });
+});
+
+/**
+ * #1255.3 — both recipes pushed the bump commit straight to main, bypassing
+ * branch protection, so a release tag could point at a commit CI never ran.
+ */
+describe("release wiring: preflight gates both recipes (#1255)", () => {
+  it("every release recipe runs the preflight before tagging", () => {
+    for (const recipe of ["release", "release-lexicon"]) {
+      const body = recipeBody(recipe);
+      expect(
+        body.includes("scripts/release-preflight.sh"),
+        `justfile recipe "${recipe}" tags and pushes without running the preflight — ` +
+          "it could release a commit CI never ran (#1255)",
+      ).toBe(true);
+      // Ordering matters: a check that runs after `git tag` proves nothing.
+      expect(body.indexOf("scripts/release-preflight.sh")).toBeLessThan(body.indexOf("git tag"));
+    }
+  });
+
+  it("the whole-repo release requires main, since it pushes main", () => {
+    expect(recipeBody("release")).toMatch(/release-preflight\.sh main/);
+  });
+});

package/src/graph-effective.ts

@@ -106,5 +106,11 @@ export function enrichEffectiveTopology(ir: GraphIR): GraphIR {
       attrs: { ...attrs, effectiveIngress, internetFacing: liveFacing || !!declaredVia, ...(via ? { internetFacingVia: via } : {}) },
     };
   });
-  return { ...ir, nodes };
+  // Record what this pass computed, so a caller can report the graph's derived surface
+  // without hardcoding attribute names. Only kinds actually enriched are listed.
+  const enriched = nodes.some((n) => isKind(n, "Instance"));
+  const derivedAttrs = enriched
+    ? { ...(ir.derivedAttrs ?? {}), Instance: ["internetFacing", "effectiveIngress"] }
+    : ir.derivedAttrs;
+  return { ...ir, nodes, ...(derivedAttrs ? { derivedAttrs } : {}) };
 }

package/src/graph-ir-live.test.ts

@@ -157,6 +157,34 @@ describe("sourceOverlayGraphs (#821 source-anchored overlay)", () => {
     expect(vpc.ownership).toBe("owned");
   });
 
+  it("carries observed attributes onto a managed declared node (#1279)", () => {
+    // Before this, the overlay copied identity but dropped everything observed
+    // ABOUT the resource, so a fact that only exists in the account — an
+    // instance's VpcId — was unreachable from the overlaid graph and
+    // `search --show VpcId` printed a blank column.
+    const observed: GraphIR = {
+      ...live,
+      nodes: live.nodes.map((x) => (x.id === "web-vpc" ? { ...x, attrs: { CidrBlock: "10.0.0.0/16" } } : x)),
+    };
+    const vpc = sourceOverlayGraphs(declared, observed).nodes.find((x) => x.id === "web-vpc")!;
+    expect(vpc.attrs.CidrBlock).toBe("10.0.0.0/16");
+  });
+
+  it("lets an observed value beat the declared one of the same name (#1279)", () => {
+    // The declared side holds an unresolved reference to another entity; the
+    // account holds the id it actually resolved to.
+    const withRef: GraphIR = {
+      ...declared,
+      nodes: declared.nodes.map((x) => (x.id === "web-vpc" ? { ...x, attrs: { VpcId: "${vpc.id}" } } : x)),
+    };
+    const observed: GraphIR = {
+      ...live,
+      nodes: live.nodes.map((x) => (x.id === "web-vpc" ? { ...x, attrs: { VpcId: "vpc-0a1b" } } : x)),
+    };
+    const vpc = sourceOverlayGraphs(withRef, observed).nodes.find((x) => x.id === "web-vpc")!;
+    expect(vpc.attrs.VpcId).toBe("vpc-0a1b");
+  });
+
   it("appends foreign nodes with their live edges, and keeps declared groups", () => {
     const ir = sourceOverlayGraphs(declared, live);
     expect(ir.nodes.map((x) => x.id)).toContain("rogue-sg");
@@ -208,3 +236,58 @@ describe("collectUnobserved (#1089)", () => {
     ).toEqual({ a: { reason: "read-failed" }, b: { reason: "no-binding" } });
   });
 });
+
+// #1271 — an observation can report relationships, not just existence. Without
+// these the live side of the graph has no edges, so a topology fold has nothing
+// to traverse and a lexicon has to compute derived answers itself.
+describe("observed edges (#1271)", () => {
+  const twoNodes = {
+    lexicon: "aws",
+    resources: {
+      "app-subnet": { type: "AWS::EC2::Subnet", status: "CREATE_COMPLETE", physicalId: "subnet-0c2d" },
+      "web-vpc": { type: "AWS::EC2::VPC", status: "CREATE_COMPLETE", physicalId: "vpc-0a1b" },
+    },
+  } satisfies LiveObservation;
+
+  it("projects an observed edge between two observed nodes", () => {
+    const ir = buildLiveGraphIr([
+      { ...twoNodes, edges: [{ from: "app-subnet", to: "web-vpc", kind: "ref", viaAttr: "VpcId" }] },
+    ]);
+    expect(ir.edges).toEqual([{ from: "app-subnet", to: "web-vpc", kind: "ref", viaAttr: "VpcId" }]);
+  });
+
+  it("no edges reported → no edges, unchanged from before", () => {
+    expect(buildLiveGraphIr([twoNodes]).edges).toEqual([]);
+  });
+
+  it("drops an edge whose endpoint was never observed", () => {
+    // A dangling reference would traverse to nothing during a fold, which reads
+    // as "no such relationship" rather than "the other end was not read".
+    const ir = buildLiveGraphIr([
+      { ...twoNodes, edges: [{ from: "app-subnet", to: "never-read", kind: "ref", viaAttr: "VpcId" }] },
+    ]);
+    expect(ir.edges).toEqual([]);
+  });
+
+  it("dedupes identical edges reported by more than one observation", () => {
+    const edge = { from: "app-subnet", to: "web-vpc", kind: "ref" as const, viaAttr: "VpcId" };
+    const ir = buildLiveGraphIr([
+      { ...twoNodes, edges: [edge] },
+      { ...twoNodes, edges: [edge] },
+    ]);
+    expect(ir.edges).toHaveLength(1);
+  });
+
+  it("orders edges deterministically — the IR is compared and committed", () => {
+    const ir = buildLiveGraphIr([
+      {
+        ...twoNodes,
+        edges: [
+          { from: "web-vpc", to: "app-subnet", kind: "ref", viaAttr: "Z" },
+          { from: "app-subnet", to: "web-vpc", kind: "ref", viaAttr: "A" },
+        ],
+      },
+    ]);
+    expect(ir.edges?.map((e) => e.from)).toEqual(["app-subnet", "web-vpc"]);
+  });
+});

package/src/graph-ir.ts

@@ -191,6 +191,13 @@ export interface GraphIR {
   imports?: IRImport[];
   /** The CI/pipeline projection alongside the component graph (#989) — see {@link IRPipeline}. */
   pipeline?: IRPipeline;
+  /**
+   * Attributes chant computed rather than read back from the provider, keyed by the kind
+   * they were folded onto. An enrichment pass records what it derived here so callers can
+   * report the graph's own surface without knowing any attribute name — the set is whatever
+   * the passes produced, not a list maintained by hand.
+   */
+  derivedAttrs?: Record<string, string[]>;
 }
 
 /** A node is anything that serializes to a resource — not a property or output. */
@@ -482,6 +489,20 @@ export interface LiveObservation {
    * overlay must not paint them "pending". See {@link sourceOverlayGraphs}.
    */
   unobserved?: Record<string, UnobservedEntity>;
+  /**
+   * Relationships the lexicon observed between the resources it read (#1271).
+   *
+   * Without these an observation can only say what exists, never how it
+   * connects — so a fold over topology has nothing to traverse on the live side
+   * and a lexicon has to compute derived answers itself and inject them as
+   * attributes. Reporting the edges instead lets the one graph fold in
+   * {@link import("./graph-effective").enrichEffectiveTopology} do the work,
+   * for every lexicon, over live and recorded observations alike.
+   *
+   * `from`/`to` are node ids in the same space as {@link LiveObservation.resources}
+   * keys, so an edge can only reference something the observation also reported.
+   */
+  edges?: IREdge[];
 }
 
 /**
@@ -533,7 +554,31 @@ export function buildLiveGraphIr(observations: LiveObservation[]): GraphIR {
   if (Object.keys(byLexicon).length) groups.byLexicon = sortKeys(byLexicon);
   if (Object.keys(byStack).length) groups.byStack = sortKeys(byStack);
 
-  return { nodes, edges: [], groups };
+  // Observed relationships (#1271). An edge whose endpoints were not both
+  // observed is dropped rather than kept as a dangling reference: the fold
+  // resolves ids to nodes, and a half-edge would silently traverse to nothing.
+  // Deduped and sorted for the same reason nodes are — the IR is compared and
+  // committed, so it has to be stable across reads.
+  const observedIds = new Set(nodes.map((n) => n.id));
+  const seen = new Set<string>();
+  const edges: IREdge[] = [];
+  for (const observation of observations) {
+    for (const edge of observation.edges ?? []) {
+      if (!observedIds.has(edge.from) || !observedIds.has(edge.to)) continue;
+      const key = `${edge.from}${edge.to}${edge.viaAttr ?? ""}${edge.toAttr ?? ""}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      edges.push(edge);
+    }
+  }
+  edges.sort(
+    (a, b) =>
+      a.from.localeCompare(b.from) ||
+      a.to.localeCompare(b.to) ||
+      (a.viaAttr ?? "").localeCompare(b.viaAttr ?? ""),
+  );
+
+  return { nodes, edges, groups };
 }
 
 /** How an overlay learns which declared nodes were never looked at (#1089). */
@@ -640,6 +685,18 @@ export function sourceOverlayGraphs(declared: GraphIR, live: GraphIR, opts?: Ove
     const merged: IRNode = { ...n }; // managed — carry the observed identity
     if (obs.physicalId) merged.physicalId = obs.physicalId;
     if (obs.ownership) merged.ownership = obs.ownership;
+    // ...and what was observed ABOUT it (#1279). The declared canvas holds what
+    // the source says; the observation holds what the account says, and a fact
+    // like `VpcId` exists only on the second. Dropping it here made every
+    // observed property invisible to anything reading the overlaid graph —
+    // `search --show VpcId` printed six blank columns, which reads as an estate
+    // with no VPCs rather than a read that never happened.
+    //
+    // Observed wins a collision. The declared value for something like `VpcId`
+    // is an unresolved reference to another entity, not an id — the account has
+    // the id. Same precedence `enrichLiveAttrs` already uses when it folds live
+    // facts onto this graph, so both paths agree on what a name means.
+    if (obs.attrs && Object.keys(obs.attrs).length > 0) merged.attrs = { ...n.attrs, ...obs.attrs };
     return tagStatus(merged, "good");
   });
   for (const n of live.nodes) {

package/src/graph-refs.test.ts

@@ -129,3 +129,62 @@ describe("mergeCatalogs", () => {
     expect(m.refs).toHaveLength(1);
   });
 });
+
+// #1275 — `viaAttr` defaulted to `label ?? path`, which serves a renderer and
+// starves a traversal: the catalog's labels are human-facing ("sg", "via")
+// while a fold matches provider attribute names ("SecurityGroupIds").
+describe("traversal name vs rendering label (#1275)", () => {
+  const nodes: IRNode[] = [
+    { id: "web", kind: "AWS::EC2::Instance", lexicon: "aws", attrs: { SubnetId: "subnet-1", SecurityGroups: [{ GroupId: "sg-1" }] } },
+    { id: "sub", kind: "AWS::EC2::Subnet", lexicon: "aws", attrs: { SubnetId: "subnet-1" } },
+    { id: "sg", kind: "AWS::EC2::SecurityGroup", lexicon: "aws", attrs: { GroupId: "sg-1" } },
+  ];
+  const identities = [
+    { kind: "AWS::EC2::Subnet", ids: ["SubnetId"] },
+    { kind: "AWS::EC2::SecurityGroup", ids: ["GroupId"] },
+  ];
+
+  it("viaAttr wins over label, so the fold can match the attribute name", () => {
+    const { edges } = reconstructEdges(nodes, {
+      identities,
+      refs: [
+        { from: "AWS::EC2::Instance", path: "SecurityGroups[].GroupId", targetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "sg", viaAttr: "SecurityGroupIds" },
+      ],
+    });
+    expect(edges).toEqual([{ from: "web", to: "sg", kind: "ref", viaAttr: "SecurityGroupIds" }]);
+  });
+
+  it("without viaAttr the label still wins, unchanged", () => {
+    const { edges } = reconstructEdges(nodes, {
+      identities,
+      refs: [
+        { from: "AWS::EC2::Instance", path: "SecurityGroups[].GroupId", targetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "sg" },
+      ],
+    });
+    expect(edges[0].viaAttr).toBe("sg");
+  });
+
+  it("a containment rule with viaAttr yields both the boundary pair and a traversable edge", () => {
+    // An instance is *in* a subnet — a boundary for the picture, and the first
+    // hop of internetFacing. It has to be both without being drawn twice.
+    const { edges, containment } = reconstructEdges(nodes, {
+      identities,
+      refs: [
+        { from: "AWS::EC2::Instance", path: "SubnetId", targetKind: "AWS::EC2::Subnet", relation: "containment", label: "in subnet", viaAttr: "SubnetId" },
+      ],
+    });
+    expect(containment).toEqual([{ child: "web", parent: "sub", label: "in subnet" }]);
+    expect(edges).toEqual([{ from: "web", to: "sub", kind: "ref", viaAttr: "SubnetId" }]);
+  });
+
+  it("a containment rule without viaAttr stays a boundary hint only", () => {
+    const { edges, containment } = reconstructEdges(nodes, {
+      identities,
+      refs: [
+        { from: "AWS::EC2::Instance", path: "SubnetId", targetKind: "AWS::EC2::Subnet", relation: "containment", label: "in subnet" },
+      ],
+    });
+    expect(containment).toHaveLength(1);
+    expect(edges).toEqual([]);
+  });
+});

package/src/graph-refs.ts

@@ -40,6 +40,25 @@ export interface RefRule {
   relation: "reference" | "containment";
   /** Edge / containment label (e.g. "in VPC", "sg", "targets"). */
   label?: string;
+  /**
+   * What the reconstructed edge's `viaAttr` should be, when traversal needs a
+   * different string than rendering does (#1275).
+   *
+   * `viaAttr` defaulted to `label ?? path`, which serves a renderer well and a
+   * traversal badly. The labels here are human-facing — "sg", "via", "in VPC" —
+   * while a fold like `enrichEffectiveTopology` matches provider attribute
+   * names: `SecurityGroupIds`, `SubnetId`, `LaunchTemplateId`. One field could
+   * not be both, so a rule that is traversed declares the name explicitly and
+   * keeps its label for the picture.
+   *
+   * On a `containment` rule this additionally opts the relation into producing
+   * an edge, on top of the boundary pair it already produces. Containment is
+   * not an edge by default and should not become one — but a fold's first hop
+   * is sometimes exactly a containment relation (an instance is *in* a subnet),
+   * and that hop has to be traversable without duplicating the rule as a
+   * reference and drawing the line twice.
+   */
+  viaAttr?: string;
 }
 
 /** A lexicon's reference knowledge — its identity map and reference rules. */
@@ -154,17 +173,29 @@ export function reconstructEdges(nodes: IRNode[], catalog: ReferenceCatalog): Re
           continue;
         }
         if (match.id === node.id) continue; // self-reference (e.g. an SG rule to its own group)
-        if (rule.relation === "containment") {
-          const k = `${node.id}|${match.id}`;
-          if (seenCont.has(k)) continue;
-          seenCont.add(k);
-          containment.push({ child: node.id, parent: match.id, ...(rule.label ? { label: rule.label } : {}) });
-        } else {
-          const via = rule.label ?? rule.path;
+        const pushEdge = (via: string): void => {
           const k = `${node.id}|${match.id}|${via}`;
-          if (seenEdge.has(k)) continue;
+          if (seenEdge.has(k)) return;
           seenEdge.add(k);
           edges.push({ from: node.id, to: match.id, kind: "ref", viaAttr: via });
+        };
+        if (rule.relation === "containment") {
+          const k = `${node.id}|${match.id}`;
+          if (!seenCont.has(k)) {
+            seenCont.add(k);
+            containment.push({ child: node.id, parent: match.id, ...(rule.label ? { label: rule.label } : {}) });
+          }
+          // A containment relation is a boundary hint, not an edge — unless the
+          // rule declares a traversal name (#1275). A fold's first hop is
+          // sometimes exactly a containment ("an instance is in a subnet"), and
+          // it must be traversable without duplicating the rule as a reference
+          // and drawing the line twice.
+          if (rule.viaAttr) pushEdge(rule.viaAttr);
+        } else {
+          // Traversal name wins over the rendering label: the labels are
+          // human-facing ("sg", "via"), and a fold matches provider attribute
+          // names (#1275).
+          pushEdge(rule.viaAttr ?? rule.label ?? rule.path);
         }
       }
     }