@intentius/chant-lexicon-k8s 0.44.13 → 0.45.0

package/src/deep-observe.test.ts

@@ -128,6 +128,38 @@ describe("k8sDeepNormalizationHooks — the static rules", () => {
     expect(foreign).toEqual({ metadata: { name: "web", labels: { "app.kubernetes.io/managed-by": "helm" } } });
   });
 
+  test("controller-stamped annotations and labels subtract; an out-of-band user label does not (#1191)", () => {
+    const live = {
+      metadata: {
+        name: "web",
+        labels: { "pod-template-hash": "5d4f8b7c9", team: "platform" },
+        annotations: {
+          "deployment.kubernetes.io/revision": "3",
+          "kubectl.kubernetes.io/last-applied-configuration": "{}",
+          "kubernetes.io/change-cause": "kubectl set image",
+        },
+      },
+    };
+    const out = normalizeDeepProperties(live, {
+      entityType: "K8s::Apps::Deployment",
+      side: "live",
+      hooks: k8sDeepNormalizationHooks,
+      counterpartPaths: new Set(["metadata", "metadata.name"]),
+    });
+    expect(out).toEqual({
+      metadata: { name: "web", labels: { team: "platform" }, annotations: { "kubernetes.io/change-cause": "kubectl set image" } },
+    });
+
+    // Declared, so compared — the allowlist is counterpart-gated like the defaults table.
+    const declaredRevision = normalizeDeepProperties(live, {
+      entityType: "K8s::Apps::Deployment",
+      side: "live",
+      hooks: k8sDeepNormalizationHooks,
+      counterpartPaths: new Set(["metadata", "metadata.name", "metadata.annotations", "metadata.annotations.deployment.kubernetes.io/revision"]),
+    });
+    expect((declaredRevision as { metadata: { annotations: Record<string, string> } }).metadata.annotations["deployment.kubernetes.io/revision"]).toBe("3");
+  });
+
   test("a server-assigned ClusterIP nobody declared subtracts; a declared one is compared", () => {
     const undeclared = normalizeDeepProperties(
       { spec: { clusterIP: "10.43.201.161", clusterIPs: ["10.43.201.161"], ipFamilies: ["IPv4"], selector: { app: "web" } } },
@@ -453,8 +485,10 @@ describe("observeResourcesDeepK8s — reading through the typed client (#1076)",
  */
 describe("end to end: managed-fields-derived drift (#1076)", () => {
   const declared = makeEntities([
-    // "web": HPA owns replicas (undeclared → pruned), Istio injects a sidecar
-    // (undeclared → pruned), and someone changed a label chant owns.
+    // "web": someone changed a label chant owns, someone added a label chant
+    // never declared (#1191), HPA owns replicas and Istio injected a sidecar
+    // (both undeclared — drift until accepted), and the Deployment controller
+    // stamped its revision annotation (system noise, never drift).
     {
       name: "web",
       entityType: "K8s::Apps::Deployment",
@@ -505,10 +539,12 @@ describe("end to end: managed-fields-derived drift (#1076)", () => {
       resourceVersion: "42",
       generation: 7,
       creationTimestamp: "2026-01-01T00:00:00Z",
-      // GENUINE DRIFT: chant owns this label, and the live value moved.
-      labels: { app: "web", tier: "frontend" },
-      // ACCEPTED: chant owns this annotation; the platform's baseline accepts "43".
-      annotations: { "build-id": "43" },
+      // GENUINE DRIFT: chant owns `tier`, and the live value moved.
+      // UNDECLARED DRIFT: `team` was added out of band by `kubectl label` (#1191).
+      labels: { app: "web", tier: "frontend", team: "platform" },
+      // ACCEPTED: chant owns build-id; the platform's baseline accepts "43".
+      // NOISE: the Deployment controller's revision counter is on the static allowlist.
+      annotations: { "build-id": "43", "deployment.kubernetes.io/revision": "3" },
       managedFields: [
         {
           manager: "chant:web",
@@ -529,15 +565,27 @@ describe("end to end: managed-fields-derived drift (#1076)", () => {
           },
         },
         {
-          // NOISE: HPA owns replicas, and chant never declared it.
+          // UNDECLARED: a human ran `kubectl label deploy web team=platform`.
+          manager: "kubectl-edit",
+          operation: "Update",
+          apiVersion: "apps/v1",
+          time: "2026-01-03T00:00:00Z",
+          fieldsV1: { "f:metadata": { "f:labels": { "f:team": {} } } },
+        },
+        {
+          // UNDECLARED until accepted: HPA owns replicas, and chant never declared it.
+          // SYSTEM NOISE: the revision annotation, stamped by the Deployment controller.
           manager: "kube-controller-manager",
           operation: "Update",
           apiVersion: "apps/v1",
           time: "2026-01-02T00:00:00Z",
-          fieldsV1: { "f:spec": { "f:replicas": {} } },
+          fieldsV1: {
+            "f:metadata": { "f:annotations": { "f:deployment.kubernetes.io/revision": {} } },
+            "f:spec": { "f:replicas": {} },
+          },
         },
         {
-          // NOISE: a mutating webhook injected a whole sidecar container.
+          // UNDECLARED until accepted: a mutating webhook injected a whole sidecar container.
           manager: "istio-sidecar-injector",
           operation: "Update",
           apiVersion: "apps/v1",
@@ -625,14 +673,21 @@ describe("end to end: managed-fields-derived drift (#1076)", () => {
       respond: (req) => (req.path.endsWith("/deployments/broken") ? { status: 500, body: statusBody(500, "InternalError", "backend unavailable") } : undefined),
     });
 
+  // The platform accepted the HPA and the sidecar — the valve #1191 leans on —
+  // but nobody accepted the `team` label.
   const baseline = {
     web: {
       type: "K8s::Apps::Deployment",
-      accepted: [{ path: "metadata.annotations.build-id", value: "43" }],
+      accepted: [
+        { path: "metadata.annotations.build-id", value: "43" },
+        { path: "spec.replicas", value: 7 },
+        { path: "spec.template.spec.containers[#istio-proxy].name", value: "istio-proxy" },
+        { path: "spec.template.spec.containers[#istio-proxy].image", value: "istio/proxyv2:1.20" },
+      ],
     },
   };
 
-  test("exactly the genuine + contested drift surfaces; controller noise and the accepted annotation do not", async () => {
+  test("genuine, undeclared and contested drift surface; accepted deviations and controller-stamped metadata do not", async () => {
     const live = normalizeDeepObservation(
       await observeResourcesDeepK8s({ environment: "prod", entityNames: [...declared.keys()], entities: declared }, cluster().connector),
     );
@@ -642,28 +697,36 @@ describe("end to end: managed-fields-derived drift (#1076)", () => {
       {
         name: "web",
         type: "K8s::Apps::Deployment",
-        changes: [{ path: "metadata.labels.tier", kind: "changed", declared: "backend", live: "frontend" }],
+        changes: [
+          // The #1191 case: foreign-owned, undeclared, not accepted — and the owner says who.
+          { path: "metadata.labels.team", kind: "undeclared", live: "platform", owner: "kubectl-edit" },
+          { path: "metadata.labels.tier", kind: "changed", declared: "backend", live: "frontend", owner: "chant:web" },
+        ],
       },
       {
         name: "worker",
         type: "K8s::Apps::Deployment",
-        changes: [{ path: "spec.replicas", kind: "changed", declared: 5, live: 9 }],
+        changes: [{ path: "spec.replicas", kind: "changed", declared: 5, live: 9, owner: "kubectl-client-side-apply" }],
       },
     ]);
 
+    // The accepted HPA replicas and sidecar are held back, not hidden.
     expect(result.accepted).toEqual([
       {
         name: "web",
         type: "K8s::Apps::Deployment",
-        changes: [{ path: "metadata.annotations.build-id", kind: "changed", declared: "42", live: "43", baseline: "43" }],
+        changes: [
+          { path: "metadata.annotations.build-id", kind: "changed", declared: "42", live: "43", baseline: "43", owner: "chant:web" },
+          { path: "spec.replicas", kind: "undeclared", live: 7, baseline: 7, owner: "kube-controller-manager" },
+          { path: "spec.template.spec.containers[#istio-proxy].image", kind: "undeclared", live: "istio/proxyv2:1.20", baseline: "istio/proxyv2:1.20" },
+          { path: "spec.template.spec.containers[#istio-proxy].name", kind: "undeclared", live: "istio-proxy", baseline: "istio-proxy" },
+        ],
       },
     ]);
 
-    // The HPA-owned replicas and the Istio sidecar never appear at all — not
-    // as drift, not as "undeclared" noise. Pruned before the diff ever runs.
-    const webDriftPaths = result.drifted.find((d) => d.name === "web")?.changes.map((c) => c.path) ?? [];
-    expect(webDriftPaths).not.toContain("spec.replicas");
-    expect(JSON.stringify(result)).not.toContain("istio-proxy");
+    // The Deployment controller's revision counter never appears at all — not
+    // as drift, not as accepted. Subtracted by the static allowlist.
+    expect(JSON.stringify(result)).not.toContain("deployment.kubernetes.io/revision");
 
     expect(result.unobserved).toEqual([
       { name: "broken", type: "K8s::Apps::Deployment", reason: "read-failed", detail: expect.stringContaining("500") },
@@ -676,16 +739,57 @@ describe("end to end: managed-fields-derived drift (#1076)", () => {
     ]);
   });
 
-  test("without the baseline the annotation is drift too; accepting it is what silences it", async () => {
+  test("without the baseline every foreign-owned undeclared field is drift too; accepting is what silences it", async () => {
     const live = normalizeDeepObservation(
       await observeResourcesDeepK8s({ environment: "prod", entityNames: [...declared.keys()], entities: declared }, cluster().connector),
     );
     const result = diffDeepObservation(declared, live, k8sDeepNormalizationHooks);
     const web = result.drifted.find((d) => d.name === "web");
-    expect(web?.changes.map((c) => c.path).sort()).toEqual(["metadata.annotations.build-id", "metadata.labels.tier"]);
+    expect(web?.changes.map((c) => c.path).sort()).toEqual([
+      "metadata.annotations.build-id",
+      "metadata.labels.team",
+      "metadata.labels.tier",
+      "spec.replicas",
+      "spec.template.spec.containers[#istio-proxy].image",
+      "spec.template.spec.containers[#istio-proxy].name",
+    ]);
     expect(result.accepted).toEqual([]);
   });
 
+  test("the same out-of-band label in the accepted baseline is not drift, at that value (#1191)", async () => {
+    const live = normalizeDeepObservation(
+      await observeResourcesDeepK8s({ environment: "prod", entityNames: [...declared.keys()], entities: declared }, cluster().connector),
+    );
+    const withTeam = {
+      web: { ...baseline.web, accepted: [...baseline.web.accepted, { path: "metadata.labels.team", value: "platform" }] },
+    };
+    const result = diffDeepObservation(declared, live, k8sDeepNormalizationHooks, withTeam);
+    const web = result.drifted.find((d) => d.name === "web");
+    expect(web?.changes).toEqual([
+      { path: "metadata.labels.tier", kind: "changed", declared: "backend", live: "frontend", owner: "chant:web" },
+    ]);
+    expect(result.accepted.find((d) => d.name === "web")?.changes).toContainEqual({
+      path: "metadata.labels.team",
+      kind: "undeclared",
+      live: "platform",
+      baseline: "platform",
+      owner: "kubectl-edit",
+    });
+
+    // Value-bound: accepting `team=platform` does not bless `team=security`.
+    const moved = {
+      web: { ...baseline.web, accepted: [...baseline.web.accepted, { path: "metadata.labels.team", value: "security" }] },
+    };
+    const movedResult = diffDeepObservation(declared, live, k8sDeepNormalizationHooks, moved);
+    expect(movedResult.drifted.find((d) => d.name === "web")?.changes).toContainEqual({
+      path: "metadata.labels.team",
+      kind: "undeclared",
+      live: "platform",
+      baseline: "security",
+      owner: "kubectl-edit",
+    });
+  });
+
   test("a whole-lexicon failure (no client) is a hole for every declared entity, never a clean report", async () => {
     // The reader's contract (matching describe-resources.ts) is to *throw* for
     // an unrecognized connect failure, not to catch it — core's own
@@ -711,11 +815,12 @@ describe("end to end: managed-fields-derived drift (#1076)", () => {
 });
 
 /**
- * The managed-fields-specific case named in #1076's acceptance: the same
- * live mutation on the same field is drift when chant owns it, and silence
- * when a controller owns it and source is silent.
+ * The managed-fields case named in #1076's acceptance, re-decided by #1191:
+ * the same live mutation on the same field is `changed` when chant owns it
+ * and source declares it, and `undeclared` when a controller owns it and
+ * source is silent. Ownership names the writer; it no longer silences.
  */
-describe("the managed-fields twist: ownership decides drift vs silence for the same mutation (#1076)", () => {
+describe("the managed-fields twist: ownership names the writer, the declared tree decides the kind (#1076, #1191)", () => {
   const liveWith = (owner: "chant" | "controller") => ({
     apiVersion: "apps/v1",
     kind: "Deployment",
@@ -768,15 +873,26 @@ describe("the managed-fields twist: ownership decides drift vs silence for the s
     ]);
   });
 
-  test("a controller owns the field and source is silent: the same mutated value is silence, not drift and not undeclared noise", async () => {
+  test("a controller owns the field and source is silent: the same mutated value is undeclared drift until accepted (#1191)", async () => {
     const cluster = fakeCluster({ objects: { [objectKey("apps/v1", "Deployment", "app", "prod")]: liveWith("controller") } });
     const entities = declaredWith(false);
     const live = normalizeDeepObservation(
       await observeResourcesDeepK8s({ environment: "prod", entityNames: ["app"], entities }, cluster.connector),
     );
     const result = diffDeepObservation(entities, live, k8sDeepNormalizationHooks);
-    expect(result.drifted).toEqual([]);
-    expect(result.unchanged).toEqual(["app"]);
-    expect(JSON.stringify(result)).not.toContain("app:2.0");
+    expect(result.drifted).toEqual([
+      {
+        name: "app",
+        type: "K8s::Apps::Deployment",
+        changes: [{ path: "spec.template.spec.containers[#app].image", kind: "undeclared", live: "app:2.0" }],
+      },
+    ]);
+
+    const accepted = {
+      app: { accepted: [{ path: "spec.template.spec.containers[#app].image", value: "app:2.0" }] },
+    };
+    const quiet = diffDeepObservation(entities, live, k8sDeepNormalizationHooks, accepted);
+    expect(quiet.drifted).toEqual([]);
+    expect(quiet.accepted.map((d) => d.name)).toEqual(["app"]);
   });
 });

package/src/deep-observe.ts

@@ -7,8 +7,7 @@
  * rather than the hand-maintained `ignoreDifferences` list every Argo user
  * keeps.
  *
- * ## Why this is not "the AWS reader, with `kubectl get` instead of Cloud
- * Control"
+ * ## What managedFields decides, and what it does not
  *
  * AWS, Azure and Temporal's rows all prune by a **static, entityType-keyed**
  * table: an ARN always looks like an ARN, `provisioningState` is always
@@ -17,65 +16,43 @@
  * what `./deep-observe-hooks.ts`'s `k8sDeepNormalizationHooks` is, and it
  * covers Kubernetes' *equivalent* static noise (`status`,
  * `metadata.{uid,resourceVersion,generation,creationTimestamp}`, a handful of
- * server-defaulted pod-spec fields).
+ * server-defaulted pod-spec fields, and the annotations and labels
+ * Kubernetes' own controllers stamp on every object of a kind —
+ * `K8S_SYSTEM_METADATA_PRUNE_PATTERNS` in `@intentius/chant/managed-fields`).
  *
- * managedFields is not that kind of rule. Whether `spec.replicas` is noise on
- * *this* Deployment depends on whether *this* Deployment's
- * `metadata.managedFields` says a controller owns it — a fact that differs
- * between two Deployments of the same type, and that the declared tree never
- * carries at all (chant's source has no `managedFields` key to normalize).
- * `DeepNormalizationHooks.prune` cannot see the object it is walking, only a
- * path and a value, so this cannot be expressed as a fixed hook the way the
- * other three rows' entire contribution is. It has to be computed once per
- * resource, here, and layered on top of the static rules before the tree is
- * normalized.
+ * managedFields is a different kind of fact. Which manager owns
+ * `spec.replicas` on *this* Deployment differs between two Deployments of
+ * the same type, and the declared tree never carries it at all (chant's
+ * source has no `managedFields` key to normalize). It has to be resolved once
+ * per resource, here, against the object in hand.
  *
- * ## The contested-field rule, precisely
+ * Until chant #1191 that resolution *pruned*: a foreign-owned path nobody
+ * declared was dropped before the tree reached core, on the theory that it
+ * was controller noise. It silenced exactly the case the deep read exists
+ * for — `kubectl label deploy web team=platform` is foreign-owned
+ * (`kubectl-edit`) and undeclared, and never appeared in fieldDrift. The
+ * policy now (recorded on #1202) is:
  *
- * For every path on the live tree, three questions, each independent:
+ * 1. **Chant-owned** (`chant`, `chant:<stack>` — chant #1075, matched on the
+ *    family so a stack rename does not stop recognizing its own history) is
+ *    always diffable.
+ * 2. **Declared, whoever owns it live** (a contested field) is always
+ *    diffable: chant's source is a statement of intent independent of which
+ *    write currently holds the field, and a foreign write that overrides a
+ *    value chant's manifest asks for is the thing `lifecycle diff --live`
+ *    exists to surface. It reports as `changed`.
+ * 3. **Foreign-owned and undeclared** is reported as `undeclared` drift,
+ *    unless the accepted baseline already carries it at that value. The
+ *    baseline (`--update-baseline`) is the noise valve: an HPA that owns
+ *    `spec.replicas` on a Deployment whose source is silent about replicas
+ *    reports once, gets accepted, and stays quiet until the value moves.
  *
- * 1. **Does any chant field manager (`chant`, `chant:<stack>` — chant #1075,
- *    matched on the family so a stack rename does not stop recognizing its
- *    own history) own this path?** If so it is chant's business regardless of
- *    what else is true — always diffable, never pruned by this rule.
- * 2. **Does some *other* manager own this path, and chant does not?** That is
- *    controller-managed noise — HPA rewriting `spec.replicas`, a mutating
- *    webhook defaulting a field, `kubectl-client-side-apply` from a human
- *    operator — *provided* nobody declared it (next question). Prune it.
- * 3. **Does chant's own manifest *also* set this path?** — independent of
- *    who currently owns it live. This is the case the issue calls out by
- *    name: **a contested field chant declared is drift-relevant.** The
- *    reasoning: chant's source is a statement of intent regardless of
- *    whether a previous apply is what currently holds the field, and a
- *    foreign write that overrides a value chant's manifest asks for is
- *    exactly the thing `lifecycle diff --live` exists to surface — silencing
- *    it because *something else* currently owns the field would hide the one
- *    case where chant and the cluster disagree about a property chant is
- *    actively declaring. So: foreign-owned *and* declared is never pruned by
- *    this rule, whatever #2 would otherwise do.
- *
- * `counterpart: "unknown"` and why it does not help here: core's own
- * counterpart tri-state (`side === "live" && counterpart === "absent"`, what
- * {@link K8S_SERVICE_DEFAULTS} is gated on) answers "did the *declared tree*
- * carry this path at all" — which is exactly question 3, but it is computed
- * by *core*, from the raw declared and raw live trees, only on the **second**
- * normalization pass (`packages/core/src/lifecycle/deep-observe.ts`'s
- * `diffDeepObservation`). This reader's own call to
- * {@link normalizeDeepProperties} runs first, with no `counterpartPaths`
- * supplied — same as the other three rows — so `counterpart` is `"unknown"`
- * for every node here, and a rule gated on `"absent"` would never fire during
- * this read at all. That is fine for a table keyed only by entityType (AWS's
- * service defaults are subtracted on core's later pass, not this one), but it
- * is *not* fine for the managed-fields rule: if this reader left
- * `spec.replicas` in the tree waiting for core's second pass to prune it,
- * core would be normalizing with the *static* `k8sDeepNormalizationHooks`,
- * which has no managedFields for this object in hand either (this reader
- * already computed its ownership sets from data it read once and does not
- * return). So question 3 is answered **here**, directly against the declared
- * `props` this reader was handed — not via `counterpart` — and the result is
- * baked into what this reader returns: a foreign-owned, undeclared field is
- * gone from the tree before it ever reaches core, and a contested one is
- * still there for the ordinary declared-vs-live comparison to catch.
+ * So ownership decides nothing about *whether* a path is compared. What it
+ * contributes is `fieldOwners` (#1189): every reported drift names the
+ * manager that holds the field live, which is how an operator tells
+ * `hpa-controller` doing its job from somebody running `kubectl edit`. The
+ * only fields subtracted because a foreign manager wrote them are the
+ * well-known system ones on the static allowlist.
  *
  * ## Resolving a managedFields entry against a live array
  *
@@ -99,10 +76,8 @@
  * container that also sets no scalar sub-fields (unusual — a real apply
  * setting a container almost always sets `image`/`name` too) would not confer
  * ownership onto a sibling field nobody's `fieldsV1` entry lists explicitly.
- * That is the conservative direction: a path absent from every manager's
- * fields is treated as "no ownership information", which leaves it diffable
- * rather than silently pruned. Reported drift that turns out to be more
- * noise than expected is a tuning problem; drift silently dropped is not.
+ * A path absent from every manager's fields simply has no `owner` on its
+ * drift line; it is compared like any other.
  *
  * ## `buildOwnershipSets` lives in core now
  *
@@ -119,7 +94,6 @@
 
 import type { K8sObject } from "@intentius/chant-k8s-client";
 import type {
-  DeepNormalizationHooks,
   DeepObservationResult,
   DeepResourceObservation,
   UnobservedEntity,
@@ -127,7 +101,7 @@ import type {
 import { deepObservation, normalizeDeepProperties } from "@intentius/chant/deep-observation";
 import { unobservedAll } from "@intentius/chant/observation";
 import { hasOwnershipMarker, LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
-import { buildOwnershipSets, pruneByOwnership, type OwnershipSets } from "@intentius/chant/managed-fields";
+import { buildOwnershipSets, type OwnershipSets } from "@intentius/chant/managed-fields";
 import { defaultK8sConnector, type K8sConnector } from "./api/connect";
 import {
   classifyApiFailure,
@@ -158,21 +132,6 @@ export interface K8sDeepObserveOptions {
   cwd?: string;
 }
 
-/**
- * The managed-fields prune, composed with the static rules, for one
- * resource's normalization call. See the module doc for the three-question
- * rule this encodes (`@intentius/chant/managed-fields`'s `pruneByOwnership`).
- */
-function perResourceHooks(sets: OwnershipSets): DeepNormalizationHooks {
-  return {
-    prune(node) {
-      if (k8sDeepNormalizationHooks.prune?.(node)) return true;
-      return pruneByOwnership(node, sets);
-    },
-    orderKey: k8sDeepNormalizationHooks.orderKey,
-  };
-}
-
 /** The live object minus the envelope fields that live outside `properties` on {@link DeepResourceObservation} (mirrors `type`/`physicalId`). */
 function propertiesTreeOf(obj: K8sObject): Record<string, unknown> {
   const { apiVersion: _apiVersion, kind: _kind, ...rest } = obj;
@@ -282,14 +241,13 @@ export async function observeResourcesDeepK8s(
         properties: normalizeDeepProperties(liveRoot, {
           entityType,
           side: "live",
-          hooks: perResourceHooks(sets),
+          hooks: k8sDeepNormalizationHooks,
         }),
-        // 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`.
+        // Who owns each path (#1189). Nothing is pruned by ownership any more
+        // (#1191), so a foreign-owned undeclared field reaches the diff as
+        // `undeclared` — and naming the manager is the whole question there:
+        // 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) {