@intentius/chant 0.105.1 → 0.106.1

package/src/op/runtime.ts

@@ -187,6 +187,23 @@ export interface OpRunStartOptions {
    * runtime takes it; a hosted run's lease is taken where the run executes.
    */
   work?: { item?: string; holder?: string };
+  /**
+   * The id to name this run by, in place of one the runtime mints (#3539).
+   * The local runtime uses it as the run record's id, the gate ledger's
+   * `runId` and `currentOpRun().runId`. `chant acp` passes fountain's
+   * conversation id here, so the record a hosted run writes in the sandbox
+   * and the run `chant run status --on fountain` reports carry the same id.
+   */
+  runId?: string;
+}
+
+/** What a caller hands {@link OpRuntimeProvider.resolveGate} besides the resolution. */
+export interface OpGateResolveOptions {
+  /**
+   * `--env` on `chant run approve` (#3539): the environment the woken run
+   * runs in. Omitted, a runtime keeps the environment the gated run had.
+   */
+  env?: string;
 }
 
 /**
@@ -220,9 +237,10 @@ export interface OpRuntimeProvider {
   /**
    * Wake a run whose gate has just been resolved. The ledger write is the
    * fact and `chant approve` owns it; this is the runtime's chance to act on
-   * it. Omit when a run re-reads the ledger on its own.
+   * it. Omit when a run re-reads the ledger on its own. `opts.env` is the
+   * `--env` the approver named, when they named one.
    */
-  resolveGate?(op: string, gate: string, resolution: GateResolutionRecord): Promise<void>;
+  resolveGate?(op: string, gate: string, resolution: GateResolutionRecord, opts?: OpGateResolveOptions): Promise<void>;
 
   /**
    * Host `chant run --components`. Optional: a runtime without it refuses the

package/src/op/runtimes/local.test.ts

@@ -95,6 +95,21 @@ describe("the local op runtime", () => {
     expect(status.result?.record?.id).toBe(handle.runId);
   });
 
+  test("a run named by its caller carries that id on the handle, the run context and the record (#3539)", async () => {
+    const { currentOpRun } = await import("../run-context");
+    let seen: ReturnType<typeof currentOpRun>;
+    loadActivitiesMock.mockResolvedValue(new Map([["ok", vi.fn(async () => { seen = currentOpRun(); })]]));
+    const runtime = createLocalOpRuntime();
+
+    const handle = await runtime.start(op("hello", [{ kind: "activity", fn: "ok", args: {} }]), { runId: "conv-42" });
+    const status = await handle.result();
+
+    expect(handle.runId).toBe("conv-42");
+    expect(status.runId).toBe("conv-42");
+    expect(seen?.runId).toBe("conv-42");
+    expect(status.result?.record?.id).toBe("conv-42");
+  });
+
   test("the project's configured lexicons decide which appliers load", async () => {
     loadActivitiesMock.mockResolvedValue(new Map([["ok", vi.fn(async () => ({}))]]));
     const runtime = createLocalOpRuntime();

package/src/op/runtimes/local.ts

@@ -139,7 +139,9 @@ export function createLocalOpRuntime(opts: { projectPath?: string } = {}): OpRun
 
       const [activities, profiles] = await Promise.all([loadActivities(lexicons), loadProfiles()]);
 
-      const runId = `local-${Date.now()}`;
+      // A caller that names the run (#3539: `chant acp` on fountain passes the
+      // conversation id) gets its id on the record; otherwise one is minted.
+      const runId = startOpts.runId ?? `local-${Date.now()}`;
       const startedAt = new Date().toISOString();
       noteEnv(op);
 

package/src/pr-loop.test.ts

@@ -16,7 +16,9 @@ import {
   PR_REPORT_SCHEMA_ID,
   prApproveCommand,
   prNoteMarker,
+  PR_GATE_OP,
   prOp,
+  prStatusContext,
   prStatusDescription,
   prStatusState,
   renderPrNote,
@@ -101,6 +103,12 @@ const appliedReport: PrReport = {
   ],
 };
 
+const resumedReport: PrReport = {
+  ...appliedReport,
+  members: [{ ...planReport.members[0], status: "applied" }, { ...planReport.members[1], status: "applied" }],
+  resumed: { applied: ["a"] },
+};
+
 describe("the pr-report schema", () => {
   test("is a valid schema and names this module's id", () => {
     expect(validSchema(schema)).toBe(true);
@@ -108,7 +116,7 @@ describe("the pr-report schema", () => {
   });
 
   test("every stage's report validates, and its change set validates against the change-set schema", () => {
-    for (const report of [planReport, refusedReport, appliedReport]) {
+    for (const report of [planReport, refusedReport, appliedReport, resumedReport]) {
       expectValid(report);
       expectValidChangeSet(report.changeSet);
       expect(report.changeSet.digest).toBe(report.digest);
@@ -144,6 +152,12 @@ describe("the note", () => {
     golden("pr-apply-applied.note.golden.md", note);
   });
 
+  test("a resumed apply names what the earlier attempt applied (#3464)", () => {
+    const note = renderPrNote(resumedReport);
+    expect(note).toContain("Resumed under the same approval: `a` applied in an earlier attempt and did not run again.");
+    expect(renderPrNote(appliedReport)).not.toContain("Resumed");
+  });
+
   test("a small limit leaves the summary out rather than cutting the table", () => {
     const note = renderPrNote(planReport, { limit: 800 });
     expect(note).toContain("| `app` |");
@@ -169,3 +183,29 @@ describe("the status", () => {
     expect(prApproveCommand(planReport, "gitlab:ana")).toBe(`chant approve pr-12 pr-apply --plan ${doc.digest} --approver gitlab:ana --sign`);
   });
 });
+
+describe("a workspace member's loop (#3465)", () => {
+  const memberReport: PrReport = { ...planReport, member: "network", op: prOp(12, "network") };
+
+  test("the op, the note marker and the status contexts carry the member's name", () => {
+    expect(prOp(12)).toBe("pr-12");
+    expect(prOp(12, "network")).toBe("pr-12-network");
+    expect(prNoteMarker("prod", "network")).toBe("<!-- chant-pr:prod:network -->");
+    expect(prNoteMarker("prod", "network")).not.toBe(prNoteMarker("prod"));
+    expect(prStatusContext("plan")).toBe("chant/plan");
+    expect(prStatusContext("apply", "network")).toBe("chant/apply/network");
+  });
+
+  test("the gate op pattern takes both forms and nothing else", () => {
+    for (const op of ["pr-12", "pr-12-network", "pr-3-a1-b2"]) expect(PR_GATE_OP.test(op)).toBe(true);
+    for (const op of ["pr-", "pr-x", "pr-12-", "pr-12-Net", "fan-out"]) expect(PR_GATE_OP.test(op)).toBe(false);
+  });
+
+  test("the report with a member validates, and its note names the member and approves its own op", () => {
+    expectValid(memberReport);
+    const note = renderPrNote(memberReport);
+    expect(note.startsWith("<!-- chant-pr:" + memberReport.env + ":network -->")).toBe(true);
+    expect(note).toContain("in member `network`");
+    expect(note).toContain("chant approve pr-12-network pr-apply");
+  });
+});

package/src/pr-loop.ts

@@ -26,6 +26,14 @@
  * On merge the apply plans the same members again, before anything applies,
  * and decides the gate against the new digest. The same plan applies; a moved
  * plan stops with both digests named and nothing applied.
+ *
+ * ## Inside a workspace member
+ *
+ * Each workspace member that generates the pipeline (#3465) runs its own
+ * plan and apply on the same pull request, so each keeps its own gate, note
+ * and statuses: op `pr-<number>-<member>`, the note marker and the status
+ * contexts carry the member's name. The gate name stays the same, so one
+ * `identity.gates` entry covers every member.
  */
 
 import type { ChangeSetAction, ChangeSetDocument } from "./change-set";
@@ -40,19 +48,30 @@ export const PR_REPORT_CONTRACT = 1;
 /** The gate a pull request's apply waits on, unless the pipeline names another. */
 export const PR_APPLY_GATE = "pr-apply";
 
-/** The op a pull request's gate is recorded under: `pr-<number>`. */
-export function prOp(pr: number): string {
-  return `pr-${pr}`;
+/**
+ * The op a pull request's gate is recorded under: `pr-<number>`, or
+ * `pr-<number>-<member>` for a workspace member's pipeline (#3465).
+ */
+export function prOp(pr: number, member?: string): string {
+  return member ? `pr-${pr}-${member}` : `pr-${pr}`;
 }
 
-/** The hidden line that marks the pull request's note, one per environment. */
-export function prNoteMarker(env: string): string {
-  return `<!-- chant-pr:${env} -->`;
+/** Whether `op` is a pull request's gate op, with or without a member. Member names follow the declaration's name pattern. */
+export const PR_GATE_OP = /^pr-\d+(?:-[a-z0-9][a-z0-9-]*)?$/;
+
+/** The hidden line that marks the pull request's note, one per environment and, in a workspace, per member. */
+export function prNoteMarker(env: string, member?: string): string {
+  return member ? `<!-- chant-pr:${env}:${member} -->` : `<!-- chant-pr:${env} -->`;
 }
 
 /** The status contexts the two stages set on the commit. */
 export const PR_STATUS_CONTEXTS = { plan: "chant/plan", apply: "chant/apply" } as const;
 
+/** A stage's status context: `chant/plan`, or `chant/plan/<member>` for a workspace member's pipeline. */
+export function prStatusContext(stage: "plan" | "apply", member?: string): string {
+  return member ? `${PR_STATUS_CONTEXTS[stage]}/${member}` : PR_STATUS_CONTEXTS[stage];
+}
+
 /** Changes a member's plan proposes, by the actions a reviewer reads. */
 export interface PrMemberCounts {
   create: number;
@@ -143,6 +162,8 @@ export interface PrReport {
   /** The pull or merge request number, when known. */
   pr: number | null;
   env: string;
+  /** The workspace member whose pipeline ran the stage (#3465). Absent outside a workspace member. */
+  member?: string;
   /** The commit the change is measured from: the merge base of the given base and `head`. */
   base: string;
   head: string;
@@ -155,6 +176,12 @@ export interface PrReport {
   refusal?: PrRefusal;
   /** The refusal or failure, as printed. */
   message?: string;
+  /**
+   * Apply stage, `--resume` (#3464): an earlier attempt at the approved set
+   * failed partway, and these components applied in it. This run applied
+   * the rest under the same approval and did not run them again.
+   */
+  resumed?: { applied: string[] };
   approval: PrApproval;
   /** Component names: which changed, which run because they depend on one, and what the change touched that no component deploys. */
   selection: {
@@ -255,12 +282,15 @@ function approvalLines(report: PrReport, approver: string): string[] {
 export function renderPrNote(report: PrReport, options: { limit?: number; approver?: string } = {}): string {
   const limit = options.limit ?? GITHUB_COMMENT_LIMIT;
   const out: string[] = [
-    prNoteMarker(report.env),
-    `### chant ${report.stage === "plan" ? "plan" : "apply"} for ${code(report.env)}`,
+    prNoteMarker(report.env, report.member),
+    `### chant ${report.stage === "plan" ? "plan" : "apply"} for ${code(report.env)}${report.member ? ` in member ${code(report.member)}` : ""}`,
     "",
     `${headline(report)} Head ${code(short(report.head))}, measured from ${code(short(report.base))}.`,
   ];
   if (report.message) out.push("", `> ${report.message.split("\n").join("\n> ")}`);
+  if (report.resumed && report.resumed.applied.length > 0) {
+    out.push("", `Resumed under the same approval: ${report.resumed.applied.map(code).join(", ")} applied in an earlier attempt and did not run again.`);
+  }
   if (report.members.length > 0) {
     out.push("", "| Member | Component | Status | Create | Update | Replace | Delete |", "|---|---|---|---:|---:|---:|---:|");
     for (const m of report.members) {

package/src/workspace/lineage-upgrade-cli.ts

@@ -15,7 +15,7 @@ import { writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { formatError, formatInfo, formatSuccess, formatWarning } from "../cli/format";
 import type { CommandContext } from "../cli/registry";
-import { approveCommand, describeGateMismatch, evaluateGate, gitGateLedgerPort, type GateLedgerPort } from "../op/gate";
+import { approveCommand, describeGateMismatch, evaluateGate, gateIsSealed, gitGateLedgerPort, type GateLedgerPort } from "../op/gate";
 import { WORKSPACE_UPGRADE_GATE_OP } from "../op/gate-name";
 import { LockError } from "./lineage-lock";
 import { applyStagedUpgrade, describeStaged, stageUpgrade, type ChantRunner, type StagedUpgrade } from "./lineage-upgrade";
@@ -104,12 +104,13 @@ export async function upgradeCommand(opts: UpgradeCommandOptions): Promise<Upgra
     });
     if (!check.satisfied) {
       if (!opts.json) {
-        if (check.mismatch) console.error(formatWarning({ message: describeGateMismatch(WORKSPACE_UPGRADE_GATE_OP, gate, check.mismatch) }));
+        const sealed = await gateIsSealed(gate);
+        if (check.mismatch) console.error(formatWarning({ message: describeGateMismatch(WORKSPACE_UPGRADE_GATE_OP, gate, check.mismatch, sealed) }));
         if (check.pushWarning) console.error(formatWarning({ message: check.pushWarning }));
         if (check.quorum) console.error(formatInfo(`approvals so far: ${check.quorum.approvers.length} of ${check.quorum.need}`));
         console.error(
           formatInfo(
-            `Gated: the patch ${staged.digest} waits for approval. Review it (--output <file> writes it), then run \`${approveCommand(WORKSPACE_UPGRADE_GATE_OP, gate)}\` and repeat this command to apply it.`,
+            `Gated: the patch ${staged.digest} waits for approval. Review it (--output <file> writes it), then run \`${approveCommand(WORKSPACE_UPGRADE_GATE_OP, gate, undefined, undefined, sealed)}\` and repeat this command to apply it.`,
           ),
         );
       }

package/src/workspace/lineage-upgrade.test.ts

@@ -21,6 +21,14 @@ import { LOCK_FILE, fileHash, readLock, writeLock } from "./lineage-lock";
 import { stageUpgrade, isGovernancePath, UPGRADE_DIR, type ChantRunner } from "./lineage-upgrade";
 import { upgradeCommand } from "./lineage-upgrade-cli";
 
+// #3521: whether the workspace seals a gate is read from identity.gates in the
+// working directory; a test says which gates are sealed instead.
+const sealedGates = new Set<string>();
+vi.mock("../op/gate", async () => {
+  const actual = await vi.importActual<typeof import("../op/gate")>("../op/gate");
+  return { ...actual, gateIsSealed: async (gate: string) => sealedGates.has(gate) };
+});
+
 const ENV = { ...process.env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t" };
 
 let root: string;
@@ -290,6 +298,38 @@ describe("chant workspace upgrade", () => {
     expect(again.outcome).toBe("up-to-date");
   });
 
+  describe("the gated hint's approve command (#3521)", () => {
+    /** Runs the upgrade into its gate, and again against an approval of another patch; returns what both printed. */
+    async function gatedOutput(): Promise<string> {
+      release("v2.0.0", { "README.md": "starter v2\n" });
+      const port = ledger();
+      const lines: string[] = [];
+      vi.spyOn(console, "error").mockImplementation((s: unknown) => { lines.push(String(s)); });
+      await upgradeCommand({ root: proj, to: "v2.0.0", runChant: passing, ledger: port, now: "2026-09-23T10:00:00.000Z" });
+      port.approve(`sha256:${"0".repeat(64)}`, "2026-09-23T10:01:00.000Z");
+      await upgradeCommand({ root: proj, to: "v2.0.0", runChant: passing, ledger: port, now: "2026-09-23T10:02:00.000Z" });
+      return lines.join("\n");
+    }
+
+    test("unsealed gate: the gated line and the mismatch line carry no --sign", async () => {
+      const out = await gatedOutput();
+      expect(out).toContain("then run `chant approve workspace-upgrade .`");
+      expect(out).toContain("needs a fresh one: chant approve workspace-upgrade .");
+      expect(out).not.toContain("--sign");
+    });
+
+    test("sealed gate: the gated line and the mismatch line end in --sign", async () => {
+      sealedGates.add(".");
+      try {
+        const out = await gatedOutput();
+        expect(out).toContain("then run `chant approve workspace-upgrade . --sign`");
+        expect(out).toContain("needs a fresh one: chant approve workspace-upgrade . --sign");
+      } finally {
+        sealedGates.clear();
+      }
+    });
+  });
+
   test("a lock that a .gitignore covers is applied beside the patch, and the digest covers it", async () => {
     put(proj, ".gitignore", ".chant/\n");
     git(proj, ["rm", "-q", "--cached", LOCK_FILE]);

package/src/workspace/member-pipeline.test.ts

@@ -79,6 +79,34 @@ describe("the component pipeline's file and command", () => {
     expect(plan.command).toBe("chant build --components --generate github --env staging --promote-to prod");
   });
 
+  test("a pull-request pipeline gets its own file and a command that regenerates it (#3465)", () => {
+    expect(memberPipelineFile("github", "api", "staging", "pr")).toBe(".github/workflows/chant-pr-api-staging.yml");
+    expect(memberPipelineFile("gitlab", "api", "staging", "pr")).toBe(".gitlab/ci/chant-pr-api-staging.gitlab-ci.yml");
+    const dir = join(repo, "services/api");
+    const plan = planMemberComponentPipeline({
+      projectDir: dir,
+      found: findWorkspaceRoot(dir)!,
+      lexicon: "github",
+      env: "staging",
+      prLoop: { gate: "infra-apply", branch: "trunk" },
+    })!;
+    expect(plan.file).toBe(".github/workflows/chant-pr-api-staging.yml");
+    expect(plan.member).toEqual({ name: "api", dir: "services/api", file: ".github/workflows/chant-pr-api-staging.yml" });
+    expect(plan.command).toBe("chant build --components --generate github --env staging --pr-loop --gate infra-apply --branch trunk");
+  });
+
+  test("the recorded command keeps --wave-gate, --canary and --base (#3049)", () => {
+    const dir = join(repo, "services/api");
+    const plan = planMemberComponentPipeline({
+      projectDir: dir,
+      found: findWorkspaceRoot(dir)!,
+      lexicon: "github",
+      env: "staging",
+      waveGate: { gate: "release", canary: ["a", "b"], base: "origin/main" },
+    })!;
+    expect(plan.command).toBe("chant build --components --generate github --env staging --wave-gate release --canary a,b --base origin/main");
+  });
+
   test("--output keeps the path, relative to the member in the command", () => {
     const dir = join(repo, "services/api");
     const plan = planMemberComponentPipeline({

package/src/workspace/member-pipeline.ts

@@ -134,11 +134,14 @@ export function memberPipelineDir(provider: string): string | undefined {
  * The default path of a member's component pipeline for one environment,
  * relative to the repository root: `chant-<member>-<env>.yml` in the forge's
  * workflow directory, or `.gitlab/ci/chant-<member>-<env>.gitlab-ci.yml`.
+ * A pull-request pipeline (`kind` `"pr"`, #3465) is `chant-pr-<member>-<env>`,
+ * so it sits beside the member's deploy pipeline for the same environment.
  */
-export function memberPipelineFile(provider: string, member: string, env: string): string | undefined {
+export function memberPipelineFile(provider: string, member: string, env: string, kind: "components" | "pr" = "components"): string | undefined {
   const dir = PIPELINE_DIRS[provider];
   if (dir === undefined) return undefined;
-  return `${dir}/chant-${member}-${env}${provider === "gitlab" ? ".gitlab-ci.yml" : ".yml"}`;
+  const stem = kind === "pr" ? `chant-pr-${member}-${env}` : `chant-${member}-${env}`;
+  return `${dir}/${stem}${provider === "gitlab" ? ".gitlab-ci.yml" : ".yml"}`;
 }
 
 /** A repository-relative path for an absolute one. */
@@ -205,6 +208,10 @@ export interface ComponentPlanInput {
   output?: string;
   params?: string[];
   paramsFile?: string;
+  /** `--pr-loop`, with its `--gate` and `--branch` (#3465). */
+  prLoop?: { gate?: string; branch?: string };
+  /** `--wave-gate` with its `--canary` and `--base` (#3049). */
+  waveGate?: { gate: string; canary?: string[]; base?: string };
 }
 
 /** The generators' own default environment when `--env` is not given. */
@@ -224,7 +231,7 @@ export function planMemberComponentPipeline(input: ComponentPlanInput): MemberCo
   if (input.output) {
     target = resolve(input.output);
   } else {
-    const file = memberPipelineFile(input.lexicon, ctx.member.name, env);
+    const file = memberPipelineFile(input.lexicon, ctx.member.name, env, input.prLoop ? "pr" : "components");
     if (file === undefined) {
       throw new Error(`there is no default pipeline path for ${input.lexicon} in a workspace member; pass --output <file>`);
     }
@@ -234,6 +241,16 @@ export function planMemberComponentPipeline(input: ComponentPlanInput): MemberCo
 
   const parts = ["chant", "build", "--components", "--generate", input.lexicon, "--env", env];
   if (input.promoteTo) parts.push("--promote-to", input.promoteTo);
+  if (input.waveGate) {
+    parts.push("--wave-gate", input.waveGate.gate);
+    if (input.waveGate.canary?.length) parts.push("--canary", input.waveGate.canary.join(","));
+    if (input.waveGate.base) parts.push("--base", input.waveGate.base);
+  }
+  if (input.prLoop) {
+    parts.push("--pr-loop");
+    if (input.prLoop.gate) parts.push("--gate", input.prLoop.gate);
+    if (input.prLoop.branch) parts.push("--branch", input.prLoop.branch);
+  }
   for (const p of input.params ?? []) parts.push("--param", p);
   if (input.paramsFile) parts.push("--params-file", relPath(ctx.memberRoot, resolve(input.paramsFile)));
   if (input.output) parts.push("--output", relPath(ctx.memberRoot, target));

package/src/workspace/pr-report.schema.json

@@ -15,11 +15,16 @@
       "description": "The pull or merge request number. null when an apply found no pull request that merged its commit."
     },
     "env": { "type": "string" },
+    "member": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]{0,39}$",
+      "description": "The workspace member whose pipeline ran the stage. Absent outside a workspace member."
+    },
     "base": { "type": "string", "pattern": "^[0-9a-f]{40,64}$", "description": "The commit the change is measured from: the merge base of the given base and head." },
     "head": { "type": "string", "pattern": "^[0-9a-f]{40,64}$" },
     "op": {
       "type": "string",
-      "description": "The gate's op, pr-<number>. Its ledger is _gates/<op>.jsonl on chant/lifecycle. pr-unknown when no pull request was found."
+      "description": "The gate's op, pr-<number>, or pr-<number>-<member> for a workspace member's pipeline. Its ledger is _gates/<op>.jsonl on chant/lifecycle. pr-unknown when no pull request was found."
     },
     "gate": { "type": "string", "description": "The gate the apply waits on, pr-apply unless the pipeline names another." },
     "digest": {
@@ -36,6 +41,14 @@
       "description": "Why an apply refused. plan-changed: an approval stands for another digest, so the plan changed after review."
     },
     "message": { "type": "string", "description": "The refusal or failure as printed." },
+    "resumed": {
+      "type": "object",
+      "required": ["applied"],
+      "description": "Apply stage with --resume (#3464): an earlier attempt at the approved set failed partway. This run applied the rest under the same approval.",
+      "properties": {
+        "applied": { "type": "array", "items": { "type": "string" }, "description": "Components the earlier attempt applied, which this run did not run again." }
+      }
+    },
     "approval": {
       "type": "object",
       "required": ["status"],