@intentius/chant 0.31.0 → 0.33.0

package/src/graph-effective.ts

@@ -0,0 +1,110 @@
+import type { GraphIR, IRNode } from "./graph-ir";
+
+/**
+ * Fold DERIVED reachability facts onto EC2 instance nodes so a single-node query
+ * can answer questions that are otherwise a multi-hop join with a union (#1139).
+ *
+ * Two facts, both things a live AWS-CLI sweep gets wrong because it can't cheaply
+ * resolve the topology:
+ *
+ *  - `effectiveIngress` — the union of security-group ingress rules reachable
+ *    from the instance, BOTH directly (`SecurityGroupIds`) AND through its launch
+ *    template (`LaunchTemplate → LaunchTemplateData → SecurityGroupIds`). The
+ *    launch-template hop is exactly what a CLI agent misses (it under-counts
+ *    SSH-reachable instances). Each rule is normalized to `proto:port:cidr`
+ *    (e.g. `tcp:22:0.0.0.0/0`) so it is precisely queryable.
+ *  - `internetFacing` — whether the instance's subnet routes to an Internet
+ *    Gateway (`subnet ← SubnetRouteTableAssociation → RouteTable ← Route →
+ *    InternetGateway`). "Public subnet" means an IGW route, not
+ *    `MapPublicIpOnLaunch`.
+ *
+ * With these, "instances SSH-reachable from the internet" is one predicate:
+ *   `kind:EC2::Instance attr:internetFacing=true attr:effectiveIngress=tcp:22:0.0.0.0/0`
+ * — no hand-joined CLI sweep, no over/under-counting.
+ */
+export function enrichEffectiveTopology(ir: GraphIR): GraphIR {
+  const byId = new Map(ir.nodes.map((n) => [n.id, n]));
+  const edges = ir.edges ?? [];
+  const kind = (n?: IRNode): string => n?.kind ?? "";
+  const isKind = (n: IRNode | undefined, suffix: string): boolean =>
+    !!n && (kind(n) === suffix || kind(n).endsWith("::" + suffix));
+  const via = (...names: string[]) => (v: string): boolean => names.includes(v);
+
+  /** Out-neighbours of `id` (edges from → to), optionally filtered by viaAttr. */
+  const out = (id: string, pred?: (v: string) => boolean): IRNode[] =>
+    edges
+      .filter((e) => e.from === id && (!pred || pred(e.viaAttr ?? e.kind ?? "")))
+      .map((e) => byId.get(e.to))
+      .filter((x): x is IRNode => !!x);
+  /** In-neighbours of `id` (edges to ← from), optionally filtered by viaAttr. */
+  const incoming = (id: string, pred?: (v: string) => boolean): IRNode[] =>
+    edges
+      .filter((e) => e.to === id && (!pred || pred(e.viaAttr ?? e.kind ?? "")))
+      .map((e) => byId.get(e.from))
+      .filter((x): x is IRNode => !!x);
+
+  const normalizeIngress = (sg: IRNode): string[] => {
+    const rules = (sg.attrs as Record<string, unknown> | undefined)?.["SecurityGroupIngress"];
+    if (!Array.isArray(rules)) return [];
+    return rules.map((r) => {
+      const rule = r as Record<string, unknown>;
+      const proto = String(rule.IpProtocol ?? "-1");
+      const from = rule.FromPort as number | undefined;
+      const to = rule.ToPort as number | undefined;
+      const port = from == null ? "all" : from === to ? `${from}` : `${from}-${to}`;
+      const cidr =
+        (rule.CidrIp as string | undefined) ??
+        (rule.CidrIpv6 as string | undefined) ??
+        (rule.SourceSecurityGroupId ? `sg:${String(rule.SourceSecurityGroupId)}` : "?");
+      return `${proto}:${port}:${cidr}`;
+    });
+  };
+
+  /** Security groups reachable from an instance — direct and via launch template. */
+  const effectiveSgs = (inst: IRNode): IRNode[] => {
+    const direct = out(inst.id, via("SecurityGroupIds", "SecurityGroupId"));
+    const templates = out(inst.id, via("LaunchTemplate", "LaunchTemplateId"));
+    const viaTemplate = templates
+      .flatMap((lt) => out(lt.id, via("LaunchTemplateData", "SecurityGroupIds", "SecurityGroupId")))
+      .filter((n) => isKind(n, "SecurityGroup"));
+    const all = [...direct.filter((n) => isKind(n, "SecurityGroup")), ...viaTemplate];
+    return [...new Map(all.map((s) => [s.id, s])).values()];
+  };
+
+  /** The IGW an instance's subnet routes to (evidence), or undefined. */
+  const internetFacingVia = (inst: IRNode): string | undefined => {
+    for (const subnet of out(inst.id, via("SubnetId")).filter((n) => isKind(n, "Subnet"))) {
+      const assocs = incoming(subnet.id, via("SubnetId")).filter((a) => isKind(a, "SubnetRouteTableAssociation"));
+      const routeTables = assocs.flatMap((a) => out(a.id, via("RouteTableId")).filter((n) => isKind(n, "RouteTable")));
+      for (const rt of routeTables) {
+        const routes = incoming(rt.id, via("RouteTableId")).filter((n) => isKind(n, "Route"));
+        for (const route of routes) {
+          const dest = (route.attrs as Record<string, unknown> | undefined)?.["DestinationCidrBlock"];
+          const igw = out(route.id, via("GatewayId")).find((g) => isKind(g, "InternetGateway"));
+          if (igw && (dest == null || dest === "0.0.0.0/0")) {
+            const id = igw.id.includes("::") ? igw.id.slice(igw.id.lastIndexOf("::") + 2) : igw.id;
+            return `${rt.id.includes("::") ? rt.id.slice(rt.id.lastIndexOf("::") + 2) : rt.id} → ${id}`;
+          }
+        }
+      }
+    }
+    return undefined;
+  };
+
+  const nodes = ir.nodes.map((n) => {
+    if (!isKind(n, "Instance")) return n;
+    const effectiveIngress = effectiveSgs(n).flatMap(normalizeIngress);
+    // A live enrichment may already have set internetFacing (+ its evidence) for
+    // a subnet chant doesn't model declaratively (e.g. the account's default
+    // VPC). Keep that truth; otherwise derive it from the declared route topology.
+    const attrs = (n.attrs ?? {}) as Record<string, unknown>;
+    const liveFacing = attrs["internetFacing"] === true;
+    const declaredVia = internetFacingVia(n);
+    const via = (attrs["internetFacingVia"] as string | undefined) ?? declaredVia;
+    return {
+      ...n,
+      attrs: { ...attrs, effectiveIngress, internetFacing: liveFacing || !!declaredVia, ...(via ? { internetFacingVia: via } : {}) },
+    };
+  });
+  return { ...ir, nodes };
+}

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
@@ -577,6 +608,9 @@ export interface LexiconPlugin {
      * convention (AWS: the stack named after `environment`).
      */
     stack?: string;
+    /** AWS region the stack is in (multi-region). When set, the observation
+     * targets this region instead of the ambient one (#1161 follow-up). */
+    region?: string;
     /**
      * Restrict the result to chant-owned resources (those carrying the
      * ownership marker, #119). Where a lexicon has no durable marker channel,
@@ -664,7 +698,7 @@ export interface LexiconPlugin {
    * thin to carry references (e.g. AWS CloudFormation, where it's sourced from
    * the fuller `exportResources` config).
    */
-  enrichLiveAttrs?(options: { environment: string; stack?: string; owned?: boolean }): Promise<Record<string, Record<string, unknown>>>;
+  enrichLiveAttrs?(options: { environment: string; stack?: string; stacks?: Array<string | { name: string; region?: string }>; owned?: boolean }): Promise<Record<string, Record<string, unknown>>>;
 
   /**
    * List runtime artifacts in the given environment. Opt-in.
@@ -717,6 +751,8 @@ export interface LexiconPlugin {
      * keeps its single-stack convention (AWS: the stack named after
      * `environment`). */
     stack?: string;
+    /** AWS region the stack is in (multi-region estates). */
+    region?: string;
     selector?: ResourceSelector;
     owned?: boolean;
     verbatim?: boolean;
@@ -783,6 +819,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)}`);
       }