@intentius/chant 0.31.0 → 0.33.0

package/dist/lifecycle/change-set.d.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
@@ -24,12 +24,17 @@ import { type UnobservedReason } from "../observation.js";
  *   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
  * marker is queried (#120). The change set never escalates `unknown` to a
@@ -66,6 +71,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 {
     env: string;
@@ -91,10 +98,11 @@ export declare 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.

package/dist/lifecycle/change-set.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"change-set.d.ts","sourceRoot":"","sources":["../../src/lifecycle/change-set.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAY,KAAK,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EAAwB,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAE7E;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,YAAY,CAAC;AAE5F;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;AAExD,MAAM,WAAW,cAAc;IAC7B,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,YAAY,CAAC;IACrB,kEAAkE;IAClE,QAAQ,EAAE;QACR,oCAAoC;QACpC,QAAQ,EAAE,OAAO,CAAC;QAClB,oCAAoC;QACpC,UAAU,EAAE,OAAO,CAAC;QACpB,qDAAqD;QACrD,IAAI,EAAE,OAAO,CAAC;QACd;;;;;WAKG;QACH,QAAQ,EAAE,OAAO,CAAC;KACnB,CAAC;IACF,6CAA6C;IAC7C,MAAM,CAAC,EAAE,eAAe,EAAE,CAAC;IAC3B,oDAAoD;IACpD,SAAS,EAAE,SAAS,CAAC;IACrB,gFAAgF;IAChF,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,gGAAgG;IAChG,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,SAAS,CAgF3E;AAID,gCAAgC;AAChC,wBAAgB,SAAS,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAWrE;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,EAAE,EAAE,SAAS,GAAG,cAAc,CAG5D;AAED,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,CA0BrD"}
+{"version":3,"file":"change-set.d.ts","sourceRoot":"","sources":["../../src/lifecycle/change-set.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAY,KAAK,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EAAwB,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,YAAY,CAAC;AAExG;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;AAExD,MAAM,WAAW,cAAc;IAC7B,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,YAAY,CAAC;IACrB,kEAAkE;IAClE,QAAQ,EAAE;QACR,oCAAoC;QACpC,QAAQ,EAAE,OAAO,CAAC;QAClB,oCAAoC;QACpC,UAAU,EAAE,OAAO,CAAC;QACpB,qDAAqD;QACrD,IAAI,EAAE,OAAO,CAAC;QACd;;;;;WAKG;QACH,QAAQ,EAAE,OAAO,CAAC;KACnB,CAAC;IACF,6CAA6C;IAC7C,MAAM,CAAC,EAAE,eAAe,EAAE,CAAC;IAC3B,oDAAoD;IACpD,SAAS,EAAE,SAAS,CAAC;IACrB,gFAAgF;IAChF,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,gGAAgG;IAChG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oGAAoG;IACpG,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,SAAS,CAiG3E;AAID,gCAAgC;AAChC,wBAAgB,SAAS,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAYrE;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,EAAE,EAAE,SAAS,GAAG,cAAc,CAG5D;AAED,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,CA6BrD"}

package/dist/lifecycle/live-diff.d.ts

@@ -32,6 +32,18 @@ export interface UnobservedResource {
     reason: UnobservedReason;
     detail?: string;
 }
+/**
+ * A live, undeclared resource whose owner-reference chain reaches a declared
+ * entity (#1077) — a Pod a declared Deployment's controller created, for
+ * instance. Reported separately from `orphan`: it is expected runtime, not a
+ * delete/adopt candidate, and is never counted as drift.
+ */
+export interface RuntimeChildResource {
+    name: string;
+    type: string;
+    /** The declared chant entity this resource's owner chain resolves to. */
+    owner: string;
+}
 export interface LiveDiffResult {
     /**
      * Declared in current build, and the provider reported it absent. Entities
@@ -39,8 +51,20 @@ export interface LiveDiffResult {
      * (#1089), so "missing" keeps meaning "confirmed not there".
      */
     missing: string[];
-    /** Observed in cloud right now, but not declared. */
+    /**
+     * Observed in cloud right now, not declared, and either carries no owner
+     * chain, or the chain does not reach a declared entity (unowned, foreign,
+     * or unresolvable — #1077 never escalates an incomplete chain read to
+     * `runtimeChildren`). A resource whose chain *does* reach a declared entity
+     * is in `runtimeChildren` instead.
+     */
     orphan: string[];
+    /**
+     * Observed in cloud right now, not declared, whose owner-reference chain
+     * reaches a declared entity (#1077) — expected runtime, not drift. Never a
+     * delete/adopt candidate; excluded from `orphan` and from drift counts.
+     */
+    runtimeChildren: RuntimeChildResource[];
     /** Was in last snapshot but isn't observed now. */
     disappeared: string[];
     /** Observed now and declared, but not in the previous snapshot. */

package/dist/lifecycle/live-diff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"live-diff.d.ts","sourceRoot":"","sources":["../../src/lifecycle/live-diff.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"live-diff.d.ts","sourceRoot":"","sources":["../../src/lifecycle/live-diff.ts"],"names":[],"mappings":"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"}

package/dist/lifecycle/observe.d.ts

@@ -33,14 +33,22 @@ export interface ObserveResult {
  * absent an explicit `stack`) queries a stack that simply doesn't exist there,
  * so the single-call path always observes zero nodes. When `stacks` is
  * present and non-empty, each observing plugin's `describeResources` is
- * called once per stack (same `environment`/`entities`/`entityNames`, only
- * `stack` varies) and the returned resource maps are unioned — a resource
- * appears under whichever stack contains its logical id. When `stacks` is
- * absent or empty, behavior is exactly the single call of before (no `stack`
- * key at all), so a single-stack project is unaffected.
+ * called once per stack and the returned observations are merged. A stack entry
+ * may be a bare name or `{ name, region?, src? }` (#1162): `src` is built
+ * SCOPED so the deployed BARE LogicalResourceIds match (the whole-project build
+ * disambiguates colliding names to `UsWest1Src…`, which the live ids never
+ * carry), and a scoped stack's observed ids are qualified `${stack}::${id}` so
+ * the same bare id in two stacks stays distinct. A bare-string stack keeps its
+ * bare ids and the tri-state merge (#57). When `stacks` is absent or empty, behavior is
+ * exactly the single call of before (no `stack` key at all), so a single-stack
+ * project is unaffected.
  */
 export declare function observeResources(environment: string, plugins: ObservationLexicon[], buildResult: BuildResult, opts?: {
     owned?: boolean;
-    stacks?: string[];
+    stacks?: Array<string | {
+        name: string;
+        region?: string;
+        src?: string;
+    }>;
 }): Promise<ObserveResult>;
 //# sourceMappingURL=observe.d.ts.map

package/dist/lifecycle/observe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/lifecycle/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAUnD,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,kBAAkB,EAAE,EAC7B,WAAW,EAAE,WAAW,EACxB,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAC5C,OAAO,CAAC,aAAa,CAAC,CAmFxB"}
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/lifecycle/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAI5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAUnD,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,kBAAkB,EAAE,EAC7B,WAAW,EAAE,WAAW,EACxB,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,GACnG,OAAO,CAAC,aAAa,CAAC,CA6HxB"}

package/dist/managed-fields.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Kubernetes-object-shape utilities shared by every lexicon whose live model
+ * is a Kubernetes API object — the k8s lexicon itself (chant #1076) and GCP's
+ * Config Connector custom resources (chant #1087).
+ *
+ * A Config Connector custom resource *is* a Kubernetes object: it carries the
+ * same envelope (`status`, `metadata.{uid,resourceVersion,generation,
+ * creationTimestamp,managedFields,selfLink}`), the same SSA `fieldsV1`
+ * encoding for `metadata.managedFields`, and some CNRM kinds even embed
+ * genuinely k8s-shaped substructures (Cloud Run's `RunService` wraps a
+ * Knative pod spec with `containers`/`env`/`ports`, keyed the same way a
+ * Deployment's are). None of that is specific to chant's k8s *lexicon* — it
+ * is a fact about the Kubernetes API that any reader of a Kubernetes-shaped
+ * object needs, regardless of which lexicon is doing the reading.
+ *
+ * This module lives in core rather than in the k8s lexicon for the same
+ * reason `./kubectl-context.ts`'s `resolveClusterTarget` does (chant #1100):
+ * GCP's observation needs it too, without taking a dependency on the k8s
+ * lexicon package. Nothing here is keyed by chant's own k8s entityType
+ * catalog (`K8s::Apps::Deployment`, …) or by any lexicon's service-default
+ * table — that stays lexicon-specific, layered on top of what's here
+ * (`lexicons/k8s/src/deep-observe-hooks.ts`'s `K8S_SERVICE_DEFAULTS`,
+ * `lexicons/gcp/src/deep-observe.ts`'s CNRM-specific annotation noise).
+ */
+import type { DeepArrayElement, DeepNode } from "./deep-observation.js";
+/**
+ * Paths every Kubernetes API object carries regardless of kind, matched on
+ * the exact index-erased pattern (there is exactly one `status`, one
+ * `metadata.managedFields`, per object — no per-type variation the way AWS's
+ * `Arn`/`RoleId` repeat at every nesting depth).
+ *
+ * - `status` — the whole subtree is server-computed; no declarative source
+ *   (chant's k8s manifests, chant's Config Connector CRs) ever authors it.
+ * - `metadata.uid`/`resourceVersion`/`generation`/`creationTimestamp` — minted
+ *   and incremented by the API server, never authored.
+ * - `metadata.managedFields` — the bookkeeping the ownership walk below reads
+ *   to decide everything else. Left in the tree it would report as permanent
+ *   drift (a timestamp changes on every write) and would recurse into the
+ *   encoded `fieldsV1` structure as if it were ordinary properties.
+ * - `metadata.selfLink` — deprecated API-server bookkeeping some clusters
+ *   still echo; never a declared field.
+ */
+export declare const K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS: ReadonlySet<string>;
+/**
+ * Kubernetes' own well-known list-map-key conventions for the substructures
+ * that recur across kinds and across lexicons: containers/initContainers/
+ * ephemeralContainers and `env`/`volumes` keyed by `name` — the same field
+ * Kubernetes' strategic-merge-patch and SSA's `list-map-keys` key on for
+ * these lists — and container ports keyed by `containerPort`+`protocol`,
+ * Service ports keyed by `port`+`protocol` (Kubernetes' own SSA
+ * `list-map-keys` for each). Both port shapes are handled under one `ports`
+ * branch by checking which field is present.
+ *
+ * Entity-type-agnostic on purpose: whether an array named `containers`
+ * belongs to a `K8s::Apps::Deployment` or to a GCP `RunService`'s embedded
+ * pod spec, the identity Kubernetes assigns each element is the same.
+ */
+export declare function k8sListMapOrderKey(element: DeepArrayElement): string | undefined;
+/**
+ * The structural shape of one `metadata.managedFields` entry this module
+ * needs. Matches `@intentius/chant-k8s-client`'s `ManagedFieldsEntry`
+ * (chant #1075) field-for-field, but is declared independently here rather
+ * than imported from that package: core must stay reachable from any
+ * lexicon's build path, and the k8s client package is deliberately *not*
+ * reachable from one (chant #1074's structural boundary,
+ * `examples/k8s-client-boundary.test.ts`). A caller that already has a real
+ * `ManagedFieldsEntry[]` (the k8s lexicon) passes it straight through —
+ * TypeScript's structural typing accepts it with no cast.
+ */
+export interface ManagedFieldsEntryLike {
+    manager?: string;
+    operation?: string;
+    subresource?: string;
+    fieldsV1?: Record<string, unknown>;
+}
+/** One live object's managed-fields ownership, resolved to chant dot-paths. */
+export interface OwnershipSets {
+    /** Paths any chant field manager owns on this object. */
+    chantOwned: ReadonlySet<string>;
+    /** Paths owned by a manager that is not chant. */
+    foreignOwned: ReadonlySet<string>;
+    /** The subset of `foreignOwned` where the declared manifest also sets the path — drift-relevant despite foreign ownership. */
+    foreignContested: ReadonlySet<string>;
+}
+/**
+ * Build the three ownership sets for one live object. `entries` is
+ * `metadata.managedFields`, already decoded (`@intentius/chant-k8s-client`'s
+ * `managedFieldsOf` for the k8s lexicon; a plain `JSON.parse` of `kubectl get
+ * -o json` for gcp); `isChantManager` classifies each entry's manager name
+ * — matched on the `chant`/`chant:<stack>` family per chant #1075, but the
+ * matcher itself is supplied by the caller rather than fixed here, because
+ * what counts as "chant" is not the same fact on every lexicon's apply path
+ * (see gcp's `deep-observe.ts` module doc for why that matters there).
+ *
+ * Subresource entries (`status`, `scale`) are excluded: a controller writing
+ * a Deployment's `status` is not competing for the spec chant declared, the
+ * same reasoning `@intentius/chant-k8s-client`'s `fieldsOwnedBy` default
+ * already encodes.
+ */
+export declare function buildOwnershipSets(entries: readonly ManagedFieldsEntryLike[], liveRoot: Record<string, unknown>, declaredRoot: Record<string, unknown>, isChantManager: (manager: string | undefined) => boolean): OwnershipSets;
+/**
+ * The three-question managed-fields prune rule, as a predicate over a
+ * {@link DeepNode} plus one object's precomputed {@link OwnershipSets} —
+ * shared by every lexicon layering a per-resource managed-fields prune on
+ * top of its own static rules (k8s's `perResourceHooks`, gcp's equivalent):
+ *
+ * 1. Chant owns the path (any chant manager) → never pruned by this rule.
+ * 2. A different manager owns it, chant does not, and it is not declared →
+ *    controller-managed noise, pruned.
+ * 3. It is declared, regardless of who owns it live → never pruned by this
+ *    rule, because chant's source is a statement of intent independent of
+ *    which write currently holds the field.
+ *
+ * Only applies to the live side — the declared tree carries no managedFields
+ * to prune by.
+ */
+export declare function pruneByOwnership(node: DeepNode, sets: OwnershipSets): boolean;
+//# sourceMappingURL=managed-fields.d.ts.map

package/dist/managed-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"managed-fields.d.ts","sourceRoot":"","sources":["../src/managed-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAIrE;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,kCAAkC,EAAE,WAAW,CAAC,MAAM,CAQjE,CAAC;AAwBH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAwBhF;AAID;;;;;;;;;;GAUG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,+EAA+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAChC,kDAAkD;IAClD,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAClC,8HAA8H;IAC9H,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACvC;AAsHD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,SAAS,sBAAsB,EAAE,EAC1C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,GACvD,aAAa,CAmBf;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAM7E"}

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