@intentius/chant 0.31.0 → 0.32.0

package/dist/owner-chain.d.ts

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

package/dist/owner-chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner-chain.d.ts","sourceRoot":"","sources":["../src/owner-chain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAEjC;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;4BAK4B;AAC5B,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,EAC1C,QAAQ,GAAE,MAAsC,GAC/C,iBAAiB,CA2BnB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/cli/command-group.test.ts

@@ -0,0 +1,208 @@
+import { describe, test, expect } from "vitest";
+import type { LexiconPlugin } from "../lexicon";
+import {
+  resolveCommandGroupVerb,
+  collectCommandGroups,
+  dispatchCommandGroup,
+  formatCommandGroupsHelp,
+  splitJoinedFlags,
+  unknownFlagError,
+  RESERVED_COMMAND_NAMES,
+  type CommandGroup,
+} from "./command-group";
+
+const noopAsync = async () => {};
+
+/** Minimal LexiconPlugin — only the fields relevant to a given test. */
+function makePlugin(name: string, group?: CommandGroup): LexiconPlugin {
+  const plugin: LexiconPlugin = {
+    name,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    serializer: { name, serialize: () => "" } as any,
+    generate: noopAsync,
+    validate: noopAsync,
+    coverage: noopAsync,
+    package: noopAsync,
+  };
+  if (group) plugin.commands = () => group;
+  return plugin;
+}
+
+function makeGroup(overrides: Partial<CommandGroup> = {}): CommandGroup {
+  return {
+    name: "kube",
+    description: "Kubernetes verb group",
+    commands: [
+      { name: "get", description: "Get resources", handler: async () => 0 },
+      { name: "version", description: "Print schema version", handler: async () => 0 },
+    ],
+    ...overrides,
+  };
+}
+
+describe("resolveCommandGroupVerb", () => {
+  test("mounts: finds the group and verb contributed by a plugin", () => {
+    const group = makeGroup();
+    const plugins = [makePlugin("k8s", group)];
+    const result = resolveCommandGroupVerb(plugins, "kube", "get");
+    expect(result.kind).toBe("matched");
+    if (result.kind === "matched") {
+      expect(result.plugin.name).toBe("k8s");
+      expect(result.group).toBe(group);
+      expect(result.command.name).toBe("get");
+    }
+  });
+
+  test("no-capability lexicon is unaffected: a plugin with no commands() is skipped", () => {
+    const plugins = [makePlugin("aws"), makePlugin("k8s", makeGroup())];
+    const result = resolveCommandGroupVerb(plugins, "kube", "get");
+    expect(result.kind).toBe("matched");
+  });
+
+  test("returns no-group when nothing claims the namespace", () => {
+    const plugins = [makePlugin("aws"), makePlugin("gcp")];
+    const result = resolveCommandGroupVerb(plugins, "kube", "get");
+    expect(result.kind).toBe("no-group");
+  });
+
+  test("returns no-group for an empty plugin list", () => {
+    expect(resolveCommandGroupVerb([], "kube", "get").kind).toBe("no-group");
+  });
+
+  test("returns unknown-verb when the group matches but the verb doesn't", () => {
+    const plugins = [makePlugin("k8s", makeGroup())];
+    const result = resolveCommandGroupVerb(plugins, "kube", "bogus");
+    expect(result.kind).toBe("unknown-verb");
+    if (result.kind === "unknown-verb") {
+      expect(result.group.name).toBe("kube");
+    }
+  });
+
+  test("returns no-verb when the group matches and no verb was given", () => {
+    const plugins = [makePlugin("k8s", makeGroup())];
+    const result = resolveCommandGroupVerb(plugins, "kube", undefined);
+    expect(result.kind).toBe("no-verb");
+  });
+
+  test("never invokes a verb's handler while resolving — registration is data, not execution", () => {
+    let invoked = false;
+    const group: CommandGroup = {
+      name: "kube",
+      description: "d",
+      commands: [{ name: "get", description: "d", handler: async () => { invoked = true; return 0; } }],
+    };
+    resolveCommandGroupVerb([makePlugin("k8s", group)], "kube", "get");
+    expect(invoked).toBe(false);
+  });
+});
+
+describe("collectCommandGroups", () => {
+  test("lists groups from plugins in order; skips plugins without one", () => {
+    const g1 = makeGroup({ name: "kube" });
+    const g2 = makeGroup({ name: "flycmd", description: "Fly verb group" });
+    const groups = collectCommandGroups([makePlugin("aws"), makePlugin("k8s", g1), makePlugin("fly", g2)]);
+    expect(groups).toEqual([g1, g2]);
+  });
+
+  test("empty when no plugin contributes a group — an absent slot changes nothing", () => {
+    expect(collectCommandGroups([makePlugin("aws"), makePlugin("gcp")])).toEqual([]);
+  });
+});
+
+describe("dispatchCommandGroup", () => {
+  test("dispatches: runs the matched verb's handler and returns its exit code", async () => {
+    let seenCtx: unknown;
+    const group: CommandGroup = {
+      name: "kube",
+      description: "d",
+      commands: [
+        {
+          name: "get",
+          description: "d",
+          handler: async (ctx) => {
+            seenCtx = ctx;
+            return 3;
+          },
+        },
+      ],
+    };
+    const result = await dispatchCommandGroup([makePlugin("k8s", group)], "kube", "get", ["pods", "-o", "wide"]);
+    expect(result).toEqual({ kind: "ran", exitCode: 3 });
+    expect(seenCtx).toEqual({ verb: "get", rawArgs: ["pods", "-o", "wide"] });
+  });
+
+  test("propagates a no-group result unchanged", async () => {
+    const result = await dispatchCommandGroup([makePlugin("aws")], "kube", "get", []);
+    expect(result).toEqual({ kind: "no-group" });
+  });
+
+  test("unknown verb produces a usage-error listing the group's real verbs", async () => {
+    const result = await dispatchCommandGroup([makePlugin("k8s", makeGroup())], "kube", "bogus", []);
+    expect(result.kind).toBe("usage-error");
+    if (result.kind === "usage-error") {
+      expect(result.message).toMatch(/Unknown kube subcommand: bogus/);
+      expect(result.hint).toMatch(/get/);
+      expect(result.hint).toMatch(/version/);
+    }
+  });
+
+  test("bare group with no verb produces a usage-error, not a crash", async () => {
+    const result = await dispatchCommandGroup([makePlugin("k8s", makeGroup())], "kube", undefined, []);
+    expect(result.kind).toBe("usage-error");
+    if (result.kind === "usage-error") {
+      expect(result.message).toMatch(/Usage: chant kube <verb>/);
+    }
+  });
+});
+
+describe("formatCommandGroupsHelp", () => {
+  test("composes group + verb listing for --help", () => {
+    const text = formatCommandGroupsHelp([makeGroup()]);
+    expect(text).toMatch(/Lexicon commands:/);
+    expect(text).toMatch(/kube/);
+    expect(text).toMatch(/get/);
+    expect(text).toMatch(/version/);
+  });
+
+  test("empty string when there are no groups", () => {
+    expect(formatCommandGroupsHelp([])).toBe("");
+  });
+});
+
+describe("splitJoinedFlags (#1127 discipline, reused by mounted commands)", () => {
+  test("splits a joined --flag=value token into two elements", () => {
+    expect(splitJoinedFlags(["--format=json"])).toEqual(["--format", "json"]);
+  });
+
+  test("splits only at the first =, preserving a value that itself contains =", () => {
+    expect(splitJoinedFlags(["--selector=env=prod"])).toEqual(["--selector", "env=prod"]);
+  });
+
+  test("leaves non-joined tokens untouched", () => {
+    expect(splitJoinedFlags(["get", "pods", "-o", "wide"])).toEqual(["get", "pods", "-o", "wide"]);
+  });
+
+  test("throws when a declared boolean flag is given a joined value", () => {
+    expect(() => splitJoinedFlags(["--watch=true"], new Set(["--watch"]))).toThrow(/--watch is a boolean flag/);
+  });
+});
+
+describe("unknownFlagError (mounted-command unknown-flag error)", () => {
+  test("produces the same 'Unknown flag' message shape core's own parser uses", () => {
+    const err = unknownFlagError("--bogus");
+    expect(err.message).toMatch(/^Unknown flag: --bogus/);
+  });
+
+  test("accepts a custom hint for the mounted command's own usage", () => {
+    const err = unknownFlagError("--bogus", "chant kube version only accepts --format.");
+    expect(err.message).toMatch(/only accepts --format/);
+  });
+});
+
+describe("RESERVED_COMMAND_NAMES", () => {
+  test("includes every core top-level word a lexicon must not shadow", () => {
+    for (const name of ["build", "lint", "run", "emulator", "lifecycle", "components", "serve", "dev", "carve"]) {
+      expect(RESERVED_COMMAND_NAMES.has(name)).toBe(true);
+    }
+  });
+});

package/src/cli/command-group.ts

@@ -0,0 +1,199 @@
+import type { LexiconPlugin } from "../lexicon";
+
+/**
+ * The lexicon command-group seam (chant #1078).
+ *
+ * A lexicon may contribute one CLI verb group, mounted under `chant <name>
+ * <verb>` (e.g. `chant kube get`). Core's only job is to find the group and
+ * call the matched verb's handler — it never inspects, validates, or
+ * special-cases what a verb does. That is the whole point: `get -o wide -l
+ * app=x --field-selector` is Kubernetes vocabulary, not something core could
+ * generalize even if it tried (see #1078's motivating case, consumed by
+ * #1079's `chant kube`).
+ *
+ * This is a DIFFERENT shape from `LexiconPlugin.emulator` (#920): the
+ * emulator capability is DATA that core itself aggregates across every
+ * configured lexicon (`chant emulator up --all` loops every plugin with an
+ * `emulator`). A command group is BEHAVIOR owned end-to-end by one lexicon —
+ * core dispatches to it wholesale and never loops or merges across plugins.
+ * The two capabilities are not layers of the same thing; migrating
+ * `emulator` onto this seam would be a worse fit, not a simplification.
+ */
+
+/** Context handed to a mounted command's handler. */
+export interface CommandGroupContext {
+  /** The verb invoked, e.g. `"get"` for `chant kube get pods`. */
+  verb: string;
+  /**
+   * Every CLI token after the group name and verb, unparsed — e.g. `chant
+   * kube get pods -o wide` hands `["pods", "-o", "wide"]`. Core does not
+   * interpret these: it has no vocabulary for a lexicon's own verbs. A
+   * handler that wants #1127's joined-`--flag=value` splitting and
+   * unknown-flag rejection can reuse {@link splitJoinedFlags} /
+   * {@link unknownFlagError} from this module for the same discipline core's
+   * own parser applies, scoped to whatever flags this verb actually accepts.
+   */
+  rawArgs: string[];
+}
+
+/** One verb within a lexicon-contributed command group. */
+export interface CommandGroupCommand {
+  /** Verb name, e.g. `"get"`, `"logs"`, `"version"`. */
+  name: string;
+  /** One-line description shown in `chant --help` and in usage errors. */
+  description: string;
+  /** Runs the verb. Returns the process exit code. */
+  handler: (ctx: CommandGroupContext) => Promise<number>;
+}
+
+/**
+ * A CLI verb group contributed by a lexicon (chant #1078). Mounted under
+ * `chant <name> <verb>`. Returned from {@link LexiconPlugin.commands}.
+ */
+export interface CommandGroup {
+  /** Namespace this group mounts under, e.g. `"kube"` for `chant kube <verb>`. */
+  name: string;
+  /** One-line description shown in `chant --help`'s composed listing. */
+  description: string;
+  /** Verbs in this group. */
+  commands: CommandGroupCommand[];
+}
+
+/**
+ * Top-level command words core's own static registry already owns
+ * (`packages/core/src/cli/main.ts`'s `registry`). A lexicon's `commands()`
+ * group name colliding with one of these is always unreachable — core's own
+ * registry is resolved first, unconditionally — so `checkConflicts`
+ * (./conflict-check.ts) treats a collision as a hard, loud failure at
+ * plugin-load time rather than a silently-ignored command group. Hand
+ * maintained alongside the registry; update both together.
+ */
+export const RESERVED_COMMAND_NAMES: ReadonlySet<string> = new Set([
+  "build", "lint", "list", "describe", "import", "audit", "migrate", "carve",
+  "init", "update", "doctor", "dev", "run", "graph", "vendor", "lifecycle",
+  "lc", "components", "emulator", "serve",
+]);
+
+/**
+ * chant #1127 — split a joined `--flag=value` token into two array elements
+ * (`--flag`, `value`), the same discipline core's own `parseArgs` applies,
+ * generalized so a lexicon's mounted command can reuse it for its own flag
+ * vocabulary instead of reimplementing the split. Throws the same shape of
+ * error as core's parser when `flag` is declared boolean but was given a
+ * value — a boolean has nothing to assign, and silently reinterpreting the
+ * joined value as the next positional would be exactly the silent misparse
+ * #1127 closed for core's own flags.
+ */
+export function splitJoinedFlags(args: string[], booleanFlags: ReadonlySet<string> = new Set()): string[] {
+  const out: string[] = [];
+  for (const arg of args) {
+    if (arg.startsWith("--") && arg.includes("=")) {
+      const eq = arg.indexOf("=");
+      const flag = arg.slice(0, eq);
+      const value = arg.slice(eq + 1);
+      if (booleanFlags.has(flag)) {
+        throw new Error(`${arg} — ${flag} is a boolean flag and does not take a value. Pass ${flag} on its own.`);
+      }
+      out.push(flag, value);
+    } else {
+      out.push(arg);
+    }
+  }
+  return out;
+}
+
+/**
+ * Same "Unknown flag" error shape core's own `parseArgs` throws (#1127), for
+ * a mounted command's own flag vocabulary — core doesn't know that
+ * vocabulary, so it can't produce this error itself; the handler does, using
+ * this helper for a consistent message.
+ */
+export function unknownFlagError(flag: string, hint = `Run "chant --help" to see supported flags.`): Error {
+  return new Error(`Unknown flag: ${flag}\n${hint}`);
+}
+
+/** Result of looking up a command group + verb among loaded plugins. */
+export type CommandGroupLookup =
+  | { kind: "no-group" }
+  | { kind: "no-verb"; group: CommandGroup }
+  | { kind: "unknown-verb"; group: CommandGroup }
+  | { kind: "matched"; plugin: LexiconPlugin; group: CommandGroup; command: CommandGroupCommand };
+
+/**
+ * Find the plugin (if any) whose `commands()` group is named `groupName`,
+ * and the verb within it named `verbName`. Pure — does no I/O, calls
+ * `plugin.commands()` at most once per plugin (registration, not execution:
+ * this never invokes a verb's handler).
+ */
+export function resolveCommandGroupVerb(
+  plugins: readonly LexiconPlugin[],
+  groupName: string,
+  verbName: string | undefined,
+): CommandGroupLookup {
+  for (const plugin of plugins) {
+    const group = plugin.commands?.();
+    if (!group || group.name !== groupName) continue;
+    if (verbName === undefined) return { kind: "no-verb", group };
+    const command = group.commands.find((c) => c.name === verbName);
+    if (!command) return { kind: "unknown-verb", group };
+    return { kind: "matched", plugin, group, command };
+  }
+  return { kind: "no-group" };
+}
+
+/** Every command group contributed by the given loaded plugins, in plugin order. */
+export function collectCommandGroups(plugins: readonly LexiconPlugin[]): CommandGroup[] {
+  const groups: CommandGroup[] = [];
+  for (const plugin of plugins) {
+    const group = plugin.commands?.();
+    if (group) groups.push(group);
+  }
+  return groups;
+}
+
+/** Result of {@link dispatchCommandGroup}. */
+export type CommandGroupDispatch =
+  | { kind: "no-group" }
+  | { kind: "usage-error"; message: string; hint: string }
+  | { kind: "ran"; exitCode: number };
+
+/**
+ * Resolve `groupName`/`verbName` against the loaded plugins and, if matched,
+ * run the verb's handler with `rawArgs`. Returns `{ kind: "no-group" }` when
+ * nothing claims `groupName` at all — the caller's cue to fall back to its
+ * own "unknown command" handling — and a printable usage error when the
+ * group matched but the verb didn't (or was omitted).
+ */
+export async function dispatchCommandGroup(
+  plugins: readonly LexiconPlugin[],
+  groupName: string,
+  verbName: string | undefined,
+  rawArgs: string[],
+): Promise<CommandGroupDispatch> {
+  const lookup = resolveCommandGroupVerb(plugins, groupName, verbName);
+  if (lookup.kind === "no-group") return { kind: "no-group" };
+  if (lookup.kind === "matched") {
+    const exitCode = await lookup.command.handler({ verb: verbName as string, rawArgs });
+    return { kind: "ran", exitCode };
+  }
+  const verbs = lookup.group.commands.map((c) => `  ${c.name.padEnd(14)} ${c.description}`).join("\n");
+  const message =
+    lookup.kind === "unknown-verb"
+      ? `Unknown ${groupName} subcommand: ${verbName}`
+      : `Usage: chant ${groupName} <verb> [args...]`;
+  return { kind: "usage-error", message, hint: `Available verbs:\n${verbs}` };
+}
+
+/**
+ * Render the `--help` section listing every lexicon-contributed command
+ * group. Empty string when there are none, so a caller can splice it in
+ * unconditionally without an extra length check.
+ */
+export function formatCommandGroupsHelp(groups: readonly CommandGroup[]): string {
+  if (groups.length === 0) return "";
+  const lines = groups.flatMap((g) => [
+    `  ${g.name.padEnd(20)}  ${g.description}`,
+    ...g.commands.map((c) => `    ${g.name} ${c.name.padEnd(Math.max(1, 17 - g.name.length))}${c.description}`),
+  ]);
+  return `Lexicon commands:\n${lines.join("\n")}\n`;
+}

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}`);