@intentius/chant 0.30.0 → 0.32.0

package/src/cli/conflict-check.test.ts

@@ -1,6 +1,6 @@
 import { describe, test, expect } from "vitest";
 import { checkConflicts } from "./conflict-check";
-import type { LexiconPlugin } from "../lexicon";
+import type { LexiconPlugin, CommandGroup } from "../lexicon";
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const mockSerializer = { name: "test", serialize: () => ({}) } as any;
@@ -14,6 +14,7 @@ function makePlugin(
     skills?: { name: string }[];
     mcpTools?: { name: string }[];
     mcpResources?: { uri: string }[];
+    commandGroup?: CommandGroup;
   } = {},
 ): LexiconPlugin {
   const plugin: LexiconPlugin = {
@@ -57,6 +58,11 @@ function makePlugin(
     (plugin as any).mcpTools = () => tools;
   }
 
+  if (opts.commandGroup) {
+    const group = opts.commandGroup;
+    plugin.commands = () => group;
+  }
+
   if (opts.mcpResources) {
     const resources = opts.mcpResources.map((r) => ({
       uri: r.uri,
@@ -202,6 +208,35 @@ describe("checkConflicts", () => {
     expect(report.warnings.filter((w) => w.type === "mcp-resource")).toHaveLength(0);
   });
 
+  // -----------------------------------------------------------------------
+  // Command-group name conflicts (hard, chant #1078)
+  // -----------------------------------------------------------------------
+
+  test("detects two lexicons claiming the same command-group name as a hard conflict", () => {
+    const plugins = [
+      makePlugin("k8s", { commandGroup: { name: "kube", description: "d", commands: [] } }),
+      makePlugin("fly", { commandGroup: { name: "kube", description: "d2", commands: [] } }),
+    ];
+    const report = checkConflicts(plugins);
+    expect(report.conflicts).toEqual([{ type: "command-group-name", key: "kube", plugins: ["k8s", "fly"] }]);
+    expect(report.warnings).toHaveLength(0);
+  });
+
+  test("detects a command-group name colliding with a reserved core command word", () => {
+    const plugins = [makePlugin("rogue", { commandGroup: { name: "build", description: "d", commands: [] } })];
+    const report = checkConflicts(plugins);
+    expect(report.conflicts).toEqual([{ type: "command-group-name", key: "build", plugins: ["rogue"] }]);
+  });
+
+  test("no conflict for a single lexicon's own, non-reserved command-group name", () => {
+    const plugins = [
+      makePlugin("k8s", { commandGroup: { name: "kube", description: "d", commands: [] } }),
+      makePlugin("aws"),
+    ];
+    const report = checkConflicts(plugins);
+    expect(report.conflicts.filter((c) => c.type === "command-group-name")).toHaveLength(0);
+  });
+
   // -----------------------------------------------------------------------
   // Combined
   // -----------------------------------------------------------------------

package/src/cli/conflict-check.ts

@@ -1,7 +1,8 @@
 import type { LexiconPlugin } from "../lexicon";
+import { RESERVED_COMMAND_NAMES } from "./command-group";
 
 export interface ConflictEntry {
-  type: "rule-id" | "skill-name" | "mcp-tool" | "mcp-resource";
+  type: "rule-id" | "skill-name" | "mcp-tool" | "mcp-resource" | "command-group-name";
   key: string;
   plugins: string[];
 }
@@ -85,5 +86,25 @@ export function checkConflicts(plugins: LexiconPlugin[]): ConflictReport {
     }
   }
 
+  // Check command-group name conflicts (hard, chant #1078). Two shapes:
+  // two lexicons claiming the same group name (only one would ever be
+  // reachable, silently), or one lexicon claiming a name core's own static
+  // registry already owns (permanently unreachable — core resolves its own
+  // registry first, unconditionally). Either is a silent-shadowing bug
+  // class, so both are hard conflicts rather than warnings.
+  const commandGroupNames = new Map<string, string[]>();
+  for (const plugin of plugins) {
+    const group = plugin.commands?.();
+    if (!group) continue;
+    const existing = commandGroupNames.get(group.name) ?? [];
+    existing.push(plugin.name);
+    commandGroupNames.set(group.name, existing);
+  }
+  for (const [name, owners] of commandGroupNames) {
+    if (owners.length > 1 || RESERVED_COMMAND_NAMES.has(name)) {
+      conflicts.push({ type: "command-group-name", key: name, plugins: owners });
+    }
+  }
+
   return { conflicts, warnings };
 }

package/src/cli/handlers/lifecycle.ts

@@ -857,6 +857,7 @@ function renderLiveDiff(lexiconName: string, environment: string, diff: LiveDiff
     `${diff.missing.length} missing, ${diff.orphan.length} orphan, ` +
     `${diff.disappeared.length} disappeared, ${diff.newlyObserved.length} newly observed, ` +
     `${diff.driftedSinceSnapshot.length} drifted, ${diff.unchanged.length} unchanged` +
+    (diff.runtimeChildren.length > 0 ? `, ${diff.runtimeChildren.length} runtime` : "") +
     (diff.unobserved.length > 0 ? `, ${diff.unobserved.length} unobserved` : "");
 
   console.log(`\n${formatBold(lexiconName)} — environment: ${environment}`);
@@ -877,6 +878,10 @@ function renderLiveDiff(lexiconName: string, environment: string, diff: LiveDiff
     console.log(formatBold("\nORPHAN (in cloud, not declared):"));
     for (const name of diff.orphan) console.log(`  - ${name}`);
   }
+  if (diff.runtimeChildren.length > 0) {
+    console.log(formatBold("\nRUNTIME (owned by a declared resource; not drift, not an orphan — #1077):"));
+    for (const r of diff.runtimeChildren) console.log(`  - ${r.name} (${r.type}) — owned by ${r.owner}`);
+  }
   if (diff.disappeared.length > 0) {
     console.log(formatBold("\nDISAPPEARED (in last snapshot, gone now):"));
     for (const name of diff.disappeared) console.log(`  - ${name}`);

package/src/cli/main.ts

@@ -27,6 +27,8 @@ import { runComponentsStatus, runComponentsReleaseRecord, runComponentsUnknown }
 import { runGraph } from "./handlers/graph";
 import { runOp, runOpList, runOpStatus, runOpSignal, runOpCancel, runOpLog } from "./handlers/run";
 import { runEmulator } from "./handlers/emulator";
+import { splitJoinedFlags, dispatchCommandGroup, collectCommandGroups, formatCommandGroupsHelp, type CommandGroup } from "./command-group";
+import type { LexiconPlugin } from "../lexicon";
 
 /**
  * Long-form flags that are pure booleans in {@link parseArgs} — their branch
@@ -118,31 +120,24 @@ export function parseArgs(args: string[]): ParsedArgs {
     env: undefined,
   };
 
+  // chant #1127 — generic joined `--flag=value` support, factored out to
+  // ./command-group.ts (chant #1078) so a lexicon's own mounted command can
+  // apply the identical splitting discipline to its own flag vocabulary.
+  // Every value-taking flag below is matched by an exact `arg === "--flag"`
+  // check and then consumes the *next* array element (`args[++i]`) as its
+  // value; a joined token like `--env=prod` never matches any of those,
+  // doesn't match the trailing positional branch either (it starts with
+  // `-`), and used to vanish with no error. Splitting the token at its FIRST
+  // `=` and re-dispatching as two array elements makes every flag below see
+  // the exact shape it already handles — including a flag like `--param`
+  // whose own value legitimately contains `=` (`--param=tier=production`
+  // splits to flag `--param`, value `tier=production`, not further split on
+  // the second `=`).
+  args = splitJoinedFlags(args, BOOLEAN_FLAGS);
+
   let i = 0;
   while (i < args.length) {
-    let arg = args[i];
-
-    // chant #1127 — generic joined `--flag=value` support. Every value-taking
-    // flag below is matched by an exact `arg === "--flag"` check and then
-    // consumes the *next* array element (`args[++i]`) as its value; a joined
-    // token like `--env=prod` never matches any of those, doesn't match the
-    // trailing positional branch either (it starts with `-`), and used to
-    // vanish with no error. Splitting the token at its FIRST `=` and
-    // re-dispatching as two array elements makes every flag below see the
-    // exact shape it already handles — including a flag like `--param`
-    // whose own value legitimately contains `=` (`--param=tier=production`
-    // splits to flag `--param`, value `tier=production`, not further split
-    // on the second `=`).
-    if (arg.startsWith("--") && arg.includes("=")) {
-      const eq = arg.indexOf("=");
-      const flag = arg.slice(0, eq);
-      const value = arg.slice(eq + 1);
-      if (BOOLEAN_FLAGS.has(flag)) {
-        throw new Error(`${arg} — ${flag} is a boolean flag and does not take a value. Pass ${flag} on its own.`);
-      }
-      args.splice(i, 1, flag, value);
-      arg = args[i];
-    }
+    const arg = args[i];
 
     if (arg === "--help" || arg === "-h") {
       result.help = true;
@@ -348,9 +343,12 @@ export function parseArgs(args: string[]): ParsedArgs {
 }
 
 /**
- * Print help message
+ * Print help message. `groups` — lexicon-contributed command groups
+ * (chant #1078), best-effort loaded from the current project; composed in
+ * below the static command list so `--help` lists every mounted verb group
+ * alongside core's own commands.
  */
-function printHelp(): void {
+function printHelp(groups: CommandGroup[] = []): void {
   console.log(`
 chant - Declarative infrastructure specification toolkit
 
@@ -575,6 +573,60 @@ Examples:
   chant describe myComponent src/
   chant describe myComponent src/ --format json
 `);
+  const groupsHelp = formatCommandGroupsHelp(groups);
+  if (groupsHelp) console.log(groupsHelp);
+}
+
+/**
+ * Best-effort load the current project's lexicon plugins for a purely
+ * read-only lookup (help composition, plugin-command dispatch) — never
+ * throws, empty on any failure (no config, no lexicons, not a chant
+ * project at all). Mirrors the existing best-effort loading already used
+ * for `emulator`/`components status` in {@link main} below.
+ */
+async function loadPluginsBestEffort(): Promise<LexiconPlugin[]> {
+  try {
+    const lexiconNames = await resolveProjectLexicons(resolve("."));
+    return await loadPlugins(lexiconNames);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * chant #1078 — the lexicon command-group seam's dispatch-time half. Core's
+ * own `parseArgs`/`resolveCommand` know nothing about a lexicon's mounted
+ * verbs, so this is only ever consulted after BOTH of those have already
+ * failed to make sense of the invocation: either `parseArgs` threw on a flag
+ * it doesn't recognize (which is *expected* for a mounted command's own
+ * vocabulary — core has none), or it parsed fine but `resolveCommand` found
+ * no match in the static registry (a mounted command with no extra flags,
+ * e.g. `chant kube version`). Either way, a lexicon-mounted command's group
+ * name and verb are always the first two CLI tokens (mirrors the `emulator
+ * <up|down|status>` compound shape from #920), so `rawArgv` — the untouched
+ * `process.argv.slice(2)` — is all this needs; nothing from the partially or
+ * fully parsed `ParsedArgs` is used, on purpose, since core's flag-parsing
+ * failure or success is irrelevant to a namespace it doesn't own.
+ *
+ * Returns `undefined` when nothing claims the leading token as a command
+ * group at all, so the caller falls back to its own error handling
+ * unchanged — a project with no lexicon exposing `commands()` (or none of
+ * its plugins matching) is completely unaffected.
+ */
+async function tryPluginCommand(rawArgv: string[]): Promise<number | undefined> {
+  const [groupName, verbName] = rawArgv;
+  if (!groupName || groupName.startsWith("-")) return undefined;
+
+  const plugins = await loadPluginsBestEffort();
+  const rawArgs = rawArgv.slice(2);
+  const result = await dispatchCommandGroup(plugins, groupName, verbName, rawArgs);
+
+  if (result.kind === "no-group") return undefined;
+  if (result.kind === "usage-error") {
+    console.error(formatError({ message: result.message, hint: result.hint }));
+    return 1;
+  }
+  return result.exitCode;
 }
 
 /**
@@ -688,10 +740,29 @@ const registry: CommandDef[] = [
  * Main entry point
  */
 async function main(): Promise<void> {
-  const args = parseArgs(process.argv.slice(2));
+  const rawArgv = process.argv.slice(2);
+
+  let args: ParsedArgs;
+  try {
+    args = parseArgs(rawArgv);
+  } catch (err) {
+    // chant #1078 — core's parser has no idea what flags a lexicon's own
+    // mounted verb accepts, so an "unknown flag" here is expected, not a
+    // real error, until we've checked whether this invocation actually
+    // targets a command group. `tryPluginCommand` returns `undefined` when
+    // nothing claims the leading token, in which case this was a genuine
+    // core-flag error and the original is rethrown unchanged.
+    const code = await tryPluginCommand(rawArgv);
+    if (code !== undefined) {
+      await flushAndExit(code);
+      return;
+    }
+    throw err;
+  }
 
   if (args.help || !args.command) {
-    printHelp();
+    const groups = await loadPluginsBestEffort().then(collectCommandGroups).catch(() => []);
+    printHelp(groups);
     process.exit(args.help ? 0 : 1);
   }
 
@@ -742,6 +813,15 @@ async function main(): Promise<void> {
 
   const match = resolveCommand(args, registry);
   if (!match) {
+    // chant #1078 — not one of core's own commands; check whether a lexicon
+    // mounted a command group under this name before giving up. This is the
+    // "parsed fine, matched nothing" trigger for the seam — the flag-error
+    // trigger is above, in the `parseArgs` catch block.
+    const code = await tryPluginCommand(rawArgv);
+    if (code !== undefined) {
+      await flushAndExit(code);
+      return;
+    }
     console.error(formatError({
       message: `Unknown command: ${args.command}`,
       hint: 'Run "chant --help" to see available commands',

package/src/codegen/generate.ts

@@ -27,6 +27,15 @@ export interface GenerateResult {
   properties: number;
   enums: number;
   warnings: Array<{ file: string; error: string }>;
+  /**
+   * Additional generated files, keyed by filename, produced by the optional
+   * {@link GeneratePipelineConfig.generateExtraArtifacts} hook. They come out
+   * of the same parse a lexicon's types and registry come out of, which is the
+   * point: an artifact derived here cannot drift from the types, the way a
+   * hand-maintained table beside them can (chant #1074's operation surface is
+   * the first of these).
+   */
+  extraArtifacts?: Record<string, string>;
 }
 
 /**
@@ -68,6 +77,14 @@ export interface GeneratePipelineConfig<T extends ParsedResult> {
   /** Generate runtime index with factory exports. */
   generateRuntimeIndex: (results: T[], naming: NamingStrategy) => string;
 
+  /**
+   * Optional extra artifacts from the same parsed results — filename → content.
+   * Used when a lexicon needs a second derived table alongside the registry and
+   * the types, and needs it to come from the same pass so the three cannot
+   * skew.
+   */
+  generateExtraArtifacts?: (results: T[], naming: NamingStrategy) => Record<string, string>;
+
   /** Optional pre-parse hook (patches, overlays, extra resources, etc.). */
   augmentSchemas?: (
     schemas: Map<string, Buffer>,
@@ -161,6 +178,13 @@ export async function generatePipeline<T extends ParsedResult>(
   log("Generating runtime index...");
   const indexTS = config.generateRuntimeIndex(results, naming);
 
+  let extraArtifacts: Record<string, string> | undefined;
+  if (config.generateExtraArtifacts) {
+    log("Generating extra artifacts...");
+    extraArtifacts = config.generateExtraArtifacts(results, naming);
+    log(`Generated ${Object.keys(extraArtifacts).length} extra artifact(s)`);
+  }
+
   // Count stats
   let resourceCount = 0;
   let propertyCount = 0;
@@ -179,6 +203,7 @@ export async function generatePipeline<T extends ParsedResult>(
     properties: propertyCount,
     enums: enumCount,
     warnings,
+    ...(extraArtifacts ? { extraArtifacts } : {}),
   };
 }
 

package/src/graph-ir-live.test.ts

@@ -60,6 +60,23 @@ describe("buildLiveGraphIr", () => {
     expect(node.attrs).toEqual({});
   });
 
+  // #1077 — owner-reference chain classification
+  it("carries runtimeOwner only when the owner chain resolves to a declared entity", () => {
+    const ir = buildLiveGraphIr([
+      {
+        lexicon: "k8s",
+        resources: {
+          "prod/web-abc": { type: "K8s::Core::Pod", status: "Running", ownerChain: { root: "declared", entity: "web" } },
+          "prod/other": { type: "K8s::Core::Pod", status: "Running", ownerChain: { root: "foreign" } },
+          "prod/plain": { type: "K8s::Core::Pod", status: "Running" },
+        },
+      },
+    ]);
+    expect(ir.nodes.find((n) => n.id === "prod/web-abc")!.runtimeOwner).toBe("web");
+    expect(ir.nodes.find((n) => n.id === "prod/other")!.runtimeOwner).toBeUndefined();
+    expect(ir.nodes.find((n) => n.id === "prod/plain")!.runtimeOwner).toBeUndefined();
+  });
+
   it("is deterministic for a fixed observation set", () => {
     expect(JSON.stringify(buildLiveGraphIr(observations))).toBe(
       JSON.stringify(buildLiveGraphIr(observations)),
@@ -85,6 +102,18 @@ describe("overlayGraphs (#780 drift overlay)", () => {
     expect(ir.nodes.map((n) => n.id).sort()).toEqual(["planned-db", "rogue-sg", "web-vpc"]);
     expect(ir.edges).toHaveLength(1);
   });
+
+  // #1077 — a provisioned, undeclared node whose owner chain reaches a
+  // declared entity paints `runtime`, not `warn` — it is expected runtime,
+  // not a foreign resource needing attention.
+  it("classifies a runtime child via _status, distinct from foreign", () => {
+    const podNode = { id: "prod/web-abc", kind: "K8s::Core::Pod", lexicon: "k8s", attrs: {}, runtimeOwner: "web" };
+    const liveWithChild: GraphIR = { nodes: [node("web-vpc"), node("rogue-sg"), podNode], edges: [], groups: {} };
+    const ir = overlayGraphs(liveWithChild, declared);
+    const statusOf = (id: string) => (ir.nodes.find((n) => n.id === id)!.attrs as { _status?: string })._status;
+    expect(statusOf("prod/web-abc")).toBe("runtime");
+    expect(statusOf("rogue-sg")).toBe("warn"); // still foreign — no runtimeOwner
+  });
 });
 
 describe("sourceOverlayGraphs (#821 source-anchored overlay)", () => {
@@ -135,6 +164,17 @@ describe("sourceOverlayGraphs (#821 source-anchored overlay)", () => {
     expect(ir.groups.byLexicon).toEqual({ aws: ["planned-db", "web-vpc"], k8s: ["app-ingress"] });
   });
 
+  // #1077 — a live, undeclared node whose owner chain reaches a declared
+  // entity is appended `runtime`, not `warn`, even though it is just as
+  // "foreign" (undeclared) from the declared graph's point of view.
+  it("appends a runtime child as `runtime`, distinct from foreign", () => {
+    const podNode = { id: "prod/web-abc", kind: "K8s::Core::Pod", lexicon: "k8s", attrs: {}, runtimeOwner: "app-ingress" };
+    const liveWithChild: GraphIR = { ...live, nodes: [...live.nodes, podNode] };
+    const ir = sourceOverlayGraphs(declared, liveWithChild);
+    expect(statusOf(ir, "prod/web-abc")).toBe("runtime");
+    expect(statusOf(ir, "rogue-sg")).toBe("warn"); // still foreign
+  });
+
   it("drops a live edge between two managed nodes — declared edges already cover it", () => {
     const liveDup: GraphIR = { ...live, edges: [{ from: "app-ingress", to: "web-vpc", kind: "ref", viaAttr: "live-label" }] };
     const ir = sourceOverlayGraphs(declared, liveDup);

package/src/graph-ir.ts

@@ -67,6 +67,15 @@ export interface IRNode {
    * `owned` = chant-managed. Absent for source-derived IR.
    */
   ownership?: "owned" | "foreign";
+  /**
+   * Live-only, undeclared nodes: the declared entity this node's
+   * owner-reference chain resolves to (#1077) — a Pod a declared Deployment's
+   * controller created, for instance. Presence of this field is what an
+   * overlay reads to paint the node `runtime` instead of `warn`/foreign; a
+   * node without it (including every declared, source-derived node) is
+   * unaffected.
+   */
+  runtimeOwner?: string;
 }
 
 /** A directed dependency: `from` references an attribute of `to`. */
@@ -504,6 +513,11 @@ export function buildLiveGraphIr(observations: LiveObservation[]): GraphIR {
       // information for a painter, and the IR's `ownership` field means "a
       // verdict was reached" — so only owned/foreign land on the node.
       if (meta.ownership === "owned" || meta.ownership === "foreign") node.ownership = meta.ownership;
+      // Owner-reference chain (#1077): only a resolved `declared` root is
+      // carried onto the node — the same "a verdict was reached" rule as
+      // ownership above, since `unowned`/`foreign`/`unknown` all mean "no
+      // declared owner", which is simply the absence of this field.
+      if (meta.ownerChain?.root === "declared") node.runtimeOwner = meta.ownerChain.entity;
       nodes.push(node);
       (byLexicon[lexicon] ??= []).push(name);
       // A live lexicon maps to one deployable stack, same as the source IR.
@@ -540,8 +554,9 @@ export function collectUnobserved(observations: LiveObservation[]): Record<strin
   return out;
 }
 
-/** Paint status a node carries in an overlay. `neutral` = chant could not look. */
-type OverlayNodeStatus = "good" | "warn" | "accent" | "neutral";
+/** Paint status a node carries in an overlay. `neutral` = chant could not look;
+ * `runtime` = live, undeclared, owner chain reaches a declared entity (#1077). */
+type OverlayNodeStatus = "good" | "warn" | "accent" | "neutral" | "runtime";
 
 function tagStatus(n: IRNode, status: OverlayNodeStatus, unobserved?: UnobservedEntity): IRNode {
   return {
@@ -558,7 +573,10 @@ function tagStatus(n: IRNode, status: OverlayNodeStatus, unobserved?: Unobserved
  * Overlay the declared graph on the provisioned one (#780, `chant graph --live
  * --overlay`) and classify each resource, tagging a `_status` a renderer colours:
  *   - **managed** (declared + provisioned) → `good`
- *   - **foreign** (provisioned, not declared) → `warn`
+ *   - **runtime** (provisioned, not declared, owner chain reaches a declared
+ *     entity — #1077) → `runtime`, e.g. a Pod a declared Deployment's
+ *     controller created — expected, not a foreign resource needing attention
+ *   - **foreign** (provisioned, not declared, no declared owner) → `warn`
  *   - **pending** (declared, provider confirmed absent) → `accent`
  *   - **unobserved** (declared, chant could not look — #1089) → `neutral`,
  *     plus an `_unobserved` attr carrying the reason
@@ -570,7 +588,9 @@ export function overlayGraphs(live: GraphIR, declared: GraphIR, opts?: OverlayOp
   const liveIds = new Set(live.nodes.map((n) => n.id));
   const unobserved = opts?.unobserved ?? {};
 
-  const nodes: IRNode[] = live.nodes.map((n) => tagStatus(n, declaredIds.has(n.id) ? "good" : "warn"));
+  const nodes: IRNode[] = live.nodes.map((n) =>
+    tagStatus(n, declaredIds.has(n.id) ? "good" : n.runtimeOwner ? "runtime" : "warn"),
+  );
   for (const n of declared.nodes) {
     if (liveIds.has(n.id)) continue;
     const u = unobserved[n.id];
@@ -597,8 +617,10 @@ export function overlayGraphs(live: GraphIR, declared: GraphIR, opts?: OverlayOp
  *     the reason on `_unobserved`. A wrong-cluster or unsupported-kind read used
  *     to paint the whole estate "pending", which is the diagram equivalent of
  *     planning a create for something that already exists.
- * **Foreign** resources (provisioned, not declared) are appended and tagged
- * `warn`, together with any live-reconstructed edges that touch them — a declared
+ * **Foreign** resources (provisioned, not declared, no declared owner) are
+ * appended and tagged `warn`; a provisioned-but-undeclared resource whose
+ * owner chain reaches a declared entity (#1077) is tagged `runtime` instead —
+ * both carry any live-reconstructed edges that touch them, since a declared
  * edge cannot describe an undeclared resource. Declared groups/exports pass
  * through unchanged; nodes and edges are sorted for deterministic output.
  */
@@ -620,7 +642,10 @@ export function sourceOverlayGraphs(declared: GraphIR, live: GraphIR, opts?: Ove
     if (obs.ownership) merged.ownership = obs.ownership;
     return tagStatus(merged, "good");
   });
-  for (const n of live.nodes) if (foreignIds.has(n.id)) nodes.push(tagStatus(n, "warn")); // foreign
+  for (const n of live.nodes) {
+    if (!foreignIds.has(n.id)) continue;
+    nodes.push(tagStatus(n, n.runtimeOwner ? "runtime" : "warn")); // runtime child or foreign
+  }
   nodes.sort((a, b) => a.id.localeCompare(b.id));
 
   // Declared edges are the canvas (the cross-substrate topology). Add only the

package/src/index.ts

@@ -50,6 +50,7 @@ export * from "./import/generator";
 export * from "./lexicon";
 export * from "./observation";
 export * from "./deep-observation";
+export * from "./owner-chain";
 export * from "./lexicon-integrity";
 export * from "./lexicon-manifest";
 export * from "./lexicon-schema";

package/src/kubectl-context.ts

@@ -72,8 +72,18 @@ export interface ResolvedClusterTarget {
   source: "bound" | "ambient";
 }
 
+/**
+ * How the resolver learns which context is ambient. The default shells
+ * `kubectl config current-context`; the k8s lexicon's typed API client
+ * (chant #1074) supplies one that reads the parsed kubeconfig instead, so a
+ * client that never needs the `kubectl` binary does not acquire a dependency
+ * on it just to check the binding. Both answer the same question, so the
+ * refusal semantics below are identical either way.
+ */
+export type AmbientContextReader = () => Promise<string | undefined>;
+
 /** Reads `kubectl config current-context`. Returns undefined if unset or kubectl fails. */
-async function currentAmbientContext(): Promise<string | undefined> {
+const currentAmbientContext: AmbientContextReader = async () => {
   try {
     const { stdout } = await execAsync("kubectl config current-context");
     const trimmed = stdout.trim();
@@ -81,6 +91,15 @@ async function currentAmbientContext(): Promise<string | undefined> {
   } catch {
     return undefined;
   }
+};
+
+/** Options for {@link resolveClusterTarget}. */
+export interface ResolveClusterTargetOptions {
+  /**
+   * Override how the ambient context is read. Defaults to
+   * `kubectl config current-context`.
+   */
+  ambientContext?: AmbientContextReader;
 }
 
 /**
@@ -105,6 +124,7 @@ export async function resolveClusterTarget(
   config: Record<string, unknown>,
   environment: string,
   lexiconName: string,
+  options: ResolveClusterTargetOptions = {},
 ): Promise<ResolvedClusterTarget> {
   const k8sConfig = config.k8s as K8sConfigShape | undefined;
   const bound = k8sConfig?.profiles?.[environment]?.context;
@@ -118,7 +138,7 @@ export async function resolveClusterTarget(
     return { source: "ambient" };
   }
 
-  const ambient = await currentAmbientContext();
+  const ambient = await (options.ambientContext ?? currentAmbientContext)();
   if (ambient && ambient !== bound) {
     throw new ClusterBindingMismatchError(environment, bound, ambient);
   }

package/src/lexicon.ts

@@ -13,6 +13,12 @@ import type { RuleMeta } from "./audit/catalog";
 import type { ReferenceCatalog } from "./graph-refs";
 import type { DescribeResourcesResult } from "./observation";
 import type { DeepNormalizationHooks, DeepObservationResult } from "./deep-observation";
+import type { OwnerChainVerdict } from "./owner-chain";
+import type { CommandGroup } from "./cli/command-group";
+
+// Re-exported so a lexicon can author its command group (#1078) from the
+// same `@intentius/chant/lexicon` entry it imports the plugin contract from.
+export type { CommandGroup, CommandGroupCommand, CommandGroupContext } from "./cli/command-group";
 
 // Re-exported so lexicons can author a reference catalog (#778) from the same
 // `@intentius/chant/lexicon` entry they import the plugin contract from.
@@ -434,6 +440,24 @@ export interface LexiconPlugin {
    * account. Absent when the lexicon has no local emulator. */
   readonly emulator?: EmulatorCapability;
 
+  /**
+   * A CLI verb group this lexicon contributes, mounted under `chant <name>
+   * <verb>` (#1078). Core learns that a lexicon MAY contribute a command
+   * group and learns nothing about what is inside it — it finds the group by
+   * name and dispatches to the matched verb's handler wholesale, the same
+   * "spec, not behavior" shape as {@link emulator}. Unlike `emulator`, which
+   * core itself aggregates across every configured lexicon in one command
+   * (`chant emulator up --all`), a command group is owned end-to-end by ONE
+   * lexicon: `get -o wide -l app=x --field-selector` is irreducibly
+   * Kubernetes vocabulary, not something core could generalize or merge
+   * across plugins even if it wanted to. Absent when the lexicon contributes
+   * no CLI surface — registering nothing here changes nothing else about how
+   * the lexicon behaves; the build/fold path never calls this or invokes any
+   * verb's handler, since command dispatch happens only in the CLI's own
+   * entry point, never in discovery/build/fold.
+   */
+  commands?(): CommandGroup;
+
   // ── Optional extensions ───────────────────────────────────
   /** Return lint rules provided by this lexicon */
   lintRules?(): LintRule[];
@@ -555,6 +579,13 @@ export interface LexiconPlugin {
    * `ownership: "unknown"` on what it returns rather than degrading silently —
    * the change set never escalates `unknown` to a `delete`.
    *
+   * An undeclared entry this method returns may carry {@link
+   * ResourceMetadata.ownerChain} (#1077) — set it when the provider's own
+   * parent/child graph (Kubernetes `ownerReferences`) shows this object's
+   * chain reaching a declared entity, so the diff engine classifies it
+   * `runtime` instead of `orphan`. Optional; a lexicon that never sets it
+   * keeps every undeclared entry classified `orphan`, unchanged.
+   *
    * `entities` carries the chant-side entity declarations for this lexicon,
    * keyed by chant entity name (e.g. the export name from a `*.ts` file).
    * Implementations that need to map cloud-side names back to chant entity
@@ -783,6 +814,19 @@ export interface ResourceMetadata {
    * a delete, and never escalates `unknown` to one.
    */
   ownership?: "owned" | "foreign" | "unknown";
+  /**
+   * Where this resource's owner-reference chain leads, for a live resource
+   * that is not itself declared (#1077). A lexicon that maintains an
+   * owner-reference graph (Kubernetes) sets this on an undeclared entry it
+   * returns; the diff engine reads `{ root: "declared" }` as `runtime`
+   * (a Pod a declared Deployment's controller created) rather than `orphan`.
+   * Distinct from {@link ownership}: that is chant's own managed-by marker,
+   * this is the provider's native parent/child graph — a runtime child
+   * usually carries no chant marker of its own at all. Absent means the
+   * lexicon supplies no chain, which is exactly today's behavior: every
+   * undeclared live resource stays `orphan`.
+   */
+  ownerChain?: OwnerChainVerdict;
 }
 
 /**