@intentius/chant-lexicon-k8s 0.38.0 → 0.41.0

package/src/composites/node-agent.ts

@@ -85,7 +85,7 @@ export interface NodeAgentResult {
  * });
  * ```
  */
-export const NodeAgent = Composite<NodeAgentProps>((props) => {
+export const NodeAgent = Composite((props: NodeAgentProps) => {
   const {
     name,
     image,

package/src/composites/ray-cluster.ts

@@ -426,7 +426,7 @@ export function buildRayNetworkPolicy(
  * });
  * ```
  */
-export const RayCluster = Composite<RayClusterProps>((props) => {
+export const RayCluster = Composite((props: RayClusterProps) => {
   const {
     name,
     namespace,

package/src/composites/ray-job.ts

@@ -101,7 +101,7 @@ export interface RayJobResult {
  * });
  * ```
  */
-export const RayJob = Composite<RayJobProps>((props) => {
+export const RayJob = Composite((props: RayJobProps) => {
   const {
     name,
     namespace,

package/src/composites/ray-service.ts

@@ -102,7 +102,7 @@ export interface RayServiceResult {
  * });
  * ```
  */
-export const RayService = Composite<RayServiceProps>((props) => {
+export const RayService = Composite((props: RayServiceProps) => {
   const {
     name,
     namespace,

package/src/composites/secure-ingress.ts

@@ -68,7 +68,7 @@ export interface SecureIngressResult {
  * });
  * ```
  */
-export const SecureIngress = Composite<SecureIngressProps>((props) => {
+export const SecureIngress = Composite((props: SecureIngressProps) => {
   const {
     name,
     hosts,

package/src/composites/sidecar-app.ts

@@ -110,7 +110,7 @@ export interface SidecarAppResult {
  * });
  * ```
  */
-export const SidecarApp = Composite<SidecarAppProps>((props) => {
+export const SidecarApp = Composite((props: SidecarAppProps) => {
   const {
     name,
     image,

package/src/composites/stateful-app.ts

@@ -80,7 +80,7 @@ export interface StatefulAppResult {
  * });
  * ```
  */
-export const StatefulApp = Composite<StatefulAppProps>((props) => {
+export const StatefulApp = Composite((props: StatefulAppProps) => {
   const {
     name,
     image,

package/src/composites/web-app.ts

@@ -93,7 +93,7 @@ export interface WebAppResult {
  * export { deployment, service, ingress };
  * ```
  */
-export const WebApp = Composite<WebAppProps>((props) => {
+export const WebApp = Composite((props: WebAppProps) => {
   const {
     name,
     image,

package/src/composites/worker-pool.ts

@@ -97,7 +97,7 @@ export interface WorkerPoolResult {
  * });
  * ```
  */
-export const WorkerPool = Composite<WorkerPoolProps>((props) => {
+export const WorkerPool = Composite((props: WorkerPoolProps) => {
   const {
     name,
     image,

package/src/composites/workload-identity-sa.ts

@@ -55,7 +55,7 @@ export interface WorkloadIdentityServiceAccountResult {
  * });
  * ```
  */
-export const WorkloadIdentityServiceAccount = Composite<WorkloadIdentityServiceAccountProps>((props) => {
+export const WorkloadIdentityServiceAccount = Composite((props: WorkloadIdentityServiceAccountProps) => {
   const {
     name,
     clientId,

package/src/composites/workload-identity-service-account.ts

@@ -55,7 +55,7 @@ export interface WorkloadIdentityServiceAccountResult {
  * });
  * ```
  */
-export const WorkloadIdentityServiceAccount = Composite<WorkloadIdentityServiceAccountProps>((props) => {
+export const WorkloadIdentityServiceAccount = Composite((props: WorkloadIdentityServiceAccountProps) => {
   const {
     name,
     gcpServiceAccountEmail,

package/src/config-schema.ts

@@ -0,0 +1,46 @@
+/**
+ * Runtime shape of the `k8s` namespace in `chant.config.ts` (#1344).
+ *
+ * `./config.ts` describes the namespace for readers and for the `satisfies
+ * K8sChantConfig` form it documents. What it could not do is make an unknown
+ * key fail: the project config schema is `.passthrough()`, so a typo in
+ * `k8s.profiles.prod.contxt` was accepted and ignored — and a missing cluster
+ * binding is the failure this lexicon most cares about, since a wrong-cluster
+ * read reports every declared resource as missing (#1100).
+ *
+ * The schema is the runtime half. It is checked against `K8sChantConfig` below,
+ * so the two descriptions of the namespace cannot drift.
+ */
+
+import { z } from "zod";
+import type { ChantConfig } from "@intentius/chant/config";
+import type { K8sChantConfig } from "./config";
+
+export const k8sClusterProfileSchema = z.strictObject({
+  context: z.string(),
+});
+
+export const k8sConfigSchema = z.strictObject({
+  profiles: z.record(z.string(), k8sClusterProfileSchema).optional(),
+  execCredentialPlugins: z.array(z.string()).optional(),
+});
+
+declare module "@intentius/chant/config" {
+  interface ChantConfig {
+    k8s?: K8sChantConfig;
+  }
+}
+
+/** Compile-time proof the augmentation reaches `ChantConfig`. */
+export type K8sConfigNamespace = NonNullable<ChantConfig["k8s"]>;
+
+/**
+ * The schema and the documented interface describe the same namespace. If a
+ * field is added to one and not the other, this stops compiling.
+ */
+type SchemaMatchesInterface = z.infer<typeof k8sConfigSchema> extends K8sChantConfig
+  ? K8sChantConfig extends z.infer<typeof k8sConfigSchema>
+    ? true
+    : never
+  : never;
+export type _SchemaAgreesWithInterface = SchemaMatchesInterface;

package/src/config.ts

@@ -39,7 +39,11 @@
  *
  * `ChantConfig` uses `.passthrough()` in its Zod schema so the `k8s` key is
  * accepted at runtime without core changes, exactly like `temporal.profiles`
- * (see `lexicons/temporal/src/config.ts`).
+ * (see `lexicons/temporal/src/config.ts`). The type side is the declaration
+ * merge at the bottom of this file — without it the snippet above compiles
+ * only until someone adds `satisfies ChantConfig`, which every example
+ * project does and which is the only thing type-checking the rest of the
+ * file (#1370).
  *
  * Deliberately out of scope here (see the issue for the full proposal):
  * deriving the binding automatically from a declared `AWS::EKS::Cluster` /
@@ -51,6 +55,8 @@
  * typed API client to inherit, rather than re-deriving it.
  */
 
+import type { ChantConfig } from "@intentius/chant/config";
+
 /** A single environment's cluster binding. */
 export interface K8sClusterProfile {
   /** kubectl context name this environment is bound to. */
@@ -78,3 +84,21 @@ export interface K8sChantConfig {
    */
   execCredentialPlugins?: string[];
 }
+
+declare module "@intentius/chant/config" {
+  interface ChantConfig {
+    k8s?: K8sChantConfig;
+  }
+}
+
+/**
+ * Compile-time proof that the augmentation above reaches `ChantConfig`, the
+ * same guard the forgejo lexicon carries (#1344).
+ *
+ * Without it this line is `Property 'k8s' does not exist on type
+ * 'ChantConfig'` — which is exactly the error a project got for writing the
+ * documented snippet with `satisfies ChantConfig` (#1370). It lives here
+ * rather than in a test because the root tsconfig excludes test files from
+ * typechecking, so a compile-time claim asserted in one is checked by nothing.
+ */
+export type K8sConfigNamespace = NonNullable<ChantConfig["k8s"]>;

package/src/deep-observe-hooks.ts

@@ -11,7 +11,9 @@
  * #1074 made that package's reachability from the build path a structural
  * property (`examples/k8s-client-boundary.test.ts`) rather than a lint rule —
  * so nothing this file exports may pull that package in, directly or
- * transitively. It imports nothing but the core contract's own types.
+ * transitively. It imports the core contract's own types, and one generated
+ * JSON data file (`./generated/list-map-keys.json`, chant #1441) — data, not a
+ * package, so the boundary property is unchanged.
  *
  * What lives here is deliberately the *entityType-keyed, resource-agnostic*
  * half of the rules: which fields the API server always populates regardless
@@ -39,7 +41,7 @@
  * keyed by chant's own k8s entityType catalog.
  */
 
-import type { DeepNode, DeepNormalizationHooks } from "@intentius/chant/lexicon";
+import type { DeepArrayElement, DeepNode, DeepNormalizationHooks } from "@intentius/chant/lexicon";
 import { K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS, k8sListMapOrderKey } from "@intentius/chant/managed-fields";
 
 /**
@@ -96,13 +98,17 @@ function canonicalJson(value: unknown): string {
  * The k8s lexicon's static noise rules: the generic Kubernetes object
  * envelope (unconditional, by pattern, `@intentius/chant/managed-fields`) and
  * Kubernetes-defaulted fields (gated on `counterpart === "absent"`), plus the
- * array orderings the acceptance criteria name — `x-kubernetes-patch-merge-
- * key`/`list-map-keys` conventions the generated surface does not currently
- * carry (see the module doc), so these are the "else named-by-name
- * conventions" the issue calls for: containers by `name`, `env` by `name`,
- * `volumes` by `name`, container/service `ports` by `containerPort`/`port` +
- * `protocol` — the same conventions `@intentius/chant/managed-fields`'s
- * `k8sListMapOrderKey` implements, reused verbatim.
+ * array orderings.
+ *
+ * The orderings are now taken from the spec itself (chant #1441): codegen
+ * carries `x-kubernetes-list-type`/`x-kubernetes-list-map-keys` through into
+ * `./generated/list-map-keys.json`, and {@link schemaListMapOrderKey} reads
+ * it. The hand-written conventions in
+ * `@intentius/chant/managed-fields`'s `k8sListMapOrderKey` — containers by
+ * `name`, `env` by `name`, `volumes` by `name`, container/service `ports` by
+ * `containerPort`/`port` + `protocol` — remain as the fallback for lists the
+ * spec does not annotate, and for readers that have no generated table at all
+ * (GCP's Config Connector hooks).
  *
  * This is the object `k8sPlugin.deepNormalizationHooks` is. It is also what
  * `./deep-observe.ts` layers its per-resource managed-fields prune on top of,
@@ -111,6 +117,80 @@ function canonicalJson(value: unknown): string {
  * — see `packages/core/src/lifecycle/deep-observe.ts`) apply the identical
  * entityType-keyed rules either way.
  */
+/** Property name → candidate key-field sets, generated from the spec (chant #1441). */
+type ListMapKeyTable = Record<string, string[][]>;
+
+let cachedListMapKeys: ListMapKeyTable | undefined;
+
+function listMapKeyTable(): ListMapKeyTable {
+  cachedListMapKeys ??= require("./generated/list-map-keys.json") as ListMapKeyTable;
+  return cachedListMapKeys;
+}
+
+/** Last dotted segment of an index-erased path: `spec.template.spec.containers` → `containers`. */
+function lastSegment(pattern: string): string {
+  const at = pattern.lastIndexOf(".");
+  return at === -1 ? pattern : pattern.slice(at + 1);
+}
+
+/**
+ * Render one key field's value into a sort key fragment. Numbers are
+ * zero-padded so the key orders numerically rather than lexicographically —
+ * `"443"` would otherwise sort before `"80"`. Cosmetic, since either order
+ * canonicalizes the two sides identically, but a human-sensible order is free
+ * to have here (the same reasoning `k8sListMapOrderKey` applies to ports).
+ */
+function keyFragment(value: unknown): string {
+  if (typeof value === "number") return String(value).padStart(5, "0");
+  return typeof value === "string" ? value : canonicalJson(value);
+}
+
+/**
+ * Join a key set's values the way `k8sListMapOrderKey` already does: the bare
+ * values, `/`-separated, with no field names.
+ *
+ * This is not only a sort key. Core renders it as the element's ADDRESS in
+ * drift output — `spec.template.spec.containers[#app].image` — so the format
+ * is user-visible and load-bearing. Emitting `name=app` here would rewrite
+ * every existing drift path. Bare values keep the six properties that were
+ * hardcoded byte-identical, and extend to the rest for free: a container port
+ * reads `[#08080/TCP]` exactly as before, a condition reads `[#Ready]`.
+ */
+function joinKeyValues(el: Record<string, unknown>, keys: string[]): string {
+  return keys.map((k) => keyFragment(el[k])).join("/");
+}
+
+/**
+ * Order an associative list's element by the identity the SPEC declares for it
+ * (chant #1441), falling back to `@intentius/chant/managed-fields`'s hand-written
+ * conventions for anything the generated table does not cover.
+ *
+ * The fallback is not vestigial. The table is built from the properties this
+ * lexicon's codegen parsed, so it covers core Kubernetes and any CRD that
+ * declares the extensions — but a CRD that declares an associative list
+ * WITHOUT `x-kubernetes-list-map-keys`, or a Config Connector resource read
+ * through GCP's hooks, still lands on the by-name conventions. Keeping both
+ * means widening the spec-derived table can never narrow what was already
+ * identified.
+ */
+export function schemaListMapOrderKey(element: DeepArrayElement): string | undefined {
+  const candidates = listMapKeyTable()[lastSegment(element.pattern)];
+  const el = element.element;
+
+  if (candidates && isRecordLike(el)) {
+    for (const keys of candidates) {
+      if (!keys.every((k) => el[k] !== undefined)) continue;
+      return joinKeyValues(el, keys);
+    }
+  }
+
+  return k8sListMapOrderKey(element);
+}
+
+function isRecordLike(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 export const k8sDeepNormalizationHooks: DeepNormalizationHooks = {
   prune(node: DeepNode): boolean {
     if (K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS.has(node.pattern)) return true;
@@ -121,5 +201,5 @@ export const k8sDeepNormalizationHooks: DeepNormalizationHooks = {
     return canonicalJson(defaults[node.pattern]) === canonicalJson(node.value);
   },
 
-  orderKey: k8sListMapOrderKey,
+  orderKey: schemaListMapOrderKey,
 };

package/src/deep-observe.ts

@@ -284,6 +284,13 @@ export async function observeResourcesDeepK8s(
           side: "live",
           hooks: perResourceHooks(sets),
         }),
+        // Who owns each surviving path (#1189). The prune above already
+        // dropped confidently-foreign undeclared noise, so what reaches the
+        // diff is chant's own fields and contested ones — and for a contested
+        // field, naming the manager is the whole question: an operator needs to
+        // tell `hpa-controller` doing its job from somebody running
+        // `kubectl edit`.
+        ...(sets.owners.size > 0 ? { fieldOwners: Object.fromEntries(sets.owners) } : {}),
       };
     } catch (err) {
       const outcome = classifyApiFailure(err);

package/src/describe-resources.test.ts

@@ -15,7 +15,7 @@ vi.mock("@intentius/chant/config", () => ({
   loadChantConfig: (...args: unknown[]) => loadChantConfigMock(...args),
 }));
 
-const { describeResources } = await import("./describe-resources");
+const { describeResources, statusFromObject, unhappyConditions } = await import("./describe-resources");
 const { fakeCluster, objectKey, ownedObject } = await import("./api/fake-cluster");
 const { defaultK8sConnector } = await import("./api/connect");
 const { fakeKubeconfig, statusBody } = await import("@intentius/chant-k8s-client/testing");
@@ -725,3 +725,140 @@ describe("k8s describeResources", () => {
     });
   });
 });
+
+// #1397 — a Pod's phase is `Running` from the moment the kubelet admits it, so
+// the phase alone reported a crashlooping Pod as `Running`, which every
+// consumer classifying that word read as healthy.
+describe("statusFromObject — the most specific failing signal (#1397)", () => {
+  test("a crashlooping Pod reports the reason, not the phase", () => {
+    expect(
+      statusFromObject({
+        status: {
+          phase: "Running",
+          containerStatuses: [{ state: { waiting: { reason: "CrashLoopBackOff", message: "back-off 5m0s" } } }],
+        },
+      } as never),
+    ).toBe("CrashLoopBackOff");
+  });
+
+  test("an image-pull failure reports the reason", () => {
+    expect(
+      statusFromObject({
+        status: { phase: "Pending", containerStatuses: [{ state: { waiting: { reason: "ImagePullBackOff" } } }] },
+      } as never),
+    ).toBe("ImagePullBackOff");
+  });
+
+  test("an unschedulable Pod reports Unschedulable, not Pending", () => {
+    expect(
+      statusFromObject({
+        status: {
+          phase: "Pending",
+          conditions: [{ type: "PodScheduled", status: "False", reason: "Unschedulable" }],
+        },
+      } as never),
+    ).toBe("Unschedulable");
+  });
+
+  test("ordinary startup is not promoted over the phase", () => {
+    // ContainerCreating and PodInitializing are not failure; surfacing them
+    // would be noise, and the phase already classifies as progressing.
+    for (const reason of ["ContainerCreating", "PodInitializing"]) {
+      expect(
+        statusFromObject({
+          status: { phase: "Pending", containerStatuses: [{ state: { waiting: { reason } } }] },
+        } as never),
+      ).toBe("Pending");
+    }
+  });
+
+  test("a terminated container does not outrank the phase — a Job container exits cleanly", () => {
+    expect(
+      statusFromObject({
+        status: { phase: "Succeeded", containerStatuses: [{ state: { terminated: { reason: "Completed", exitCode: 0 } } }] },
+      } as never),
+    ).toBe("Succeeded");
+  });
+
+  test("a healthy Pod and a ready Deployment are unchanged", () => {
+    expect(statusFromObject({ status: { phase: "Running", containerStatuses: [{ state: { running: {} } }] } } as never)).toBe("Running");
+    expect(statusFromObject({ status: { readyReplicas: 3, replicas: 3 } } as never)).toBe("READY");
+    expect(statusFromObject({ status: { readyReplicas: 1, replicas: 3 } } as never)).toBe("PROGRESSING(1/3)");
+    expect(statusFromObject({} as never)).toBe("PRESENT");
+  });
+});
+
+// #1401 — #1397 made the status WORD honest; this carries the part that says
+// what to do about it. `Unschedulable` is the reason; "0/3 nodes are available"
+// is the answer.
+describe("unhappyConditions (#1401)", () => {
+  test("reports an unschedulable Pod's message, not just its reason", () => {
+    expect(
+      unhappyConditions({
+        status: {
+          conditions: [
+            {
+              type: "PodScheduled",
+              status: "False",
+              reason: "Unschedulable",
+              message: "0/3 nodes are available: 1 node(s) had untolerated taint.",
+            },
+          ],
+        },
+      } as never),
+    ).toEqual(["PodScheduled=Unschedulable: 0/3 nodes are available: 1 node(s) had untolerated taint."]);
+  });
+
+  test("is absent when every condition is happy — presence means the object has something to say", () => {
+    expect(
+      unhappyConditions({
+        status: { conditions: [{ type: "Ready", status: "True" }, { type: "PodScheduled", status: "True" }] },
+      } as never),
+    ).toBeUndefined();
+  });
+
+  test("knows the happy polarity is per condition type", () => {
+    // Ready/Available/PodScheduled are good when True; the *Pressure and
+    // NetworkUnavailable node conditions are good when False. Treating them all
+    // the same would report every healthy node as unhappy, or hide a node
+    // genuinely under disk pressure.
+    const healthyNode = {
+      status: {
+        conditions: [
+          { type: "Ready", status: "True" },
+          { type: "MemoryPressure", status: "False" },
+          { type: "DiskPressure", status: "False" },
+        ],
+      },
+    };
+    expect(unhappyConditions(healthyNode as never)).toBeUndefined();
+
+    const pressured = {
+      status: {
+        conditions: [
+          { type: "Ready", status: "True" },
+          { type: "DiskPressure", status: "True", reason: "KubeletHasDiskPressure" },
+        ],
+      },
+    };
+    expect(unhappyConditions(pressured as never)).toEqual(["DiskPressure=KubeletHasDiskPressure"]);
+  });
+
+  test("reports every unhappy condition, since a stuck Deployment has two", () => {
+    expect(
+      unhappyConditions({
+        status: {
+          conditions: [
+            { type: "Available", status: "False", reason: "MinimumReplicasUnavailable" },
+            { type: "Progressing", status: "False", reason: "ProgressDeadlineExceeded", message: "ReplicaSet has timed out." },
+          ],
+        },
+      } as never),
+    ).toHaveLength(2);
+  });
+
+  test("is absent for an object with no conditions at all", () => {
+    expect(unhappyConditions({ status: {} } as never)).toBeUndefined();
+    expect(unhappyConditions({} as never)).toBeUndefined();
+  });
+});

package/src/describe-resources.ts

@@ -80,6 +80,22 @@ function pruneUndefined<T extends Record<string, unknown>>(obj: T): Record<strin
  */
 export function statusFromObject(obj: K8sObject): string {
   const status = obj.status;
+
+  // The most specific FAILING signal wins over the outermost one (#1397).
+  //
+  // A Pod's phase is `Running` from the moment the kubelet admits it and one
+  // container starts — so a crashlooping Pod reported `Running`, which every
+  // consumer classifying that word read as healthy. The failure lives one level
+  // down, in `containerStatuses[].state.waiting.reason`, and never reached the
+  // wire, so nothing downstream could recover it.
+  const waiting = failingContainerReason(status);
+  if (waiting) return waiting;
+
+  // Scheduling failure is a condition, not a phase: an unschedulable Pod is
+  // `Pending`, which is true and useless next to `Unschedulable`.
+  const blocked = failingConditionReason(status);
+  if (blocked) return blocked;
+
   const phase = status?.phase;
   if (typeof phase === "string") return phase;
   if (status && typeof status.readyReplicas === "number" && typeof status.replicas === "number") {
@@ -90,6 +106,85 @@ export function statusFromObject(obj: K8sObject): string {
   return "PRESENT";
 }
 
+/**
+ * The reason a container is stuck, if one is — `CrashLoopBackOff`,
+ * `ImagePullBackOff`, `CreateContainerConfigError`.
+ *
+ * Only a WAITING container counts. A terminated one may have exited cleanly as
+ * part of a Job, and a running one is not stuck; neither should outrank the
+ * phase.
+ */
+function failingContainerReason(status: K8sObject["status"]): string | undefined {
+  const containers = (status as { containerStatuses?: unknown } | undefined)?.containerStatuses;
+  if (!Array.isArray(containers)) return undefined;
+  for (const c of containers) {
+    const reason = (c as { state?: { waiting?: { reason?: unknown } } })?.state?.waiting?.reason;
+    // `ContainerCreating` and `PodInitializing` are ordinary startup, not
+    // failure — they already classify as progressing, and promoting them over
+    // the phase would just be noisier.
+    if (typeof reason === "string" && reason.length > 0 && reason !== "ContainerCreating" && reason !== "PodInitializing") {
+      return reason;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The reason a blocking condition is False — `Unschedulable` and the like.
+ *
+ * Only conditions whose truth means "this object is usable"; a False `Ready` on
+ * its own is already visible through the phase and the container states above.
+ */
+function failingConditionReason(status: K8sObject["status"]): string | undefined {
+  const conditions = (status as { conditions?: unknown } | undefined)?.conditions;
+  if (!Array.isArray(conditions)) return undefined;
+  for (const c of conditions) {
+    const cond = c as { type?: unknown; status?: unknown; reason?: unknown };
+    if (cond.type !== "PodScheduled") continue;
+    if (cond.status !== "False") continue;
+    if (typeof cond.reason === "string" && cond.reason.length > 0) return cond.reason;
+  }
+  return undefined;
+}
+
+
+/**
+ * The unhappy conditions on a live object, as `Type=Reason: message` (#1401).
+ *
+ * #1397 made the status WORD honest — a crashlooping Pod reports
+ * `CrashLoopBackOff` rather than `Running`. This carries the part that says
+ * what to do about it: `Unschedulable` is the reason, and
+ * `0/3 nodes are available: 1 node(s) had untolerated taint` is the answer, and
+ * only the first reached the wire.
+ *
+ * Only conditions that are NOT in their happy state are reported. A `Ready=True`
+ * says nothing an operator needs and would bury the one line that does — and a
+ * condition's happy polarity is per type: `Ready`/`Available`/`PodScheduled`
+ * are good when True, while `Unschedulable`-style and the standard
+ * `*Pressure`/`NetworkUnavailable` node conditions are good when False.
+ *
+ * Absent when everything is happy, so a consumer can treat presence as "this
+ * object has something to say".
+ */
+const CONDITIONS_GOOD_WHEN_FALSE = /pressure$|^networkunavailable$|^unschedulable$|failed/i;
+
+export function unhappyConditions(obj: K8sObject): string[] | undefined {
+  const conditions = (obj.status as { conditions?: unknown } | undefined)?.conditions;
+  if (!Array.isArray(conditions)) return undefined;
+  const out: string[] = [];
+  for (const c of conditions) {
+    const cond = c as { type?: unknown; status?: unknown; reason?: unknown; message?: unknown };
+    if (typeof cond.type !== "string" || typeof cond.status !== "string") continue;
+    const goodWhenFalse = CONDITIONS_GOOD_WHEN_FALSE.test(cond.type);
+    const happy = goodWhenFalse ? cond.status === "False" : cond.status === "True";
+    if (happy) continue;
+    const reason = typeof cond.reason === "string" && cond.reason ? `=${cond.reason}` : "";
+    const message = typeof cond.message === "string" && cond.message ? `: ${cond.message}` : "";
+    out.push(`${cond.type}${reason}${message}`);
+  }
+  return out.length > 0 ? out : undefined;
+}
+
 interface Declared {
   entityName: string;
   entityType: string;
@@ -211,6 +306,8 @@ export async function describeResources(
           namespace: obj.metadata?.namespace,
           labels: obj.metadata?.labels,
           resourceVersion: obj.metadata?.resourceVersion,
+          // What the object's own controller says is wrong with it (#1401).
+          conditions: unhappyConditions(obj),
         }),
       };
     } catch (err) {
@@ -289,6 +386,7 @@ async function addRuntimeChildren(
           namespace,
           labels: pod.metadata?.labels,
           resourceVersion: pod.metadata?.resourceVersion,
+          conditions: unhappyConditions(pod),
         }),
       };
     });