@intentius/chant-lexicon-k8s 0.57.0 → 0.58.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-k8s",
-  "version": "0.57.0",
+  "version": "0.58.0",
   "description": "Kubernetes lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -76,7 +76,7 @@
     "@types/js-yaml": "^4.0.9"
   },
   "optionalDependencies": {
-    "@intentius/chant-k8s-client": "^0.57.0"
+    "@intentius/chant-k8s-client": "^0.58.0"
   },
   "devDependencies": {
     "@intentius/chant": "*",
@@ -84,7 +84,7 @@
   },
   "peerDependencies": {
     "zod": "^4.3.6",
-    "@intentius/chant": "^0.57.0",
+    "@intentius/chant": "^0.58.0",
     "typescript": "^5.9.3"
   }
 }

package/src/api/sweep-types.ts

@@ -10,8 +10,7 @@
  *
  * It lives in its own module, with no imports of its own, because both
  * consumers reach it from different directions — `../export-resources.ts`
- * pulls in the whole import parser, and a Temporal worker loading the apply
- * activity should not.
+ * pulls in the whole import parser, and the apply activity should not.
  */
 export const DEFAULT_IMPORT_TYPES: readonly string[] = [
   "K8s::Apps::Deployment",

package/src/composites/composites.test.ts

@@ -3868,7 +3868,7 @@ describe("OperatorStack", () => {
     }
   });
 
-  test("observe-dial ConvergeOp with a mutating dispatch target still gets read-only RBAC — observe never dispatches, per TMP014/convergeTick", () => {
+  test("observe-dial ConvergeOp with a mutating dispatch target still gets read-only RBAC — observe never dispatches, per OPS014/convergeTick", () => {
     const result: any = OperatorStack({
       name: "chant-operator",
       image: "chant:latest",
@@ -3880,7 +3880,7 @@ describe("OperatorStack", () => {
     }
   });
 
-  test("reconcile-dial ConvergeOp with a mutating dispatch target still gets read-only RBAC — TMP014 only lets apply free-run a mutating dispatch", () => {
+  test("reconcile-dial ConvergeOp with a mutating dispatch target still gets read-only RBAC — OPS014 only lets apply free-run a mutating dispatch", () => {
     const result: any = OperatorStack({
       name: "chant-operator",
       image: "chant:latest",
@@ -3979,6 +3979,17 @@ describe("OperatorStack", () => {
     expect(() => deriveHostVerbClass("x", "observe", [DESTRUCTIVE_OP])).toThrow(/destructive/);
   });
 
+  // #2192 — the refusal cites the rule that actually owns it (OPS014), and
+  // gives OPS014's own reason. The old message argued from the local
+  // executor's inability to honour a gate, which #2119 retired: a gated op
+  // now ends the run `gated` rather than being refused, so the refusal stands
+  // on the unattended-approval ground instead.
+  test("deriveHostVerbClass: the destructive refusal names OPS014 and the unattended-approval reason", () => {
+    expect(() => deriveHostVerbClass("x", "apply", [DESTRUCTIVE_OP])).toThrow(/OPS014/);
+    expect(() => deriveHostVerbClass("x", "apply", [DESTRUCTIVE_OP])).toThrow(/unattended/);
+    expect(() => deriveHostVerbClass("x", "apply", [DESTRUCTIVE_OP])).not.toThrow(/TMP014/);
+  });
+
   // ── Build-time refusals ──────────────────────────────────────────────
 
   test("refuses an empty converge array", () => {

package/src/composites/operator-stack.ts

@@ -16,39 +16,40 @@
  * (lease fencing, `chant operator status`, durable gate-as-fact semantics).
  * `OperatorStack`'s container command is deliberately `chant run <name>`,
  * the one-shot local tick `ConvergeOp` (#1484) already ships and tests
- * against (`lexicons/temporal/src/composites/converge-op.ts`'s own doc:
+ * against (`packages/core/src/op/composites/converge-op.ts`'s own doc:
  * "one-shot runnable locally for a single tick"). When #1485 lands, a
  * caller can override `command` to shell out to `chant operator tick`
  * instead — this composite doesn't need to change for that; only the
  * command a caller passes does.
  *
  * `concurrencyPolicy: "Forbid"` is the k8s-native analogue of
- * `ConvergeOp`'s own Temporal schedule `overlap: "Skip"` policy — never
- * queue a second tick behind one still running.
+ * `ConvergeOp`'s own `schedule.overlap: "skip"` policy — never queue a
+ * second tick behind one still running.
  *
  * ## RBAC derivation
  *
  * `ConvergeOp` adds no authority an environment did not already grant
  * (#1484's Autonomy table). `OperatorStack` re-derives the same bound at the
- * k8s RBAC layer, independently of the temporal lexicon (this module has no
- * dependency on it — see the layering note below): for each hosted
+ * k8s RBAC layer, from the Op configs alone (see the Layering note below for
+ * what this module imports and what it restates): for each hosted
  * ConvergeOp, walk its `dispatchTargets` (the OpConfigs its rule table's
  * `run()` actions may name) through `classifyOpVerbClass`
  * (`packages/core/src/op/op-verb-class.ts`, #1954), then keep only the
  * highest verb class this host's `dial` could ever actually free-run —
  * exactly `convergeTick`'s own `verbClassAllowedToDispatch` gate and
- * `TMP014`'s build-time refusal, restated as an RBAC ceiling:
+ * `OPS014`'s build-time refusal, restated as an RBAC ceiling:
  *
  * - `dial: "observe"` never dispatches (report-only) → read-only RBAC,
  *   regardless of what the rule table's targets could otherwise do.
- * - `dial: "reconcile"` only free-runs a read-only target (TMP014 refuses a
+ * - `dial: "reconcile"` only free-runs a read-only target (OPS014 refuses a
  *   mutating dispatch under reconcile in v1) → read-only RBAC.
  * - `dial: "apply"` free-runs read-only and mutating targets → RBAC gains
  *   create/update/patch, never delete.
  * - A `dispatchTargets` entry that itself classifies `destructive` is
- *   refused outright, at construction — TMP014 already refuses a
- *   destructive `run()` target under any dial in v1 (the local dispatch
- *   executor can't honor its required gate), so a `destructive` target
+ *   refused outright, at construction — OPS014 already refuses a
+ *   destructive `run()` target under any dial in v1 (a converge tick runs
+ *   unattended, and a destructive dispatch needs a person's approval before
+ *   it is attempted, not a gate read after the fact), so a `destructive` target
  *   reaching this composite is either a config bypassing that build check
  *   or a target `OperatorStack` should never grant permission toward.
  *   `never delete`, unconditionally, in v1 — no verb class here ever grants
@@ -61,11 +62,11 @@
  *
  * ## Layering
  *
- * `lexicons/k8s` has no workspace dependency on `lexicons/temporal` (nor
- * the reverse — see both packages' `package.json`), so this module doesn't
- * import `ConvergeOpConfig`/`ConvergeRule` types. `OperatorStackConvergeHost`
- * restates the handful of `ConvergeOp` fields this composite actually needs
- * (`name`, `schedule`, `env`, `dial`) structurally; `dispatchTargets` takes
+ * `OperatorStackConvergeHost` restates the handful of `ConvergeOp` fields
+ * this composite actually needs (`name`, `schedule`, `env`, `dial`)
+ * structurally rather than importing `ConvergeOpConfig`: the CronJob is
+ * built from a host description, not from an Op config, and a caller that
+ * has neither should still be able to describe one. `dispatchTargets` takes
  * plain `OpConfig`-shaped values from `@intentius/chant/op` (a dependency
  * this lexicon already has via the `@intentius/chant` peer dependency),
  * the same type `classifyOpVerbClass` itself takes.
@@ -80,7 +81,7 @@ import { Namespace, CronJob, ServiceAccount, Role, RoleBinding } from "../genera
 
 /**
  * Mirrors `ConvergeOp`'s own `ConvergeDial`
- * (`lexicons/temporal/src/composites/converge-op.ts`) structurally — see
+ * (`packages/core/src/op/composites/converge-op.ts`) structurally — see
  * this module's Layering doc for why it's restated rather than imported.
  */
 export type OperatorDial = "observe" | "reconcile" | "apply";
@@ -104,7 +105,7 @@ export interface OperatorStackConvergeHost {
   /**
    * OpConfigs for every op this ConvergeOp's rule table may `run()` — the
    * sibling `*.op.ts` declarations its `run()` actions name. Used to derive
-   * least-privilege RBAC the same way `TMP014` derives its build-time
+   * least-privilege RBAC the same way `OPS014` derives its build-time
    * refusals. Omit or leave empty when every rule only `report()`s; the
    * host still gets read-only RBAC for its own observation.
    */
@@ -183,7 +184,7 @@ function rbacVerbsFor(verbClass: OpVerbClass): string[] {
 /**
  * Whether `dial` ever actually free-runs a dispatch classified `verbClass` —
  * restates `convergeTick`'s own `verbClassAllowedToDispatch`
- * (`lexicons/temporal/src/op/activities/converge.ts`) so the RBAC ceiling
+ * (`packages/core/src/op/activities/converge.ts`) so the RBAC ceiling
  * this composite grants matches the ceiling the tick itself enforces at
  * runtime, without importing across the lexicon boundary (see this module's
  * Layering doc).
@@ -198,7 +199,7 @@ function dialAllowsVerbClass(dial: OperatorDial, verbClass: OpVerbClass): boolea
  * Derive the highest verb class a host's ServiceAccount actually needs:
  * the max, across `dispatchTargets`, of each target's own class — but only
  * counting a target `dial` could ever actually dispatch (one it can't just
- * gets reported, per `TMP014`/`convergeTick`, and needs no elevated grant).
+ * gets reported, per `OPS014`/`convergeTick`, and needs no elevated grant).
  * A `dispatchTargets` entry that classifies `destructive` is refused
  * outright rather than silently ignored — see this module's RBAC
  * derivation doc on why a destructive target reaching this composite is
@@ -211,7 +212,8 @@ export function deriveHostVerbClass(hostName: string, dial: OperatorDial, dispat
     if (verbClass === "destructive") {
       throw new Error(
         `OperatorStack host "${hostName}": a dispatchTargets entry classifies as destructive — ConvergeOp v1 refuses a destructive run() target under any dial ` +
-          `(TMP014; the local dispatch executor can't honor its required gate). Remove it from dispatchTargets, or remediate manually via a gated op.`,
+          `(OPS014; a converge tick runs unattended, and a destructive dispatch needs a person's approval before it is attempted, not a gate the tick reads after it has already committed to the run). ` +
+          `Remove it from dispatchTargets, and run the destructive op yourself through its gate.`,
       );
     }
     if (!dialAllowsVerbClass(dial, verbClass)) continue; // dial refuses this dispatch — reported, not run; needs no elevated RBAC

package/src/config.ts

@@ -2,8 +2,8 @@
  * K8s environment → cluster binding — chant #1100.
  *
  * Every cloud lexicon binds an environment to a scope: AWS resolves `<env>`
- * to a CloudFormation stack, Azure treats `<env>` as the resource group,
- * Temporal looks up `temporal.profiles.<env>`. Before this, k8s bound
+ * to a CloudFormation stack, Azure treats `<env>` as the resource group.
+ * Before this, k8s bound
  * nothing — `describeResources` shelled out to `kubectl get` with no
  * `--context`, so `chant lifecycle diff prod --live` read whichever cluster
  * `kubectl config current-context` happened to point at.
@@ -40,8 +40,8 @@
  *   and the missing binding.
  *
  * `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`). The type side is the declaration
+ * accepted at runtime without core changes, exactly like the `terraform` key
+ * (see `lexicons/terraform/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

package/src/crd/crd-sources.ts

@@ -26,7 +26,7 @@ const KUBERAY_CRD_BASE = `https://raw.githubusercontent.com/ray-project/kuberay/
  * Argo CD CRDs — argoproj.io/v1alpha1
  *
  * Produces (the `argoproj.io` group is mapped to the `Argo` namespace —
- * see GROUP_NAMESPACE_OVERRIDES in crd/parser.ts):
+ * see GROUP_NAMESPACE_OVERRIDES in group-namespace.ts):
  *   K8s::Argo::Application     → apiVersion: argoproj.io/v1alpha1, kind: Application
  *   K8s::Argo::ApplicationSet  → apiVersion: argoproj.io/v1alpha1, kind: ApplicationSet
  *   K8s::Argo::AppProject      → apiVersion: argoproj.io/v1alpha1, kind: AppProject
@@ -221,7 +221,7 @@ const PROM_OPERATOR_CRD_BASE = `https://raw.githubusercontent.com/prometheus-ope
  * also carries `ExternalArtifact` and `ArtifactGenerator` (experimental, and a
  * separate `source.extensions.fluxcd.io` group), which are intentionally left
  * out. All groups map to the `Flux` namespace (see GROUP_NAMESPACE_OVERRIDES in
- * crd/parser.ts):
+ * group-namespace.ts):
  *   K8s::Flux::GitRepository / OCIRepository / HelmRepository / HelmChart / Bucket
  *                                          → source.toolkit.fluxcd.io/v1
  *   K8s::Flux::Kustomization               → kustomize.toolkit.fluxcd.io/v1
@@ -259,7 +259,7 @@ const FLUX_OPERATOR_INSTALL = `https://github.com/controlplaneio-fluxcd/flux-ope
  * KubeMicroVM CRDs — lambda.aws.amazon.com/v1alpha1
  *
  * Produces (the group is mapped to the `KubeMicroVM` namespace — see
- * GROUP_NAMESPACE_OVERRIDES in crd/parser.ts):
+ * GROUP_NAMESPACE_OVERRIDES in group-namespace.ts):
  *   K8s::KubeMicroVM::MicroVM            → kind: MicroVM
  *   K8s::KubeMicroVM::MicroVMImage       → kind: MicroVMImage
  *   K8s::KubeMicroVM::MicroVMNetwork     → kind: MicroVMNetwork
@@ -287,7 +287,7 @@ const KUBEMICROVM_VERSION = "1.0.11";
  * k3s estate's GitOps surface is written in.
  *
  * Produces (both groups map to the `K3s` namespace — see
- * GROUP_NAMESPACE_OVERRIDES in crd/parser.ts):
+ * GROUP_NAMESPACE_OVERRIDES in group-namespace.ts):
  *   K8s::K3s::HelmChart        → apiVersion: helm.cattle.io/v1, kind: HelmChart
  *   K8s::K3s::HelmChartConfig  → apiVersion: helm.cattle.io/v1, kind: HelmChartConfig
  *   K8s::K3s::Addon            → apiVersion: k3s.cattle.io/v1,  kind: Addon

package/src/deep-observe-hooks.ts

@@ -61,7 +61,8 @@ import { GENERATED_ONCE_LABEL_KEY } from "./secret-labels";
  * Kubernetes-defaulted fields, per entity type, as index-erased property
  * paths. Subtracted only where source never declared the property
  * (`side === "live" && counterpart === "absent"`) — cdk-real-drift's default
- * subtraction, same convention as AWS/Azure/Temporal's tables.
+ * subtraction, same convention as the AWS and Azure tables
+ * (`AWS_SERVICE_DEFAULTS`, `AZURE_SERVICE_DEFAULTS`).
  *
  * Sparse and evidence-based rather than derived from the generated schema:
  * the k8s OpenAPI spec this lexicon's codegen consumes
@@ -70,9 +71,8 @@ import { GENERATED_ONCE_LABEL_KEY } from "./secret-labels";
  * actually expressible today. Widening this table is additive and needs no
  * contract change.
  *
- * `spec.strategy` is listed whole, not as `spec.strategy.type`, for the same
- * reason Temporal's `TEMPORAL_SCHEDULE_DEFAULTS` lists `state` whole: pruning
- * only the leaf would still recurse into the object, and a nested default the
+ * `spec.strategy` is listed whole rather than as `spec.strategy.type`, because
+ * pruning only the leaf would still recurse into the object, and a nested default the
  * table does not separately name (`rollingUpdate.maxSurge`/`maxUnavailable`,
  * both `"25%"` when `spec.strategy` is omitted entirely) would leave behind an
  * empty `strategy: {}` — a value distinct from no `strategy` key at all, and

package/src/deep-observe.test.ts

@@ -36,6 +36,7 @@ const { statusBody } = await import("@intentius/chant-k8s-client/testing");
 const { isChantFieldManager } = await import("@intentius/chant-k8s-client");
 const { diffDeepObservation, observeDeep } = await import("@intentius/chant/lifecycle/deep-observe");
 const { normalizeDeepObservation, normalizeDeepProperties } = await import("@intentius/chant/deep-observation");
+const { heldElsewhere } = await import("@intentius/chant/held-elsewhere");
 
 type Entity = { name: string; entityType: string; props: Record<string, unknown> };
 function makeEntities(records: Entity[]): Map<string, { entityType: string; props: Record<string, unknown> }> {
@@ -687,19 +688,20 @@ describe("end to end: managed-fields-derived drift (#1076)", () => {
     },
   };
 
-  test("genuine, undeclared and contested drift surface; accepted deviations and controller-stamped metadata do not", async () => {
+  test("contested drift surfaces; fields nobody declared are unclaimed and accepted deviations are held back", async () => {
     const live = normalizeDeepObservation(
       await observeResourcesDeepK8s({ environment: "prod", entityNames: [...declared.keys()], entities: declared }, cluster().connector),
     );
     const result = diffDeepObservation(declared, live, k8sDeepNormalizationHooks, baseline);
 
+    // Only a path chant's source declares can be drift (#2160). `tier` is
+    // declared and holds a different value live, which is the whole point of
+    // the contested case: a foreign write over a field chant asks for.
     expect(result.drifted).toEqual([
       {
         name: "web",
         type: "K8s::Apps::Deployment",
         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" },
         ],
       },
@@ -710,16 +712,39 @@ describe("end to end: managed-fields-derived drift (#1076)", () => {
       },
     ]);
 
-    // The accepted HPA replicas and sidecar are held back, not hidden.
+    // Everything source never set, with the manager where managedFields has one
+    // and the claim where it does not. The `team` label needs no baseline entry
+    // to stay quiet now, and `kubectl-edit` still says who put it there.
+    expect(result.unclaimed).toEqual([
+      {
+        name: "web",
+        type: "K8s::Apps::Deployment",
+        fields: [
+          { path: "metadata.labels.team", live: "platform", heldBy: "kubectl-edit", source: "field-manager" },
+          { path: "spec.replicas", live: 7, heldBy: "kube-controller-manager", source: "field-manager", baseline: 7 },
+          {
+            path: "spec.template.spec.containers[#istio-proxy].image",
+            live: "istio/proxyv2:1.20",
+            source: "claimed-fields",
+            baseline: "istio/proxyv2:1.20",
+          },
+          {
+            path: "spec.template.spec.containers[#istio-proxy].name",
+            live: "istio-proxy",
+            source: "claimed-fields",
+            baseline: "istio-proxy",
+          },
+        ],
+      },
+    ]);
+
+    // The accepted build-id is 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", 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" },
         ],
       },
     ]);
@@ -739,7 +764,10 @@ describe("end to end: managed-fields-derived drift (#1076)", () => {
     ]);
   });
 
-  test("without the baseline every foreign-owned undeclared field is drift too; accepting is what silences it", async () => {
+  test("without the baseline only the declared paths are drift; the rest are still unclaimed", async () => {
+    // The baseline was the noise valve before #2160. It is no longer load
+    // bearing for a field nobody declared: the claim answers first, so an HPA's
+    // replica count and an injected sidecar are quiet with no baseline at all.
     const live = normalizeDeepObservation(
       await observeResourcesDeepK8s({ environment: "prod", entityNames: [...declared.keys()], entities: declared }, cluster().connector),
     );
@@ -747,8 +775,10 @@ describe("end to end: managed-fields-derived drift (#1076)", () => {
     const web = result.drifted.find((d) => d.name === "web");
     expect(web?.changes.map((c) => c.path).sort()).toEqual([
       "metadata.annotations.build-id",
-      "metadata.labels.team",
       "metadata.labels.tier",
+    ]);
+    expect(result.unclaimed.find((d) => d.name === "web")?.fields.map((f) => f.path)).toEqual([
+      "metadata.labels.team",
       "spec.replicas",
       "spec.template.spec.containers[#istio-proxy].image",
       "spec.template.spec.containers[#istio-proxy].name",
@@ -756,38 +786,40 @@ describe("end to end: managed-fields-derived drift (#1076)", () => {
     expect(result.accepted).toEqual([]);
   });
 
-  test("the same out-of-band label in the accepted baseline is not drift, at that value (#1191)", async () => {
+  test("managedFields names the manager where it has one, and the claim answers where it does not (#2160)", async () => {
+    // The k8s row is the only substrate where both sources are available, so
+    // it is the one place the fallback can be tested against real data. The
+    // `team` label has a managedFields entry addressed by a plain path, so the
+    // API server answers. The injected sidecar's fields are inside a list the
+    // diff addresses by key (`[#istio-proxy]`), which no managedFields entry
+    // names in that form, so the claimed-field set answers instead.
     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({
+    const result = diffDeepObservation(declared, live, k8sDeepNormalizationHooks);
+    const web = result.unclaimed.find((d) => d.name === "web");
+
+    const byManager = web?.fields.find((f) => f.path === "metadata.labels.team");
+    expect(byManager).toEqual({
       path: "metadata.labels.team",
-      kind: "undeclared",
       live: "platform",
-      baseline: "platform",
-      owner: "kubectl-edit",
+      heldBy: "kubectl-edit",
+      source: "field-manager",
     });
 
-    // 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",
+    const byClaim = web?.fields.find((f) => f.path === "spec.template.spec.containers[#istio-proxy].image");
+    expect(byClaim).toEqual({
+      path: "spec.template.spec.containers[#istio-proxy].image",
+      live: "istio/proxyv2:1.20",
+      source: "claimed-fields",
     });
+    expect(byClaim).not.toHaveProperty("heldBy");
+
+    // Both sources agree on the verdict; they differ only in how much they can
+    // say about it. Neither is drift, and neither is proposed for update.
+    expect(result.drifted.find((d) => d.name === "web")?.changes.map((c) => c.path)).not.toContain(
+      "metadata.labels.team",
+    );
   });
 
   test("a whole-lexicon failure (no client) is a hole for every declared entity, never a clean report", async () => {
@@ -814,6 +846,142 @@ describe("end to end: managed-fields-derived drift (#1076)", () => {
   });
 });
 
+/**
+ * #2162's honest example, driven through the real reader and core's real
+ * `diffDeepObservation` the same way the "end to end" suite above does — the
+ * declared alternative to the `accepted` baseline dance that suite's own
+ * `web` fixture needs for the very same field: an HPA owns `spec.replicas`
+ * on a Deployment source never sets a literal value for. Before this, the
+ * only way to stop hearing about it was `--update-baseline`, and a later
+ * scale event (7 -> 12) reported as drift again the moment the accepted
+ * value moved. `heldElsewhere()` needs no baseline entry at all, and does
+ * not re-alert when the HPA changes its mind.
+ */
+describe("heldElsewhere(): the HPA/replicas case without a baseline entry (#2162)", () => {
+  const declared = makeEntities([
+    {
+      name: "web",
+      entityType: "K8s::Apps::Deployment",
+      props: {
+        metadata: { name: "web", namespace: "prod", labels: { app: "web" } },
+        spec: {
+          replicas: heldElsewhere<number>({ by: "hpa", reason: "the autoscaler owns replicas after the first apply" }),
+          selector: { matchLabels: { app: "web" } },
+          template: { metadata: { labels: { app: "web" } }, spec: { containers: [{ name: "app", image: "web:1.0" }] } },
+        },
+      },
+    },
+  ]);
+
+  const webLiveAt = (replicas: number) => ({
+    apiVersion: "apps/v1",
+    kind: "Deployment",
+    metadata: {
+      name: "web",
+      namespace: "prod",
+      uid: "uid-web",
+      labels: { app: "web" },
+      managedFields: [
+        {
+          manager: "chant:web",
+          operation: "Apply",
+          apiVersion: "apps/v1",
+          fieldsV1: {
+            "f:metadata": { "f:labels": { "f:app": {} } },
+            "f:spec": {
+              "f:selector": {},
+              "f:template": {
+                "f:spec": { "f:containers": { 'k:{"name":"app"}': { ".": {}, "f:name": {}, "f:image": {} } } },
+              },
+            },
+          },
+        },
+        {
+          // The autoscaler: chant's own manifest never mentions `replicas`,
+          // so nothing here contests it — the HPA is the only writer.
+          manager: "kube-controller-manager",
+          operation: "Update",
+          apiVersion: "apps/v1",
+          fieldsV1: { "f:spec": { "f:replicas": {} } },
+        },
+      ],
+    },
+    spec: {
+      replicas,
+      selector: { matchLabels: { app: "web" } },
+      template: { metadata: { labels: { app: "web" } }, spec: { containers: [{ name: "app", image: "web:1.0" }] } },
+    },
+  });
+
+  const clusterAt = (replicas: number) =>
+    fakeCluster({ objects: { [objectKey("apps/v1", "Deployment", "web", "prod")]: webLiveAt(replicas) } });
+
+  test("reports held with the HPA as owner — no drift, no baseline entry needed", async () => {
+    const live = normalizeDeepObservation(
+      await observeResourcesDeepK8s({ environment: "prod", entityNames: [...declared.keys()], entities: declared }, clusterAt(7).connector),
+    );
+    const result = diffDeepObservation(declared, live, k8sDeepNormalizationHooks);
+
+    expect(result.drifted).toEqual([]);
+    expect(result.accepted).toEqual([]);
+    expect(result.held).toEqual([
+      {
+        name: "web",
+        type: "K8s::Apps::Deployment",
+        held: [
+          {
+            path: "spec.replicas",
+            by: "hpa",
+            reason: "the autoscaler owns replicas after the first apply",
+            live: 7,
+            suspicious: false,
+            owner: "kube-controller-manager",
+          },
+        ],
+      },
+    ]);
+  });
+
+  test("a later scale event does not re-alert — unlike the accepted baseline, held is not value-bound", async () => {
+    const live = normalizeDeepObservation(
+      await observeResourcesDeepK8s({ environment: "prod", entityNames: [...declared.keys()], entities: declared }, clusterAt(12).connector),
+    );
+    const result = diffDeepObservation(declared, live, k8sDeepNormalizationHooks);
+
+    expect(result.drifted).toEqual([]);
+    expect(result.held[0].held[0]).toMatchObject({ live: 12, suspicious: false });
+  });
+
+  test("no live value at all is suspicious — the declared hand-over never showed up", async () => {
+    // No managedFields entry for replicas, and the live object carries none
+    // either — a Deployment where the HPA was never actually wired up.
+    const neverScaled = {
+      apiVersion: "apps/v1",
+      kind: "Deployment",
+      metadata: { name: "web", namespace: "prod", uid: "uid-web", labels: { app: "web" } },
+      spec: {
+        selector: { matchLabels: { app: "web" } },
+        template: { metadata: { labels: { app: "web" } }, spec: { containers: [{ name: "app", image: "web:1.0" }] } },
+      },
+    };
+    const live = normalizeDeepObservation(
+      await observeResourcesDeepK8s(
+        { environment: "prod", entityNames: [...declared.keys()], entities: declared },
+        fakeCluster({ objects: { [objectKey("apps/v1", "Deployment", "web", "prod")]: neverScaled } }).connector,
+      ),
+    );
+    const result = diffDeepObservation(declared, live, k8sDeepNormalizationHooks);
+
+    expect(result.held).toEqual([
+      {
+        name: "web",
+        type: "K8s::Apps::Deployment",
+        held: [{ path: "spec.replicas", by: "hpa", reason: "the autoscaler owns replicas after the first apply", suspicious: true }],
+      },
+    ]);
+  });
+});
+
 /**
  * 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
@@ -873,27 +1041,29 @@ describe("the managed-fields twist: ownership names the writer, the declared tre
     ]);
   });
 
-  test("a controller owns the field and source is silent: the same mutated value is undeclared drift until accepted (#1191)", async () => {
+  test("a controller owns the field and source is silent: the same mutated value is unclaimed, never drift (#2160)", async () => {
+    // The mirror of the test above, and the whole claim in one pair: the same
+    // live value, the same manager, and the declaration is what decides
+    // whether it is chant's problem.
     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.drifted).toEqual([]);
+    expect(result.unclaimed).toEqual([
       {
         name: "app",
         type: "K8s::Apps::Deployment",
-        changes: [{ path: "spec.template.spec.containers[#app].image", kind: "undeclared", live: "app:2.0" }],
+        fields: [
+          { path: "spec.template.spec.containers[#app].image", live: "app:2.0", source: "claimed-fields" },
+        ],
       },
     ]);
-
-    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"]);
+    // No baseline entry needed to silence it, which is what #1191's valve was
+    // being used for.
+    expect(result.unchanged).toEqual(["app"]);
   });
 });
 
@@ -954,9 +1124,12 @@ describe("secret masking — diff --live never holds a Secret data value (#1830,
     // MASTER_KEY is present on both sides: both values collapse to the mask,
     // so a value-only difference is NOT drift — that is the contract, chant
     // cannot know and must not learn whether the bytes moved.
-    expect(changes.map((c) => `${c.path}:${c.kind}`).sort()).toEqual([
-      "data.INJECTED_KEY:undeclared",
-      "data.PENDING_KEY:absent",
+    expect(changes.map((c) => `${c.path}:${c.kind}`).sort()).toEqual(["data.PENDING_KEY:absent"]);
+
+    // The injected key is a key source never declared, so it is unclaimed
+    // (#2160). Presence still classifies; the value is still the mask.
+    expect(result.unclaimed.find((d) => d.name === "master-key")?.fields).toEqual([
+      { path: "data.INJECTED_KEY", live: "[REDACTED]", source: "claimed-fields" },
     ]);
 
     // The hard line, asserted over the whole serialized result: no data