@intentius/chant 0.27.0 → 0.29.0

package/src/lint/post-synth.ts

@@ -35,6 +35,19 @@ export function getPrimaryOutput(output: string | SerializerResult): string {
 
 /**
  * A diagnostic from a post-synthesis check.
+ *
+ * chant #1138 — deliberately carries no `file`/`line` the way `LintDiagnostic`
+ * (`./rule.ts`) does. A post-synth check runs over `ctx.outputs` — the
+ * SYNTHESIZED output text (a CloudFormation template, a Kubernetes manifest) —
+ * not a `ts.SourceFile`, so there is no AST position to report in the first
+ * place. `entity` (below) is the closest thing to a locator and is NOT a
+ * substitute: it names a resource in that synthesized output (a CFN logical
+ * id, a k8s `metadata.name`), which several checks in this repo never even
+ * set (a cross-cutting check with no single implicated resource), and which
+ * is not guaranteed to match a `ctx.entities` map key. This is why source-
+ * comment (`chant-disable`) suppression is out of scope for post-synth
+ * findings — see `./config.ts`'s `applyConfiguredSeverity` doc for the full
+ * reasoning and what suppression surface post-synth findings get instead.
  */
 export interface PostSynthDiagnostic {
   /** ID of the check that produced this diagnostic */
@@ -43,7 +56,11 @@ export interface PostSynthDiagnostic {
   severity: Severity;
   /** Human-readable message */
   message: string;
-  /** Optional entity name related to this diagnostic */
+  /**
+   * Optional resource name related to this diagnostic — a name from the
+   * SYNTHESIZED OUTPUT (a CFN logical id, a k8s `metadata.name`), not a
+   * source file/line. See this interface's doc comment.
+   */
   entity?: string;
   /** Optional lexicon related to this diagnostic */
   lexicon?: string;
@@ -96,3 +113,15 @@ export function runPostSynthChecks(
   }
   return diagnostics;
 }
+
+// chant #1138 — `applyConfiguredSeverity` (the `lint.rules` severity-override
+// pass over a set of `PostSynthDiagnostic`s) lives in `./config.ts`, not here,
+// even though it operates on this module's own type. This file is a leaf:
+// every lexicon's post-synth checks import it as a real runtime module (not
+// just for types — `getPrimaryOutput` above is a plain function several
+// checks call directly), so it has to stay cheap to load. `./config.ts` is
+// not cheap — it resolves built-in preset paths via the runtime adapter at
+// module scope — and pulling that into every lexicon's check barrel merely to
+// share one filter function is the wrong trade. `applyConfiguredSeverity`
+// only needs this module's TYPE (`PostSynthDiagnostic`), which costs nothing
+// at runtime, so the dependency runs the other way instead.

package/src/live-endpoint.test.ts

@@ -0,0 +1,115 @@
+import { describe, test, expect } from "vitest";
+import { applyLiveEndpoint, zeroResourcesWarning, LEXICON_ENDPOINT_ENV_VAR } from "./live-endpoint";
+import type { EnvironmentDeclaration } from "./config";
+
+describe("applyLiveEndpoint (#1166)", () => {
+  test("no-op — and no notice — when the environment declares no endpoint at all", () => {
+    const env: NodeJS.ProcessEnv = {};
+    const result = applyLiveEndpoint(["floci", "prod"], "floci", ["aws"], env);
+    expect(result.notice).toBeUndefined();
+    expect(env.AWS_ENDPOINT_URL).toBeUndefined();
+    result.restore(); // always safe, even as a no-op
+    expect(env.AWS_ENDPOINT_URL).toBeUndefined();
+  });
+
+  test("applies the declared endpoint to the ambient var of every observing lexicon that has one", () => {
+    const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
+    const env: NodeJS.ProcessEnv = {};
+    const result = applyLiveEndpoint(environments, "floci", ["aws"], env);
+    expect(env.AWS_ENDPOINT_URL).toBe("http://localhost:4566");
+    expect(result.notice).toMatch(/environment "floci" declares endpoint http:\/\/localhost:4566/);
+    expect(result.notice).toMatch(/AWS_ENDPOINT_URL/);
+  });
+
+  test("restore() removes exactly what it set, not a pre-existing value it didn't touch", () => {
+    const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
+    const env: NodeJS.ProcessEnv = {};
+    const result = applyLiveEndpoint(environments, "floci", ["aws"], env);
+    expect(env.AWS_ENDPOINT_URL).toBe("http://localhost:4566");
+    result.restore();
+    expect(env.AWS_ENDPOINT_URL).toBeUndefined();
+  });
+
+  test("ambient wins: an already-set var is left untouched, and the notice says so", () => {
+    const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
+    const env: NodeJS.ProcessEnv = { AWS_ENDPOINT_URL: "http://real-endpoint.example" };
+    const result = applyLiveEndpoint(environments, "floci", ["aws"], env);
+    expect(env.AWS_ENDPOINT_URL).toBe("http://real-endpoint.example"); // unchanged
+    expect(result.notice).toMatch(/ambient AWS_ENDPOINT_URL already set/);
+    result.restore();
+    expect(env.AWS_ENDPOINT_URL).toBe("http://real-endpoint.example"); // restore never touches what it didn't set
+  });
+
+  test("a bare-string environment entry has no endpoint to apply", () => {
+    const env: NodeJS.ProcessEnv = {};
+    const result = applyLiveEndpoint(["floci"], "floci", ["aws"], env);
+    expect(result.notice).toBeUndefined();
+    expect(env.AWS_ENDPOINT_URL).toBeUndefined();
+  });
+
+  test("only applies to lexicons actually observing, and only those with a known endpoint var", () => {
+    const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
+    const env: NodeJS.ProcessEnv = {};
+    // k8s has no ambient-var knob (config-resolved instead) — nothing to set.
+    const result = applyLiveEndpoint(environments, "floci", ["k8s"], env);
+    expect(env.AWS_ENDPOINT_URL).toBeUndefined();
+    expect(result.notice).toBeUndefined();
+  });
+
+  test("applies to fly's FLY_FLAPS_BASE_URL too, when fly is among the observing lexicons", () => {
+    const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
+    const env: NodeJS.ProcessEnv = {};
+    const result = applyLiveEndpoint(environments, "floci", ["aws", "fly"], env);
+    expect(env.AWS_ENDPOINT_URL).toBe("http://localhost:4566");
+    expect(env.FLY_FLAPS_BASE_URL).toBe("http://localhost:4566");
+    result.restore();
+    expect(env.AWS_ENDPOINT_URL).toBeUndefined();
+    expect(env.FLY_FLAPS_BASE_URL).toBeUndefined();
+  });
+
+  test("mixed: one lexicon's var is applied, another's ambient value wins — both show up in the notice", () => {
+    const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
+    const env: NodeJS.ProcessEnv = { FLY_FLAPS_BASE_URL: "http://real-fly.example" };
+    const result = applyLiveEndpoint(environments, "floci", ["aws", "fly"], env);
+    expect(env.AWS_ENDPOINT_URL).toBe("http://localhost:4566"); // applied
+    expect(env.FLY_FLAPS_BASE_URL).toBe("http://real-fly.example"); // ambient wins
+    expect(result.notice).toMatch(/applied to AWS_ENDPOINT_URL/);
+    expect(result.notice).toMatch(/ambient FLY_FLAPS_BASE_URL already set/);
+  });
+
+  test("audited endpoint-knob registry: only aws and fly (gcp/k8s/azure/temporal resolve via config, not an ambient var)", () => {
+    expect(LEXICON_ENDPOINT_ENV_VAR).toEqual({ aws: "AWS_ENDPOINT_URL", fly: "FLY_FLAPS_BASE_URL" });
+  });
+
+  test("a name that isn't declared at all has no endpoint to apply", () => {
+    const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
+    const env: NodeJS.ProcessEnv = {};
+    const result = applyLiveEndpoint(environments, "prod", ["aws"], env);
+    expect(result.notice).toBeUndefined();
+    expect(env.AWS_ENDPOINT_URL).toBeUndefined();
+  });
+});
+
+describe("zeroResourcesWarning (#1166)", () => {
+  test("undefined when nothing was declared to look for", () => {
+    expect(zeroResourcesWarning("aws", "floci", 0, { resources: {}, unobserved: {} })).toBeUndefined();
+  });
+
+  test("undefined when resources were actually observed", () => {
+    expect(
+      zeroResourcesWarning("aws", "floci", 2, { resources: { a: {} }, unobserved: {} }),
+    ).toBeUndefined();
+  });
+
+  test("undefined when the emptiness is already explained by #1089 unobserved", () => {
+    expect(
+      zeroResourcesWarning("aws", "floci", 2, { resources: {}, unobserved: { a: { reason: "no-binding" } } }),
+    ).toBeUndefined();
+  });
+
+  test("warns with declared count and the check-endpoint hint when truly empty and unexplained", () => {
+    expect(zeroResourcesWarning("aws", "floci", 3, { resources: {}, unobserved: {} })).toBe(
+      'aws: 0 live resources for env "floci" (3 declared) — check the endpoint/credentials',
+    );
+  });
+});

package/src/live-endpoint.ts

@@ -0,0 +1,148 @@
+/**
+ * chant #1166 — let a declared `environment` carry its own endpoint so
+ * `--live --env <name>` is self-sufficient.
+ *
+ * The bug this closes: `chant graph --live --env floci` (and `lifecycle
+ * diff`/`plan`) observe a stack by shelling out through each lexicon's
+ * `describeResources()`. For AWS that shell-out honors the ambient
+ * `AWS_ENDPOINT_URL` env var — when a project's `floci` environment is a local
+ * emulator (`http://localhost:4566`) but the invoking shell never exported
+ * that var, the AWS CLI silently targets real AWS instead. The stack named
+ * after the environment doesn't exist there, so `describeResources` hits its
+ * `stackDoesNotExist` branch and returns an empty, unremarkable "nothing is
+ * deployed" — indistinguishable from the truthful answer. This cost real
+ * debugging time validating #1162's live overlay: the observation code was
+ * right, the manual repro just never set the var.
+ *
+ * The fix: `environments` in `chant.config.ts` can name an endpoint per
+ * environment (`config.ts`'s `EnvironmentDeclaration`), and {@link
+ * applyLiveEndpoint} injects it into the ambient env var each observing
+ * lexicon's CLI shell-out actually reads — but only for a var that isn't
+ * already set. Ambient always wins: a shell that already exports
+ * `AWS_ENDPOINT_URL` sees no change in behavior.
+ *
+ * Audited (#1166) which lexicons have an ambient-env-var endpoint knob at
+ * all, since that's the specific footgun — a lexicon whose environment
+ * binding is resolved from `chant.config` itself (not an ambient var) has
+ * nothing to inject here:
+ *
+ *   - **aws**  — `AWS_ENDPOINT_URL`, read directly by
+ *     `lexicons/aws/src/components/cloud-executor.ts` / `plugin.ts` before
+ *     every `aws …` shell-out (`applyAwsEndpoint`/`applyAwsEndpointArgv`).
+ *   - **fly**  — `FLY_FLAPS_BASE_URL`, read by `resolveEndpoint()` in
+ *     `lexicons/fly/src/op/activities/fly-apply.ts`, the same seam
+ *     `describeResources` (`../describe-resources.ts`) calls through.
+ *   - **gcp**, **k8s** — resolve their live target from `chant.config` itself
+ *     (`k8s.profiles.<env>.context` via `resolveClusterTarget`,
+ *     `packages/core/src/kubectl-context.ts`), not an ambient var. Nothing to
+ *     inject: the config *is* the binding already.
+ *   - **azure** — resolves via the `az` CLI's own logged-in
+ *     subscription/session context; no ambient endpoint var exists to miss.
+ *   - **temporal** — resolves its connection from `temporal.profiles.<env>`
+ *     (`resolveProfile`, `lexicons/temporal/src/describe-resources.ts`), the
+ *     same "config is the binding" shape as k8s/gcp.
+ */
+
+import { environmentEndpoint, type EnvironmentDeclaration } from "./config";
+
+/**
+ * Per-lexicon ambient env var a `--live` read honors for its endpoint. Only
+ * lexicons with a genuine ambient-var footgun are listed — see the module doc
+ * for the full audit (gcp/k8s/azure/temporal resolve their target from
+ * `chant.config` instead, so they have nothing to inject).
+ */
+export const LEXICON_ENDPOINT_ENV_VAR: Record<string, string> = {
+  aws: "AWS_ENDPOINT_URL",
+  fly: "FLY_FLAPS_BASE_URL",
+};
+
+/** Result of {@link applyLiveEndpoint} — always call `restore()`, even when nothing was applied (it is then a no-op). */
+export interface AppliedEndpoint {
+  /**
+   * One line describing what happened, or `undefined` when the environment
+   * declares no endpoint at all (nothing to say). Present whether the
+   * declared endpoint was applied OR an ambient var already won — #1166's
+   * "no silent anything" stance: an operator should never have to guess which
+   * target a `--live` read actually used.
+   */
+  notice?: string;
+  /** Undo whatever ambient env vars this call set. Always safe to call. */
+  restore: () => void;
+}
+
+/**
+ * Resolve `environment`'s declared endpoint (if any) from `config.environments`
+ * and apply it to the ambient env var of every lexicon in `lexicons` that has
+ * one ({@link LEXICON_ENDPOINT_ENV_VAR}) — but only when that var isn't
+ * already set. Ambient always wins (#1166): behavior for a shell that already
+ * exports `AWS_ENDPOINT_URL` is unchanged.
+ *
+ * Call before a `--live` describe/enrich pass; `restore()` in a `finally` so
+ * the injected value never leaks into a later invocation in the same process
+ * (tests, or a long-lived host like the MCP server).
+ */
+export function applyLiveEndpoint(
+  environments: EnvironmentDeclaration[] | undefined,
+  environment: string,
+  lexicons: readonly string[],
+  env: NodeJS.ProcessEnv = process.env,
+): AppliedEndpoint {
+  const endpoint = environmentEndpoint(environments, environment);
+  if (!endpoint) return { restore: () => {} };
+
+  const applied: string[] = [];
+  const overridden: string[] = [];
+  const seen = new Set<string>(); // a var shared by two lexicons is only reported once
+  for (const lexicon of lexicons) {
+    const varName = LEXICON_ENDPOINT_ENV_VAR[lexicon];
+    if (!varName || seen.has(varName)) continue;
+    seen.add(varName);
+    if (env[varName]) {
+      overridden.push(varName);
+      continue;
+    }
+    env[varName] = endpoint;
+    applied.push(varName);
+  }
+
+  const notices: string[] = [];
+  if (applied.length > 0) {
+    notices.push(
+      `environment "${environment}" declares endpoint ${endpoint} — applied to ${applied.join(", ")} for this read`,
+    );
+  }
+  if (overridden.length > 0) {
+    notices.push(
+      `ambient ${overridden.join(", ")} already set — keeping it over environment "${environment}"'s declared endpoint (${endpoint})`,
+    );
+  }
+
+  return {
+    notice: notices.length > 0 ? notices.join("; ") : undefined,
+    restore: () => {
+      for (const varName of applied) delete env[varName];
+    },
+  };
+}
+
+/**
+ * #1166 acceptance: when a `--live` describe comes back with zero resources
+ * for a lexicon that had declared entities to look for, and nothing was
+ * already reported NOT-OBSERVED (#1089) either, that is either "genuinely
+ * nothing is deployed yet" or a misconfigured endpoint/credentials — the two
+ * are visually identical, so a caller must say so rather than stay quiet.
+ * Returns `undefined` when there is nothing to declare (no declared entities
+ * to have asked about, or the emptiness is already explained by #1089's
+ * `unobserved`).
+ */
+export function zeroResourcesWarning(
+  lexicon: string,
+  environment: string,
+  declaredCount: number,
+  observed: { resources: Record<string, unknown>; unobserved: Record<string, unknown> },
+): string | undefined {
+  if (declaredCount === 0) return undefined;
+  if (Object.keys(observed.resources).length > 0) return undefined;
+  if (Object.keys(observed.unobserved).length > 0) return undefined;
+  return `${lexicon}: 0 live resources for env "${environment}" (${declaredCount} declared) — check the endpoint/credentials`;
+}

package/src/observation.test.ts

@@ -0,0 +1,96 @@
+/**
+ * The observation contract itself (#1089) — the normalizer, the envelope
+ * discriminant, and the multi-stack merge.
+ */
+import { describe, test, expect } from "vitest";
+import {
+  UNOBSERVED_REASONS,
+  formatUnobserved,
+  isObservationResult,
+  isUnobservedReason,
+  mergeObservations,
+  normalizeObservation,
+  observation,
+  unobservedAll,
+  unobservedReasonText,
+} from "./observation";
+import type { ResourceMetadata } from "./lexicon";
+
+const meta = (over: Partial<ResourceMetadata> = {}): ResourceMetadata => ({
+  type: "Fake::Resource",
+  status: "OK",
+  ...over,
+});
+
+describe("normalizeObservation", () => {
+  test("a bare map means 'I looked at everything'", () => {
+    expect(normalizeObservation({ a: meta() })).toEqual({ resources: { a: meta() }, unobserved: {} });
+  });
+
+  test("the envelope carries both halves", () => {
+    const value = observation({ a: meta() }, { b: { reason: "read-failed" } });
+    expect(normalizeObservation(value)).toEqual({
+      resources: { a: meta() },
+      unobserved: { b: { reason: "read-failed" } },
+    });
+  });
+
+  test("undefined normalizes to two empty maps", () => {
+    expect(normalizeObservation(undefined)).toEqual({ resources: {}, unobserved: {} });
+  });
+
+  test("an entity literally named `observation` cannot be mistaken for the envelope", () => {
+    const bare = { observation: meta({ type: "Odd::Name" }) };
+    expect(isObservationResult(bare)).toBe(false);
+    expect(normalizeObservation(bare).resources.observation.type).toBe("Odd::Name");
+  });
+
+  test("the envelope omits an empty unobserved map", () => {
+    expect(observation({ a: meta() }, {})).toEqual({ observation: "v1", resources: { a: meta() } });
+  });
+});
+
+describe("unobservedAll", () => {
+  test("marks every named entity with one reason, carrying declared types", () => {
+    const entities = new Map([["a", { entityType: "AWS::S3::Bucket" }]]);
+    expect(unobservedAll(["a", "b"], "no-credentials", "token expired", entities)).toEqual({
+      a: { reason: "no-credentials", type: "AWS::S3::Bucket", detail: "token expired" },
+      b: { reason: "no-credentials", detail: "token expired" },
+    });
+  });
+});
+
+describe("mergeObservations (multi-stack)", () => {
+  test("present beats not-observed beats absent", () => {
+    const merged = mergeObservations([
+      { resources: {}, unobserved: { a: { reason: "read-failed" }, b: { reason: "no-binding" } } },
+      { resources: { a: meta() }, unobserved: {} },
+    ]);
+    expect(Object.keys(merged.resources)).toEqual(["a"]);
+    expect(Object.keys(merged.unobserved)).toEqual(["b"]);
+  });
+
+  test("an entity nobody looked for in any stack stays absent", () => {
+    const merged = mergeObservations([
+      { resources: { a: meta() }, unobserved: {} },
+      { resources: { b: meta() }, unobserved: {} },
+    ]);
+    expect(merged.unobserved).toEqual({});
+  });
+});
+
+describe("reason totality", () => {
+  test("every reason has human text and passes the guard", () => {
+    for (const reason of UNOBSERVED_REASONS) {
+      expect(isUnobservedReason(reason)).toBe(true);
+      expect(unobservedReasonText(reason).length).toBeGreaterThan(0);
+    }
+    expect(isUnobservedReason("made-up")).toBe(false);
+  });
+
+  test("formatUnobserved names the entity, the type and the detail", () => {
+    expect(
+      formatUnobserved("widget", { type: "K8s::X::Widget", reason: "unsupported-kind", detail: "no mapping" }),
+    ).toBe("widget (K8s::X::Widget) — no reader for this resource kind: no mapping");
+  });
+});

package/src/observation.ts

@@ -0,0 +1,213 @@
+/**
+ * The observation contract (#1089) — what a lexicon's `describeResources()`
+ * is allowed to mean.
+ *
+ * Before this module there were two ways for an observation to return nothing
+ * for a declared entity and no way to tell them apart:
+ *
+ *   1. The provider was asked and said the resource does not exist.
+ *   2. The lexicon never looked — no reader for that kind, the read errored,
+ *      no credentials, no cluster/subscription binding.
+ *
+ * Both arrived at the change set as "absent", and absent + declared classifies
+ * as `create`. So `chant lifecycle plan` proposed creating a Kubernetes CRD
+ * that already existed in the cluster, with nothing in the plan to say the tool
+ * had simply not looked (a warn on stderr is not a signal in a change set).
+ *
+ * The contract is a tri-state, per declared entity:
+ *
+ *   - **OBSERVED-PRESENT** — a key in `resources`. The provider returned it.
+ *   - **OBSERVED-ABSENT** — in neither map. The lexicon looked and the provider
+ *     reported it missing. This is the only shape that may become a `create`.
+ *   - **NOT-OBSERVED** — a key in `unobserved`, carrying a total
+ *     {@link UnobservedReason}. Never a `create`, never a `delete`; consumers
+ *     surface it and stop.
+ *
+ * Compatibility: `describeResources()` may still return the bare
+ * `name → ResourceMetadata` map it always did — that means "everything I was
+ * asked about, I looked at" and normalizes to an empty `unobserved`. Reporting
+ * NOT-OBSERVED requires the explicitly versioned {@link ObservationResult}
+ * envelope, which is discriminated by its literal `observation: "v1"` field (a
+ * bare map's value at any key is a `ResourceMetadata` object, never that
+ * string, so the two shapes can never be confused).
+ */
+
+import type { ResourceMetadata } from "./lexicon";
+
+/**
+ * Why a declared entity was not observed. Total: a lexicon that cannot observe
+ * an entity must pick one of these, and consumers may switch exhaustively.
+ *
+ * - `read-failed` — the provider was reached and the read errored (a non-zero
+ *   CLI exit, a 5xx, an unparseable response).
+ * - `no-credentials` — no usable credentials/authorization for the target.
+ * - `no-binding` — the environment resolves to no concrete target (no kubectl
+ *   context, no subscription, no stack, no endpoint).
+ * - `unsupported-kind` — the lexicon has no reader for this entity type (the
+ *   K8s CRD case, Azure's nested ARM types). The resource may well exist.
+ * - `filtered` — the entity was reached but withheld by a caller-requested
+ *   filter (`owned: true` against a resource carrying no chant marker). The
+ *   result deliberately says nothing about it, which is still not absence: a
+ *   declared resource that exists but is foreign must not classify as `create`.
+ */
+export type UnobservedReason =
+  | "read-failed"
+  | "no-credentials"
+  | "no-binding"
+  | "unsupported-kind"
+  | "filtered";
+
+/** Every legal {@link UnobservedReason}, for validation and conformance checks. */
+export const UNOBSERVED_REASONS: readonly UnobservedReason[] = [
+  "read-failed",
+  "no-credentials",
+  "no-binding",
+  "unsupported-kind",
+  "filtered",
+];
+
+/** True when `value` is a legal {@link UnobservedReason}. */
+export function isUnobservedReason(value: unknown): value is UnobservedReason {
+  return typeof value === "string" && (UNOBSERVED_REASONS as readonly string[]).includes(value);
+}
+
+/** One declared entity the lexicon could not observe, and why. */
+export interface UnobservedEntity {
+  /** Declared entity type, when the lexicon knows it (it usually does — the entity is declared). */
+  type?: string;
+  /** Total verdict. */
+  reason: UnobservedReason;
+  /** Human-readable detail: the command that failed, the missing binding key, the unsupported kind. */
+  detail?: string;
+}
+
+/**
+ * The observation envelope — a `describeResources()` return value that can say
+ * "I did not look at this one". Explicitly versioned: `observation: "v1"`.
+ */
+export interface ObservationResult {
+  /** Discriminant + wire version. Distinguishes the envelope from the bare `name → ResourceMetadata` map. */
+  readonly observation: "v1";
+  /** OBSERVED-PRESENT, keyed by chant entity name. */
+  resources: Record<string, ResourceMetadata>;
+  /** NOT-OBSERVED, keyed by chant entity name. Omit or leave empty when everything asked about was looked at. */
+  unobserved?: Record<string, UnobservedEntity>;
+}
+
+/**
+ * What `describeResources()` may return: the bare map (pre-#1089, still valid —
+ * "I looked at everything") or the {@link ObservationResult} envelope.
+ */
+export type DescribeResourcesResult = Record<string, ResourceMetadata> | ObservationResult;
+
+/** Normalized form every consumer works with. Both maps always present. */
+export interface NormalizedObservation {
+  resources: Record<string, ResourceMetadata>;
+  unobserved: Record<string, UnobservedEntity>;
+}
+
+/** True when `value` is the versioned {@link ObservationResult} envelope. */
+export function isObservationResult(value: unknown): value is ObservationResult {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { observation?: unknown }).observation === "v1"
+  );
+}
+
+/**
+ * Build an {@link ObservationResult}. Lexicons use this rather than writing the
+ * discriminant by hand.
+ */
+export function observation(
+  resources: Record<string, ResourceMetadata>,
+  unobserved?: Record<string, UnobservedEntity>,
+): ObservationResult {
+  return {
+    observation: "v1",
+    resources,
+    ...(unobserved && Object.keys(unobserved).length > 0 ? { unobserved } : {}),
+  };
+}
+
+/**
+ * Normalize either accepted return shape. `undefined` (a lexicon that returned
+ * nothing at all) normalizes to two empty maps — which reads as "everything was
+ * observed absent", so callers that mean "the read failed" must say so with
+ * {@link unobservedAll} rather than returning nothing.
+ */
+export function normalizeObservation(value: DescribeResourcesResult | undefined): NormalizedObservation {
+  if (!value) return { resources: {}, unobserved: {} };
+  if (isObservationResult(value)) {
+    return { resources: value.resources ?? {}, unobserved: value.unobserved ?? {} };
+  }
+  return { resources: value, unobserved: {} };
+}
+
+/**
+ * Mark every named entity NOT-OBSERVED with one reason — the whole-lexicon
+ * failure case (the provider CLI is missing, the cluster binding refused, the
+ * credentials are gone). Core applies this when `describeResources()` throws,
+ * so a thrown read degrades to an honest "did not look" for each declared
+ * entity instead of an empty map that classifies as N creates.
+ */
+export function unobservedAll(
+  names: Iterable<string>,
+  reason: UnobservedReason,
+  detail?: string,
+  types?: Map<string, { entityType: string }> | Record<string, string>,
+): Record<string, UnobservedEntity> {
+  const typeOf = (name: string): string | undefined => {
+    if (!types) return undefined;
+    if (types instanceof Map) return types.get(name)?.entityType;
+    return types[name];
+  };
+  const out: Record<string, UnobservedEntity> = {};
+  for (const name of names) {
+    const type = typeOf(name);
+    out[name] = { reason, ...(type ? { type } : {}), ...(detail ? { detail } : {}) };
+  }
+  return out;
+}
+
+/**
+ * Union several observations of the same lexicon (the multi-stack read, where
+ * `describeResources` runs once per stack). Precedence is
+ * present > not-observed > absent: a resource found in any stack is present; an
+ * entity nobody could look at stays not-observed; an entity every reader looked
+ * for and did not find is absent.
+ */
+export function mergeObservations(parts: Iterable<NormalizedObservation>): NormalizedObservation {
+  const resources: Record<string, ResourceMetadata> = {};
+  const unobserved: Record<string, UnobservedEntity> = {};
+  for (const part of parts) {
+    Object.assign(resources, part.resources);
+    Object.assign(unobserved, part.unobserved);
+  }
+  // Present wins: a stack that could not be read does not un-observe a resource
+  // another stack returned.
+  for (const name of Object.keys(resources)) delete unobserved[name];
+  return { resources, unobserved };
+}
+
+/** One-line human phrasing of a reason, for CLI output. */
+export function unobservedReasonText(reason: UnobservedReason): string {
+  switch (reason) {
+    case "read-failed":
+      return "read failed";
+    case "no-credentials":
+      return "no credentials";
+    case "no-binding":
+      return "no binding for this environment";
+    case "unsupported-kind":
+      return "no reader for this resource kind";
+    case "filtered":
+      return "withheld by the --owned filter";
+  }
+}
+
+/** `name — reason (detail)`, the shared rendering for CLI and plan output. */
+export function formatUnobserved(name: string, entry: UnobservedEntity): string {
+  const base = `${name}${entry.type ? ` (${entry.type})` : ""} — ${unobservedReasonText(entry.reason)}`;
+  return entry.detail ? `${base}: ${entry.detail}` : base;
+}