@intentius/chant 0.28.0 → 0.30.0

package/src/lifecycle/snapshot.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect, vi, beforeEach } from "vitest";
-import { createMockPlugin, staticDescribeResources, staticListArtifacts } from "@intentius/chant-test-utils";
+import { createMockPlugin, staticDescribeResources, staticObservation, staticListArtifacts } from "@intentius/chant-test-utils";
 import type { BuildResult } from "../build";
 
 const writeSnapshotMock = vi.fn();
@@ -114,6 +114,44 @@ describe("takeSnapshot", () => {
     expect(result.errors.some((e) => e.includes("aws") && e.includes("no valid"))).toBe(true);
   });
 
+  // #1089 — a snapshot is evidence of what was seen. An entity nobody could
+  // read must be recorded as a hole, not omitted (which the next diff would
+  // read back as "was not there").
+  test("records unobserved entities alongside the resources", async () => {
+    const plugin = createMockPlugin({
+      name: "k8s",
+      describeResources: staticObservation(
+        { web: { type: "K8s::Apps::Deployment", status: "READY" } },
+        { widget: { type: "K8s::X::Widget", reason: "unsupported-kind", detail: "no reader" } },
+      ),
+    });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ k8s: ["web", "widget"] }));
+    expect(result.snapshots[0].unobserved).toEqual({
+      widget: { type: "K8s::X::Widget", reason: "unsupported-kind", detail: "no reader" },
+    });
+    expect(result.warnings.some((w) => w.includes("widget") && w.includes("not observed"))).toBe(true);
+  });
+
+  test("an entirely unreadable environment is not snapshotted as empty", async () => {
+    const plugin = createMockPlugin({
+      name: "k8s",
+      describeResources: staticObservation({}, { web: { reason: "no-credentials" } }),
+    });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ k8s: ["web"] }));
+    expect(result.snapshots).toEqual([]);
+    expect(result.errors.some((e) => e.includes("could not be read"))).toBe(true);
+  });
+
+  test("a throwing plugin reports each declared entity as unobserved in the warnings", async () => {
+    const plugin = createMockPlugin({
+      name: "k8s",
+      describeResources: async () => { throw new Error("kubeconfig missing"); },
+    });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ k8s: ["web"] }));
+    expect(result.snapshots).toEqual([]);
+    expect(result.warnings.some((w) => w.includes("web") && w.includes("kubeconfig missing"))).toBe(true);
+  });
+
   test("resources missing required type/status are dropped with warning", async () => {
     const plugin = createMockPlugin({
       name: "aws",

package/src/lifecycle/snapshot.ts

@@ -9,16 +9,12 @@ import type { LifecycleSnapshot } from "./types";
 import { computeBuildDigest } from "./digest";
 import { writeSnapshot, snapshotStorageKey, getHeadCommit, pushLifecycle } from "./git";
 import { sortedJsonReplacer } from "../utils";
-
-/** Patterns in attribute names that suggest sensitive data. */
-const SENSITIVE_PATTERNS = [
-  /password/i,
-  /secret/i,
-  /token/i,
-  /private.?key/i,
-  /credential/i,
-  /connection.?string/i,
-];
+import { formatUnobserved, normalizeObservation, unobservedAll, type UnobservedEntity } from "../observation";
+// One list of secret-bearing property names for both observation depths
+// (#1014): the thin path warns on them here, the deep path masks them before a
+// property tree is ever rendered or committed. Two lists would eventually
+// disagree about what counts as a secret.
+import { isSensitiveKey } from "../deep-observation";
 
 /**
  * Check for potential sensitive data in resource attributes and return warnings.
@@ -30,7 +26,7 @@ function checkSensitiveData(
   for (const [name, meta] of Object.entries(resources)) {
     if (!meta.attributes) continue;
     for (const attrName of Object.keys(meta.attributes)) {
-      if (SENSITIVE_PATTERNS.some((p) => p.test(attrName))) {
+      if (isSensitiveKey(attrName)) {
         warnings.push(
           `Potential sensitive data in ${name}.attributes.${attrName} — ensure it is scrubbed`,
         );
@@ -124,22 +120,32 @@ export async function takeSnapshot(
 
     let resources: Record<string, ResourceMetadata> = {};
     let artifacts: Record<string, ArtifactMetadata> = {};
+    let unobserved: Record<string, UnobservedEntity> = {};
 
     try {
       if (plugin.describeResources) {
-        const raw = await plugin.describeResources({
-          environment,
-          buildOutput,
-          entityNames,
-          entities,
-          stack,
-        });
-        const { valid, dropped, warnings: validationWarnings } = validateResources(raw);
+        const observed = normalizeObservation(
+          await plugin.describeResources({
+            environment,
+            buildOutput,
+            entityNames,
+            entities,
+            stack,
+          }),
+        );
+        const { valid, dropped, warnings: validationWarnings } = validateResources(observed.resources);
         warnings.push(...validationWarnings);
         if (dropped.length > 0) {
           warnings.push(`${plugin.name}: dropped ${dropped.length} invalid resource(s)`);
         }
         resources = valid;
+        // Record the holes (#1089). A snapshot is evidence of what was seen; an
+        // entity nobody could read must not be recorded as "was not there",
+        // because the next diff would then read it back as absent.
+        unobserved = observed.unobserved;
+        for (const [name, entry] of Object.entries(unobserved)) {
+          warnings.push(`${plugin.name}: not observed — ${formatUnobserved(name, entry)}`);
+        }
       }
 
       if (plugin.listArtifacts) {
@@ -153,7 +159,12 @@ export async function takeSnapshot(
       }
 
       if (Object.keys(resources).length === 0 && Object.keys(artifacts).length === 0) {
-        errors.push(`${plugin.name}: no valid resources or artifacts returned`);
+        const unreadable = Object.keys(unobserved).length;
+        errors.push(
+          unreadable > 0
+            ? `${plugin.name}: nothing observed — ${unreadable} declared entity(ies) could not be read (see warnings); not snapshotting an unread environment as empty`
+            : `${plugin.name}: no valid resources or artifacts returned`,
+        );
         continue;
       }
 
@@ -164,15 +175,24 @@ export async function takeSnapshot(
         commit: headCommit,
         timestamp,
         resources,
+        ...(Object.keys(unobserved).length > 0 && { unobserved }),
         ...(Object.keys(artifacts).length > 0 && { artifacts }),
         digest,
       };
 
       snapshots.push(snapshot);
     } catch (err) {
+      // A thrown read is not an empty environment — record nothing and say so
+      // (#1089). Writing a snapshot here would persist "none of this exists".
       errors.push(
         `${plugin.name}: ${err instanceof Error ? err.message : String(err)}`,
       );
+      const message = err instanceof Error ? err.message : String(err);
+      for (const [name, entry] of Object.entries(
+        unobservedAll(entityNames, "read-failed", message, entities),
+      )) {
+        warnings.push(`${plugin.name}: not observed — ${formatUnobserved(name, entry)}`);
+      }
     }
   }
 

package/src/lifecycle/status.test.ts

@@ -32,8 +32,8 @@ describe("status", () => {
       const cs: ChangeSet = {
         env: "prod",
         entries: [
-          { name: "search-service", type: "T", action: "noop", evidence: { declared: true, inSnapshot: true, live: true }, ownership: "owned" },
-          { name: "orphan-thing", type: "T", action: "adopt", evidence: { declared: false, inSnapshot: false, live: true }, ownership: "foreign" },
+          { name: "search-service", type: "T", action: "noop", evidence: { declared: true, inSnapshot: true, live: true, observed: true }, ownership: "owned" },
+          { name: "orphan-thing", type: "T", action: "adopt", evidence: { declared: false, inSnapshot: false, live: true, observed: true }, ownership: "foreign" },
         ],
       };
       const evidence = liveEvidenceFromChangeSet(cs);
@@ -49,7 +49,7 @@ describe("status", () => {
         const cs: ChangeSet = {
           env: "prod",
           entries: [
-            { name: "search-service-v2", type: "T", action: "noop", evidence: { declared: true, inSnapshot: true, live: true }, ownership: "owned" },
+            { name: "search-service-v2", type: "T", action: "noop", evidence: { declared: true, inSnapshot: true, live: true, observed: true }, ownership: "owned" },
           ],
         };
         const mapping: LiveNameMapping = new Map([["search-svc", ["search-service-v2"]]]);
@@ -63,7 +63,7 @@ describe("status", () => {
         const cs: ChangeSet = {
           env: "prod",
           entries: [
-            { name: "search-service", type: "T", action: "noop", evidence: { declared: true, inSnapshot: true, live: true }, ownership: "owned" },
+            { name: "search-service", type: "T", action: "noop", evidence: { declared: true, inSnapshot: true, live: true, observed: true }, ownership: "owned" },
           ],
         };
         const mapping: LiveNameMapping = new Map([["some-other-component", ["renamed-thing"]]]);
@@ -75,8 +75,8 @@ describe("status", () => {
         const cs: ChangeSet = {
           env: "prod",
           entries: [
-            { name: "cluster-node-1", type: "T", action: "noop", evidence: { declared: true, inSnapshot: true, live: true }, ownership: "owned" },
-            { name: "cluster-node-2", type: "T", action: "update", evidence: { declared: true, inSnapshot: true, live: true }, ownership: "owned" },
+            { name: "cluster-node-1", type: "T", action: "noop", evidence: { declared: true, inSnapshot: true, live: true, observed: true }, ownership: "owned" },
+            { name: "cluster-node-2", type: "T", action: "update", evidence: { declared: true, inSnapshot: true, live: true, observed: true }, ownership: "owned" },
           ],
         };
         const mapping: LiveNameMapping = new Map([["neo4j-cluster", ["cluster-node-1", "cluster-node-2"]]]);
@@ -297,7 +297,7 @@ describe("status", () => {
       const cs: ChangeSet = {
         env: "prod",
         entries: [
-          { name: "search-service-v2", type: "T", action: "noop", evidence: { declared: true, inSnapshot: true, live: true }, ownership: "owned" },
+          { name: "search-service-v2", type: "T", action: "noop", evidence: { declared: true, inSnapshot: true, live: true, observed: true }, ownership: "owned" },
         ],
       };
       const mapping: LiveNameMapping = new Map([["search-svc", ["search-service-v2"]]]);
@@ -311,7 +311,7 @@ describe("status", () => {
       const cs: ChangeSet = {
         env: "prod",
         entries: [
-          { name: "search-service", type: "T", action: "noop", evidence: { declared: true, inSnapshot: true, live: true }, ownership: "owned" },
+          { name: "search-service", type: "T", action: "noop", evidence: { declared: true, inSnapshot: true, live: true, observed: true }, ownership: "owned" },
         ],
       };
       const liveEvidence = liveEvidenceFromChangeSet(cs);
@@ -381,5 +381,86 @@ describe("status", () => {
       const merged = mergeLiveEvidence(undefined, supplement);
       expect(merged.get("c")).toEqual({ live: true, ownership: "owned", action: undefined });
     });
+
+    test("a direct stack observation clears an inherited hole; a failing one keeps it (#1089)", () => {
+      const base = new Map<string, LiveComponentEvidence>([
+        ["a", { live: false, unobserved: { reason: "read-failed" } }],
+        ["b", { live: false, unobserved: { reason: "read-failed" } }],
+      ]);
+      const supplement = new Map<string, LiveComponentEvidence>([
+        ["a", { live: true, ownership: "owned" }],
+        ["b", { live: false, unobserved: { reason: "read-failed", detail: "no determinate status" } }],
+      ]);
+      const merged = mergeLiveEvidence(base, supplement);
+      expect(merged.get("a")!.unobserved).toBeUndefined();
+      expect(merged.get("b")!.unobserved?.reason).toBe("read-failed");
+    });
+  });
+
+  // ── The observation tri-state reaches the status join (#1089) ─────────────
+
+  describe("not-observed never becomes 'stale' (#1089)", () => {
+    const record = {
+      version: 1,
+      component: "search-svc",
+      env: "prod",
+      digest: "sha256:abc",
+      gitSha: "g",
+      runId: "r",
+      timestamp: "2026-01-01T00:00:00Z",
+      actor: "ci",
+    } as const;
+
+    test("a recorded component whose live state could not be read reports unknown", () => {
+      const rows = reconcileStatus("prod", [record], {
+        liveEvidence: new Map<string, LiveComponentEvidence>([
+          ["search-svc", { live: false, unobserved: { reason: "no-binding", detail: "no kubectl context" } }],
+        ]),
+      });
+      expect(rows[0].reconciliation).toBe("unknown");
+      expect(rows[0].detail).toContain("could not be observed");
+      expect(rows[0].detail).toContain("no kubectl context");
+      // `live` is omitted entirely — `false` would read as "not deployed".
+      expect(rows[0].live).toBeUndefined();
+      expect(rows[0].unobserved).toEqual({ reason: "no-binding", detail: "no kubectl context" });
+    });
+
+    test("the same component, actually observed absent, still reports stale", () => {
+      const rows = reconcileStatus("prod", [record], {
+        liveEvidence: new Map<string, LiveComponentEvidence>([["search-svc", { live: false }]]),
+      });
+      expect(rows[0].reconciliation).toBe("stale");
+      expect(rows[0].live).toBe(false);
+    });
+
+    test("an unrecorded component that could not be read is unknown, not unrecorded", () => {
+      const rows = reconcileStatus("prod", [], {
+        allComponents: ["search-svc"],
+        liveEvidence: new Map<string, LiveComponentEvidence>([
+          ["search-svc", { live: false, unobserved: { reason: "read-failed" } }],
+        ]),
+      });
+      expect(rows[0].reconciliation).toBe("unknown");
+    });
+
+    test("liveEvidenceFromChangeSet carries the plan's unobserved verdict", () => {
+      const evidence = liveEvidenceFromChangeSet({
+        env: "prod",
+        entries: [
+          {
+            name: "search-svc",
+            action: "unobserved",
+            evidence: { declared: true, inSnapshot: false, live: false, observed: false },
+            ownership: "unknown",
+            unobservedReason: "unsupported-kind",
+            unobservedDetail: "no reader",
+          },
+        ],
+      });
+      expect(evidence.get("search-svc")!.unobserved).toEqual({
+        reason: "unsupported-kind",
+        detail: "no reader",
+      });
+    });
   });
 });

package/src/lifecycle/status.ts

@@ -21,6 +21,9 @@
  *    lower-confidence signal rather than silently treated as "reconciled".
  *  - **reconciled** — a release record exists and live evidence (via
  *    ownership) confirms the component is present and owned by chant.
+ *  - **unknown** — live evidence was requested and could not be read (#1089),
+ *    or was not requested at all. A component chant could not observe is never
+ *    reported `stale`: "the read failed" and "it is gone" are different facts.
  *
  * This is deliberately a light-touch reconciliation: chant's lexicons report
  * resource-level status (`ResourceMetadata`), not "the digest currently
@@ -36,6 +39,7 @@
 import type { ChangeSet, ChangeAction } from "./change-set";
 import { latestPerComponent, type ReleaseRecord } from "./release-ledger";
 import type { BuildLedgerEntry, ComponentBomSummary } from "./build-ledger";
+import { unobservedReasonText, type UnobservedReason } from "../observation";
 
 /** One row of `chant components status [env]` — the per-component join of recorded vs live. */
 export interface ComponentStatusRow {
@@ -63,9 +67,18 @@ export interface ComponentStatusRow {
   /**
    * Machine-readable "observed live", when live evidence was gathered (`--live`).
    * A consumer joining this row onto a graph node should read this rather than
-   * string-matching `detail`. Absent when `--live` was not requested.
+   * string-matching `detail`. Absent when `--live` was not requested — and, since
+   * #1089, also absent when live state could not be read at all: `false` means
+   * "looked, not there", never "did not look". Read {@link unobserved} for that
+   * case; a consumer that treats absent as "unknown" already handles it.
    */
   live?: boolean;
+  /**
+   * Set when `--live` was requested and the observation could not read this
+   * component (#1089). `live` is absent alongside it and `reconciliation` is
+   * `unknown` — the row reports a hole rather than a verdict.
+   */
+  unobserved?: { reason: UnobservedReason; detail?: string };
   /**
    * The owning deploy unit's raw status, when a lexicon reported it (AWS: the
    * component's own CFN stack via `describeStackStatus`). Lets a renderer paint a
@@ -103,6 +116,12 @@ export interface ComponentStatusResult {
 export interface LiveComponentEvidence {
   /** True if this component name was observed live at all (declared+live, or orphan+live). */
   live: boolean;
+  /**
+   * Set when the observation could not read this component (#1089). `live` is
+   * `false` alongside it, but only because the boolean has nowhere else to go —
+   * every consumer must branch on this field before believing `live: false`.
+   */
+  unobserved?: { reason: UnobservedReason; detail?: string };
   /** The `ChangeSet` action chant's existing plan logic assigned, when the component maps to a tracked entity/resource name. */
   action?: ChangeAction;
   /** Ownership verdict, when known. */
@@ -132,6 +151,10 @@ export function mergeLiveEvidence(
     const b = merged.get(component);
     merged.set(component, {
       live: sup.live,
+      // A direct stack observation that succeeded answers the question the
+      // change-set axis could not — so it clears an inherited "not observed".
+      // A supplement that itself could not read keeps the hole.
+      ...(sup.unobserved ? { unobserved: sup.unobserved } : {}),
       ownership: sup.ownership ?? b?.ownership,
       action: b?.action,
       stack: sup.stack ?? b?.stack,
@@ -178,8 +201,12 @@ function mergeEvidence(entries: LiveComponentEvidence[]): LiveComponentEvidence
   const action = entries.some((e) => e.action === "update")
     ? "update"
     : entries.find((e) => e.action !== undefined)?.action;
+  // A component whose entities were partly readable is still partly unknown, so
+  // any unobserved entity keeps the hole — unless something under it was
+  // actually seen live, which already answers "is this deployed".
+  const unobserved = live ? undefined : entries.find((e) => e.unobserved)?.unobserved;
 
-  return { live, ownership, action };
+  return { live, ownership, action, ...(unobserved ? { unobserved } : {}) };
 }
 
 /**
@@ -204,6 +231,16 @@ export function liveEvidenceFromChangeSet(
       live: entry.evidence.live,
       action: entry.action,
       ownership: entry.ownership,
+      // Carry the plan's "could not look" verdict through so the status join
+      // reports a hole instead of reading `live: false` as "gone" (#1089).
+      ...(entry.action === "unobserved" && entry.unobservedReason
+        ? {
+            unobserved: {
+              reason: entry.unobservedReason,
+              ...(entry.unobservedDetail ? { detail: entry.unobservedDetail } : {}),
+            },
+          }
+        : {}),
     });
   }
 
@@ -275,6 +312,15 @@ export function reconcileStatus(
       detail = recorded
         ? "recorded; live status not queried (pass --live to reconcile)"
         : "no release record found";
+    } else if (evidence?.unobserved) {
+      // Live evidence was requested and could not be read (#1089). Neither
+      // `stale` (which claims the component is gone) nor `reconciled` is
+      // supportable — the honest verdict is that nothing is known.
+      reconciliation = "unknown";
+      const why = `${unobservedReasonText(evidence.unobserved.reason)}${evidence.unobserved.detail ? `: ${evidence.unobserved.detail}` : ""}`;
+      detail = recorded
+        ? `recorded ${recorded.timestamp} (digest ${recorded.digest}), but live state could not be observed — ${why}`
+        : `no release record, and live state could not be observed — ${why}`;
     } else if (!recorded && evidence?.live) {
       reconciliation = "unrecorded";
       detail = `live${evidence.ownership === "owned" ? " and chant-owned" : ""}, but no release record exists — deployed outside the recorded path`;
@@ -300,7 +346,11 @@ export function reconcileStatus(
       componentBom,
       reconciliation,
       detail,
-      ...(liveEvidence ? { live: !!evidence?.live } : {}),
+      // `live` is only emitted when it is a real answer: requested AND read.
+      // An unread component leaves it absent (= unknown to every consumer)
+      // rather than reporting `false`, which would read as "not deployed".
+      ...(liveEvidence && !evidence?.unobserved ? { live: !!evidence?.live } : {}),
+      ...(evidence?.unobserved ? { unobserved: evidence.unobserved } : {}),
       ...(evidence?.stack ? { stack: evidence.stack } : {}),
     });
   }

package/src/lifecycle/types.ts

@@ -1,4 +1,5 @@
 import type { ResourceMetadata, ArtifactMetadata } from "../lexicon";
+import type { UnobservedEntity } from "../observation";
 
 export type { ResourceMetadata, ArtifactMetadata } from "../lexicon";
 
@@ -18,6 +19,13 @@ export interface LifecycleSnapshot {
   timestamp: string;
   /** Resource metadata keyed by logical name */
   resources: Record<string, ResourceMetadata>;
+  /**
+   * Declared entities this observation could not read (#1089), keyed by logical
+   * name. Additive and optional: a snapshot without it observed everything it
+   * was asked about. Present so a later diff can tell "was not there when the
+   * snapshot was taken" from "was never looked at".
+   */
+  unobserved?: Record<string, UnobservedEntity>;
   /** Artifact metadata keyed by server-side identifier (lexicon-specific). */
   artifacts?: Record<string, ArtifactMetadata>;
   /** Build digest at snapshot time — what was declared when this snapshot was taken */

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',
+    );
+  });
+});