@intentius/chant 0.44.2 → 0.44.3

package/dist/build.d.ts

@@ -203,6 +203,29 @@ export declare function collectLexiconOutputs(entities: Map<string, Declarable>)
  * @returns Array of auto-detected LexiconOutput instances
  */
 export declare function detectCrossLexiconRefs(entities: Map<string, Declarable>): LexiconOutput[];
+/** What merging build-root contributions produced: non-fatal render notes and
+ * fatal messages (a failed contributor, a name collision). */
+export interface BuildRootMergeResult {
+    warnings: string[];
+    errors: string[];
+}
+/**
+ * Run each build-root contributor (#1548 piece 3) and merge its rendered
+ * entities into `entities`, in place. THE one merge implementation — `build()`
+ * uses it for step 4b, and the graph handler's discover-based paths reuse it
+ * so a rendered kustomize root joins the graphed entity set under exactly the
+ * rules the build applies (#1626):
+ *
+ * - a contributed name colliding with an existing entity is an error, never a
+ *   silent overwrite;
+ * - a contributor that throws becomes an error carrying its message (the k8s
+ *   hook's missing-binary refusal names the binaries), not a stack trace.
+ *
+ * Errors come back as plain messages; each caller wraps them in its own error
+ * vocabulary (`BuildErrorClass` in `build()`, the CLI's `formatError` on the
+ * graph paths).
+ */
+export declare function mergeBuildRootEntities(entities: Map<string, Declarable>, contributors: ReadonlyArray<() => Promise<BuildRootContribution>>): Promise<BuildRootMergeResult>;
 /**
  * Builds a lexicon specification by discovering entities, sorting them
  * topologically, and serializing them using the lexicon serializers.

package/dist/build.d.ts.map

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

package/dist/cli/handlers/graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/graph.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAsClD;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAwCnE"}
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/graph.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAqGlD;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAwCnE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.44.2",
+  "version": "0.44.3",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/build.ts

@@ -565,6 +565,53 @@ function generateManifest(
   };
 }
 
+/** What merging build-root contributions produced: non-fatal render notes and
+ * fatal messages (a failed contributor, a name collision). */
+export interface BuildRootMergeResult {
+  warnings: string[];
+  errors: string[];
+}
+
+/**
+ * Run each build-root contributor (#1548 piece 3) and merge its rendered
+ * entities into `entities`, in place. THE one merge implementation — `build()`
+ * uses it for step 4b, and the graph handler's discover-based paths reuse it
+ * so a rendered kustomize root joins the graphed entity set under exactly the
+ * rules the build applies (#1626):
+ *
+ * - a contributed name colliding with an existing entity is an error, never a
+ *   silent overwrite;
+ * - a contributor that throws becomes an error carrying its message (the k8s
+ *   hook's missing-binary refusal names the binaries), not a stack trace.
+ *
+ * Errors come back as plain messages; each caller wraps them in its own error
+ * vocabulary (`BuildErrorClass` in `build()`, the CLI's `formatError` on the
+ * graph paths).
+ */
+export async function mergeBuildRootEntities(
+  entities: Map<string, Declarable>,
+  contributors: ReadonlyArray<() => Promise<BuildRootContribution>>,
+): Promise<BuildRootMergeResult> {
+  const warnings: string[] = [];
+  const errors: string[] = [];
+  for (const contribute of contributors) {
+    try {
+      const contribution = await contribute();
+      warnings.push(...(contribution.warnings ?? []));
+      for (const [name, entity] of contribution.entities) {
+        if (entities.has(name)) {
+          errors.push(`Build-root entity "${name}" collides with a discovered entity of the same name`);
+          continue;
+        }
+        entities.set(name, entity);
+      }
+    } catch (error) {
+      errors.push(error instanceof Error ? error.message : String(error));
+    }
+  }
+  return { warnings, errors };
+}
+
 /**
  * Builds a lexicon specification by discovering entities, sorting them
  * topologically, and serializing them using the lexicon serializers.
@@ -680,25 +727,10 @@ async function buildFromDiscoveryResult(
   // object, and re-running the contributors there would duplicate every
   // contributed entity once per child.
   if (!parentBuildStack && options?.buildRoots) {
-    for (const contribute of options.buildRoots) {
-      try {
-        const contribution = await contribute();
-        for (const w of contribution.warnings ?? []) warnings.push(w);
-        for (const [name, entity] of contribution.entities) {
-          if (discoveryResult.entities.has(name)) {
-            errors.push(
-              new BuildErrorClass(
-                "",
-                `Build-root entity "${name}" collides with a discovered entity of the same name`,
-              ),
-            );
-            continue;
-          }
-          discoveryResult.entities.set(name, entity);
-        }
-      } catch (error) {
-        errors.push(new BuildErrorClass("", error instanceof Error ? error.message : String(error)));
-      }
+    const merged = await mergeBuildRootEntities(discoveryResult.entities, options.buildRoots);
+    warnings.push(...merged.warnings);
+    for (const message of merged.errors) {
+      errors.push(new BuildErrorClass("", message));
     }
   }
 

package/src/cli/handlers/graph.test.ts

@@ -52,10 +52,16 @@ vi.mock("../../graph-layout", () => ({
 // hit the Op-graph and source-view modes, so these mocks don't touch them).
 const loadPluginsMock = vi.fn();
 const resolveLexMock = vi.fn();
-vi.mock("../plugins", () => ({
-  loadPlugins: (...a: unknown[]) => loadPluginsMock(...a),
-  resolveProjectLexicons: (...a: unknown[]) => resolveLexMock(...a),
-}));
+vi.mock("../plugins", async () => {
+  // Real `collectBuildRootContributors` (#1626): it is pure binding — the
+  // handler's build-root plumbing is exactly what the tests below assert.
+  const actual = await vi.importActual<typeof import("../plugins")>("../plugins");
+  return {
+    ...actual,
+    loadPlugins: (...a: unknown[]) => loadPluginsMock(...a),
+    resolveProjectLexicons: (...a: unknown[]) => resolveLexMock(...a),
+  };
+});
 const observeMock = vi.fn();
 const replayMock = vi.fn();
 const hasSnapshotMock = vi.fn((..._a: unknown[]) => Promise.resolve(false));
@@ -86,17 +92,22 @@ vi.mock("../../config", async () => {
   };
 });
 const buildMock = vi.fn();
-vi.mock("../../build", () => ({
-  // Forwards its arguments so a test can assert what the live path passed —
-  // `buildParams` in particular (#1483), the same reason `discover` above
-  // forwards for #1359.
-  build: (...a: unknown[]) => {
-    buildMock(...a);
-    return Promise.resolve({ errors: [] });
-  },
-  partitionByLexicon: () => ({}),
-  computeStackGraph: () => ({}),
-}));
+vi.mock("../../build", async () => {
+  // Real `mergeBuildRootEntities` (#1626): the graph paths reuse build's one
+  // merge implementation, so the tests exercise the real merge rules
+  // (collision → error) rather than a re-stubbed copy of them.
+  const actual = await vi.importActual<typeof import("../../build")>("../../build");
+  return {
+    ...actual,
+    // Forwards its arguments so a test can assert what the live path passed —
+    // `buildParams` in particular (#1483), the same reason `discover` above
+    // forwards for #1359.
+    build: (...a: unknown[]) => {
+      buildMock(...a);
+      return Promise.resolve({ errors: [] });
+    },
+  };
+});
 
 const { runGraph } = await import("./graph");
 
@@ -812,4 +823,169 @@ describe("runGraph", () => {
       });
     });
   });
+
+  // #1626 — #1612's `buildRoots` seam reached `chant build` and the lifecycle
+  // handlers but none of the graph command's four entity-collection sites, so
+  // a `k8s.kustomize.roots` estate graphed only its typed source: the rendered
+  // Deployment/Service existed in the build output and on the cluster, and
+  // nowhere in any graph. The shapes here mirror the kustomize-root fixture
+  // (lexicons/k8s/src/testdata/kustomize-root, rendered as `overlays/prod`):
+  // the contributor below returns exactly what `renderKustomizeRoots` returns
+  // for it — rendered-manifest entities keyed `overlays/prod/<kindName>`,
+  // props = the verbatim document, provenance annotation stamped.
+  describe("build-root contributions reach the graph (#1626)", () => {
+    const KUSTOMIZE_ROOT_ANNOTATION = "chant.intentius.io/kustomize-root";
+
+    /** A rendered kustomize document as `renderedManifestEntity` shapes it. */
+    const rendered = (group: string, kind: string, name: string, spec: Record<string, unknown>): Declarable =>
+      ({
+        lexicon: "k8s",
+        entityType: `K8s::${group}::${kind}`,
+        kind: "resource",
+        props: {
+          apiVersion: group === "Core" ? "v1" : `${group.toLowerCase()}/v1`,
+          kind,
+          metadata: { name, annotations: { [KUSTOMIZE_ROOT_ANNOTATION]: "overlays/prod" } },
+          spec,
+        },
+        [DECLARABLE_MARKER]: true,
+        [Symbol.for("chant.k8s.renderedManifest")]: true,
+      }) as unknown as Declarable;
+
+    const fixtureContribution = () => ({
+      entities: new Map<string, Declarable>([
+        ["overlays/prod/serviceProdWeb", rendered("Core", "Service", "prod-web", { selector: { app: "web" } })],
+        ["overlays/prod/deploymentProdWeb", rendered("Apps", "Deployment", "prod-web", { replicas: 3 })],
+      ]),
+    });
+
+    /** A k8s-shaped plugin whose `buildRoots` hook renders the fixture. */
+    const k8sPluginStub = (hook = async () => fixtureContribution()) => ({
+      name: "k8s",
+      serializer: {},
+      describeResources: () => Promise.resolve({}),
+      buildRoots: hook,
+    });
+
+    const declaredNamespace = (): void => {
+      discoverMock.mockResolvedValue({
+        entities: new Map<string, Declarable>([["ns", decl({ lexicon: "k8s", entityType: "K8s::Core::Namespace", kind: "resource", props: { metadata: { name: "web" } } })]]),
+        errors: [], dependencies: new Map(), sourceFiles: [],
+      });
+    };
+
+    const staticWithFixtureRoot = (hook?: () => Promise<{ entities: Map<string, Declarable> }>): void => {
+      lintMock.mockResolvedValue({ success: true });
+      declaredNamespace();
+      resolveLexMock.mockResolvedValue(["k8s"]);
+      loadPluginsMock.mockResolvedValue([k8sPluginStub(hook)]);
+    };
+
+    test("static --format ir emits the rendered nodes alongside the typed ones", async () => {
+      staticWithFixtureRoot();
+      const exit = await runGraph({ args: makeArgs({ format: "ir" }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      const ir = JSON.parse(stdoutBuf.join("\n"));
+      expect(ir.nodes.map((n: { id: string }) => n.id).sort()).toEqual([
+        "ns",
+        "overlays/prod/deploymentProdWeb",
+        "overlays/prod/serviceProdWeb",
+      ]);
+      const deployment = ir.nodes.find((n: { id: string }) => n.id === "overlays/prod/deploymentProdWeb");
+      expect(deployment.kind).toBe("K8s::Apps::Deployment");
+      expect(deployment.lexicon).toBe("k8s");
+    });
+
+    // #1624 made attrs projection monotonic; the provenance annotation is a
+    // nested `metadata` tree, so it belongs to the full-property tier and only
+    // that tier — present at --detail 3, absent from --detail 1's topology view.
+    test("--detail 3 carries the provenance annotation in the rendered node's attrs; --detail 1 does not", async () => {
+      staticWithFixtureRoot();
+      expect(await runGraph({ args: makeArgs({ format: "ir", detail: 3 }), plugins: [], serializers: [] })).toBe(0);
+      const detailed = JSON.parse(stdoutBuf.join("\n"));
+      const at3 = detailed.nodes.find((n: { id: string }) => n.id === "overlays/prod/deploymentProdWeb");
+      expect(at3.attrs.metadata.annotations[KUSTOMIZE_ROOT_ANNOTATION]).toBe("overlays/prod");
+
+      stdoutBuf.length = 0;
+      staticWithFixtureRoot();
+      expect(await runGraph({ args: makeArgs({ format: "ir", detail: 1 }), plugins: [], serializers: [] })).toBe(0);
+      const coarse = JSON.parse(stdoutBuf.join("\n"));
+      const at1 = coarse.nodes.find((n: { id: string }) => n.id === "overlays/prod/deploymentProdWeb");
+      expect(at1).toBeDefined(); // the node survives the tier —
+      expect(at1.attrs.metadata).toBeUndefined(); // its property tree does not
+    });
+
+    test("a contributed name colliding with a discovered entity fails the graph like a discovery error", async () => {
+      staticWithFixtureRoot(async () => ({
+        entities: new Map<string, Declarable>([["ns", rendered("Core", "Namespace", "web", {})]]),
+      }));
+      const exit = await runGraph({ args: makeArgs({ format: "ir" }), plugins: [], serializers: [] });
+      expect(exit).toBe(1);
+      expect(stdoutBuf.join("\n")).toBe("");
+      expect(stderrBuf.join("\n")).toContain('"ns" collides');
+    });
+
+    test("--stacks joins the rendered entities into the stack partitions", async () => {
+      declaredNamespace();
+      resolveLexMock.mockResolvedValue(["k8s"]);
+      loadPluginsMock.mockResolvedValue([k8sPluginStub()]);
+      const exit = await runGraph({ args: makeArgs({ stacks: true, json: true }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      // partitionByLexicon/computeStackGraph are stubbed above; what matters is
+      // that the merge ran before them without erroring. The collision case
+      // proves the same merge is live on this path:
+      stderrBuf.length = 0;
+      declaredNamespace();
+      loadPluginsMock.mockResolvedValue([
+        k8sPluginStub(async () => ({ entities: new Map<string, Declarable>([["ns", rendered("Core", "Namespace", "web", {})]]) })),
+      ]);
+      expect(await runGraph({ args: makeArgs({ stacks: true, json: true }), plugins: [], serializers: [] })).toBe(1);
+      expect(stderrBuf.join("\n")).toContain('"ns" collides');
+    });
+
+    test("--live passes the contributors through to build(), like lifecycle does", async () => {
+      resolveLexMock.mockResolvedValue(["k8s"]);
+      loadPluginsMock.mockResolvedValue([k8sPluginStub()]);
+      observeMock.mockResolvedValue({ observations: [], errors: [], warnings: [] });
+      const exit = await runGraph({ args: makeArgs({ format: "ir", live: true, env: "kcheck" }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      const [, , , options] = buildMock.mock.calls[0] as [string, unknown, unknown, { buildRoots?: unknown[] }];
+      expect(options.buildRoots).toHaveLength(1);
+    });
+
+    test("--live --overlay classifies an observed rendered node as managed, not foreign", async () => {
+      resolveLexMock.mockResolvedValue(["k8s"]);
+      loadPluginsMock.mockResolvedValue([k8sPluginStub()]);
+      declaredNamespace();
+      // The cluster has the namespace and the rendered Deployment — the
+      // latter observed through the same entityType/props flow as any
+      // declared entity (its props carry metadata.name like typed ones).
+      observeMock.mockResolvedValue({
+        observations: [{
+          lexicon: "k8s",
+          resources: {
+            ns: { type: "K8s::Core::Namespace", status: "OBSERVED", physicalId: "uid-ns", ownership: "owned" },
+            "overlays/prod/deploymentProdWeb": { type: "K8s::Apps::Deployment", status: "OBSERVED", physicalId: "uid-deploy", ownership: "owned" },
+          },
+        }],
+        errors: [], warnings: [],
+      });
+      const exit = await runGraph({
+        args: makeArgs({ format: "ir", live: true, overlay: true, env: "kcheck" }),
+        plugins: [], serializers: [],
+      });
+      expect(exit).toBe(0);
+      const ir = JSON.parse(stdoutBuf.join("\n"));
+      const deployment = ir.nodes.find((n: { id: string }) => n.id === "overlays/prod/deploymentProdWeb");
+      // Declared (via the merged contribution) + observed = managed. Before
+      // #1626 the declared canvas lacked the rendered node, so it read as
+      // foreign (`warn`) despite being chant's own build output.
+      expect(deployment.attrs._status).toBe("good");
+      expect(deployment.physicalId).toBe("uid-deploy");
+      // The rendered Service was declared but not observed — pending, the
+      // same verdict a typed entity would get.
+      const service = ir.nodes.find((n: { id: string }) => n.id === "overlays/prod/serviceProdWeb");
+      expect(service.attrs._status).toBe("accent");
+    });
+  });
 });

package/src/cli/handlers/graph.ts

@@ -1,7 +1,7 @@
-import { resolve } from "node:path";
+import { dirname, resolve } from "node:path";
 import { discoverOps } from "../../op/discover";
 import { discover } from "../../discovery/index";
-import { partitionByLexicon, computeStackGraph, build } from "../../build";
+import { partitionByLexicon, computeStackGraph, build, mergeBuildRootEntities } from "../../build";
 import { buildGraphIr, buildLiveGraphIr, collectUnobserved, overlayGraphs, sourceOverlayGraphs, type GraphIR, type IRPipeline, type LiveObservation } from "../../graph-ir";
 import { buildDeclaredPerStack } from "../../graph-declared";
 import { reconstructEdges, mergeCatalogs, containmentGroups, type ReferenceCatalog, type ContainmentPair } from "../../graph-refs";
@@ -15,7 +15,7 @@ import { toMermaid } from "../../graph-mermaid";
 import { toDot } from "../../graph-dot";
 import { getLayoutEngine, toLayoutInput, type NodeSize } from "../../graph-layout";
 import { lintCommand } from "../commands/lint";
-import { loadPlugins, resolveProjectLexicons } from "../plugins";
+import { loadPlugins, resolveProjectLexicons, collectBuildRootContributors } from "../plugins";
 import { readFileSync } from "node:fs";
 import { formatError, formatWarning, formatBold } from "../format";
 import type { CommandContext } from "../registry";
@@ -56,6 +56,69 @@ async function graphBuildParams(
   return resolution.provenance;
 }
 
+/**
+ * The build-root contributors this invocation's project configures (#1626) —
+ * the same closures `chant build` and the lifecycle handlers hand to
+ * `BuildOptions.buildRoots`, bound here for the graph command's
+ * discover-based paths, which never run `build()` and so never ran the hook:
+ * a `k8s.kustomize.roots` estate graphed only its typed source while its
+ * built (and deployed) output carried the rendered manifests too.
+ *
+ * `graph` is not `requiresPlugins` (Op/source-graph modes must work without a
+ * lexicon), so plugins are loaded here when `ctx.plugins` is empty, mirroring
+ * `runGraphLive`. Rooted at the config's own directory, like
+ * `cli/commands/build.ts` — a relative kustomize root resolves against where
+ * it was declared, not against a sourceDir-scoped graph path. A project that
+ * fails to load plugins degrades to no contributors with a warning rather
+ * than failing modes that never needed plugins at all.
+ */
+async function graphBuildRootContributors(
+  ctx: CommandContext,
+  projectPath: string,
+): Promise<Array<() => Promise<import("../../lexicon").BuildRootContribution>>> {
+  const { config, configPath } = await loadChantConfigUpward(projectPath).catch(
+    () => ({ config: {} as ChantConfig, configPath: undefined }),
+  );
+  let plugins = ctx.plugins;
+  if (plugins.length === 0) {
+    try {
+      plugins = await loadPlugins(await resolveProjectLexicons(projectPath));
+    } catch (err) {
+      console.error(formatWarning({
+        message: `could not load the project's lexicons — build-root entities (kustomize roots) will be missing from the graph (${err instanceof Error ? err.message : String(err)})`,
+      }));
+      return [];
+    }
+  }
+  return collectBuildRootContributors(
+    plugins,
+    config as unknown as Record<string, unknown>,
+    configPath ? dirname(configPath) : projectPath,
+  );
+}
+
+/**
+ * Merge build-root contributions into a discovered entity set — the exact
+ * merge `build()` performs (one implementation: `mergeBuildRootEntities`,
+ * ../../build.ts), surfaced in the graph command's error style. Returns false
+ * when a contributor failed or a name collided; the caller stops, matching
+ * how the discover-based paths treat discovery errors — a graph missing the
+ * entities the build would refuse over must not be emitted as if complete.
+ */
+async function mergeGraphBuildRoots(
+  entities: Map<string, import("../../declarable").Declarable>,
+  contributors: Array<() => Promise<import("../../lexicon").BuildRootContribution>>,
+): Promise<boolean> {
+  if (contributors.length === 0) return true;
+  const merged = await mergeBuildRootEntities(entities, contributors);
+  for (const w of merged.warnings) console.error(formatWarning({ message: w }));
+  if (merged.errors.length > 0) {
+    for (const message of merged.errors) console.error(formatError({ message }));
+    return false;
+  }
+  return true;
+}
+
 /**
  * `chant graph` — the Op dependency graph by default; `--stacks` renders the
  * cross-stack apply-ordering graph (edges, order, waves) chant computes from
@@ -154,11 +217,17 @@ async function runGraphLive(
   // a confidently wrong overlay rather than an empty one.
   const liveBuildParams = await graphBuildParams(ctx, projectPath);
   if (!liveBuildParams) return 1;
+  // #1626 — the same build-root contributors `chant build` runs (kustomize
+  // roots rendered into entities), so the scope handed to describeResources
+  // includes the rendered objects and the live read observes them like any
+  // declared entity. Without this the built estate carried them but the graph
+  // build here didn't, and the overlay called every one of them foreign.
+  const buildRoots = collectBuildRootContributors(plugins, config as unknown as Record<string, unknown>, projectPath);
   const buildResult = await build(
     resolve(args.src ?? config.sourceDir ?? "."),
     plugins.map((p) => p.serializer),
     undefined,
-    { buildParams: liveBuildParams },
+    { buildParams: liveBuildParams, buildRoots },
   );
   if (buildResult.errors.length > 0) {
     console.error(formatError({ message: "Build failed — fix errors before graphing live state" }));
@@ -323,14 +392,23 @@ async function runGraphLive(
       const declared = await discover(resolve(args.src ?? config.sourceDir ?? "."), {
         ...(declaredParams ? { buildParams: declaredParams } : {}),
       });
-      if (declared.errors.length === 0) {
+      // #1626 — the declared canvas must include what the build declares, and
+      // that is discovery PLUS build-root contributions (rendered kustomize
+      // objects). Same contributors, same merge as the `build()` above — so
+      // the rendered nodes classify `good`/`accent` like typed ones instead
+      // of reading as foreign. A merge that fails here (it just succeeded in
+      // the build above, so only a non-deterministic render gets this far)
+      // degrades exactly like discovery errors: overlay skipped, said once.
+      if (declared.errors.length > 0) {
+        console.error(formatWarning({ message: "overlay: source has discovery errors — showing the provisioned graph without the declared overlay" }));
+      } else if (!(await mergeGraphBuildRoots(declared.entities, buildRoots))) {
+        console.error(formatWarning({ message: "overlay: a build root failed to render — showing the provisioned graph without the declared overlay" }));
+      } else {
         const declaredIr = buildGraphIr(declared.entities, projectPath);
         ir =
           args.overlayAnchor === "live"
             ? overlayGraphs(ir, declaredIr, overlayOpts)
             : sourceOverlayGraphs(declaredIr, ir, overlayOpts);
-      } else {
-        console.error(formatWarning({ message: "overlay: source has discovery errors — showing the provisioned graph without the declared overlay" }));
       }
     }
   }
@@ -584,6 +662,14 @@ async function runGraphView(
     return 1;
   }
 
+  // #1626 — join the build-root contributions (rendered kustomize objects) to
+  // the discovered set, the way `build()` does before partitioning, so the
+  // static graph shows the same estate the build emits. Fatal on failure,
+  // like discovery errors: this graph stands for what would build.
+  if (!(await mergeGraphBuildRoots(result.entities, await graphBuildRootContributors(ctx, projectPath)))) {
+    return 1;
+  }
+
   // Build the base IR, focus with a lens (declarable-level, most precise), then
   // apply the detail tier — so e.g. blast:<resource> works before any collapse.
   let ir: GraphIR = buildGraphIr(result.entities, projectPath);
@@ -703,6 +789,12 @@ async function runStackGraph(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
+  // #1626 — same join as runGraphView: contributed entities are part of the
+  // built estate, so they belong in its stack partitions too.
+  if (!(await mergeGraphBuildRoots(result.entities, await graphBuildRootContributors(ctx, projectPath)))) {
+    return 1;
+  }
+
   const lexicons = [...partitionByLexicon(result.entities).keys()];
   const graph = computeStackGraph(result.entities, lexicons);