@intentius/chant-lexicon-k8s 0.41.20 → 0.44.1

package/src/crd/crd-sources.ts

@@ -277,6 +277,40 @@ const FLUX_OPERATOR_INSTALL = `https://github.com/controlplaneio-fluxcd/flux-ope
 const KUBEMICROVM_CHART = "oci://ghcr.io/codriverlabs/helm/kube-microvm-operator";
 const KUBEMICROVM_VERSION = "1.0.11";
 
+/**
+ * k3s bundled-controller CRDs — helm.cattle.io/v1 + k3s.cattle.io/v1
+ *
+ * k3s's manifest auto-deploy machinery speaks these CRDs: drop a HelmChart
+ * into /var/lib/rancher/k3s/server/manifests and the embedded helm-controller
+ * installs the chart; every auto-deployed manifest is tracked by an Addon.
+ * Typed here for the same reason the Flux toolkit kinds are — they are what a
+ * k3s estate's GitOps surface is written in.
+ *
+ * Produces (both groups map to the `K3s` namespace — see
+ * GROUP_NAMESPACE_OVERRIDES in crd/parser.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
+ *
+ * The pin is k3s v1.36.3+k3s1 (the release the k3s lexicon pins), but the k3s
+ * repo itself publishes no CRD YAMLs — its manifests/ directory carries only
+ * the bundled charts, and the API types live in dependency repos. The URLs
+ * below point at the exact versions that release vendors in its go.mod:
+ *   github.com/k3s-io/helm-controller v0.17.7  (helm.cattle.io CRDs)
+ *   github.com/k3s-io/api             v0.1.4   (k3s.cattle.io CRDs)
+ * When bumping, re-read go.mod at the new k3s tag and move both pins together.
+ *
+ * k3s-io/api also ships an ETCDSnapshotFile CRD — deliberately left out. It is
+ * status-only controller bookkeeping (the server writes them to describe
+ * snapshots it took); nothing an author would declare.
+ *
+ * Controller install: none — both controllers are embedded in the k3s binary.
+ */
+const K3S_HELM_CONTROLLER_VERSION = "v0.17.7"; // vendored by k3s v1.36.3+k3s1
+const K3S_API_VERSION = "v0.1.4"; // vendored by k3s v1.36.3+k3s1
+const K3S_HELM_CONTROLLER_CRD_BASE = `https://raw.githubusercontent.com/k3s-io/helm-controller/${K3S_HELM_CONTROLLER_VERSION}/pkg/crds/yaml/generated`;
+const K3S_API_CRD_BASE = `https://raw.githubusercontent.com/k3s-io/api/${K3S_API_VERSION}/pkg/crds/yaml/generated`;
+
 export const CRD_SOURCES: CRDSource[] = [
   { type: "url", url: `${KUBERAY_CRD_BASE}/ray.io_rayclusters.yaml` },
   { type: "url", url: `${KUBERAY_CRD_BASE}/ray.io_rayjobs.yaml` },
@@ -335,6 +369,9 @@ export const CRD_SOURCES: CRDSource[] = [
     url: FLUX_OPERATOR_INSTALL,
     kinds: ["FluxInstance", "FluxReport", "ResourceSet", "ResourceSetInputProvider"],
   },
+  { type: "url", url: `${K3S_HELM_CONTROLLER_CRD_BASE}/helm.cattle.io_helmcharts.yaml` },
+  { type: "url", url: `${K3S_HELM_CONTROLLER_CRD_BASE}/helm.cattle.io_helmchartconfigs.yaml` },
+  { type: "url", url: `${K3S_API_CRD_BASE}/k3s.cattle.io_addons.yaml` },
   {
     type: "helm",
     chart: KUBEMICROVM_CHART,

package/src/crd/parser.ts

@@ -52,6 +52,12 @@ const GROUP_NAMESPACE_OVERRIDES: Record<string, string> = {
   // 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",
+  // k3s's bundled controllers ship under two groups but are one thing to an
+  // author — the k3s auto-deploy surface. The first-segment rule would give
+  // `K8s::Helm::HelmChart`, which reads like it belongs to the helm lexicon,
+  // and would split HelmChart from the Addon that tracks its deployment.
+  "helm.cattle.io": "K3s",
+  "k3s.cattle.io": "K3s",
 };
 
 /**

package/src/deep-observe-hooks.ts

@@ -44,6 +44,7 @@
 import { createRequire } from "module";
 import type { DeepArrayElement, DeepNode, DeepNormalizationHooks } from "@intentius/chant/lexicon";
 import { K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS, k8sListMapOrderKey } from "@intentius/chant/managed-fields";
+import { LABEL_OWNERSHIP_KEYS, OWNERSHIP_MANAGED_BY_VALUE } from "@intentius/chant/ownership";
 
 // This module ships as ESM (tsx strips types from src/ directly), where a bare
 // `require` is not defined — the same reason serializer.ts and the LSP modules
@@ -86,13 +87,64 @@ export const K8S_SERVICE_DEFAULTS: Record<string, Record<string, unknown>> = {
     "spec.template.spec.restartPolicy": "Always",
     "spec.template.spec.terminationGracePeriodSeconds": 30,
     "spec.template.spec.schedulerName": "default-scheduler",
+    // Widened on the CC canonical estate (#1214): a container declaring an
+    // httpGet probe, a named port, or nothing about termination gets exactly
+    // these from the API server. SSA attributes a server-defaulted field to no
+    // manager, so the managed-fields prune deliberately leaves them diffable
+    // (see ./deep-observe.ts) — this table is where they subtract.
+    "spec.template.spec.containers[].livenessProbe.failureThreshold": 3,
+    "spec.template.spec.containers[].livenessProbe.periodSeconds": 10,
+    "spec.template.spec.containers[].livenessProbe.successThreshold": 1,
+    "spec.template.spec.containers[].livenessProbe.timeoutSeconds": 1,
+    "spec.template.spec.containers[].livenessProbe.httpGet.scheme": "HTTP",
+    "spec.template.spec.containers[].readinessProbe.failureThreshold": 3,
+    "spec.template.spec.containers[].readinessProbe.periodSeconds": 10,
+    "spec.template.spec.containers[].readinessProbe.successThreshold": 1,
+    "spec.template.spec.containers[].readinessProbe.timeoutSeconds": 1,
+    "spec.template.spec.containers[].readinessProbe.httpGet.scheme": "HTTP",
+    "spec.template.spec.containers[].ports[].protocol": "TCP",
+    "spec.template.spec.containers[].terminationMessagePath": "/dev/termination-log",
+    "spec.template.spec.containers[].terminationMessagePolicy": "File",
+    "spec.template.spec.securityContext": {},
   },
   "K8s::Core::Service": {
     "spec.sessionAffinity": "None",
     "spec.type": "ClusterIP",
+    "spec.internalTrafficPolicy": "Cluster",
+    "spec.ipFamilyPolicy": "SingleStack",
+    "spec.ports[].protocol": "TCP",
   },
 };
 
+/**
+ * Server-ASSIGNED fields — populated by the API server with a value that
+ * varies per object (an allocated ClusterIP, the resolved IP family list), so
+ * unlike {@link K8S_SERVICE_DEFAULTS} there is no fixed value to compare
+ * against. Counterpart-gated like the defaults table: a declared `clusterIP`
+ * is still compared, only the purely server-filled appearance is noise.
+ */
+export const K8S_SERVER_ASSIGNED_PATTERNS: Record<string, ReadonlySet<string>> = {
+  "K8s::Core::Service": new Set(["spec.clusterIP", "spec.clusterIPs", "spec.ipFamilies"]),
+};
+
+/**
+ * chant's own ownership marker, as label paths (#1214 — the k8s edition of
+ * azure's #1213 rule). The build stamps `app.kubernetes.io/managed-by` +
+ * `chant.intentius.io/{stack,env}` into every manifest it emits, so a managed
+ * object always carries them live while the declared *source* the diff
+ * compares does not — chant reading its own signature back as drift. The
+ * managed-fields prune cannot subtract them: they are in the applied config,
+ * so chant's field manager owns them, and chant-owned is always diffable.
+ * Counterpart-gated at the call site; managed-by is additionally gated on the
+ * value `"chant"`, so `managed-by: helm` appearing out of band still surfaces.
+ */
+const K8S_OWNERSHIP_LABEL_PATTERNS: ReadonlySet<string> = new Set([
+  `metadata.labels.${LABEL_OWNERSHIP_KEYS.stack}`,
+  `metadata.labels.${LABEL_OWNERSHIP_KEYS.env}`,
+]);
+
+const K8S_MANAGED_BY_LABEL_PATTERN = `metadata.labels.${LABEL_OWNERSHIP_KEYS.managedBy}`;
+
 /** Stable JSON with sorted keys — the fallback ordering key for a set-like array without a natural identity field. */
 function canonicalJson(value: unknown): string {
   return (
@@ -206,6 +258,14 @@ export const k8sDeepNormalizationHooks: DeepNormalizationHooks = {
     if (K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS.has(node.pattern)) return true;
 
     if (node.side !== "live" || node.counterpart !== "absent") return false;
+
+    // chant's own ownership marker is not drift (see the sets' docs).
+    if (K8S_OWNERSHIP_LABEL_PATTERNS.has(node.pattern)) return true;
+    if (node.pattern === K8S_MANAGED_BY_LABEL_PATTERN && node.value === OWNERSHIP_MANAGED_BY_VALUE) return true;
+
+    // A server-assigned value nobody declared is allocation, not drift.
+    if (K8S_SERVER_ASSIGNED_PATTERNS[node.entityType]?.has(node.pattern)) return true;
+
     const defaults = K8S_SERVICE_DEFAULTS[node.entityType];
     if (!defaults || !Object.prototype.hasOwnProperty.call(defaults, node.pattern)) return false;
     return canonicalJson(defaults[node.pattern]) === canonicalJson(node.value);

package/src/deep-observe.test.ts

@@ -96,6 +96,120 @@ describe("k8sDeepNormalizationHooks — the static rules", () => {
     expect(declaredExplicit).toEqual({ spec: { strategy: strategyDefault, replicas: 3 } });
   });
 
+  test("chant's own stamped labels are not drift; a foreign managed-by and a user label still are", () => {
+    const live = {
+      metadata: {
+        name: "web",
+        labels: {
+          "app.kubernetes.io/managed-by": "chant",
+          "chant.intentius.io/stack": "cc-azure-canonical",
+          "chant.intentius.io/env": "local",
+          team: "platform",
+        },
+      },
+    };
+    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" } } });
+
+    const foreign = normalizeDeepProperties(
+      { metadata: { name: "web", labels: { "app.kubernetes.io/managed-by": "helm" } } },
+      {
+        entityType: "K8s::Apps::Deployment",
+        side: "live",
+        hooks: k8sDeepNormalizationHooks,
+        counterpartPaths: new Set(["metadata", "metadata.name"]),
+      },
+    );
+    expect(foreign).toEqual({ metadata: { name: "web", labels: { "app.kubernetes.io/managed-by": "helm" } } });
+  });
+
+  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" } } },
+      {
+        entityType: "K8s::Core::Service",
+        side: "live",
+        hooks: k8sDeepNormalizationHooks,
+        counterpartPaths: new Set(["spec", "spec.selector", "spec.selector.app"]),
+      },
+    );
+    expect(undeclared).toEqual({ spec: { selector: { app: "web" } } });
+
+    const declared = normalizeDeepProperties(
+      { spec: { clusterIP: "10.43.0.10" } },
+      {
+        entityType: "K8s::Core::Service",
+        side: "live",
+        hooks: k8sDeepNormalizationHooks,
+        counterpartPaths: new Set(["spec", "spec.clusterIP"]),
+      },
+    );
+    expect(declared).toEqual({ spec: { clusterIP: "10.43.0.10" } });
+  });
+
+  test("probe and termination defaults subtract inside a declared container", () => {
+    const out = normalizeDeepProperties(
+      {
+        spec: {
+          template: {
+            spec: {
+              securityContext: {},
+              containers: [
+                {
+                  name: "api",
+                  image: "example:1",
+                  terminationMessagePath: "/dev/termination-log",
+                  terminationMessagePolicy: "File",
+                  livenessProbe: { httpGet: { path: "/", port: 8080, scheme: "HTTP" }, failureThreshold: 3, periodSeconds: 10, successThreshold: 1, timeoutSeconds: 1 },
+                  ports: [{ containerPort: 8080, name: "http", protocol: "TCP" }],
+                },
+              ],
+            },
+          },
+        },
+      },
+      {
+        entityType: "K8s::Apps::Deployment",
+        side: "live",
+        hooks: k8sDeepNormalizationHooks,
+        counterpartPaths: new Set([
+          "spec", "spec.template", "spec.template.spec",
+          "spec.template.spec.containers", "spec.template.spec.containers[]",
+          "spec.template.spec.containers[].name", "spec.template.spec.containers[].image",
+          "spec.template.spec.containers[].livenessProbe",
+          "spec.template.spec.containers[].livenessProbe.httpGet",
+          "spec.template.spec.containers[].livenessProbe.httpGet.path",
+          "spec.template.spec.containers[].livenessProbe.httpGet.port",
+          "spec.template.spec.containers[].ports",
+          "spec.template.spec.containers[].ports[]",
+          "spec.template.spec.containers[].ports[].containerPort",
+          "spec.template.spec.containers[].ports[].name",
+        ]),
+      },
+    );
+    expect(out).toEqual({
+      spec: {
+        template: {
+          spec: {
+            containers: [
+              {
+                name: "api",
+                image: "example:1",
+                livenessProbe: { httpGet: { path: "/", port: 8080 } },
+                ports: [{ containerPort: 8080, name: "http" }],
+              },
+            ],
+          },
+        },
+      },
+    });
+  });
+
   test("a one-sided pass never subtracts defaults — the reader has no declared tree yet", () => {
     const out = normalizeDeepProperties(
       { spec: { strategy: { type: "RollingUpdate", rollingUpdate: { maxSurge: "25%", maxUnavailable: "25%" } } } },

package/src/describe-resources.test.ts

@@ -465,6 +465,44 @@ describe("k8s describeResources", () => {
       warnSpy.mockRestore();
     });
 
+    test("a failed read names the bound context it read (#1488)", async () => {
+      loadChantConfigMock.mockResolvedValue({ config: { k8s: { profiles: { prod: { context: "prod-eks" } } } } });
+      const cluster = fakeCluster({
+        kubeconfig: twoContexts,
+        respond: (req) =>
+          req.path.endsWith("/deployments/web")
+            ? { status: 500, body: statusBody(500, "InternalError", "etcdserver: leader changed") }
+            : undefined,
+      });
+
+      const result = await describeResources(
+        { environment: "prod", buildOutput: "", entityNames: ["web"], entities: entities() },
+        (o) => defaultK8sConnector({ ...o, client: { kubeconfig: twoContexts, requestLayer: cluster.layer } }),
+      );
+
+      expect(result.unobserved?.web?.reason).toBe("read-failed");
+      expect(result.unobserved?.web?.detail).toContain('context "prod-eks" (bound by k8s.profiles.prod.context)');
+    });
+
+    test("an ambient read failure names the context that was read and the missing binding (#1488)", async () => {
+      loadChantConfigMock.mockResolvedValue({ config: {} });
+      const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+      const cluster = fakeCluster({
+        kubeconfig: twoContexts,
+        respond: (req) =>
+          req.path.endsWith("/deployments/web") ? { status: 500, body: statusBody(500, "InternalError", "nope") } : undefined,
+      });
+
+      const result = await describeResources(
+        { environment: "prod", buildOutput: "", entityNames: ["web"], entities: entities() },
+        (o) => defaultK8sConnector({ ...o, client: { kubeconfig: twoContexts, requestLayer: cluster.layer } }),
+      );
+      warnSpy.mockRestore();
+
+      expect(result.unobserved?.web?.reason).toBe("read-failed");
+      expect(result.unobserved?.web?.detail).toContain('context "prod-eks" (ambient; no k8s.profiles.prod binding)');
+    });
+
     test("a bound context the kubeconfig does not have refuses with the context name", async () => {
       loadChantConfigMock.mockResolvedValue({ config: { k8s: { profiles: { prod: { context: "gone-eks" } } } } });
       const oneContext = fakeKubeconfig({ contexts: [{ name: "prod-eks" }], currentContext: "prod-eks" });
@@ -573,6 +611,161 @@ describe("k8s describeResources", () => {
       expect(result.resources["prod/hand-made"]).toBeUndefined();
     });
 
+    // The issue's own estate: a declared MicroVMReplicaSet whose operator
+    // made MicroVMs — a CRD kind no table anticipated. Discovery names it.
+    test("a controller-made child of a CRD kind surfaces as a runtime child of the declared CR", async () => {
+      const replicaSet = {
+        apiVersion: "lambda.aws.amazon.com/v1alpha1",
+        kind: "MicroVMReplicaSet",
+        metadata: { name: "kmv-dev-a-vm", namespace: "microvm-demo", uid: "mvrs-uid" },
+      };
+      const vm = {
+        apiVersion: "lambda.aws.amazon.com/v1alpha1",
+        kind: "MicroVM",
+        metadata: {
+          name: "kmv-dev-a-vm-42sgf",
+          namespace: "microvm-demo",
+          uid: "vm-uid",
+          ownerReferences: [
+            { apiVersion: "lambda.aws.amazon.com/v1alpha1", kind: "MicroVMReplicaSet", name: "kmv-dev-a-vm", uid: "mvrs-uid", controller: true },
+          ],
+        },
+        status: { phase: "Running" },
+      };
+      const cluster = fakeCluster({
+        objects: {
+          [objectKey("lambda.aws.amazon.com/v1alpha1", "MicroVMReplicaSet", "kmv-dev-a-vm", "microvm-demo")]: replicaSet,
+          [objectKey("lambda.aws.amazon.com/v1alpha1", "MicroVM", "kmv-dev-a-vm-42sgf", "microvm-demo")]: vm,
+        },
+      });
+
+      const result = await describeResources(
+        {
+          environment: "dev",
+          buildOutput: "",
+          entityNames: ["workloadReplicaSet"],
+          entities: makeEntities([
+            {
+              name: "workloadReplicaSet",
+              entityType: "K8s::KubeMicroVM::MicroVMReplicaSet",
+              props: { metadata: { name: "kmv-dev-a-vm", namespace: "microvm-demo" } },
+            },
+          ]),
+        },
+        cluster.connector,
+      );
+
+      expect(result.resources["microvm-demo/kmv-dev-a-vm-42sgf"]).toMatchObject({
+        type: "K8s::Lambda::MicroVM",
+        physicalId: "vm-uid",
+        ownerChain: { root: "declared", entity: "workloadReplicaSet" },
+      });
+    });
+
+    test("a child in a group the estate never declares surfaces too — discovery names the kinds, not the declaration", async () => {
+      // A declared CR whose operator makes ordinary Deployments: ray.io is
+      // declared, apps/v1 is not, and the estate-groups sweep never listed it.
+      const rayCluster = { apiVersion: "ray.io/v1", kind: "RayCluster", metadata: { name: "ml", namespace: "ray", uid: "ray-uid" } };
+      const head = {
+        apiVersion: "apps/v1",
+        kind: "Deployment",
+        metadata: {
+          name: "ml-head",
+          namespace: "ray",
+          uid: "head-uid",
+          ownerReferences: [{ apiVersion: "ray.io/v1", kind: "RayCluster", name: "ml", uid: "ray-uid", controller: true }],
+        },
+        status: { readyReplicas: 1, replicas: 1 },
+      };
+      const cluster = fakeCluster({
+        objects: {
+          [objectKey("ray.io/v1", "RayCluster", "ml", "ray")]: rayCluster,
+          [objectKey("apps/v1", "Deployment", "ml-head", "ray")]: head,
+        },
+      });
+
+      const result = await describeResources(
+        {
+          environment: "prod",
+          buildOutput: "",
+          entityNames: ["ml"],
+          entities: makeEntities([
+            { name: "ml", entityType: "K8s::Ray::RayCluster", props: { metadata: { name: "ml", namespace: "ray" } } },
+          ]),
+        },
+        cluster.connector,
+      );
+
+      expect(result.resources["ray/ml-head"]).toMatchObject({
+        type: "K8s::Apps::Deployment",
+        physicalId: "head-uid",
+        ownerChain: { root: "declared", entity: "ml" },
+      });
+    });
+
+    test("a discovered kind the sweep cannot list is an unobserved hole, never silently absent", async () => {
+      const cluster = fakeCluster({
+        objects: { [objectKey("batch/v1", "CronJob", "backup", "prod")]: cronJob },
+        respond: (req) =>
+          req.path === "/apis/batch/v1/namespaces/prod/jobs"
+            ? { status: 403, body: statusBody(403, "Forbidden", "jobs is forbidden") }
+            : undefined,
+      });
+
+      const result = await describeResources(
+        { environment: "prod", buildOutput: "", entityNames: ["backup"], entities: declaredCronJob() },
+        cluster.connector,
+      );
+
+      // Declared resolution is never failed by the sweep.
+      expect(result.resources.backup).toMatchObject({ type: "K8s::Batch::CronJob", physicalId: "cj-uid" });
+      // The failed list is a hole the observation admits, with the failure's
+      // own classification — a 403 is a credentials problem, and silence here
+      // would have read as "no runtime children in prod".
+      expect(result.unobserved?.["runtime-sweep:batch/v1/Job"]).toMatchObject({
+        type: "K8s::Batch::Job",
+        reason: "no-credentials",
+      });
+      expect(result.unobserved?.["runtime-sweep:batch/v1/Job"]?.detail).toContain("namespace prod");
+    });
+
+    test("a cluster-scoped child chains to a declared cluster-scoped entity — the one case cluster-scoped kinds are swept", async () => {
+      const ns = { apiVersion: "v1", kind: "Namespace", metadata: { name: "team-a", uid: "ns-uid" }, status: { phase: "Active" } };
+      const role = {
+        apiVersion: "rbac.authorization.k8s.io/v1",
+        kind: "ClusterRole",
+        metadata: {
+          name: "team-a-admin",
+          uid: "role-uid",
+          ownerReferences: [{ apiVersion: "v1", kind: "Namespace", name: "team-a", uid: "ns-uid", controller: true }],
+        },
+      };
+      const cluster = fakeCluster({
+        objects: {
+          [objectKey("v1", "Namespace", "team-a")]: ns,
+          [objectKey("rbac.authorization.k8s.io/v1", "ClusterRole", "team-a-admin")]: role,
+        },
+      });
+
+      const result = await describeResources(
+        {
+          environment: "prod",
+          buildOutput: "",
+          entityNames: ["team"],
+          entities: makeEntities([
+            { name: "team", entityType: "K8s::Core::Namespace", props: { metadata: { name: "team-a" } } },
+          ]),
+        },
+        cluster.connector,
+      );
+
+      expect(result.resources["cluster:team-a-admin"]).toMatchObject({
+        type: "K8s::Rbac::ClusterRole",
+        physicalId: "role-uid",
+        ownerChain: { root: "declared", entity: "team" },
+      });
+    });
+
     test("a Flux-managed Deployment is attributed to its declared Kustomization by the controller's labels (#1549)", async () => {
       // Flux stamps managed objects with name+namespace labels instead of
       // ownerReferences, so the chain walk reaches nothing — the label
@@ -702,7 +895,7 @@ describe("k8s describeResources", () => {
       expect(result.resources["flux-system/cert-manager"]).toBeUndefined();
     });
 
-    test("a core-only estate sweeps no extra groups — Pods stay the core representative", async () => {
+    test("the sweep's bound is the estate's namespaces, not a kind list — and no cluster-scoped list without a cluster-scoped entity", async () => {
       const svc = { apiVersion: "v1", kind: "Service", metadata: { name: "web", namespace: "prod", uid: "svc-uid" } };
       const cluster = fakeCluster({
         objects: { [objectKey("v1", "Service", "web", "prod")]: svc },
@@ -720,10 +913,20 @@ describe("k8s describeResources", () => {
         cluster.connector,
       );
 
-      // Discovery was consulted for no non-core groupVersion: the only list
-      // sweeps are the namespace's pods.
-      const groupDiscovery = cluster.layer.paths().filter((p) => /^\/apis\/[^/]+\/[^/]+$/.test(p) && !p.includes("namespaces"));
-      expect(groupDiscovery.filter((p) => !p.startsWith("/apis/apps"))).toEqual([]);
+      const paths = cluster.layer.paths();
+      const isDiscovery = (p: string) =>
+        p === "/api" || p === "/apis" || /^\/api\/[^/]+$/.test(p) || /^\/apis\/[^/]+\/[^/]+$/.test(p);
+      const reads = paths.filter((p) => !isDiscovery(p));
+      // Discovery names the kinds; every actual read or list stays inside the
+      // one namespace the estate touches. Nothing is listed cluster-wide.
+      expect(reads.length).toBeGreaterThan(0);
+      expect(reads.every((p) => p.includes("/namespaces/prod/"))).toBe(true);
+      // Nothing declared is cluster-scoped, so no owner chain could reach a
+      // cluster-scoped object — their kinds are not listed at all.
+      expect(paths.some((p) => p.endsWith("/clusterroles"))).toBe(false);
+      // Events churn by the thousands and can never chain (`involvedObject`,
+      // not `ownerReferences`) — discovery serves them, the sweep skips them.
+      expect(paths.some((p) => p.endsWith("/events"))).toBe(false);
     });
   });
 
@@ -914,7 +1117,7 @@ describe("k8s describeResources", () => {
       expect(Object.keys(result.resources)).toHaveLength(2); // web + standalonePod, no synthetic duplicate
     });
 
-    test("a Pod-list failure for a namespace is best-effort — declared entities still resolve", async () => {
+    test("a Pod-list failure never fails declared resolution — and surfaces as an unobserved hole (#1517)", async () => {
       const cluster = fakeCluster({
         objects: { [objectKey("apps/v1", "Deployment", "web", "prod")]: web },
         respond: (req) => (req.path.endsWith("/pods") ? { status: 403, body: statusBody(403, "Forbidden", "no pods list") } : undefined),
@@ -927,6 +1130,12 @@ describe("k8s describeResources", () => {
 
       expect(result.resources.web).toMatchObject({ type: "K8s::Apps::Deployment", physicalId: "uid-1" });
       expect(Object.keys(result.resources)).toEqual(["web"]);
+      // Silence would read as "no runtime Pods in prod", which the failed
+      // list never proved — the sweep admits the hole instead.
+      expect(result.unobserved?.["runtime-sweep:v1/Pod"]).toMatchObject({
+        type: "K8s::Core::Pod",
+        reason: "no-credentials",
+      });
     });
 
     test("a lexicon-supported entity type with no namespaced entities resolved does no Pod scan at all", async () => {