@intentius/chant 0.38.0 → 0.39.0

package/src/graph-declared.ts

@@ -22,12 +22,24 @@ export async function buildDeclaredPerStack(
 ): Promise<GraphIR> {
   const nodes: IRNode[] = [];
   const edges: GraphIR["edges"] = [];
+  // Which nodes belong to which stack (#1433). This is not derived or guessed:
+  // the stack is declared in config and every node here is being renamed with
+  // its name on the line below. The membership was always known and thrown
+  // away, which left `byStack` — the axis consumers draw boundary boxes from —
+  // empty for the one project shape that genuinely has side-by-side stacks.
+  const byStack: Record<string, string[]> = {};
   for (const st of stacks) {
     if (!st.src) continue;
     const g = buildGraphIr((await discover(resolve(projectPath, st.src))).entities, projectPath);
     const q = (id: string) => `${st.name}::${id}`;
-    for (const n of g.nodes) nodes.push({ ...n, id: q(n.id) });
+    for (const n of g.nodes) {
+      const id = q(n.id);
+      nodes.push({ ...n, id });
+      (byStack[st.name] ??= []).push(id);
+    }
     for (const e of g.edges) edges.push({ ...e, from: q(e.from), to: q(e.to) });
   }
-  return { nodes, edges, groups: {} };
+  for (const ids of Object.values(byStack)) ids.sort();
+  const groups: GraphIR["groups"] = Object.keys(byStack).length ? { byStack } : {};
+  return { nodes, edges, groups };
 }

package/src/graph-ir.ts

@@ -94,9 +94,23 @@ export interface IREdge {
 export interface IRGroups {
   byLexicon?: Record<string, string[]>;
   byComposite?: Record<string, string[]>;
-  /** Deployable-stack grouping (`stackName → nodeIds`). A stack is a lexicon
-   * partition today; #513 phase 2 regroups by nested child-project. Consumers
-   * (e.g. pinhole's boundary boxes) read this rather than inferring stacks. */
+  /**
+   * Deployable-stack grouping (`stackName → nodeIds`). Consumers (e.g. pinhole's
+   * boundary boxes) read this rather than inferring stacks — which is the point,
+   * so it should never require one.
+   *
+   * Two sources, depending on how the project is shaped:
+   *
+   *  - **side-by-side stacks**, declared in config and composed by
+   *    `buildDeclaredPerStack` — keys are the declared stack names. Nothing is
+   *    inferred; the project stated both the names and the membership.
+   *  - **one source tree** — keys are lexicon partitions, since each lexicon
+   *    serialises to one deployable stack.
+   *
+   * Formerly documented as awaiting "#513 phase 2" to regroup by nested
+   * child-project. #513 is closed and that phase was never filed; directory
+   * partitioning is the exception rather than the rule (#1433).
+   */
   byStack?: Record<string, string[]>;
   /** Live containment (#779): a container node id → the node ids directly inside
    * it (VPC → subnets/SGs, subnet → instances/service). Nested *flatly* — a
@@ -415,11 +429,21 @@ export function buildGraphIr(
     nodes.push(node);
 
     (byLexicon[entity.lexicon] ??= []).push(name);
-    // A stack is a lexicon partition (each lexicon serialises to one deployable
-    // stack — a CloudFormation template, a CI config). `byStack` mirrors that
-    // today; #513 phase 2 will regroup it by nested child-project. It's a
-    // distinct axis from `byLexicon` (which is for provenance/colouring), so it's
-    // emitted separately even where the two currently coincide.
+    // Within ONE source tree a stack is a lexicon partition — each lexicon
+    // serialises to one deployable stack (a CloudFormation template, a CI
+    // config) — so that is what `byStack` reports here. It stays a distinct axis
+    // from `byLexicon` (which is for provenance/colouring), emitted separately
+    // even where the two coincide.
+    //
+    // A project with genuinely separate, side-by-side stacks declares them in
+    // config, and `buildDeclaredPerStack` (./graph-declared.ts) groups those by
+    // their declared names — no inference, since the project already said. That
+    // is the multi-stack shape chant steers toward (#1433).
+    //
+    // This previously promised that "#513 phase 2 will regroup it by nested
+    // child-project". #513 is closed, that phase was never filed, and directory
+    // partitioning is the exception rather than the rule — so the promise is
+    // withdrawn rather than left pointing at a closed issue.
     (byStack[entity.lexicon] ??= []).push(name);
     if (prov?.composite) (byComposite[prov.composite] ??= []).push(name);
   }

package/src/graph-refs.test.ts

@@ -188,3 +188,59 @@ describe("traversal name vs rendering label (#1275)", () => {
     expect(edges).toEqual([]);
   });
 });
+
+describe("containment is traversable without being drawn", () => {
+  // "What is inside this" is a query, not a picture. The two had been decided
+  // by one field: a containment rule became a real edge only if it set
+  // `viaAttr`, which a renderer also reads. So making a relationship queryable
+  // meant drawing it, and the list of which ones had been remembered was the
+  // list of which questions could be asked.
+  const catalog: ReferenceCatalog = {
+    identities: [
+      { kind: "Subnet", ids: ["SubnetId"] },
+      { kind: "Vpc", ids: ["VpcId"] },
+    ],
+    refs: [
+      { from: "Eni", path: "SubnetId", targetKind: "Subnet", relation: "containment", label: "in subnet" },
+      { from: "Subnet", path: "VpcId", targetKind: "Vpc", relation: "containment", label: "in VPC" },
+    ],
+  };
+  const nodes = [
+    { id: "vpc-1", kind: "Vpc", lexicon: "x", attrs: { VpcId: "vpc-1" } },
+    { id: "sub-1", kind: "Subnet", lexicon: "x", attrs: { SubnetId: "sub-1", VpcId: "vpc-1" } },
+    { id: "sub-2", kind: "Subnet", lexicon: "x", attrs: { SubnetId: "sub-2", VpcId: "vpc-1" } },
+    { id: "eni-1", kind: "Eni", lexicon: "x", attrs: { SubnetId: "sub-1" } },
+  ];
+
+  it("still draws no containment lines — the boundary stays a boundary", () => {
+    const { edges } = reconstructEdges(nodes, catalog);
+    expect(edges).toEqual([]);
+  });
+
+  it("still reports the boundary pairs a renderer groups by", () => {
+    const { containment } = reconstructEdges(nodes, catalog);
+    expect(containment).toContainEqual({ child: "eni-1", parent: "sub-1", label: "in subnet" });
+    expect(containment).toContainEqual({ child: "sub-1", parent: "vpc-1", label: "in VPC" });
+  });
+
+  it("offers the same pairs as edges a query can walk", () => {
+    const { containmentEdges } = reconstructEdges(nodes, catalog);
+    expect(containmentEdges).toContainEqual({ from: "eni-1", to: "sub-1", kind: "ref", viaAttr: "SubnetId" });
+    expect(containmentEdges).toContainEqual({ from: "sub-1", to: "vpc-1", kind: "ref", viaAttr: "VpcId" });
+  });
+
+  it("no rule had to opt in — neither declares viaAttr", () => {
+    // The point of the change. Both rules above are plain containment; the
+    // traversal name is derived from the attribute the containment was read
+    // through, so a new kind is queryable the day its rule is written.
+    expect(catalog.refs.every((r) => r.viaAttr === undefined)).toBe(true);
+    // eni-1 -> sub-1, and both subnets -> vpc-1.
+    const { containmentEdges } = reconstructEdges(nodes, catalog);
+    expect(containmentEdges).toHaveLength(3);
+  });
+
+  it("an empty container is reached by nothing, which is the whole question", () => {
+    const { containmentEdges } = reconstructEdges(nodes, catalog);
+    expect(containmentEdges.some((e) => e.to === "sub-2")).toBe(false);
+  });
+});

package/src/graph-refs.ts

@@ -86,6 +86,30 @@ export interface DanglingRef {
 export interface ReconstructedEdges {
   edges: IREdge[];
   containment: ContainmentPair[];
+  /**
+   * The same containment pairs, as edges a query can walk.
+   *
+   * Containment is a boundary when you are drawing it and a relationship when
+   * you are asking about it, and those two consumers had been served by one
+   * decision. `edges` is what a renderer draws as lines, so putting "is in this
+   * VPC" there would draw a line from every resource to its VPC and undo the
+   * boxes; that is why containment is kept out of it, and why it stays out.
+   *
+   * But `->`/`<-` is asking which nodes reach which, and being inside something
+   * is a way of reaching it. "Which subnets have no network interfaces in them"
+   * and "which VPCs have no instances in them" are the same question, and both
+   * are containment. With only `edges` to walk, the negation matched everything
+   * and reported an estate where nothing is anywhere.
+   *
+   * The escape hatch this replaces was per-rule: a containment rule could set
+   * `viaAttr` and become a real edge. That put the query layer's needs in a
+   * field the renderer also reads, and it had to be remembered per rule —
+   * `AWS::EC2::Instance -> Subnet` had it and `AWS::EC2::NetworkInterface ->
+   * Subnet` did not, which is the kind of gap hand-maintained lists always
+   * develop. Deriving them here means a containment rule is traversable because
+   * it is a containment rule, not because someone remembered.
+   */
+  containmentEdges: IREdge[];
   dangling: DanglingRef[];
 }
 
@@ -158,6 +182,8 @@ export function reconstructEdges(nodes: IRNode[], catalog: ReferenceCatalog): Re
 
   const edges: IREdge[] = [];
   const containment: ContainmentPair[] = [];
+  const containmentEdges: IREdge[] = [];
+  const seenContEdge = new Set<string>();
   const dangling: DanglingRef[] = [];
   const seenEdge = new Set<string>();
   const seenCont = new Set<string>();
@@ -185,6 +211,15 @@ export function reconstructEdges(nodes: IRNode[], catalog: ReferenceCatalog): Re
             seenCont.add(k);
             containment.push({ child: node.id, parent: match.id, ...(rule.label ? { label: rule.label } : {}) });
           }
+          // Traversable by construction. The attribute the containment was read
+          // through is its traversal name, so `<-attr:` can still discriminate
+          // between two ways of being inside something.
+          const via = rule.viaAttr ?? rule.path;
+          const ke = `${node.id}|${match.id}|${via}`;
+          if (!seenContEdge.has(ke)) {
+            seenContEdge.add(ke);
+            containmentEdges.push({ from: node.id, to: match.id, kind: "ref", viaAttr: via });
+          }
           // A containment relation is a boundary hint, not an edge — unless the
           // rule declares a traversal name (#1275). A fold's first hop is
           // sometimes exactly a containment ("an instance is in a subnet"), and
@@ -202,10 +237,11 @@ export function reconstructEdges(nodes: IRNode[], catalog: ReferenceCatalog): Re
   }
 
   edges.sort((a, b) => `${a.from}|${a.to}|${a.viaAttr}`.localeCompare(`${b.from}|${b.to}|${b.viaAttr}`));
+  containmentEdges.sort((a, b) => `${a.from}|${a.to}|${a.viaAttr}`.localeCompare(`${b.from}|${b.to}|${b.viaAttr}`));
   containment.sort((a, b) => `${a.child}|${a.parent}`.localeCompare(`${b.child}|${b.parent}`));
   dangling.sort((a, b) => `${a.from}|${a.path}|${a.value}`.localeCompare(`${b.from}|${b.path}|${b.value}`));
 
-  return { edges, containment, dangling };
+  return { edges, containment, containmentEdges, dangling };
 }
 
 /**

package/src/kubectl-context.ts

@@ -126,7 +126,10 @@ export async function resolveClusterTarget(
   lexiconName: string,
   options: ResolveClusterTargetOptions = {},
 ): Promise<ResolvedClusterTarget> {
-  const k8sConfig = config.k8s as K8sConfigShape | undefined;
+  // #1344 — the k8s lexicon declares this namespace and core validates it at
+  // load, so the shape is checked rather than asserted. `K8sConfigShape` stays
+  // as core's local description for the case where the lexicon is absent.
+  const k8sConfig = (config as { k8s?: K8sConfigShape }).k8s;
   const bound = k8sConfig?.profiles?.[environment]?.context;
 
   if (!bound) {

package/src/lexicon-config.test.ts

@@ -0,0 +1,111 @@
+import { describe, test, expect } from "vitest";
+import { z } from "zod";
+import { validateLexiconConfig, formatLexiconConfigProblems } from "./lexicon-config";
+import type { ChantConfig } from "./config";
+
+const forgejo = {
+  name: "forgejo",
+  configSchema: z.strictObject({
+    runnerLabels: z.record(z.string(), z.string()).optional(),
+    actionsRoot: z.string().optional(),
+  }),
+};
+
+const undeclared = { name: "docker" };
+
+const cfg = (extra: Record<string, unknown>): ChantConfig =>
+  ({ lexicons: ["forgejo"], ...extra }) as unknown as ChantConfig;
+
+describe("validateLexiconConfig (#1344)", () => {
+  test("accepts a namespace matching the declared shape", () => {
+    const problems = validateLexiconConfig(
+      [forgejo],
+      cfg({ forgejo: { runnerLabels: { "ubuntu-latest": "docker" }, actionsRoot: "https://x" } }),
+    );
+    expect(problems).toEqual([]);
+  });
+
+  test("rejects an unknown key — the typo that used to be silently ignored", () => {
+    const problems = validateLexiconConfig([forgejo], cfg({ forgejo: { runnerLabel: {} } }));
+    expect(problems).toHaveLength(1);
+    expect(problems[0].path).toBe("forgejo");
+    expect(problems[0].message).toContain("runnerLabel");
+  });
+
+  test("names the dotted path of a bad value, not just the namespace", () => {
+    const problems = validateLexiconConfig([forgejo], cfg({ forgejo: { actionsRoot: 42 } }));
+    expect(problems[0].path).toBe("forgejo.actionsRoot");
+  });
+
+  test("an absent namespace is fine — every one of them is optional", () => {
+    expect(validateLexiconConfig([forgejo], cfg({}))).toEqual([]);
+  });
+
+  test("an empty namespace is fine", () => {
+    expect(validateLexiconConfig([forgejo], cfg({ forgejo: {} }))).toEqual([]);
+  });
+
+  test("a lexicon that declares nothing keeps passthrough", () => {
+    // Tightening a namespace nobody described would fail configs that work.
+    expect(validateLexiconConfig([undeclared], cfg({ docker: { anything: true } }))).toEqual([]);
+  });
+
+  test("another lexicon's namespace is not this lexicon's to reject", () => {
+    expect(validateLexiconConfig([forgejo], cfg({ somethingElse: { a: 1 } }))).toEqual([]);
+  });
+
+  test("core's own keys are untouched", () => {
+    expect(validateLexiconConfig([forgejo], cfg({ sourceDir: "src", build: { fold: true } }))).toEqual([]);
+  });
+
+  test("reports every problem, not just the first", () => {
+    const problems = validateLexiconConfig(
+      [forgejo],
+      cfg({ forgejo: { runnerLabel: {}, actionsRoot: 42 } }),
+    );
+    expect(problems.length).toBeGreaterThanOrEqual(2);
+  });
+
+  test("validates each declaring lexicon independently", () => {
+    const temporal = {
+      name: "temporal",
+      configSchema: z.strictObject({ defaultProfile: z.string().optional() }),
+    };
+    const problems = validateLexiconConfig(
+      [forgejo, temporal],
+      cfg({ forgejo: { actionsRoot: "https://x" }, temporal: { defaultProfil: "local" } }),
+    );
+    expect(problems.map((p) => p.lexicon)).toEqual(["temporal"]);
+  });
+
+  test("no config at all is not a problem", () => {
+    expect(validateLexiconConfig([forgejo], undefined)).toEqual([]);
+  });
+
+  test("a nested strictObject catches a typo one level down", () => {
+    const k8s = {
+      name: "k8s",
+      configSchema: z.strictObject({
+        profiles: z.record(z.string(), z.strictObject({ context: z.string() })).optional(),
+      }),
+    };
+    const problems = validateLexiconConfig(
+      [k8s],
+      cfg({ k8s: { profiles: { prod: { contxt: "prod-eks" } } } }),
+    );
+    // Two, and both are right: the key it does not recognize, and the required
+    // one that is now missing because of the typo.
+    expect(problems.map((p) => p.path).sort()).toEqual(["k8s.profiles.prod", "k8s.profiles.prod.context"]);
+  });
+});
+
+describe("formatLexiconConfigProblems", () => {
+  test("one indented line per problem", () => {
+    const problems = validateLexiconConfig([forgejo], cfg({ forgejo: { actionsRoot: 42 } }));
+    expect(formatLexiconConfigProblems(problems)).toMatch(/^ {2}forgejo\.actionsRoot: /);
+  });
+
+  test("empty for no problems", () => {
+    expect(formatLexiconConfigProblems([])).toBe("");
+  });
+});

package/src/lexicon-config.ts

@@ -0,0 +1,92 @@
+/**
+ * The config namespace a lexicon owns (#1344).
+ *
+ * Three lexicons read a top-level `chant.config.ts` key named after themselves —
+ * `k8s.profiles.<env>.context`, `temporal.profiles`, `forgejo.runnerLabels` and
+ * `forgejo.actionsRoot` — all documented for users, none declared anywhere.
+ * `ChantConfigSchema` is `.passthrough()`, so at runtime any key is accepted and
+ * a typo is silently ignored: write `runnerLabel` and the Forgejo dialect just
+ * uses its defaults, with nothing said. The `ChantConfig` interface is closed,
+ * so the documented forgejo example did not even compile:
+ *
+ *     error TS2353: Object literal may only specify known properties,
+ *     and 'forgejo' does not exist in type 'ChantConfig'.
+ *
+ * Three lexicons had arrived at three different workarounds: temporal exported
+ * its own widened `TemporalChantConfig`, k8s's docs dropped `satisfies`, and
+ * forgejo's kept it and were wrong.
+ *
+ * A lexicon now declares the shape of its namespace. The declaration is both
+ * halves of the fix at once: core validates against it at load, and the lexicon
+ * derives the type it augments `ChantConfig` with from the same schema, so the
+ * runtime rule and the compile-time one cannot disagree.
+ */
+
+import type { ZodObject, ZodRawShape } from "zod";
+import type { ChantConfig } from "./config";
+
+/**
+ * A lexicon's config schema. A `ZodObject` specifically, so core can apply
+ * `.strict()` itself rather than trusting each lexicon to remember — an unknown
+ * key at the top of a declared namespace is a typo, and silently ignoring it is
+ * the behavior this replaces.
+ *
+ * Nested objects are the lexicon's own responsibility: author them with
+ * `z.strictObject` so a typo in `k8s.profiles.prod.contxt` fails too. `.strict()`
+ * applies to one level.
+ */
+export type LexiconConfigSchema = ZodObject<ZodRawShape>;
+
+/** What a lexicon needs to expose for its namespace to be validated. */
+export interface ConfigOwningLexicon {
+  name: string;
+  configSchema?: LexiconConfigSchema;
+}
+
+export interface LexiconConfigProblem {
+  /** The lexicon whose namespace failed. */
+  lexicon: string;
+  /** Dotted path to the offending value, e.g. `forgejo.runnerLabel`. */
+  path: string;
+  message: string;
+}
+
+/**
+ * Validate each lexicon's own namespace against the schema it declares.
+ *
+ * A lexicon that declares nothing keeps today's passthrough — silence for an
+ * unknown key — because tightening a namespace nobody described would fail
+ * configs that are working. Declaring is the opt-in.
+ *
+ * An absent namespace is not a problem: every one of them is optional.
+ */
+export function validateLexiconConfig(
+  lexicons: readonly ConfigOwningLexicon[],
+  config: ChantConfig | undefined,
+): LexiconConfigProblem[] {
+  if (!config) return [];
+  const problems: LexiconConfigProblem[] = [];
+  const raw = config as unknown as Record<string, unknown>;
+
+  for (const lexicon of lexicons) {
+    const schema = lexicon.configSchema;
+    if (!schema) continue;
+    const value = raw[lexicon.name];
+    if (value === undefined) continue;
+
+    const result = schema.strict().safeParse(value);
+    if (result.success) continue;
+
+    for (const issue of result.error.issues) {
+      const path = [lexicon.name, ...issue.path.map(String)].join(".");
+      problems.push({ lexicon: lexicon.name, path, message: issue.message });
+    }
+  }
+
+  return problems;
+}
+
+/** One line per problem, for a CLI error. */
+export function formatLexiconConfigProblems(problems: readonly LexiconConfigProblem[]): string {
+  return problems.map((p) => `  ${p.path}: ${p.message}`).join("\n");
+}

package/src/lexicon.ts

@@ -10,6 +10,7 @@ import type { McpToolContribution, McpResourceContribution } from "./mcp/types";
 import type { DriverComponent } from "./components/driver";
 import type { EmulatorDeclaration } from "./op/emulator-lifecycle";
 import type { OwnershipChannel } from "./ownership";
+import type { LexiconConfigSchema } from "./lexicon-config";
 import type { RuleMeta } from "./audit/catalog";
 import type { ReferenceCatalog } from "./graph-refs";
 import type { IREdge } from "./graph-ir";
@@ -440,6 +441,25 @@ export interface LexiconPlugin {
   /** Package lexicon into distributable tarball */
   package(options?: { verbose?: boolean; force?: boolean }): Promise<void>;
 
+  /**
+   * The shape of this lexicon's own `chant.config.ts` namespace — the top-level
+   * key named after the lexicon (#1344).
+   *
+   * k8s reads `k8s.profiles.<env>.context`, temporal `temporal.profiles`,
+   * forgejo `forgejo.runnerLabels` and `forgejo.actionsRoot`. All were
+   * documented for users and declared nowhere: the config schema is
+   * `.passthrough()`, so a typo was accepted and silently ignored, and the
+   * `ChantConfig` interface is closed, so the documented examples did not
+   * compile.
+   *
+   * Declaring the schema makes an unknown key inside the namespace an error
+   * rather than a default, and gives the lexicon a single source to derive the
+   * type it augments `ChantConfig` with — so the runtime rule and the
+   * compile-time one cannot disagree. Omit it and the namespace keeps today's
+   * passthrough.
+   */
+  readonly configSchema?: LexiconConfigSchema;
+
   /**
    * Local emulator(s) (#920), if this lexicon has any: Floci for aws, floci-az
    * for azure, floci-gcp for gcp, mudflaps and spritzer for fly. Drives

package/src/lifecycle/deep-diff.test.ts

@@ -4,7 +4,7 @@ import { UNRESOLVED, type NormalizedDeepObservation } from "../deep-observation"
 import type { BaselineLexicon } from "./observation-baseline";
 
 const live = (
-  resources: Record<string, { type: string; properties: Record<string, unknown> }>,
+  resources: Record<string, { type: string; properties: Record<string, unknown>; fieldOwners?: Record<string, string> }>,
   unobserved: NormalizedDeepObservation["unobserved"] = {},
 ): NormalizedDeepObservation => ({ resources, unobserved });
 
@@ -155,3 +155,50 @@ describe("diffDeep with an accepted baseline", () => {
     expect(result.drifted[0].changes.map((c) => c.path)).toEqual(["Extra"]);
   });
 });
+
+// #1189 — `kind` says a path is undeclared or changed; `owner` says who did it.
+// The two are independent: `hpa-controller` owning `spec.replicas` and somebody
+// running `kubectl edit` are the same kind and opposite situations.
+describe("diffDeep — owning field manager (#1189)", () => {
+  const declared = { web: { type: "K8s::Apps::Deployment", properties: { spec: { replicas: 2 } } } };
+
+  test("names the manager on a drifted path", () => {
+    const result = diffDeep({
+      declared,
+      live: live({
+        web: {
+          type: "K8s::Apps::Deployment",
+          properties: { spec: { replicas: 5 } },
+          fieldOwners: { "spec.replicas": "hpa-controller" },
+        },
+      }),
+    });
+    expect(result.drifted[0].changes[0]).toMatchObject({
+      path: "spec.replicas",
+      kind: "changed",
+      owner: "hpa-controller",
+    });
+  });
+
+  test("is absent when the substrate records no per-field ownership", () => {
+    // Every substrate but k8s. The field must not appear at all rather than
+    // appear empty — a consumer branches on its presence.
+    const result = diffDeep({
+      declared,
+      live: live({ web: { type: "K8s::Apps::Deployment", properties: { spec: { replicas: 5 } } } }),
+    });
+    expect(result.drifted[0].changes[0]).not.toHaveProperty("owner");
+  });
+
+  test("is absent for a path with no live value — nobody owns a field that is not there", () => {
+    const result = diffDeep({
+      declared,
+      live: live({
+        web: { type: "K8s::Apps::Deployment", properties: {}, fieldOwners: { "spec.replicas": "someone" } },
+      }),
+    });
+    const change = result.drifted[0].changes.find((c) => c.path === "spec.replicas")!;
+    expect(change.kind).toBe("absent");
+    expect(change).not.toHaveProperty("owner");
+  });
+});

package/src/lifecycle/deep-diff.ts

@@ -59,6 +59,17 @@ export interface PropertyDrift {
    * accepted value there would lose the most useful column in the report.
    */
   baseline?: unknown;
+  /**
+   * The field manager that owns this path live, where the substrate records one
+   * (#1189) — Kubernetes' `managedFields`, and nowhere else today.
+   *
+   * `kind` says a path is `undeclared` or `changed`; this says who did it.
+   * "Owned by `kubectl-client-side-apply`" and "owned by `hpa-controller`" are
+   * the same `kind` and mean opposite things: one is somebody bypassing the
+   * pipeline, the other is a controller doing its job. Absent on a substrate
+   * with no per-field ownership, which is every substrate but k8s.
+   */
+  owner?: string;
 }
 
 /** Property-level drift for one declared entity. */
@@ -173,11 +184,16 @@ export function diffDeep(input: DiffDeepInput): DeepDiffResult {
       if (hasDeclared && hasLive && deepValueEqual(declaredValue, liveValue)) continue;
 
       const kind: PropertyDriftKind = !hasDeclared ? "undeclared" : !hasLive ? "absent" : "changed";
+      // Who owns the path live, where the substrate records it (#1189). Only
+      // meaningful for a path that exists live — an `absent` drift has no live
+      // field for anyone to own.
+      const owner = hasLive ? liveEntity.fieldOwners?.[path] : undefined;
       const drift: PropertyDrift = {
         path,
         kind,
         ...(hasDeclared ? { declared: declaredValue } : {}),
         ...(hasLive ? { live: liveValue } : {}),
+        ...(owner ? { owner } : {}),
       };
 
       const acceptedEntry = acceptedDeviation(baseline, name, path);

package/src/lifecycle/digest.test.ts

@@ -115,3 +115,84 @@ describe("diffDigests", () => {
     expect(result.removed.sort()).toEqual(["c"]);
   });
 });
+
+/**
+ * chant #1442 — a digest records what interpreted the declarations, not only
+ * what was declared.
+ */
+function withVersions(versions: Record<string, string> | undefined): BuildResult {
+  const result = makeBuildResult({ k8s: [{ name: "app", type: "K8s::Apps::Deployment", props: { replicas: 2 } }] });
+  return { ...result, lexiconVersions: versions } as unknown as BuildResult;
+}
+
+describe("computeBuildDigest — lexicon versions (#1442)", () => {
+  test("records the version of each lexicon that served the build", () => {
+    expect(computeBuildDigest(withVersions({ k8s: "0.38.0" })).lexiconVersions).toEqual({ k8s: "0.38.0" });
+  });
+
+  test("records once per lexicon, not once per resource", () => {
+    const many = makeBuildResult({
+      k8s: [
+        { name: "a", type: "K8s::Apps::Deployment", props: {} },
+        { name: "b", type: "K8s::Core::Service", props: {} },
+      ],
+    });
+    const digest = computeBuildDigest({ ...many, lexiconVersions: { k8s: "0.38.0" } } as unknown as BuildResult);
+    expect(Object.keys(digest.resources)).toHaveLength(2);
+    expect(digest.lexiconVersions).toEqual({ k8s: "0.38.0" });
+  });
+
+  test("a build with no plugins records an empty map, not absence", () => {
+    // Absent and empty mean different things when read back: absent is
+    // "recorded before #1442", empty is "recorded, nothing loaded".
+    expect(computeBuildDigest(withVersions(undefined)).lexiconVersions).toEqual({});
+  });
+
+  test("the recorded map is a copy, so later mutation cannot rewrite history", () => {
+    const versions = { k8s: "0.38.0" };
+    const digest = computeBuildDigest(withVersions(versions));
+    versions.k8s = "0.39.0";
+    expect(digest.lexiconVersions).toEqual({ k8s: "0.38.0" });
+  });
+});
+
+describe("diffDigests — lexicon version changes (#1442)", () => {
+  const resources = { app: { type: "K8s::Apps::Deployment", lexicon: "k8s", propsHash: "same" } };
+  const digest = (lexiconVersions?: Record<string, string>): BuildDigest =>
+    ({ resources, dependencies: {}, outputs: {}, deployOrder: ["k8s"], lexiconVersions }) as BuildDigest;
+
+  test("reports a bump even when every resource is unchanged", () => {
+    const diff = diffDigests(digest({ k8s: "0.39.0" }), digest({ k8s: "0.38.0" }));
+    expect(diff.changed).toEqual([]);
+    expect(diff.unchanged).toEqual(["app"]);
+    expect(diff.lexiconVersionChanges).toEqual([{ lexicon: "k8s", previous: "0.38.0", current: "0.39.0" }]);
+  });
+
+  test("reports nothing when versions match", () => {
+    expect(diffDigests(digest({ k8s: "0.38.0" }), digest({ k8s: "0.38.0" })).lexiconVersionChanges).toEqual([]);
+  });
+
+  test("reports a lexicon added to or dropped from the build", () => {
+    const added = diffDigests(digest({ k8s: "0.38.0", aws: "0.38.0" }), digest({ k8s: "0.38.0" }));
+    expect(added.lexiconVersionChanges).toEqual([{ lexicon: "aws", previous: undefined, current: "0.38.0" }]);
+
+    const dropped = diffDigests(digest({ k8s: "0.38.0" }), digest({ k8s: "0.38.0", aws: "0.38.0" }));
+    expect(dropped.lexiconVersionChanges).toEqual([{ lexicon: "aws", previous: "0.38.0", current: undefined }]);
+  });
+
+  test("a pre-#1442 snapshot reports no change rather than inventing one", () => {
+    // The older digest never recorded versions. Every lexicon would otherwise
+    // look newly-added on the first comparison after upgrading chant.
+    expect(diffDigests(digest({ k8s: "0.38.0" }), digest(undefined)).lexiconVersionChanges).toEqual([]);
+    expect(diffDigests(digest(undefined), digest({ k8s: "0.38.0" })).lexiconVersionChanges).toEqual([]);
+  });
+
+  test("with no previous digest at all, there is no version change", () => {
+    expect(diffDigests(digest({ k8s: "0.38.0" }), undefined).lexiconVersionChanges).toEqual([]);
+  });
+
+  test("changes are ordered by lexicon name, so output is stable", () => {
+    const diff = diffDigests(digest({ k8s: "2", aws: "2", gcp: "2" }), digest({ k8s: "1", aws: "1", gcp: "1" }));
+    expect(diff.lexiconVersionChanges.map((c) => c.lexicon)).toEqual(["aws", "gcp", "k8s"]);
+  });
+});