@intentius/chant 0.27.0 → 0.29.0

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

@@ -0,0 +1,94 @@
+import { describe, test, expect, vi, beforeEach } from "vitest";
+
+const execMock = vi.fn();
+vi.mock("node:child_process", async () => {
+  const actual = await vi.importActual<typeof import("node:child_process")>("node:child_process");
+  return {
+    ...actual,
+    exec: (cmd: string, cb: (err: Error | null, out: { stdout: string; stderr: string }) => void) => {
+      Promise.resolve(execMock(cmd)).then(
+        (out) => cb(null, out as { stdout: string; stderr: string }),
+        (err) => cb(err as Error, { stdout: "", stderr: "" }),
+      );
+    },
+  };
+});
+
+const { resolveClusterTarget, ClusterBindingMismatchError } = await import("./kubectl-context");
+
+describe("resolveClusterTarget (chant #1100)", () => {
+  beforeEach(() => {
+    execMock.mockReset();
+  });
+
+  test("no binding declared: returns ambient source, warns visibly, never probes kubectl", async () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    const target = await resolveClusterTarget({}, "prod", "k8s");
+
+    expect(target).toEqual({ source: "ambient" });
+    expect(execMock).not.toHaveBeenCalled();
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringMatching(/\[k8s\].*environment "prod".*k8s\.profiles\.prod\.context/s),
+    );
+    warnSpy.mockRestore();
+  });
+
+  test("bound and ambient context matches: returns the bound context", async () => {
+    execMock.mockResolvedValue({ stdout: "prod-eks\n", stderr: "" });
+
+    const target = await resolveClusterTarget(
+      { k8s: { profiles: { prod: { context: "prod-eks" } } } },
+      "prod",
+      "k8s",
+    );
+
+    expect(target).toEqual({ context: "prod-eks", source: "bound" });
+    expect(execMock).toHaveBeenCalledWith(expect.stringContaining("current-context"));
+  });
+
+  test("bound and ambient context cannot be determined: proceeds with the bound context anyway", async () => {
+    execMock.mockRejectedValue(new Error("no kubeconfig"));
+
+    const target = await resolveClusterTarget(
+      { k8s: { profiles: { prod: { context: "prod-eks" } } } },
+      "prod",
+      "k8s",
+    );
+
+    expect(target).toEqual({ context: "prod-eks", source: "bound" });
+  });
+
+  test("bound and ambient context mismatches: refuses loudly, naming env/expected/ambient", async () => {
+    execMock.mockResolvedValue({ stdout: "staging-eks\n", stderr: "" });
+
+    const err: unknown = await resolveClusterTarget(
+      { k8s: { profiles: { prod: { context: "prod-eks" } } } },
+      "prod",
+      "k8s",
+    ).catch((e: unknown) => e);
+
+    expect(err).toBeInstanceOf(ClusterBindingMismatchError);
+    const mismatch = err as InstanceType<typeof ClusterBindingMismatchError>;
+    expect(mismatch.environment).toBe("prod");
+    expect(mismatch.expectedContext).toBe("prod-eks");
+    expect(mismatch.ambientContext).toBe("staging-eks");
+    expect(mismatch.message).toContain('environment "prod"');
+    expect(mismatch.message).toContain('"prod-eks"');
+    expect(mismatch.message).toContain('"staging-eks"');
+  });
+
+  test("bound for a different environment than the one requested: treated as unbound for this environment", async () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    const target = await resolveClusterTarget(
+      { k8s: { profiles: { staging: { context: "staging-eks" } } } },
+      "prod",
+      "k8s",
+    );
+
+    expect(target).toEqual({ source: "ambient" });
+    expect(execMock).not.toHaveBeenCalled();
+    warnSpy.mockRestore();
+  });
+});

package/src/kubectl-context.ts

@@ -0,0 +1,207 @@
+/**
+ * K8s environment→cluster binding — chant #1100.
+ *
+ * Every cloud lexicon binds an environment to a scope: AWS resolves `<env>`
+ * to a CloudFormation stack, Azure treats `<env>` as the resource group,
+ * Temporal looks up `temporal.profiles.<env>` in `chant.config.ts`. K8s (and
+ * GCP-via-Config-Connector, which observes through the same kubectl path)
+ * bound nothing — `describeResources` shelled out to `kubectl get` with no
+ * `--context`, so it read whatever cluster `kubectl config current-context`
+ * happened to point at. Point `prod` at a dev cluster and every declared
+ * resource reads as missing — a wrong-cluster diff that looks like a
+ * confident list of deletions.
+ *
+ * This module is the shared resolver both the k8s and gcp lexicons'
+ * `describeResources` call, so they resolve a cluster identity the same way
+ * (see `lexicons/k8s/src/config.ts`'s `K8sChantConfig` for the declared
+ * shape). It is intentionally provider-agnostic and lives in core (like
+ * `./ownership.ts`) rather than in the k8s lexicon package, since gcp's
+ * Config Connector observation needs it too without taking a dependency on
+ * the k8s lexicon.
+ */
+
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import type { UnobservedReason } from "./observation";
+
+const execAsync = promisify(exec);
+
+/** A single environment's cluster binding — see `K8sChantConfig` in the k8s lexicon. */
+export interface K8sClusterProfile {
+  /** kubectl context name this environment is bound to. */
+  context: string;
+}
+
+/** Shape of the `k8s` passthrough key in `chant.config.ts` that this resolver reads. */
+export interface K8sConfigShape {
+  profiles?: Record<string, K8sClusterProfile>;
+}
+
+/**
+ * Thrown when an environment declares a cluster binding but the ambient
+ * kubectl context disagrees with it. Refusing here — instead of silently
+ * observing whichever cluster is ambient — is the fix for #1100: a
+ * wrong-cluster read reports every declared resource as missing, which #1089
+ * then classifies as a confident (and wrong) list of `create` actions.
+ */
+export class ClusterBindingMismatchError extends Error {
+  constructor(
+    public readonly environment: string,
+    public readonly expectedContext: string,
+    public readonly ambientContext: string,
+  ) {
+    super(
+      `k8s: environment "${environment}" is bound to cluster context "${expectedContext}" ` +
+        `(k8s.profiles.${environment}.context), but the ambient kubectl context is ` +
+        `"${ambientContext}". Refusing to observe — reading the wrong cluster would misreport ` +
+        `every declared resource as missing. Run \`kubectl config use-context ${expectedContext}\` ` +
+        `to switch, or update the binding in chant.config.ts if "${ambientContext}" is actually correct.`,
+    );
+    this.name = "ClusterBindingMismatchError";
+  }
+}
+
+export interface ResolvedClusterTarget {
+  /**
+   * Explicit `--context` value to pass to every kubectl invocation. Present
+   * only when the environment has a declared binding — undefined means
+   * "no binding, keep today's ambient-context behavior".
+   */
+  context?: string;
+  /** Where the target came from. */
+  source: "bound" | "ambient";
+}
+
+/** Reads `kubectl config current-context`. Returns undefined if unset or kubectl fails. */
+async function currentAmbientContext(): Promise<string | undefined> {
+  try {
+    const { stdout } = await execAsync("kubectl config current-context");
+    const trimmed = stdout.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve the kubectl context an environment should be observed/applied
+ * against, reading `k8s.profiles.<environment>.context` from `chant.config.ts`
+ * (the `config` passed in is the passthrough `ChantConfig`, cast loosely since
+ * the `k8s` key isn't declared on the core schema — same pattern as
+ * `temporal.profiles`).
+ *
+ * - No binding declared: returns `{ source: "ambient" }` — unchanged
+ *   behavior — but logs a visible warning identifying the caller and
+ *   environment, so the fallback is never silent (#1100 acceptance).
+ * - Binding declared and the ambient context agrees (or ambient can't be
+ *   determined): returns `{ context: bound, source: "bound" }`. Callers
+ *   should pass this context explicitly on every kubectl invocation rather
+ *   than relying on it also being ambient.
+ * - Binding declared and the ambient context disagrees: throws
+ *   {@link ClusterBindingMismatchError} — a loud refusal instead of quietly
+ *   reading the wrong cluster.
+ */
+export async function resolveClusterTarget(
+  config: Record<string, unknown>,
+  environment: string,
+  lexiconName: string,
+): Promise<ResolvedClusterTarget> {
+  const k8sConfig = config.k8s as K8sConfigShape | undefined;
+  const bound = k8sConfig?.profiles?.[environment]?.context;
+
+  if (!bound) {
+    console.warn(
+      `[${lexiconName}] no cluster binding for environment "${environment}" ` +
+        `(k8s.profiles.${environment}.context in chant.config.ts) — observing whatever kubectl ` +
+        `context is ambient. Add a binding to pin this environment to a specific cluster (chant #1100).`,
+    );
+    return { source: "ambient" };
+  }
+
+  const ambient = await currentAmbientContext();
+  if (ambient && ambient !== bound) {
+    throw new ClusterBindingMismatchError(environment, bound, ambient);
+  }
+
+  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 });
+  });
+});

package/src/lifecycle/change-set.ts

@@ -13,11 +13,12 @@
  * load-bearing.
  */
 import { diffLive, type AttributeChange, type DiffLiveInput } from "./live-diff";
+import { unobservedReasonText, type UnobservedReason } from "../observation";
 
 /**
  * What the projection proposes for a single resource.
  *
- * - `create` — declared in source, absent from live.
+ * - `create` — declared in source, and the provider **confirmed** it absent.
  * - `update` — declared and live, but live config drifted.
  * - `delete` — a chant-owned resource that is live but no longer declared.
  *   Only emitted once ownership is known (#121); never inferred from the
@@ -25,8 +26,11 @@ import { diffLive, type AttributeChange, type DiffLiveInput } from "./live-diff"
  * - `adopt` — live but undeclared, ownership not established → a candidate to
  *   pull back into source, never an auto-delete.
  * - `noop` — declared and live with no drift, or already reconciled.
+ * - `unobserved` — declared, and the lexicon could not look (#1089). Not a
+ *   proposal at all: it is the plan admitting a hole. Never a create, never a
+ *   delete. Read `unobservedReason` for which hole.
  */
-export type ChangeAction = "create" | "update" | "delete" | "adopt" | "noop";
+export type ChangeAction = "create" | "update" | "delete" | "adopt" | "noop" | "unobserved";
 
 /**
  * Who answers "is this resource chant's?". `unknown` until a live ownership
@@ -47,13 +51,24 @@ export interface ChangeSetEntry {
     declared: boolean;
     /** Present in the last snapshot. */
     inSnapshot: boolean;
-    /** Observed in the live system right now. */
+    /** Observed present in the live system right now. */
     live: boolean;
+    /**
+     * The lexicon actually looked at this entity (#1089). `false` with
+     * `live: false` means "unknown", not "absent" — the distinction the whole
+     * change set now rests on. Absent-and-looked-at is `observed: true,
+     * live: false`.
+     */
+    observed: boolean;
   };
   /** Attribute-level changes, for `update`. */
   deltas?: AttributeChange[];
   /** Live-marker ownership. Defaults to `unknown`. */
   ownership: Ownership;
+  /** Why the entity could not be observed, for `action: "unobserved"` (#1089). */
+  unobservedReason?: UnobservedReason;
+  /** Human-readable backing for `unobservedReason` (the failing command, the missing binding). */
+  unobservedDetail?: string;
 }
 
 export interface ChangeSet {
@@ -67,11 +82,16 @@ export interface ChangeSet {
  * `create`/`update` are precise from declared-vs-live. `delete` is never
  * emitted here — an undeclared live resource classifies as `adopt` until
  * ownership is known.
+ *
+ * A declared entity the lexicon could not observe (`input.unobserved`, #1089)
+ * classifies as `unobserved` and nothing else: no `create` is ever synthesized
+ * from a read that did not happen.
  */
 export function buildChangeSet(env: string, input: DiffLiveInput): ChangeSet {
   const diff = diffLive(input);
   const { declared, observedNow } = input;
   const observedThen = input.observedThen ?? {};
+  const unobservedInput = input.unobserved ?? {};
 
   const driftByName = new Map(
     diff.driftedSinceSnapshot.map((d) => [d.name, d.changes] as const),
@@ -81,6 +101,7 @@ export function buildChangeSet(env: string, input: DiffLiveInput): ChangeSet {
     ...declared,
     ...Object.keys(observedNow),
     ...Object.keys(observedThen),
+    ...Object.keys(unobservedInput),
   ]);
 
   const entries: ChangeSetEntry[] = [];
@@ -88,8 +109,11 @@ export function buildChangeSet(env: string, input: DiffLiveInput): ChangeSet {
     const isDeclared = declared.has(name);
     const live = Object.prototype.hasOwnProperty.call(observedNow, name);
     const inSnapshot = Object.prototype.hasOwnProperty.call(observedThen, name);
-    const type = observedNow[name]?.type ?? observedThen[name]?.type;
-    const evidence = { declared: isDeclared, inSnapshot, live };
+    // A returned resource was observed by definition; `unobserved` only counts
+    // for entities the lexicon did not return.
+    const unobservedEntry = live ? undefined : unobservedInput[name];
+    const type = observedNow[name]?.type ?? observedThen[name]?.type ?? unobservedEntry?.type;
+    const evidence = { declared: isDeclared, inSnapshot, live, observed: !unobservedEntry };
 
     // Ownership comes from the LIVE marker only (carried on observedNow), never
     // from the snapshot. This is the invariant that keeps the snapshot from
@@ -100,8 +124,13 @@ export function buildChangeSet(env: string, input: DiffLiveInput): ChangeSet {
     let action: ChangeAction;
     let deltas: AttributeChange[] | undefined;
 
-    if (isDeclared && !live) {
-      // Declared in source, not in the cloud → create.
+    if (unobservedEntry) {
+      // The lexicon never looked. Absence is not established, so neither a
+      // create (declared) nor a delete/adopt (undeclared) can be proposed —
+      // the entry exists to say the plan has a hole here.
+      action = "unobserved";
+    } else if (isDeclared && !live) {
+      // Declared in source, and the provider confirmed it absent → create.
       action = "create";
     } else if (isDeclared && live) {
       const drift = driftByName.get(name);
@@ -120,14 +149,27 @@ export function buildChangeSet(env: string, input: DiffLiveInput): ChangeSet {
       action = "noop";
     }
 
-    entries.push({ name, type, action, evidence, deltas, ownership });
+    entries.push({
+      name,
+      type,
+      action,
+      evidence,
+      deltas,
+      ownership,
+      ...(unobservedEntry
+        ? {
+            unobservedReason: unobservedEntry.reason,
+            ...(unobservedEntry.detail ? { unobservedDetail: unobservedEntry.detail } : {}),
+          }
+        : {}),
+    });
   }
 
   entries.sort((a, b) => a.name.localeCompare(b.name));
   return { env, entries };
 }
 
-const ACTION_ORDER: ChangeAction[] = ["create", "update", "delete", "adopt", "noop"];
+const ACTION_ORDER: ChangeAction[] = ["create", "update", "delete", "adopt", "noop", "unobserved"];
 
 /** Count entries per action. */
 export function summarize(cs: ChangeSet): Record<ChangeAction, number> {
@@ -137,6 +179,7 @@ export function summarize(cs: ChangeSet): Record<ChangeAction, number> {
     delete: 0,
     adopt: 0,
     noop: 0,
+    unobserved: 0,
   };
   for (const e of cs.entries) counts[e.action]++;
   return counts;
@@ -148,8 +191,10 @@ export function summarize(cs: ChangeSet): Record<ChangeAction, number> {
  * GitLab renders an `artifacts:reports:terraform` artifact in the merge-request
  * UI as "N to add, M to change, K to delete". The format is generic — any tool
  * that emits this JSON gets the widget — and the chant plan maps onto it
- * directly. Only the mutating actions count: `adopt` and `noop` are excluded,
- * since the widget has no column for "live but undeclared" or "no change".
+ * directly. Only the mutating actions count: `adopt`, `noop` and `unobserved`
+ * are excluded, since the widget has no column for "live but undeclared", "no
+ * change", or "could not look" (#1089). The widget is therefore a floor, not a
+ * complete plan: read the full change set when entities are unobserved.
  *
  * The widget label reads "Terraform" regardless of producer; that is GitLab's
  * fixed string, not a claim chant makes.
@@ -175,10 +220,17 @@ export function renderChangeSet(cs: ChangeSet): string {
   for (const action of ACTION_ORDER) {
     const group = cs.entries.filter((e) => e.action === action);
     if (group.length === 0) continue;
-    lines.push(`\n${action.toUpperCase()}:`);
+    lines.push(
+      action === "unobserved"
+        ? "\nUNOBSERVED (declared; chant could not read live state — no action proposed):"
+        : `\n${action.toUpperCase()}:`,
+    );
     for (const e of group) {
       const own = e.ownership === "unknown" ? "" : ` [${e.ownership}]`;
-      lines.push(`  ${e.name}${e.type ? ` (${e.type})` : ""}${own}`);
+      const why = e.unobservedReason
+        ? ` — ${unobservedReasonText(e.unobservedReason)}${e.unobservedDetail ? `: ${e.unobservedDetail}` : ""}`
+        : "";
+      lines.push(`  ${e.name}${e.type ? ` (${e.type})` : ""}${own}${why}`);
       for (const d of e.deltas ?? []) {
         lines.push(`      ${d.path}: ${fmt(d.oldValue)} → ${fmt(d.newValue)}`);
       }