@intentius/chant-lexicon-k8s 0.30.0 → 0.32.0

package/src/api/fake-cluster.ts

@@ -0,0 +1,218 @@
+/**
+ * A fake cluster to point the k8s lexicon at, for tests (chant #1074).
+ *
+ * It builds a **real** `@intentius/chant-k8s-client` over a literal kubeconfig
+ * with `@kubernetes/client-node`'s HTTP send replaced. So kubeconfig parsing,
+ * context selection, the credential policy, API discovery, path construction
+ * and the auth path all run for real; the only thing that does not happen is
+ * the socket. Nothing reads `~/.kube/config` or `$KUBECONFIG`, and nothing can
+ * reach a cluster the developer happens to have a context for.
+ *
+ * Shipped rather than kept in a test file because the lexicon's own tests, the
+ * cross-lexicon lifecycle suite and a consumer wiring chant into their harness
+ * all need the same thing.
+ */
+
+import type { K8sObject } from "@intentius/chant-k8s-client";
+import { apiResourceList, fakeKubeconfig, fakeRequestLayer, statusBody } from "@intentius/chant-k8s-client/testing";
+import type { FakeRequestLayer, RecordedRequest } from "@intentius/chant-k8s-client/testing";
+import { createK8sClient } from "@intentius/chant-k8s-client";
+import type { ConnectedClient, ConnectOptions, K8sConnector } from "./connect";
+import { operationTable } from "./operation-surface";
+
+export interface FakeClusterOptions {
+  /**
+   * Objects the cluster holds, keyed by
+   * `<apiVersion>/<Kind>/<namespace|_>/<name>`, e.g.
+   * `apps/v1/Deployment/prod/web`. Build keys with {@link objectKey}.
+   */
+  objects?: Record<string, K8sObject>;
+  /**
+   * Entity types (or `<apiVersion> <Kind>` pairs) this cluster serves. Defaults
+   * to every type in the generated operation surface, which is what makes a
+   * CRD resolvable in a test without registering anything.
+   */
+  serves?: readonly string[];
+  /** Full control: return a response for a request, or undefined to fall through. */
+  respond?: (request: RecordedRequest) => { status?: number; body?: unknown } | undefined;
+  /** Kubeconfig to hand the client. Defaults to a single-context one. */
+  kubeconfig?: string;
+}
+
+export interface FakeCluster {
+  connector: K8sConnector;
+  layer: FakeRequestLayer;
+  /** Connect options every call received, for asserting the binding path. */
+  connects: ConnectOptions[];
+}
+
+/** Key an object the way {@link fakeCluster} indexes them. */
+export function objectKey(apiVersion: string, kind: string, name: string, namespace?: string): string {
+  return `${apiVersion}/${kind}/${namespace ?? "_"}/${name}`;
+}
+
+/** Build a live object with chant's ownership marker already on it. */
+export function ownedObject(
+  apiVersion: string,
+  kind: string,
+  name: string,
+  namespace: string | undefined,
+  extra: Partial<K8sObject> = {},
+): K8sObject {
+  return {
+    apiVersion,
+    kind,
+    metadata: {
+      name,
+      ...(namespace ? { namespace } : {}),
+      uid: `uid-${name}`,
+      resourceVersion: "1",
+      labels: { "app.kubernetes.io/managed-by": "chant" },
+      ...(extra.metadata ?? {}),
+    },
+    ...(extra.status ? { status: extra.status } : {}),
+  };
+}
+
+interface ServedResource {
+  apiVersion: string;
+  kind: string;
+  plural: string;
+  namespaced: boolean;
+}
+
+function servedResources(serves: readonly string[] | undefined): ServedResource[] {
+  const table = operationTable();
+  const entries = serves
+    ? serves.map((s) => table[s]).filter((d) => d !== undefined)
+    : Object.values(table);
+  return entries
+    .filter((d) => d.verbs.length > 0)
+    .map((d) => ({
+      apiVersion: d.apiVersion,
+      kind: d.kind,
+      plural: d.plural,
+      namespaced: d.scope === "Namespaced",
+    }));
+}
+
+/**
+ * A cluster that answers discovery for the kinds it serves and holds the
+ * objects it was given. Anything else 404s with a real `Status` body, which is
+ * how a test drives the absent branch of the observation tri-state.
+ */
+export function fakeCluster(options: FakeClusterOptions = {}): FakeCluster {
+  const resources = servedResources(options.serves);
+  const byApiVersion = new Map<string, ServedResource[]>();
+  for (const r of resources) {
+    const list = byApiVersion.get(r.apiVersion) ?? [];
+    list.push(r);
+    byApiVersion.set(r.apiVersion, list);
+  }
+
+  // Path → the object it addresses, and list path → its members, precomputed
+  // so the responder below is a pair of lookups.
+  const byPath = new Map<string, K8sObject>();
+  const listPaths = new Map<string, K8sObject[]>();
+  const addToList = (path: string, object: K8sObject): void => {
+    const list = listPaths.get(path) ?? [];
+    list.push(object);
+    listPaths.set(path, list);
+  };
+  for (const [key, object] of Object.entries(options.objects ?? {})) {
+    const [group, version, kind, namespace, name] = splitKey(key);
+    const apiVersion = group ? `${group}/${version}` : version;
+    const resource = resources.find((r) => r.apiVersion === apiVersion && r.kind === kind);
+    if (!resource) continue;
+    const base = apiVersion.includes("/") ? `/apis/${apiVersion}` : `/api/${apiVersion}`;
+    if (resource.namespaced) {
+      const ns = namespace === "_" ? "default" : namespace;
+      byPath.set(`${base}/namespaces/${ns}/${resource.plural}/${name}`, object);
+      addToList(`${base}/namespaces/${ns}/${resource.plural}`, object);
+    } else {
+      byPath.set(`${base}/${resource.plural}/${name}`, object);
+    }
+    // Cluster-wide list, which is what `chant import` sweeps.
+    addToList(`${base}/${resource.plural}`, object);
+  }
+
+  const groups = new Map<string, string>();
+  for (const apiVersion of byApiVersion.keys()) {
+    if (!apiVersion.includes("/")) continue;
+    const group = apiVersion.slice(0, apiVersion.indexOf("/"));
+    if (!groups.has(group)) groups.set(group, apiVersion);
+  }
+
+  const layer = fakeRequestLayer((request) => {
+    const custom = options.respond?.(request);
+    if (custom !== undefined) return custom;
+
+    if (request.path === "/api") return { body: { kind: "APIVersions", versions: ["v1"] } };
+    if (request.path === "/apis") {
+      return {
+        body: {
+          kind: "APIGroupList",
+          groups: [...groups].map(([name, apiVersion]) => ({
+            name,
+            preferredVersion: { groupVersion: apiVersion, version: apiVersion.split("/")[1] },
+            versions: [{ groupVersion: apiVersion }],
+          })),
+        },
+      };
+    }
+
+    const apiVersion = apiVersionFromDiscoveryPath(request.path);
+    if (apiVersion) {
+      const served = byApiVersion.get(apiVersion);
+      if (!served) return { status: 404, body: statusBody(404, "NotFound", "the server could not find the requested resource") };
+      return {
+        body: apiResourceList(
+          apiVersion,
+          served.map((r) => ({ name: r.plural, kind: r.kind, namespaced: r.namespaced })),
+        ),
+      };
+    }
+
+    const object = byPath.get(request.path);
+    if (object) return { body: object };
+
+    if (isListPath(request.path, resources)) {
+      return { body: { kind: "List", items: listPaths.get(request.path) ?? [], metadata: {} } };
+    }
+
+    return { status: 404, body: statusBody(404, "NotFound", `${request.path} not found`) };
+  });
+
+  const connects: ConnectOptions[] = [];
+  const connector: K8sConnector = async (connectOptions): Promise<ConnectedClient> => {
+    connects.push(connectOptions);
+    const client = await createK8sClient({
+      kubeconfig: options.kubeconfig ?? fakeKubeconfig(),
+      requestLayer: layer,
+      ...(connectOptions.context ? { context: connectOptions.context } : {}),
+      ...connectOptions.client,
+    });
+    return { client, target: { source: "ambient" } };
+  };
+
+  return { connector, layer, connects };
+}
+
+function splitKey(key: string): [group: string, version: string, kind: string, namespace: string, name: string] {
+  const parts = key.split("/");
+  // `apps/v1/Deployment/prod/web` (5) or `v1/Service/prod/web` (4)
+  if (parts.length === 5) return [parts[0], parts[1], parts[2], parts[3], parts[4]];
+  return ["", parts[0], parts[1], parts[2], parts[3]];
+}
+
+function apiVersionFromDiscoveryPath(path: string): string | undefined {
+  if (/^\/api\/[^/]+$/.test(path)) return path.slice("/api/".length);
+  if (/^\/apis\/[^/]+\/[^/]+$/.test(path)) return path.slice("/apis/".length);
+  return undefined;
+}
+
+/** True when the path addresses a collection of a kind this cluster serves. */
+function isListPath(path: string, resources: ServedResource[]): boolean {
+  const plural = path.split("/").pop();
+  return resources.some((r) => r.plural === plural);
+}

package/src/api/operation-surface.test.ts

@@ -0,0 +1,116 @@
+/**
+ * The generated operation surface (chant #1074) — and the anti-skew gate that
+ * is the whole reason it is generated rather than written.
+ *
+ * The issue's requirement is that the client's addressing and the declarable
+ * types come out of the same codegen pass "so types and client cannot skew".
+ * Generating them together is the mechanism; this file is the proof, and it is
+ * what would fail if someone later added a resource to one artifact and not the
+ * other.
+ */
+
+import { describe, test, expect } from "vitest";
+import { createRequire } from "module";
+import { addressableEntityTypes, deriveOperation, operationFor, operationTable, pluralizeKind } from "./operation-surface";
+
+const require = createRequire(import.meta.url);
+
+interface RegistryEntry {
+  resourceType: string;
+  kind: "resource" | "property";
+  apiVersion?: string;
+  gvkKind?: string;
+}
+
+const registry = require("../generated/lexicon-k8s.json") as Record<string, RegistryEntry>;
+
+describe("operation surface ↔ declarable registry (the anti-skew gate)", () => {
+  test("every registry resource with a GVK has an operation entry saying the same thing", () => {
+    const table = operationTable();
+    const missing: string[] = [];
+    const disagreeing: string[] = [];
+
+    for (const entry of Object.values(registry)) {
+      if (entry.kind !== "resource" || !entry.apiVersion || !entry.gvkKind) continue;
+      const operation = table[entry.resourceType];
+      if (!operation) {
+        missing.push(entry.resourceType);
+        continue;
+      }
+      if (operation.apiVersion !== entry.apiVersion || operation.kind !== entry.gvkKind) {
+        disagreeing.push(
+          `${entry.resourceType}: registry ${entry.apiVersion}/${entry.gvkKind} vs operations ${operation.apiVersion}/${operation.kind}`,
+        );
+      }
+    }
+
+    expect(missing, "resources the serializer can emit but the client cannot address").toEqual([]);
+    expect(disagreeing, "resources the serializer and the client disagree about").toEqual([]);
+  });
+
+  test("no operation entry names a type the registry does not carry", () => {
+    const known = new Set(Object.values(registry).map((e) => e.resourceType));
+    const orphans = addressableEntityTypes().filter((t) => !known.has(t));
+    expect(orphans, "operation entries with no declarable type behind them").toEqual([]);
+  });
+
+  test("coverage is an order of magnitude past the twenty-entry map it replaces", () => {
+    // The retired KUBECTL_RESOURCE had 20 entries and every CRD fell off it.
+    expect(addressableEntityTypes().length).toBeGreaterThan(150);
+  });
+});
+
+describe("addressing", () => {
+  test.each([
+    ["K8s::Apps::Deployment", "apps/v1", "Deployment", "deployments", "Namespaced"],
+    ["K8s::Core::Pod", "v1", "Pod", "pods", "Namespaced"],
+    ["K8s::Core::Namespace", "v1", "Namespace", "namespaces", "Cluster"],
+    ["K8s::Rbac::ClusterRole", "rbac.authorization.k8s.io/v1", "ClusterRole", "clusterroles", "Cluster"],
+    ["K8s::Networking::Ingress", "networking.k8s.io/v1", "Ingress", "ingresses", "Namespaced"],
+    ["K8s::Batch::CronJob", "batch/v1", "CronJob", "cronjobs", "Namespaced"],
+  ])("%s → %s %s /%s (%s)", (entityType, apiVersion, kind, plural, scope) => {
+    expect(operationFor(entityType)).toMatchObject({ apiVersion, kind, plural, scope });
+  });
+
+  // Every one of these was `unsupported-kind` before #1074.
+  test.each([
+    ["K8s::Ray::RayCluster", "ray.io/v1", "RayCluster", "rayclusters"],
+    ["K8s::Argo::Application", "argoproj.io/v1alpha1", "Application", "applications"],
+    ["K8s::CertManager::Certificate", "cert-manager.io/v1", "Certificate", "certificates"],
+    ["K8s::Monitoring::ServiceMonitor", "monitoring.coreos.com/v1", "ServiceMonitor", "servicemonitors"],
+  ])("CRD %s → %s %s /%s", (entityType, apiVersion, kind, plural) => {
+    expect(operationFor(entityType)).toMatchObject({ apiVersion, kind, plural });
+  });
+
+  test("the plural and scope come from the schema, not from a guess", () => {
+    // `ingresses`, not `ingresss`; `namespaces` cluster-scoped, not namespaced.
+    const ingress = operationFor("K8s::Networking::Ingress")!;
+    expect(ingress.plural).toBe("ingresses");
+    expect(operationFor("K8s::Core::Namespace")!.scope).toBe("Cluster");
+    // And verbs are documented rather than assumed.
+    expect(ingress.verbs).toContain("get");
+  });
+
+  test("an entity type in no known API group is not guessed at", () => {
+    expect(operationFor("K8s::NotAGroupChantKnows::Thing")).toBeUndefined();
+    expect(operationFor("AWS::S3::Bucket")).toBeUndefined();
+    expect(operationFor("nonsense")).toBeUndefined();
+  });
+
+  test("derivation covers a checkout with no generated artifacts", () => {
+    expect(deriveOperation("K8s::Apps::Deployment")).toMatchObject({ apiVersion: "apps/v1", kind: "Deployment" });
+    expect(deriveOperation("K8s::Ray::RayCluster")).toBeUndefined();
+  });
+});
+
+describe("pluralizeKind", () => {
+  test.each([
+    ["Deployment", "deployments"],
+    ["Ingress", "ingresses"],
+    ["NetworkPolicy", "networkpolicies"],
+    ["Endpoints", "endpointses"],
+    ["Gateway", "gateways"],
+  ])("%s → %s", (kind, plural) => {
+    expect(pluralizeKind(kind)).toBe(plural);
+  });
+});

package/src/api/operation-surface.ts

@@ -0,0 +1,129 @@
+/**
+ * Reading the generated operation surface — chant #1074.
+ *
+ * The table itself is written by `chant generate` (see
+ * `../codegen/generate-operations.ts`); this is the runtime side, and it is
+ * deliberately the only place in the lexicon that knows how an entity type
+ * becomes an API address.
+ *
+ * Loading mirrors the serializer's handling of `lexicon-k8s.json`: a `require`
+ * behind a try/catch, so a checkout that has not run `chant generate` yet
+ * degrades to derivation rather than failing to import. Nothing here touches
+ * the filesystem at module load (chant #1081) — the first call does, and caches.
+ */
+
+import { createRequire } from "module";
+
+const require = createRequire(import.meta.url);
+
+/** One resource's addressing information, as `chant generate` emits it. */
+export interface K8sOperationDescriptor {
+  /** chant entity type, e.g. `K8s::Apps::Deployment`. */
+  entityType: string;
+  /** `v1`, `apps/v1`, `ray.io/v1` — what goes in a manifest. */
+  apiVersion: string;
+  /** `Deployment`, `RayCluster`. */
+  kind: string;
+  /** Plural path segment the schema documents, e.g. `deployments`. */
+  plural: string;
+  scope: "Namespaced" | "Cluster";
+  /** Verbs the schema documents for the named-object path. */
+  verbs: string[];
+}
+
+/** The generated file's shape: entity type → descriptor. */
+export type K8sOperationTable = Record<string, K8sOperationDescriptor>;
+
+/**
+ * Fallback plural for a kind whose schema documented no named-object path.
+ *
+ * Kubernetes' own pluralization for resource names is the lowercased kind with
+ * English plural rules applied — the three cases `kubectl` implements. It only
+ * fires for kinds the OpenAPI paths do not cover, and the live client overrides
+ * it from the cluster's discovery regardless, so it is a placeholder rather
+ * than a second table to maintain.
+ */
+export function pluralizeKind(kind: string): string {
+  const lower = kind.toLowerCase();
+  if (/(s|x|z|ch|sh)$/.test(lower)) return `${lower}es`;
+  if (/[^aeiou]y$/.test(lower)) return `${lower.slice(0, -1)}ies`;
+  return `${lower}s`;
+}
+
+/**
+ * Well-known API group → apiVersion, for a checkout with no generated table.
+ * Deliberately the same list the serializer falls back to, so a lexicon
+ * running without generated artifacts addresses what it serializes.
+ */
+const FALLBACK_GROUP_VERSIONS: Record<string, string> = {
+  Core: "v1",
+  Apps: "apps/v1",
+  Batch: "batch/v1",
+  Networking: "networking.k8s.io/v1",
+  Policy: "policy/v1",
+  Rbac: "rbac.authorization.k8s.io/v1",
+  Storage: "storage.k8s.io/v1",
+  Autoscaling: "autoscaling/v2",
+  Admissionregistration: "admissionregistration.k8s.io/v1",
+};
+
+let cached: K8sOperationTable | null = null;
+
+/** The generated table, loaded once. Empty when nothing has been generated. */
+export function operationTable(): K8sOperationTable {
+  if (cached) return cached;
+  try {
+    cached = require("../generated/operations.json") as K8sOperationTable;
+  } catch {
+    cached = {};
+  }
+  return cached;
+}
+
+/** Reset the memoized table. Tests only. */
+export function resetOperationTableForTests(): void {
+  cached = null;
+}
+
+/**
+ * How to address a declared entity type over the API.
+ *
+ * Returns undefined only for a type the generated surface does not carry and
+ * whose `K8s::<Group>::<Kind>` shape yields no known group — which is the one
+ * case where chant genuinely does not know what to ask for. Every generated
+ * resource type, including every CRD baked in at generation time, is in the
+ * table; that is the difference between this and the twenty-entry map it
+ * replaces.
+ */
+export function operationFor(entityType: string): K8sOperationDescriptor | undefined {
+  const table = operationTable();
+  const found = table[entityType];
+  if (found) return found;
+  return deriveOperation(entityType);
+}
+
+/**
+ * Last-resort derivation from the entity type's own shape, for a lexicon
+ * running without generated artifacts. It cannot invent an API group it has
+ * never seen, so an unknown group returns undefined rather than a guess that
+ * would address the wrong thing.
+ */
+export function deriveOperation(entityType: string): K8sOperationDescriptor | undefined {
+  const parts = entityType.split("::");
+  if (parts.length !== 3 || parts[0] !== "K8s") return undefined;
+  const apiVersion = FALLBACK_GROUP_VERSIONS[parts[1]];
+  if (!apiVersion) return undefined;
+  return {
+    entityType,
+    apiVersion,
+    kind: parts[2],
+    plural: pluralizeKind(parts[2]),
+    scope: "Namespaced",
+    verbs: [],
+  };
+}
+
+/** Every entity type the generated surface can address. */
+export function addressableEntityTypes(): string[] {
+  return Object.keys(operationTable()).sort();
+}

package/src/api/owner-chain.test.ts

@@ -0,0 +1,171 @@
+import { describe, test, expect, vi } from "vitest";
+import { resolveK8sOwnerChain } from "./owner-chain";
+import type { K8sObject } from "@intentius/chant-k8s-client";
+
+function pod(uid: string, ownerRefs?: Array<Record<string, unknown>>): K8sObject {
+  return {
+    apiVersion: "v1",
+    kind: "Pod",
+    metadata: { name: "p", namespace: "prod", uid, ...(ownerRefs ? { ownerReferences: ownerRefs } : {}) },
+  };
+}
+
+function ownerRef(kind: string, name: string, uid: string, controller = true): Record<string, unknown> {
+  return { apiVersion: "apps/v1", kind, name, uid, controller };
+}
+
+describe("resolveK8sOwnerChain (#1077)", () => {
+  test("no ownerReferences at all → unowned", async () => {
+    const reader = { readIfPresent: vi.fn() };
+    const result = await resolveK8sOwnerChain(pod("pod-uid"), {
+      declaredByUid: new Map(),
+      reader,
+      namespace: "prod",
+    });
+    expect(result).toEqual({ root: "unowned" });
+    expect(reader.readIfPresent).not.toHaveBeenCalled();
+  });
+
+  test("owner uid matches a declared entity directly → declared, no extra reads", async () => {
+    const reader = { readIfPresent: vi.fn() };
+    const result = await resolveK8sOwnerChain(pod("pod-uid", [ownerRef("Deployment", "web", "deploy-uid")]), {
+      declaredByUid: new Map([["deploy-uid", "web"]]),
+      reader,
+      namespace: "prod",
+    });
+    expect(result).toEqual({ root: "declared", entity: "web" });
+    expect(reader.readIfPresent).not.toHaveBeenCalled();
+  });
+
+  test("Pod → ReplicaSet (undeclared, read live) → Deployment (declared) resolves through the intermediate hop", async () => {
+    const replicaSet: K8sObject = {
+      apiVersion: "apps/v1",
+      kind: "ReplicaSet",
+      metadata: {
+        name: "web-7d9f8c9c8",
+        namespace: "prod",
+        uid: "rs-uid",
+        ownerReferences: [ownerRef("Deployment", "web", "deploy-uid")],
+      },
+    };
+    const reader = { readIfPresent: vi.fn().mockResolvedValue(replicaSet) };
+    const result = await resolveK8sOwnerChain(pod("pod-uid", [ownerRef("ReplicaSet", "web-7d9f8c9c8", "rs-uid")]), {
+      declaredByUid: new Map([["deploy-uid", "web"]]),
+      reader,
+      namespace: "prod",
+    });
+    expect(result).toEqual({ root: "declared", entity: "web" });
+    expect(reader.readIfPresent).toHaveBeenCalledTimes(1);
+    expect(reader.readIfPresent).toHaveBeenCalledWith({
+      apiVersion: "apps/v1",
+      kind: "ReplicaSet",
+      name: "web-7d9f8c9c8",
+      namespace: "prod",
+    });
+  });
+
+  test("chain resolves fully to a live, undeclared root → foreign", async () => {
+    const replicaSet: K8sObject = {
+      apiVersion: "apps/v1",
+      kind: "ReplicaSet",
+      metadata: { name: "other-rs", namespace: "prod", uid: "rs-uid" }, // no further owner
+    };
+    const reader = { readIfPresent: vi.fn().mockResolvedValue(replicaSet) };
+    const result = await resolveK8sOwnerChain(pod("pod-uid", [ownerRef("ReplicaSet", "other-rs", "rs-uid")]), {
+      declaredByUid: new Map(), // nothing declared at all
+      reader,
+      namespace: "prod",
+    });
+    expect(result).toEqual({ root: "foreign" });
+  });
+
+  test("an owner read that 404s (readIfPresent → undefined) is conservative unknown, not foreign", async () => {
+    const reader = { readIfPresent: vi.fn().mockResolvedValue(undefined) };
+    const result = await resolveK8sOwnerChain(pod("pod-uid", [ownerRef("ReplicaSet", "gone-rs", "rs-uid")]), {
+      declaredByUid: new Map(),
+      reader,
+      namespace: "prod",
+    });
+    expect(result).toEqual({ root: "unknown" });
+  });
+
+  test("an owner read that throws (RBAC denial, transport error) is conservative unknown", async () => {
+    const reader = { readIfPresent: vi.fn().mockRejectedValue(new Error("Forbidden")) };
+    const result = await resolveK8sOwnerChain(pod("pod-uid", [ownerRef("ReplicaSet", "denied-rs", "rs-uid")]), {
+      declaredByUid: new Map(),
+      reader,
+      namespace: "prod",
+    });
+    expect(result).toEqual({ root: "unknown" });
+  });
+
+  test("a cycle (A owns B, B owns A) terminates and classifies unknown rather than looping forever", async () => {
+    const objA: K8sObject = {
+      apiVersion: "v1",
+      kind: "Widget",
+      metadata: { name: "a", namespace: "prod", uid: "a-uid", ownerReferences: [ownerRef("Widget", "b", "b-uid")] },
+    };
+    const objB: K8sObject = {
+      apiVersion: "v1",
+      kind: "Widget",
+      metadata: { name: "b", namespace: "prod", uid: "b-uid", ownerReferences: [ownerRef("Widget", "a", "a-uid")] },
+    };
+    const reader = {
+      readIfPresent: vi.fn(async ({ name }: { name: string }) => (name === "a" ? objA : objB)),
+    };
+    const start: K8sObject = {
+      apiVersion: "v1",
+      kind: "Widget",
+      metadata: { name: "start", namespace: "prod", uid: "start-uid", ownerReferences: [ownerRef("Widget", "a", "a-uid")] },
+    };
+    const result = await resolveK8sOwnerChain(start, { declaredByUid: new Map(), reader, namespace: "prod" });
+    expect(result).toEqual({ root: "unknown" });
+  });
+
+  test("respects a custom maxDepth, fetching no more than maxDepth + 1 objects", async () => {
+    // A chain 5 hops deep, but bounded to 2 — never reaches the declared root.
+    const objects: Record<string, K8sObject> = {};
+    for (let i = 0; i < 5; i++) {
+      objects[`n${i}`] = {
+        apiVersion: "v1",
+        kind: "Widget",
+        metadata: { name: `n${i}`, namespace: "prod", uid: `uid-${i}`, ownerReferences: [ownerRef("Widget", `n${i + 1}`, `uid-${i + 1}`)] },
+      };
+    }
+    const reader = {
+      readIfPresent: vi.fn(async ({ name }: { name: string }) => objects[name]),
+    };
+    const start: K8sObject = {
+      apiVersion: "v1",
+      kind: "Widget",
+      metadata: { name: "start", namespace: "prod", uid: "start-uid", ownerReferences: [ownerRef("Widget", "n0", "uid-0")] },
+    };
+    const result = await resolveK8sOwnerChain(start, {
+      declaredByUid: new Map([["uid-4", "deep-entity"]]), // reachable, but past the bound
+      reader,
+      namespace: "prod",
+      maxDepth: 2,
+    });
+    expect(result).toEqual({ root: "unknown" });
+    expect(reader.readIfPresent.mock.calls.length).toBeLessThanOrEqual(3); // maxDepth + 1
+  });
+
+  test("a starting object without a uid cannot be classified — unknown", async () => {
+    const reader = { readIfPresent: vi.fn() };
+    const noUid: K8sObject = { apiVersion: "v1", kind: "Pod", metadata: { name: "p", namespace: "prod" } };
+    const result = await resolveK8sOwnerChain(noUid, { declaredByUid: new Map(), reader, namespace: "prod" });
+    expect(result).toEqual({ root: "unknown" });
+    expect(reader.readIfPresent).not.toHaveBeenCalled();
+  });
+
+  test("picks the controller:true owner reference when several are present", async () => {
+    const reader = { readIfPresent: vi.fn() };
+    const refs = [ownerRef("OtherOwner", "shared", "shared-uid", false), ownerRef("Deployment", "web", "deploy-uid", true)];
+    const result = await resolveK8sOwnerChain(pod("pod-uid", refs), {
+      declaredByUid: new Map([["deploy-uid", "web"]]),
+      reader,
+      namespace: "prod",
+    });
+    expect(result).toEqual({ root: "declared", entity: "web" });
+  });
+});