@intentius/chant 0.29.0 → 0.31.0

package/src/cli/handlers/graph.ts

@@ -2,7 +2,7 @@ import { resolve } from "node:path";
 import { discoverOps } from "../../op/discover";
 import { discover } from "../../discovery/index";
 import { partitionByLexicon, computeStackGraph, build } from "../../build";
-import { buildGraphIr, buildLiveGraphIr, collectUnobserved, overlayGraphs, sourceOverlayGraphs, type GraphIR, type LiveObservation } from "../../graph-ir";
+import { buildGraphIr, buildLiveGraphIr, collectUnobserved, overlayGraphs, sourceOverlayGraphs, type GraphIR, type IRPipeline, type LiveObservation } from "../../graph-ir";
 import { reconstructEdges, mergeCatalogs, containmentGroups, type ReferenceCatalog, type ContainmentPair } from "../../graph-refs";
 import { observeResources } from "../../lifecycle/observe";
 import { loadChantConfig, environmentNames } from "../../config";
@@ -17,7 +17,7 @@ import { loadPlugins, resolveProjectLexicons } from "../plugins";
 import { readFileSync } from "node:fs";
 import { formatError, formatWarning, formatBold } from "../format";
 import type { CommandContext } from "../registry";
-import { computeComponentGraph } from "../../components/cli-support";
+import { computeComponentGraph, generateComponentsPipeline } from "../../components/cli-support";
 import { discoverComponents } from "../../components/discover";
 import { cfnDeployStacks } from "./components";
 
@@ -34,6 +34,18 @@ import { cfnDeployStacks } from "./components";
 export async function runGraph(ctx: CommandContext): Promise<number> {
   const viewFormats = ["ir", "mermaid", "dot", "layout"] as const;
   const isViewFormat = (viewFormats as readonly string[]).includes(ctx.args.format);
+  // `--projection <lexicon>` (#989) only means anything for the component
+  // graph's IR — it adds the CI/pipeline shape to `GraphIR.pipeline`, a field
+  // the other view formats' emitters (mermaid/dot/layout) don't read, and the
+  // plain (non-`--format`) `--components` text/`--json` modes don't build an
+  // IR at all. Reject every other combination up front rather than silently
+  // ignoring the flag.
+  if (ctx.args.projection && !(ctx.args.components && ctx.args.format === "ir")) {
+    console.error(formatError({
+      message: "--projection needs --components --format ir — the CI/pipeline projection extends the component-graph IR, the only mode that carries it.",
+    }));
+    return 1;
+  }
   // `--live` graphs the provisioned (observed) infrastructure, not the declared
   // source (epic #776). It only makes sense as a view format; default to `ir`.
   if (ctx.args.live) {
@@ -281,6 +293,15 @@ async function runComponentGraph(ctx: CommandContext): Promise<number> {
  * the CI pipeline. Distinct from `runGraphView`, which emits the AWS *entity*
  * graph — the component projection has one node per component, not per resource.
  *
+ * `--projection <lexicon>` (#989, `--format ir` only — validated in `runGraph`)
+ * adds the **CI/pipeline projection** alongside this component graph:
+ * `ir.pipeline` carries the stages/jobs/`needs` `<lexicon>`'s
+ * `generateComponentPipeline` synthesizes for `chant build --components
+ * --generate <lexicon>` (`generateComponentsPipeline`, ../../components/cli-support.ts)
+ * — reused wholesale, not re-derived, so a consumer (e.g. behold, epic #492/
+ * INTENTIUS/behold#54) gets the pipeline shape as first-class IR nodes/edges
+ * instead of re-deriving it from `dependsOn` or parsing generated CI YAML.
+ *
  * Lint-gated like the entity view: the DAG stands for deployable source, so we
  * refuse to emit it for source that does not pass lint.
  */
@@ -312,7 +333,7 @@ async function runComponentGraphView(
   const waveOf = new Map<string, number>();
   graph.waves.forEach((wave, i) => wave.forEach((name) => waveOf.set(name, i + 1)));
 
-  const ir: GraphIR = {
+  let ir: GraphIR = {
     nodes: graph.order.map((name) => ({
       id: name,
       kind: "Component",
@@ -327,9 +348,49 @@ async function runComponentGraphView(
     },
   };
 
+  if (ctx.args.projection) {
+    const pipeline = await buildPipelineProjection(projectPath, ctx.args.projection, ctx.args.sandbox);
+    if (!pipeline.success) {
+      console.error(formatError({ message: pipeline.error ?? `Failed to generate ${ctx.args.projection} pipeline projection` }));
+      return 1;
+    }
+    ir = { ...ir, pipeline: pipeline.pipeline };
+  }
+
   return emitIr(ir, ctx, format);
 }
 
+/**
+ * Reshape `generateComponentsPipeline`'s result (../../components/cli-support.ts
+ * — the exact function `chant build --components --generate <lexicon>` calls)
+ * into the IR's `IRPipeline` vocabulary (#989): one `IRPipelineNode` per
+ * generated CI job, one `IRPipelineEdge` per `needs:` dependency (consumer job
+ * → producer job, mirroring the component edges' consumer → producer
+ * direction). Every shape decision — job naming, one stage per wave,
+ * dependency resolution — stays owned by `lexicon`'s `generateComponentPipeline`;
+ * this only relabels its `{ stages, jobs }` output as IR nodes/edges, it never
+ * re-derives the graph.
+ */
+async function buildPipelineProjection(
+  projectPath: string,
+  lexicon: string,
+  sandbox?: boolean,
+): Promise<{ success: true; pipeline: IRPipeline } | { success: false; error?: string }> {
+  const result = await generateComponentsPipeline(projectPath, lexicon, undefined, sandbox);
+  if (!result.success) return { success: false, error: result.error };
+
+  const jobs = result.jobs ?? [];
+  return {
+    success: true,
+    pipeline: {
+      provider: lexicon,
+      stages: result.stages ?? [],
+      nodes: jobs.map((j) => ({ id: j.jobName, kind: "CIJob" as const, component: j.component, stage: j.stage })),
+      edges: jobs.flatMap((j) => j.needs.map((dep) => ({ from: j.jobName, to: dep, kind: "needs" as const }))),
+    },
+  };
+}
+
 /**
  * `chant graph --format ir|mermaid|dot|layout` — build the graph IR (honouring
  * `--detail`) and emit it as JSON, a Mermaid flowchart, Graphviz DOT, or node

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

@@ -1,6 +1,6 @@
 import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
 import { sep } from "node:path";
-import { createMockPlugin, staticDescribeResources, staticObservation, staticListArtifacts } from "@intentius/chant-test-utils";
+import { createMockPlugin, staticDescribeResources, staticObservation, staticDeepObservation, staticListArtifacts } from "@intentius/chant-test-utils";
 import type { LexiconPlugin, ResourceMetadata } from "../../lexicon";
 import type { BuildResult } from "../../build";
 import type { ParsedArgs } from "../registry";
@@ -12,14 +12,22 @@ const readEnvironmentSnapshotsMock = vi.fn();
 const listSnapshotsMock = vi.fn();
 const takeSnapshotMock = vi.fn();
 const loadChantConfigMock = vi.fn();
+const pushLifecycleMock = vi.fn();
+const readBlobFromPathMock = vi.fn();
+const writeBlobToPathMock = vi.fn();
 
 vi.mock("../../build", () => ({ build: (...args: unknown[]) => buildMock(...args) }));
 vi.mock("../../lifecycle/git", () => ({
   fetchLifecycle: () => fetchLifecycleMock(),
+  pushLifecycle: () => pushLifecycleMock(),
   readSnapshot: (...args: unknown[]) => readSnapshotMock(...args),
   readEnvironmentSnapshots: (...args: unknown[]) => readEnvironmentSnapshotsMock(...args),
   listSnapshots: (...args: unknown[]) => listSnapshotsMock(...args),
   snapshotStorageKey: (lexicon: string, stack?: string) => (stack ? `${stack}__${lexicon}` : lexicon),
+  // The accepted-observation baseline (#1014) rides the same orphan-branch
+  // plumbing as the snapshots, so it is mocked at the same seam.
+  readBlobFromPath: (...args: unknown[]) => readBlobFromPathMock(...args),
+  writeBlobToPath: (...args: unknown[]) => writeBlobToPathMock(...args),
 }));
 vi.mock("../../lifecycle/snapshot", () => ({
   takeSnapshot: (...args: unknown[]) => takeSnapshotMock(...args),
@@ -93,6 +101,12 @@ describe("runLifecycleDiff --live", () => {
     readSnapshotMock.mockReset();
     loadChantConfigMock.mockReset();
     loadChantConfigMock.mockResolvedValue({ config: {} });
+    readBlobFromPathMock.mockReset();
+    readBlobFromPathMock.mockResolvedValue(null); // no accepted baseline recorded
+    writeBlobToPathMock.mockReset();
+    writeBlobToPathMock.mockResolvedValue("sha");
+    pushLifecycleMock.mockReset();
+    pushLifecycleMock.mockResolvedValue(true);
   });
 
   test("surfaces drift between previous snapshot and live state", async () => {
@@ -352,6 +366,117 @@ describe("runLifecycleDiff --live", () => {
     expect(output).toContain("added");
   });
 
+  // #1014 — property-level drift, gated purely on the deep capability.
+  describe("deep observation (#1014)", () => {
+    const withDeep = (over: Parameters<typeof createMockPlugin>[0] = {}) =>
+      createMockPlugin({
+        name: "aws",
+        describeResources: staticObservation({ bucket: meta() }),
+        observeResourcesDeep: staticDeepObservation({
+          bucket: {
+            type: "AWS::S3::Bucket",
+            properties: { Versioning: "Suspended", Logging: { Target: "audit" } },
+          },
+        }),
+        ...over,
+      });
+
+    const runDiff = async (plugins: LexiconPlugin[], args: Partial<ParsedArgs> = {}) => {
+      buildMock.mockResolvedValue(makeBuildResult({ aws: ["bucket"] }));
+      // Declared: versioning on, nothing about logging.
+      const build = makeBuildResult({ aws: ["bucket"] });
+      build.entities.set("bucket", {
+        lexicon: "aws",
+        entityType: "AWS::S3::Bucket",
+        props: { Versioning: "Enabled" },
+      } as never);
+      buildMock.mockResolvedValue(build);
+      fetchLifecycleMock.mockResolvedValue(undefined);
+      readSnapshotMock.mockResolvedValue(null);
+      return runLifecycleDiff({
+        args: makeArgs({ command: "state", path: "diff", extraPositional: "prod", live: true, ...args }),
+        plugins,
+        serializers: plugins.map((p) => p.serializer),
+      } as never);
+    };
+
+    test("reports the changed property and the undeclared one", 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");
+    });
+
+    test("a lexicon with no deep reader prints nothing extra", async () => {
+      await runDiff([createMockPlugin({ name: "aws", describeResources: staticObservation({ bucket: meta() }) })]);
+      expect(stdoutBuf.join("\n")).not.toContain("(properties)");
+    });
+
+    test("an accepted deviation in the baseline stops re-alerting", async () => {
+      readBlobFromPathMock.mockResolvedValue(
+        JSON.stringify({
+          baseline: "v1",
+          environment: "prod",
+          lexicons: { aws: { bucket: { accepted: [{ path: "Logging.Target", value: "audit" }] } } },
+        }),
+      );
+      await runDiff([withDeep()]);
+      const output = stdoutBuf.join("\n");
+      expect(output).toContain("Versioning: Enabled → Suspended");
+      expect(output).not.toContain("Logging.Target: <undeclared>");
+      expect(output).toContain("ACCEPTED (in the baseline; not drift)");
+    });
+
+    test("--json carries the property drift 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 }> }> } } };
+      };
+      expect(payload.lexicons.aws.deep.drifted[0].changes.map((c) => c.path).sort()).toEqual([
+        "Logging.Target",
+        "Versioning",
+      ]);
+    });
+
+    test("a deep read that could not look is a hole, not drift", async () => {
+      await runDiff([
+        withDeep({
+          observeResourcesDeep: staticDeepObservation(
+            {},
+            { bucket: { type: "AWS::S3::Bucket", reason: "no-credentials", detail: "token expired" } },
+          ),
+        }),
+      ]);
+      const output = `${stdoutBuf.join("\n")}\n${stderrBuf.join("\n")}`;
+      expect(output).toContain("PROPERTIES UNOBSERVED");
+      expect(output).toContain("no credentials");
+      expect(output).toContain("could not be observed — that part of the estate is unknown, not clean");
+    });
+
+    test("--update-baseline writes what was reported and pushes it", async () => {
+      await runDiff([withDeep()], { updateBaseline: true });
+      expect(writeBlobToPathMock).toHaveBeenCalledTimes(1);
+      const [environment, filename, content] = writeBlobToPathMock.mock.calls[0] as [string, string, string];
+      expect(environment).toBe("prod");
+      expect(filename).toBe("observation-baseline.json");
+      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"]);
+      expect(pushLifecycleMock).toHaveBeenCalled();
+      expect(stderrBuf.join("\n")).toContain("accepted 2 deviation(s)");
+    });
+
+    test("--update-baseline with nothing reported writes nothing", async () => {
+      await runDiff([
+        withDeep({ observeResourcesDeep: staticDeepObservation({}) }),
+      ], { updateBaseline: true });
+      expect(writeBlobToPathMock).not.toHaveBeenCalled();
+      expect(stderrBuf.join("\n")).toContain("nothing to accept");
+    });
+  });
+
   // #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.

package/src/cli/handlers/lifecycle.ts

@@ -1,7 +1,19 @@
 import { resolve } from "node:path";
 import { build } from "../../build";
 import { takeSnapshot } from "../../lifecycle/snapshot";
-import { readSnapshot, readSnapshotAt, readEnvironmentSnapshots, listSnapshots, fetchLifecycle, snapshotStorageKey, StaleLifecycleBranchError } from "../../lifecycle/git";
+import { readSnapshot, readSnapshotAt, readEnvironmentSnapshots, listSnapshots, fetchLifecycle, pushLifecycle, snapshotStorageKey, StaleLifecycleBranchError } from "../../lifecycle/git";
+import { deepDiffForLexicon } from "../../lifecycle/deep-observe";
+import { countPropertyDrift, type DeepDiffResult } from "../../lifecycle/deep-diff";
+import {
+  acceptDeviations,
+  baselineForLexicon,
+  emptyBaseline,
+  readObservationBaseline,
+  writeObservationBaseline,
+  OBSERVATION_BASELINE_FILE,
+  type DeviationToAccept,
+  type ObservationBaseline,
+} 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, gitlabMrReport, summarize, type ChangeSet } from "../../lifecycle/change-set";
@@ -287,6 +299,12 @@ export async function runLifecycleDiff(ctx: CommandContext): Promise<number> {
   let totalChecked = 0;
   let anyBuildError = false;
 
+  // Accepted-deviation baseline (#1014). Read once for the whole run — it is
+  // env-keyed, not stack-keyed, and every deep pass subtracts from the same
+  // committed set. Absent is the normal state (nothing accepted yet).
+  const baseline = args.live ? await readObservationBaseline(environment) : null;
+  const accepted: Record<string, DeviationToAccept[]> = {};
+
   // #1166 — an environment can declare its own endpoint (a local emulator like
   // Floci), so `--live` is self-sufficient even when the ambient shell never
   // exported e.g. AWS_ENDPOINT_URL. Ambient always wins when it's already set.
@@ -324,10 +342,23 @@ export async function runLifecycleDiff(ctx: CommandContext): Promise<number> {
             // no components / discovery failed → single-stack observe path
           }
         }
-        const r = await runLifecycleDiffLive({ environment, lexicons, plugins, buildResult, json, stack: target.stack, componentStacks });
+        const r = await runLifecycleDiffLive({
+          environment,
+          lexicons,
+          plugins,
+          buildResult,
+          json,
+          stack: target.stack,
+          componentStacks,
+          baseline,
+          updateBaseline: args.updateBaseline,
+        });
         totalDrift += r.totalDrift;
         totalUnobserved += r.totalUnobserved;
         totalChecked += r.totalLexiconsChecked;
+        for (const [lexicon, deviations] of Object.entries(r.toAccept)) {
+          (accepted[lexicon] ??= []).push(...deviations);
+        }
         if (json) {
           if (target.stack) perStackJson[target.stack] = r.byLexicon;
           else combinedLexiconsJson = r.byLexicon;
@@ -337,6 +368,13 @@ export async function runLifecycleDiff(ctx: CommandContext): Promise<number> {
       }
     }
 
+    // `--update-baseline` (#1014): record what the deep pass just reported as
+    // accepted, so it stops re-alerting. Runs before the summary lines so the
+    // "no drift" verdict below still describes the run that produced it.
+    if (args.live && args.updateBaseline) {
+      await recordAcceptedBaseline(environment, baseline, accepted, json);
+    }
+
     if (args.live) {
       if (json) {
         // Single-stack keeps the original `{ environment, lexicons }` shape
@@ -372,6 +410,50 @@ export async function runLifecycleDiff(ctx: CommandContext): Promise<number> {
   }
 }
 
+/**
+ * Write the accepted-deviation baseline (#1014) for everything the deep pass
+ * reported this run, and push it on the same orphan branch the snapshots use.
+ *
+ * Acceptance is a deliberate, committed act — that is the whole difference
+ * between this and a suppression flag — so the write is loud: it names the
+ * count and the storage path, and a failed push says so rather than leaving
+ * the operator believing the team's baseline moved.
+ */
+async function recordAcceptedBaseline(
+  environment: string,
+  existing: ObservationBaseline | null,
+  accepted: Record<string, DeviationToAccept[]>,
+  json: boolean,
+): Promise<void> {
+  const total = Object.values(accepted).reduce((n, d) => n + d.length, 0);
+  if (total === 0) {
+    if (!json) {
+      console.error(formatWarning({
+        message: "--update-baseline: nothing to accept — no property-level deviations were reported",
+      }));
+    }
+    return;
+  }
+  let next = existing ?? emptyBaseline(environment);
+  for (const [lexicon, deviations] of Object.entries(accepted)) {
+    next = acceptDeviations(next, lexicon, deviations);
+  }
+  try {
+    await writeObservationBaseline(next);
+    const pushed = await pushLifecycle();
+    if (!json) {
+      console.error(formatSuccess(
+        `--update-baseline: accepted ${total} deviation(s) into ${environment}/${OBSERVATION_BASELINE_FILE} on chant/lifecycle` +
+          (pushed ? " (pushed)" : " (local only — no remote configured or push refused)"),
+      ));
+    }
+  } catch (err) {
+    console.error(formatError({
+      message: `--update-baseline: could not write the baseline — ${err instanceof Error ? err.message : String(err)}`,
+    }));
+  }
+}
+
 interface BetweenDiffArgs {
   environment: string;
   lexiconFilter?: string;
@@ -494,6 +576,10 @@ interface LiveDiffArgs {
    * union (the same fix graph/plan use), else every deployed resource reads as
    * "missing". Empty → the single-stack observe path. */
   componentStacks?: string[];
+  /** Accepted-deviation baseline for this environment (#1014), or null when none is recorded. */
+  baseline: ObservationBaseline | null;
+  /** `--update-baseline`: accept everything the deep pass reports this run. */
+  updateBaseline?: boolean;
 }
 
 interface LiveDiffOutcome {
@@ -504,6 +590,8 @@ interface LiveDiffOutcome {
       observed?: Record<string, ResourceMetadata>;
       /** Declared entities the lexicon could not read (#1089), keyed by name. */
       unobserved?: Record<string, UnobservedEntity>;
+      /** Property-level drift (#1014), present only for lexicons with a deep reader. */
+      deep?: DeepDiffResult;
       artifacts?: LiveArtifactDiffResult;
     }
   >;
@@ -511,6 +599,8 @@ interface LiveDiffOutcome {
   /** Declared entities nobody could read. Not drift — a hole in the report. */
   totalUnobserved: number;
   totalLexiconsChecked: number;
+  /** Deviations `--update-baseline` should record, per lexicon. */
+  toAccept: Record<string, DeviationToAccept[]>;
 }
 
 /**
@@ -576,6 +666,7 @@ async function runLifecycleDiffLive(args: LiveDiffArgs): Promise<LiveDiffOutcome
   let totalUnobserved = 0;
   let totalLexiconsChecked = 0;
   const byLexicon: LiveDiffOutcome["byLexicon"] = {};
+  const toAccept: Record<string, DeviationToAccept[]> = {};
   if (!args.json && args.stack) console.log(`\n${formatBold(`■ stack ${args.stack}`)}`);
 
   for (const lexiconName of args.lexicons) {
@@ -644,6 +735,27 @@ async function runLifecycleDiffLive(args: LiveDiffArgs): Promise<LiveDiffOutcome
         if (Object.keys(observed.unobserved).length > 0) entry.unobserved = observed.unobserved;
       } else renderLiveDiff(lexiconName, args.environment, diff);
       lexiconChecked = true;
+
+      // ── Deep path (property-level, #1014) ───────────────────────────────
+      // Gated purely on the capability: a lexicon without a deep reader is
+      // completely unaffected, including its output.
+      if (plugin.observeResourcesDeep) {
+        const deep = await deepDiffForLexicon(plugin, {
+          environment: args.environment,
+          buildOutput,
+          entities,
+          stack: args.stack,
+          componentStacks: args.componentStacks,
+          baseline: baselineForLexicon(args.baseline, lexiconName),
+        });
+        totalDrift += countPropertyDrift(deep);
+        // Only count a deep hole for an entity the thin read *did* resolve —
+        // 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);
+      }
     }
 
     // ── Artifacts path (context-keyed) ─────────────────────────────────────
@@ -668,7 +780,76 @@ async function runLifecycleDiffLive(args: LiveDiffArgs): Promise<LiveDiffOutcome
     if (lexiconChecked) totalLexiconsChecked++;
   }
 
-  return { byLexicon, totalDrift, totalUnobserved, totalLexiconsChecked };
+  return { byLexicon, totalDrift, totalUnobserved, totalLexiconsChecked, toAccept };
+}
+
+/**
+ * Everything a deep diff reported this run, as deviations to record accepted.
+ * `--update-baseline` accepts what was *reported*, never what was already
+ * suppressed — re-accepting an unchanged suppression would rewrite its
+ * `recordedAt` on every run and turn the baseline into a churn file.
+ */
+function deviationsToAccept(deep: DeepDiffResult): DeviationToAccept[] {
+  const out: DeviationToAccept[] = [];
+  for (const entity of deep.drifted) {
+    for (const change of entity.changes) {
+      // Only a value that is actually live can be accepted: `absent` means the
+      // cloud does not carry the declared property, which is a finding to fix
+      // in source or in the cloud, not a value to bless.
+      if (!("live" in change)) continue;
+      out.push({ entity: entity.name, type: entity.type, path: change.path, value: change.live });
+    }
+  }
+  return out;
+}
+
+/** Property-level drift report (#1014). Silent when a lexicon's deep read found nothing to say. */
+function renderDeepDiff(lexiconName: string, deep: DeepDiffResult): void {
+  const drift = countPropertyDrift(deep);
+  if (
+    drift === 0 &&
+    deep.accepted.length === 0 &&
+    deep.unobserved.length === 0 &&
+    deep.undeclaredEntities.length === 0
+  ) {
+    return;
+  }
+
+  const acceptedCount = deep.accepted.reduce((n, e) => n + e.changes.length, 0);
+  console.log(`\n${formatBold(`${lexiconName} (properties)`)}`);
+  console.log(
+    `${drift} property drift across ${deep.drifted.length} resource(s), ` +
+      `${acceptedCount} accepted, ${deep.unchanged.length} unchanged` +
+      (deep.unobserved.length > 0 ? `, ${deep.unobserved.length} unobserved` : ""),
+  );
+  console.log("-".repeat(80));
+
+  if (deep.unobserved.length > 0) {
+    console.log(formatBold("\nPROPERTIES UNOBSERVED (declared; the deep read could not look):"));
+    for (const u of deep.unobserved) console.log(`  ? ${formatUnobserved(u.name, u)}`);
+  }
+  if (deep.drifted.length > 0) {
+    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})`);
+      for (const change of entity.changes) {
+        const declared = "declared" in change ? formatValue(change.declared) : "<undeclared>";
+        const live = "live" in change ? formatValue(change.live) : "<absent>";
+        const baseline = "baseline" in change ? ` [accepted: ${formatValue(change.baseline)}]` : "";
+        console.log(`      ${change.path}: ${declared} → ${live}${baseline}`);
+      }
+    }
+  }
+  if (deep.undeclaredEntities.length > 0) {
+    console.log(formatBold("\nUNDECLARED (read deeply, never declared in source):"));
+    for (const name of deep.undeclaredEntities) console.log(`  - ${name}`);
+  }
+  if (acceptedCount > 0) {
+    console.log(formatBold("\nACCEPTED (in the baseline; not drift):"));
+    for (const entity of deep.accepted) {
+      console.log(`  - ${entity.name}: ${entity.changes.map((c) => c.path).join(", ")}`);
+    }
+  }
 }
 
 function renderLiveDiff(lexiconName: string, environment: string, diff: LiveDiffResult): void {

package/src/cli/main.test.ts

@@ -95,6 +95,12 @@ describe("parseArgs", () => {
     expect(result.down).toBe(true);
   });
 
+  test("parses graph --components --format ir --projection <lexicon>", () => {
+    const result = parseArgs(["graph", "--components", "--format", "ir", "--projection", "gitlab"]);
+    expect(result.components).toBe(true);
+    expect(result.projection).toBe("gitlab");
+  });
+
   test("combines multiple options", () => {
     const result = parseArgs([
       "build",

package/src/cli/main.ts

@@ -64,6 +64,7 @@ const BOOLEAN_FLAGS = new Set([
   "--json",
   "--progress-json",
   "--update-snapshot",
+  "--update-baseline",
   "--run-examples",
   "--check",
   "--bump",
@@ -269,6 +270,8 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.progressJson = true;
     } else if (arg === "--update-snapshot") {
       result.updateSnapshot = true;
+    } else if (arg === "--update-baseline") {
+      result.updateBaseline = true;
     } else if (arg === "--run-examples") {
       result.runExamples = true;
     } else if (arg === "--pinned-digest") {
@@ -312,6 +315,8 @@ export function parseArgs(args: string[]): ParsedArgs {
       (result.param ??= []).push(args[++i]);
     } else if (arg === "--params-file") {
       result.paramsFile = args[++i];
+    } else if (arg === "--projection") {
+      result.projection = args[++i];
     } else if (arg.startsWith("--")) {
       // chant #1127 — every recognized flag is matched above; anything left
       // starting with `--` is unrecognized, whether it arrived bare
@@ -421,12 +426,19 @@ Ops:
                         --layout-engine graphviz to use dot instead;
                         --detail 0..3: stacks|composites|declarables|attributes;
                         --lens lexicon:<n>|stack:<n>|blast:<node> (--up/--down))
+                        --components --format ir --projection gitlab|github|forgejo:
+                        add the CI/pipeline projection (stages/jobs/needs) to
+                        the component-graph IR, from the same generator
+                        'build --components --generate' uses (#989)
 
 Lifecycle (alias: lc):
   lifecycle snapshot <env>  Query API, save metadata to orphan branch
   lifecycle show <env>      Show latest lifecycle snapshot
   lifecycle diff <env>      Compare current build against last snapshot
                             --live: query cloud now and detect drift
+                            (lexicons with a deep reader also report
+                            property-level drift; --update-baseline records
+                            what it reports as accepted so it stops alerting)
   lifecycle plan <env>      Typed change set (create/update/delete/adopt) vs live
   lifecycle affected        Stacks a change affects (--base <ref> [--include-dependents])
                             --json: emit the ChangeSet as JSON

package/src/cli/registry.ts

@@ -118,6 +118,14 @@ export interface ParsedArgs {
   theme?: string;
   /** `chant dev surface-diff --update-snapshot` — write the fresh snapshot as the new baseline */
   updateSnapshot?: boolean;
+  /**
+   * `chant lifecycle diff <env> --live --update-baseline` (#1014) — record every
+   * property-level deviation this run reports as *accepted*, so it stops
+   * re-alerting. Value-bound: a later change to the accepted value is drift
+   * again. Writes `<env>/observation-baseline.json` on the chant/lifecycle
+   * orphan branch; never touches the cloud.
+   */
+  updateBaseline?: boolean;
   /** `chant dev surface-diff --run-examples` — also run the example build harness */
   runExamples?: boolean;
   /** `chant dev surface-diff --pinned-digest <file>` — path to SHA-256 digest file for supply-chain verification */
@@ -154,6 +162,12 @@ export interface ParsedArgs {
   param?: string[];
   /** `chant build --params-file <path>` (#1064) — a JSON file of `{ "name": value }` build-time parameter values. Second precedence, after `--param`. */
   paramsFile?: string;
+  /** `chant graph --components --format ir --projection <lexicon>` (#989) — add
+   * the CI/pipeline projection (stages/jobs/`needs`) to the component-graph IR,
+   * synthesized by `<lexicon>`'s `generateComponentPipeline` (gitlab, github,
+   * forgejo today) — the same generator `chant build --components --generate
+   * <lexicon>` uses, reused rather than re-derived. */
+  projection?: string;
 }
 
 /**

package/src/codegen/generate.ts

@@ -27,6 +27,15 @@ export interface GenerateResult {
   properties: number;
   enums: number;
   warnings: Array<{ file: string; error: string }>;
+  /**
+   * Additional generated files, keyed by filename, produced by the optional
+   * {@link GeneratePipelineConfig.generateExtraArtifacts} hook. They come out
+   * of the same parse a lexicon's types and registry come out of, which is the
+   * point: an artifact derived here cannot drift from the types, the way a
+   * hand-maintained table beside them can (chant #1074's operation surface is
+   * the first of these).
+   */
+  extraArtifacts?: Record<string, string>;
 }
 
 /**
@@ -68,6 +77,14 @@ export interface GeneratePipelineConfig<T extends ParsedResult> {
   /** Generate runtime index with factory exports. */
   generateRuntimeIndex: (results: T[], naming: NamingStrategy) => string;
 
+  /**
+   * Optional extra artifacts from the same parsed results — filename → content.
+   * Used when a lexicon needs a second derived table alongside the registry and
+   * the types, and needs it to come from the same pass so the three cannot
+   * skew.
+   */
+  generateExtraArtifacts?: (results: T[], naming: NamingStrategy) => Record<string, string>;
+
   /** Optional pre-parse hook (patches, overlays, extra resources, etc.). */
   augmentSchemas?: (
     schemas: Map<string, Buffer>,
@@ -161,6 +178,13 @@ export async function generatePipeline<T extends ParsedResult>(
   log("Generating runtime index...");
   const indexTS = config.generateRuntimeIndex(results, naming);
 
+  let extraArtifacts: Record<string, string> | undefined;
+  if (config.generateExtraArtifacts) {
+    log("Generating extra artifacts...");
+    extraArtifacts = config.generateExtraArtifacts(results, naming);
+    log(`Generated ${Object.keys(extraArtifacts).length} extra artifact(s)`);
+  }
+
   // Count stats
   let resourceCount = 0;
   let propertyCount = 0;
@@ -179,6 +203,7 @@ export async function generatePipeline<T extends ParsedResult>(
     properties: propertyCount,
     enums: enumCount,
     warnings,
+    ...(extraArtifacts ? { extraArtifacts } : {}),
   };
 }