@intentius/chant-lexicon-k8s 0.37.3 → 0.39.0

package/src/crd/crd-sources.ts

@@ -93,6 +93,111 @@ const COCKROACH_OPERATOR_CRD_BASE = `https://raw.githubusercontent.com/cockroach
 const CERT_MANAGER_VERSION = "v1.16.2";
 const CERT_MANAGER_CRD_BUNDLE = `https://github.com/cert-manager/cert-manager/releases/download/${CERT_MANAGER_VERSION}/cert-manager.crds.yaml`;
 
+/**
+ * CloudNativePG CRDs — postgresql.cnpg.io/v1
+ *
+ * The Postgres operator. Produces, under the `Cnpg` namespace (both groups are
+ * mapped there explicitly in parser.ts; the first-segment rule would otherwise
+ * split them into `Postgresql` and `Barmancloud`):
+ *   K8s::Cnpg::Cluster          → postgresql.cnpg.io/v1
+ *   K8s::Cnpg::ScheduledBackup  → postgresql.cnpg.io/v1
+ *   K8s::Cnpg::Backup           → postgresql.cnpg.io/v1
+ *   K8s::Cnpg::Pooler           → postgresql.cnpg.io/v1
+ *
+ * Pinned to 1.29.1 rather than latest (1.30.0) because that is the operator a
+ * real consumer runs — BinaryBourbon/fountain's k8s overlay.
+ *
+ * Note on ScheduledBackup.schedule: it is a **six**-field cron with leading
+ * seconds, not the five-field form Kubernetes CronJob takes. The schema types
+ * it as a plain string, so a five-field value passes every check here and
+ * silently means something else on the cluster.
+ *
+ * Database, Publication and Subscription are deliberately left out — no known
+ * consumer needs them, and pulling a whole provider is what the note at the top
+ * of this file warns against.
+ *
+ * Operator install: kubectl apply --server-side -f
+ *   https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.29/releases/cnpg-1.29.1.yaml
+ */
+const CNPG_VERSION = "v1.29.1";
+const CNPG_CRD_BASE = `https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/${CNPG_VERSION}/config/crd/bases`;
+
+/**
+ * barman-cloud plugin CRD — barmancloud.cnpg.io/v1
+ *
+ * CNPG's WAL archiving / object-storage backend, shipped as a separate plugin
+ * with its own release train. Produces:
+ *   K8s::Cnpg::ObjectStore  → barmancloud.cnpg.io/v1
+ *
+ * A CNPG Cluster reaches it through `spec.plugins[]` — `name:
+ * barman-cloud.cloudnative-pg.io`, `isWALArchiver: true`,
+ * `parameters.barmanObjectName` naming the ObjectStore — so the two are only
+ * ever useful together.
+ *
+ * Pinned to 0.14.0 (latest). Its ObjectStore schema is a superset of 0.7.0's:
+ * same four spec properties, more detail inside them.
+ *
+ * Plugin install: kubectl apply -f
+ *   https://github.com/cloudnative-pg/plugin-barman-cloud/releases/download/v0.14.0/manifest.yaml
+ */
+const BARMAN_PLUGIN_VERSION = "v0.14.0";
+const BARMAN_PLUGIN_CRD_BASE = `https://raw.githubusercontent.com/cloudnative-pg/plugin-barman-cloud/${BARMAN_PLUGIN_VERSION}/config/crd/bases`;
+/**
+ * Traefik proxy CRDs — traefik.io/v1alpha1
+ *
+ * Traefik's own routing surface. An `IngressRoute` is not a
+ * `networking.k8s.io` Ingress with annotations — it is a distinct CRD with its
+ * own matcher grammar, so an estate fronted by Traefik has no expressible edge
+ * without these. Produces, under the `Traefik` namespace (first-segment rule,
+ * no override needed):
+ *   K8s::Traefik::IngressRoute          K8s::Traefik::Middleware
+ *   K8s::Traefik::IngressRouteTCP       K8s::Traefik::MiddlewareTCP
+ *   K8s::Traefik::IngressRouteUDP       K8s::Traefik::ServersTransport
+ *   K8s::Traefik::TLSOption             K8s::Traefik::ServersTransportTCP
+ *   K8s::Traefik::TLSStore              K8s::Traefik::TraefikService
+ *
+ * Only the `traefik.io` group. The chart's crds/ directory also ships
+ * `hub.traefik.io_*` (Traefik Hub, a different commercial product, ~12 kinds,
+ * no known consumer) and a vendored copy of the Gateway API, which is already
+ * generated here from its upstream repo and would collide.
+ *
+ * Version footgun: the pin below is the **chart** version, and the chart
+ * version is not the Traefik version. Chart v41.1.0 ships Traefik v3.7.9.
+ * When bumping, record both.
+ *
+ * Controller install: helm repo add traefik https://traefik.github.io/charts
+ *   && helm install traefik traefik/traefik --version 41.1.0
+ */
+const TRAEFIK_CHART_VERSION = "v41.1.0";
+const TRAEFIK_CRD_BASE = `https://raw.githubusercontent.com/traefik/traefik-helm-chart/${TRAEFIK_CHART_VERSION}/traefik/crds`;
+/**
+ * Infisical operator CRDs — secrets.infisical.com/v1alpha1
+ *
+ * The declarative form of chant's own secrets boundary. An `InfisicalSecret`
+ * says where a secret comes from and who may fetch it; it never carries a
+ * value. Without it an estate can declare the Deployment that consumes a
+ * Secret but not the thing that makes the Secret exist. Produces, under the
+ * `Infisical` namespace:
+ *   K8s::Infisical::InfisicalSecret
+ *   K8s::Infisical::InfisicalPushSecret
+ *   K8s::Infisical::InfisicalDynamicSecret
+ *
+ * The group is overridden to `Infisical` in parser.ts. The first-segment rule
+ * would give `K8s::Secrets::InfisicalSecret`, which reads like a core Secret
+ * next to the `K8s::Core::Secret` that already exists.
+ *
+ * Two things about the URL, both easy to lose an hour to:
+ *   - The operator lives in its own repo, `Infisical/kubernetes-operator`.
+ *     The path under the `Infisical/infisical` monorepo 404s.
+ *   - The tag is path-shaped — `infisical-k8-operator/v0.11.7`. Not a typo,
+ *     and not a directory.
+ *
+ * Operator install: helm repo add infisical https://dl.cloudsmith.io/public/infisical/helm-charts/helm/charts/
+ *   && helm install infisical-secrets-operator infisical/secrets-operator
+ */
+const INFISICAL_OPERATOR_VERSION = "infisical-k8-operator/v0.11.7";
+const INFISICAL_CRD_BASE = `https://raw.githubusercontent.com/Infisical/kubernetes-operator/${INFISICAL_OPERATOR_VERSION}/config/crd/bases`;
+
 /**
  * Prometheus Operator CRDs — monitoring.coreos.com/v1
  *
@@ -188,6 +293,24 @@ export const CRD_SOURCES: CRDSource[] = [
   { type: "url", url: CERT_MANAGER_CRD_BUNDLE },
   { type: "url", url: `${PROM_OPERATOR_CRD_BASE}/monitoring.coreos.com_servicemonitors.yaml` },
   { type: "url", url: `${PROM_OPERATOR_CRD_BASE}/monitoring.coreos.com_prometheusrules.yaml` },
+  { type: "url", url: `${CNPG_CRD_BASE}/postgresql.cnpg.io_clusters.yaml` },
+  { type: "url", url: `${CNPG_CRD_BASE}/postgresql.cnpg.io_scheduledbackups.yaml` },
+  { type: "url", url: `${CNPG_CRD_BASE}/postgresql.cnpg.io_backups.yaml` },
+  { type: "url", url: `${CNPG_CRD_BASE}/postgresql.cnpg.io_poolers.yaml` },
+  { type: "url", url: `${BARMAN_PLUGIN_CRD_BASE}/barmancloud.cnpg.io_objectstores.yaml` },
+  { type: "url", url: `${TRAEFIK_CRD_BASE}/traefik.io_ingressroutes.yaml` },
+  { type: "url", url: `${TRAEFIK_CRD_BASE}/traefik.io_ingressroutetcps.yaml` },
+  { type: "url", url: `${TRAEFIK_CRD_BASE}/traefik.io_ingressrouteudps.yaml` },
+  { type: "url", url: `${TRAEFIK_CRD_BASE}/traefik.io_middlewares.yaml` },
+  { type: "url", url: `${TRAEFIK_CRD_BASE}/traefik.io_middlewaretcps.yaml` },
+  { type: "url", url: `${TRAEFIK_CRD_BASE}/traefik.io_serverstransports.yaml` },
+  { type: "url", url: `${TRAEFIK_CRD_BASE}/traefik.io_serverstransporttcps.yaml` },
+  { type: "url", url: `${TRAEFIK_CRD_BASE}/traefik.io_tlsoptions.yaml` },
+  { type: "url", url: `${TRAEFIK_CRD_BASE}/traefik.io_tlsstores.yaml` },
+  { type: "url", url: `${TRAEFIK_CRD_BASE}/traefik.io_traefikservices.yaml` },
+  { type: "url", url: `${INFISICAL_CRD_BASE}/secrets.infisical.com_infisicalsecrets.yaml` },
+  { type: "url", url: `${INFISICAL_CRD_BASE}/secrets.infisical.com_infisicalpushsecrets.yaml` },
+  { type: "url", url: `${INFISICAL_CRD_BASE}/secrets.infisical.com_infisicaldynamicsecrets.yaml` },
   {
     type: "url",
     url: FLUX_TOOLKIT_INSTALL,

package/src/crd/infisical.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Infisical acceptance test.
+ *
+ * Transcribed from fountain's `k8s/infisicalsecret.yaml`. Every field in that
+ * manifest is policy — where the secret comes from, who may fetch it, what
+ * happens to the materialized Secret when the CR goes away. None of it is a
+ * value, which is why this kind is expressible in chant at all.
+ */
+
+import { describe, test, expect } from "vitest";
+import { InfisicalSecret } from "../generated";
+import { k8sSerializer } from "../serializer";
+import { parseYAML } from "@intentius/chant/yaml";
+
+function synth(logicalName: string, resource: unknown): any {
+  const yaml = k8sSerializer.serialize(new Map([[logicalName, resource as never]]));
+  return parseYAML(yaml);
+}
+
+const fountainSecrets = new InfisicalSecret({
+  metadata: { name: "fountain-secrets", namespace: "fountain", labels: { app: "fountain" } },
+  spec: {
+    hostAPI: "http://infisical.infisical.svc.cluster.local:8080",
+    resyncInterval: 60,
+    authentication: {
+      kubernetesAuth: {
+        identityId: "6ccf748c-7fe1-4584-a206-b0a56d84530c",
+        autoCreateServiceAccountToken: true,
+        serviceAccountRef: { name: "fountain-infisical", namespace: "fountain" },
+        secretsScope: { projectSlug: "fountain-q-cwt", envSlug: "prod", secretsPath: "/" },
+      },
+    },
+    managedSecretReference: {
+      secretName: "fountain-secrets",
+      secretNamespace: "fountain",
+      creationPolicy: "Orphan",
+    },
+  },
+});
+
+describe("InfisicalSecret", () => {
+  test("carries the Infisical apiVersion and kind", () => {
+    const doc = synth("fountainSecrets", fountainSecrets);
+    expect(doc.apiVersion).toBe("secrets.infisical.com/v1alpha1");
+    expect(doc.kind).toBe("InfisicalSecret");
+    expect(doc.metadata.name).toBe("fountain-secrets");
+  });
+
+  test("reproduces fountain's infisicalsecret.yaml", () => {
+    const { spec } = synth("fountainSecrets", fountainSecrets);
+    expect(spec.hostAPI).toBe("http://infisical.infisical.svc.cluster.local:8080");
+    expect(spec.resyncInterval).toBe(60);
+    expect(spec.managedSecretReference).toEqual({
+      secretName: "fountain-secrets",
+      secretNamespace: "fountain",
+      creationPolicy: "Orphan",
+    });
+  });
+
+  test("serializes the whole kubernetesAuth block", () => {
+    const { spec } = synth("fountainSecrets", fountainSecrets);
+    // Kubernetes-native auth: the point is that no credential is stored
+    // anywhere. The operator presents a ServiceAccount token instead, so
+    // dropping any part of this block is what turns the deployment back into
+    // one that needs a secret to fetch its secrets.
+    expect(spec.authentication.kubernetesAuth).toEqual({
+      identityId: "6ccf748c-7fe1-4584-a206-b0a56d84530c",
+      autoCreateServiceAccountToken: true,
+      serviceAccountRef: { name: "fountain-infisical", namespace: "fountain" },
+      secretsScope: { projectSlug: "fountain-q-cwt", envSlug: "prod", secretsPath: "/" },
+    });
+  });
+
+  test("declares a source and never a value", () => {
+    // The reason this CRD fits chant at all: synthesis resolves nothing here.
+    // If a secret value could reach the manifest, the manifest would stop
+    // being safe to commit -- so assert on the serialized text, not the props.
+    const yaml = k8sSerializer.serialize(
+      new Map([["fountainSecrets", fountainSecrets as never]]),
+    );
+    expect(yaml).not.toMatch(/\bvalue\s*:/);
+    expect(yaml).not.toMatch(/\bdata\s*:/);
+    expect(yaml).not.toMatch(/\bstringData\s*:/);
+  });
+
+  test("keeps resyncInterval a number", () => {
+    const { spec } = synth("fountainSecrets", fountainSecrets);
+    // Quoted, the operator rejects the CR rather than defaulting -- worth
+    // pinning because seconds-as-a-string is a habit from other tools.
+    expect(typeof spec.resyncInterval).toBe("number");
+  });
+
+  test("creationPolicy Orphan survives, since the two policies differ on deletion", () => {
+    const { spec } = synth("fountainSecrets", fountainSecrets);
+    // Orphan leaves the materialized Secret behind when the CR is deleted;
+    // Owner takes it with it. Silently flipping to the default would make CR
+    // deletion destructive.
+    expect(spec.managedSecretReference.creationPolicy).toBe("Orphan");
+  });
+});

package/src/crd/parser.ts

@@ -44,6 +44,14 @@ const GROUP_NAMESPACE_OVERRIDES: Record<string, string> = {
   "image.toolkit.fluxcd.io": "Flux",
   "fluxcd.controlplane.io": "Flux",
   "lambda.aws.amazon.com": "KubeMicroVM",
+  // CNPG and its barman-cloud plugin ship under two groups but are one thing to
+  // an author: a Cluster's `plugins[]` names an ObjectStore. The first-segment
+  // rule would scatter them into `Postgresql` and `Barmancloud`.
+  "postgresql.cnpg.io": "Cnpg",
+  "barmancloud.cnpg.io": "Cnpg",
+  // Not `Secrets`: `K8s::Secrets::InfisicalSecret` reads like a core Secret,
+  // and `K8s::Core::Secret` is right there to be confused with.
+  "secrets.infisical.com": "Infisical",
 };
 
 /**

package/src/crd/traefik.test.ts

@@ -0,0 +1,108 @@
+/**
+ * Traefik acceptance test.
+ *
+ * Transcribed from fountain's `k8s/ingressroute.yaml` — the websecure route
+ * with `tls.secretName`, and the web route whose middleware lives in another
+ * namespace. The cross-namespace reference is the reason this file exists: it
+ * is one extra key, it is easy to leave off, and leaving it off produces a
+ * route that applies cleanly and drops traffic.
+ */
+
+import { describe, test, expect } from "vitest";
+import { IngressRoute, Middleware } from "../generated";
+import { k8sSerializer } from "../serializer";
+import { parseYAML } from "@intentius/chant/yaml";
+
+function synth(logicalName: string, resource: unknown): any {
+  const yaml = k8sSerializer.serialize(new Map([[logicalName, resource as never]]));
+  return parseYAML(yaml);
+}
+
+describe("Traefik IngressRoute", () => {
+  const secure = new IngressRoute({
+    metadata: { name: "fountain", namespace: "fountain", labels: { app: "fountain" } },
+    spec: {
+      entryPoints: ["websecure"],
+      routes: [
+        {
+          match: "Host(`fountain.inevitable.fyi`)",
+          kind: "Rule",
+          services: [{ name: "fountain", port: 80 }],
+        },
+      ],
+      tls: { secretName: "fountain-tls" },
+    },
+  });
+
+  const plain = new IngressRoute({
+    metadata: { name: "fountain-http", namespace: "fountain", labels: { app: "fountain" } },
+    spec: {
+      entryPoints: ["web"],
+      routes: [
+        {
+          match: "Host(`fountain.inevitable.fyi`)",
+          kind: "Rule",
+          middlewares: [{ name: "redirect-https", namespace: "default" }],
+          services: [{ name: "fountain", port: 80 }],
+        },
+      ],
+    },
+  });
+
+  test("carries the Traefik apiVersion and kind", () => {
+    const doc = synth("fountain", secure);
+    expect(doc.apiVersion).toBe("traefik.io/v1alpha1");
+    expect(doc.kind).toBe("IngressRoute");
+  });
+
+  test("reproduces the websecure route", () => {
+    const { spec } = synth("fountain", secure);
+    expect(spec.entryPoints).toEqual(["websecure"]);
+    expect(spec.tls).toEqual({ secretName: "fountain-tls" });
+    expect(spec.routes).toHaveLength(1);
+    expect(spec.routes[0].kind).toBe("Rule");
+    expect(spec.routes[0].services).toEqual([{ name: "fountain", port: 80 }]);
+  });
+
+  test("preserves the matcher grammar verbatim", () => {
+    const { spec } = synth("fountain", secure);
+    // Traefik's matcher is its own language, and the backticks around the host
+    // are part of it -- not YAML quoting. Anything that strips or re-quotes
+    // them produces a rule that parses and matches nothing.
+    expect(spec.routes[0].match).toBe("Host(`fountain.inevitable.fyi`)");
+    expect(spec.routes[0].match).toContain("`fountain.inevitable.fyi`");
+  });
+
+  test("keeps the namespace on a cross-namespace middleware ref", () => {
+    const { spec } = synth("fountainHttp", plain);
+    // `redirect-https` lives in `default`, the route in `fountain`. Without the
+    // qualifier Traefik looks in the route's own namespace, finds nothing, and
+    // serves the route with no redirect -- so plain HTTP quietly keeps working
+    // instead of upgrading.
+    expect(spec.routes[0].middlewares).toEqual([
+      { name: "redirect-https", namespace: "default" },
+    ]);
+  });
+
+  test("a route with no TLS omits the key rather than emptying it", () => {
+    const { spec } = synth("fountainHttp", plain);
+    expect(spec.tls).toBeUndefined();
+    expect(spec.entryPoints).toEqual(["web"]);
+  });
+});
+
+describe("Traefik Middleware", () => {
+  test("serializes the redirect the routes point at", () => {
+    const doc = synth(
+      "redirectHttps",
+      new Middleware({
+        metadata: { name: "redirect-https", namespace: "default" },
+        spec: { redirectScheme: { scheme: "https", permanent: true } },
+      }),
+    );
+    expect(doc.apiVersion).toBe("traefik.io/v1alpha1");
+    expect(doc.kind).toBe("Middleware");
+    expect(doc.metadata.namespace).toBe("default");
+    expect(doc.spec.redirectScheme).toEqual({ scheme: "https", permanent: true });
+  });
+});

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