@intentius/chant 0.31.0 → 0.33.0

package/src/managed-fields.ts

@@ -0,0 +1,328 @@
+/**
+ * Kubernetes-object-shape utilities shared by every lexicon whose live model
+ * is a Kubernetes API object — the k8s lexicon itself (chant #1076) and GCP's
+ * Config Connector custom resources (chant #1087).
+ *
+ * A Config Connector custom resource *is* a Kubernetes object: it carries the
+ * same envelope (`status`, `metadata.{uid,resourceVersion,generation,
+ * creationTimestamp,managedFields,selfLink}`), the same SSA `fieldsV1`
+ * encoding for `metadata.managedFields`, and some CNRM kinds even embed
+ * genuinely k8s-shaped substructures (Cloud Run's `RunService` wraps a
+ * Knative pod spec with `containers`/`env`/`ports`, keyed the same way a
+ * Deployment's are). None of that is specific to chant's k8s *lexicon* — it
+ * is a fact about the Kubernetes API that any reader of a Kubernetes-shaped
+ * object needs, regardless of which lexicon is doing the reading.
+ *
+ * This module lives in core rather than in the k8s lexicon for the same
+ * reason `./kubectl-context.ts`'s `resolveClusterTarget` does (chant #1100):
+ * GCP's observation needs it too, without taking a dependency on the k8s
+ * lexicon package. Nothing here is keyed by chant's own k8s entityType
+ * catalog (`K8s::Apps::Deployment`, …) or by any lexicon's service-default
+ * table — that stays lexicon-specific, layered on top of what's here
+ * (`lexicons/k8s/src/deep-observe-hooks.ts`'s `K8S_SERVICE_DEFAULTS`,
+ * `lexicons/gcp/src/deep-observe.ts`'s CNRM-specific annotation noise).
+ */
+
+import type { DeepArrayElement, DeepNode } from "./deep-observation";
+
+// ── The generic Kubernetes object envelope ──────────────────────────────────
+
+/**
+ * Paths every Kubernetes API object carries regardless of kind, matched on
+ * the exact index-erased pattern (there is exactly one `status`, one
+ * `metadata.managedFields`, per object — no per-type variation the way AWS's
+ * `Arn`/`RoleId` repeat at every nesting depth).
+ *
+ * - `status` — the whole subtree is server-computed; no declarative source
+ *   (chant's k8s manifests, chant's Config Connector CRs) ever authors it.
+ * - `metadata.uid`/`resourceVersion`/`generation`/`creationTimestamp` — minted
+ *   and incremented by the API server, never authored.
+ * - `metadata.managedFields` — the bookkeeping the ownership walk below reads
+ *   to decide everything else. Left in the tree it would report as permanent
+ *   drift (a timestamp changes on every write) and would recurse into the
+ *   encoded `fieldsV1` structure as if it were ordinary properties.
+ * - `metadata.selfLink` — deprecated API-server bookkeeping some clusters
+ *   still echo; never a declared field.
+ */
+export const K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS: ReadonlySet<string> = new Set([
+  "status",
+  "metadata.uid",
+  "metadata.resourceVersion",
+  "metadata.generation",
+  "metadata.creationTimestamp",
+  "metadata.managedFields",
+  "metadata.selfLink",
+]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** 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 (
+    JSON.stringify(value, (_k, v: unknown) =>
+      v && typeof v === "object" && !Array.isArray(v)
+        ? Object.fromEntries(Object.entries(v as Record<string, unknown>).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+        : v,
+    ) ?? ""
+  );
+}
+
+/** The final segment of an index-erased pattern (`spec.template.spec.containers[].env[].name` → `name`'s *container*, i.e. `env`). */
+function lastSegment(pattern: string): string {
+  const withoutIndex = pattern.replace(/\[\]$/, "");
+  const dot = withoutIndex.lastIndexOf(".");
+  return dot === -1 ? withoutIndex : withoutIndex.slice(dot + 1);
+}
+
+/**
+ * Kubernetes' own well-known list-map-key conventions for the substructures
+ * that recur across kinds and across lexicons: containers/initContainers/
+ * ephemeralContainers and `env`/`volumes` keyed by `name` — the same field
+ * Kubernetes' strategic-merge-patch and SSA's `list-map-keys` key on for
+ * these lists — and container ports keyed by `containerPort`+`protocol`,
+ * Service ports keyed by `port`+`protocol` (Kubernetes' own SSA
+ * `list-map-keys` for each). Both port shapes are handled under one `ports`
+ * branch by checking which field is present.
+ *
+ * Entity-type-agnostic on purpose: whether an array named `containers`
+ * belongs to a `K8s::Apps::Deployment` or to a GCP `RunService`'s embedded
+ * pod spec, the identity Kubernetes assigns each element is the same.
+ */
+export function k8sListMapOrderKey(element: DeepArrayElement): string | undefined {
+  const name = lastSegment(element.pattern);
+  const el = element.element;
+
+  if (name === "containers" || name === "initContainers" || name === "ephemeralContainers") {
+    return isRecord(el) && typeof el.name === "string" ? el.name : canonicalJson(el);
+  }
+  if (name === "env" || name === "volumes") {
+    return isRecord(el) && typeof el.name === "string" ? el.name : canonicalJson(el);
+  }
+  if (name === "ports") {
+    if (isRecord(el)) {
+      const protocol = typeof el.protocol === "string" ? el.protocol : "TCP";
+      // Zero-padded so the sort key orders numerically, not lexicographically
+      // ("443" would otherwise sort before "80") — cosmetic, since either
+      // order canonicalizes the two sides identically, but a stable,
+      // human-sensible order is free to have here.
+      if (typeof el.containerPort === "number") return `${String(el.containerPort).padStart(5, "0")}/${protocol}`;
+      if (typeof el.port === "number") return `${String(el.port).padStart(5, "0")}/${protocol}`;
+    }
+    return canonicalJson(el);
+  }
+
+  return undefined;
+}
+
+// ── managedFields ownership ─────────────────────────────────────────────────
+
+/**
+ * The structural shape of one `metadata.managedFields` entry this module
+ * needs. Matches `@intentius/chant-k8s-client`'s `ManagedFieldsEntry`
+ * (chant #1075) field-for-field, but is declared independently here rather
+ * than imported from that package: core must stay reachable from any
+ * lexicon's build path, and the k8s client package is deliberately *not*
+ * reachable from one (chant #1074's structural boundary,
+ * `examples/k8s-client-boundary.test.ts`). A caller that already has a real
+ * `ManagedFieldsEntry[]` (the k8s lexicon) passes it straight through —
+ * TypeScript's structural typing accepts it with no cast.
+ */
+export interface ManagedFieldsEntryLike {
+  manager?: string;
+  operation?: string;
+  subresource?: string;
+  fieldsV1?: Record<string, unknown>;
+}
+
+/** One live object's managed-fields ownership, resolved to chant dot-paths. */
+export interface OwnershipSets {
+  /** Paths any chant field manager owns on this object. */
+  chantOwned: ReadonlySet<string>;
+  /** Paths owned by a manager that is not chant. */
+  foreignOwned: ReadonlySet<string>;
+  /** The subset of `foreignOwned` where the declared manifest also sets the path — drift-relevant despite foreign ownership. */
+  foreignContested: ReadonlySet<string>;
+}
+
+function sameJson(a: unknown, b: unknown): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+function findKeyedIndex(array: readonly unknown[], keyFields: Record<string, unknown>): number {
+  return array.findIndex(
+    (el) => isRecord(el) && Object.entries(keyFields).every(([k, v]) => sameJson(el[k], v)),
+  );
+}
+
+function findValueIndex(array: readonly unknown[], value: unknown): number {
+  return array.findIndex((el) => sameJson(el, value));
+}
+
+function joinField(parent: string, name: string): string {
+  return parent ? `${parent}.${name}` : name;
+}
+
+function joinIndex(parent: string, index: number): string {
+  return `${parent}[${index}]`;
+}
+
+/**
+ * Walk one manager's `fieldsV1` tree in lockstep with the live object and the
+ * declared props, threading the *live* dot-path (chant's own path syntax —
+ * no leading dot, real array indices) as it goes. `owned` collects every path
+ * this manager's entry reaches on the live tree; `contested` collects the
+ * subset where the declared tree also has a value at the equivalent
+ * position, resolved by the same key/value match rather than by index.
+ *
+ * Only `f:`/`i:`/`v:`/`k:`/`.` are understood — the same five forms
+ * `@intentius/chant-k8s-client`'s `managed-fields.ts`'s `renderSegment`
+ * renders — and an unrecognized prefix is skipped, consistent with that
+ * module's own behavior, rather than guessed at.
+ */
+function walkOwnership(
+  fieldsNode: unknown,
+  liveNode: unknown,
+  declaredNode: unknown,
+  path: string,
+  owned: Set<string>,
+  contested: Set<string>,
+): void {
+  if (fieldsNode === null || typeof fieldsNode !== "object" || Array.isArray(fieldsNode)) return;
+
+  for (const [key, child] of Object.entries(fieldsNode as Record<string, unknown>)) {
+    if (key === ".") {
+      if (path !== "") {
+        owned.add(path);
+        if (declaredNode !== undefined) contested.add(path);
+      }
+      continue;
+    }
+
+    if (key.startsWith("f:")) {
+      const name = key.slice(2);
+      if (!isRecord(liveNode) || !(name in liveNode)) continue;
+      const childLive = liveNode[name];
+      const childDeclared = isRecord(declaredNode) ? declaredNode[name] : undefined;
+      const childPath = joinField(path, name);
+      owned.add(childPath);
+      if (childDeclared !== undefined) contested.add(childPath);
+      walkOwnership(child, childLive, childDeclared, childPath, owned, contested);
+      continue;
+    }
+
+    if (key.startsWith("i:")) {
+      const idx = Number(key.slice(2));
+      if (!Array.isArray(liveNode) || !Number.isInteger(idx) || idx < 0 || idx >= liveNode.length) continue;
+      const childLive: unknown = liveNode[idx];
+      const childDeclared = Array.isArray(declaredNode) ? declaredNode[idx] : undefined;
+      const childPath = joinIndex(path, idx);
+      owned.add(childPath);
+      if (childDeclared !== undefined) contested.add(childPath);
+      walkOwnership(child, childLive, childDeclared, childPath, owned, contested);
+      continue;
+    }
+
+    if (key.startsWith("v:") || key.startsWith("k:")) {
+      if (!Array.isArray(liveNode)) continue;
+      let decoded: unknown;
+      try {
+        decoded = JSON.parse(key.slice(2));
+      } catch {
+        continue; // not decodable JSON — skip rather than mangle, like renderSegment.
+      }
+
+      const liveIdx =
+        key.startsWith("v:")
+          ? findValueIndex(liveNode, decoded)
+          : isRecord(decoded)
+            ? findKeyedIndex(liveNode, decoded)
+            : -1;
+      if (liveIdx === -1) continue;
+
+      let childDeclared: unknown;
+      if (Array.isArray(declaredNode)) {
+        const declaredIdx = key.startsWith("v:")
+          ? findValueIndex(declaredNode, decoded)
+          : isRecord(decoded)
+            ? findKeyedIndex(declaredNode, decoded)
+            : -1;
+        childDeclared = declaredIdx === -1 ? undefined : declaredNode[declaredIdx];
+      }
+
+      const childLive: unknown = liveNode[liveIdx];
+      const childPath = joinIndex(path, liveIdx);
+      owned.add(childPath);
+      if (childDeclared !== undefined) contested.add(childPath);
+      walkOwnership(child, childLive, childDeclared, childPath, owned, contested);
+      continue;
+    }
+    // An unrecognized prefix (a future fieldsV1 encoding) — skip.
+  }
+}
+
+/**
+ * Build the three ownership sets for one live object. `entries` is
+ * `metadata.managedFields`, already decoded (`@intentius/chant-k8s-client`'s
+ * `managedFieldsOf` for the k8s lexicon; a plain `JSON.parse` of `kubectl get
+ * -o json` for gcp); `isChantManager` classifies each entry's manager name
+ * — matched on the `chant`/`chant:<stack>` family per chant #1075, but the
+ * matcher itself is supplied by the caller rather than fixed here, because
+ * what counts as "chant" is not the same fact on every lexicon's apply path
+ * (see gcp's `deep-observe.ts` module doc for why that matters there).
+ *
+ * Subresource entries (`status`, `scale`) are excluded: a controller writing
+ * a Deployment's `status` is not competing for the spec chant declared, the
+ * same reasoning `@intentius/chant-k8s-client`'s `fieldsOwnedBy` default
+ * already encodes.
+ */
+export function buildOwnershipSets(
+  entries: readonly ManagedFieldsEntryLike[],
+  liveRoot: Record<string, unknown>,
+  declaredRoot: Record<string, unknown>,
+  isChantManager: (manager: string | undefined) => boolean,
+): OwnershipSets {
+  const chantOwned = new Set<string>();
+  const foreignOwned = new Set<string>();
+  const foreignContested = new Set<string>();
+
+  for (const entry of entries) {
+    if (typeof entry.manager !== "string" || entry.manager.length === 0) continue;
+    if (entry.subresource !== undefined) continue;
+
+    if (isChantManager(entry.manager)) {
+      // Chant-owned paths are always diffable, regardless of who else is
+      // involved — "contested" only matters for a *foreign* owner.
+      walkOwnership(entry.fieldsV1, liveRoot, declaredRoot, "", chantOwned, new Set());
+    } else {
+      walkOwnership(entry.fieldsV1, liveRoot, declaredRoot, "", foreignOwned, foreignContested);
+    }
+  }
+
+  return { chantOwned, foreignOwned, foreignContested };
+}
+
+/**
+ * The three-question managed-fields prune rule, as a predicate over a
+ * {@link DeepNode} plus one object's precomputed {@link OwnershipSets} —
+ * shared by every lexicon layering a per-resource managed-fields prune on
+ * top of its own static rules (k8s's `perResourceHooks`, gcp's equivalent):
+ *
+ * 1. Chant owns the path (any chant manager) → never pruned by this rule.
+ * 2. A different manager owns it, chant does not, and it is not declared →
+ *    controller-managed noise, pruned.
+ * 3. It is declared, regardless of who owns it live → never pruned by this
+ *    rule, because chant's source is a statement of intent independent of
+ *    which write currently holds the field.
+ *
+ * Only applies to the live side — the declared tree carries no managedFields
+ * to prune by.
+ */
+export function pruneByOwnership(node: DeepNode, sets: OwnershipSets): boolean {
+  if (node.side !== "live") return false;
+  if (sets.chantOwned.has(node.path)) return false;
+  if (!sets.foreignOwned.has(node.path)) return false;
+  if (sets.foreignContested.has(node.path)) return false;
+  return true;
+}

package/src/owner-chain.test.ts

@@ -0,0 +1,97 @@
+import { describe, test, expect } from "vitest";
+import { classifyOwnerChain, DEFAULT_MAX_OWNER_CHAIN_DEPTH, type OwnerChainNode } from "./owner-chain";
+
+describe("classifyOwnerChain (#1077)", () => {
+  test("owned chain reaching a declared entity → declared", () => {
+    // pod -> replicaSet -> deployment (declared)
+    const nodes = new Map<string, OwnerChainNode>([
+      ["pod-uid", { ownerId: "rs-uid" }],
+      ["rs-uid", { ownerId: "deploy-uid" }],
+      ["deploy-uid", { declaredEntity: "web" }],
+    ]);
+    expect(classifyOwnerChain("pod-uid", nodes)).toEqual({ root: "declared", entity: "web" });
+  });
+
+  test("a node that is itself declared resolves immediately", () => {
+    const nodes = new Map<string, OwnerChainNode>([["deploy-uid", { declaredEntity: "web" }]]);
+    expect(classifyOwnerChain("deploy-uid", nodes)).toEqual({ root: "declared", entity: "web" });
+  });
+
+  test("no owner reference at all → unowned", () => {
+    const nodes = new Map<string, OwnerChainNode>([["pod-uid", {}]]);
+    expect(classifyOwnerChain("pod-uid", nodes)).toEqual({ root: "unowned" });
+  });
+
+  test("chain fully resolves to a live, undeclared root → foreign", () => {
+    // pod -> replicaSet -> deployment, but the deployment is not declared
+    const nodes = new Map<string, OwnerChainNode>([
+      ["pod-uid", { ownerId: "rs-uid" }],
+      ["rs-uid", { ownerId: "deploy-uid" }],
+      ["deploy-uid", {}],
+    ]);
+    expect(classifyOwnerChain("pod-uid", nodes)).toEqual({ root: "foreign" });
+  });
+
+  test("the starting node itself could not be read → unknown", () => {
+    const nodes = new Map<string, OwnerChainNode>([["pod-uid", { ownerUnreadable: true }]]);
+    expect(classifyOwnerChain("pod-uid", nodes)).toEqual({ root: "unknown" });
+  });
+
+  test("an intermediate owner could not be read → unknown, conservative (never foreign, never declared)", () => {
+    const nodes = new Map<string, OwnerChainNode>([
+      ["pod-uid", { ownerId: "rs-uid" }],
+      ["rs-uid", { ownerUnreadable: true }],
+    ]);
+    expect(classifyOwnerChain("pod-uid", nodes)).toEqual({ root: "unknown" });
+  });
+
+  test("an owner reference naming a node never resolved into the map → unknown", () => {
+    const nodes = new Map<string, OwnerChainNode>([["pod-uid", { ownerId: "rs-uid" }]]);
+    expect(classifyOwnerChain("pod-uid", nodes)).toEqual({ root: "unknown" });
+  });
+
+  test("the starting id itself is not in the map → unknown", () => {
+    expect(classifyOwnerChain("nope", new Map())).toEqual({ root: "unknown" });
+  });
+
+  test("a cycle is detected and classified unknown, not an infinite loop", () => {
+    const nodes = new Map<string, OwnerChainNode>([
+      ["a", { ownerId: "b" }],
+      ["b", { ownerId: "a" }],
+    ]);
+    expect(classifyOwnerChain("a", nodes)).toEqual({ root: "unknown" });
+  });
+
+  test("a self-referencing node is a cycle of one", () => {
+    const nodes = new Map<string, OwnerChainNode>([["a", { ownerId: "a" }]]);
+    expect(classifyOwnerChain("a", nodes)).toEqual({ root: "unknown" });
+  });
+
+  test("exceeding the depth bound is conservative unknown, not foreign", () => {
+    // A straight-line chain one hop longer than the default bound, never
+    // reaching a declared entity or a definite foreign root within it.
+    const nodes = new Map<string, OwnerChainNode>();
+    const depth = DEFAULT_MAX_OWNER_CHAIN_DEPTH + 5;
+    for (let i = 0; i < depth; i++) nodes.set(`n${i}`, { ownerId: `n${i + 1}` });
+    nodes.set(`n${depth}`, {}); // the true, foreign root — but out of bounds
+    expect(classifyOwnerChain("n0", nodes)).toEqual({ root: "unknown" });
+  });
+
+  test("a chain exactly at the depth bound still resolves to declared", () => {
+    const nodes = new Map<string, OwnerChainNode>();
+    const depth = DEFAULT_MAX_OWNER_CHAIN_DEPTH;
+    for (let i = 0; i < depth; i++) nodes.set(`n${i}`, { ownerId: `n${i + 1}` });
+    nodes.set(`n${depth}`, { declaredEntity: "root-entity" });
+    expect(classifyOwnerChain("n0", nodes)).toEqual({ root: "declared", entity: "root-entity" });
+  });
+
+  test("a custom maxDepth is honored", () => {
+    const nodes = new Map<string, OwnerChainNode>([
+      ["a", { ownerId: "b" }],
+      ["b", { ownerId: "c" }],
+      ["c", { declaredEntity: "deep" }],
+    ]);
+    expect(classifyOwnerChain("a", nodes, 1)).toEqual({ root: "unknown" });
+    expect(classifyOwnerChain("a", nodes, 2)).toEqual({ root: "declared", entity: "deep" });
+  });
+});

package/src/owner-chain.ts

@@ -0,0 +1,128 @@
+/**
+ * Owner-chain classification (chant #1077).
+ *
+ * `describeResources()` already lets a lexicon report a live object it never
+ * asked about by name — that is how `orphan` has always worked (a resource
+ * present in `observedNow` that is not in `declared`). Every existing consumer
+ * treats every such object the same way: undeclared, so a delete/adopt
+ * candidate.
+ *
+ * On Kubernetes that conflates two different things. A console-added SNS
+ * subscription (the AWS case #1014/#1015 was built for) really is out-of-band
+ * drift. A Pod a declared Deployment's controller created is not drift at
+ * all — it is the runtime doing its job, and it will be recreated the moment
+ * it is deleted. `ownerReferences` is what tells them apart: the Pod's chain
+ * of owners terminates at the Deployment, which is declared.
+ *
+ * This module owns the *category* — the four possible answers to "where does
+ * this object's owner chain lead" — and the pure algorithm that walks a chain
+ * to one of them. A lexicon supplies the chain (reading `ownerReferences`,
+ * possibly across several API reads to walk past an intermediate object chant
+ * never declared, e.g. a ReplicaSet between a Pod and its Deployment); this
+ * module supplies the bounded, cycle-safe interpretation, so that logic is
+ * written and tested once rather than once per lexicon.
+ */
+
+/**
+ * Where a live, undeclared resource's owner-reference chain leads.
+ *
+ * - `declared` — the chain reaches an entity chant's own build declared. This
+ *   is the whole point of #1077: the diff engine reads this as `runtime`, not
+ *   `orphan`, and never proposes deleting it.
+ * - `unowned` — the resource carries no owner reference at all. A genuinely
+ *   standalone live object; classifies as `orphan`, unchanged from before this
+ *   module existed.
+ * - `foreign` — the chain fully resolves (every hop was readable, no cycle, no
+ *   depth bound hit) but terminates at a live root that is not declared.
+ *   Still `orphan` — it belongs to something real, just not to this build.
+ * - `unknown` — some hop could not be resolved: an unreadable owner, a cycle,
+ *   or the depth bound. Composes with #1168's tri-state precedent: an owner
+ *   chain chant could not fully verify is not a confirmed anything, so it is
+ *   never escalated to `declared` and stays routed as `orphan` today, exactly
+ *   as `foreign`/`unowned` are — never treated as a safer-than-warranted
+ *   `runtime` classification just because the read was incomplete.
+ */
+export type OwnerChainVerdict =
+  | { readonly root: "declared"; readonly entity: string }
+  | { readonly root: "unowned" }
+  | { readonly root: "foreign" }
+  | { readonly root: "unknown" };
+
+/**
+ * One node in the owner graph a lexicon assembles for {@link classifyOwnerChain}.
+ * Keyed externally (in the `nodes` map passed to the walk) by whatever stable
+ * identity the lexicon's provider uses — a Kubernetes UID, for instance.
+ */
+export interface OwnerChainNode {
+  /**
+   * This node's immediate owner, by its key in the same `nodes` map. Omit
+   * (`undefined`) when the object carries no owner reference at all — that is
+   * how a chain's *starting* node reports `unowned` rather than `unknown`.
+   */
+  ownerId?: string;
+  /**
+   * True when this node's own owner could not be determined — the read
+   * failed, was denied, or the object simply could not be fetched. Distinct
+   * from having no owner: this says "unknown", not "none".
+   */
+  ownerUnreadable?: boolean;
+  /**
+   * The declared chant entity name, when this node corresponds to one. A node
+   * with this set ends the walk immediately with `{ root: "declared" }` —
+   * whatever `ownerId`/`ownerUnreadable` it might also carry is irrelevant,
+   * since the chain already reached what it was looking for.
+   */
+  declaredEntity?: string;
+}
+
+/** Default bound on how many owner hops {@link classifyOwnerChain} will walk
+ * before giving up conservatively. Kubernetes' own garbage collector does not
+ * bound this at all, but a live read has to — a bound this generous is well
+ * past any real ownership depth (Pod → ReplicaSet → Deployment is 2 hops) and
+ * exists only to turn a corrupt or adversarial chain into `unknown` rather
+ * than an infinite walk. */
+export const DEFAULT_MAX_OWNER_CHAIN_DEPTH = 12;
+
+/**
+ * Walk the owner chain starting at `startId` through `nodes`, bounded and
+ * cycle-safe. Pure — the caller has already done whatever I/O was needed to
+ * populate `nodes`; this function only interprets the graph it was given.
+ *
+ * `nodes` need not contain every ancestor: a node the caller never resolved
+ * (because it gave up, hit the caller's own fetch bound, or the read failed)
+ * is simply absent from the map, and a reference to an absent node classifies
+ * as `unknown` — the conservative answer, same as an explicit
+ * `ownerUnreadable`.
+ */
+export function classifyOwnerChain(
+  startId: string,
+  nodes: ReadonlyMap<string, OwnerChainNode>,
+  maxDepth: number = DEFAULT_MAX_OWNER_CHAIN_DEPTH,
+): OwnerChainVerdict {
+  const start = nodes.get(startId);
+  if (!start) return { root: "unknown" };
+  if (start.declaredEntity) return { root: "declared", entity: start.declaredEntity };
+  if (start.ownerUnreadable) return { root: "unknown" };
+  if (start.ownerId === undefined) return { root: "unowned" };
+
+  const visited = new Set<string>([startId]);
+  let currentId = start.ownerId;
+
+  for (let depth = 0; depth < maxDepth; depth++) {
+    if (visited.has(currentId)) return { root: "unknown" }; // cycle
+    visited.add(currentId);
+
+    const node = nodes.get(currentId);
+    if (!node) return { root: "unknown" }; // referenced but never resolved
+    if (node.declaredEntity) return { root: "declared", entity: node.declaredEntity };
+    if (node.ownerUnreadable) return { root: "unknown" };
+    if (node.ownerId === undefined) return { root: "foreign" }; // a real, live, undeclared root
+
+    currentId = node.ownerId;
+  }
+
+  // The bound was hit without resolving to a declared entity or a definite
+  // root. Conservative: not a confirmed `foreign` either, since one more hop
+  // might have reached a declared entity — see the type doc on `unknown`.
+  return { root: "unknown" };
+}