@intentius/chant 0.57.0 → 0.59.0

package/src/lifecycle/deep-diff.ts

@@ -20,6 +20,17 @@
  * {@link UNRESOLVED} — an unevaluated intrinsic (`Fn::Sub`, `Ref`) has no
  * source-side value to compare, and reporting one as drift would light up every
  * interpolated property forever.
+ *
+ * ## The claim decides what counts as drift (#2160)
+ *
+ * The declared tree is not only one side of a comparison, it is a statement of
+ * which fields chant ever set — the claimed-field set (../claimed-fields.ts).
+ * A live value on a path outside it is somebody else's field: an autoscaler's
+ * replica count, a controller's annotation, a value a person typed into a
+ * console. It is reported in {@link DeepDiffResult.unclaimed}, with the
+ * manager's name where the substrate records one, and it is not drift. Only a
+ * claimed path that moved is, and drift is the only thing that may become an
+ * update.
  */
 
 import {
@@ -29,6 +40,8 @@ import {
   type DeepNormalizationHooks,
   type NormalizedDeepObservation,
 } from "../deep-observation";
+import { claimedFieldsFromPaths, heldBy, isClaimed, type FieldClaimSource } from "../claimed-fields";
+import { isNormalizedHeldElsewhere } from "../held-elsewhere";
 import { originOfPath, type PathOrigin } from "../provenance";
 import type { UnobservedResource } from "./live-diff";
 import { acceptedDeviation, type BaselineLexicon } from "./observation-baseline";
@@ -37,20 +50,30 @@ import { acceptedDeviation, type BaselineLexicon } from "./observation-baseline"
  * How a property differs.
  *
  * - `changed` — declared and live both have the path, with different values.
- * - `undeclared` — live has it, source never did. cdk-real-drift's whole reason
- *   to exist: the console-added property CloudFormation itself will not report.
+ *   The only kind that may become an update.
  * - `absent` — source declares it and the live tree does not carry it. Weaker
- *   than the other two: a provider that omits a property it considers unset is
+ *   than `changed`: a provider that omits a property it considers unset is
  *   common, which is what the lexicon's pruning hook is for.
+ *
+ * A live value on a path source never declared used to be a third kind,
+ * `undeclared`. It is no longer drift at all (#2160): chant never set that
+ * field, so somebody else holds it, and it is reported in
+ * {@link DeepDiffResult.unclaimed} instead. It is still reported — pruning
+ * what chant cannot attribute is how #1191 lost a console-added label — it just
+ * stopped being a difference chant proposes to close.
  */
-export type PropertyDriftKind = "changed" | "undeclared" | "absent";
+export type PropertyDriftKind = "changed" | "absent";
 
 /** One property-level difference. */
 export interface PropertyDrift {
   /** Path within the normalized property tree (`Tags[0].Value`). */
   path: string;
   kind: PropertyDriftKind;
-  /** Value in source. Absent for `undeclared`. */
+  /**
+   * Value in source. Always present since #2160 — a drift row is only ever
+   * raised for a path the declaration claims — and kept optional for the wire
+   * shape consumers already branch on.
+   */
   declared?: unknown;
   /** Value in the cloud. Absent for `absent`. */
   live?: unknown;
@@ -64,7 +87,8 @@ export interface PropertyDrift {
    * The field manager that owns this path live, where the substrate records one
    * (#1189) — Kubernetes' `managedFields`, and nowhere else today.
    *
-   * `kind` says a path is `undeclared` or `changed`; this says who did it.
+   * `kind` says whether a claimed path changed or went missing; this says who
+   * holds it live.
    * "Owned by `kubectl-client-side-apply`" and "owned by `hpa-controller`" are
    * the same `kind` and mean opposite things: one is somebody bypassing the
    * pipeline, the other is a controller doing its job. Absent on a substrate
@@ -92,6 +116,76 @@ export interface DeepEntityDrift {
   changes: PropertyDrift[];
 }
 
+/**
+ * One live property value on a path this declaration never claimed (#2160) —
+ * a field that exists and that chant did not set.
+ *
+ * Reported, never proposed. The interesting column is {@link source}: on
+ * Kubernetes the API server names the manager and this row says
+ * `hpa-controller`; everywhere else the declaration is the only witness and the
+ * row says "not mine" without saying whose.
+ */
+export interface PropertyUnclaimed {
+  /** Path within the normalized property tree (`spec.replicas`). */
+  path: string;
+  /** The value the cloud is carrying. */
+  live: unknown;
+  /**
+   * The field manager holding it, where the substrate records one. Absent on
+   * every substrate but Kubernetes, and absent on Kubernetes for a path no
+   * `managedFields` entry covers.
+   */
+  heldBy?: string;
+  /** Which source answered: the substrate's manager, or the claimed-field set. */
+  source: FieldClaimSource;
+  /**
+   * The accepted value from the baseline, when this path has one. An unclaimed
+   * field needs no acceptance to stay quiet, so this is carried for continuity with
+   * baselines recorded before #2160 rather than because it changes anything.
+   */
+  baseline?: unknown;
+}
+
+/** Live property values one declared entity is not claiming. */
+export interface DeepEntityUnclaimed {
+  name: string;
+  type: string;
+  fields: PropertyUnclaimed[];
+}
+
+/**
+ * One property declared `heldElsewhere()` (#2162) — a fact about who owns the
+ * field at runtime, reported beside drift rather than folded into it. Never a
+ * {@link PropertyDrift}: a held property is never `changed`, `undeclared`, or
+ * `absent`, and is never proposed for update.
+ */
+export interface PropertyHeld {
+  /** Path within the normalized property tree, same addressing as {@link PropertyDrift.path}. */
+  path: string;
+  /** Who holds it — the marker's `by`. */
+  by: string;
+  /** Why chant does not reconcile it — the marker's `reason`. */
+  reason: string;
+  /** The live value, when the deep read found one at this path. */
+  live?: unknown;
+  /**
+   * True when this path carried no live value at all — the deep read found
+   * nothing here, not even a provider default. A declared hand-over with no
+   * evidence anything was ever written is itself worth a look: either the
+   * holder never ran, or this is not the field it actually writes.
+   */
+  suspicious: boolean;
+  /** The field manager that owns this path live, where the substrate records one (#1189). See {@link PropertyDrift.owner}. */
+  owner?: string;
+}
+
+/** Held properties (#2162) for one declared entity. */
+export interface DeepEntityHeld {
+  name: string;
+  type: string;
+  held: PropertyHeld[];
+}
+
 export interface DeepDiffResult {
   /** Entities with at least one reportable property difference. Sorted by name. */
   drifted: DeepEntityDrift[];
@@ -101,6 +195,28 @@ export interface DeepDiffResult {
    * being held back and the count never silently changes meaning.
    */
   accepted: DeepEntityDrift[];
+  /**
+   * Live values on paths nobody declared (#2160), per entity. Sorted by name.
+   *
+   * Not drift, and deliberately a sibling of `drifted` rather than a kind
+   * inside it: `countPropertyDrift` does not see this list, `--update-baseline`
+   * does not record it, and nothing downstream may turn one of these into an
+   * update. It exists so the report can still say the field is there and who
+   * has it.
+   *
+   * Not `held`, which is the opposite fact: `held` is a field source declared
+   * and then handed over with `heldElsewhere()`, and this is a field source
+   * never declared at all.
+   */
+  unclaimed: DeepEntityUnclaimed[];
+  /**
+   * Properties declared `heldElsewhere()` (#2162) — reported here instead of
+   * in `drifted`/`accepted`, whatever the live value is. Not a suppression:
+   * every held property is listed, with its holder and reason, so a reader of
+   * the plan sees which fields are not being managed and by whom. Sorted by
+   * name.
+   */
+  held: DeepEntityHeld[];
   /** Entities whose property trees matched. Sorted. */
   unchanged: string[];
   /** Declared entities whose *properties* could not be read (#1089). Sorted. */
@@ -144,6 +260,8 @@ export function diffDeep(input: DiffDeepInput): DeepDiffResult {
   const baseline = input.baseline ?? {};
   const drifted: DeepEntityDrift[] = [];
   const accepted: DeepEntityDrift[] = [];
+  const unclaimed: DeepEntityUnclaimed[] = [];
+  const held: DeepEntityHeld[] = [];
   const unchanged: string[] = [];
   const unobserved: UnobservedResource[] = [];
   const undeclaredEntities: string[] = [];
@@ -187,39 +305,85 @@ export function diffDeep(input: DiffDeepInput): DeepDiffResult {
       hooks: input.hooks,
     });
 
+    // The claim (#2160): every path this declaration's props flatten to, in the
+    // grammar this loop addresses paths by. Derived here rather than read off
+    // `liveEntity.claimedFields` so `diffDeep` stays a pure function of its two
+    // trees; `lifecycle/deep-observe.ts` computes the identical set from the
+    // identical normalized tree and carries it on the observation for consumers.
+    const claimed = claimedFieldsFromPaths(declaredFlat.keys());
+
     const paths = [...new Set([...declaredFlat.keys(), ...liveFlat.keys()])].sort();
     const reported: PropertyDrift[] = [];
     const suppressed: PropertyDrift[] = [];
+    const unclaimedFields: PropertyUnclaimed[] = [];
+    const heldHere: PropertyHeld[] = [];
 
     for (const path of paths) {
-      const hasDeclared = declaredFlat.has(path);
+      const hasDeclared = isClaimed(claimed, path);
       const hasLive = liveFlat.has(path);
       const declaredValue = declaredFlat.get(path);
       const liveValue = liveFlat.get(path);
 
+      // A `heldElsewhere()` marker (#2162): never drift, whatever the live
+      // value is (or isn't) — reported in its own section instead, with its
+      // holder and reason, and never proposed for update. Checked ahead of
+      // the UNRESOLVED/equality shortcuts below: a held path is not "no
+      // source-side value" (UNRESOLVED) and its declared side will never
+      // structurally equal a live value, so without this check every held
+      // property would fall through and report as ordinary `changed` drift.
+      if (hasDeclared && isNormalizedHeldElsewhere(declaredValue)) {
+        heldHere.push({
+          path,
+          by: declaredValue.by,
+          reason: declaredValue.reason,
+          ...(hasLive ? { live: liveValue } : {}),
+          // No live value at all is the one thing chant can check in a
+          // single observation: a claimed hand-over that produced no
+          // evidence — not even a provider default — is worth a look.
+          suspicious: !hasLive,
+          ...(hasLive && liveEntity.fieldOwners?.[path] ? { owner: liveEntity.fieldOwners[path] } : {}),
+        });
+        continue;
+      }
+
       // An unevaluated intrinsic has no source-side value to compare against.
       if (hasDeclared && declaredValue === UNRESOLVED) continue;
       if (hasDeclared && hasLive && deepValueEqual(declaredValue, liveValue)) continue;
 
-      const kind: PropertyDriftKind = !hasDeclared ? "undeclared" : !hasLive ? "absent" : "changed";
+      const acceptedEntry = acceptedDeviation(baseline, name, path);
+
+      // A live value on a path nobody claimed is somebody else's field, not a
+      // difference chant proposes to close (#2160). Reported, never drift,
+      // never a candidate for an update — and the manager name, where the
+      // substrate records one, is the whole answer an operator wants.
+      if (!hasDeclared) {
+        const { holder, source } = heldBy(liveEntity.fieldOwners, path);
+        unclaimedFields.push({
+          path,
+          live: liveValue,
+          ...(holder ? { heldBy: holder } : {}),
+          source,
+          ...(acceptedEntry ? { baseline: acceptedEntry.value } : {}),
+        });
+        continue;
+      }
+
+      const kind: PropertyDriftKind = !hasLive ? "absent" : "changed";
       // Who owns the path live, where the substrate records it (#1189). Only
       // meaningful for a path that exists live — an `absent` drift has no live
       // field for anyone to own.
       const owner = hasLive ? liveEntity.fieldOwners?.[path] : undefined;
-      // The declared-side counterpart (#1443). Only meaningful for a path
-      // source actually declares — an `undeclared` drift has no authored
-      // expression for anything to have produced.
-      const origin = hasDeclared ? originOfPath(declaredEntity.pathOrigins, path) : undefined;
+      // The declared-side counterpart (#1443).
+      const origin = originOfPath(declaredEntity.pathOrigins, path);
       const drift: PropertyDrift = {
         path,
         kind,
-        ...(hasDeclared ? { declared: declaredValue } : {}),
+        declared: declaredValue,
         ...(hasLive ? { live: liveValue } : {}),
         ...(owner ? { owner } : {}),
         ...(origin ? { origin } : {}),
       };
 
-      const acceptedEntry = acceptedDeviation(baseline, name, path);
       if (acceptedEntry) {
         drift.baseline = acceptedEntry.value;
         // Value-bound acceptance: the accepted value is not drift, a different
@@ -233,13 +397,20 @@ export function diffDeep(input: DiffDeepInput): DeepDiffResult {
     }
 
     if (suppressed.length > 0) accepted.push({ name, type, changes: suppressed });
+    if (unclaimedFields.length > 0) unclaimed.push({ name, type, fields: unclaimedFields });
     if (reported.length > 0) drifted.push({ name, type, changes: reported });
+    // Held fields do not disqualify an entity from `unchanged`: every property
+    // chant declared matches, and the epic's whole point is that a controller's
+    // field stops being a finding chant restates on every tick.
     else if (suppressed.length === 0) unchanged.push(name);
+    if (heldHere.length > 0) held.push({ name, type, held: heldHere });
   }
 
   return {
     drifted: drifted.sort((a, b) => a.name.localeCompare(b.name)),
     accepted: accepted.sort((a, b) => a.name.localeCompare(b.name)),
+    unclaimed: unclaimed.sort((a, b) => a.name.localeCompare(b.name)),
+    held: held.sort((a, b) => a.name.localeCompare(b.name)),
     unchanged: unchanged.sort(),
     unobserved: unobserved.sort((a, b) => a.name.localeCompare(b.name)),
     undeclaredEntities: undeclaredEntities.sort(),
@@ -250,3 +421,35 @@ export function diffDeep(input: DiffDeepInput): DeepDiffResult {
 export function countPropertyDrift(result: DeepDiffResult): number {
   return result.drifted.reduce((n, e) => n + e.changes.length, 0);
 }
+
+/** Total live values on paths no declaration claimed, across every entity (#2160). Never added to the drift count. */
+export function countUnclaimed(result: DeepDiffResult): number {
+  return result.unclaimed.reduce((n, e) => n + e.fields.length, 0);
+}
+
+/** Total held properties (#2162) across every entity. */
+export function countHeld(result: DeepDiffResult): number {
+  return result.held.reduce((n, e) => n + e.held.length, 0);
+}
+
+/** One held property flagged suspicious (#2162), with its entity attached. */
+export interface SuspiciousHeld extends PropertyHeld {
+  name: string;
+  type: string;
+}
+
+/**
+ * Every held property whose declaration looks like a hand-over that never
+ * happened — no live value ever showed up for it. Worth a look: either the
+ * named holder never ran, or this is not the field it actually writes.
+ * Sorted by entity name, then path.
+ */
+export function suspiciousHeld(result: DeepDiffResult): SuspiciousHeld[] {
+  const out: SuspiciousHeld[] = [];
+  for (const entity of result.held) {
+    for (const h of entity.held) {
+      if (h.suspicious) out.push({ name: entity.name, type: entity.type, ...h });
+    }
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name) || a.path.localeCompare(b.path));
+}

package/src/lifecycle/deep-observe.test.ts

@@ -156,10 +156,12 @@ describe("deepDiffForLexicon", () => {
       observeResourcesDeep: async () =>
         deepObservation({ a: { type: "T", properties: { Extra: "accepted-value" } } }),
     });
+    // A path source declares: since #2160 the baseline only ever suppresses
+    // drift, and a path nobody declared never reaches it (it is unclaimed).
     const opts = {
       environment: "prod",
       buildOutput: "",
-      entities: entities({ a: { entityType: "T", props: {} } }),
+      entities: entities({ a: { entityType: "T", props: { Extra: "ours" } } }),
     };
     const withoutBaseline = await deepDiffForLexicon(plugin, opts);
     expect(withoutBaseline.drifted[0].changes[0].path).toBe("Extra");

package/src/lifecycle/deep-observe.ts

@@ -26,6 +26,7 @@ import {
   type DeepResourceObservation,
   type NormalizedDeepObservation,
 } from "../deep-observation";
+import { claimedFieldPaths, claimedFieldsOfTree } from "../claimed-fields";
 import { unobservedAll, type UnobservedEntity } from "../observation";
 import type { PathOrigin } from "../provenance";
 import { diffDeep, type DeclaredDeepEntity, type DeepDiffResult } from "./deep-diff";
@@ -140,14 +141,15 @@ export function diffDeepObservation(
     const declaredPaths = deepPathSet(declaredRaw);
     const livePaths = deepPathSet(liveRaw);
 
+    const declaredProperties = normalizeDeepProperties(declaredRaw, {
+      entityType: entity.entityType,
+      side: "declared",
+      hooks,
+      counterpartPaths: livePaths,
+    });
     declared[name] = {
       type: entity.entityType,
-      properties: normalizeDeepProperties(declaredRaw, {
-        entityType: entity.entityType,
-        side: "declared",
-        hooks,
-        counterpartPaths: livePaths,
-      }),
+      properties: declaredProperties,
       ...(entity.pathOrigins ? { pathOrigins: entity.pathOrigins } : {}),
     };
     if (liveEntity) {
@@ -158,6 +160,14 @@ export function diffDeepObservation(
         // up by the flattened path, so a keyed list element (`[#name]`) has
         // no owner today — its raw index path is what the reader recorded.
         ...(liveEntity.fieldOwners ? { fieldOwners: liveEntity.fieldOwners } : {}),
+        // The claimed-field set (#2160), computed from the declaration and
+        // carried on the observation so a consumer holding only this envelope
+        // can classify a live value three ways rather than two. Same normalized
+        // tree and same hooks `diffDeep` flattens, so the two never disagree
+        // about a path.
+        claimedFields: claimedFieldPaths(
+          claimedFieldsOfTree(declaredProperties, { entityType: entity.entityType, ...(hooks ? { hooks } : {}) }),
+        ),
         properties: normalizeDeepProperties(liveRaw, {
           entityType: liveEntity.type || entity.entityType,
           side: "live",

package/src/lifecycle/gate-ledger.test.ts

@@ -3,8 +3,12 @@ import { withTestDir } from "@intentius/chant-test-utils";
 import { spawnSync } from "node:child_process";
 import { writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { appendGateResolution, readGateResolutions, latestResolutionSince, resolveApprovalUrl, isApprovalUrl } from "./gate-ledger";
-import { readBlobFromPath } from "./git";
+import {
+  appendGateResolution, appendPendingGate, readGateResolutions, readGateLedger,
+  latestResolutionSince, latestPendingGate, isPendingGateExpired,
+  resolveApprovalUrl, isApprovalUrl, type PendingGateRecord,
+} from "./gate-ledger";
+import { readBlobFromPath, writeBlobToPath } from "./git";
 
 function git(args: string[], cwd: string): { stdout: string; exitCode: number } {
   const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
@@ -181,3 +185,71 @@ describe("lifecycle/gate-ledger", () => {
     });
   });
 });
+
+describe("lifecycle/gate-ledger — pending facts (#2119)", () => {
+  test("pending facts and resolutions share the file and read back separately", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const { record: pending } = await appendPendingGate(
+        {
+          op: "fountain-apply", gate: "rollout-gate",
+          description: "release manager signs off",
+          runId: "local-1",
+          timestamp: "2026-01-01T00:00:00.000Z",
+          expiresAt: "2026-01-03T00:00:00.000Z",
+        },
+        { cwd: dir },
+      );
+      await appendGateResolution(
+        { op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-02T00:00:00.000Z" },
+        { cwd: dir },
+      );
+
+      const { resolutions, pending: pendings, malformed } = await readGateLedger("fountain-apply", { cwd: dir });
+      expect(malformed).toBe(0);
+      expect(pendings).toEqual([pending]);
+      expect(resolutions.map((r) => r.resolvedBy)).toEqual(["alex"]);
+
+      // A pending line is not a malformed resolution to the narrow reader.
+      const narrow = await readGateResolutions("fountain-apply", { cwd: dir });
+      expect(narrow.malformed).toBe(0);
+      expect(narrow.records).toHaveLength(1);
+    });
+  });
+
+  test("latestPendingGate picks the newest fact for the gate, expired or not", () => {
+    const at = (timestamp: string, gate = "g"): PendingGateRecord => ({
+      version: 1, kind: "pending", op: "o", gate, timestamp,
+      expiresAt: "2026-01-09T00:00:00.000Z",
+    });
+    const records = [at("2026-01-01T00:00:00.000Z"), at("2026-01-05T00:00:00.000Z"), at("2026-01-07T00:00:00.000Z", "other")];
+    expect(latestPendingGate(records, "g")?.timestamp).toBe("2026-01-05T00:00:00.000Z");
+    expect(latestPendingGate(records, "absent")).toBeUndefined();
+  });
+
+  test("isPendingGateExpired is true at and after expiresAt", () => {
+    const record: PendingGateRecord = {
+      version: 1, kind: "pending", op: "o", gate: "g",
+      timestamp: "2026-01-01T00:00:00.000Z", expiresAt: "2026-01-03T00:00:00.000Z",
+    };
+    expect(isPendingGateExpired(record, "2026-01-02T23:59:59.000Z")).toBe(false);
+    expect(isPendingGateExpired(record, "2026-01-03T00:00:00.000Z")).toBe(true);
+    expect(isPendingGateExpired(record, "2026-01-04T00:00:00.000Z")).toBe(true);
+  });
+
+  test("a pending line missing expiresAt is malformed, not read as a resolution", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await writeBlobToPath(
+        "_gates", "fountain-apply.jsonl",
+        JSON.stringify({ version: 1, kind: "pending", op: "fountain-apply", gate: "g", timestamp: "2026-01-01T00:00:00.000Z" }),
+        "hand-written",
+        { cwd: dir },
+      );
+      const { resolutions, pending, malformed } = await readGateLedger("fountain-apply", { cwd: dir });
+      expect(malformed).toBe(1);
+      expect(pending).toEqual([]);
+      expect(resolutions).toEqual([]);
+    });
+  });
+});