@intentius/chant 0.31.0 → 0.32.0

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/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/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;
 }
 
 /**

package/src/lifecycle/change-set.test.ts

@@ -106,6 +106,77 @@ describe("buildChangeSet (#118)", () => {
     expect(cs.entries.filter((e) => e.action === "adopt").map((e) => e.name)).toEqual(["b", "c"]);
   });
 
+  // ── Owner-reference chain classification (#1077) ──────────────────────────
+
+  test("undeclared, owner chain reaches a declared entity → runtime, never delete or adopt", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["web"]),
+      observedNow: {
+        web: meta({ type: "K8s::Apps::Deployment" }),
+        "prod/web-abc": meta({ type: "K8s::Core::Pod", ownerChain: { root: "declared", entity: "web" } }),
+      },
+      observedThen: undefined,
+    });
+    const e = cs.entries.find((x) => x.name === "prod/web-abc")!;
+    expect(e.action).toBe("runtime");
+    expect(e.runtimeOwner).toBe("web");
+  });
+
+  test("a runtime child that also carries chant's own ownership marker is still `runtime`, never `delete`", () => {
+    // Guards the ordering in buildChangeSet: runtimeOwner must be checked
+    // before the ownership marker, in case a runtime child ever inherits the
+    // marker (e.g. label propagation from its owner's pod template).
+    const cs = buildChangeSet("prod", {
+      declared: new Set(),
+      observedNow: {
+        "prod/web-abc": meta({ ownership: "owned", ownerChain: { root: "declared", entity: "web" } }),
+      },
+      observedThen: undefined,
+    });
+    const e = cs.entries.find((x) => x.name === "prod/web-abc")!;
+    expect(e.action).toBe("runtime");
+  });
+
+  test("undeclared, unowned → orphan/adopt, not runtime", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(),
+      observedNow: { "prod/standalone": meta({ ownerChain: { root: "unowned" } }) },
+      observedThen: undefined,
+    });
+    const e = cs.entries.find((x) => x.name === "prod/standalone")!;
+    expect(e.action).toBe("adopt");
+    expect(e.runtimeOwner).toBeUndefined();
+  });
+
+  test("undeclared, foreign root → orphan/adopt, not runtime", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(),
+      observedNow: { "prod/other": meta({ ownerChain: { root: "foreign" } }) },
+      observedThen: undefined,
+    });
+    expect(cs.entries.find((x) => x.name === "prod/other")!.action).toBe("adopt");
+  });
+
+  test("undeclared, unresolved chain (unreadable/cycle/depth) → conservative adopt, not runtime", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(),
+      observedNow: { "prod/mystery": meta({ ownerChain: { root: "unknown" } }) },
+      observedThen: undefined,
+    });
+    const e = cs.entries.find((x) => x.name === "prod/mystery")!;
+    expect(e.action).toBe("adopt");
+    expect(e.runtimeOwner).toBeUndefined();
+  });
+
+  test("a lexicon with no owner chain at all is unaffected — undeclared stays adopt/delete as before", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(),
+      observedNow: { orphan: meta({ ownership: "owned" }) },
+      observedThen: undefined,
+    });
+    expect(cs.entries.find((x) => x.name === "orphan")!.action).toBe("delete");
+  });
+
   test("only in snapshot (gone now, undeclared) → noop", () => {
     const cs = buildChangeSet("prod", {
       declared: new Set(),
@@ -148,6 +219,23 @@ describe("summarize / renderChangeSet", () => {
     expect(out).toContain("ADOPT:");
     expect(out).toContain("orphan");
   });
+
+  test("summarize and render surface the runtime action (#1077)", () => {
+    const withRuntime = buildChangeSet("prod", {
+      declared: new Set(["web"]),
+      observedNow: {
+        web: meta({ type: "K8s::Apps::Deployment" }),
+        "prod/web-abc": meta({ type: "K8s::Core::Pod", ownerChain: { root: "declared", entity: "web" } }),
+      },
+      observedThen: undefined,
+    });
+    expect(summarize(withRuntime).runtime).toBe(1);
+    expect(summarize(withRuntime).adopt).toBe(0);
+    const out = renderChangeSet(withRuntime);
+    expect(out).toContain("RUNTIME");
+    expect(out).toContain("prod/web-abc");
+    expect(out).toContain("owned by web");
+  });
 });
 
 describe("gitlabMrReport (#329)", () => {
@@ -169,6 +257,18 @@ describe("gitlabMrReport (#329)", () => {
     expect(gitlabMrReport(cs)).toEqual({ create: 1, update: 1, delete: 1 });
   });
 
+  test("a runtime child (#1077) is excluded from the widget — never counted as a change", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["web"]),
+      observedNow: {
+        web: meta({ type: "K8s::Apps::Deployment" }),
+        "prod/web-abc": meta({ type: "K8s::Core::Pod", ownerChain: { root: "declared", entity: "web" } }),
+      },
+      observedThen: undefined,
+    });
+    expect(gitlabMrReport(cs)).toEqual({ create: 0, update: 0, delete: 0 });
+  });
+
   test("empty plan reports all zeros", () => {
     const cs = buildChangeSet("prod", {
       declared: new Set(),

package/src/lifecycle/change-set.ts

@@ -3,8 +3,8 @@
  *
  * `chant lifecycle diff --live` computes a three-way comparison — declared now /
  * last snapshot / live now — and prints it. `buildChangeSet` promotes that
- * same signal into a classified create/update/delete/adopt/noop set that other
- * tooling (reconcile, apply) can act on.
+ * same signal into a classified create/update/delete/adopt/runtime/noop set
+ * that other tooling (reconcile, apply) can act on.
  *
  * Strictly read-only and pure: no I/O, no mutation. The classification reads
  * ownership from the live marker only (populated downstream); until ownership
@@ -25,12 +25,17 @@ import { unobservedReasonText, type UnobservedReason } from "../observation";
  *   snapshot.
  * - `adopt` — live but undeclared, ownership not established → a candidate to
  *   pull back into source, never an auto-delete.
+ * - `runtime` — live but undeclared, and its owner-reference chain reaches a
+ *   declared entity (#1077): a Pod a declared Deployment's controller
+ *   created, for instance. Never a delete, never an adopt candidate — it is
+ *   not drift, just the runtime doing its job. `runtimeOwner` names the
+ *   declared entity it belongs to.
  * - `noop` — declared and live with no drift, or already reconciled.
  * - `unobserved` — declared, and the lexicon could not look (#1089). Not a
  *   proposal at all: it is the plan admitting a hole. Never a create, never a
  *   delete. Read `unobservedReason` for which hole.
  */
-export type ChangeAction = "create" | "update" | "delete" | "adopt" | "noop" | "unobserved";
+export type ChangeAction = "create" | "update" | "delete" | "adopt" | "runtime" | "noop" | "unobserved";
 
 /**
  * Who answers "is this resource chant's?". `unknown` until a live ownership
@@ -69,6 +74,8 @@ export interface ChangeSetEntry {
   unobservedReason?: UnobservedReason;
   /** Human-readable backing for `unobservedReason` (the failing command, the missing binding). */
   unobservedDetail?: string;
+  /** The declared entity this resource's owner chain resolves to, for `action: "runtime"` (#1077). */
+  runtimeOwner?: string;
 }
 
 export interface ChangeSet {
@@ -121,6 +128,15 @@ export function buildChangeSet(env: string, input: DiffLiveInput): ChangeSet {
     // record chant has to host.
     const ownership: Ownership = observedNow[name]?.ownership ?? "unknown";
 
+    // Owner-reference chain (#1077), same live-only provenance as ownership
+    // above. Only a `declared` root changes the classification; `unknown` is
+    // deliberately not escalated (#1168's tri-state precedent — an
+    // unconfirmed chain never earns the more confident verdict).
+    const runtimeOwner =
+      !isDeclared && observedNow[name]?.ownerChain?.root === "declared"
+        ? observedNow[name]!.ownerChain!.entity
+        : undefined;
+
     let action: ChangeAction;
     let deltas: AttributeChange[] | undefined;
 
@@ -140,6 +156,13 @@ export function buildChangeSet(env: string, input: DiffLiveInput): ChangeSet {
       } else {
         action = "noop";
       }
+    } else if (live && runtimeOwner) {
+      // Live, undeclared, and its owner chain reaches a declared entity
+      // (#1077) — expected runtime, never a delete/adopt candidate, checked
+      // ahead of the ownership marker below: even a runtime child that
+      // happens to carry chant's own marker (label propagation from its
+      // owner's template) must never be proposed for deletion.
+      action = "runtime";
     } else if (live) {
       // Live but undeclared. Only a chant-owned orphan is a safe delete; a
       // foreign or unknown orphan can be adopted but never auto-deleted.
@@ -162,6 +185,7 @@ export function buildChangeSet(env: string, input: DiffLiveInput): ChangeSet {
             ...(unobservedEntry.detail ? { unobservedDetail: unobservedEntry.detail } : {}),
           }
         : {}),
+      ...(runtimeOwner ? { runtimeOwner } : {}),
     });
   }
 
@@ -169,7 +193,7 @@ export function buildChangeSet(env: string, input: DiffLiveInput): ChangeSet {
   return { env, entries };
 }
 
-const ACTION_ORDER: ChangeAction[] = ["create", "update", "delete", "adopt", "noop", "unobserved"];
+const ACTION_ORDER: ChangeAction[] = ["create", "update", "delete", "adopt", "runtime", "noop", "unobserved"];
 
 /** Count entries per action. */
 export function summarize(cs: ChangeSet): Record<ChangeAction, number> {
@@ -178,6 +202,7 @@ export function summarize(cs: ChangeSet): Record<ChangeAction, number> {
     update: 0,
     delete: 0,
     adopt: 0,
+    runtime: 0,
     noop: 0,
     unobserved: 0,
   };
@@ -191,10 +216,11 @@ export function summarize(cs: ChangeSet): Record<ChangeAction, number> {
  * GitLab renders an `artifacts:reports:terraform` artifact in the merge-request
  * UI as "N to add, M to change, K to delete". The format is generic — any tool
  * that emits this JSON gets the widget — and the chant plan maps onto it
- * directly. Only the mutating actions count: `adopt`, `noop` and `unobserved`
- * are excluded, since the widget has no column for "live but undeclared", "no
- * change", or "could not look" (#1089). The widget is therefore a floor, not a
- * complete plan: read the full change set when entities are unobserved.
+ * directly. Only the mutating actions count: `adopt`, `runtime`, `noop` and
+ * `unobserved` are excluded, since the widget has no column for "live but
+ * undeclared", "expected runtime child" (#1077), "no change", or "could not
+ * look" (#1089). The widget is therefore a floor, not a complete plan: read
+ * the full change set when entities are unobserved or classified runtime.
  *
  * The widget label reads "Terraform" regardless of producer; that is GitLab's
  * fixed string, not a claim chant makes.
@@ -223,14 +249,17 @@ export function renderChangeSet(cs: ChangeSet): string {
     lines.push(
       action === "unobserved"
         ? "\nUNOBSERVED (declared; chant could not read live state — no action proposed):"
-        : `\n${action.toUpperCase()}:`,
+        : action === "runtime"
+          ? "\nRUNTIME (owned by a declared resource; not drift, never a delete/adopt candidate):"
+          : `\n${action.toUpperCase()}:`,
     );
     for (const e of group) {
       const own = e.ownership === "unknown" ? "" : ` [${e.ownership}]`;
       const why = e.unobservedReason
         ? ` — ${unobservedReasonText(e.unobservedReason)}${e.unobservedDetail ? `: ${e.unobservedDetail}` : ""}`
         : "";
-      lines.push(`  ${e.name}${e.type ? ` (${e.type})` : ""}${own}${why}`);
+      const owner = e.runtimeOwner ? ` — owned by ${e.runtimeOwner}` : "";
+      lines.push(`  ${e.name}${e.type ? ` (${e.type})` : ""}${own}${why}${owner}`);
       for (const d of e.deltas ?? []) {
         lines.push(`      ${d.path}: ${fmt(d.oldValue)} → ${fmt(d.newValue)}`);
       }