@intentius/chant 0.56.0 → 0.58.0

package/src/cli/handlers/build.test.ts

@@ -6,7 +6,7 @@
  * `buildParams`, so a `*.component.ts` file reading `params.<name>` always
  * saw `{}` under `chant build --components --generate`, exactly like `chant
  * run --components` (see ../handlers/run.test.ts's "build-time parameters"
- * describe block for the equivalent local/`--temporal` coverage).
+ * describe block for the equivalent local-run coverage).
  *
  * Mocks `generateComponentsPipeline` and `loadChantConfigUpward` (chant
  * #1117 — `runGenerateComponents` walks up to the project root now, same as
@@ -149,3 +149,83 @@ describe("runBuild --components --generate (chant #1108 build-time parameters)",
     expect(generateComponentsPipelineMock).not.toHaveBeenCalled();
   });
 });
+
+/**
+ * chant #2060. `chant build --components --generate --format json` forwarded
+ * only `{ stages, jobs, yaml }`, dropping `result.env` even though the
+ * generator (#2046, PR #2050) resolves and returns it. A consumer reading the
+ * structured output (behold does) had no environment identity except by
+ * parsing the YAML back, which #2046 was meant to retire.
+ */
+describe("runBuild --components --generate --format json (chant #2060 env passthrough)", () => {
+  beforeEach(() => {
+    generateComponentsPipelineMock.mockReset();
+    loadChantConfigUpwardMock.mockReset().mockResolvedValue({ config: {} });
+  });
+
+  test("--format json includes result.env alongside stages, jobs and yaml", async () => {
+    generateComponentsPipelineMock.mockResolvedValue({
+      success: true,
+      yaml: "name: chant-components-prod\nenv:\n  CHANT_ENV: prod\n",
+      stages: ["deploy"],
+      jobs: [{ jobName: "deploy-web", component: "web", stage: "deploy", needs: [] }],
+      env: "prod",
+    });
+    const stdout: string[] = [];
+    vi.spyOn(console, "log").mockImplementation((s: string) => { stdout.push(s); });
+
+    const exit = await runBuild({
+      args: makeArgs({ format: "json", env: "prod" }),
+      plugins: [],
+      serializers: [],
+    });
+
+    expect(exit).toBe(0);
+    expect(stdout).toHaveLength(1);
+    const printed = JSON.parse(stdout[0]);
+    expect(printed).toEqual({
+      stages: ["deploy"],
+      jobs: [{ jobName: "deploy-web", component: "web", stage: "deploy", needs: [] }],
+      yaml: "name: chant-components-prod\nenv:\n  CHANT_ENV: prod\n",
+      env: "prod",
+    });
+    vi.restoreAllMocks();
+  });
+
+  test("--format json omits env when the generator's result carries none", async () => {
+    generateComponentsPipelineMock.mockResolvedValue({
+      success: true,
+      yaml: "stages: []",
+      stages: [],
+      jobs: [],
+    });
+    const stdout: string[] = [];
+    vi.spyOn(console, "log").mockImplementation((s: string) => { stdout.push(s); });
+
+    const exit = await runBuild({ args: makeArgs({ format: "json" }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(0);
+    const printed = JSON.parse(stdout[0]);
+    expect(printed).toEqual({ stages: [], jobs: [], yaml: "stages: []" });
+    expect(printed).not.toHaveProperty("env");
+    vi.restoreAllMocks();
+  });
+
+  test("the default text format is unchanged: env is not forwarded and only the raw yaml is printed", async () => {
+    generateComponentsPipelineMock.mockResolvedValue({
+      success: true,
+      yaml: "name: chant-components-prod\nenv:\n  CHANT_ENV: prod\n",
+      stages: ["deploy"],
+      jobs: [{ jobName: "deploy-web", component: "web", stage: "deploy", needs: [] }],
+      env: "prod",
+    });
+    const stdout: string[] = [];
+    vi.spyOn(console, "log").mockImplementation((s: string) => { stdout.push(s); });
+
+    const exit = await runBuild({ args: makeArgs({ env: "prod" }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(0);
+    expect(stdout).toEqual(["name: chant-components-prod\nenv:\n  CHANT_ENV: prod\n"]);
+    vi.restoreAllMocks();
+  });
+});

package/src/cli/handlers/build.ts

@@ -63,7 +63,21 @@ async function runGenerateComponents(ctx: CommandContext): Promise<number> {
 
   const yaml = result.yaml ?? "";
   if (args.format === "json") {
-    console.log(JSON.stringify({ stages: result.stages, jobs: result.jobs, yaml }, null, 2));
+    console.log(
+      JSON.stringify(
+        {
+          stages: result.stages,
+          jobs: result.jobs,
+          yaml,
+          // The environment the generated pipeline deploys (#2046), the
+          // generator's own resolution, forwarded rather than left for a
+          // consumer to re-derive by parsing the YAML back (#2060).
+          ...(result.env ? { env: result.env } : {}),
+        },
+        null,
+        2,
+      ),
+    );
   } else if (args.output) {
     const outputPath = resolve(args.output);
     mkdirSync(dirname(outputPath), { recursive: true });

package/src/cli/handlers/graph.test.ts

@@ -233,14 +233,14 @@ describe("runGraph", () => {
         filePath: file,
       });
 
-      test("an op discoverOps finds at the project root becomes a Temporal::Op node", async () => {
+      test("an op discoverOps finds at the project root becomes a Chant::Op node", async () => {
         lintClean(); discovered();
         discoverOpsMock.mockResolvedValue({ ops: new Map([["deploy", rootOp("/proj/deploy.op.ts")]]), errors: [] });
         const exit = await runGraph({ args: makeArgs({ format: "ir", path: "/proj", detail: 3 }), plugins: [], serializers: [] });
         expect(exit).toBe(0);
         const ir = JSON.parse(stdoutBuf.join("\n"));
         const node = ir.nodes.find((n: { id: string }) => n.id === "deploy");
-        expect(node).toMatchObject({ kind: "Temporal::Op", lexicon: "temporal", sourceLoc: { file: "deploy.op.ts" } });
+        expect(node).toMatchObject({ kind: "Chant::Op", lexicon: "chant", sourceLoc: { file: "deploy.op.ts" } });
         expect(node.attrs.phases[0].name).toBe("Apply");
         expect(node.attrs.depends).toEqual(["infra"]);
       });
@@ -248,7 +248,7 @@ describe("runGraph", () => {
       test("an op discovery already loaded from sourceDir is not added twice", async () => {
         lintClean();
         const entities = sampleEntities();
-        entities.set("deploy", decl({ lexicon: "temporal", entityType: "Temporal::Op", props: { name: "deploy", phases: [] } }));
+        entities.set("deploy", decl({ lexicon: "chant", entityType: "Chant::Op", props: { name: "deploy", phases: [] } }));
         discoverMock.mockResolvedValue({ entities, errors: [], dependencies: new Map(), sourceFiles: ["/proj/src/deploy.op.ts"] });
         discoverOpsMock.mockResolvedValue({ ops: new Map([["deploy", rootOp("/proj/src/deploy.op.ts")]]), errors: [] });
         const exit = await runGraph({ args: makeArgs({ format: "ir", path: "/proj", detail: 3 }), plugins: [], serializers: [] });

package/src/cli/handlers/lifecycle.test.ts

@@ -3,6 +3,7 @@ import { sep } from "node:path";
 import { createMockPlugin, staticDescribeResources, staticObservation, staticDeepObservation, staticListArtifacts } from "@intentius/chant-test-utils";
 import type { LexiconPlugin, ResourceMetadata } from "../../lexicon";
 import { deepObservation } from "../../deep-observation";
+import { heldElsewhere } from "../../held-elsewhere";
 import type { BuildResult } from "../../build";
 import type { ParsedArgs } from "../registry";
 
@@ -565,12 +566,49 @@ describe("runLifecycleDiff --live", () => {
       } as never);
     };
 
-    test("reports the changed property and the undeclared one", async () => {
+    test("reports the changed property as drift and the undeclared one as unclaimed", async () => {
       await runDiff([withDeep()]);
       const output = stdoutBuf.join("\n");
       expect(output).toContain("aws (properties)");
       expect(output).toContain("Versioning: Enabled → Suspended");
-      expect(output).toContain("Logging.Target: <undeclared> → audit");
+      // #2160: source never set Logging.Target, so it is somebody else's field.
+      // Still reported, no longer a difference chant proposes to close.
+      expect(output).toContain("UNCLAIMED");
+      expect(output).toContain("Logging.Target: audit [not in this declaration's claimed fields]");
+      expect(output).toContain("1 property drift across 1 resource(s)");
+      expect(output).toContain("1 unclaimed");
+    });
+
+    // #2181 - the early-return guard tested the held count twice and never the
+    // unclaimed count, so a report whose only finding was a live value
+    // nobody declared printed nothing at all: no summary line, no section. That
+    // is the case #2160 was opened to surface.
+    test("a report whose only finding is a live value nobody declared still renders", async () => {
+      const plugins = [withDeep()];
+      const build = makeBuildResult({ aws: ["bucket"] });
+      // Declared exactly what is live, so there is no drift left to carry the
+      // section into the output.
+      build.entities.set("bucket", {
+        lexicon: "aws",
+        entityType: "AWS::S3::Bucket",
+        props: { Versioning: "Suspended" },
+      } as never);
+      buildMock.mockResolvedValue(build);
+      fetchLifecycleMock.mockResolvedValue(undefined);
+      readSnapshotMock.mockResolvedValue(null);
+
+      await runLifecycleDiff({
+        args: makeArgs({ command: "state", path: "diff", extraPositional: "prod", live: true }),
+        plugins,
+        serializers: plugins.map((p) => p.serializer),
+      } as never);
+
+      const output = stdoutBuf.join("\n");
+      expect(output).toContain("aws (properties)");
+      expect(output).toContain("0 property drift across 0 resource(s)");
+      expect(output).toContain("1 unclaimed");
+      expect(output).toContain("UNCLAIMED");
+      expect(output).toContain("Logging.Target: audit");
     });
 
     test("a lexicon with no deep reader prints nothing extra", async () => {
@@ -579,28 +617,36 @@ describe("runLifecycleDiff --live", () => {
     });
 
     test("an accepted deviation in the baseline stops re-alerting", async () => {
+      // A path source declares: since #2160 the baseline only ever has drift to
+      // suppress, because an undeclared path is unclaimed and never alerted.
       readBlobFromPathMock.mockResolvedValue(
         JSON.stringify({
           baseline: "v1",
           environment: "prod",
-          lexicons: { aws: { bucket: { accepted: [{ path: "Logging.Target", value: "audit" }] } } },
+          lexicons: { aws: { bucket: { accepted: [{ path: "Versioning", value: "Suspended" }] } } },
         }),
       );
       await runDiff([withDeep()]);
       const output = stdoutBuf.join("\n");
-      expect(output).toContain("Versioning: Enabled → Suspended");
-      expect(output).not.toContain("Logging.Target: <undeclared>");
+      expect(output).not.toContain("PROPERTY DRIFT");
       expect(output).toContain("ACCEPTED (in the baseline; not drift)");
     });
 
-    test("--json carries the property drift under the lexicon's `deep` key", async () => {
+    test("--json carries the property drift and the unclaimed fields under the lexicon's `deep` key", async () => {
       await runDiff([withDeep()], { json: true });
       const payload = JSON.parse(stdoutBuf.join("\n")) as {
-        lexicons: { aws: { deep: { drifted: Array<{ changes: Array<{ path: string }> }> } } };
+        lexicons: {
+          aws: {
+            deep: {
+              drifted: Array<{ changes: Array<{ path: string }> }>;
+              unclaimed: Array<{ fields: Array<{ path: string; live: unknown; source: string }> }>;
+            };
+          };
+        };
       };
-      expect(payload.lexicons.aws.deep.drifted[0].changes.map((c) => c.path).sort()).toEqual([
-        "Logging.Target",
-        "Versioning",
+      expect(payload.lexicons.aws.deep.drifted[0].changes.map((c) => c.path)).toEqual(["Versioning"]);
+      expect(payload.lexicons.aws.deep.unclaimed[0].fields).toEqual([
+        { path: "Logging.Target", live: "audit", source: "claimed-fields" },
       ]);
     });
 
@@ -628,9 +674,11 @@ describe("runLifecycleDiff --live", () => {
       const written = JSON.parse(content) as {
         lexicons: { aws: { bucket: { accepted: Array<{ path: string; value: unknown }> } } };
       };
-      expect(written.lexicons.aws.bucket.accepted.map((a) => a.path)).toEqual(["Logging.Target", "Versioning"]);
+      // Only drift is accepted. A held field needs no acceptance: it was never
+      // reported as a deviation to begin with (#2160).
+      expect(written.lexicons.aws.bucket.accepted.map((a) => a.path)).toEqual(["Versioning"]);
       expect(pushLifecycleMock).toHaveBeenCalled();
-      expect(stderrBuf.join("\n")).toContain("accepted 2 deviation(s)");
+      expect(stderrBuf.join("\n")).toContain("accepted 1 deviation(s)");
     });
 
     test("--update-baseline with nothing reported writes nothing", async () => {
@@ -642,6 +690,72 @@ describe("runLifecycleDiff --live", () => {
     });
   });
 
+  // #2162 — a `heldElsewhere()` marker reports as held, not drift, and a
+  // held property nothing ever writes is flagged suspicious on stderr.
+  describe("heldElsewhere() markers (#2162)", () => {
+    const runHeldDiff = async (
+      liveProperties: Record<string, unknown>,
+      args: Partial<ParsedArgs> = {},
+    ) => {
+      const build = makeBuildResult({ k8s: ["web"] });
+      build.entities.set("web", {
+        lexicon: "k8s",
+        entityType: "K8s::Apps::Deployment",
+        props: { spec: { replicas: heldElsewhere<number>({ by: "hpa", reason: "the autoscaler owns replicas after the first apply" }) } },
+      } as never);
+      buildMock.mockResolvedValue(build);
+      fetchLifecycleMock.mockResolvedValue(undefined);
+      readSnapshotMock.mockResolvedValue(null);
+      const plugins: LexiconPlugin[] = [
+        createMockPlugin({
+          name: "k8s",
+          describeResources: staticObservation({ web: meta({ type: "K8s::Apps::Deployment" }) }),
+          observeResourcesDeep: staticDeepObservation({
+            web: { type: "K8s::Apps::Deployment", properties: { spec: liveProperties } },
+          }),
+        }),
+      ];
+      return runLifecycleDiff({
+        args: makeArgs({ command: "state", path: "diff", extraPositional: "prod", live: true, ...args }),
+        plugins,
+        serializers: plugins.map((p) => p.serializer),
+      } as never);
+    };
+
+    test("a live value on the held path renders as HELD, not drift", async () => {
+      await runHeldDiff({ replicas: 5 });
+      const output = stdoutBuf.join("\n");
+      expect(output).toContain("HELD (declared heldElsewhere(); not drift, never proposed for update)");
+      expect(output).toContain("spec.replicas: held by hpa — 5 (the autoscaler owns replicas after the first apply)");
+      expect(output).not.toContain("PROPERTY DRIFT");
+    });
+
+    test("--json carries the held set under the lexicon's deep.held key", async () => {
+      await runHeldDiff({ replicas: 5 }, { json: true });
+      const payload = JSON.parse(stdoutBuf.join("\n")) as {
+        lexicons: { k8s: { deep: { held: Array<{ name: string; held: Array<{ path: string; by: string }> }> } } };
+      };
+      expect(payload.lexicons.k8s.deep.held).toEqual([
+        {
+          name: "web",
+          type: "K8s::Apps::Deployment",
+          held: [
+            { path: "spec.replicas", by: "hpa", reason: "the autoscaler owns replicas after the first apply", live: 5, suspicious: false },
+          ],
+        },
+      ]);
+    });
+
+    test("no live value at all is flagged suspicious, on the terminal and on stderr", async () => {
+      await runHeldDiff({});
+      const output = stdoutBuf.join("\n");
+      expect(output).toContain("SUSPICIOUS: no live value ever showed up here");
+      expect(stderrBuf.join("\n")).toContain(
+        'web.spec.replicas is declared heldElsewhere(by: "hpa") but no live value ever showed up there',
+      );
+    });
+  });
+
   // #1166 — an environment can declare its own endpoint (a local emulator like
   // Floci), applied to the ambient var of every observing lexicon that has one
   // unless the ambient shell already set it.
@@ -799,6 +913,75 @@ describe("runLifecyclePlan", () => {
     expect(web.queried).toBe("/apis/apps/v1/namespaces/default/deployments/web");
   });
 
+  // #2162 — a held property is not an action, so the plan carries it beside
+  // `entries` rather than inside one, attributed to its lexicon the same way
+  // an entry is.
+  test("--json carries the held set beside entries, attributed to its lexicon", async () => {
+    const build = makeBuildResult({ k8s: ["web"] });
+    build.entities.set("web", {
+      lexicon: "k8s",
+      entityType: "K8s::Apps::Deployment",
+      props: { spec: { replicas: heldElsewhere<number>({ by: "hpa", reason: "the autoscaler owns replicas after the first apply" }) } },
+    } as never);
+    buildMock.mockResolvedValue(build);
+    const plugins: LexiconPlugin[] = [
+      createMockPlugin({
+        name: "k8s",
+        describeResources: staticObservation({ web: meta({ type: "K8s::Apps::Deployment" }) }),
+        observeResourcesDeep: staticDeepObservation({
+          web: { type: "K8s::Apps::Deployment", properties: { spec: { replicas: 5 } } },
+        }),
+      }),
+    ];
+    const exit = await runLifecyclePlan({
+      args: makeArgs({ path: "plan", extraPositional: "prod", json: true }),
+      plugins,
+      serializers: plugins.map((p) => p.serializer),
+    });
+    expect(exit).toBe(0);
+    const plan = JSON.parse(stdoutBuf.join("\n"));
+    expect(plan.entries.find((e: { name: string }) => e.name === "web").action).not.toBe("update");
+    expect(plan.held).toEqual([
+      {
+        name: "web",
+        type: "K8s::Apps::Deployment",
+        lexicon: "k8s",
+        held: [
+          { path: "spec.replicas", by: "hpa", reason: "the autoscaler owns replicas after the first apply", live: 5, suspicious: false },
+        ],
+      },
+    ]);
+  });
+
+  test("the human render carries a HELD section, and a suspicious one warns on stderr", async () => {
+    const build = makeBuildResult({ k8s: ["web"] });
+    build.entities.set("web", {
+      lexicon: "k8s",
+      entityType: "K8s::Apps::Deployment",
+      props: { spec: { replicas: heldElsewhere<number>({ by: "hpa", reason: "x" }) } },
+    } as never);
+    buildMock.mockResolvedValue(build);
+    const plugins: LexiconPlugin[] = [
+      createMockPlugin({
+        name: "k8s",
+        describeResources: staticObservation({ web: meta({ type: "K8s::Apps::Deployment" }) }),
+        observeResourcesDeep: staticDeepObservation({
+          web: { type: "K8s::Apps::Deployment", properties: { spec: {} } },
+        }),
+      }),
+    ];
+    const exit = await runLifecyclePlan({
+      args: makeArgs({ path: "plan", extraPositional: "prod" }),
+      plugins,
+      serializers: plugins.map((p) => p.serializer),
+    });
+    expect(exit).toBe(0);
+    expect(stdoutBuf.join("\n")).toContain("HELD (declared heldElsewhere(); not drift, never proposed for update)");
+    expect(stderrBuf.join("\n")).toContain(
+      'web.spec.replicas is declared heldElsewhere(by: "hpa") but no live value ever showed up there',
+    );
+  });
+
   // #1674 — the plan merges every lexicon's change set into one flat
   // `entries[]`; each row must still say which lexicon observed it, and carry
   // the provider's physical id so an adopt/delete/runtime row named by a live

package/src/cli/handlers/lifecycle.ts

@@ -4,8 +4,9 @@ import { build } from "../../build";
 import { takeSnapshot } from "../../lifecycle/snapshot";
 import { readSnapshot, readSnapshotAt, readEnvironmentSnapshots, listSnapshots, fetchLifecycle, pushLifecycle, snapshotStorageKey, StaleLifecycleBranchError } from "../../lifecycle/git";
 import { deepDiffForLexicon, type DeclaredEntities } from "../../lifecycle/deep-observe";
-import { countPropertyDrift, type DeepDiffResult } from "../../lifecycle/deep-diff";
-import { describePathOrigin, getPathProvenance } from "../../provenance";
+import { countUnclaimed, countPropertyDrift, countHeld, suspiciousHeld, type DeepDiffResult, type DeepEntityHeld } from "../../lifecycle/deep-diff";
+import { describePathOrigin, getPathProvenance, getProvenance, type EntityProvenance } from "../../provenance";
+import { resolveDeepDrift, resolveDriftedField, type FieldReconcile } from "../../fold-provenance";
 import {
   acceptDeviations,
   baselineForLexicon,
@@ -18,7 +19,7 @@ import {
 } from "../../lifecycle/observation-baseline";
 import { computeBuildDigest, diffDigests } from "../../lifecycle/digest";
 import { diffLive, diffLiveArtifacts, diffSnapshots, type LiveDiffResult, type LiveArtifactDiffResult, type SnapshotDiffResult } from "../../lifecycle/live-diff";
-import { buildChangeSet, renderChangeSet, renderChangeSetMarkdown, gitlabMrReport, unobservedPlanNotice, type ChangeSet } from "../../lifecycle/change-set";
+import { buildChangeSet, renderChangeSet, renderChangeSetMarkdown, gitlabMrReport, unobservedPlanNotice, type ChangeSet, type HeldEntitySet } from "../../lifecycle/change-set";
 import { mergeReceiptEntries, observedValueResolver, planReceipts, readReceiptValue, type ReceiptReading } from "../../lifecycle/receipt-plan";
 import { annotateDisruption, disruptionNotices } from "../../lifecycle/disruption";
 import { collectEffectReceipts, isEffectReceipt } from "../../effect-receipt";
@@ -697,6 +698,13 @@ interface LiveDiffOutcome {
       unobserved?: Record<string, UnobservedEntity>;
       /** Property-level drift (#1014), present only for lexicons with a deep reader. */
       deep?: DeepDiffResult;
+      /**
+       * chant #2161 — one verdict per drifted field: what the fold provenance
+       * says produced it, and what the return leg may therefore propose. A
+       * sibling of `deep` rather than a field inside it, because `deep` is the
+       * comparison and this is what may be done about it.
+       */
+      reconcile?: FieldReconcile[];
       artifacts?: LiveArtifactDiffResult;
       /** What `listArtifacts` actually saw, keyed like `artifacts`' entries
        * (behold#146). The diff alone is snapshot-relative key lists — on a
@@ -882,8 +890,25 @@ async function runLifecycleDiffLive(args: LiveDiffArgs): Promise<LiveDiffOutcome
         // otherwise one unreadable entity is counted twice.
         totalUnobserved += deep.unobserved.filter((u) => !observed.unobserved[u.name]).length;
         if (args.updateBaseline) toAccept[lexiconName] = deviationsToAccept(deep);
-        if (args.json) (byLexicon[lexiconName] ??= {}).deep = deep;
-        else renderDeepDiff(lexiconName, deep);
+        // chant #2161 — the return leg, classified by fold provenance. Read off
+        // the build's own entities, which is where the record lives.
+        const provenanceOf = (name: string): EntityProvenance | undefined => {
+          const entity = args.buildResult.entities.get(name);
+          return entity ? getProvenance(entity) : undefined;
+        };
+        if (args.json) {
+          const entry = (byLexicon[lexiconName] ??= {});
+          entry.deep = deep;
+          entry.reconcile = resolveDeepDrift(deep.drifted, provenanceOf);
+        } else renderDeepDiff(lexiconName, deep, provenanceOf);
+        // Printed on stderr regardless of `--json` (#2162), same reason the
+        // unobserved/disruption notices are: a shape with no column for
+        // "suspicious" must not read as clean.
+        for (const s of suspiciousHeld(deep)) {
+          console.error(formatWarning({
+            message: `${lexiconName}: ${s.name}.${s.path} is declared heldElsewhere(by: "${s.by}") but no live value ever showed up there — the hand-over may never have happened.`,
+          }));
+        }
       }
     }
 
@@ -939,10 +964,18 @@ function deviationsToAccept(deep: DeepDiffResult): DeviationToAccept[] {
 }
 
 /** Property-level drift report (#1014). Silent when a lexicon's deep read found nothing to say. */
-function renderDeepDiff(lexiconName: string, deep: DeepDiffResult): void {
+function renderDeepDiff(
+  lexiconName: string,
+  deep: DeepDiffResult,
+  provenanceOf: (entity: string) => EntityProvenance | undefined = () => undefined,
+): void {
   const drift = countPropertyDrift(deep);
+  const unclaimedCount = countUnclaimed(deep);
+  const heldCount = countHeld(deep);
   if (
     drift === 0 &&
+    heldCount === 0 &&
+    unclaimedCount === 0 &&
     deep.accepted.length === 0 &&
     deep.unobserved.length === 0 &&
     deep.undeclaredEntities.length === 0
@@ -955,6 +988,8 @@ function renderDeepDiff(lexiconName: string, deep: DeepDiffResult): void {
   console.log(
     `${drift} property drift across ${deep.drifted.length} resource(s), ` +
       `${acceptedCount} accepted, ${deep.unchanged.length} unchanged` +
+      (heldCount > 0 ? `, ${heldCount} held` : "") +
+      (unclaimedCount > 0 ? `, ${unclaimedCount} unclaimed` : "") +
       (deep.unobserved.length > 0 ? `, ${deep.unobserved.length} unobserved` : ""),
   );
   console.log("-".repeat(80));
@@ -967,6 +1002,7 @@ function renderDeepDiff(lexiconName: string, deep: DeepDiffResult): void {
     console.log(formatBold("\nPROPERTY DRIFT (declared vs live; baseline shown where one exists):"));
     for (const entity of deep.drifted) {
       console.log(`  - ${entity.name} (${entity.type})`);
+      const provenance = provenanceOf(entity.name);
       for (const change of entity.changes) {
         const declared = "declared" in change ? formatValue(change.declared) : "<undeclared>";
         const live = "live" in change ? formatValue(change.live) : "<absent>";
@@ -975,9 +1011,42 @@ function renderDeepDiff(lexiconName: string, deep: DeepDiffResult): void {
         const from = change.origin ? ` [from: ${describePathOrigin(change.origin)}]` : "";
         const owner = change.owner ? ` [owner: ${change.owner}]` : "";
         console.log(`      ${change.path}: ${declared} → ${live}${baseline}${from}${owner}`);
+        // chant #2161 — what may be done about it, when the origin says
+        // something today's behaviour would get wrong. A field the author
+        // declared directly is left unremarked: editing it IS today's
+        // behaviour, and saying so on every row would bury the two that matter.
+        const { resolution } = resolveDriftedField({
+          entity: entity.name,
+          path: change.path,
+          ...("declared" in change ? { declared: change.declared } : {}),
+          ...("live" in change ? { live: change.live } : {}),
+          ...(change.origin ? { origin: change.origin } : {}),
+          ...(provenance ? { provenance } : {}),
+        });
+        if (resolution.kind !== "edit-declaration") {
+          console.log(`        ${resolution.description}`);
+        }
       }
     }
   }
+  if (deep.unclaimed.length > 0) {
+    // Not drift, and printed after it for that reason (#2160): chant never set
+    // these fields, so nothing here is a change chant proposes to make.
+    console.log(formatBold("\nUNCLAIMED (live values on properties chant never declared; not drift):"));
+    for (const entity of deep.unclaimed) {
+      console.log(`  - ${entity.name} (${entity.type})`);
+      for (const field of entity.fields) {
+        const holder = field.heldBy
+          ? `held by ${field.heldBy}`
+          : "not in this declaration's claimed fields";
+        console.log(`      ${field.path}: ${formatValue(field.live)} [${holder}]`);
+      }
+    }
+  }
+  if (heldCount > 0) {
+    console.log(formatBold("\nHELD (declared heldElsewhere(); not drift, never proposed for update):"));
+    for (const line of renderHeldLines(deep.held)) console.log(line);
+  }
   if (deep.undeclaredEntities.length > 0) {
     console.log(formatBold("\nUNDECLARED (read deeply, never declared in source):"));
     for (const name of deep.undeclaredEntities) console.log(`  - ${name}`);
@@ -990,6 +1059,30 @@ function renderDeepDiff(lexiconName: string, deep: DeepDiffResult): void {
   }
 }
 
+/**
+ * Render one `heldElsewhere()` property (#2162) — shared between the deep
+ * diff's HELD section and the plan's, so the two never disagree about what a
+ * held field looks like on the terminal.
+ */
+function formatHeldProperty(h: { path: string; by: string; reason: string; live?: unknown; suspicious: boolean; owner?: string }): string {
+  const live = "live" in h ? formatValue(h.live) : "<absent>";
+  const owner = h.owner ? ` [owner: ${h.owner}]` : "";
+  const suspicious = h.suspicious
+    ? " [SUSPICIOUS: no live value ever showed up here — check the holder is actually running, or that this is the field it writes]"
+    : "";
+  return `      ${h.path}: held by ${h.by} — ${live}${owner} (${h.reason})${suspicious}`;
+}
+
+/** Lines for every held property across a lexicon's entities, indented and grouped by entity name. */
+function renderHeldLines(held: readonly DeepEntityHeld[]): string[] {
+  const lines: string[] = [];
+  for (const entity of held) {
+    lines.push(`  - ${entity.name} (${entity.type})`);
+    for (const h of entity.held) lines.push(formatHeldProperty(h));
+  }
+  return lines;
+}
+
 function renderLiveDiff(lexiconName: string, environment: string, diff: LiveDiffResult): void {
   const counts =
     `${diff.missing.length} missing, ${diff.orphan.length} orphan, ` +
@@ -1148,6 +1241,9 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
 
   const merged: ChangeSet = { env: environment, entries: [] };
   let checked = 0;
+  // Held properties (#2162), across every lexicon this plan checks — not an
+  // action, so it rides beside `entries` rather than inside it.
+  const heldSets: HeldEntitySet[] = [];
 
   // Effect receipts (#1832): declared, diffed, and observed like any resource,
   // but observe-only to the generic apply path — the plan compares live value
@@ -1221,6 +1317,26 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
       });
 
       Object.assign(allObservedResources, observed.resources);
+
+      // Held properties (#2162): opt-in on the same capability the deep diff
+      // path gates on. A held property is never a proposal, so it is
+      // computed here (once per lexicon, against this same observation) and
+      // carried on the plan beside `entries` rather than folded into one.
+      if (plugin.observeResourcesDeep) {
+        const deep = await deepDiffForLexicon(plugin, {
+          environment,
+          buildOutput,
+          entities,
+          componentStacks,
+        });
+        for (const entity of deep.held) heldSets.push({ ...entity, lexicon: lexiconName });
+        for (const s of suspiciousHeld(deep)) {
+          console.error(formatWarning({
+            message: `${lexiconName}: ${s.name}.${s.path} is declared heldElsewhere(by: "${s.by}") but no live value ever showed up there — the hand-over may never have happened.`,
+          }));
+        }
+      }
+
       for (const [receiptName, receipt] of receipts) {
         if (receipt.lexicon !== lexiconName) continue;
         const live = observed.resources[receiptName];
@@ -1301,6 +1417,7 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
   }
 
   merged.entries.sort((a, b) => a.name.localeCompare(b.name));
+  if (heldSets.length > 0) merged.held = heldSets.sort((a, b) => a.name.localeCompare(b.name));
 
   // Say it on stderr too, so `--json` and `--report gitlab-mr` consumers (whose
   // shapes have no room for it) still learn the plan has a hole (#1089). The

package/src/cli/handlers/misc.ts

@@ -24,7 +24,7 @@ const CHANT_VERSION: string = (() => {
 
 const AUDIT_FORMATS: AuditFormat[] = ["stylish", "json", "sarif", "markdown", "html"];
 const AUDIT_TIERS: AuditTier[] = ["merge-worthy", "all"];
-const AUDIT_FAIL_ON: AuditFailOn[] = ["merge-worthy", "warning", "none"];
+const AUDIT_FAIL_ON: AuditFailOn[] = ["merge-worthy", "warning", "error", "none"];
 
 /**
  * Parse `--scope system,user,project`. Returns `undefined` (meaning "all") when