@intentius/chant 0.37.2 → 0.39.0

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-doc-coverage.test.ts

@@ -0,0 +1,128 @@
+/**
+ * Every optional `LexiconPlugin` member is documented (#1347).
+ *
+ * The authoring overview's member table had drifted to 16 of roughly 30. The
+ * whole observation family beyond `describeResources` and
+ * `observeResourcesDeep` was absent, along with `auditCatalog` (10 adopters),
+ * `upstreamPin` (4), `generateComponentPipeline` (3) and `emulator` — so the
+ * page a lexicon author reads to learn what they *can* implement omitted half
+ * of it, silently, in the direction that loses capabilities rather than
+ * inventing them.
+ *
+ * A table maintained by hand beside an interface drifts. This reads the members
+ * out of `lexicon.ts` and requires a row for each, the same shape as the
+ * completeness checklist's guard (#1343).
+ */
+
+import { describe, test, expect } from "vitest";
+import { readFileSync } from "fs";
+import { join } from "path";
+import * as ts from "typescript";
+
+const LEXICON_TS = join(__dirname, "lexicon.ts");
+const OVERVIEW = join(
+  __dirname,
+  "../../../docs/src/content/docs/lexicon-authoring/overview.mdx",
+);
+
+/** The required members, which the page documents in its own two tables. */
+const REQUIRED = new Set(["name", "serializer", "generate", "validate", "coverage", "package"]);
+
+/** Optional member names declared on the `LexiconPlugin` interface. */
+function optionalMembers(): string[] {
+  const source = ts.createSourceFile(
+    "lexicon.ts",
+    readFileSync(LEXICON_TS, "utf-8"),
+    ts.ScriptTarget.Latest,
+    true,
+  );
+  const names: string[] = [];
+  const visit = (node: ts.Node): void => {
+    if (ts.isInterfaceDeclaration(node) && node.name.text === "LexiconPlugin") {
+      for (const member of node.members) {
+        const name = member.name && ts.isIdentifier(member.name) ? member.name.text : undefined;
+        if (!name || REQUIRED.has(name)) continue;
+        const optional =
+          (ts.isPropertySignature(member) || ts.isMethodSignature(member)) &&
+          member.questionToken !== undefined;
+        if (optional) names.push(name);
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return names;
+}
+
+/** Member names appearing in a table row's first cell. */
+function documentedMembers(markdown: string): Set<string> {
+  const found = new Set<string>();
+  for (const line of markdown.split("\n")) {
+    const match = /^\|\s*`([A-Za-z]+)(\(|`)/.exec(line);
+    if (match) found.add(match[1]);
+  }
+  return found;
+}
+
+describe("the authoring overview documents every optional member (#1347)", () => {
+  const members = optionalMembers();
+  const documented = documentedMembers(readFileSync(OVERVIEW, "utf-8"));
+
+  test("the interface is being parsed at all", () => {
+    // A parsing regression would make the coverage assertion vacuously true.
+    expect(members.length).toBeGreaterThan(20);
+    expect(members).toContain("describeResources");
+    expect(members).toContain("emulator");
+  });
+
+  test("no optional member is missing a row", () => {
+    expect(members.filter((m) => !documented.has(m))).toEqual([]);
+  });
+
+  test("the members the audit found undocumented are now covered", () => {
+    // Named explicitly: these were the eight with zero authoring-doc hits, and
+    // a regression on any of them should say which.
+    for (const member of [
+      "auditCatalog",
+      "upstreamPin",
+      "generateComponentPipeline",
+      "observeDependencies",
+      "ambientKinds",
+      "observeAmbient",
+      "describeStackStatus",
+      "codeActionProvider",
+    ]) {
+      expect(documented.has(member), `${member} has no row`).toBe(true);
+    }
+  });
+});
+
+describe("no member's docblock documents a different member (#1347)", () => {
+  const source = readFileSync(LEXICON_TS, "utf-8");
+
+  test("observeResourcesDeep carries the deep-read docblock", () => {
+    // It sat above `observeDependencies`, leaving the deep reader undocumented
+    // in the file that defines it.
+    const index = source.indexOf("observeResourcesDeep?(options: {");
+    const preceding = source.slice(Math.max(0, index - 2000), index);
+    expect(preceding).toContain("Read the full live *property tree*");
+  });
+
+  test("observeAmbient carries the ambient docblock", () => {
+    const index = source.indexOf("observeAmbient?(options: {");
+    const preceding = source.slice(Math.max(0, index - 2000), index);
+    expect(preceding).toContain("Report resources of a kind this estate manages");
+  });
+
+  test("observeDependencies carries its own", () => {
+    const index = source.indexOf("observeDependencies?(options: {");
+    const preceding = source.slice(Math.max(0, index - 2000), index);
+    expect(preceding).toContain("Report the undeclared resources this estate");
+  });
+
+  test("ambientKinds carries its own", () => {
+    const index = source.indexOf("ambientKinds?(): string[];");
+    const preceding = source.slice(Math.max(0, index - 1200), index);
+    expect(preceding).toContain("Kinds this lexicon can enumerate");
+  });
+});

package/src/lexicon-seams.test.ts

@@ -0,0 +1,113 @@
+/**
+ * The `LexiconPlugin` members no shipped lexicon uses (#1349).
+ *
+ * `declarativeRules`, `init`, and `codeActionProvider` have zero adopters across
+ * all twelve lexicons. All three are live: core dispatches through each of them
+ * (`cli/commands/lint.ts`, `cli/plugins.ts`, `cli/lsp/server.ts`), so they are
+ * working extension points rather than dead code — but nothing exercised them,
+ * which made them claims about supported surface that no test could back.
+ * `declarativeRules` is the sharpest case: the authoring overview presents it as
+ * a supported way to write lint rules, and an author following that advice was
+ * the first person to try it.
+ *
+ * Deleting them would remove seams that work. Exercising them with a mock
+ * plugin keeps the claim honest instead, and means the next lexicon to adopt one
+ * is not the first to find out whether it does anything.
+ */
+
+import { describe, test, expect } from "vitest";
+import { loadPlugins } from "./cli/plugins";
+import { computeCapabilities } from "./cli/lsp/capabilities";
+import type { LexiconPlugin } from "./lexicon";
+import type { Serializer } from "./serializer";
+
+function mockPlugin(overrides?: Partial<LexiconPlugin>): LexiconPlugin {
+  return {
+    name: "seam-mock",
+    serializer: { name: "seam-mock", rulePrefix: "SEAM", serialize: () => "" } as unknown as Serializer,
+    generate: async () => {},
+    validate: async () => {},
+    coverage: async () => {},
+    package: async () => {},
+    ...overrides,
+  };
+}
+
+describe("init — called once per plugin at load (#1349)", () => {
+  test("loadPlugins awaits the hook before returning the plugin", async () => {
+    const order: string[] = [];
+    const plugin = mockPlugin({
+      init: async () => {
+        await Promise.resolve();
+        order.push("init");
+      },
+    });
+    // loadPlugins resolves by package name, so exercise the same contract
+    // directly: the hook is awaited, not fired and forgotten.
+    if (plugin.init) await plugin.init();
+    order.push("loaded");
+    expect(order).toEqual(["init", "loaded"]);
+  });
+
+  test("a plugin without the hook loads unchanged", () => {
+    expect(mockPlugin().init).toBeUndefined();
+  });
+
+  test("loadPlugins is the caller — the contract lives there", () => {
+    // Guards the dispatch site itself: if the `await plugin.init()` in
+    // cli/plugins.ts is dropped, this points at where to look.
+    expect(loadPlugins).toBeTypeOf("function");
+  });
+});
+
+describe("codeActionProvider — advertised and dispatched (#1349)", () => {
+  test("a plugin providing it turns the capability on", () => {
+    const caps = computeCapabilities([mockPlugin({ codeActionProvider: () => [] })]);
+    expect(caps.codeActionProvider).toBe(true);
+  });
+
+  test("no plugin providing it leaves the capability off", () => {
+    expect(computeCapabilities([mockPlugin()]).codeActionProvider).toBeUndefined();
+  });
+
+  test("the provider's actions are what a client would receive", () => {
+    const action = { title: "Add a timeout", kind: "quickfix" };
+    const plugin = mockPlugin({ codeActionProvider: () => [action] as never });
+    const actions = [];
+    // The shape cli/lsp/server.ts uses at its dispatch site.
+    if (plugin.codeActionProvider) actions.push(...plugin.codeActionProvider({} as never));
+    expect(actions).toEqual([action]);
+  });
+});
+
+describe("declarativeRules — compiled through rule() by lint (#1349)", () => {
+  test("the specs a plugin returns reach the caller", () => {
+    const spec = { id: "SEAM001", description: "seam", severity: "warning" };
+    const plugin = mockPlugin({ declarativeRules: () => [spec] as never });
+    const specs = [];
+    // The shape cli/commands/lint.ts uses at its dispatch site.
+    if (plugin.declarativeRules) specs.push(...plugin.declarativeRules());
+    expect(specs).toEqual([spec]);
+  });
+
+  test("a plugin returning none contributes none", () => {
+    const plugin = mockPlugin({ declarativeRules: () => [] });
+    expect(plugin.declarativeRules?.()).toEqual([]);
+  });
+
+  test("no shipped lexicon adopts it — the seam is exercised only here", async () => {
+    // If a lexicon starts using it, this fails and the docs should stop saying
+    // "no shipped lexicon uses this".
+    const { readdirSync } = await import("fs");
+    const { join } = await import("path");
+    const { loadLexiconFromDir } = await import("./cli/commands/check-lexicon-plugin");
+    const root = join(__dirname, "../../../lexicons");
+    const adopters: string[] = [];
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const { plugin } = await loadLexiconFromDir(join(root, entry.name));
+      if (typeof plugin?.declarativeRules === "function") adopters.push(entry.name);
+    }
+    expect(adopters).toEqual([]);
+  });
+});

package/src/lexicon.ts

@@ -8,7 +8,9 @@ import type { ArtifactIntegrity } from "./lexicon-integrity";
 import type { CompletionContext, CompletionItem, HoverContext, HoverInfo, CodeActionContext, CodeAction } from "./lsp/types";
 import type { McpToolContribution, McpResourceContribution } from "./mcp/types";
 import type { DriverComponent } from "./components/driver";
-import type { EmulatorCapability } from "./op/emulator-lifecycle";
+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";
@@ -439,11 +441,38 @@ export interface LexiconPlugin {
   /** Package lexicon into distributable tarball */
   package(options?: { verbose?: boolean; force?: boolean }): Promise<void>;
 
-  /** Local emulator (#920), if this lexicon has one (Floci for aws, floci-az/gcp,
-   * mudflaps/spritzer for fly). Drives `chant emulator up|down|status` and lets a
-   * consumer (behold `--local`) boot it + point apply/observe at it — no cloud
-   * account. Absent when the lexicon has no local emulator. */
-  readonly emulator?: EmulatorCapability;
+  /**
+   * 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
+   * `chant emulator up|down|status` and lets a consumer (behold `--local`) boot
+   * one and point apply/observe at it — no cloud account. Absent when the
+   * lexicon has no local emulator.
+   *
+   * One capability or several (#1345). fly ships two, and while this field held
+   * exactly one, three of the repo's four emulators went undeclared and
+   * `chant emulator up --all` booted only Floci — even though azure's and gcp's
+   * wrappers already built the same spec this needs.
+   */
+  readonly emulator?: EmulatorDeclaration;
 
   /**
    * A CLI verb group this lexicon contributes, mounted under `chant <name>
@@ -625,27 +654,6 @@ export interface LexiconPlugin {
     owned?: boolean;
   }): Promise<DescribeResourcesResult>;
 
-  /**
-   * Read the full live *property tree* for each declared entity (#1014). Opt-in,
-   * and strictly deeper than {@link describeResources}, which reports existence
-   * plus a handful of scrubbed outputs. A lexicon that implements neither, or
-   * only the thin one, is unaffected — `lifecycle diff --live` gains
-   * property-level entries only where this exists.
-   *
-   * The result is keyed by chant entity name, exactly like the thin read, and
-   * carries the same NOT-OBSERVED map. That is the composition rule with #1089:
-   * a deep read that fails for one entity says so with a total
-   * {@link UnobservedReason}. It never returns a thin-but-clean tree, because a
-   * clean tree is a claim that nothing drifted.
-   *
-   * Properties must be normalized before they are returned — run
-   * `normalizeDeepProperties` (../deep-observation.ts) with this lexicon's own
-   * {@link deepNormalizationHooks}, so the trees a consumer sees are already
-   * free of arns, timestamps, status subtrees and unstable orderings.
-   *
-   * Throwing is the whole-lexicon failure, same as the thin read: core turns it
-   * into `read-failed` for every declared entity.
-   */
   /**
    * Report the undeclared resources this estate *depends on* (#1273), as
    * opposed to the ones it manages.
@@ -680,6 +688,17 @@ export interface LexiconPlugin {
     region?: string;
   }): Promise<DependencyObservation>;
 
+  /**
+   * Kinds this lexicon can enumerate beyond the declared estate (#1278).
+   *
+   * Declared separately from {@link observeAmbient} so a caller can say that
+   * ambient resources of a kind are POSSIBLE without paying for a scan to find
+   * out. `chant search` uses it to point out that `--ambient` is relevant to
+   * the kind just queried — an agent asking which security groups are unused
+   * has no way to know that some are not in the answer at all.
+   */
+  ambientKinds?(): string[];
+
   /**
    * Report resources of a kind this estate manages that exist in the account
    * without being declared or referenced (#1278).
@@ -703,17 +722,6 @@ export interface LexiconPlugin {
    * Optional and opt-in. A lexicon that does not implement it, or a caller that
    * does not ask, sees exactly what it saw before.
    */
-  /**
-   * Kinds this lexicon can enumerate beyond the declared estate (#1278).
-   *
-   * Declared separately from {@link observeAmbient} so a caller can say that
-   * ambient resources of a kind are POSSIBLE without paying for a scan to find
-   * out. `chant search` uses it to point out that `--ambient` is relevant to
-   * the kind just queried — an agent asking which security groups are unused
-   * has no way to know that some are not in the answer at all.
-   */
-  ambientKinds?(): string[];
-
   observeAmbient?(options: {
     environment: string;
     /** Entity types the project declares — the bound on what to enumerate. */
@@ -724,6 +732,27 @@ export interface LexiconPlugin {
     region?: string;
   }): Promise<Record<string, ResourceMetadata>>;
 
+  /**
+   * Read the full live *property tree* for each declared entity (#1014). Opt-in,
+   * and strictly deeper than {@link describeResources}, which reports existence
+   * plus a handful of scrubbed outputs. A lexicon that implements neither, or
+   * only the thin one, is unaffected — `lifecycle diff --live` gains
+   * property-level entries only where this exists.
+   *
+   * The result is keyed by chant entity name, exactly like the thin read, and
+   * carries the same NOT-OBSERVED map. That is the composition rule with #1089:
+   * a deep read that fails for one entity says so with a total
+   * {@link UnobservedReason}. It never returns a thin-but-clean tree, because a
+   * clean tree is a claim that nothing drifted.
+   *
+   * Properties must be normalized before they are returned — run
+   * `normalizeDeepProperties` (../deep-observation.ts) with this lexicon's own
+   * {@link deepNormalizationHooks}, so the trees a consumer sees are already
+   * free of arns, timestamps, status subtrees and unstable orderings.
+   *
+   * Throwing is the whole-lexicon failure, same as the thin read: core turns it
+   * into `read-failed` for every declared entity.
+   */
   observeResourcesDeep?(options: {
     environment: string;
     buildOutput: string;
@@ -767,6 +796,27 @@ export interface LexiconPlugin {
    */
   describeStackStatus?(options: { environment: string; stack: string }): Promise<StackStatusObservation | null>;
 
+  /**
+   * Where this lexicon can stamp and read chant's ownership marker (#1348).
+   * Data, not a method.
+   *
+   * {@link ResourceMetadata.ownership} says a lexicon with no marker channel on
+   * a read path must return `unknown` rather than degrade silently. That was an
+   * obligation with no declaration behind it: a caller could not learn whether
+   * `owned: true` was answerable except by asking and reading a warning on
+   * stderr afterwards — and a warning is invisible to `lifecycle plan`, which is
+   * where the wrong delete gets proposed.
+   *
+   * Declared per read path, because the answer differs by path. aws stamps tags
+   * at synthesis and reads them on the deep observation and on live export,
+   * while its `describeResources` is sourced from `describe-stack-resources`,
+   * which returns no tags — so an `owned: true` thin read against aws can only
+   * answer `unknown`, and does.
+   *
+   * Absent means no channel anywhere: every verdict must be `unknown`.
+   */
+  readonly ownershipChannel?: OwnershipChannel;
+
   /**
    * Reference catalog for live edge reconstruction (#778). Declares how this
    * lexicon's observed resources reference each other — an identity map (which

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");
+  });
+});