@intentius/chant 0.27.0 → 0.29.0

package/src/discovery/sandbox/config-boundary.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
 import { mkdir, writeFile, rm, realpath } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
@@ -236,4 +236,58 @@ describe("chant.config.ts evaluation under --sandbox (chant #1113)", () => {
     );
     expect(marker()).toBeUndefined();
   });
+
+  /**
+   * chant #1148 — `chant.config.ts`'s own `console.log`/`console.error` used
+   * to go nowhere under `--sandbox`. Same relay as the run-fallback child
+   * (`./run.test.ts`), just this child's own prefix.
+   */
+  describe("console output forwarding (chant #1148)", () => {
+    beforeEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    afterEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    /** Spies on `process.stderr.write` and returns the lines captured so far — same shape as `../../cli/handlers/emulator.test.ts`'s `stdout()`/`stderr()` helpers. */
+    function captureStderr(): string[] {
+      const lines: string[] = [];
+      vi.spyOn(process.stderr, "write").mockImplementation((chunk: unknown) => {
+        lines.push(String(chunk));
+        return true;
+      });
+      return lines;
+    }
+
+    // See ./run.test.ts's identical helper doc: the IPC "message" the awaited
+    // call resolves on and the child's stdout/stderr pipe data are
+    // independent channels, so polling briefly avoids a flaky assertion.
+    async function waitFor(lines: string[], matcher: RegExp, timeoutMs = 5000): Promise<void> {
+      const start = Date.now();
+      while (Date.now() - start < timeoutMs) {
+        if (matcher.test(lines.join(""))) return;
+        await new Promise((r) => setTimeout(r, 10));
+      }
+      throw new Error(`stderr never matched ${matcher}. Captured so far:\n${lines.join("")}`);
+    }
+
+    test("the config's own console.log/console.error are forwarded, prefixed with [sandbox:config]", async () => {
+      const stderr = captureStderr();
+      await writeFile(
+        join(testDir, "chant.config.ts"),
+        `console.log("hello from config stdout");\n` +
+          `console.error("hello from config stderr");\n` +
+          `export default { lexicons: ["aws"] };\n`,
+      );
+      armSandboxConfigEvaluation();
+
+      const { config } = await loadChantConfig(testDir);
+
+      expect(config.lexicons).toEqual(["aws"]);
+      await waitFor(stderr, /^\[sandbox:config\] hello from config stdout$/m);
+      await waitFor(stderr, /^\[sandbox:config\] hello from config stderr$/m);
+    });
+  });
 });

package/src/discovery/sandbox/config-run.ts

@@ -108,6 +108,9 @@ export async function evaluateConfigSandboxed(
         env,
         timeoutMs: CONFIG_CHILD_TIMEOUT_MS,
         label: `sandboxed evaluation of ${configPath}`,
+        // chant #1148 — the config's own console.log/error no longer goes
+        // nowhere; see `./fork.ts`'s `outputPrefix` doc.
+        outputPrefix: "[sandbox:config]",
       },
       isConfigChildResponse,
     );

package/src/discovery/sandbox/config-wire.ts

@@ -27,8 +27,9 @@
  * ## What `ChantConfig` legally holds
  *
  * Every field of `ChantConfig` (`../../config.ts`) is JSON data: string arrays
- * (`lexicons`, `capabilities`, `environments`), strings (`sourceDir`), nested
- * plain objects of strings/booleans (`ownership`, `build`, `release`, `sbom`,
+ * (`lexicons`, `capabilities`), strings (`sourceDir`), an array of strings or
+ * plain `{ name, endpoint }` objects (`environments`, #1166), nested plain
+ * objects of strings/booleans (`ownership`, `build`, `release`, `sbom`,
  * `signing`, `vulnPolicy`), arrays of plain objects (`stacks`), and records of
  * plain objects (`buildParams`). `lint` is a `LintConfig`, whose rule values
  * are a severity string or a `[severity, options]` tuple, and whose `plugins`

package/src/discovery/sandbox/fork.ts

@@ -11,6 +11,11 @@ import { fork } from "node:child_process";
  * one function is the cheapest way to make "same profile" a fact rather than
  * a claim.
  *
+ * chant #1148 — this is also the one place chant forwards a sandboxed
+ * child's own stdout/stderr, so `./run.ts`, `./config-run.ts` and
+ * `./policy-run.ts` cannot drift on whether project output vanishes. See
+ * {@link SandboxForkOptions.outputPrefix}.
+ *
  * Isolation mechanics (verified on Node v24.13.1 — see the chant#1045 PR
  * description for the full write-up):
  *  - `--permission --allow-fs-read=<bundle dir>,<project dir>[,<trusted
@@ -45,6 +50,26 @@ export interface SandboxForkOptions {
   timeoutMs: number;
   /** What timed out / exited early, for the error message (e.g. `"sandboxed run"`). */
   label: string;
+  /**
+   * chant #1148 — prepended to every line the child writes on EITHER stdout
+   * or stderr before it is relayed, line-buffered, to this process's own
+   * stderr (e.g. `"[sandbox:run]"`, `"[sandbox:config]"`,
+   * `"[policy:org.ts]"`).
+   *
+   * A sandboxed child's `console.log`/`console.error` used to go nowhere: its
+   * stdout was piped but never read, and its stderr was captured only into
+   * {@link stderrBuf}'s error-message use, never surfaced on a successful
+   * run. Diagnostics crossing as data (the whole point of the boundary) is
+   * not the same thing as incidental output being silently dropped — chant's
+   * stance is that nothing the project prints vanishes, sandboxed or not.
+   *
+   * This is forwarding, not a second capture: {@link stderrBuf} still
+   * accumulates the child's raw stderr for `classifyChildError`/the
+   * exited-before-reporting message exactly as before. Both read the same
+   * `data` events; one buffers for classification, this one relays for a
+   * human to see.
+   */
+  outputPrefix: string;
   /**
    * chant #1131 — an optional payload sent to the child over the SAME IPC
    * channel its response comes back on, immediately after the fork.
@@ -65,6 +90,36 @@ export interface SandboxForkOptions {
   send?: Record<string, unknown>;
 }
 
+/**
+ * chant #1148 — buffers arbitrary chunks and calls `emit` once per complete
+ * line, never on a chunk boundary that happens to split a line in two (a
+ * pipe makes no promise that one `write()` on the child's side arrives as one
+ * `data` event on ours). `flush()` emits whatever partial line never got a
+ * trailing newline, so the last unterminated write doesn't silently vanish
+ * when the stream ends — the same no-dropping stance this whole feature
+ * exists for.
+ */
+function lineBuffered(emit: (line: string) => void) {
+  let pending = "";
+  return {
+    push(chunk: Buffer | string): void {
+      pending += chunk.toString();
+      let newlineAt = pending.indexOf("\n");
+      while (newlineAt !== -1) {
+        emit(pending.slice(0, newlineAt));
+        pending = pending.slice(newlineAt + 1);
+        newlineAt = pending.indexOf("\n");
+      }
+    },
+    flush(): void {
+      if (pending.length > 0) {
+        emit(pending);
+        pending = "";
+      }
+    },
+  };
+}
+
 /**
  * Fork `bundlePath` under `--permission` with a scrubbed environment, and
  * resolve with the first IPC message that satisfies `isResponse` (or reject
@@ -74,7 +129,8 @@ export function forkSandboxed<T>(
   options: SandboxForkOptions,
   isResponse: (value: unknown) => value is T,
 ): Promise<T> {
-  const { bundlePath, bundleDir, projectRealpath, externalReadPaths, env, timeoutMs, label, send } = options;
+  const { bundlePath, bundleDir, projectRealpath, externalReadPaths, env, timeoutMs, label, send, outputPrefix } =
+    options;
 
   return new Promise((resolvePromise, reject) => {
     const readAllowances = [bundleDir, projectRealpath, ...externalReadPaths].map(
@@ -106,9 +162,27 @@ export function forkSandboxed<T>(
       });
     }
 
+    // chant #1148 — forward, don't just capture. Both streams write to THIS
+    // process's stderr, prefixed and line-buffered, independent of
+    // `stderrBuf` below (which keeps accumulating raw stderr for
+    // `classifyChildError`'s use — forwarded and captured are not mutually
+    // exclusive, the same bytes feed both).
+    const forwardLine = (line: string): void => {
+      process.stderr.write(`${outputPrefix} ${line}\n`);
+    };
+    const stdoutForwarder = lineBuffered(forwardLine);
+    const stderrForwarder = lineBuffered(forwardLine);
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+      stdoutForwarder.push(chunk);
+    });
+    child.stdout?.on("end", () => stdoutForwarder.flush());
+
     child.stderr?.on("data", (chunk: Buffer) => {
       stderrBuf += chunk.toString();
+      stderrForwarder.push(chunk);
     });
+    child.stderr?.on("end", () => stderrForwarder.flush());
 
     child.on("message", (msg: unknown) => {
       if (settled || !isResponse(msg)) return;

package/src/discovery/sandbox/policy-boundary.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
 import { mkdir, writeFile, rm, realpath, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
@@ -281,6 +281,61 @@ describe("lint.policies execution under --sandbox (chant #1131)", () => {
     expect(await run([])).toEqual([]);
   });
 
+  /**
+   * chant #1148 — a policy's own `console.log`/`console.error` used to go
+   * nowhere under `--sandbox` (noted as a residual when #1131 shipped). Same
+   * relay as the run-fallback and config children, keyed to the policy
+   * module's own basename rather than a generic tag.
+   */
+  describe("console output forwarding (chant #1148)", () => {
+    beforeEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    afterEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    /** Spies on `process.stderr.write` and returns the lines captured so far — same shape as `../../cli/handlers/emulator.test.ts`'s `stdout()`/`stderr()` helpers. */
+    function captureStderr(): string[] {
+      const lines: string[] = [];
+      vi.spyOn(process.stderr, "write").mockImplementation((chunk: unknown) => {
+        lines.push(String(chunk));
+        return true;
+      });
+      return lines;
+    }
+
+    // See ./run.test.ts's identical helper doc: the IPC "message" the
+    // awaited call resolves on and the child's stdout/stderr pipe data are
+    // independent channels, so polling briefly avoids a flaky assertion.
+    async function waitFor(lines: string[], matcher: RegExp, timeoutMs = 5000): Promise<void> {
+      const start = Date.now();
+      while (Date.now() - start < timeoutMs) {
+        if (matcher.test(lines.join(""))) return;
+        await new Promise((r) => setTimeout(r, 10));
+      }
+      throw new Error(`stderr never matched ${matcher}. Captured so far:\n${lines.join("")}`);
+    }
+
+    test("a policy's console.log/console.error are forwarded, prefixed with [policy:<module-basename>]", async () => {
+      const stderr = captureStderr();
+      await writeMarkerPolicy(
+        "org.ts",
+        `console.log("hello from policy stdout");\n` +
+          `console.error("hello from policy stderr");\n` +
+          `export const c = { id: "X", description: "d", check: () => [] };\n`,
+      );
+      armSandboxPolicyExecution();
+
+      const diags = await run(["org.ts"]);
+
+      expect(diags).toEqual([]);
+      await waitFor(stderr, /^\[policy:org\.ts\] hello from policy stdout$/m);
+      await waitFor(stderr, /^\[policy:org\.ts\] hello from policy stderr$/m);
+    });
+  });
+
   test("a program that runs a policy child EXITS — the child is not left holding the event loop", async () => {
     // Found the hard way while measuring #1131's cost: unlike the run and
     // config drivers, the policy driver keeps a `message` listener registered

package/src/discovery/sandbox/policy-run.ts

@@ -1,5 +1,5 @@
 import { realpathSync, rmSync } from "node:fs";
-import { resolve } from "node:path";
+import { basename, resolve } from "node:path";
 import type { PostSynthDiagnostic } from "../../lint/post-synth";
 import { bundleDriver } from "./bundle";
 import { generatePolicyDriverSource } from "./driver";
@@ -79,6 +79,17 @@ interface PolicyChildResponse {
   error?: { name: string; file: string; message: string; type: string };
 }
 
+/**
+ * chant #1148 — `[policy:<module-basename>]`, joined when a project declares
+ * more than one policy module (all of them share the one child — see the
+ * module doc above). One policy module is the only shape this repo's own
+ * corpus exercises (`lexicons/k8s/examples/org-policy`), so this is the
+ * common case, not a hypothetical.
+ */
+function policyOutputPrefix(policyPaths: readonly string[]): string {
+  return `[policy:${policyPaths.map((p) => basename(p)).join(",")}]`;
+}
+
 function isPolicyChildResponse(value: unknown): value is PolicyChildResponse {
   return (
     typeof value === "object" &&
@@ -158,6 +169,9 @@ export async function runPoliciesSandboxed(options: SandboxPolicyOptions): Promi
         timeoutMs: POLICY_CHILD_TIMEOUT_MS,
         label: `sandboxed evaluation of lint.policies (${policyPaths.length} module(s))`,
         send: payload,
+        // chant #1148 — a policy's own console.log/error no longer goes
+        // nowhere; see `./fork.ts`'s `outputPrefix` doc.
+        outputPrefix: policyOutputPrefix(policyPaths),
       },
       isPolicyChildResponse,
     );

package/src/discovery/sandbox/run.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
 import { mkdir, writeFile, rm, realpath } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
@@ -176,4 +176,88 @@ describe("runFallbackFilesSandboxed — isolation", () => {
     expect(ref.getLogicalName?.()).toBe("dataBucket");
     expect(ref.attribute).toBe("Arn");
   });
+
+  /**
+   * chant #1148 — a run-fallback file's own `console.log`/`console.error`
+   * used to go nowhere: the child's stdout was piped but never read, and its
+   * stderr was captured only for `classifyChildError`'s use, never surfaced
+   * on a successful run. `./fork.ts` now relays both, line-buffered and
+   * prefixed, to THIS process's stderr — diagnostics crossing as data was
+   * never meant to mean incidental output vanishes.
+   */
+  describe("console output forwarding (chant #1148)", () => {
+    beforeEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    afterEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    /** Spies on `process.stderr.write` and returns the lines captured so far — same shape as `../../cli/handlers/emulator.test.ts`'s `stdout()`/`stderr()` helpers. */
+    function captureStderr(): string[] {
+      const lines: string[] = [];
+      vi.spyOn(process.stderr, "write").mockImplementation((chunk: unknown) => {
+        lines.push(String(chunk));
+        return true;
+      });
+      return lines;
+    }
+
+    // The child's IPC "message" (what the awaited call resolves on) and its
+    // stdout/stderr pipe data are two independent channels — nothing orders
+    // one ahead of the other, and #1147 deliberately keeps it that way (see
+    // the hang-regression test in policy-boundary.test.ts). Polling briefly
+    // rather than asserting immediately avoids a flaky test without giving
+    // the production path anything to wait for.
+    async function waitFor(lines: string[], matcher: RegExp, timeoutMs = 5000): Promise<void> {
+      const start = Date.now();
+      while (Date.now() - start < timeoutMs) {
+        if (matcher.test(lines.join(""))) return;
+        await new Promise((r) => setTimeout(r, 10));
+      }
+      throw new Error(`stderr never matched ${matcher}. Captured so far:\n${lines.join("")}`);
+    }
+
+    test("both console.log and console.error are forwarded, prefixed with [sandbox:run]", async () => {
+      const stderr = captureStderr();
+      const file = join(testDir, "noisy.ts");
+      await writeFile(
+        file,
+        `
+          console.log("hello from run-fallback stdout");
+          console.error("hello from run-fallback stderr");
+          export const value = "ok";
+        `,
+      );
+
+      const result = await runFallbackFilesSandboxed([file], testDir);
+
+      expect(result.errors).toEqual([]);
+      await waitFor(stderr, /^\[sandbox:run\] hello from run-fallback stdout$/m);
+      await waitFor(stderr, /^\[sandbox:run\] hello from run-fallback stderr$/m);
+    });
+
+    test("a file that exits hard still has its stderr in the classified error (forwarding doesn't replace capture)", async () => {
+      const stderr = captureStderr();
+      const file = join(testDir, "crashes.ts");
+      await writeFile(
+        file,
+        `
+          console.error("about to exit hard");
+          process.exit(1);
+        `,
+      );
+
+      const result = await runFallbackFilesSandboxed([file], testDir);
+
+      // A hard process.exit() takes the whole bundled child with it — this is
+      // fork.ts's pre-existing "child exited before reporting results" path,
+      // fed by the SAME stderrBuf that now also feeds forwarding.
+      expect(result.errors).toHaveLength(1);
+      expect(result.errors[0].message).toMatch(/about to exit hard/);
+
+      await waitFor(stderr, /^\[sandbox:run\] about to exit hard$/m);
+    });
+  });
 });

package/src/discovery/sandbox/run.ts

@@ -112,6 +112,9 @@ export async function runFallbackFilesSandboxed(
         env: { PATH: process.env.PATH ?? "" },
         timeoutMs: CHILD_TIMEOUT_MS,
         label: "sandboxed run",
+        // chant #1148 — a run-fallback file's own console.log/error no
+        // longer goes nowhere; see `./fork.ts`'s `outputPrefix` doc.
+        outputPrefix: "[sandbox:run]",
       },
       isChildResponse,
     );

package/src/env.test.ts

@@ -40,6 +40,18 @@ describe("unknownEnvError", () => {
   test("rejects an undeclared env with a clear message", () => {
     expect(unknownEnvError("stage", ["dev", "prod"])).toMatch(/Unknown environment "stage".*dev, prod/);
   });
+
+  // #1166 — `environments` entries may now be `{ name, endpoint }`; validation
+  // reduces to names either way, unaffected by an object entry's endpoint.
+  test("accepts an object-form declared env, mixed with bare strings", () => {
+    expect(unknownEnvError("floci", ["prod", { name: "floci", endpoint: "http://localhost:4566" }])).toBeUndefined();
+  });
+
+  test("rejects an undeclared env against a mixed string/object list, naming both", () => {
+    expect(
+      unknownEnvError("stage", ["prod", { name: "floci", endpoint: "http://localhost:4566" }]),
+    ).toMatch(/Unknown environment "stage".*prod, floci/);
+  });
 });
 
 describe("env-aware discovery (#505)", () => {

package/src/env.ts

@@ -18,6 +18,8 @@
  * pinhole renders/diffs them to show environment drift (INTENTIUS/pinhole#3).
  */
 
+import { environmentNames, type EnvironmentDeclaration } from "./config";
+
 /** The environment variable the CLI sets from `--env`. */
 export const ENV_VAR = "CHANT_ENV";
 
@@ -30,10 +32,16 @@ export function env(fallback?: string): string | undefined {
  * Validate a requested environment against the project's declared `environments`
  * (`chant.config`). Returns an error message for an unknown env, or `undefined`
  * when it's valid (or when the project declares no environments, in which case
- * any name is accepted).
+ * any name is accepted). `declared` entries may be a bare name or `{ name,
+ * endpoint }` (#1166) — {@link environmentNames} reduces either to the names
+ * this checks against.
  */
-export function unknownEnvError(requested: string | undefined, declared: string[] | undefined): string | undefined {
+export function unknownEnvError(
+  requested: string | undefined,
+  declared: EnvironmentDeclaration[] | undefined,
+): string | undefined {
   if (!requested || !declared || declared.length === 0) return undefined;
-  if (declared.includes(requested)) return undefined;
-  return `Unknown environment "${requested}". Declared environments: ${declared.join(", ")}.`;
+  const names = environmentNames(declared) ?? [];
+  if (names.includes(requested)) return undefined;
+  return `Unknown environment "${requested}". Declared environments: ${names.join(", ")}.`;
 }

package/src/fold/fold.ts

@@ -298,8 +298,18 @@ export function collectConsts(sourceFile: ts.SourceFile): Map<string, ts.Express
   return consts;
 }
 
-/** A property/element key foldable without execution: identifier, string, or numeric literal. */
-function propName(node: ts.PropertyName): string {
+/**
+ * A property/element key foldable without execution: identifier, string, or
+ * numeric literal.
+ *
+ * Exported for chant #1023's composite-factory interpreter
+ * (../discovery/fold-import.ts), which walks object literals itself — a
+ * factory body may construct a resource inside one, which {@link fold} has no
+ * case for — and must reject a computed key with the identical message
+ * {@link fold} would, rather than growing a second, silently divergent copy of
+ * this rule.
+ */
+export function propName(node: ts.PropertyName): string {
   if (isLiteralPropertyName(node)) return node.text;
   throw foldError(node, computedPropertyNameMessage(node));
 }

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

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { buildLiveGraphIr, overlayGraphs, sourceOverlayGraphs, type LiveObservation, type GraphIR } from "./graph-ir";
+import { buildLiveGraphIr, collectUnobserved, overlayGraphs, sourceOverlayGraphs, type LiveObservation, type GraphIR } from "./graph-ir";
 
 // A fixture "snapshot" — what a lexicon's describeResources() returns for a live
 // environment (managed-only). Two AWS resources; the subnet references the VPC by
@@ -140,4 +140,31 @@ describe("sourceOverlayGraphs (#821 source-anchored overlay)", () => {
     const ir = sourceOverlayGraphs(declared, liveDup);
     expect(ir.edges.filter((e) => e.from === "app-ingress" && e.to === "web-vpc")).toHaveLength(1);
   });
+
+  // #1089 — "not deployed yet" is a claim the read has to support.
+  it("paints a declared node nobody could read `neutral`, not `accent`", () => {
+    const ir = sourceOverlayGraphs(declared, live, {
+      unobserved: { "planned-db": { reason: "no-binding", detail: "no kubectl context" } },
+    });
+    const node = ir.nodes.find((x) => x.id === "planned-db")!;
+    expect((node.attrs as { _status?: string })._status).toBe("neutral");
+    expect((node.attrs as { _unobserved?: string })._unobserved).toBe("no-binding");
+  });
+
+  it("still paints a confirmed-absent declared node `accent`", () => {
+    const ir = sourceOverlayGraphs(declared, live, { unobserved: {} });
+    expect((ir.nodes.find((x) => x.id === "planned-db")!.attrs as { _status?: string })._status).toBe("accent");
+  });
+});
+
+describe("collectUnobserved (#1089)", () => {
+  it("unions every observation's holes", () => {
+    expect(
+      collectUnobserved([
+        { lexicon: "aws", resources: {}, unobserved: { a: { reason: "read-failed" } } },
+        { lexicon: "k8s", resources: {} },
+        { lexicon: "gcp", resources: {}, unobserved: { b: { reason: "no-binding" } } },
+      ]),
+    ).toEqual({ a: { reason: "read-failed" }, b: { reason: "no-binding" } });
+  });
 });

package/src/graph-ir.ts

@@ -6,6 +6,7 @@ import { isLexiconOutput, type LexiconOutput } from "./lexicon-output";
 import { getProvenance } from "./provenance";
 import { INTRINSIC_MARKER } from "./intrinsic";
 import type { ResourceMetadata } from "./lexicon";
+import type { UnobservedEntity } from "./observation";
 
 /**
  * Graph IR — the engine-neutral, lint-gated representation of a project's
@@ -419,6 +420,12 @@ function sortKeys(rec: Record<string, string[]>): Record<string, string[]> {
 export interface LiveObservation {
   lexicon: string;
   resources: Record<string, ResourceMetadata>;
+  /**
+   * Declared entities the lexicon could not observe (#1089), keyed by name.
+   * They are not live nodes — but they are not confirmed-absent either, so the
+   * overlay must not paint them "pending". See {@link sourceOverlayGraphs}.
+   */
+  unobserved?: Record<string, UnobservedEntity>;
 }
 
 /**
@@ -446,7 +453,10 @@ export function buildLiveGraphIr(observations: LiveObservation[]): GraphIR {
         attrs: meta.attributes ?? {},
       };
       if (meta.physicalId) node.physicalId = meta.physicalId;
-      if (meta.ownership) node.ownership = meta.ownership;
+      // `unknown` is a legitimate verdict on the metadata (#1089) but carries no
+      // information for a painter, and the IR's `ownership` field means "a
+      // verdict was reached" — so only owned/foreign land on the node.
+      if (meta.ownership === "owned" || meta.ownership === "foreign") node.ownership = meta.ownership;
       nodes.push(node);
       (byLexicon[lexicon] ??= []).push(name);
       // A live lexicon maps to one deployable stack, same as the source IR.
@@ -465,22 +475,60 @@ export function buildLiveGraphIr(observations: LiveObservation[]): GraphIR {
   return { nodes, edges: [], groups };
 }
 
+/** How an overlay learns which declared nodes were never looked at (#1089). */
+export interface OverlayOptions {
+  /**
+   * Declared entities the observation could not read, keyed by name (union of
+   * every {@link LiveObservation}'s `unobserved`). They are tagged `neutral`
+   * instead of `accent`: "not yet provisioned" is a claim the read never
+   * supported.
+   */
+  unobserved?: Record<string, UnobservedEntity>;
+}
+
+/** The union of every observation's unobserved entities — the input to the overlays. */
+export function collectUnobserved(observations: LiveObservation[]): Record<string, UnobservedEntity> {
+  const out: Record<string, UnobservedEntity> = {};
+  for (const o of observations) Object.assign(out, o.unobserved ?? {});
+  return out;
+}
+
+/** Paint status a node carries in an overlay. `neutral` = chant could not look. */
+type OverlayNodeStatus = "good" | "warn" | "accent" | "neutral";
+
+function tagStatus(n: IRNode, status: OverlayNodeStatus, unobserved?: UnobservedEntity): IRNode {
+  return {
+    ...n,
+    attrs: {
+      ...n.attrs,
+      _status: status,
+      ...(unobserved ? { _unobserved: unobserved.reason } : {}),
+    },
+  };
+}
+
 /**
  * Overlay the declared graph on the provisioned one (#780, `chant graph --live
  * --overlay`) and classify each resource, tagging a `_status` a renderer colours:
  *   - **managed** (declared + provisioned) → `good`
  *   - **foreign** (provisioned, not declared) → `warn`
- *   - **pending** (declared, not yet provisioned) → `accent`
+ *   - **pending** (declared, provider confirmed absent) → `accent`
+ *   - **unobserved** (declared, chant could not look — #1089) → `neutral`,
+ *     plus an `_unobserved` attr carrying the reason
  * Live nodes keep their edges/containment; pending nodes are appended (they have
  * no live edges). Sorted; the live groups pass through unchanged.
  */
-export function overlayGraphs(live: GraphIR, declared: GraphIR): GraphIR {
+export function overlayGraphs(live: GraphIR, declared: GraphIR, opts?: OverlayOptions): GraphIR {
   const declaredIds = new Set(declared.nodes.map((n) => n.id));
   const liveIds = new Set(live.nodes.map((n) => n.id));
-  const tagged = (n: IRNode, status: "good" | "warn" | "accent"): IRNode => ({ ...n, attrs: { ...n.attrs, _status: status } });
+  const unobserved = opts?.unobserved ?? {};
 
-  const nodes: IRNode[] = live.nodes.map((n) => tagged(n, declaredIds.has(n.id) ? "good" : "warn"));
-  for (const n of declared.nodes) if (!liveIds.has(n.id)) nodes.push(tagged(n, "accent"));
+  const nodes: IRNode[] = live.nodes.map((n) => tagStatus(n, declaredIds.has(n.id) ? "good" : "warn"));
+  for (const n of declared.nodes) {
+    if (liveIds.has(n.id)) continue;
+    const u = unobserved[n.id];
+    nodes.push(u ? tagStatus(n, "neutral", u) : tagStatus(n, "accent"));
+  }
   nodes.sort((a, b) => a.id.localeCompare(b.id));
 
   return { ...live, nodes };
@@ -497,27 +545,35 @@ export function overlayGraphs(live: GraphIR, declared: GraphIR): GraphIR {
  * Each declared node is classified against live observation and tagged `_status`:
  *   - **managed** (declared + provisioned) → `good`, carrying the observed
  *     `physicalId` / `ownership` onto the declared node
- *   - **pending** (declared, not provisioned) → `accent`
+ *   - **pending** (declared, provider confirmed absent) → `accent`
+ *   - **unobserved** (declared, chant could not look — #1089) → `neutral`, with
+ *     the reason on `_unobserved`. A wrong-cluster or unsupported-kind read used
+ *     to paint the whole estate "pending", which is the diagram equivalent of
+ *     planning a create for something that already exists.
  * **Foreign** resources (provisioned, not declared) are appended and tagged
  * `warn`, together with any live-reconstructed edges that touch them — a declared
  * edge cannot describe an undeclared resource. Declared groups/exports pass
  * through unchanged; nodes and edges are sorted for deterministic output.
  */
-export function sourceOverlayGraphs(declared: GraphIR, live: GraphIR): GraphIR {
+export function sourceOverlayGraphs(declared: GraphIR, live: GraphIR, opts?: OverlayOptions): GraphIR {
   const liveById = new Map(live.nodes.map((n) => [n.id, n]));
   const declaredIds = new Set(declared.nodes.map((n) => n.id));
   const foreignIds = new Set(live.nodes.filter((n) => !declaredIds.has(n.id)).map((n) => n.id));
-  const tagged = (n: IRNode, status: "good" | "warn" | "accent"): IRNode => ({ ...n, attrs: { ...n.attrs, _status: status } });
+  const unobserved = opts?.unobserved ?? {};
 
   const nodes: IRNode[] = declared.nodes.map((n) => {
     const obs = liveById.get(n.id);
-    if (!obs) return tagged(n, "accent"); // pending — declared, not provisioned
+    if (!obs) {
+      const u = unobserved[n.id];
+      // unobserved — declared, and nobody looked; not "pending"
+      return u ? tagStatus(n, "neutral", u) : tagStatus(n, "accent");
+    }
     const merged: IRNode = { ...n }; // managed — carry the observed identity
     if (obs.physicalId) merged.physicalId = obs.physicalId;
     if (obs.ownership) merged.ownership = obs.ownership;
-    return tagged(merged, "good");
+    return tagStatus(merged, "good");
   });
-  for (const n of live.nodes) if (foreignIds.has(n.id)) nodes.push(tagged(n, "warn")); // foreign
+  for (const n of live.nodes) if (foreignIds.has(n.id)) nodes.push(tagStatus(n, "warn")); // foreign
   nodes.sort((a, b) => a.id.localeCompare(b.id));
 
   // Declared edges are the canvas (the cross-substrate topology). Add only the