@intentius/chant 0.124.1 → 0.124.3

package/src/op/op-waves.test.ts

@@ -663,3 +663,99 @@ describe("apply-stage hooks run by the apply, under its lock (#3804)", () => {
     h.done();
   });
 });
+
+describe("a product's wave gate moved onto the waves (#3821)", () => {
+  const digest = (n: string) => `sha256:${n.repeat(64)}`;
+  const tg: OpWavesSpec = {
+    name: "tf-apply",
+    op: "tf-apply",
+    gateName: "wave-{k}",
+    digest: { over: "changing" },
+    planWave: ["tg", "plan", "{wave}", "{runs}", "{plans}"],
+    applyWave: ["tg", "apply", "{wave}", "{runs}", "{plans}"],
+    waves: [{ name: "net", runs: [{ target: "vpc" }, { target: "dns" }, { target: "nat" }] }],
+  };
+  function harness(plans: Record<string, { planDigest: string; empty?: boolean }>, extra: Record<string, unknown> = {}, atBase: OpWavesSpec = tg) {
+    const cwd = mkdtempSync(join(tmpdir(), "op-waves-3821-"));
+    const calls: string[] = [];
+    const exec: OpWaveExec = (argv, dir) => {
+      calls.push(argv.join(" "));
+      const runs = JSON.parse(readFileSync(join(dir, argv[3]!), "utf-8")) as OpWaveRunsFile;
+      if (argv[1] === "plan") writeFileSync(join(dir, argv[4]!), JSON.stringify({ runs: runs.runs.map((r) => ({ target: r.target, ...plans[r.target] })), ...extra }));
+      return 0;
+    };
+    const show: OpWaveShowAtBase = () => ({ sha: "b".repeat(40), text: JSON.stringify(atBase) });
+    return { cwd, calls, exec, show, done: () => rmSync(cwd, { recursive: true, force: true }) };
+  }
+
+  test("the spec checks gateName, digest and neverOverMcp", () => {
+    expect(() => assertOpWavesSpec(tg)).not.toThrow();
+    expect(() => assertOpWavesSpec({ ...tg, gateName: "wave" })).toThrow(/pattern with \{k\}/);
+    expect(() => assertOpWavesSpec({ ...tg, gateName: "{op}-{k}" })).toThrow(/names \{op\}/);
+    expect(() => assertOpWavesSpec({ ...tg, digest: { over: "some" as "all" } })).toThrow(/digest.over/);
+    expect(() => assertOpWavesSpec({ ...tg, neverOverMcp: "yes" as unknown as boolean })).toThrow(/neverOverMcp/);
+  });
+
+  test("the gate keeps the product's name, and the digest covers only the runs that change something", async () => {
+    const plans = { vpc: { planDigest: digest("1") }, dns: { planDigest: digest("2"), empty: true }, nat: { planDigest: digest("3") } };
+    const h = harness(plans);
+    const gates = memoryGateLedgerPort();
+    const result = await runOpWave({ spec: tg, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates });
+    const changing = waveSetDigest([{ member: "vpc", planDigest: digest("1") }, { member: "nat", planDigest: digest("3") }]);
+    expect(result).toMatchObject({ exitCode: 3, decision: { gate: "wave-1", digest: changing, digestOver: "changing", status: "waiting" } });
+    expect(gates.appended[0]).toMatchObject({ op: "tf-apply", gate: "wave-1", planDigest: changing });
+    h.done();
+  });
+
+  test("an approval a product recorded for its gate and digest before the move lets the wave apply", async () => {
+    const plans = { vpc: { planDigest: digest("1") }, dns: { planDigest: digest("2"), empty: true }, nat: { planDigest: digest("3") } };
+    const h = harness(plans);
+    const changing = waveSetDigest([{ member: "vpc", planDigest: digest("1") }, { member: "nat", planDigest: digest("3") }]);
+    const gates = memoryGateLedgerPort({
+      pending: [{ version: 1, kind: "pending", op: "tf-apply", gate: "wave-1", timestamp: "2026-10-10T00:00:00Z", expiresAt: "2026-10-12T00:00:00Z", planDigest: changing, neverOverMcp: true }],
+      resolutions: [{ version: 1, op: "tf-apply", gate: "wave-1", resolvedBy: "alice", timestamp: "2026-10-10T01:00:00Z", planDigest: changing }],
+    });
+    const result = await runOpWave({ spec: tg, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates, now: "2026-10-10T02:00:00Z" });
+    expect(result).toMatchObject({ exitCode: 0, decision: { status: "approved", approvedBy: "alice" } });
+    expect(gates.appended).toEqual([]);
+    h.done();
+  });
+
+  test("a wave whose runs are all empty digests every run, as before", async () => {
+    const plans = { vpc: { planDigest: digest("1"), empty: true }, dns: { planDigest: digest("2"), empty: true }, nat: { planDigest: digest("3"), empty: true } };
+    const h = harness(plans);
+    const result = await runOpWave({ spec: tg, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort() });
+    const all = waveSetDigest(["vpc", "dns", "nat"].map((t, i) => ({ member: t, planDigest: digest(String(i + 1)) })));
+    expect(result).toMatchObject({ exitCode: 0, decision: { digest: all, status: "not-required" } });
+    h.done();
+  });
+
+  test("the plans file's pending fields and the spec's neverOverMcp land on the pending fact; chant's own fields are refused", async () => {
+    const plans = { vpc: { planDigest: digest("1") }, dns: { planDigest: digest("2") }, nat: { planDigest: digest("3") } };
+    const members = [{ member: "vpc", planDigest: digest("1") }];
+    const h = harness(plans, { pending: { commit: "c".repeat(40), members, description: "wave 1 of 3: vpc, dns, nat" } });
+    // neverOverMcp at base counts even when the change drops it.
+    const gates = memoryGateLedgerPort();
+    const result = await runOpWave({ spec: tg, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: () => ({ sha: "b".repeat(40), text: JSON.stringify({ ...tg, neverOverMcp: true }) }), gates });
+    expect(result.exitCode).toBe(3);
+    expect(gates.appended[0]).toMatchObject({ commit: "c".repeat(40), members, description: "wave 1 of 3: vpc, dns, nat", neverOverMcp: true, gate: "wave-1", op: "tf-apply" });
+    h.done();
+
+    const bad = harness(plans, { pending: { gate: "other" } });
+    await expect(runOpWave({ spec: tg, specFile: "waves.json", wave: 1, cwd: bad.cwd, exec: bad.exec, show: bad.show, gates: memoryGateLedgerPort() })).rejects.toThrow(/sets gate, which chant writes itself/);
+    bad.done();
+  });
+
+  test("a spec without the new fields names its gates and digests as before", async () => {
+    const plain: OpWavesSpec = { ...tg, gateName: undefined, digest: undefined, name: "roots" };
+    const plans = { vpc: { planDigest: digest("1") }, dns: { planDigest: digest("2"), empty: true }, nat: { planDigest: digest("3") } };
+    const h = harness(plans, {}, plain);
+    const gates = memoryGateLedgerPort();
+    const result = await runOpWave({ spec: plain, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates });
+    const all = waveSetDigest(["vpc", "dns", "nat"].map((t, i) => ({ member: t, planDigest: digest(String(i + 1)) })));
+    expect(result.decision).toMatchObject({ gate: "roots-wave-1", digest: all });
+    expect(result.decision).not.toHaveProperty("digestOver");
+    expect(gates.appended[0]).not.toHaveProperty("neverOverMcp");
+    h.done();
+  });
+});

package/src/op/op-waves.ts

@@ -22,9 +22,11 @@
  *
  * ## The gate
  *
- * Wave k waits on `waveGateName(<gate>, k)`, recorded under the spec's name,
- * bound to {@link waveSetDigest} over its runs' plan digests (`../gated-waves.ts`,
- * the same digest a component fan-out's wave binds). Whether it waits at all
+ * Wave k waits on `waveGateName(<gate>, k)`, or the spec's `gateName` pattern
+ * ({@link opWaveGateName}, #3821), recorded under the spec's name, bound to
+ * {@link waveSetDigest} over its runs' plan digests (`../gated-waves.ts`, the
+ * same digest a component fan-out's wave binds), or with `digest.over:
+ * "changing"` over the runs whose plan changes something. 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.
  *
@@ -170,12 +172,28 @@ export interface OpWave {
  * `{plan}` is replaced per run.
  */
 export interface OpWavesSpec {
-  /** The pipeline's name, and the op the wave gates are recorded under (`chant approve <name> <gate>-wave-<k>`). */
+  /** The pipeline's name, and the op the wave gates are recorded under (`chant approve <name> <gate>-wave-<k>`, or the `gateName` pattern). */
   name: string;
   /** The Op a run runs when it names none. */
   op: string;
   /** The base gate name. Default: `name`. */
   gate?: string;
+  /**
+   * The name of wave k's gate (#3821): `{gate}` is the base gate name and
+   * `{k}` the wave's number. Default `"{gate}-wave-{k}"`. A product moving
+   * its own wave gates onto these waves names its old pattern here (such as
+   * `"wave-{k}"`), so the approvals already on the ledger keep their gate.
+   */
+  gateName?: string;
+  /** Which runs the set digest covers (#3821). Default: every run. */
+  digest?: OpWavesDigest;
+  /**
+   * The waves' pending facts carry `neverOverMcp` (#3821, chant#3485): their
+   * gates are never resolved over MCP or ACP, whichever channel reached
+   * them. Read at the base commit too, and either one setting it is enough,
+   * so a change cannot drop the rule for its own gates.
+   */
+  neverOverMcp?: boolean;
   /** Branches whose pushes run the waves. Default `["main"]`. */
   branches?: string[];
   /**
@@ -230,6 +248,28 @@ export interface OpWavesSpec {
   notify?: NotifyConfig;
 }
 
+/** Which runs a wave's set digest covers (#3821). */
+export interface OpWavesDigest {
+  /**
+   * `all` (the default): every run's plan. `changing`: only the runs whose
+   * plan is not `empty`, or every run when all of them are empty. A product
+   * whose plan note shows a digest over the plans that change something
+   * names `changing`, so the digest the wave asks approval for is the one
+   * the note showed.
+   */
+  over?: "all" | "changing";
+}
+
+export const OP_WAVES_DIGEST_OVER = ["all", "changing"] as const;
+
+/** The default gate name pattern. */
+export const OP_WAVE_DEFAULT_GATE_NAME = "{gate}-wave-{k}";
+
+/** The gate wave `k` waits on (#3821): the spec's `gateName` pattern, by default `<gate>-wave-<k>`. */
+export function opWaveGateName(spec: Pick<OpWavesSpec, "name" | "gate" | "gateName">, k: number): string {
+  return (spec.gateName ?? OP_WAVE_DEFAULT_GATE_NAME).replaceAll("{gate}", spec.gate ?? spec.name).replaceAll("{k}", String(k));
+}
+
 /** What happens to an approval once a wave applies under it (#3784). */
 export interface OpWavesApprovals {
   /**
@@ -331,6 +371,22 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
       if (typeof value !== "boolean") throw new Error(`${where}: approvals.spend must be true or false.`);
     }
   }
+  if (spec.gateName !== undefined) {
+    if (typeof spec.gateName !== "string" || !spec.gateName.includes("{k}") || /\s/.test(spec.gateName)) {
+      throw new Error(`${where}: gateName must be a pattern with {k}, the wave's number, and no spaces, such as "${OP_WAVE_DEFAULT_GATE_NAME}" or "wave-{k}".`);
+    }
+    const left = spec.gateName.replaceAll("{gate}", "").replaceAll("{k}", "").match(/\{[^}]*\}/);
+    if (left) throw new Error(`${where}: gateName names ${left[0]}; the pattern fills in {gate} and {k} only.`);
+  }
+  if (spec.digest !== undefined) {
+    const d = spec.digest as unknown;
+    if (d === null || typeof d !== "object" || Array.isArray(d)) throw new Error(`${where}: \`digest\` must be { "over"?: "all" | "changing" }.`);
+    for (const [key, value] of Object.entries(d as Record<string, unknown>)) {
+      if (key !== "over") throw new Error(`${where}: digest.${key} is not a setting; the one there is digest.over.`);
+      if (!OP_WAVES_DIGEST_OVER.includes(value as "all")) throw new Error(`${where}: digest.over is ${JSON.stringify(value)}; use "all" or "changing".`);
+    }
+  }
+  if (spec.neverOverMcp !== undefined && typeof spec.neverOverMcp !== "boolean") throw new Error(`${where}: neverOverMcp must be true or false.`);
   if (spec.notify !== undefined) {
     const problem = notifyConfigProblem(spec.notify, "notify");
     if (problem) throw new Error(`${where}: ${problem}`);

package/src/op/steward-points.ts

@@ -121,6 +121,13 @@ export interface AskPointInRunOptions {
   on?: string;
   /** The steward turn, when the caller has it. Default: this process's (`currentStewardTurn`). */
   turn?: StewardTurn | null;
+  /**
+   * Where a new question goes (#3815): the working tree, or `chant/lifecycle`.
+   * Default: the ledger in a steward's turn and the tree otherwise
+   * (`askPoint`'s rule). A run whose checkout does not outlive it, such as a
+   * CI job, passes `"ledger"` so a person can answer after the job ends.
+   */
+  store?: "tree" | "ledger";
 }
 
 /** What a steward reaches through its broker, read from its declaration when the turn named only the steward. */
@@ -178,6 +185,7 @@ export async function askPointInRun(opts: AskPointInRunOptions): Promise<{ answe
     ...(opts.kind !== undefined ? { kind: opts.kind } : {}),
     ...(ask ? { ask } : {}),
     ...(opts.on !== undefined ? { on: opts.on } : {}),
+    ...(opts.store !== undefined ? { store: opts.store } : {}),
     ...(turn ? { steward: { name: turn.steward, ...(turn.run ? { run: turn.run } : {}) } } : {}),
   });
   if ("error" in doc) throw new Error(`decision point ${opts.point}: ${doc.error.code}: ${doc.error.message}`);

package/src/override-gate.test.ts

@@ -148,6 +148,11 @@ describe("decideOverride", () => {
       expect(parseAppliedOverrides(`${JSON.stringify(applied)}\nnot json\n{"version":1,"kind":"finished"}\n`)).toEqual([applied]);
     });
 
+    test("takes just the subject, digest, time and approver (#3823)", () => {
+      const slim = appliedOverride({ subject: ROOT, digest: DIGEST, at: first.timestamp, by: "github:alice" }, { timestamp: "2026-10-11T11:05:00.000Z", runId: "42", commit: "c".repeat(40) });
+      expect(slim).toEqual(applied);
+    });
+
     test("a spent override does not count for the same plan again", () => {
       const d = decideOverride(input([first], { applied: [applied] }));
       expect(d.status === "none" && d.refusals).toEqual([expect.stringMatching(/is spent: a run applied under it at 2026-10-11T11:05:00/)]);

package/src/override-gate.ts

@@ -359,8 +359,14 @@ export function decideOverride(input: OverrideInput): OverrideDecision {
   };
 }
 
-/** The applied record a run appends before it applies under `override`, which spends it. Appending it is the caller's. */
-export function appliedOverride(override: StandingOverride, at: { timestamp: string; runId?: string; commit?: string }): AppliedOverrideRecord {
+/**
+ * The applied record a run appends before it applies under `override`, which
+ * spends it. Appending it is the caller's. It reads only the subject, the
+ * override digest and the override's time and approver, so a product that
+ * carries those through its own record can pass them without the ledger line
+ * (#3823); a whole {@link StandingOverride} still works.
+ */
+export function appliedOverride(override: Pick<StandingOverride, "subject" | "digest" | "at" | "by">, at: { timestamp: string; runId?: string; commit?: string }): AppliedOverrideRecord {
   return {
     version: 1,
     kind: "applied",

package/src/point-decision-bundle.test.ts

@@ -0,0 +1,62 @@
+/**
+ * The gate-point decision bundles small (#3816).
+ *
+ * terragucci's wave gate asks a decision point, and terragucci ships as one
+ * bundled file with no TypeScript compiler, chant CLI, lint or codegen code
+ * in it. `@intentius/chant/op/gate-point-run` reached all of those through
+ * the workspace asker and the decide activity. `@intentius/chant/point-decision`
+ * holds the decision with the asker and the ledger port injected. This
+ * bundles it the way terragucci would and reads esbuild's own list of what
+ * went in.
+ */
+
+import { join } from "node:path";
+import { build } from "esbuild";
+import { describe, expect, test } from "vitest";
+import { REPO } from "./workspace/__fixtures__/contract-repo";
+
+const FORBIDDEN = [
+  /node_modules\//,
+  /\/src\/cli\//,
+  /\/src\/workspace\//,
+  /\/src\/fold\//,
+  /\/src\/lint\//,
+  /\/src\/codegen\//,
+  /\/src\/op\/activities\//,
+  /\/src\/lifecycle\/git\.ts$/,
+  /\/src\/lifecycle\/gate-ledger\.ts$/,
+];
+
+describe("the point-decision bundle", () => {
+  test("holds the gate-point decision and its pure helpers, and no workspace, CLI, package or git code", async () => {
+    const result = await build({
+      entryPoints: [join(REPO, "packages", "core", "src", "point-decision.ts")],
+      bundle: true,
+      platform: "node",
+      format: "esm",
+      write: false,
+      metafile: true,
+      outdir: "out",
+      logLevel: "silent",
+    });
+    const inputs = Object.keys(result.metafile.inputs);
+    for (const pattern of FORBIDDEN) {
+      expect(inputs.filter((i) => pattern.test(i)), String(pattern)).toEqual([]);
+    }
+    // The plan digest is the one chant computes, which brings its canonical JSON with it, as in gate-decision.
+    expect(inputs.map((i) => i.replace(/^.*?packages\//, "packages/")).sort()).toEqual([
+      "packages/core/src/content-digest.ts",
+      "packages/core/src/declarable.ts",
+      "packages/core/src/effect-receipt.ts",
+      "packages/core/src/intrinsic.ts",
+      "packages/core/src/lifecycle/gate-ledger-select.ts",
+      "packages/core/src/lifecycle/gate-pending.ts",
+      "packages/core/src/lifecycle/plan-digest.ts",
+      "packages/core/src/op/duration.ts",
+      "packages/core/src/op/gate-point.ts",
+      "packages/core/src/point-decision.ts",
+    ]);
+    const bytes = result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0);
+    expect(bytes).toBeLessThan(24 * 1024);
+  });
+});

package/src/point-decision.e2e.test.ts

@@ -0,0 +1,95 @@
+/**
+ * #3816: a tool built into one file decides a gate that asks a decision point
+ * with `@intentius/chant/point-decision`, asking through the chant bin
+ * (`chantGatePointAsker`) and recording through its own gate ledger port.
+ * The question is open until a person answers it with `chant workspace points
+ * answer`; then the same call records the resolution that cites the answer,
+ * once per answer and plan. With `store: "ledger"` the question is held on
+ * `chant/lifecycle`, not in the working tree (#3815).
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test, vi } from "vitest";
+import { cleanScratch, workspace } from "./workspace/__fixtures__/decide-workspace";
+import { defaultChantCommand } from "./workspace/conformance";
+import { memoryGateLedgerPort } from "./op/gate";
+import { chantGatePointAsker, evaluatePointGate, type PointGateCheck } from "./point-decision";
+
+const PLAN = `jcs1-sha256:${"5".repeat(64)}`;
+
+const POINTS = {
+  points: {
+    "prod-apply": {
+      title: "Apply this plan to prod",
+      question: { type: "noul", instructions: "Should this plan be applied to prod?", criteria: { true: "Apply it.", false: "Do not apply it." } },
+      inputs: { "gate.component": "the Op the gate belongs to", "gate.planDigest": "the plan the gate binds" },
+      deciders: [{ kind: "quorum", count: 1 }],
+    },
+  },
+};
+
+const command = defaultChantCommand();
+let root: string;
+
+const chant = (...args: string[]): Record<string, unknown> => {
+  let out: string;
+  try {
+    out = execFileSync(command[0], [...command.slice(1), ...args], { cwd: root, encoding: "utf-8", env: { ...process.env, NO_COLOR: "1" }, stdio: ["ignore", "pipe", "pipe"] });
+  } catch (e) {
+    out = String((e as { stdout?: string }).stdout ?? "");
+  }
+  return JSON.parse(out) as Record<string, unknown>;
+};
+
+const answersInTree = (): string[] => (existsSync(join(root, "answers")) ? readdirSync(join(root, "answers")).filter((f) => f.endsWith(".md")) : []);
+
+beforeAll(() => {
+  root = workspace(POINTS);
+  vi.stubEnv("CI", "");
+});
+
+afterAll(() => {
+  vi.unstubAllEnvs();
+  cleanScratch();
+});
+
+describe("a gate-point decision through the chant bin (#3816)", () => {
+  test("waits on the open question, then passes on a person's answer, once per answer and plan", async () => {
+    const port = memoryGateLedgerPort();
+    const asker = chantGatePointAsker({ command, cwd: root });
+    const input = { op: "tf-apply", gate: "approve-apply", point: { name: "prod-apply" }, planDigest: PLAN, now: "2026-10-11T13:00:00.000Z" };
+
+    const first = await evaluatePointGate(port, asker, input);
+    expect(first).toMatchObject({ satisfied: false, recorded: true, waiting: { point: "prod-apply", state: "escalated", subject: "gate:tf-apply/approve-apply" } });
+    const waiting = first as Extract<PointGateCheck, { waiting: unknown }>;
+    expect(port.appended).toEqual([expect.objectContaining({ op: "tf-apply", gate: "approve-apply", planDigest: PLAN, answer: { point: "prod-apply", id: waiting.waiting.id, path: waiting.waiting.path } })]);
+
+    // Asked again while open, the standing pending fact is reused.
+    expect(await evaluatePointGate(port, asker, input)).toMatchObject({ satisfied: false, recorded: false });
+
+    expect(chant("workspace", "points", "answer", waiting.waiting.id, "--answer", "yes", "--by", "alice")).toMatchObject({ written: true, question: { state: "answered" } });
+
+    const passed = await evaluatePointGate(port, asker, input);
+    expect(passed).toMatchObject({ satisfied: true, recorded: true, resolution: { resolvedBy: "alice", planDigest: PLAN, answer: { id: waiting.waiting.id, answer: true, decider: "quorum", answeredBy: ["alice"] } } });
+    expect(await evaluatePointGate(port, asker, input)).toMatchObject({ satisfied: true, recorded: false });
+    expect(port.resolved).toHaveLength(1);
+  }, 120_000);
+
+  test("a point with store ledger holds the question on chant/lifecycle, and an answer it does not pass on refuses", async () => {
+    const port = memoryGateLedgerPort();
+    const asker = chantGatePointAsker({ command, cwd: root });
+    const before = answersInTree();
+    const input = { op: "ledger-apply", gate: "approve-apply", point: { name: "prod-apply", store: "ledger" as const }, planDigest: PLAN };
+
+    const first = (await evaluatePointGate(port, asker, input)) as Extract<PointGateCheck, { waiting: unknown }>;
+    expect(first.waiting.state).toBe("escalated");
+    expect(answersInTree()).toEqual(before);
+
+    chant("workspace", "points", "answer", first.waiting.id, "--answer", "no", "--by", "alice");
+    const refused = await evaluatePointGate(port, asker, input);
+    expect(refused).toMatchObject({ satisfied: false, answer: { id: first.waiting.id, answer: false } });
+    expect("refused" in refused && refused.refused).toContain("passes only on true");
+  }, 120_000);
+});