@intentius/chant 0.37.2 → 0.39.0

package/src/lifecycle/replay.ts

@@ -15,6 +15,7 @@
  */
 
 import { readEnvironmentSnapshots } from "./git";
+import { unqualifiedKey } from "./identity";
 import type { LiveObservation } from "../graph-ir";
 import type { LifecycleSnapshot } from "./types";
 
@@ -72,16 +73,35 @@ export async function replaySnapshots(
   // account-level: the default security group three stacks each recorded is one
   // group, not three. Managed resources are stack-qualified below and cannot
   // collide, so only the unqualified ones need this.
+  //
+  // "Account-level" is the part that needed qualifying (#1416): a resource that
+  // records a region is regional, and two regions' copies are two resources
+  // however equal their ids look. `unqualifiedKey` keys those by region, so the
+  // set below still collapses one region's resource seen from two stacks and no
+  // longer collapses two regions'.
   const seenUnqualified = new Set<string>();
+  // One recorded stack is one region, so there is nothing to merge and nothing
+  // to disambiguate — its ids stay exactly what they were recorded as, which is
+  // also what `chant search --live` gives that project.
+  const merging = stored.size > 1;
   // A stack's snapshot could only exclude what THAT stack manages, so a stack
   // declaring no security groups reported the neighbouring stack's as ambient.
   // The union is only knowable here, with every snapshot in hand.
   const managedPhysicalIds = new Set<string>();
+  // Where a managed resource ends up, by physical id. A duplicate is dropped
+  // below rather than rendered twice, and anything that pointed at the
+  // duplicate has to be re-pointed at the survivor — dropping the node alone
+  // would take its edges with it, since `buildLiveGraphIr` discards an edge
+  // whose endpoints were not both observed.
+  const managedKeyOf = new Map<string, string>();
   for (const content of stored.values()) {
     const snap = JSON.parse(content) as LifecycleSnapshot;
-    for (const meta of Object.values(snap.resources ?? {})) {
+    const snapStack = snap.stack;
+    const snapQualifies = snapStack !== undefined && scopedStacks.has(snapStack);
+    for (const [id, meta] of Object.entries(snap.resources ?? {})) {
       if (!meta.ambient && !meta.referencedBy?.length && meta.physicalId) {
         managedPhysicalIds.add(meta.physicalId);
+        managedKeyOf.set(meta.physicalId, snapQualifies ? `${snapStack}::${id}` : id);
       }
     }
   }
@@ -97,32 +117,60 @@ export async function replaySnapshots(
     // collide, and none of them join the declared canvas, which qualifies.
     const stack = snapshot.stack;
     const qualify = stack !== undefined && scopedStacks.has(stack);
-    // Dependencies (#1273) are keyed by physical id and are account-level: the
-    // default VPC's route table is one resource however many stacks route
-    // through it. Qualifying those would split it per stack and break the
-    // edges into it.
-    const managed = (id: string, meta: { referencedBy?: string[]; ambient?: boolean }): string =>
-      qualify && !meta.ambient && !(meta.referencedBy && meta.referencedBy.length > 0)
-        ? `${stack}::${id}`
-        : id;
+    // Dependencies (#1273) and ambient resources (#1278) are keyed by physical
+    // id and are NOT stack-qualified: the default VPC's route table is one
+    // resource however many stacks route through it, and qualifying it would
+    // split it per stack and break the edges into it.
+    const unqualifiedByNature = (meta: { referencedBy?: string[]; ambient?: boolean }): boolean =>
+      Boolean(meta.ambient) || Boolean(meta.referencedBy && meta.referencedBy.length > 0);
+    // Region qualification (#1416) applies to exactly those, and never to a
+    // managed resource: an unscoped project's declared canvas joins on bare
+    // ids, so re-keying `web` to `us-east-1::web` would unjoin it from its own
+    // declaration.
+    const keyOf = (id: string, meta: { referencedBy?: string[]; ambient?: boolean; attributes?: Record<string, unknown> }): string => {
+      if (unqualifiedByNature(meta)) return merging ? unqualifiedKey(id, meta) : id;
+      return qualify ? `${stack}::${id}` : id;
+    };
     const resources: Record<string, (typeof snapshot.resources)[string]> = {};
+    // Duplicates dropped here, and where they went, so edges can follow.
+    const merged = new Map<string, string>();
     for (const [id, meta] of Object.entries(snapshot.resources ?? {})) {
-      const key = managed(id, meta);
-      if (key === id) {
-        // Ambient means "nothing manages this". Another stack managing it makes
-        // that false, and reporting it twice would inflate any count over it.
-        if (meta.ambient && meta.physicalId && managedPhysicalIds.has(meta.physicalId)) continue;
-        // Unqualified: account-level, so first sighting wins and the rest are
-        // the same resource seen again from another stack's snapshot.
-        if (seenUnqualified.has(id)) continue;
-        seenUnqualified.add(id);
+      const key = keyOf(id, meta);
+      if (!qualify || unqualifiedByNature(meta)) {
+        // Ambient means "nothing manages this", and being referenced means "the
+        // estate reaches this" — neither stops it being managed. When a stack
+        // manages the same physical resource, this entry is that resource seen
+        // from outside, and rendering both inflates any count over it.
+        //
+        // The dependency half of that was missing, and it was not cosmetic: a
+        // subnet declared by its stack was also recorded as `subnet-9af06b90`
+        // with `referencedBy`, so an estate with 13 subnets replayed as 16 and
+        // "which subnets have no network interfaces" answered 11 where the
+        // truth was 8. The three extra were occupied subnets whose second copy
+        // had no interface pointing at it — a duplicate reads as empty, because
+        // the edges resolved to the other one.
+        const duplicate = Boolean(meta.ambient) || Boolean(meta.referencedBy && meta.referencedBy.length > 0);
+        if (duplicate && meta.physicalId && managedPhysicalIds.has(meta.physicalId)) {
+          const survivor = managedKeyOf.get(meta.physicalId);
+          if (survivor && survivor !== key) merged.set(id, survivor);
+          continue;
+        }
+        // Unqualified: one resource per key, so first sighting wins and the
+        // rest are the same resource seen again from another stack's snapshot.
+        // The key carries the region when there is one, so "the same resource"
+        // no longer spans regions.
+        if (seenUnqualified.has(key)) continue;
+        seenUnqualified.add(key);
       }
       resources[key] = meta;
     }
     const known = new Set(Object.keys(snapshot.resources ?? {}));
     const requalify = (id: string): string => {
+      // A dropped duplicate's edges belong to the resource that survived it.
+      const survivor = merged.get(id);
+      if (survivor) return survivor;
       const meta = (snapshot.resources ?? {})[id];
-      return known.has(id) && meta ? managed(id, meta) : id;
+      return known.has(id) && meta ? keyOf(id, meta) : id;
     };
     const edges = (snapshot.edges ?? []).map((e) => ({ ...e, from: requalify(e.from), to: requalify(e.to) }));
     observations.push({

package/src/lifecycle/types.ts

@@ -97,6 +97,18 @@ export interface ResourceDigest {
 export interface BuildDigest {
   /** Per-resource digest keyed by logical name */
   resources: Record<string, ResourceDigest>;
+  /**
+   * chant #1442 — lexicon name → version that produced this build.
+   *
+   * Recorded once per lexicon rather than on every {@link ResourceDigest},
+   * which would repeat one string across every resource of a stack for no
+   * added information.
+   *
+   * Optional because a digest read back from an older snapshot will not have
+   * it. Absent and empty are different: absent means "recorded before this
+   * existed", empty means "recorded, and no plugins were loaded".
+   */
+  lexiconVersions?: Record<string, string>;
   /** Resource-level dependency graph */
   dependencies: Record<string, string[]>;
   /** Cross-lexicon output bridges from BuildManifest */
@@ -117,4 +129,18 @@ export interface DigestDiff {
   changed: string[];
   /** Resources where propsHash matches */
   unchanged: string[];
+  /**
+   * chant #1442 — lexicons whose VERSION moved between the two digests, even
+   * where every resource is unchanged.
+   *
+   * A build whose only difference is the lexicon that emitted it is a real
+   * difference: the lexicon is a generated artifact pinned to an upstream
+   * spec, so a bump can change output with no source change. Reported
+   * separately from `changed` because no resource's declaration moved — the
+   * interpreter did.
+   *
+   * Empty when neither digest recorded versions, so a comparison against a
+   * pre-#1442 snapshot reports nothing rather than inventing a change.
+   */
+  lexiconVersionChanges: Array<{ lexicon: string; previous?: string; current?: string }>;
 }

package/src/live-endpoint.test.ts

@@ -1,11 +1,29 @@
 import { describe, test, expect } from "vitest";
-import { applyLiveEndpoint, zeroResourcesWarning, LEXICON_ENDPOINT_ENV_VAR } from "./live-endpoint";
+import { applyLiveEndpoint, zeroResourcesWarning, endpointEnvVarsFor } from "./live-endpoint";
+import type { EmulatorCapability } from "./op/emulator-lifecycle";
+
+/** A lexicon standing in for one whose emulator names an endpoint var. */
+function lexicon(name: string, ...vars: string[]): { name: string; emulator?: EmulatorCapability } {
+  if (vars.length === 0) return { name };
+  return {
+    name,
+    emulator: {
+      spec: { name: `chant-${name}`, image: `${name}:0`, containerPort: 1, healthPath: "/h" },
+      // Credentials come back alongside the endpoint, as they do for real:
+      // only the vars carrying the endpoint itself should be injected.
+      env: (endpoint) => ({
+        ...Object.fromEntries(vars.map((v) => [v, endpoint])),
+        [`${name.toUpperCase()}_ACCESS_KEY_ID`]: "test",
+      }),
+    },
+  };
+}
 import type { EnvironmentDeclaration } from "./config";
 
 describe("applyLiveEndpoint (#1166)", () => {
   test("no-op — and no notice — when the environment declares no endpoint at all", () => {
     const env: NodeJS.ProcessEnv = {};
-    const result = applyLiveEndpoint(["floci", "prod"], "floci", ["aws"], env);
+    const result = applyLiveEndpoint(["floci", "prod"], "floci", [lexicon("aws", "AWS_ENDPOINT_URL")], env);
     expect(result.notice).toBeUndefined();
     expect(env.AWS_ENDPOINT_URL).toBeUndefined();
     result.restore(); // always safe, even as a no-op
@@ -15,7 +33,7 @@ describe("applyLiveEndpoint (#1166)", () => {
   test("applies the declared endpoint to the ambient var of every observing lexicon that has one", () => {
     const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
     const env: NodeJS.ProcessEnv = {};
-    const result = applyLiveEndpoint(environments, "floci", ["aws"], env);
+    const result = applyLiveEndpoint(environments, "floci", [lexicon("aws", "AWS_ENDPOINT_URL")], env);
     expect(env.AWS_ENDPOINT_URL).toBe("http://localhost:4566");
     expect(result.notice).toMatch(/environment "floci" declares endpoint http:\/\/localhost:4566/);
     expect(result.notice).toMatch(/AWS_ENDPOINT_URL/);
@@ -24,7 +42,7 @@ describe("applyLiveEndpoint (#1166)", () => {
   test("restore() removes exactly what it set, not a pre-existing value it didn't touch", () => {
     const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
     const env: NodeJS.ProcessEnv = {};
-    const result = applyLiveEndpoint(environments, "floci", ["aws"], env);
+    const result = applyLiveEndpoint(environments, "floci", [lexicon("aws", "AWS_ENDPOINT_URL")], env);
     expect(env.AWS_ENDPOINT_URL).toBe("http://localhost:4566");
     result.restore();
     expect(env.AWS_ENDPOINT_URL).toBeUndefined();
@@ -33,7 +51,7 @@ describe("applyLiveEndpoint (#1166)", () => {
   test("ambient wins: an already-set var is left untouched, and the notice says so", () => {
     const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
     const env: NodeJS.ProcessEnv = { AWS_ENDPOINT_URL: "http://real-endpoint.example" };
-    const result = applyLiveEndpoint(environments, "floci", ["aws"], env);
+    const result = applyLiveEndpoint(environments, "floci", [lexicon("aws", "AWS_ENDPOINT_URL")], env);
     expect(env.AWS_ENDPOINT_URL).toBe("http://real-endpoint.example"); // unchanged
     expect(result.notice).toMatch(/ambient AWS_ENDPOINT_URL already set/);
     result.restore();
@@ -42,7 +60,7 @@ describe("applyLiveEndpoint (#1166)", () => {
 
   test("a bare-string environment entry has no endpoint to apply", () => {
     const env: NodeJS.ProcessEnv = {};
-    const result = applyLiveEndpoint(["floci"], "floci", ["aws"], env);
+    const result = applyLiveEndpoint(["floci"], "floci", [lexicon("aws", "AWS_ENDPOINT_URL")], env);
     expect(result.notice).toBeUndefined();
     expect(env.AWS_ENDPOINT_URL).toBeUndefined();
   });
@@ -51,7 +69,7 @@ describe("applyLiveEndpoint (#1166)", () => {
     const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
     const env: NodeJS.ProcessEnv = {};
     // k8s has no ambient-var knob (config-resolved instead) — nothing to set.
-    const result = applyLiveEndpoint(environments, "floci", ["k8s"], env);
+    const result = applyLiveEndpoint(environments, "floci", [lexicon("k8s")], env);
     expect(env.AWS_ENDPOINT_URL).toBeUndefined();
     expect(result.notice).toBeUndefined();
   });
@@ -59,7 +77,7 @@ describe("applyLiveEndpoint (#1166)", () => {
   test("applies to fly's FLY_FLAPS_BASE_URL too, when fly is among the observing lexicons", () => {
     const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
     const env: NodeJS.ProcessEnv = {};
-    const result = applyLiveEndpoint(environments, "floci", ["aws", "fly"], env);
+    const result = applyLiveEndpoint(environments, "floci", [lexicon("aws", "AWS_ENDPOINT_URL"), lexicon("fly", "FLY_FLAPS_BASE_URL")], env);
     expect(env.AWS_ENDPOINT_URL).toBe("http://localhost:4566");
     expect(env.FLY_FLAPS_BASE_URL).toBe("http://localhost:4566");
     result.restore();
@@ -70,21 +88,42 @@ describe("applyLiveEndpoint (#1166)", () => {
   test("mixed: one lexicon's var is applied, another's ambient value wins — both show up in the notice", () => {
     const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
     const env: NodeJS.ProcessEnv = { FLY_FLAPS_BASE_URL: "http://real-fly.example" };
-    const result = applyLiveEndpoint(environments, "floci", ["aws", "fly"], env);
+    const result = applyLiveEndpoint(environments, "floci", [lexicon("aws", "AWS_ENDPOINT_URL"), lexicon("fly", "FLY_FLAPS_BASE_URL")], env);
     expect(env.AWS_ENDPOINT_URL).toBe("http://localhost:4566"); // applied
     expect(env.FLY_FLAPS_BASE_URL).toBe("http://real-fly.example"); // ambient wins
     expect(result.notice).toMatch(/applied to AWS_ENDPOINT_URL/);
     expect(result.notice).toMatch(/ambient FLY_FLAPS_BASE_URL already set/);
   });
 
-  test("audited endpoint-knob registry: only aws and fly (gcp/k8s/azure/temporal resolve via config, not an ambient var)", () => {
-    expect(LEXICON_ENDPOINT_ENV_VAR).toEqual({ aws: "AWS_ENDPOINT_URL", fly: "FLY_FLAPS_BASE_URL" });
+  test("the endpoint vars come from the lexicon's own emulator, not a map in core (#1345)", () => {
+    expect(endpointEnvVarsFor(lexicon("aws", "AWS_ENDPOINT_URL"))).toEqual(["AWS_ENDPOINT_URL"]);
+  });
+
+  test("credentials the emulator also needs are not treated as endpoint vars", () => {
+    // `env()` returns keys and secrets beside the endpoint; injecting those
+    // into the ambient shell for a `--live` read is not this function's job.
+    expect(endpointEnvVarsFor(lexicon("aws", "AWS_ENDPOINT_URL"))).not.toContain("AWS_ACCESS_KEY_ID");
+  });
+
+  test("a lexicon with no emulator contributes no var — it resolves its target from config", () => {
+    expect(endpointEnvVarsFor(lexicon("k8s"))).toEqual([]);
+  });
+
+  test("a lexicon declaring two emulators contributes both vars", () => {
+    const fly = {
+      name: "fly",
+      emulator: [
+        lexicon("mudflaps", "FLY_FLAPS_BASE_URL").emulator!,
+        lexicon("spritzer", "SPRITES_BASE_URL").emulator!,
+      ],
+    };
+    expect(endpointEnvVarsFor(fly).sort()).toEqual(["FLY_FLAPS_BASE_URL", "SPRITES_BASE_URL"]);
   });
 
   test("a name that isn't declared at all has no endpoint to apply", () => {
     const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
     const env: NodeJS.ProcessEnv = {};
-    const result = applyLiveEndpoint(environments, "prod", ["aws"], env);
+    const result = applyLiveEndpoint(environments, "prod", [lexicon("aws", "AWS_ENDPOINT_URL")], env);
     expect(result.notice).toBeUndefined();
     expect(env.AWS_ENDPOINT_URL).toBeUndefined();
   });

package/src/live-endpoint.ts

@@ -24,38 +24,36 @@
  * Audited (#1166) which lexicons have an ambient-env-var endpoint knob at
  * all, since that's the specific footgun — a lexicon whose environment
  * binding is resolved from `chant.config` itself (not an ambient var) has
- * nothing to inject here:
+ * nothing to inject here.
  *
- *   - **aws**  — `AWS_ENDPOINT_URL`, read directly by
- *     `lexicons/aws/src/components/cloud-executor.ts` / `plugin.ts` before
- *     every `aws …` shell-out (`applyAwsEndpoint`/`applyAwsEndpointArgv`).
- *   - **fly**  — `FLY_FLAPS_BASE_URL`, read by `resolveEndpoint()` in
- *     `lexicons/fly/src/op/activities/fly-apply.ts`, the same seam
- *     `describeResources` (`../describe-resources.ts`) calls through.
- *   - **gcp**, **k8s** — resolve their live target from `chant.config` itself
- *     (`k8s.profiles.<env>.context` via `resolveClusterTarget`,
- *     `packages/core/src/kubectl-context.ts`), not an ambient var. Nothing to
- *     inject: the config *is* the binding already.
- *   - **azure** — resolves via the `az` CLI's own logged-in
- *     subscription/session context; no ambient endpoint var exists to miss.
- *   - **temporal** — resolves its connection from `temporal.profiles.<env>`
- *     (`resolveProfile`, `lexicons/temporal/src/describe-resources.ts`), the
- *     same "config is the binding" shape as k8s/gcp.
+ * Which var that is per lexicon is no longer written down twice (#1345). It is
+ * derived from the lexicon's own {@link EmulatorCapability.env}, which already
+ * has to name the var that points tooling at a booted emulator. The map this
+ * replaced listed aws and fly, and its prose asserted azure had no ambient
+ * endpoint var — while `lexicons/azure/src/describe-resources.ts` and
+ * `deep-observe.ts` both read `AZURE_ENDPOINT_URL` on every call, so a
+ * `--live --env floci` read against azure silently went to real Azure.
  */
 
 import { environmentEndpoint, type EnvironmentDeclaration } from "./config";
+import { emulatorsOf, endpointEnvVars, type EmulatorDeclaration } from "./op/emulator-lifecycle";
 
 /**
- * Per-lexicon ambient env var a `--live` read honors for its endpoint. Only
- * lexicons with a genuine ambient-var footgun are listed — see the module doc
- * for the full audit (gcp/k8s/azure/temporal resolve their target from
- * `chant.config` instead, so they have nothing to inject).
+ * The ambient endpoint vars a lexicon honors, from its emulator capability.
+ *
+ * A lexicon with no emulator contributes nothing, which is the same answer the
+ * hand-maintained map gave for k8s, gcp and temporal — they resolve their live
+ * target from `chant.config` itself, so there is nothing to inject.
  */
-export const LEXICON_ENDPOINT_ENV_VAR: Record<string, string> = {
-  aws: "AWS_ENDPOINT_URL",
-  fly: "FLY_FLAPS_BASE_URL",
-};
+export function endpointEnvVarsFor(lexicon: EndpointLexicon): string[] {
+  return emulatorsOf(lexicon.emulator).flatMap((cap) => endpointEnvVars(cap));
+}
 
+/** What {@link applyLiveEndpoint} needs of a plugin: its name and its emulators. */
+export interface EndpointLexicon {
+  name: string;
+  emulator?: EmulatorDeclaration;
+}
 /** Result of {@link applyLiveEndpoint} — always call `restore()`, even when nothing was applied (it is then a no-op). */
 export interface AppliedEndpoint {
   /**
@@ -84,7 +82,7 @@ export interface AppliedEndpoint {
 export function applyLiveEndpoint(
   environments: EnvironmentDeclaration[] | undefined,
   environment: string,
-  lexicons: readonly string[],
+  lexicons: readonly EndpointLexicon[],
   env: NodeJS.ProcessEnv = process.env,
 ): AppliedEndpoint {
   const endpoint = environmentEndpoint(environments, environment);
@@ -94,15 +92,16 @@ export function applyLiveEndpoint(
   const overridden: string[] = [];
   const seen = new Set<string>(); // a var shared by two lexicons is only reported once
   for (const lexicon of lexicons) {
-    const varName = LEXICON_ENDPOINT_ENV_VAR[lexicon];
-    if (!varName || seen.has(varName)) continue;
-    seen.add(varName);
-    if (env[varName]) {
-      overridden.push(varName);
-      continue;
+    for (const varName of endpointEnvVarsFor(lexicon)) {
+      if (seen.has(varName)) continue;
+      seen.add(varName);
+      if (env[varName]) {
+        overridden.push(varName);
+        continue;
+      }
+      env[varName] = endpoint;
+      applied.push(varName);
     }
-    env[varName] = endpoint;
-    applied.push(varName);
   }
 
   const notices: string[] = [];

package/src/managed-fields.test.ts

@@ -155,6 +155,11 @@ describe("pruneByOwnership — the shared three-question rule", () => {
     chantOwned: new Set(["metadata.labels.tier"]),
     foreignOwned: new Set(["spec.replicas", "metadata.annotations.noise"]),
     foreignContested: new Set(["spec.replicas"]),
+    owners: new Map([
+      ["metadata.labels.tier", "chant"],
+      ["spec.replicas", "hpa-controller"],
+      ["metadata.annotations.noise", "kube-controller-manager"],
+    ]),
   };
 
   test("never prunes the declared side", () => {
@@ -177,3 +182,48 @@ describe("pruneByOwnership — the shared three-question rule", () => {
     expect(pruneByOwnership(node({ path: "spec.selector", pattern: "spec.selector" }), sets)).toBe(false);
   });
 });
+
+// #1189 — the three sets answer "which category owns this path". A reader needs
+// the other question: `hpa-controller` and `kubectl-client-side-apply` are the
+// same category and mean opposite things to an operator.
+describe("buildOwnershipSets — owning manager per path (#1189)", () => {
+  const entries = [
+    { manager: "chant", operation: "Apply", fieldsV1: { "f:metadata": { "f:labels": { "f:tier": {} } } } },
+    { manager: "hpa-controller", operation: "Apply", fieldsV1: { "f:spec": { "f:replicas": {} } } },
+    {
+      manager: "kubectl-client-side-apply",
+      operation: "Update",
+      fieldsV1: { "f:spec": { "f:template": { "f:spec": { "f:containers": {} } } } },
+    },
+  ];
+
+  test("records which manager owns each path", () => {
+    const sets = buildOwnershipSets(
+      entries,
+      { metadata: { labels: { tier: "web" } }, spec: { replicas: 3, template: { spec: { containers: [] } } } },
+      { metadata: { labels: { tier: "web" } }, spec: { replicas: 2 } },
+      (m) => m === "chant",
+    );
+    expect(sets.owners.get("metadata.labels.tier")).toBe("chant");
+    expect(sets.owners.get("spec.replicas")).toBe("hpa-controller");
+    expect(sets.owners.get("spec.template.spec.containers")).toBe("kubectl-client-side-apply");
+  });
+
+  test("the categories are unchanged by recording owners", () => {
+    const sets = buildOwnershipSets(
+      entries,
+      { metadata: { labels: { tier: "web" } }, spec: { replicas: 3, template: { spec: { containers: [] } } } },
+      { metadata: { labels: { tier: "web" } }, spec: { replicas: 2 } },
+      (m) => m === "chant",
+    );
+    expect(sets.chantOwned.has("metadata.labels.tier")).toBe(true);
+    expect(sets.foreignOwned.has("spec.replicas")).toBe(true);
+    // Declared AND foreign-owned — contested, so still diffable.
+    expect(sets.foreignContested.has("spec.replicas")).toBe(true);
+  });
+
+  test("is empty when the object carries no managedFields at all", () => {
+    const sets = buildOwnershipSets([], { spec: {} }, { spec: {} }, (m) => m === "chant");
+    expect(sets.owners.size).toBe(0);
+  });
+});

package/src/managed-fields.ts

@@ -144,6 +144,17 @@ export interface OwnershipSets {
   foreignOwned: ReadonlySet<string>;
   /** The subset of `foreignOwned` where the declared manifest also sets the path — drift-relevant despite foreign ownership. */
   foreignContested: ReadonlySet<string>;
+  /**
+   * Path → the name of the manager that owns it (#1189).
+   *
+   * The three sets above answer *which category* owns a path, which is all the
+   * prune rule needs. A reader needs the other question — "owned by
+   * `kubectl-client-side-apply`" and "owned by `hpa-controller`" are the same
+   * category and mean very different things to an operator. Last writer wins
+   * where several managers touch one path, matching what the API server itself
+   * reports.
+   */
+  owners: ReadonlyMap<string, string>;
 }
 
 function sameJson(a: unknown, b: unknown): boolean {
@@ -188,6 +199,9 @@ function walkOwnership(
   path: string,
   owned: Set<string>,
   contested: Set<string>,
+  /** Records path → manager as it walks (#1189); omitted by callers that only need the sets. */
+  owners?: Map<string, string>,
+  manager?: string,
 ): void {
   if (fieldsNode === null || typeof fieldsNode !== "object" || Array.isArray(fieldsNode)) return;
 
@@ -196,6 +210,7 @@ function walkOwnership(
       if (path !== "") {
         owned.add(path);
         if (declaredNode !== undefined) contested.add(path);
+        if (owners && manager) owners.set(path, manager);
       }
       continue;
     }
@@ -208,7 +223,8 @@ function walkOwnership(
       const childPath = joinField(path, name);
       owned.add(childPath);
       if (childDeclared !== undefined) contested.add(childPath);
-      walkOwnership(child, childLive, childDeclared, childPath, owned, contested);
+      if (owners && manager) owners.set(childPath, manager);
+      walkOwnership(child, childLive, childDeclared, childPath, owned, contested, owners, manager);
       continue;
     }
 
@@ -220,7 +236,8 @@ function walkOwnership(
       const childPath = joinIndex(path, idx);
       owned.add(childPath);
       if (childDeclared !== undefined) contested.add(childPath);
-      walkOwnership(child, childLive, childDeclared, childPath, owned, contested);
+      if (owners && manager) owners.set(childPath, manager);
+      walkOwnership(child, childLive, childDeclared, childPath, owned, contested, owners, manager);
       continue;
     }
 
@@ -255,7 +272,8 @@ function walkOwnership(
       const childPath = joinIndex(path, liveIdx);
       owned.add(childPath);
       if (childDeclared !== undefined) contested.add(childPath);
-      walkOwnership(child, childLive, childDeclared, childPath, owned, contested);
+      if (owners && manager) owners.set(childPath, manager);
+      walkOwnership(child, childLive, childDeclared, childPath, owned, contested, owners, manager);
       continue;
     }
     // An unrecognized prefix (a future fieldsV1 encoding) — skip.
@@ -286,6 +304,7 @@ export function buildOwnershipSets(
   const chantOwned = new Set<string>();
   const foreignOwned = new Set<string>();
   const foreignContested = new Set<string>();
+  const owners = new Map<string, string>();
 
   for (const entry of entries) {
     if (typeof entry.manager !== "string" || entry.manager.length === 0) continue;
@@ -294,13 +313,13 @@ export function buildOwnershipSets(
     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());
+      walkOwnership(entry.fieldsV1, liveRoot, declaredRoot, "", chantOwned, new Set(), owners, entry.manager);
     } else {
-      walkOwnership(entry.fieldsV1, liveRoot, declaredRoot, "", foreignOwned, foreignContested);
+      walkOwnership(entry.fieldsV1, liveRoot, declaredRoot, "", foreignOwned, foreignContested, owners, entry.manager);
     }
   }
 
-  return { chantOwned, foreignOwned, foreignContested };
+  return { chantOwned, foreignOwned, foreignContested, owners };
 }
 
 /**