@intentius/chant 0.28.0 → 0.30.0

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

@@ -810,3 +810,108 @@ describe("foldModule", () => {
     expect(result.bad?.ok).toBe(false);
   });
 });
+
+/**
+ * chant #1169 — a `new Type(...)` used as a VALUE.
+ *
+ * `fold()` produces the same {@link FoldedResource} envelope for a nested
+ * construction as for a top-level one, and it is symbolic in exactly the sense
+ * `{__intrinsic}`/`{__helper}` are: nothing is executed here, the constructor's
+ * NAME and folded arguments are recorded, and ../discovery/fold-import.ts
+ * resolves the name through the file's own imports and builds the real
+ * instance. These tests own the envelope; the construction half is
+ * ../discovery/fold-import.test.ts's.
+ */
+describe("constructions as values (chant #1169)", () => {
+  test("a nested construction folds to a `{__resource}` envelope, recursively", () => {
+    const src = `
+      export const job = new Job({
+        image: new Image({ name: "node:22" }),
+        rules: [new Rule({ if: "$CI" })],
+        deep: { inner: new Guest({ cpus: new Count({ n: 1 }) }) },
+      });
+    `;
+    expect(foldModule(src).job).toEqual({
+      ok: true,
+      spec: {
+        __resource: "Job",
+        props: {
+          image: { __resource: "Image", props: { name: "node:22" } },
+          rules: [{ __resource: "Rule", props: { if: "$CI" } }],
+          deep: {
+            inner: { __resource: "Guest", props: { cpus: { __resource: "Count", props: { n: 1 } } } },
+          },
+        },
+      },
+    });
+  });
+
+  test("a nested construction with a non-props-first signature keeps its positional `args`", () => {
+    // chant #1082's shape, nested. `props` stays the first object-literal
+    // argument (a view, for readers); `args` is what the entity is built from.
+    const src = `export const p = new Outer({ x: new Parameter("String", { Default: "dev" }) });`;
+    const result = foldModule(src);
+    expect(result.p?.ok).toBe(true);
+    if (!result.p?.ok) return;
+    expect(result.p.spec.props.x).toEqual({
+      __resource: "Parameter",
+      props: { Default: "dev" },
+      args: ["String", { Default: "dev" }],
+    });
+  });
+
+  test("a nested `new ns.Type(...)` is rejected — the class must be reachable through a named import", () => {
+    const src = `export const job = new Job({ image: new ns.Image({ name: "x" }) });`;
+    const result = foldModule(src);
+    expect(result.job?.ok).toBe(false);
+    if (result.job?.ok) return;
+    expect(result.job?.error).toContain("needs a plain imported constructor");
+  });
+
+  test("a BARE reference to a same-file resource const is rejected without a caller that can construct", () => {
+    // `fold()` on its own has no module graph, so it cannot hand back the
+    // instance the reference means — and re-folding the initializer would build
+    // a duplicate. Rejected; `externals` (the bridge's pre-resolved same-file
+    // instances) is the only thing that answers this.
+    const src = `
+      const db = new DbCluster({ engine: "aurora" });
+      export const worker = new Instance({ needs: [db] });
+    `;
+    const result = foldModule(src);
+    expect(result.worker?.ok).toBe(false);
+    if (result.worker?.ok) return;
+    expect(result.worker?.error).toContain("same-file resource `db` used as a value is not foldable");
+  });
+
+  test("`externals` answers a same-file resource reference when a caller pre-resolved it", () => {
+    const src = `
+      const db = new DbCluster({ engine: "aurora" });
+      export const worker = new Instance({ needs: [db] });
+    `;
+    const sourceFile = ts.createSourceFile("t.ts", src, ts.ScriptTarget.Latest, true);
+    const consts = collectConsts(sourceFile);
+    const liveDb = { pretendInstance: true };
+
+    const folded = fold(consts.get("worker") as ts.Expression, consts, [], new Map([["db", liveDb]]));
+    // The exact object, not a copy of it: identity is what makes the reference
+    // and the registered entity the same thing.
+    expect((folded as { props: { needs: unknown[] } }).props.needs[0]).toBe(liveDb);
+  });
+
+  test("an ATTRIBUTE reference to a same-file resource is unaffected — still the `{__attrRef}` envelope", () => {
+    const src = `
+      const db = new DbCluster({ engine: "aurora" });
+      export const worker = new Instance({ host: db.Endpoint });
+    `;
+    const sourceFile = ts.createSourceFile("t.ts", src, ts.ScriptTarget.Latest, true);
+    const consts = collectConsts(sourceFile);
+
+    const folded = fold(consts.get("worker") as ts.Expression, consts, [], new Map([["db", { live: true }]]));
+    // `consts` is consulted before `externals` for a property access, so a
+    // pre-resolved instance does not change what a sibling attribute reference
+    // folds to.
+    expect((folded as { props: Record<string, unknown> }).props.host).toEqual({
+      __attrRef: { entity: "db", attribute: "Endpoint" },
+    });
+  });
+});

package/src/fold/fold.ts

@@ -27,12 +27,23 @@ import { isFoldableHelperName } from "./foldable-helpers";
  * cross-resource `{ __attrRef }` case, literal-key-only), unary `!`/`-`,
  * the binary operators `+ - * / === !== > < >= <=`, short-circuit
  * `&& || ??`, conditional expressions, `as`/`satisfies`/`!`/parenthesized
- * unwrapping, a nested `new Type({...})` resource-as-value, and registered
- * lexicon intrinsic tagged templates — is defined ONCE, in {@link "./subset"}
- * ({@link findSubsetViolation}), and shared with EVL001/EVL003
+ * unwrapping, a nested `new Type({...})` resource-as-value (chant #1169), and
+ * registered lexicon intrinsic tagged templates — is defined ONCE, in
+ * {@link "./subset"} ({@link findSubsetViolation}), and shared with EVL001/EVL003
  * ({@link "../lint/rules/evl001-non-literal-expression"}), so the linted
  * subset and the folded subset can never drift apart (#1024).
  *
+ * chant #1169 closed the largest of the documented fold/EVL divergences in the
+ * process: a nested `new Type(...)` used as a value was shape-valid for
+ * `./subset` and rejected by `fold()`, because `fold()` could only produce the
+ * `{__resource, props}` envelope and nothing constructed it. Now it folds to
+ * that envelope and ../discovery/fold-import.ts constructs the REAL instance
+ * from it. The remaining divergences are the resolution-dependent ones
+ * ./subset's own module doc enumerates, plus one this change adds in the same
+ * safe direction: a BARE identifier bound to a same-file `new` is shape-valid
+ * there and rejected here, because folding it would build a duplicate of a
+ * resource discovery already registered — see {@link fold}'s identifier branch.
+ *
  * A `CallExpression` has almost no case — a function call as a value is
  * structurally unrepresentable, not merely linted against. Composite
  * factory calls are out of scope here (epic Phase 5, #1023). There are
@@ -170,6 +181,15 @@ export interface SymbolicValue {
 
 /**
  * The result of folding a resource constructor: `new Type({ ...props })`.
+ *
+ * chant #1169 — produced for a NESTED `new Type(...)` used as a value too, not
+ * just for a file's own top-level resource declaration. It is symbolic in
+ * exactly the sense {@link FoldedIntrinsic} and {@link FoldedHelperCall} are:
+ * `fold()` executes nothing, it records which constructor the source named and
+ * with what arguments. ../discovery/fold-import.ts resolves that name through
+ * the folding file's own imports and calls the real class, so a folded
+ * construction and a run construction are the same construction. An envelope
+ * must never reach a serializer — see the `new` branch of {@link fold}.
  */
 export interface FoldedResource {
   __resource: string;
@@ -298,8 +318,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));
 }
@@ -536,7 +566,37 @@ export function fold(
       }
       throw foldError(node, `unresolved identifier: ${node.text}`);
     }
-    return fold(consts.get(node.text) as ts.Expression, consts, intrinsics, externals);
+    const initializer = consts.get(node.text) as ts.Expression;
+    // chant #1169 — a BARE reference to a same-file `const x = new T(...)` is a
+    // reference to THAT resource instance, and the ONE thing it must never
+    // become is a second one. Re-folding the initializer here would do exactly
+    // that now that the `new` branch below constructs: the consumer would get a
+    // duplicate object discovery never registered, whose `AttrRef`s could never
+    // be assigned a logical name ("Cannot serialize AttrRef …: logical name not
+    // set") and whose `Ref` would silently inline instead of referencing. A
+    // crash or wrong output, not drift.
+    //
+    // So `externals` — and ONLY `externals` — answers this one. A caller with a
+    // module graph (../discovery/fold-import.ts) pre-resolves each of this
+    // file's `new`-valued consts to ONE instance, in source order, before any
+    // declarator is folded, and puts it here; every reference in the file then
+    // reads that same object, exactly as running the module top-to-bottom
+    // would. A caller without one (`foldModule`, a unit test) has no way to
+    // construct anything, so the reference stays a rejection and the file falls
+    // back to run.
+    //
+    // `bucket.name` is a different question and keeps its answer regardless: the
+    // property-access branch below consults `consts` first, so a sibling
+    // attribute reference is still the symbolic `{__attrRef}` the serializer
+    // resolves by NAME. Nothing about the existing envelope changes.
+    if (ts.isNewExpression(initializer)) {
+      if (externals?.has(node.text)) return externals.get(node.text) as FoldedValue;
+      throw foldError(
+        node,
+        `same-file resource \`${node.text}\` used as a value is not foldable — falls back to run`,
+      );
+    }
+    return fold(initializer, consts, intrinsics, externals);
   }
 
   if (ts.isPropertyAccessExpression(node)) {
@@ -626,20 +686,40 @@ export function fold(
   }
 
   if (ts.isNewExpression(node)) {
-    // A nested `new Type({...})` used as a property VALUE is not leaf-foldable.
-    // fold can only produce the {__resource, props} envelope, and — unlike a
-    // TOP-LEVEL resource, which fold-import constructs into a real Declarable —
-    // a nested one is never constructed, so the envelope leaks into serialization
-    // as the wrong value (real fold-vs-run drift; the #1025 differential caught
-    // this on gitlab/multi-stage-deploy, where `new Image({...})` as a job's
-    // `image:` must serialize as `{ name }`, not `{ __resource, props }`).
-    // Reject so the file falls back to run, which constructs and serializes it
-    // correctly. EVL permits this statically — it's a documented fold/EVL
-    // divergence, like identifier resolution and spread runtime type.
-    throw foldError(
-      node,
-      `nested \`new ${briefNodeText(node.expression)}(...)\` as a value is not foldable — falls back to run`,
-    );
+    // chant #1169 — a nested `new Type({...})` used as a property VALUE folds
+    // to the SAME {@link FoldedResource} envelope a top-level resource
+    // declaration does, and is constructed for real by the same bridge.
+    //
+    // This used to be an unconditional rejection, and the reason it was is
+    // worth keeping in view: `fold()` alone can only produce the envelope, and
+    // an envelope that reaches serialization is the wrong value — the #1025
+    // differential caught exactly that on gitlab/multi-stage-deploy, where
+    // `new Image({...})` as a job's `image:` must serialize as the constructed
+    // Image's own shape, not as `{__resource, props}`. What changed is not the
+    // envelope's safety but who consumes it: ../discovery/fold-import.ts's
+    // `reviveFoldedValue` now REVIVES a `{__resource}` node into a real
+    // instance, built by the class the file's own `import` names, resolved
+    // through the same provenance-checked machinery that already constructs a
+    // top-level resource (and that #1023's factory interpreter already uses to
+    // construct a nested `new` inside a factory body — the asymmetry that
+    // motivated this change). Nothing symbolic survives into the serializer:
+    // the value the outer constructor receives is the same object the run path
+    // would have handed it, with the same prototype, the same `props`, and the
+    // same `toJSON`/`kind` the serializer's walker dispatches on.
+    //
+    // Only a PLAIN IDENTIFIER constructor is admissible. `new ns.Type(...)`
+    // cannot be resolved to a live class through the file's named imports, so
+    // it stays a rejection rather than folding to an envelope nothing can
+    // revive — the same bare-identifier rule #1023's `checkFactoryExpression`
+    // applies to a body-level construction, and the same one `fold()` applies
+    // to an intrinsic call and an authoring helper.
+    if (!ts.isIdentifier(node.expression)) {
+      throw foldError(
+        node,
+        `nested \`new ${briefNodeText(node.expression)}(...)\` as a value needs a plain imported constructor — falls back to run`,
+      );
+    }
+    return foldResource(node, consts, intrinsics, externals);
   }
 
   if (ts.isCallExpression(node)) {

package/src/fold/subset.test.ts

@@ -258,18 +258,49 @@ describe("documented divergences — NOT unified by design (see subset.ts module
     expect(evl001NonLiteralExpressionRule.check(context)).toHaveLength(0);
   });
 
-  test("nested resource construction: fold rejects a nested `new Type()` used as a value (falls back to run); EVL001 allows it statically", () => {
-    // A top-level `new Type()` folds (fold-import constructs a real Declarable),
-    // but a NESTED one as a property value can only fold to a {__resource,props}
-    // envelope that is never constructed, so it would serialize wrong (real
-    // fold-vs-run drift, caught by the #1025 differential on gitlab). fold()
-    // therefore rejects it, falling the file back to run; EVL allows it (a valid
-    // TS constructor call), so this is an inherent, out-of-scope divergence.
+  test("nested resource construction: NO LONGER a divergence (chant #1169) — both fold and EVL001 accept it", () => {
+    // This was the largest divergence in the table until #1169: a nested
+    // `new Type()` as a property value could only fold to a {__resource, props}
+    // envelope nothing constructed, so it would have serialized wrong (real
+    // fold-vs-run drift, caught by the #1025 differential on gitlab), and fold()
+    // rejected it while EVL allowed it.
+    //
+    // fold() now produces the envelope and ../discovery/fold-import.ts revives
+    // it into a REAL instance of the class the file imported, so the two sides
+    // agree. Kept as a test rather than deleted: it is the assertion that the
+    // divergence stays closed, and that the envelope carries the nested
+    // constructor's own name and props for the bridge to build from.
     const source = `const bad = new Thing({ x: new Inner({ y: 1 }) });`;
     const sourceFile = ts.createSourceFile("t.ts", source, ts.ScriptTarget.Latest, true);
     const consts = collectConsts(sourceFile);
     const badInit = consts.get("bad") as ts.NewExpression;
 
+    expect(foldResource(badInit, consts, [])).toEqual({
+      __resource: "Thing",
+      props: { x: { __resource: "Inner", props: { y: 1 } } },
+    });
+
+    const context: LintContext = { sourceFile, entities: [], filePath: "t.ts", lexicon: undefined };
+    expect(evl001NonLiteralExpressionRule.check(context)).toHaveLength(0);
+  });
+
+  test("same-file resource used as a bare value: fold rejects it (would build a duplicate); EVL001 allows it statically", () => {
+    // chant #1169's own new divergence, in the same safe direction as every
+    // other one here. `DependsOn: [dbCluster]` hands the run path THE instance
+    // this file already exported; folding the identifier would construct a
+    // SECOND one, which discovery never registers and whose AttrRefs can never
+    // be named. Rejected, so the file falls back to run — where both references
+    // are the same object by construction. EVL sees a plain identifier and has
+    // no binding resolver (subset.ts module doc, point 1), so it stays
+    // permissive.
+    const source = `
+      const db = new DbCluster({ engine: "aurora" });
+      const bad = new Instance({ x: 1 }, { DependsOn: [db] });
+    `;
+    const sourceFile = ts.createSourceFile("t.ts", source, ts.ScriptTarget.Latest, true);
+    const consts = collectConsts(sourceFile);
+    const badInit = consts.get("bad") as ts.NewExpression;
+
     expect(() => foldResource(badInit, consts, [])).toThrow(FoldError);
 
     const context: LintContext = { sourceFile, entities: [], filePath: "t.ts", lexicon: undefined };

package/src/fold/subset.ts

@@ -35,6 +35,15 @@ import { intrinsicCallFolds, type IntrinsicDef } from "../lexicon";
  *      intentional asymmetry, not a bug: it can only ever be a *false
  *      negative* on EVL's part (EVL passes something `fold()` might later
  *      reject for being unresolved), never the reverse.
+ *
+ *      chant #1169 adds one more resolution-dependent rejection in the same
+ *      direction: an identifier bound to a same-file `const x = new T(...)`,
+ *      used as a VALUE. It is shape-valid here; `fold()` answers it only when
+ *      its caller pre-resolved that const to the one real instance the file
+ *      built (`../discovery/fold-import.ts`), and rejects otherwise, because
+ *      re-folding the initializer would construct a duplicate of a resource
+ *      discovery has already registered. Shape cannot see the difference, and
+ *      the rejection is a fall-back-to-run, never a wrong value.
  *   2. Tagged-template *tag registration* — needs a lexicon's intrinsics
  *      manifest, which isn't available to a syntax-only lint rule. `fold()`
  *      alone checks it; this module treats any tag name as shape-valid and

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
@@ -123,6 +124,51 @@ export interface IRImport {
   node: string;
 }
 
+/**
+ * One generated CI job in the pipeline projection (`chant graph --components
+ * --format ir --projection <lexicon>`, #989) — the same job a CI-provider
+ * lexicon's `generateComponentPipeline` synthesizes for `chant build
+ * --components --generate <lexicon>` (see `ComponentPipelineJob`,
+ * ./lexicon.ts), reshaped into the IR's node vocabulary.
+ */
+export interface IRPipelineNode {
+  /** CI job name (the generator's job id — a safe YAML/workflow key). */
+  id: string;
+  kind: "CIJob";
+  /** The component this job triggers. */
+  component: string;
+  /** The stage/wave this job runs in — the same wave index as the component
+   * graph's `groups.byWave` (one CI stage/`needs:`-level per wave). */
+  stage: string;
+}
+
+/** A `needs:` dependency between two generated CI jobs — mirrors the
+ * `dependsOn` edge it derives from, consumer job → producer job. */
+export interface IRPipelineEdge {
+  from: string;
+  to: string;
+  kind: "needs";
+}
+
+/**
+ * The CI/pipeline projection of a component graph (#989): the stages/jobs/
+ * `needs` a CI-provider lexicon (gitlab, github, forgejo, or any lexicon
+ * implementing `generateComponentPipeline`) would synthesize for `chant build
+ * --components --generate <lexicon>`, reused here — never re-derived — as
+ * first-class IR nodes/edges. A consumer (e.g. behold) reads this alongside
+ * the component graph's `nodes`/`edges`/`groups.byWave` to render the CI
+ * shape without parsing generated YAML. Present only when `chant graph
+ * --components --format ir` is invoked with `--projection <lexicon>`.
+ */
+export interface IRPipeline {
+  /** The CI-provider lexicon that produced this projection (e.g. "gitlab"). */
+  provider: string;
+  /** Wave-ordered stage names — 1:1 with the component graph's `groups.byWave` keys. */
+  stages: string[];
+  nodes: IRPipelineNode[];
+  edges: IRPipelineEdge[];
+}
+
 /** The full graph IR for a project at the default (declarable) detail level. */
 export interface GraphIR {
   nodes: IRNode[];
@@ -134,6 +180,8 @@ export interface GraphIR {
    * `name` to another stack's export `name` to draw the cross-stack edge; the
    * parameter's in-stack consumers are ordinary `$ref` edges to it (#513). */
   imports?: IRImport[];
+  /** The CI/pipeline projection alongside the component graph (#989) — see {@link IRPipeline}. */
+  pipeline?: IRPipeline;
 }
 
 /** A node is anything that serializes to a resource — not a property or output. */
@@ -419,6 +467,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 +500,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 +522,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 +592,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