@intentius/chant-lexicon-k8s 0.31.0 → 0.32.0

package/src/deep-observe.ts

@@ -0,0 +1,299 @@
+/**
+ * Kubernetes deep observation (#1076) — the k8s row of the deep-observe
+ * contract (#1014), and the epic's (#1073) thesis made real: chant compiled
+ * the manifest, so it knows which fields it authored; the API server records,
+ * per field, which manager last wrote it (`metadata.managedFields`, chant
+ * #1075/#1178). Intersecting those two makes Kubernetes drift *derived*
+ * 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"
+ *
+ * AWS, Azure and Temporal's rows all prune by a **static, entityType-keyed**
+ * table: an ARN always looks like an ARN, `provisioningState` is always
+ * server-populated, a namespace's retention default is always the same
+ * value. None of that needs the specific live object in hand — it is exactly
+ * 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).
+ *
+ * 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.
+ *
+ * ## The contested-field rule, precisely
+ *
+ * For every path on the live tree, three questions, each independent:
+ *
+ * 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.
+ *
+ * ## Resolving a managedFields entry against a live array
+ *
+ * `metadata.managedFields[].fieldsV1` encodes a list item three ways —
+ * `k:{"name":"web"}` (by key), `v:"blue"` (by value), `i:3` (by index) — and
+ * chant #1178's `managed-fields.ts` renders all three to a path *string*
+ * (`.spec.containers[name="web"]`) for display. Parsing that string back
+ * would be ambiguous in general (a label key may itself contain `.`, e.g.
+ * `app.kubernetes.io/name`, indistinguishable in the rendered form from
+ * nested fields), so this reader does not parse strings at all: it walks the
+ * *structured* `fieldsV1` tree directly (`walkOwnership`, below), matching
+ * each `k:`/`v:` entry against the actual live array to find the concrete
+ * index, and against the actual declared array (by the same key or value) to
+ * answer question 3 for that element specifically — a declared container
+ * named `app` at index 0 is still "declared" if a sidecar gets injected in
+ * front of it and shifts it to live index 1.
+ *
+ * ## What is deliberately not modeled
+ *
+ * A manager's `.` entry (SSA's "I own this element's presence") on a
+ * 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.
+ *
+ * ## `buildOwnershipSets` lives in core now
+ *
+ * The ownership walk itself (`walkOwnership`, resolving a `fieldsV1` tree
+ * against the live and declared trees) has nothing k8s-*lexicon*-specific
+ * about it — it is generic Kubernetes SSA machinery. Chant #1087 (GCP's row,
+ * reusing this one, since a Config Connector CR is a Kubernetes object too)
+ * moved it to `@intentius/chant/managed-fields` rather than have gcp depend
+ * on this lexicon's package, the same reason chant #1100's
+ * `resolveClusterTarget` lives in core. This module re-exports
+ * `buildOwnershipSets`/`OwnershipSets` from there so nothing here changes for
+ * an existing importer of this file.
+ */
+
+import type { K8sObject } from "@intentius/chant-k8s-client";
+import type {
+  DeepNormalizationHooks,
+  DeepObservationResult,
+  DeepResourceObservation,
+  UnobservedEntity,
+} from "@intentius/chant/lexicon";
+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 { defaultK8sConnector, type K8sConnector } from "./api/connect";
+import {
+  classifyApiFailure,
+  isMissingClientPackage,
+  isWholeLexiconFailure,
+  MISSING_CLIENT_DETAIL,
+} from "./api/classify";
+import { operationFor } from "./api/operation-surface";
+import { k8sDeepNormalizationHooks } from "./deep-observe-hooks";
+
+// Re-exported so a dynamic importer of this module (plugin.ts's
+// `observeResourcesDeep`, a test) can get the reader and its hooks from one
+// place, the same shape AWS/Azure/Temporal's single deep-observe.ts offers.
+// `plugin.ts`'s own `deepNormalizationHooks` field imports the hooks
+// separately, directly from `./deep-observe-hooks` — that file has no
+// dependency on `@intentius/chant-k8s-client`, so it is safe to import
+// statically; this module is not (see the module doc).
+export { k8sDeepNormalizationHooks, buildOwnershipSets, type OwnershipSets };
+
+export interface K8sDeepObserveOptions {
+  environment: string;
+  buildOutput?: string;
+  entityNames: string[];
+  entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+  stack?: string;
+  owned?: boolean;
+  /** Directory whose `chant.config.ts` carries the cluster binding. Defaults to cwd. */
+  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;
+  return rest;
+}
+
+/**
+ * Read the live property tree for each declared entity, pruning by
+ * `metadata.managedFields` (see the module doc). Reuses the same connector,
+ * discovery/caching client and tri-state failure classification as the thin
+ * read (`./describe-resources.ts`) — the binding check (chant #1100/#1155)
+ * still refuses before any resource is touched, and a connect failure still
+ * becomes NOT-OBSERVED for every declared entity rather than an empty result.
+ */
+export async function observeResourcesDeepK8s(
+  options: K8sDeepObserveOptions,
+  connect: K8sConnector = defaultK8sConnector,
+): Promise<DeepObservationResult> {
+  const { managedFieldsOf, isChantFieldManager } = await import("@intentius/chant-k8s-client");
+
+  const declared = [...options.entities].map(([entityName, entity]) => ({
+    entityName,
+    entityType: entity.entityType,
+    props: entity.props,
+  }));
+
+  let client;
+  try {
+    ({ client } = await connect({ environment: options.environment, cwd: options.cwd }));
+  } catch (err) {
+    if (isMissingClientPackage(err)) {
+      return deepObservation(
+        {},
+        unobservedAll(
+          declared.map((d) => d.entityName),
+          "read-failed",
+          MISSING_CLIENT_DETAIL,
+          options.entities,
+        ),
+      );
+    }
+    if (isWholeLexiconFailure(err)) {
+      const outcome = classifyApiFailure(err);
+      return deepObservation(
+        {},
+        unobservedAll(
+          declared.map((d) => d.entityName),
+          outcome.kind === "unobserved" ? outcome.reason : "read-failed",
+          outcome.kind === "unobserved" ? outcome.detail : undefined,
+          options.entities,
+        ),
+      );
+    }
+    // A cluster-binding mismatch (chant #1100) — refuse loudly, same as the
+    // thin path; core turns the throw into NOT-OBSERVED for every entity.
+    throw err;
+  }
+
+  const resources: Record<string, DeepResourceObservation> = {};
+  const unobserved: Record<string, UnobservedEntity> = {};
+
+  await client.concurrently(declared, async ({ entityName, entityType, props }) => {
+    const operation = operationFor(entityType);
+    if (!operation) {
+      unobserved[entityName] = {
+        type: entityType,
+        reason: "unsupported-kind",
+        detail: `no generated operation surface for ${entityType} — run \`chant generate\` in the k8s lexicon, or declare the CRD as a codegen source`,
+      };
+      return;
+    }
+
+    const metadata = props.metadata as { name?: string; namespace?: string } | undefined;
+    const name = metadata?.name;
+    if (!name) {
+      unobserved[entityName] = {
+        type: entityType,
+        reason: "read-failed",
+        detail: "declared entity has no metadata.name to query by",
+      };
+      return;
+    }
+
+    try {
+      const obj = await client.read({
+        apiVersion: operation.apiVersion,
+        kind: operation.kind,
+        name,
+        ...(metadata?.namespace ? { namespace: metadata.namespace } : {}),
+      });
+
+      if (options.owned && !hasOwnershipMarker(obj.metadata?.labels, LABEL_OWNERSHIP_KEYS)) {
+        unobserved[entityName] = {
+          type: entityType,
+          reason: "filtered",
+          detail: "live object carries no chant ownership marker and --owned was requested",
+        };
+        return;
+      }
+
+      const liveRoot = propertiesTreeOf(obj);
+      const sets = buildOwnershipSets(managedFieldsOf(obj), liveRoot, props, isChantFieldManager);
+
+      resources[entityName] = {
+        type: entityType,
+        physicalId: obj.metadata?.uid,
+        properties: normalizeDeepProperties(liveRoot, {
+          entityType,
+          side: "live",
+          hooks: perResourceHooks(sets),
+        }),
+      };
+    } catch (err) {
+      const outcome = classifyApiFailure(err);
+      if (outcome.kind === "unobserved") {
+        unobserved[entityName] = { type: entityType, reason: outcome.reason, detail: outcome.detail };
+      }
+      // `absent` records nothing — the thin read already reports the
+      // non-existence; restating it here would turn one finding into two.
+    }
+  });
+
+  return deepObservation(resources, unobserved);
+}

package/src/describe-resources.test.ts

@@ -16,7 +16,7 @@ vi.mock("@intentius/chant/config", () => ({
 }));
 
 const { describeResources } = await import("./describe-resources");
-const { fakeCluster, objectKey } = await import("./api/fake-cluster");
+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");
 
@@ -501,4 +501,227 @@ describe("k8s describeResources", () => {
     expect(result.unobserved?.web?.detail).toContain("npm i @intentius/chant-k8s-client");
     expect(result.unobserved?.web?.type).toBe("K8s::Apps::Deployment");
   });
+
+  // ── Runtime children: owner-reference chain classification (chant #1077) ──
+
+  describe("runtime children (#1077)", () => {
+    function declaredDeployment() {
+      return makeEntities([
+        { name: "web", entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web", namespace: "prod" } } },
+      ]);
+    }
+
+    test("a Pod owned (via an undeclared ReplicaSet) by a declared Deployment reports ownerChain: declared", async () => {
+      const replicaSet = {
+        apiVersion: "apps/v1",
+        kind: "ReplicaSet",
+        metadata: {
+          name: "web-7d9f8c9c8",
+          namespace: "prod",
+          uid: "rs-uid",
+          ownerReferences: [{ apiVersion: "apps/v1", kind: "Deployment", name: "web", uid: "uid-1", controller: true }],
+        },
+      };
+      const runtimePod = {
+        apiVersion: "v1",
+        kind: "Pod",
+        metadata: {
+          name: "web-7d9f8c9c8-abcde",
+          namespace: "prod",
+          uid: "pod-uid",
+          ownerReferences: [{ apiVersion: "apps/v1", kind: "ReplicaSet", name: "web-7d9f8c9c8", uid: "rs-uid", controller: true }],
+        },
+        status: { phase: "Running" },
+      };
+      const cluster = fakeCluster({
+        objects: {
+          [objectKey("apps/v1", "Deployment", "web", "prod")]: web,
+          [objectKey("apps/v1", "ReplicaSet", "web-7d9f8c9c8", "prod")]: replicaSet,
+          [objectKey("v1", "Pod", "web-7d9f8c9c8-abcde", "prod")]: runtimePod,
+        },
+      });
+
+      const result = await describeResources(
+        { environment: "prod", buildOutput: "", entityNames: ["web"], entities: declaredDeployment() },
+        cluster.connector,
+      );
+
+      const child = result.resources["prod/web-7d9f8c9c8-abcde"];
+      expect(child).toMatchObject({
+        type: "K8s::Core::Pod",
+        physicalId: "pod-uid",
+        status: "Running",
+        ownerChain: { root: "declared", entity: "web" },
+      });
+      // Reads the ReplicaSet to walk past it — one extra request beyond the
+      // Deployment read and the Pod list.
+      expect(cluster.layer.paths()).toContain("/apis/apps/v1/namespaces/prod/replicasets/web-7d9f8c9c8");
+    });
+
+    test("a genuinely unowned Pod in the same namespace reports ownerChain: unowned (still an orphan downstream)", async () => {
+      const standalonePod = {
+        apiVersion: "v1",
+        kind: "Pod",
+        metadata: { name: "standalone", namespace: "prod", uid: "standalone-uid" },
+        status: { phase: "Running" },
+      };
+      const cluster = fakeCluster({
+        objects: {
+          [objectKey("apps/v1", "Deployment", "web", "prod")]: web,
+          [objectKey("v1", "Pod", "standalone", "prod")]: standalonePod,
+        },
+      });
+
+      const result = await describeResources(
+        { environment: "prod", buildOutput: "", entityNames: ["web"], entities: declaredDeployment() },
+        cluster.connector,
+      );
+
+      expect(result.resources["prod/standalone"]).toMatchObject({
+        type: "K8s::Core::Pod",
+        ownerChain: { root: "unowned" },
+      });
+    });
+
+    test("a Pod owned by something never declared reports ownerChain: foreign", async () => {
+      const otherRs = {
+        apiVersion: "apps/v1",
+        kind: "ReplicaSet",
+        metadata: { name: "other-rs", namespace: "prod", uid: "other-rs-uid" }, // no further owner
+      };
+      const otherPod = {
+        apiVersion: "v1",
+        kind: "Pod",
+        metadata: {
+          name: "other-pod",
+          namespace: "prod",
+          uid: "other-pod-uid",
+          ownerReferences: [{ apiVersion: "apps/v1", kind: "ReplicaSet", name: "other-rs", uid: "other-rs-uid", controller: true }],
+        },
+      };
+      const cluster = fakeCluster({
+        objects: {
+          [objectKey("apps/v1", "Deployment", "web", "prod")]: web,
+          [objectKey("apps/v1", "ReplicaSet", "other-rs", "prod")]: otherRs,
+          [objectKey("v1", "Pod", "other-pod", "prod")]: otherPod,
+        },
+      });
+
+      const result = await describeResources(
+        { environment: "prod", buildOutput: "", entityNames: ["web"], entities: declaredDeployment() },
+        cluster.connector,
+      );
+
+      expect(result.resources["prod/other-pod"]).toMatchObject({ ownerChain: { root: "foreign" } });
+    });
+
+    test("--owned withholds an unrelated Pod, but keeps a runtime child of a declared (owned) entity", async () => {
+      // The declared Deployment must itself carry chant's marker for `--owned`
+      // to surface it at all — otherwise it is filtered before a Pod scan ever
+      // has a declared uid to compare against.
+      const ownedWeb = ownedObject("apps/v1", "Deployment", "web", "prod", { status: { readyReplicas: 3, replicas: 3 } });
+      const standalonePod = {
+        apiVersion: "v1",
+        kind: "Pod",
+        metadata: { name: "standalone", namespace: "prod", uid: "standalone-uid" },
+      };
+      const runtimePod = {
+        apiVersion: "v1",
+        kind: "Pod",
+        metadata: {
+          name: "web-abc",
+          namespace: "prod",
+          uid: "pod-uid",
+          ownerReferences: [{ apiVersion: "apps/v1", kind: "Deployment", name: "web", uid: "uid-web", controller: true }],
+        },
+      };
+      const cluster = fakeCluster({
+        objects: {
+          [objectKey("apps/v1", "Deployment", "web", "prod")]: ownedWeb,
+          [objectKey("v1", "Pod", "standalone", "prod")]: standalonePod,
+          [objectKey("v1", "Pod", "web-abc", "prod")]: runtimePod,
+        },
+      });
+
+      const result = await describeResources(
+        {
+          environment: "prod",
+          buildOutput: "",
+          entityNames: ["web"],
+          entities: declaredDeployment(),
+          owned: true,
+        },
+        cluster.connector,
+      );
+
+      expect(result.resources.web).toBeDefined(); // the marker let it through
+      expect(result.resources["prod/standalone"]).toBeUndefined();
+      expect(result.resources["prod/web-abc"]).toMatchObject({ ownerChain: { root: "declared", entity: "web" } });
+    });
+
+    test("a Pod that is itself declared is never duplicated as a runtime child", async () => {
+      const declaredPod = {
+        apiVersion: "v1",
+        kind: "Pod",
+        metadata: { name: "standalone-pod", namespace: "prod", uid: "uid-declared-pod" },
+        status: { phase: "Running" },
+      };
+      const cluster = fakeCluster({
+        objects: {
+          [objectKey("apps/v1", "Deployment", "web", "prod")]: web,
+          [objectKey("v1", "Pod", "standalone-pod", "prod")]: declaredPod,
+        },
+      });
+
+      const result = await describeResources(
+        {
+          environment: "prod",
+          buildOutput: "",
+          entityNames: ["web", "standalonePod"],
+          entities: makeEntities([
+            { name: "web", entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web", namespace: "prod" } } },
+            { name: "standalonePod", entityType: "K8s::Core::Pod", props: { metadata: { name: "standalone-pod", namespace: "prod" } } },
+          ]),
+        },
+        cluster.connector,
+      );
+
+      expect(result.resources.standalonePod).toBeDefined();
+      expect(result.resources["prod/standalone-pod"]).toBeUndefined();
+      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 () => {
+      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),
+      });
+
+      const result = await describeResources(
+        { environment: "prod", buildOutput: "", entityNames: ["web"], entities: declaredDeployment() },
+        cluster.connector,
+      );
+
+      expect(result.resources.web).toMatchObject({ type: "K8s::Apps::Deployment", physicalId: "uid-1" });
+      expect(Object.keys(result.resources)).toEqual(["web"]);
+    });
+
+    test("a lexicon-supported entity type with no namespaced entities resolved does no Pod scan at all", async () => {
+      const ns = { apiVersion: "v1", kind: "Namespace", metadata: { name: "mynamespace", uid: "uid-ns" }, status: { phase: "Active" } };
+      const cluster = fakeCluster({ objects: { [objectKey("v1", "Namespace", "mynamespace")]: ns } });
+
+      const result = await describeResources(
+        {
+          environment: "prod",
+          buildOutput: "",
+          entityNames: ["ns"],
+          entities: makeEntities([{ name: "ns", entityType: "K8s::Core::Namespace", props: { metadata: { name: "mynamespace" } } }]),
+        },
+        cluster.connector,
+      );
+
+      expect(Object.keys(result.resources)).toEqual(["ns"]);
+      expect(cluster.layer.paths().some((p) => p.endsWith("/pods"))).toBe(false);
+    });
+  });
 });

package/src/describe-resources.ts

@@ -35,12 +35,27 @@
  * NOT-OBSERVED with a reason. A declared `k8s.profiles.<env>.context` that
  * disagrees with the ambient one still refuses before a single resource is
  * touched, via the same `resolveClusterTarget` the GCP lexicon shares.
+ *
+ * ## Runtime children (chant #1077)
+ *
+ * A Pod a declared Deployment's controller created is live and undeclared —
+ * exactly the shape `lifecycle diff --live` has always classified `orphan`.
+ * On Kubernetes that is wrong: it is expected runtime, not drift, and will be
+ * recreated the moment it is deleted. After the declared-entity reads above
+ * resolve, this scans Pods in the namespaces they actually live in and walks
+ * each one's `ownerReferences` chain (`./api/owner-chain.ts`) against the
+ * entities this very call resolved. A chain reaching one of them is reported
+ * with `ownerChain: { root: "declared", ... }`; core's diff/change-set engine
+ * reads that as `runtime` instead of `orphan`. Deliberately scoped to Pods —
+ * the concrete case the issue and its acceptance criteria name — and to the
+ * namespaces this observation already touched, not a cluster-wide sweep;
+ * widening to other controller-spawned kinds is the same walk repeated.
  */
 
 import type { ObservationResult, ResourceMetadata, UnobservedEntity } from "@intentius/chant/lexicon";
 import { observation, unobservedAll } from "@intentius/chant/observation";
 import { hasOwnershipMarker, classifyOwnership, LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
-import type { K8sObject } from "@intentius/chant-k8s-client";
+import type { K8sClient, K8sObject } from "@intentius/chant-k8s-client";
 import { defaultK8sConnector, type K8sConnector } from "./api/connect";
 import {
   classifyApiFailure,
@@ -49,6 +64,7 @@ import {
   MISSING_CLIENT_DETAIL,
 } from "./api/classify";
 import { operationFor } from "./api/operation-surface";
+import { resolveK8sOwnerChain } from "./api/owner-chain";
 
 function pruneUndefined<T extends Record<string, unknown>>(obj: T): Record<string, unknown> {
   const out: Record<string, unknown> = {};
@@ -207,5 +223,74 @@ export async function describeResources(
     }
   });
 
+  await addRuntimeChildren(client, resources, options.owned);
+
   return observation(resources, unobserved);
 }
+
+/**
+ * Scan Pods in the namespaces of entities this call just resolved, and
+ * classify each one's owner-reference chain (#1077). Mutates `resources` in
+ * place, adding an entry per Pod whose chain was worth reporting.
+ *
+ * Best-effort and additive: a namespace this scan cannot list (RBAC denial,
+ * a transient error) is simply skipped rather than failing the observation —
+ * Pods are not declared entities, so there is no NOT-OBSERVED axis for them
+ * to report against, the same way an out-of-band AWS child resource has none
+ * either.
+ */
+async function addRuntimeChildren(
+  client: K8sClient,
+  resources: Record<string, ResourceMetadata>,
+  owned: boolean | undefined,
+): Promise<void> {
+  const declaredByUid = new Map<string, string>();
+  for (const [entityName, meta] of Object.entries(resources)) {
+    if (meta.physicalId) declaredByUid.set(meta.physicalId, entityName);
+  }
+
+  const namespaces = new Set<string>();
+  for (const meta of Object.values(resources)) {
+    const namespace = (meta.attributes as { namespace?: string } | undefined)?.namespace;
+    if (namespace) namespaces.add(namespace);
+  }
+  if (namespaces.size === 0) return;
+
+  await client.concurrently([...namespaces], async (namespace) => {
+    let pods: K8sObject[];
+    try {
+      pods = await client.list({ apiVersion: "v1", kind: "Pod" }, { namespace });
+    } catch {
+      return; // best-effort — see the function doc
+    }
+
+    await client.concurrently(pods, async (pod) => {
+      const uid = pod.metadata?.uid;
+      const name = pod.metadata?.name;
+      if (!uid || !name || declaredByUid.has(uid)) return; // declared directly, or unaddressable
+
+      const ownerChain = await resolveK8sOwnerChain(pod, { declaredByUid, reader: client, namespace });
+
+      // `--owned`: withhold a Pod that is neither a runtime child of a
+      // declared entity nor carrying chant's own marker — the same rule the
+      // declared-entity read above applies, extended to the undeclared axis
+      // this scan introduces.
+      const marker = hasOwnershipMarker(pod.metadata?.labels, LABEL_OWNERSHIP_KEYS);
+      if (owned && ownerChain.root !== "declared" && !marker) return;
+
+      resources[`${namespace}/${name}`] = {
+        type: "K8s::Core::Pod",
+        physicalId: uid,
+        status: statusFromObject(pod),
+        lastUpdated: pod.metadata?.creationTimestamp,
+        ownership: classifyOwnership(pod.metadata?.labels, LABEL_OWNERSHIP_KEYS),
+        ownerChain,
+        attributes: pruneUndefined({
+          namespace,
+          labels: pod.metadata?.labels,
+          resourceVersion: pod.metadata?.resourceVersion,
+        }),
+      };
+    });
+  });
+}