@intentius/chant-lexicon-k8s 0.28.0 → 0.30.0

package/dist/describe-resources.d.ts

@@ -7,9 +7,14 @@
  * name (using the props.metadata.name + props.metadata.namespace from #39's
  * entity-prop pass-through).
  *
- * Resource-not-found is silent — `state diff --live` then reports it as
- * missing (declared, not in cloud). Unknown entity types are warn-skipped;
- * extending the KUBECTL_RESOURCE map covers more.
+ * The observation tri-state (#1089) is what the return value carries. A genuine
+ * `NotFound` from the API server is an absence, and only that becomes a `create`
+ * downstream. An entity type with no entry in `KUBECTL_RESOURCE` — every CRD —
+ * was never looked at, and comes back `unsupported-kind`: it may well be running
+ * in the cluster, and proposing to create it would be a guess. Auth failures and
+ * unreachable API servers come back `no-credentials` / `no-binding` for the same
+ * reason. Extending the KUBECTL_RESOURCE map converts unsupported-kind holes into
+ * real reads; until then they are holes chant admits to.
  *
  * Before touching any resource, the environment is resolved to a cluster
  * identity (chant #1100) via `resolveClusterTarget` — see `./config.ts` for
@@ -19,7 +24,7 @@
  * error rather than silently reading the wrong cluster. No binding keeps
  * today's behavior (ambient context), with a visible warning.
  */
-import type { ResourceMetadata } from "@intentius/chant/lexicon";
+import type { ObservationResult } from "@intentius/chant/lexicon";
 /**
  * Map chant entity types to `kubectl get` resource names. Add entries here
  * as new types are needed.
@@ -34,5 +39,5 @@ export declare function describeResources(options: {
         props: Record<string, unknown>;
     }>;
     owned?: boolean;
-}): Promise<Record<string, ResourceMetadata>>;
+}): Promise<ObservationResult>;
 //# sourceMappingURL=describe-resources.d.ts.map

package/dist/describe-resources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../src/describe-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAOjE;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAoBnD,CAAC;AAsCF,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CA2D5C"}
+{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../src/describe-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAsC,MAAM,0BAA0B,CAAC;AAQtG;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAoBnD,CAAC;AAsCF,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAyF7B"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "63b8e4b79b980ec7b6fb5e49b43686eeb7b024e6feab86d6d71169c65db10587",
+    "manifest.json": "a14947ba11b4d27cc1387e873f31bcacec4af1e574efe03110ee9f826c74451a",
     "meta.json": "6d112006daa7196eb28619ac5a3893b709dc2b845edbd537db7d7b471e8dc104",
     "types/index.d.ts": "7b873148146a5512c22baabfde6cfcc3248c24c2c7578f68a19544af5dc675f6",
     "rules/argo-appset-single-project.ts": "afa9f310753aa2d475f35012b13135b2dfaebed2a35d44edbe185ebc07673674",
@@ -50,5 +50,5 @@
     "skills/chant-k8s-aks.md": "e18f0e2b055f72cd7a37deaf258d7027c2d4d3e286e8fd4975b27a1f981a3ad9",
     "skills/chant-k8s-argo.md": "b1a0b826559d8c5033a479c5781efaf650320f0aee4419d8841170bd3393cea5"
   },
-  "composite": "d6deea6f0e6f08944da12ce71f90784b9fce48659eee22cbf223ae331c7e1e22"
+  "composite": "76ad1e3946f333f82f54e8da4c6b1f6e3ba11c7137d7f5b2728a58e786b1341e"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "k8s",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "chantVersion": ">=0.1.0",
   "namespace": "K8s",
   "intrinsics": [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-k8s",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "Kubernetes lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -75,7 +75,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.28.0",
+    "@intentius/chant": "^0.30.0",
     "typescript": "^5.9.3"
   }
 }

package/src/describe-resources.test.ts

@@ -60,13 +60,13 @@ describe("k8s describeResources", () => {
 
     const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["web", "webSvc"], entities });
 
-    expect(result["web"]).toMatchObject({
+    expect(result.resources["web"]).toMatchObject({
       type: "K8s::Apps::Deployment",
       physicalId: "uid-1",
       status: "READY",
       attributes: expect.objectContaining({ namespace: "prod", labels: { app: "web" } }),
     });
-    expect(result["webSvc"]).toMatchObject({
+    expect(result.resources["webSvc"]).toMatchObject({
       type: "K8s::Core::Service",
       physicalId: "uid-2",
       status: "PRESENT",
@@ -82,10 +82,12 @@ describe("k8s describeResources", () => {
 
     const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["missing"], entities });
 
-    expect(result).toEqual({});
+    // A real NotFound is an absence: neither present nor unobserved.
+    expect(result.resources).toEqual({});
+    expect(result.unobserved ?? {}).toEqual({});
   });
 
-  test("entity types without kubectl mapping are warn-skipped", async () => {
+  test("entity types without kubectl mapping are reported unobserved, not absent (#1089)", async () => {
     const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
     const entities = makeEntities([
       { name: "exotic", entityType: "K8s::Custom::CRD::SomeOperator", props: { metadata: { name: "x" } } },
@@ -93,13 +95,69 @@ describe("k8s describeResources", () => {
 
     const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["exotic"], entities });
 
-    expect(result).toEqual({});
-    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("kubectl mapping"));
+    expect(result.resources).toEqual({});
+    expect(result.unobserved?.exotic).toMatchObject({
+      type: "K8s::Custom::CRD::SomeOperator",
+      reason: "unsupported-kind",
+    });
+    expect(execMock).not.toHaveBeenCalled();
     const mappingWarning = warnSpy.mock.calls.find((c) => String(c[0]).includes("kubectl mapping"));
     expect(mappingWarning?.[0]).toContain("K8s::Custom::CRD::SomeOperator");
     warnSpy.mockRestore();
   });
 
+  // #1089 — a kubectl failure that is not a NotFound proves nothing about the
+  // object's existence, and must not reach the change set as an absence.
+  test.each([
+    ["error: You must be logged in to the server (Unauthorized)", "no-credentials"],
+    ["The connection to the server 127.0.0.1:6443 was refused - did you specify the right host or port?", "no-binding"],
+    ["error: unexpected EOF while parsing", "read-failed"],
+  ])("kubectl failure %j is reported unobserved (%s)", async (stderr, reason) => {
+    execMock.mockImplementation(() => { throw Object.assign(new Error("kubectl failed"), { stderr }); });
+    const entities = makeEntities([
+      { name: "web", entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web", namespace: "prod" } } },
+    ]);
+
+    const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["web"], entities });
+
+    expect(result.resources).toEqual({});
+    expect(result.unobserved?.web?.reason).toBe(reason);
+  });
+
+  test("a CRD kind the server does not serve is a real absence (nothing of that kind can exist)", async () => {
+    execMock.mockImplementation(() => {
+      throw Object.assign(new Error("kubectl failed"), {
+        stderr: 'error: the server doesn\'t have a resource type "widgets"',
+      });
+    });
+    const entities = makeEntities([
+      { name: "web", entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web", namespace: "prod" } } },
+    ]);
+
+    const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["web"], entities });
+
+    expect(result.resources).toEqual({});
+    expect(result.unobserved ?? {}).toEqual({});
+  });
+
+  test("--owned withholds an unmarked live object as `filtered`, never as absent (#1089)", async () => {
+    execMock.mockResolvedValue({
+      stdout: JSON.stringify({
+        metadata: { name: "web", namespace: "prod", uid: "uid-1", creationTimestamp: "t", labels: { app: "web" } },
+        status: { readyReplicas: 1, replicas: 1 },
+      }),
+      stderr: "",
+    });
+    const entities = makeEntities([
+      { name: "web", entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web", namespace: "prod" } } },
+    ]);
+
+    const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["web"], entities, owned: true });
+
+    expect(result.resources).toEqual({});
+    expect(result.unobserved?.web?.reason).toBe("filtered");
+  });
+
   test("Deployment with replicas != readyReplicas reports PROGRESSING", async () => {
     execMock.mockResolvedValue({
       stdout: JSON.stringify({
@@ -115,7 +173,7 @@ describe("k8s describeResources", () => {
 
     const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["web"], entities });
 
-    expect(result["web"].status).toBe("PROGRESSING(1/3)");
+    expect(result.resources["web"].status).toBe("PROGRESSING(1/3)");
   });
 
   test("Pod uses status.phase as the status", async () => {
@@ -133,7 +191,7 @@ describe("k8s describeResources", () => {
 
     const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["p"], entities });
 
-    expect(result["p"].status).toBe("Running");
+    expect(result.resources["p"].status).toBe("Running");
   });
 
   test("namespace-less resource omits the -n flag", async () => {
@@ -159,14 +217,15 @@ describe("k8s describeResources", () => {
     expect(receivedCmd).toContain("namespace mynamespace");
   });
 
-  test("entity without metadata.name is silently skipped", async () => {
+  test("entity without metadata.name is unobserved — nothing was queried", async () => {
     const entities = makeEntities([
       { name: "broken", entityType: "K8s::Apps::Deployment", props: {} },
     ]);
 
     const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["broken"], entities });
 
-    expect(result).toEqual({});
+    expect(result.resources).toEqual({});
+    expect(result.unobserved?.broken?.reason).toBe("read-failed");
     expect(execMock).not.toHaveBeenCalled();
   });
 
@@ -196,7 +255,7 @@ describe("k8s describeResources", () => {
       const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["web"], entities: deploymentEntities() });
 
       expect(receivedCmd).toContain("--context prod-eks");
-      expect(result["web"]).toMatchObject({ type: "K8s::Apps::Deployment", physicalId: "uid-1", status: "READY" });
+      expect(result.resources["web"]).toMatchObject({ type: "K8s::Apps::Deployment", physicalId: "uid-1", status: "READY" });
     });
 
     test("bound and ambient context mismatches: refuses loudly instead of observing the wrong cluster", async () => {
@@ -228,7 +287,7 @@ describe("k8s describeResources", () => {
       // Unchanged: no ambient-context probe, no --context flag, same result shape as today.
       expect(receivedCmd).not.toContain("--context");
       expect(receivedCmd).not.toContain("current-context");
-      expect(result["web"]).toMatchObject({ type: "K8s::Apps::Deployment", physicalId: "uid-1", status: "READY" });
+      expect(result.resources["web"]).toMatchObject({ type: "K8s::Apps::Deployment", physicalId: "uid-1", status: "READY" });
 
       // Visible, not silent: a warning names the environment and the missing binding.
       const bindingWarning = warnSpy.mock.calls.find((c) => String(c[0]).includes("no cluster binding"));

package/src/describe-resources.ts

@@ -7,9 +7,14 @@
  * name (using the props.metadata.name + props.metadata.namespace from #39's
  * entity-prop pass-through).
  *
- * Resource-not-found is silent — `state diff --live` then reports it as
- * missing (declared, not in cloud). Unknown entity types are warn-skipped;
- * extending the KUBECTL_RESOURCE map covers more.
+ * The observation tri-state (#1089) is what the return value carries. A genuine
+ * `NotFound` from the API server is an absence, and only that becomes a `create`
+ * downstream. An entity type with no entry in `KUBECTL_RESOURCE` — every CRD —
+ * was never looked at, and comes back `unsupported-kind`: it may well be running
+ * in the cluster, and proposing to create it would be a guess. Auth failures and
+ * unreachable API servers come back `no-credentials` / `no-binding` for the same
+ * reason. Extending the KUBECTL_RESOURCE map converts unsupported-kind holes into
+ * real reads; until then they are holes chant admits to.
  *
  * Before touching any resource, the environment is resolved to a cluster
  * identity (chant #1100) via `resolveClusterTarget` — see `./config.ts` for
@@ -22,10 +27,11 @@
 
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
-import type { ResourceMetadata } from "@intentius/chant/lexicon";
+import type { ObservationResult, ResourceMetadata, UnobservedEntity } from "@intentius/chant/lexicon";
+import { observation } from "@intentius/chant/observation";
 import { hasOwnershipMarker, classifyOwnership, LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
 import { loadChantConfig } from "@intentius/chant/config";
-import { resolveClusterTarget } from "@intentius/chant/kubectl-context";
+import { resolveClusterTarget, classifyKubectlFailure } from "@intentius/chant/kubectl-context";
 
 const execAsync = promisify(exec);
 
@@ -97,8 +103,9 @@ export async function describeResources(options: {
   entityNames: string[];
   entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
   owned?: boolean;
-}): Promise<Record<string, ResourceMetadata>> {
+}): Promise<ObservationResult> {
   const result: Record<string, ResourceMetadata> = {};
+  const unobserved: Record<string, UnobservedEntity> = {};
   const skippedTypes = new Set<string>();
 
   // Resolve the cluster identity for this environment before touching any
@@ -112,13 +119,29 @@ export async function describeResources(options: {
   for (const [entityName, { entityType, props }] of options.entities) {
     const kubectlResource = KUBECTL_RESOURCE[entityType];
     if (!kubectlResource) {
+      // No reader for this kind (every CRD). The object may exist; chant has no
+      // way to ask. Reporting it as unobserved is what stops `lifecycle plan`
+      // proposing to create a CRD that is already in the cluster (#1089).
       skippedTypes.add(entityType);
+      unobserved[entityName] = {
+        type: entityType,
+        reason: "unsupported-kind",
+        detail: `no kubectl mapping for ${entityType} — extend KUBECTL_RESOURCE to observe it`,
+      };
       continue;
     }
 
     const metadata = props.metadata as { name?: string; namespace?: string } | undefined;
     const name = metadata?.name;
-    if (!name) continue;
+    if (!name) {
+      // Nothing to query by. Not an absence — chant never issued a read.
+      unobserved[entityName] = {
+        type: entityType,
+        reason: "read-failed",
+        detail: "declared entity has no metadata.name to query by",
+      };
+      continue;
+    }
 
     const nsArg = metadata.namespace ? ["-n", metadata.namespace] : [];
     const cmd = ["kubectl", "get", kubectlResource, name, ...nsArg, ...ctxArg, "-o", "json"].join(" ");
@@ -126,8 +149,16 @@ export async function describeResources(options: {
     try {
       const { stdout } = await execAsync(cmd);
       const obj: KubectlResponse = JSON.parse(stdout);
-      // owned filter: skip resources not carrying chant's marker label.
+      // owned filter: withhold resources not carrying chant's marker label.
+      // Withheld is not absent (#1089) — this object exists, it just isn't
+      // chant's, and dropping it silently is how `--owned` used to turn a
+      // declared-but-foreign resource into a proposed `create`.
       if (options.owned && !hasOwnershipMarker(obj.metadata?.labels, LABEL_OWNERSHIP_KEYS)) {
+        unobserved[entityName] = {
+          type: entityType,
+          reason: "filtered",
+          detail: "live object carries no chant ownership marker and --owned was requested",
+        };
         continue;
       }
       result[entityName] = {
@@ -142,18 +173,23 @@ export async function describeResources(options: {
           resourceVersion: obj.metadata?.resourceVersion,
         }),
       };
-    } catch {
-      // Resource not found / kubectl error — leave it out so state diff
-      // can report it as missing. Don't fail the whole snapshot.
+    } catch (err) {
+      // Only a real NotFound leaves the entity out (an absence the diff may
+      // read as missing and the plan as create). Auth, connectivity, and every
+      // other failure prove nothing about existence and are reported as such.
+      const outcome = classifyKubectlFailure(err);
+      if (outcome.kind === "unobserved") {
+        unobserved[entityName] = { type: entityType, reason: outcome.reason, detail: outcome.detail };
+      }
     }
   }
 
   if (skippedTypes.size > 0) {
     // eslint-disable-next-line no-console
     console.warn(
-      `[k8s] skipped ${skippedTypes.size} entity type(s) without kubectl mapping: ${[...skippedTypes].join(", ")}`,
+      `[k8s] no kubectl mapping for ${skippedTypes.size} entity type(s): ${[...skippedTypes].join(", ")} — reported as unobserved (not absent), so no create is proposed for them`,
     );
   }
 
-  return result;
+  return observation(result, unobserved);
 }

package/src/lifecycle-integration.test.ts

@@ -31,6 +31,9 @@ vi.mock("node:child_process", async () => {
 const { k8sPlugin } = await import("./plugin");
 const { liveImportFromPlugins } = await import("@intentius/chant/cli/commands/import");
 const { buildChangeSet } = await import("@intentius/chant/lifecycle/change-set");
+const { normalizeObservation } = await import("@intentius/chant/observation");
+const { liveEvidenceFromChangeSet, reconcileStatus } = await import("@intentius/chant/lifecycle/status");
+const { describeObservationConformance } = await import("@intentius/chant-test-utils");
 
 const liveDeployment = {
   apiVersion: "apps/v1",
@@ -82,14 +85,16 @@ describe("k8s lifecycle integration (#163)", () => {
         : new Error("not found"),
     );
 
-    const observedNow = await k8sPlugin.describeResources!({
-      environment: "prod",
-      buildOutput: "",
-      entityNames: ["web"],
-      entities: new Map([
-        ["web", { entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web", namespace: "prod" } } }],
-      ]),
-    });
+    const { resources: observedNow } = normalizeObservation(
+      await k8sPlugin.describeResources!({
+        environment: "prod",
+        buildOutput: "",
+        entityNames: ["web"],
+        entities: new Map([
+          ["web", { entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web", namespace: "prod" } } }],
+        ]),
+      }),
+    );
     expect(observedNow.web?.type).toBe("K8s::Apps::Deployment");
 
     const cs = buildChangeSet("prod", {
@@ -108,4 +113,130 @@ describe("k8s lifecycle integration (#163)", () => {
     });
     expect(cs2.entries.find((e) => e.name === "web")!.action).toBe("noop");
   });
+
+  /**
+   * The #1089 chain, end to end on the real plugin: a declared CRD the lexicon
+   * has no reader for goes describe → plan → component status without ever
+   * turning into a create or a "stale" component.
+   */
+  test("tri-state chain: an unreadable CRD stays unobserved through describe → plan → status (#1089)", async () => {
+    execMock.mockImplementation((cmd?: string) =>
+      cmd?.includes("deployment.apps web")
+        ? {
+            stdout: JSON.stringify({
+              metadata: { name: "web", namespace: "prod", uid: "uid-1" },
+              status: { readyReplicas: 3, replicas: 3 },
+            }),
+            stderr: "",
+          }
+        : new Error('Error from server (NotFound): deployments.apps "gone" not found'),
+    );
+
+    const entities = new Map([
+      ["web", { entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web", namespace: "prod" } } }],
+      ["gone", { entityType: "K8s::Apps::Deployment", props: { metadata: { name: "gone", namespace: "prod" } } }],
+      ["widget", { entityType: "K8s::Example::Widget", props: { metadata: { name: "widget", namespace: "prod" } } }],
+    ]);
+
+    // 1. describe — three declared entities, three different verdicts.
+    const observed = normalizeObservation(
+      await k8sPlugin.describeResources!({
+        environment: "prod",
+        buildOutput: "",
+        entityNames: [...entities.keys()],
+        entities,
+      }),
+    );
+    expect(Object.keys(observed.resources)).toEqual(["web"]);
+    expect(observed.unobserved.widget.reason).toBe("unsupported-kind");
+    expect(observed.unobserved.gone).toBeUndefined(); // NotFound is an absence
+
+    // 2. plan — the CRD is `unobserved`; only the confirmed-absent one is a create.
+    const cs = buildChangeSet("prod", {
+      declared: new Set(entities.keys()),
+      observedNow: observed.resources,
+      observedThen: undefined,
+      unobserved: observed.unobserved,
+    });
+    const byName = Object.fromEntries(cs.entries.map((e) => [e.name, e.action]));
+    expect(byName).toEqual({ web: "noop", gone: "create", widget: "unobserved" });
+
+    // 3. status — a recorded component whose entity was never read reports
+    // `unknown`, not `stale`, and carries no `live` boolean at all.
+    const rows = reconcileStatus("prod", [
+      { component: "widget", env: "prod", digest: "sha256:abc", gitSha: "g", runId: "r", timestamp: "2026-01-01T00:00:00Z", actor: "ci" },
+    ], { liveEvidence: liveEvidenceFromChangeSet(cs) });
+    const widgetRow = rows.find((r) => r.component === "widget")!;
+    expect(widgetRow.reconciliation).toBe("unknown");
+    expect(widgetRow.live).toBeUndefined();
+    expect(widgetRow.unobserved?.reason).toBe("unsupported-kind");
+    expect(widgetRow.detail).toContain("could not be observed");
+  });
+});
+
+// The shared conformance suite (#1089) — every observing lexicon runs it.
+describeObservationConformance({
+  lexicon: "k8s",
+  scenarios: [
+    {
+      name: "a CRD kind with no reader",
+      declared: ["widget", "gone"],
+      expectUnobserved: ["widget"],
+      expectAbsent: ["gone"],
+      run: () => {
+        execMock.mockImplementation(() => new Error('Error from server (NotFound): deployments.apps "gone" not found'));
+        return k8sPlugin.describeResources!({
+          environment: "prod",
+          buildOutput: "",
+          entityNames: ["widget", "gone"],
+          entities: new Map([
+            ["widget", { entityType: "K8s::Example::Widget", props: { metadata: { name: "widget" } } }],
+            ["gone", { entityType: "K8s::Apps::Deployment", props: { metadata: { name: "gone" } } }],
+          ]),
+        });
+      },
+    },
+    {
+      name: "an unreachable API server",
+      declared: ["web"],
+      expectUnobserved: ["web"],
+      run: () => {
+        execMock.mockImplementation(() =>
+          Object.assign(new Error("kubectl failed"), {
+            stderr: "The connection to the server 127.0.0.1:6443 was refused - did you specify the right host or port?",
+          }),
+        );
+        return k8sPlugin.describeResources!({
+          environment: "prod",
+          buildOutput: "",
+          entityNames: ["web"],
+          entities: new Map([
+            ["web", { entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web" } } }],
+          ]),
+        });
+      },
+    },
+    {
+      name: "a healthy read",
+      declared: ["web"],
+      expectPresent: ["web"],
+      run: () => {
+        execMock.mockImplementation(() => ({
+          stdout: JSON.stringify({
+            metadata: { name: "web", namespace: "prod", uid: "uid-1", labels: { "app.kubernetes.io/managed-by": "chant" } },
+            status: { readyReplicas: 1, replicas: 1 },
+          }),
+          stderr: "",
+        }));
+        return k8sPlugin.describeResources!({
+          environment: "prod",
+          buildOutput: "",
+          entityNames: ["web"],
+          entities: new Map([
+            ["web", { entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web" } } }],
+          ]),
+        });
+      },
+    },
+  ],
 });