@intentius/chant 0.28.0 → 0.29.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.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

package/src/index.ts

@@ -48,6 +48,7 @@ export * from "./lint/discover";
 export * from "./import/parser";
 export * from "./import/generator";
 export * from "./lexicon";
+export * from "./observation";
 export * from "./lexicon-integrity";
 export * from "./lexicon-manifest";
 export * from "./lexicon-schema";

package/src/kubectl-context.ts

@@ -22,6 +22,7 @@
 
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
+import type { UnobservedReason } from "./observation";
 
 const execAsync = promisify(exec);
 
@@ -124,3 +125,83 @@ export async function resolveClusterTarget(
 
   return { context: bound, source: "bound" };
 }
+
+// ── kubectl read outcomes (#1089) ───────────────────────────────────────────
+
+/**
+ * What a failed `kubectl get` actually proved. Shared by the k8s and gcp
+ * lexicons, which read through the same kubectl path and used to collapse every
+ * non-zero exit into "not there" — so an expired token, a downed API server, or
+ * an uninstalled CRD all classified as `create`.
+ */
+export type KubectlReadOutcome =
+  /** The API server answered and the object is not there. Safe to plan a create. */
+  | { kind: "absent" }
+  /** The read proved nothing about the object's existence. */
+  | { kind: "unobserved"; reason: UnobservedReason; detail: string };
+
+/** Pull whatever the child process actually said out of an exec rejection. */
+function execErrorText(err: unknown): string {
+  if (typeof err === "object" && err !== null) {
+    const e = err as { stderr?: unknown; message?: unknown };
+    const stderr = typeof e.stderr === "string" ? e.stderr.trim() : "";
+    if (stderr) return stderr;
+    if (typeof e.message === "string") return e.message.trim();
+  }
+  return String(err);
+}
+
+/** Collapse kubectl's noise to one line for a plan/diff entry. */
+function firstLine(text: string, max = 200): string {
+  const line = text.split("\n").find((l) => l.trim().length > 0)?.trim() ?? text.trim();
+  return line.length > max ? `${line.slice(0, max - 3)}...` : line;
+}
+
+/**
+ * Classify a `kubectl get` failure into the observation tri-state (#1089).
+ *
+ * Only a genuine `NotFound` from the API server — or a kind the server does not
+ * serve at all, where no instance can exist — establishes absence. Auth,
+ * connectivity, and unresolvable contexts establish nothing, and must reach the
+ * change set as NOT-OBSERVED rather than as an empty result.
+ */
+export function classifyKubectlFailure(err: unknown): KubectlReadOutcome {
+  const text = execErrorText(err);
+  const lower = text.toLowerCase();
+
+  // The object was looked for and is not there.
+  if (lower.includes("notfound") || /error from server \(notfound\)/.test(lower) || lower.includes("not found")) {
+    return { kind: "absent" };
+  }
+  // The cluster serves no such kind, so no instance of it can exist there. The
+  // usual cause is a CRD this same plan has not applied yet — a real absence,
+  // and the case a create is for.
+  if (
+    lower.includes("the server doesn't have a resource type") ||
+    lower.includes("the server could not find the requested resource")
+  ) {
+    return { kind: "absent" };
+  }
+  if (
+    lower.includes("unauthorized") ||
+    lower.includes("forbidden") ||
+    lower.includes("you must be logged in") ||
+    lower.includes("invalid bearer token") ||
+    lower.includes("credentials")
+  ) {
+    return { kind: "unobserved", reason: "no-credentials", detail: firstLine(text) };
+  }
+  if (
+    lower.includes("unable to connect to the server") ||
+    lower.includes("connection refused") ||
+    lower.includes("no configuration has been provided") ||
+    lower.includes("did you specify the right host or port") ||
+    lower.includes("context was not found") ||
+    /context ".*" does not exist/.test(lower) ||
+    lower.includes("no such host") ||
+    lower.includes("i/o timeout")
+  ) {
+    return { kind: "unobserved", reason: "no-binding", detail: firstLine(text) };
+  }
+  return { kind: "unobserved", reason: "read-failed", detail: firstLine(text) };
+}

package/src/lexicon.ts

@@ -11,11 +11,23 @@ import type { DriverComponent } from "./components/driver";
 import type { EmulatorCapability } from "./op/emulator-lifecycle";
 import type { RuleMeta } from "./audit/catalog";
 import type { ReferenceCatalog } from "./graph-refs";
+import type { DescribeResourcesResult } from "./observation";
 
 // Re-exported so lexicons can author a reference catalog (#778) from the same
 // `@intentius/chant/lexicon` entry they import the plugin contract from.
 export type { ReferenceCatalog, IdentityRule, RefRule } from "./graph-refs";
 
+// The observation contract (#1089), re-exported from the same entry so a
+// lexicon's `describeResources` can report NOT-OBSERVED without a second
+// import path. Runtime helpers live in `@intentius/chant/observation`.
+export type {
+  DescribeResourcesResult,
+  ObservationResult,
+  NormalizedObservation,
+  UnobservedEntity,
+  UnobservedReason,
+} from "./observation";
+
 /**
  * Manifest for a packaged lexicon — metadata embedded in the tarball.
  *
@@ -507,6 +519,27 @@ export interface LexiconPlugin {
    * Use this when each chant entity has a 1:1 cloud equivalent — e.g. an
    * AWS CFN resource, a K8s object, an ARM resource, a Temporal namespace.
    *
+   * **The observation contract (#1089).** Returning nothing for a declared
+   * entity is a claim, and there are two different claims to make. Either the
+   * provider was asked and reported the resource absent — which is what lets
+   * the change set propose `create` — or the lexicon never looked, which must
+   * not. An implementation that has a "did not look" case (no reader for the
+   * kind, the read errored, no credentials, no cluster binding) must return the
+   * {@link ObservationResult} envelope and name those entities in `unobserved`
+   * with a total {@link UnobservedReason}. Warning on stderr is not enough: a
+   * warning is invisible to `lifecycle plan`, which is where the wrong `create`
+   * gets proposed. Returning the bare `name → ResourceMetadata` map is still
+   * valid and means "everything I was asked about, I looked at".
+   *
+   * Throwing is the whole-lexicon failure (see the k8s cluster-binding refusal,
+   * #1100): core catches it and marks every declared entity NOT-OBSERVED with
+   * `read-failed`, so a failed read is never a list of creates.
+   *
+   * Ownership verdicts are total (#1089). When `owned` is requested and the
+   * lexicon has no marker channel on this path, it must stamp
+   * `ownership: "unknown"` on what it returns rather than degrading silently —
+   * the change set never escalates `unknown` to a `delete`.
+   *
    * `entities` carries the chant-side entity declarations for this lexicon,
    * keyed by chant entity name (e.g. the export name from a `*.ts` file).
    * Implementations that need to map cloud-side names back to chant entity
@@ -536,7 +569,7 @@ export interface LexiconPlugin {
      * everything.
      */
     owned?: boolean;
-  }): Promise<Record<string, ResourceMetadata>>;
+  }): Promise<DescribeResourcesResult>;
 
   /**
    * Report the live status of one deploy unit by its deployed name. Opt-in.
@@ -683,12 +716,14 @@ export interface ResourceMetadata {
   /** Cloud-assigned output properties */
   attributes?: Record<string, unknown>;
   /**
-   * Live ownership verdict from the resource's marker (#119/#120), when the
-   * lexicon could determine it. `owned` = carries chant's marker; `foreign` =
-   * no marker. Absent = the lexicon has no marker channel here. The change set
-   * reads this — never the snapshot — to decide whether an orphan is a delete.
+   * Live ownership verdict from the resource's marker (#119/#120). `owned` =
+   * carries chant's marker; `foreign` = no marker; `unknown` = the lexicon has
+   * no marker channel on this read path and says so rather than degrading
+   * silently (#1089 — verdicts are total). Absent is read as `unknown`. The
+   * change set reads this — never the snapshot — to decide whether an orphan is
+   * a delete, and never escalates `unknown` to one.
    */
-  ownership?: "owned" | "foreign";
+  ownership?: "owned" | "foreign" | "unknown";
 }
 
 /**

package/src/lifecycle/change-set.test.ts

@@ -17,7 +17,7 @@ describe("buildChangeSet (#118)", () => {
     });
     const e = cs.entries.find((x) => x.name === "bucket")!;
     expect(e.action).toBe("create");
-    expect(e.evidence).toEqual({ declared: true, inSnapshot: false, live: false });
+    expect(e.evidence).toEqual({ declared: true, inSnapshot: false, live: false, observed: true });
     expect(e.ownership).toBe("unknown");
   });
 
@@ -187,3 +187,95 @@ describe("gitlabMrReport (#329)", () => {
     expect(gitlabMrReport(cs)).toEqual({ create: 0, update: 0, delete: 0 });
   });
 });
+
+// ── The observation tri-state (#1089) ───────────────────────────────────────
+
+describe("buildChangeSet: not-observed is not absent (#1089)", () => {
+  test("declared and not observed → unobserved, never create", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["crd-widget"]),
+      observedNow: {},
+      observedThen: undefined,
+      unobserved: {
+        "crd-widget": {
+          type: "K8s::Example::Widget",
+          reason: "unsupported-kind",
+          detail: "no kubectl mapping",
+        },
+      },
+    });
+    const e = cs.entries.find((x) => x.name === "crd-widget")!;
+    expect(e.action).toBe("unobserved");
+    expect(e.evidence).toEqual({ declared: true, inSnapshot: false, live: false, observed: false });
+    expect(e.unobservedReason).toBe("unsupported-kind");
+    expect(e.type).toBe("K8s::Example::Widget");
+  });
+
+  test("the same entity, confirmed absent, still classifies as create", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["crd-widget"]),
+      observedNow: {},
+      observedThen: undefined,
+    });
+    expect(cs.entries.find((x) => x.name === "crd-widget")!.action).toBe("create");
+  });
+
+  test("a returned resource wins over an unobserved claim for the same name", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["queue"]),
+      observedNow: { queue: meta() },
+      observedThen: undefined,
+      unobserved: { queue: { reason: "read-failed" } },
+    });
+    const e = cs.entries.find((x) => x.name === "queue")!;
+    expect(e.action).toBe("noop");
+    expect(e.evidence.observed).toBe(true);
+  });
+
+  test("an unobserved entity that is in the snapshot is not read as gone", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["queue"]),
+      observedNow: {},
+      observedThen: { queue: meta() },
+      unobserved: { queue: { reason: "no-credentials" } },
+    });
+    const e = cs.entries.find((x) => x.name === "queue")!;
+    expect(e.action).toBe("unobserved");
+    expect(e.evidence.inSnapshot).toBe(true);
+  });
+
+  test("an unobserved entity is never a delete, even with an owned marker in the snapshot", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(),
+      observedNow: {},
+      observedThen: { legacy: meta({ ownership: "owned" }) },
+      unobserved: { legacy: { reason: "read-failed" } },
+    });
+    expect(cs.entries.find((x) => x.name === "legacy")!.action).toBe("unobserved");
+  });
+
+  test("summarize and render surface the hole", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["a"]),
+      observedNow: {},
+      observedThen: undefined,
+      unobserved: { a: { reason: "no-binding", detail: "no kubectl context for prod" } },
+    });
+    expect(summarize(cs).unobserved).toBe(1);
+    expect(summarize(cs).create).toBe(0);
+    const out = renderChangeSet(cs);
+    expect(out).toContain("UNOBSERVED");
+    expect(out).toContain("no binding for this environment");
+    expect(out).toContain("no kubectl context for prod");
+  });
+
+  test("the GitLab widget excludes unobserved — its three columns cannot express a hole", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["a"]),
+      observedNow: {},
+      observedThen: undefined,
+      unobserved: { a: { reason: "read-failed" } },
+    });
+    expect(gitlabMrReport(cs)).toEqual({ create: 0, update: 0, delete: 0 });
+  });
+});