@intentius/chant 0.117.0 → 0.118.1

package/dist/op/op-waves.d.ts

@@ -27,6 +27,12 @@
  * the same digest a component fan-out's wave binds). Whether it waits at all
  * is the wave's gate policy, read from the base commit's copy of the spec
  * file, so a change cannot loosen the rule that gates its own merge.
+ *
+ * So is which approvals count (#3684), the wave's `approval`: `ledger` (any
+ * `chant approve` of the digest), `sealed` (only one whose seal verifies
+ * against the signers file at base) or `pr-review` (also the merged pull
+ * request's review of its head, by a writer other than its author, when the
+ * head planned the same digest). See `./gate-review.ts`.
  */
 import type { OpEnvironment, OpSetupStep } from "../lexicon.js";
 /** When a wave waits for an approval. */
@@ -38,6 +44,15 @@ export type OpWaveGatePolicy =
 /** Never: only review and branch protection stand in front of the wave. */
  | "never";
 export declare const OP_WAVE_GATE_POLICIES: readonly OpWaveGatePolicy[];
+/** Which approvals of a gate's digest count (#3684). See `./gate-review.ts`. */
+export type GateApprovalSource = 
+/** Any resolution on `chant/lifecycle` that names the digest. */
+"ledger"
+/** As `ledger`, and the merged pull request's review of its head, by a writer other than its author. */
+ | "pr-review"
+/** Only a resolution sealed by a key the signers file at base lists for its approver. */
+ | "sealed";
+export declare const GATE_APPROVAL_SOURCES: readonly GateApprovalSource[];
 /** One Op run in a wave: an Op applied to one target (an environment, a database, a tenant). */
 export interface OpWaveRun {
     /** What the run applies to. Unique within its wave; it names the run in the set digest. */
@@ -55,6 +70,11 @@ export interface OpWave {
      * spec file at the base commit, never from the change being applied.
      */
     gate?: OpWaveGatePolicy;
+    /**
+     * Which approvals of the wave's digest count (#3684). Default `"ledger"`.
+     * Like `gate`, the runner reads it from the spec file at the base commit.
+     */
+    approval?: GateApprovalSource;
     /**
      * Split the wave into a deciding job and this many share jobs, each
      * applying a slice of the runs. Default 1: one job plans, decides and

package/dist/op/op-waves.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.117.0",
+  "version": "0.118.1",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/build.ts

@@ -19,6 +19,7 @@ import { discover, type DiscoveryResult, type FoldDecision } from "./discovery/i
 import { decodeEntitySet, type DiscoveredEntitiesJson } from "./discovery/entity-wire";
 import { buildDependencyGraph } from "./discovery/graph";
 import { topologicalSort } from "./sort";
+import { statSync } from "node:fs";
 import { resolve } from "node:path";
 
 /**
@@ -641,6 +642,15 @@ function generateManifest(
   };
 }
 
+/** The directory a build discovered from, for build-root contributors; undefined when the build's path is not one (an entity-set JSON's label). */
+function sourceDirOf(path: string): string | undefined {
+  try {
+    return statSync(path).isDirectory() ? resolve(path) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /** What merging build-root contributions produced: non-fatal render notes and
  * fatal messages (a failed contributor, a name collision). */
 export interface BuildRootMergeResult {
@@ -667,6 +677,7 @@ export interface BuildRootMergeResult {
 export async function mergeBuildRootEntities(
   entities: Map<string, Declarable>,
   contributors: ReadonlyArray<BuildRootContributor>,
+  sourceDir?: string,
 ): Promise<BuildRootMergeResult> {
   const warnings: string[] = [];
   const errors: string[] = [];
@@ -677,7 +688,7 @@ export async function mergeBuildRootEntities(
       // ciphertext file to resolve). Contributors run in order, so this also
       // carries what earlier contributors added; the merge below is still the
       // only writer, which is what keeps the collision refusal meaningful.
-      const contribution = await contribute({ entities });
+      const contribution = await contribute({ entities, ...(sourceDir !== undefined ? { sourceDir } : {}) });
       warnings.push(...(contribution.warnings ?? []));
       for (const [name, entity] of contribution.entities) {
         if (entities.has(name)) {
@@ -809,7 +820,7 @@ async function buildFromDiscoveryResult(
   // object, and re-running the contributors there would duplicate every
   // contributed entity once per child.
   if (!parentBuildStack && options?.buildRoots) {
-    const merged = await mergeBuildRootEntities(discoveryResult.entities, options.buildRoots);
+    const merged = await mergeBuildRootEntities(discoveryResult.entities, options.buildRoots, sourceDirOf(resolvedPathForChildStack));
     warnings.push(...merged.warnings);
     for (const message of merged.errors) {
       errors.push(new BuildErrorClass("", message));

package/src/cli/commands/build.ts

@@ -922,7 +922,8 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
   const resourceCount = result.entities.size;
   const fileCount = result.sourceFileCount;
 
-  if (fileCount === 0 && errors.length === 0) {
+  // A build root (a lexicon's own source files, a rendered overlay) can declare everything without one .ts file.
+  if (fileCount === 0 && resourceCount === 0 && errors.length === 0) {
     console.error(formatInfo("No source files found — create .ts files in the target directory"));
   }
 

package/src/cli/handlers/run-wave.ts

@@ -5,13 +5,25 @@
 
 import { readFileSync } from "node:fs";
 import { relative, resolve } from "node:path";
-import { parseOpWavesSpec, runOpWave } from "../../op/op-waves-run";
+import { parseOpWavesSpec, recordOpWaveHeadPlans, runOpWave } from "../../op/op-waves-run";
 import { formatError } from "../format";
 import type { CommandContext } from "../registry";
 
 export async function runOpWaveCommand(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
   const specFile = args.opsSpec;
+  if (specFile && args.recordPlans) {
+    try {
+      const spec = parseOpWavesSpec(readFileSync(resolve(specFile), "utf-8"), `--spec ${specFile}`);
+      const plans = await recordOpWaveHeadPlans({ spec });
+      if (args.json) console.log(JSON.stringify(plans, null, 2));
+      else for (const w of plans.waves) console.error(`wave ${w.wave} (${w.name}) at ${plans.head.slice(0, 12)}: ${w.digest}`);
+      return 0;
+    } catch (err) {
+      console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+      return 1;
+    }
+  }
   if (!specFile || args.wave === undefined) {
     console.error(formatError({
       message: "`chant run wave` needs --spec <file> and --wave <k>",

package/src/cli/main.ts

@@ -108,6 +108,7 @@ const BOOLEAN_FLAGS = new Set([
   "--root-only",
   "--generated",
   "--decide",
+  "--record-plans",
 ]);
 
 /**
@@ -359,6 +360,8 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.wave = wave;
     } else if (arg === "--decide") {
       result.decide = true;
+    } else if (arg === "--record-plans") {
+      result.recordPlans = true;
     } else if (arg === "--share") {
       const raw = args[++i];
       const share = Number(raw);
@@ -925,7 +928,10 @@ Ops:
   run wave --spec <file> --wave <k>  Plan, gate and apply wave k of an Op
                         waves spec (#3679): the job a generated waves
                         pipeline runs. --decide plans and decides only;
-                        --share <i> applies one share of a decided wave
+                        --share <i> applies one share of a decided wave.
+                        --record-plans (no --wave), in a pull request's
+                        pipeline: plan every wave at its head and record the
+                        digests a pr-review approval mode compares
   run resume [--op <name>]  Start again each CI job that waits at a gate an
                         approval now answers, through the forge's API
                         (#3683); approves nothing. --dry-run lists them

package/src/cli/plugins.ts

@@ -211,7 +211,7 @@ export function collectBuildRootContributors(
     .filter((plugin) => typeof plugin.buildRoots === "function")
     // `entities` is not bindable here — discovery has not run — so the merge
     // hands it in when it calls the closure (#1828 / SOPS provenance).
-    .map((plugin): import("../lexicon").BuildRootContributor => (ctx) => plugin.buildRoots!({ projectRoot, config, entities: ctx?.entities }));
+    .map((plugin): import("../lexicon").BuildRootContributor => (ctx) => plugin.buildRoots!({ projectRoot, config, entities: ctx?.entities, ...(ctx?.sourceDir !== undefined ? { sourceDir: ctx.sourceDir } : {}) }));
   return [...codegen, ...roots];
 }
 

package/src/cli/registry.ts

@@ -252,6 +252,8 @@ export interface ParsedArgs {
   wave?: number;
   /** `chant run wave --decide` (#3679) — plan a wide wave and decide its gate, applying nothing. */
   decide?: boolean;
+  /** `chant run wave --record-plans` (#3684) — plan every wave at a pull request's head and record the digests for a `pr-review` gate. */
+  recordPlans?: boolean;
   /** `chant run wave --share <i>` (#3679) — apply share `i` of a decided wide wave. */
   share?: number;
   /** `chant components fan-out --canary <component>` (#3049), repeatable — components that form wave 1. */

package/src/discovery/files.ts

@@ -116,3 +116,21 @@ export async function findInfraFiles(path: string, options?: FindInfraFilesOptio
     accept: (name, full) => isSourceFileName(name) && !hasDiscoveryMarkerSync(full),
   });
 }
+
+/**
+ * Find the files under `path` that `accept` wants, through the same walk and
+ * the same project globs as {@link findInfraFiles}: a lexicon that reads
+ * source of its own beside the TypeScript (the sql lexicon's `.sql` files)
+ * sees exactly the tree source discovery sees, so `dist`, git-ignored paths,
+ * child projects and the project's `exclude` globs are left out for it too.
+ */
+export async function findSourceFiles(path: string, accept: (name: string, full: string) => boolean, options?: FindInfraFilesOptions): Promise<string[]> {
+  const globs = options?.globs === null ? undefined : (options?.globs ?? (await resolveDiscoveryGlobs(path)));
+  return walkDiscovery({
+    walker: "source",
+    root: path,
+    globs,
+    excludeDirs: await workspaceMemberDirs(path),
+    accept,
+  });
+}

package/src/lexicon.ts

@@ -984,6 +984,15 @@ export interface BuildRootContext {
    * treat an absent map as an empty one.
    */
   entities?: ReadonlyMap<string, Declarable>;
+  /**
+   * The directory this build discovered its source in (the path handed to
+   * `build()`, which `--src` or `sourceDir` chose), absolute. A contributor
+   * that reads files beside the typed source (the sql lexicon's `.sql`
+   * files) reads them here, so it sees the tree discovery saw. Optional: a
+   * caller that is not a build (the graph paths) omits it, and a hook then
+   * falls back to `sourceDir` in `config`, resolved against `projectRoot`.
+   */
+  sourceDir?: string;
 }
 
 /**
@@ -1003,7 +1012,7 @@ export interface BuildRootContribution {
  * the argument is still assignable, which is what every pre-#1828 hook does.
  */
 export type BuildRootContributor = (
-  ctx: Pick<BuildRootContext, "entities">,
+  ctx: Pick<BuildRootContext, "entities" | "sourceDir">,
 ) => Promise<BuildRootContribution>;
 
 /**

package/src/lifecycle/gate-ledger.ts

@@ -222,6 +222,13 @@ export interface GateResolutionRecord {
    * verifies. Absent on an unsigned approval.
    */
   seal?: GateApprovalSeal;
+  /**
+   * The forge review this approval came from (#3684): a wave whose approval
+   * mode is `pr-review` writes it when the merged pull request's head was
+   * approved by a writer other than its author and planned this digest.
+   * `resolvedBy` is the first of `approvers`.
+   */
+  review?: { pr: number; head: string; approvers: string[] };
   /**
    * The answer record that passed the gate, on a gate that asks a decision
    * point (#3170). The run writes this resolution itself when the point's

package/src/op/activities/lifecycle-gate.test.ts

@@ -0,0 +1,147 @@
+/**
+ * #3712: a `chant lifecycle diff` that fails yields no digest, so an approval
+ * cannot pass a gate for a plan nobody read.
+ *
+ * Before the fix the activity caught the diff's non-zero exit and digested
+ * its error output. Every run whose build failed printed the same lines, so
+ * an approval of one such run's digest matched the next, whatever the
+ * declarations had become, and the Apply phase (which builds on its own)
+ * applied the change.
+ */
+
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+/** What the next `chant lifecycle diff` prints and how it exits. */
+const next = { stdout: "", stderr: "", code: 0 };
+
+vi.mock(import("node:child_process"), async (importOriginal) => ({
+  ...(await importOriginal()),
+  exec: ((_command: string, _options: unknown, callback: (err: unknown, out?: { stdout: string; stderr: string }) => void) => {
+    if (next.code === 0) callback(null, { stdout: next.stdout, stderr: next.stderr });
+    else callback(Object.assign(new Error("exit"), { code: next.code, stdout: next.stdout, stderr: next.stderr }));
+  }) as never,
+}));
+
+const { lifecycleDiff, lifecycleDiffDigest } = await import("./lifecycle");
+const { OpRunFailure, runOpLocally } = await import("../local-executor");
+const { stepOutput } = await import("../step-output-ref");
+type ActivityFn = import("../activity-registry").ActivityFn;
+type ActivityProfile = import("../activity-registry").ActivityProfile;
+type GateLedgerPort = import("../gate").GateLedgerPort;
+type GateResolutionRecord = import("../../lifecycle/gate-ledger").GateResolutionRecord;
+type PendingGateRecord = import("../../lifecycle/gate-ledger").PendingGateRecord;
+type OpConfig = import("../types").OpConfig;
+
+const PROFILES: Record<string, ActivityProfile> = {
+  fastIdempotent: { timeout: "5m", retry: { maximumAttempts: 1 } },
+};
+
+const BUILD_FAILED = "error: Build failed for project — fix errors before diffing";
+const ARGS = { env: "dev", live: true };
+
+function failDiff(): void {
+  Object.assign(next, { stdout: "", stderr: BUILD_FAILED, code: 1 });
+}
+
+function diffPrints(render: string): void {
+  Object.assign(next, { stdout: render, stderr: "", code: 0 });
+}
+
+beforeEach(() => {
+  diffPrints("");
+  vi.spyOn(console, "log").mockImplementation(() => undefined);
+  vi.spyOn(console, "error").mockImplementation(() => undefined);
+});
+
+describe("lifecycleDiff on a failed diff (#3712)", () => {
+  test("a build error rejects, naming the command and the error, with no digest", async () => {
+    failDiff();
+    await expect(lifecycleDiff(ARGS)).rejects.toThrow(/chant lifecycle diff dev --live failed \(exit 1\); no plan to digest:\n.*Build failed for project/);
+  });
+
+  test("a diff that succeeds still returns its digest", async () => {
+    diffPrints("MISSING (declared, provider reports not in cloud):\n  - events");
+    const result = await lifecycleDiff(ARGS);
+    expect(result.exitCode).toBe(0);
+    expect(result.drifted).toBe(true);
+    expect(result.planDigest).toBe(lifecycleDiffDigest(ARGS, "MISSING (declared, provider reports not in cloud):\n  - events"));
+  });
+});
+
+describe("ApplyOp's gate over a diff whose build fails (#3712)", () => {
+  function ledger(): GateLedgerPort & { approve(planDigest: string): void } {
+    const resolutions: GateResolutionRecord[] = [];
+    const pending: PendingGateRecord[] = [];
+    return {
+      approve(planDigest) {
+        resolutions.push({ version: 1, op: "apply-dev", gate: "approve-apply-dev", resolvedBy: "alex", timestamp: "2026-10-10T12:05:00.000Z", planDigest });
+      },
+      async read() {
+        return { resolutions: [...resolutions], pending: [...pending] };
+      },
+      async appendPending(input) {
+        const record: PendingGateRecord = { version: 1, kind: "pending", ...input };
+        pending.push(record);
+        return { record, pushed: true };
+      },
+    };
+  }
+
+  const statuses = (failure: unknown) =>
+    (failure as InstanceType<typeof OpRunFailure>).result.records.map((r) => [r.fn, r.status]);
+
+  /** ApplyOp's Plan, Approve and Apply phases, with the real `lifecycleDiff` and an apply that records what it applied. */
+  function harness() {
+    const declared = { schema: "A" };
+    const applied: string[] = [];
+    const activities = new Map<string, ActivityFn>([
+      ["lifecycleDiff", (args, signal) => lifecycleDiff(args as { env: string; live?: boolean }, signal)],
+      ["nativeApply", async () => {
+        applied.push(declared.schema);
+      }],
+    ]);
+    const config: OpConfig = {
+      name: "apply-dev",
+      overview: "",
+      phases: [
+        { name: "Plan", steps: [{ kind: "activity", fn: "lifecycleDiff", id: "plan", args: ARGS }] },
+        { name: "Approve", steps: [{ kind: "gate", gate: "approve-apply-dev", plan: stepOutput("plan", "planDigest") }] },
+        { name: "Apply", steps: [{ kind: "activity", fn: "nativeApply" }] },
+      ],
+    };
+    return { declared, applied, activities, config };
+  }
+
+  test("an approval of plan A does not pass for plan B when the diff's build fails both times", async () => {
+    const { declared, applied, activities, config } = harness();
+    const gates = ledger();
+
+    // Plan A: the diff's build fails. The run stops at Plan: nothing reaches the gate.
+    failDiff();
+    const first = await runOpLocally(config, activities, PROFILES, undefined, { gates, now: "2026-10-10T12:00:00.000Z" }).catch((e: unknown) => e);
+    expect(first).toBeInstanceOf(OpRunFailure);
+    expect(statuses(first)).toEqual([["lifecycleDiff", "fail"]]);
+    expect(applied).toEqual([]);
+
+    // The digest the diff's error output used to give: someone approves it.
+    gates.approve(lifecycleDiffDigest(ARGS, BUILD_FAILED));
+
+    // Plan B: the declarations change, and the diff's build still fails.
+    declared.schema = "B";
+    const second = await runOpLocally(config, activities, PROFILES, undefined, { gates, now: "2026-10-10T12:10:00.000Z" }).catch((e: unknown) => e);
+    expect(second).toBeInstanceOf(OpRunFailure);
+    expect(statuses(second)).toEqual([["lifecycleDiff", "fail"]]);
+    expect(applied).toEqual([]);
+  });
+
+  test("with the build fixed, the run stops at the gate for the plan it read", async () => {
+    const { applied, activities, config } = harness();
+    const gates = ledger();
+    const render = "MISSING (declared, provider reports not in cloud):\n  - events";
+    diffPrints(render);
+    const run = await runOpLocally(config, activities, PROFILES, undefined, { gates, now: "2026-10-10T12:00:00.000Z" });
+    expect(run.status).toBe("gated");
+    expect(run.gate?.planDigest).toBe(lifecycleDiffDigest(ARGS, render));
+    expect(applied).toEqual([]);
+  });
+});

package/src/op/activities/lifecycle.ts

@@ -32,7 +32,7 @@ export interface LifecycleDiffArgs {
 export interface LifecycleDiffResult {
   /** Combined stdout + stderr from the chant command. */
   output: string;
-  /** Process exit code (0 = success). */
+  /** Process exit code: always 0, since a diff that exits non-zero throws (#3712). */
   exitCode: number;
   /**
    * True when the diff output contains any drift indicators
@@ -121,18 +121,27 @@ export function lifecycleDiffDigest(args: LifecycleDiffArgs, output: string): st
  * MISSING / ORPHAN / DRIFTED / DISAPPEARED / PROPERTY DRIFT section headers documented in
  * cli/state.mdx. Pair with `outcomeAttribute: { name: "Drift", from: "drifted" }`
  * on a WatchOp activity step to surface drift as the run's `Drift` outcome.
+ *
+ * A diff that exits non-zero (#3712) fails the step and yields no digest.
+ * Its output is an error, not a change set: every failed run printed the
+ * same lines, so a digest over them was one an approval matched whatever
+ * the declarations had become since.
  */
 export async function lifecycleDiff(args: LifecycleDiffArgs, signal?: AbortSignal): Promise<LifecycleDiffResult> {
   const liveFlag = args.live ? " --live" : "";
+  const command = `chant lifecycle diff ${args.env}${liveFlag}`;
+  let stdout: string;
+  let stderr: string;
   try {
-    const { stdout, stderr } = await execAsync(`chant lifecycle diff ${args.env}${liveFlag}`, { signal });
-    const output = `${stdout}${stderr}`.trim();
-    if (output) console.log(output);
-    return { output, exitCode: 0, drifted: detectDrift(output), planDigest: lifecycleDiffDigest(args, output) };
+    ({ stdout, stderr } = await execAsync(command, { signal }));
   } catch (err) {
     const e = err as { code?: number; stdout?: string; stderr?: string };
     const output = `${e.stdout ?? ""}${e.stderr ?? ""}`.trim();
     if (output) console.error(output);
-    return { output, exitCode: e.code ?? 1, drifted: detectDrift(output), planDigest: lifecycleDiffDigest(args, output) };
+    const message = `${command} failed (exit ${String(e.code ?? 1)}); no plan to digest${output ? `:\n${output}` : ""}`;
+    throw new Error(message);
   }
+  const output = `${stdout}${stderr}`.trim();
+  if (output) console.log(output);
+  return { output, exitCode: 0, drifted: detectDrift(output), planDigest: lifecycleDiffDigest(args, output) };
 }