@intentius/chant 0.79.0 → 0.81.0

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

@@ -0,0 +1,127 @@
+/**
+ * `chant build --components --generate` inside a workspace member (#2542).
+ * Component discovery is stubbed with a fixed graph; the github generator is
+ * the real one, so the files checked here are what a user gets. A project
+ * outside any workspace is held to its old output byte for byte, and to a
+ * snapshot, since level 0 must not move (#2525).
+ */
+
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { DriverComponent } from "../../components/driver";
+import type { ComponentPipelineOptions } from "../../lexicon";
+import type { ParsedArgs } from "../registry";
+import { generateGithubPipeline } from "@intentius/chant-lexicon-github/components/generate-pipeline";
+import { twoMemberWorkspace } from "../../workspace/__fixtures__/two-member-workspace";
+
+const components: DriverComponent[] = [
+  { name: "shared-alb", dependsOn: [], deploy: [] },
+  { name: "api", dependsOn: ["shared-alb"], deploy: [] },
+];
+
+const received: (ComponentPipelineOptions | undefined)[] = [];
+vi.mock("../../components/cli-support", () => ({
+  generateComponentsPipeline: async (_path: string, _lexicon: string, options?: ComponentPipelineOptions) => {
+    received.push(options);
+    const { yaml, stages, jobs, env } = generateGithubPipeline(components, options);
+    return { success: true, yaml, stages, jobs, env };
+  },
+}));
+vi.mock("../../config", async () => {
+  const actual = await vi.importActual<typeof import("../../config")>("../../config");
+  return { ...actual, loadChantConfigUpward: async () => ({ config: {} }) };
+});
+
+const { runBuild } = await import("./build");
+
+function args(overrides: Partial<ParsedArgs>): ParsedArgs {
+  return {
+    command: "build",
+    path: ".",
+    format: "",
+    fix: false,
+    watch: false,
+    verbose: false,
+    help: false,
+    live: false,
+    components: true,
+    generate: "github",
+    ...overrides,
+  };
+}
+
+let repo: string;
+let logs: string[];
+beforeEach(() => {
+  received.length = 0;
+  logs = [];
+  vi.spyOn(console, "error").mockImplementation(() => {});
+  vi.spyOn(console, "log").mockImplementation((s: string) => {
+    logs.push(s);
+  });
+});
+afterEach(() => {
+  vi.restoreAllMocks();
+  rmSync(repo, { recursive: true, force: true });
+});
+
+describe("a project inside a workspace member", () => {
+  beforeEach(() => {
+    repo = twoMemberWorkspace();
+  });
+
+  test("the pipeline is written to the member's file at the repository root, filtered and recorded", async () => {
+    expect(await runBuild({ args: args({ path: join(repo, "services/api"), env: "staging" }), plugins: [], serializers: [] })).toBe(0);
+
+    expect(received[0]?.member).toEqual({ name: "api", dir: "services/api", file: ".github/workflows/chant-api-staging.yml" });
+    const file = join(repo, ".github/workflows/chant-api-staging.yml");
+    const text = readFileSync(file, "utf-8");
+    const [header, ...rest] = text.split("\n");
+    expect(header).toContain("Regenerate with: chant build --components --generate github --env staging");
+    expect(rest.join("\n")).toBe(generateGithubPipeline(components, { env: "staging", member: received[0]!.member }).yaml);
+    expect(text).toContain("working-directory: services/api");
+
+    const record = JSON.parse(readFileSync(join(repo, "services/api/.chant/generated.json"), "utf-8"));
+    expect(record.files).toEqual([{ path: ".github/workflows/chant-api-staging.yml", command: "chant build --components --generate github --env staging", env: "staging" }]);
+  });
+
+  test("two members write two files and never collide", async () => {
+    await runBuild({ args: args({ path: join(repo, "services/api"), env: "prod" }), plugins: [], serializers: [] });
+    await runBuild({ args: args({ path: join(repo, "apps/web"), env: "prod" }), plugins: [], serializers: [] });
+    expect(existsSync(join(repo, ".github/workflows/chant-api-prod.yml"))).toBe(true);
+    expect(existsSync(join(repo, ".github/workflows/chant-web-prod.yml"))).toBe(true);
+  });
+
+  test("--format json names the member and the file and writes nothing", async () => {
+    expect(await runBuild({ args: args({ path: join(repo, "apps/web"), env: "prod", format: "json" }), plugins: [], serializers: [] })).toBe(0);
+    const out = JSON.parse(logs.join("\n"));
+    expect(out).toMatchObject({ member: "web", file: ".github/workflows/chant-web-prod.yml", env: "prod" });
+    expect(existsSync(join(repo, ".github/workflows/chant-web-prod.yml"))).toBe(false);
+  });
+
+  test("an example project in a group is not a member, and gets the plain pipeline", async () => {
+    expect(await runBuild({ args: args({ path: join(repo, "examples/demo") }), plugins: [], serializers: [] })).toBe(0);
+    expect(received[0]).toEqual({ env: undefined });
+    expect(logs.join("\n")).toBe(generateGithubPipeline(components, {}).yaml);
+  });
+});
+
+describe("a project outside any workspace (level 0)", () => {
+  beforeEach(() => {
+    repo = realpathSync(mkdtempSync(join(tmpdir(), "chant-build-level0-")));
+    execFileSync("git", ["init", "-q"], { cwd: repo });
+  });
+
+  test("the pipeline is the generator's output, unchanged", async () => {
+    const output = join(repo, "pipeline.yml");
+    expect(await runBuild({ args: args({ path: repo, env: "staging", output }), plugins: [], serializers: [] })).toBe(0);
+    expect(received[0]).toEqual({ env: "staging" });
+    const text = readFileSync(output, "utf-8");
+    expect(text).toBe(generateGithubPipeline(components, { env: "staging" }).yaml);
+    expect(text).toMatchSnapshot();
+    expect(existsSync(join(repo, ".chant"))).toBe(false);
+  });
+});

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

@@ -70,6 +70,17 @@ describe("runBuild --components --generate (chant #1108 build-time parameters)",
     vi.restoreAllMocks();
   });
 
+  test("--promote-to is forwarded to the generator as promoteTo (#2575)", async () => {
+    generateComponentsPipelineMock.mockResolvedValue({ success: true, yaml: "stages: []", stages: [], jobs: [] });
+    vi.spyOn(console, "log").mockImplementation(() => {});
+
+    const exit = await runBuild({ args: makeArgs({ env: "staging", promoteTo: "prod" }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(0);
+    expect(generateComponentsPipelineMock).toHaveBeenCalledWith(".", "gitlab", { env: "staging", promoteTo: "prod" }, undefined, []);
+    vi.restoreAllMocks();
+  });
+
   test("chant.config.ts's declared buildParams resolve, log, and are forwarded to generateComponentsPipeline", async () => {
     loadChantConfigUpwardMock.mockResolvedValue({
       config: { buildParams: { tier: { type: "string", default: "light" } } },

package/src/cli/handlers/build.ts

@@ -6,6 +6,7 @@ import type { CommandContext } from "../registry";
 import { generateComponentsPipeline } from "../../components/cli-support";
 import { loadChantConfigUpward, type ChantConfig } from "../../config";
 import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
+import { findWorkspaceRoot } from "../../project-root";
 
 /**
  * `chant build --components --generate <lexicon>` — generate mode (#563,
@@ -44,6 +45,33 @@ async function runGenerateComponents(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
+  // A project inside a workspace member gets that member's pipeline (#2542):
+  // path-filtered, run in the member's directory, written to a file named
+  // after the member and recorded as the member's generated file. The
+  // workspace module loads only when a declaration was found, so a project
+  // outside any workspace generates exactly what it did before.
+  const found = findWorkspaceRoot(resolve(args.path));
+  let plan: import("../../workspace/member-pipeline").MemberComponentPlan | undefined;
+  let memberPipeline: typeof import("../../workspace/member-pipeline") | undefined;
+  if (found) {
+    memberPipeline = await import("../../workspace/member-pipeline");
+    try {
+      plan = memberPipeline.planMemberComponentPipeline({
+        projectDir: resolve(args.path),
+        found,
+        lexicon,
+        env: args.env,
+        promoteTo: args.promoteTo,
+        output: args.output,
+        params: args.param,
+        paramsFile: args.paramsFile,
+      });
+    } catch (err) {
+      console.error(formatError({ message: memberPipeline.describeError(err) }));
+      return 1;
+    }
+  }
+
   // Which lexicons support generate mode is a property of the loaded lexicon
   // plugins (those implementing `generateComponentPipeline`, #688), not a
   // hard-coded core list — `generateComponentsPipeline` returns a descriptive
@@ -51,7 +79,7 @@ async function runGenerateComponents(ctx: CommandContext): Promise<number> {
   const result = await generateComponentsPipeline(
     args.path,
     lexicon,
-    { env: args.env },
+    { env: args.env, ...(args.promoteTo ? { promoteTo: args.promoteTo } : {}), ...(plan ? { member: plan.member } : {}) },
     args.sandbox,
     paramsResolution.provenance,
   );
@@ -73,11 +101,17 @@ async function runGenerateComponents(ctx: CommandContext): Promise<number> {
           // 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 } : {}),
+          // A workspace member's pipeline (#2542): the member and the file
+          // the pipeline belongs in, relative to the repository root.
+          ...(plan ? { member: plan.member.name, file: plan.file } : {}),
         },
         null,
         2,
       ),
     );
+  } else if (plan && memberPipeline) {
+    memberPipeline.writeMemberComponentPipeline(plan, yaml);
+    console.error(formatSuccess(`wrote ${formatBold(plan.file)} for member ${formatBold(plan.member.name)}`));
   } else if (args.output) {
     const outputPath = resolve(args.output);
     mkdirSync(dirname(outputPath), { recursive: true });

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

@@ -23,6 +23,7 @@ const awsEmulatorStub = {
 const getHeadCommitMock = vi.fn();
 const fetchLifecycleMock = vi.fn();
 const pushLifecycleMock = vi.fn();
+const readSnapshotMock = vi.fn();
 
 const appendReleaseRecordMock = vi.fn();
 const readReleaseLedgerMock = vi.fn();
@@ -38,6 +39,8 @@ vi.mock("../../lifecycle/git", () => ({
   getHeadCommit: (...args: unknown[]) => getHeadCommitMock(...args),
   fetchLifecycle: (...args: unknown[]) => fetchLifecycleMock(...args),
   pushLifecycle: (...args: unknown[]) => pushLifecycleMock(...args),
+  readSnapshot: (...args: unknown[]) => readSnapshotMock(...args),
+  snapshotStorageKey: (lexicon: string, stack?: string) => (stack ? `${stack}__${lexicon}` : lexicon),
   StaleLifecycleBranchError: class StaleLifecycleBranchError extends Error {},
 }));
 
@@ -125,6 +128,7 @@ describe("components handlers", () => {
     getHeadCommitMock.mockReset().mockResolvedValue("abc123headsha");
     fetchLifecycleMock.mockReset().mockResolvedValue(true);
     pushLifecycleMock.mockReset().mockResolvedValue(true);
+    readSnapshotMock.mockReset().mockResolvedValue(null);
     appendReleaseRecordMock.mockReset();
     readReleaseLedgerMock.mockReset().mockResolvedValue({ records: [], malformed: 0 });
     listReleaseEnvironmentsMock.mockReset().mockResolvedValue([]);
@@ -567,6 +571,129 @@ describe("components handlers", () => {
       });
     });
 
+    // #2513: `--live` could never report `drifted` — the change set was built
+    // with no prior observation, so a live, declared entity was always `noop`,
+    // and nothing compared the live identity with the recorded release. These
+    // go through the handler end to end with a fake lexicon.
+    describe("drifted (#2513)", () => {
+      const released = {
+        version: 1,
+        component: "svc",
+        env: "prod",
+        digest: "sha256:released",
+        gitSha: "1111111aaaaaaa",
+        runId: "run-1",
+        timestamp: "2026-02-01T00:00:00.000Z",
+        actor: "alice",
+      };
+
+      async function statusRow(
+        resources: Record<string, ResourceMetadata>,
+        opts: { snapshot?: { timestamp: string; resources: Record<string, ResourceMetadata> }; failRead?: boolean } = {},
+      ) {
+        readReleaseLedgerMock.mockResolvedValue({ records: [released], malformed: 0 });
+        buildMock.mockResolvedValue(makeBuildResult({ aws: ["svc"] }));
+        readSnapshotMock.mockImplementation(async (env: string, key: string) =>
+          opts.snapshot && env === "prod" && key === "aws"
+            ? JSON.stringify({ lexicon: "aws", environment: "prod", commit: "c", ...opts.snapshot })
+            : null,
+        );
+        const plugins: LexiconPlugin[] = [
+          createMockPlugin({
+            name: "aws",
+            emulator: awsEmulatorStub,
+            describeResources: opts.failRead
+              ? async () => { throw new Error("credentials expired"); }
+              : staticDescribeResources(resources),
+          }),
+        ];
+        stdoutBuf.length = 0;
+        const exit = await runComponentsStatus({
+          args: makeArgs({ extraPositional: "prod", live: true, json: true }),
+          plugins,
+          serializers: plugins.map((p) => p.serializer),
+        });
+        expect(exit).toBe(0);
+        return JSON.parse(stdoutBuf.join(""))[0];
+      }
+
+      test("reconciled: live identity matches the recorded digest and git sha", async () => {
+        const row = await statusRow({ svc: meta({ attributes: { digest: "sha256:released", gitSha: "1111111" } }) });
+        expect(row).toMatchObject({ component: "svc", reconciliation: "reconciled", live: true });
+      });
+
+      test("drifted: live resource reports a digest other than the recorded one", async () => {
+        const row = await statusRow({ svc: meta({ attributes: { digest: "sha256:foreign" } }) });
+        expect(row).toMatchObject({ component: "svc", reconciliation: "drifted", live: true });
+        expect(row.detail).toContain("sha256:foreign");
+      });
+
+      test("drifted: live resource reports a different git sha", async () => {
+        const row = await statusRow({ svc: meta({ attributes: { gitSha: "2222222bbbbbbb" } }) });
+        expect(row).toMatchObject({ reconciliation: "drifted" });
+        expect(row.detail).toContain("2222222bbbbbbb");
+      });
+
+      test("drifted: live attributes changed since a snapshot taken after the release", async () => {
+        const row = await statusRow(
+          { svc: meta({ attributes: { revision: "7" } }) },
+          { snapshot: { timestamp: "2026-02-01T00:05:00.000Z", resources: { svc: meta({ attributes: { revision: "6" } }) } } },
+        );
+        expect(row).toMatchObject({ reconciliation: "drifted" });
+        expect(row.detail).toContain("attributes.revision");
+      });
+
+      test("drifted: chant's ownership marker disappeared since a post-release snapshot", async () => {
+        const row = await statusRow(
+          { svc: meta({ ownership: "foreign" }) },
+          { snapshot: { timestamp: "2026-02-02T00:00:00.000Z", resources: { svc: meta({ ownership: "owned" }) } } },
+        );
+        expect(row).toMatchObject({ reconciliation: "drifted" });
+        expect(row.detail).toContain("ownership marker");
+      });
+
+      test("reconciled: a snapshot older than the release does not attribute the release's own change to drift", async () => {
+        const row = await statusRow(
+          { svc: meta({ attributes: { revision: "7" } }) },
+          { snapshot: { timestamp: "2026-01-15T00:00:00.000Z", resources: { svc: meta({ attributes: { revision: "6" } }) } } },
+        );
+        expect(row).toMatchObject({ reconciliation: "reconciled" });
+      });
+
+      test("reconciled: unchanged since the snapshot, and no identity reported (no identity is not drift)", async () => {
+        const row = await statusRow(
+          { svc: meta() },
+          { snapshot: { timestamp: "2026-02-01T00:05:00.000Z", resources: { svc: meta() } } },
+        );
+        expect(row).toMatchObject({ reconciliation: "reconciled" });
+      });
+
+      test("stale: recorded, and the provider confirmed nothing live", async () => {
+        const row = await statusRow(
+          {},
+          { snapshot: { timestamp: "2026-02-01T00:05:00.000Z", resources: { svc: meta({ attributes: { digest: "sha256:foreign" } }) } } },
+        );
+        expect(row).toMatchObject({ reconciliation: "stale", live: false });
+      });
+
+      test("unknown: a failed read is never drifted, whatever the snapshot says", async () => {
+        const row = await statusRow(
+          {},
+          {
+            failRead: true,
+            snapshot: { timestamp: "2026-02-01T00:05:00.000Z", resources: { svc: meta({ attributes: { digest: "sha256:foreign" } }) } },
+          },
+        );
+        expect(row).toMatchObject({ reconciliation: "unknown" });
+        expect(row).not.toHaveProperty("live");
+      });
+
+      test("reads the same unstacked snapshot `lifecycle plan` reads", async () => {
+        await statusRow({ svc: meta() });
+        expect(readSnapshotMock).toHaveBeenCalledWith("prod", "aws");
+      });
+    });
+
     test("reports malformed ledger lines as a warning without failing", async () => {
       readReleaseLedgerMock.mockResolvedValue({ records: [], malformed: 2 });
       const ctx = { args: makeArgs({ extraPositional: "prod" }), plugins: [], serializers: [] };

package/src/cli/handlers/components.ts

@@ -28,7 +28,8 @@
  */
 import { resolve, join, dirname } from "node:path";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { getHeadCommit, fetchLifecycle, pushLifecycle, StaleLifecycleBranchError } from "../../lifecycle/git";
+import { getHeadCommit, fetchLifecycle, pushLifecycle, readSnapshot, snapshotStorageKey, StaleLifecycleBranchError } from "../../lifecycle/git";
+import type { LifecycleSnapshot } from "../../lifecycle/types";
 import {
   appendReleaseRecord,
   readReleaseLedger,
@@ -37,7 +38,7 @@ import {
   resolveRunId,
   InvalidReleaseRecordError,
 } from "../../lifecycle/release-ledger";
-import { reconcileStatus, liveEvidenceFromChangeSet, compareAcrossEnvironments, mergeLiveEvidence, type LiveComponentEvidence } from "../../lifecycle/status";
+import { reconcileStatus, liveEvidenceFromChangeSet, compareAcrossEnvironments, mergeLiveEvidence, type LiveComponentEvidence, type EntityLiveRead } from "../../lifecycle/status";
 import { commandBuildParams } from "../build-params-cli";
 import { buildChangeSet } from "../../lifecycle/change-set";
 import { buildLedgerEntries, componentBomSummary, type BuildLedgerEntry } from "../../lifecycle/build-ledger";
@@ -51,11 +52,12 @@ import { build } from "../../build";
 import { discoverComponents } from "../../components/discover";
 import { formatError, formatWarning, formatSuccess, formatBold } from "../format";
 import type { CommandContext } from "../registry";
-import type { LexiconPlugin } from "../../lexicon";
+import type { LexiconPlugin, ResourceMetadata } from "../../lexicon";
 import { normalizeObservation, mergeObservations, unobservedAll, type NormalizedObservation } from "../../observation";
 import type { Phase, Component } from "../../components/component";
 import { deployUnits } from "../../components/deploy-units";
 import { sortedJsonReplacer } from "../../utils";
+import { withoutReadFlags } from "../../lifecycle/legacy-digest";
 
 /**
  * chant components release <env> --component <name> --digest <sha256:...>
@@ -276,7 +278,8 @@ export async function runComponentsExport(ctx: CommandContext): Promise<number>
     }
   }
 
-  await writeFile(join(targetDir, "manifest.json"), JSON.stringify(manifest, sortedJsonReplacer, 2));
+  // The exported manifest is the recorded one; read-side flags (#2514) stay out of it.
+  await writeFile(join(targetDir, "manifest.json"), JSON.stringify(withoutReadFlags(manifest), sortedJsonReplacer, 2));
 
   const missing = results.filter((r) => r.status === "missing");
 
@@ -284,6 +287,7 @@ export async function runComponentsExport(ctx: CommandContext): Promise<number>
     console.log(JSON.stringify({
       component: manifest.component,
       manifestDigest: manifest.manifestDigest,
+      ...(manifest.flags ? { flags: manifest.flags } : {}),
       outDir: targetDir,
       entries: results,
     }, null, 2));
@@ -318,6 +322,7 @@ interface StatusJsonRow {
     runId: string;
     timestamp: string;
     actor: string;
+    flags?: string[];
   } | null;
   build: {
     manifestDigest: string;
@@ -464,6 +469,42 @@ async function observeComponentStacks(
   return evidence;
 }
 
+/**
+ * The last lifecycle snapshot(s) for one lexicon, as `components status --live`
+ * reads them for its drift baseline (#2513). Reads the stack-keyed snapshot for
+ * each stack the status read targets and the unstacked one `lifecycle plan`
+ * reads, merging resources (a stack's own snapshot wins) and remembering, per
+ * entity, which snapshot's timestamp it came from. A missing or unreadable
+ * snapshot is no baseline, never an error: with none, nothing can have changed
+ * since, and the status falls back to identity and presence.
+ */
+async function readStatusBaseline(
+  environment: string,
+  lexicon: string,
+  stacks: Array<string | undefined>,
+): Promise<{ resources: Record<string, ResourceMetadata> | undefined; timestamps: Map<string, string> }> {
+  const keys = [...new Set([...stacks.filter((s): s is string => !!s).map((s) => snapshotStorageKey(lexicon, s)), snapshotStorageKey(lexicon)])];
+  let resources: Record<string, ResourceMetadata> | undefined;
+  const timestamps = new Map<string, string>();
+  for (const key of keys) {
+    let snap: LifecycleSnapshot | undefined;
+    try {
+      const content = await readSnapshot(environment, key);
+      snap = content ? (JSON.parse(content) as LifecycleSnapshot) : undefined;
+    } catch {
+      snap = undefined;
+    }
+    if (!snap?.resources) continue;
+    resources ??= {};
+    for (const [name, meta] of Object.entries(snap.resources)) {
+      if (Object.prototype.hasOwnProperty.call(resources, name)) continue;
+      resources[name] = meta;
+      if (snap.timestamp) timestamps.set(name, snap.timestamp);
+    }
+  }
+  return { resources, timestamps };
+}
+
 export async function runComponentsStatus(ctx: CommandContext): Promise<number> {
   const { args, plugins, serializers } = ctx;
   const requestedEnv = args.extraPositional;
@@ -554,6 +595,7 @@ export async function runComponentsStatus(ctx: CommandContext): Promise<number>
         for (const stack of config.stacks ?? []) componentStackNames.add(stack.name);
         const readTargets: Array<string | undefined> = componentStackNames.size ? [...componentStackNames] : [undefined];
         const merged: { env: string; entries: import("../../lifecycle/change-set").ChangeSetEntry[] } = { env: environment, entries: [] };
+        const observations = new Map<string, EntityLiveRead>();
         for (const plugin of plugins) {
           if (!plugin.describeResources) continue;
           const declared = new Set<string>();
@@ -593,15 +635,29 @@ export async function runComponentsStatus(ctx: CommandContext): Promise<number>
             console.error(formatWarning({ message: `${plugin.name}: describeResources failed — ${message} (components in this lexicon report unknown, not stale)` }));
             observed = { resources: {}, unobserved: unobservedAll(declared, "read-failed", message, entities), queried: {}, sources: {}, notes: [] };
           }
+          // The last lifecycle snapshot is the prior observation drift is
+          // measured against (#2513) — the same one `lifecycle plan` reads, so
+          // `drifted` here means what `update` means there. Without it every
+          // live, declared entity classified `noop` and `drifted` could not be
+          // reached. Each entity remembers its snapshot's timestamp so the
+          // status join can ignore a change made before the release.
+          const baseline = await readStatusBaseline(environment, plugin.name, readTargets);
           const cs = buildChangeSet(environment, {
             declared,
             observedNow: observed.resources,
-            observedThen: undefined,
+            observedThen: baseline.resources,
             unobserved: observed.unobserved,
           }, { lexicon: plugin.name });
           merged.entries.push(...cs.entries);
+          for (const entry of cs.entries) {
+            observations.set(entry.name, {
+              now: observed.resources[entry.name],
+              then: baseline.resources?.[entry.name],
+              thenAt: baseline.timestamps.get(entry.name),
+            });
+          }
         }
-        liveEvidence = liveEvidenceFromChangeSet(merged, liveNameMapping);
+        liveEvidence = liveEvidenceFromChangeSet(merged, liveNameMapping, { observations });
 
         // Multi-stack component projects (each component owns its own stack) are
         // invisible to the entity-keyed, single-stack `describeResources` above —
@@ -652,6 +708,7 @@ export async function runComponentsStatus(ctx: CommandContext): Promise<number>
               runId: row.recorded.runId,
               timestamp: row.recorded.timestamp,
               actor: row.recorded.actor,
+              ...(row.recorded.flags ? { flags: row.recorded.flags } : {}),
             }
           : null,
         build: row.build
@@ -729,14 +786,19 @@ export async function runComponentsStatus(ctx: CommandContext): Promise<number>
       row.env.padEnd(12) +
       digestShort.padEnd(20) +
       row.reconciliation.padEnd(14) +
-      row.detail,
+      row.detail +
+      (row.recorded?.flags?.length ? ` [${row.recorded.flags.join(", ")}]` : ""),
     );
   }
 
   if (comparisons) {
     console.log(`\n${formatBold(`Cross-check: ${requestedEnv} vs ${args.compareTo}`)}`);
     for (const c of comparisons) {
-      const verdict = c.same ? "same build" : "DIFFERENT builds";
+      const verdict = c.same
+        ? "same build"
+        : c.mixedDigestForms
+          ? "different digests, one recorded before real SHA-256 (legacy-digest), so this cannot tell"
+          : "DIFFERENT builds";
       console.log(`  ${c.component}: ${c.digestA ?? "(none)"} vs ${c.digestB ?? "(none)"} — ${verdict}`);
     }
   }

package/src/cli/handlers/dev.ts

@@ -1,5 +1,5 @@
 import { resolve } from "node:path";
-import { formatError, formatSuccess } from "../format";
+import { formatError, formatSuccess, formatWarning } from "../format";
 import type { CommandContext } from "../registry";
 
 export async function runDevGenerate(ctx: CommandContext): Promise<number> {
@@ -33,6 +33,11 @@ export async function runDevOnboard(ctx: CommandContext): Promise<number> {
   }
 
   const { onboardCommand, printOnboardResult } = await import("../commands/onboard");
+  // chant#2578 — so a lexicon the project declares by path is recognised.
+  // chant#2591 — read without running chant.config.ts.
+  const { recordProjectLexicons, unknownPathLexiconsNotice } = await import("../plugins");
+  const notice = unknownPathLexiconsNotice(recordProjectLexicons(process.cwd()));
+  if (notice !== undefined) console.error(formatWarning({ message: notice }));
   const result = onboardCommand({ name, verbose: ctx.args.verbose });
   await printOnboardResult(result, name);
   return result.success ? 0 : 1;

package/src/cli/handlers/fan-out.ts

@@ -43,7 +43,8 @@ import { deriveFanOut, fanOutRegistry } from "../../components/fan-out-support";
 import { runFanOut } from "../../components/fan-out-run";
 import { renderFanOutHuman, renderFanOutJson, renderFanOutPlan } from "../../components/fan-out-output";
 import { ndjsonProgressSink } from "../../components/run-progress";
-import { writeGatedRunSummary } from "../../op/gate-summary";
+import { summaryLedgerPrefix, writeGatedRunSummary } from "../../op/gate-summary";
+import { approveCommand } from "../../op/gate";
 import { remainingFanOut, type ChangedUnits, type FanOutProgress } from "../../components/fan-out";
 import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
 import { formatError, formatInfo, formatWarning } from "../format";
@@ -320,7 +321,11 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
 
   if (result.status === "gated" && result.gate) {
     const pending = result.gate;
-    console.error(formatInfo(`approve : chant approve ${pending.op} ${pending.gate} --plan ${result.plan.digest}`));
+    // The pending fact's own plan: the fan-out's digest for the gate over the
+    // set, or a component's plan and environment for a gate inside one (#2574).
+    console.error(formatInfo(
+      `approve : ${approveCommand(pending.op, pending.gate, pending.environment)} --plan ${pending.planDigest ?? result.plan.digest}`,
+    ));
     writeGatedRunSummary({
       op: pending.op,
       gate: pending.gate,
@@ -328,6 +333,8 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
       expiresAt: pending.expiresAt,
       ...(pending.url ? { url: pending.url } : {}),
       ...(pending.planDigest ? { planDigest: pending.planDigest } : {}),
+      ...(await summaryLedgerPrefix()),
+      ...(pending.environment ? { environment: pending.environment } : {}),
     });
     return GATED_EXIT_CODE;
   }

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

@@ -2,6 +2,7 @@ import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
 import type { ParsedArgs } from "../registry";
 import { DECLARABLE_MARKER, type Declarable } from "../../declarable";
 import { AttrRef } from "../../attrref";
+import { GRAPH_IR_VERSION } from "../../graph-ir";
 
 /**
  * The aws emulator capability, as the real plugin declares it. `--live`
@@ -226,6 +227,25 @@ describe("runGraph", () => {
       expect(ir.edges).toContainEqual({ from: "subnet", to: "vpc", kind: "ref", viaAttr: "network" });
     });
 
+    // #2529 — the IR carries its version, as the first key, so a reader can
+    // decide how to read the rest before it reads anything else.
+    test("--format ir leads with the IR version", async () => {
+      lintClean(); discovered();
+      const exit = await runGraph({ args: makeArgs({ format: "ir" }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      const ir = JSON.parse(stdoutBuf.join("\n"));
+      expect(ir.version).toBe(GRAPH_IR_VERSION);
+      expect(GRAPH_IR_VERSION).toBe(1);
+      expect(Object.keys(ir)[0]).toBe("version");
+    });
+
+    test("the other view formats carry no version field", async () => {
+      lintClean(); discovered();
+      const exit = await runGraph({ args: makeArgs({ format: "mermaid" }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      expect(stdoutBuf.join("\n")).not.toContain("version");
+    });
+
     // #1675 — discovery scans sourceDir, but ops live beside it (project root,
     // `ops/`) and are found by discoverOps from the git root. The IR joins them.
     describe("ops outside sourceDir reach the IR (#1675)", () => {

package/src/cli/handlers/graph.ts

@@ -2,7 +2,7 @@ import { dirname, resolve } from "node:path";
 import { discoverOps } from "../../op/discover";
 import { discover } from "../../discovery/index";
 import { partitionByLexicon, computeStackGraph, build, mergeBuildRootEntities } from "../../build";
-import { buildGraphIr, buildLiveGraphIr, collectUnobserved, overlayGraphs, sourceOverlayGraphs, type GraphIR, type IRPipeline, type LiveObservation } from "../../graph-ir";
+import { buildGraphIr, buildLiveGraphIr, collectUnobserved, overlayGraphs, sourceOverlayGraphs, GRAPH_IR_VERSION, type GraphIR, type IRPipeline, type LiveObservation } from "../../graph-ir";
 import { behaviourOverlay } from "../../behaviour-overlay";
 import type { SerializerResult } from "../../serializer";
 import { applyBehaviourOverlay, behaviourRequestFromIr } from "../../behaviour-graph";
@@ -886,7 +886,9 @@ async function emitIr(
       }
     case "ir":
     default:
-      console.log(JSON.stringify(ir, null, 2));
+      // The version leads the document (#2529), so a reader sees it before
+      // anything it might not understand.
+      console.log(JSON.stringify({ version: GRAPH_IR_VERSION, ...ir }, null, 2));
       return 0;
   }
 }