@intentius/chant 0.124.22 → 0.124.24

package/src/ci-jobs.ts

@@ -15,7 +15,9 @@
  *  - the `setup` steps and `environment` a job may carry, checked once per
  *    forge ({@link assertSetupSteps}, {@link assertEnvironment},
  *    {@link gitlabSetupScript}, {@link assertGitlabEnvironment});
- *  - GitLab's `rules:` expressions and `id_tokens:` declaration.
+ *  - GitLab's `rules:` expressions and `id_tokens:` declaration;
+ *  - where a job runs and the id tokens it asks for (#3914), {@link githubRunsOn},
+ *    {@link gitlabTags}, {@link gitlabIdTokensDoc} and {@link idTokenAudienceEnv}.
  *
  * The Forgejo dialect (action refs, dropped `permissions:` and
  * `environment:`, the header note naming what was dropped) is the forgejo
@@ -96,11 +98,66 @@ export function dirnameOf(path: string): string {
   return i <= 0 ? "." : path.slice(0, i);
 }
 
+/**
+ * Where a generated job runs (#3914): a runner label, a list of labels the
+ * runner must all carry, or on GitHub a runner group with optional labels.
+ * `runs-on` on GitHub and Forgejo, `tags` on GitLab.
+ */
+export type CiRunner = string | readonly string[] | { group: string; labels?: readonly string[] };
+
+/** True when `runner` is a GitHub runner group, which only GitHub has. */
+export function isRunnerGroup(runner: CiRunner | undefined): runner is { group: string; labels?: readonly string[] } {
+  return runner !== undefined && typeof runner === "object" && !Array.isArray(runner);
+}
+
+/**
+ * Refuse a runner group on a forge that has none (#3914). `subject` and
+ * `field` name whose runner it is, such as `Op waves "x"` and `wave "prod"
+ * runner`.
+ */
+export function assertRunnerLabels(subject: string, field: string, runner: CiRunner | undefined, forge: "GitLab" | "Forgejo"): void {
+  if (!isRunnerGroup(runner)) return;
+  throw new Error(
+    `${subject}: ${field} is the runner group "${runner.group}", which only GitHub has. ` +
+      `${forge === "GitLab" ? "GitLab picks a runner by its tags" : "Forgejo picks a runner by its labels"}; give a label or a list of labels.`,
+  );
+}
+
+/**
+ * Each id token's audience as a variable, `<NAME>_AUDIENCE` (#3914). On
+ * GitHub and Forgejo the audience is chosen when the job requests the token,
+ * so the job reads it from there; GitLab declares it in `id_tokens:`
+ * ({@link gitlabIdTokensDoc}).
+ */
+export function idTokenAudienceEnv(idTokens: Readonly<Record<string, string>> | undefined): Record<string, string> {
+  return Object.fromEntries(Object.entries(idTokens ?? {}).map(([name, aud]) => [`${name}_AUDIENCE`, aud]));
+}
+
+/** A job's GitLab `id_tokens:` for `{ <variable>: <audience> }` (#3914), or undefined when there are none. */
+export function gitlabIdTokensDoc(idTokens: Readonly<Record<string, string>> | undefined): Record<string, { aud: string }> | undefined {
+  const entries = Object.entries(idTokens ?? {});
+  return entries.length > 0 ? Object.fromEntries(entries.map(([name, aud]) => [name, { aud }])) : undefined;
+}
+
+/** A job's GitLab `tags:` for `runner` (#3914), or undefined when it names none. */
+export function gitlabTags(runner: CiRunner | undefined): string[] | undefined {
+  if (runner === undefined || isRunnerGroup(runner)) return undefined;
+  return typeof runner === "string" ? [runner] : [...runner];
+}
+
 // ── GitHub Actions and Forgejo Actions ──────────────────────────────────────
 
 /** The runner label a generated job asks for; the Forgejo dialect rewrites it to the project's label. */
 export const GITHUB_RUNNER = "ubuntu-latest";
 
+/** A job's `runs-on` for `runner` (#3914): {@link GITHUB_RUNNER} when it names none. */
+export function githubRunsOn(runner: CiRunner | undefined): string | string[] | { group: string; labels?: string[] } {
+  if (runner === undefined) return GITHUB_RUNNER;
+  if (typeof runner === "string") return runner;
+  if (isRunnerGroup(runner)) return { group: runner.group, ...(runner.labels && runner.labels.length > 0 ? { labels: [...runner.labels] } : {}) };
+  return [...runner];
+}
+
 /** The job token, which GitHub and Forgejo both mint for every run. */
 export const GITHUB_JOB_TOKEN = "${{ github.token }}";
 

package/src/cli/commands/build.ts

@@ -32,6 +32,7 @@ import { loadPolicyChecks } from "../../lint/policy";
 import { armSandboxPolicyExecution, runProjectPolicies } from "../../lint/policy-sandbox";
 import { sortedJsonReplacer } from "../../utils";
 import { rankFoldBlockers, toCollapsedFormat, type FoldRankResult } from "../../discovery/fold-rank";
+import { foldExecutionCounts } from "../../discovery/fold-import";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
 import { writeFileSync, mkdirSync } from "fs";
 import { resolve, dirname, join, relative } from "path";
@@ -396,6 +397,23 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
             : (decision.reason ?? "fell back to run");
         console.error(formatInfo(`[fold:${decision.mode}] ${rel} — ${detail}`));
       }
+      // typescript-as-data#177 — the exact instrument beside the sampled one.
+      // `test/leftness` reports "0 MB of definition-library code on the path"
+      // from a `node --cpu-prof` recording, and a profile has a sampling
+      // floor: 0 MB is everything the profiler could see rather than nothing
+      // having run. L10.1's counters have no floor.
+      //
+      // Inside --verbose with the per-file lines, not beside them. The default
+      // path is deliberately quiet for the reason above, and the leftness
+      // capture already runs --verbose and greps this log for `[fold:fold]`.
+      const counts = foldExecutionCounts();
+      console.error(
+        formatInfo(
+          `[fold:counts] factoryInvocations=${counts.factoryInvocations} ` +
+            `projectFactoryInvocations=${counts.projectFactoryInvocations} ` +
+            `factoryInterpretations=${counts.factoryInterpretations}`,
+        ),
+      );
     } else {
       console.error(formatInfo(summarizeFoldDecisions(result.foldDecisions)));
     }

package/src/cli/handlers/approve.ts

@@ -24,6 +24,7 @@ import { FAN_OUT_GATE_OP, OVERRIDE_GATE_OP, WORKSPACE_UPGRADE_GATE_OP } from "..
 import { PR_GATE_OP } from "../../pr-loop";
 import { pushLifecycleReport, requireLifecycleLedger } from "../../lifecycle/git";
 import { LIFECYCLE_LOCAL_NOTE, isLifecycleLocalNote } from "../../lifecycle/local-note";
+import { ledgerRecordingOff, NO_RECORD_ENV } from "../../lifecycle/no-record";
 import { formatError, formatWarning, formatSuccess, formatInfo } from "../format";
 import type { CommandContext } from "../registry";
 
@@ -267,6 +268,14 @@ export async function recordGateApproval(
   gate: string,
   opts: GateApprovalOptions,
 ): Promise<GateApprovalOutcome> {
+  // #3955: with recording off the approval would be dropped with the process.
+  if (ledgerRecordingOff()) {
+    console.error(formatError({
+      message: `Cannot record the approval of "${gate}": ${NO_RECORD_ENV} is set, so nothing is written to chant/lifecycle`,
+      hint: `Unset ${NO_RECORD_ENV} to approve the gate.`,
+    }));
+    return { ok: false };
+  }
   const { ops } = await discoverOps();
   // `fan-out` is the op name every `chant components fan-out` gate is recorded
   // under (../handlers/fan-out.ts). It is a command rather than a declaration,

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

@@ -42,7 +42,7 @@ vi.mock("node:child_process", async () => {
   return { ...actual, exec: execWithCustom, execFile: execFileWithCustom };
 });
 
-const { runEmulator, formatEmulatorHelp, parsePortMappings } = await import("./emulator");
+const { runEmulator, formatEmulatorHelp, parsePortMappings, parseUpOptions } = await import("./emulator");
 
 function cap(): EmulatorCapability {
   return {
@@ -286,3 +286,63 @@ describe("chant emulator --port and --help (#3673)", () => {
     expect(formatEmulatorHelp([])).toContain("No lexicon configured for this project has a local emulator.");
   });
 });
+
+describe("chant emulator up --image, --network, --setting, --loopback (#3952)", () => {
+  const floci = (): EmulatorCapability => ({ ...cap(), spec: { ...cap().spec, settingsPrefix: "FLOCI_" } });
+  const other = (): EmulatorCapability => ({
+    spec: { name: "chant-floci-az", image: "floci/floci-az:1.0.0", containerPort: 4577, healthPath: "/health" },
+    env: () => ({}),
+  });
+
+  beforeEach(() => {
+    upMock.mockReset();
+    vi.restoreAllMocks();
+  });
+
+  test("up passes each option to the lifecycle", async () => {
+    stderr();
+    upMock.mockResolvedValue({ endpoint: "http://localhost:4566" });
+    const exit = await runEmulator({
+      args: makeArgs({
+        path: "up", image: "floci/floci:1.6.0", network: "loom", loopback: true,
+        setting: ["FLOCI_STORAGE_MODE=memory", "FLOCI_X=a=b"], port: ["4567"],
+      }),
+      plugins: [plugin("aws", floci())],
+      serializers: [],
+    });
+    expect(exit).toBe(0);
+    expect(upMock).toHaveBeenCalledWith({
+      image: "floci/floci:1.6.0", network: "loom", loopback: true,
+      settings: { FLOCI_STORAGE_MODE: "memory", FLOCI_X: "a=b" }, port: 4567,
+    });
+  });
+
+  test("a setting no selected emulator takes is refused before anything starts", async () => {
+    const err = stderr();
+    const exit = await runEmulator({
+      args: makeArgs({ path: "up", setting: ["HOME=/tmp"] }),
+      plugins: [plugin("aws", floci())],
+      serializers: [],
+    });
+    expect(exit).toBe(1);
+    expect(upMock).not.toHaveBeenCalled();
+    expect(err.join("\n")).toContain("--setting HOME: no selected emulator takes it; the selected ones take FLOCI_* (chant-floci)");
+  });
+
+  test("settings go only to the emulator whose prefix matches; --image needs one emulator", () => {
+    const a = floci();
+    const b = other();
+    const opts = parseUpOptions({ setting: ["FLOCI_A=1"], network: "n" }, [a, b]);
+    expect(opts.get(a)).toEqual({ network: "n", settings: { FLOCI_A: "1" } });
+    expect(opts.get(b)).toEqual({ network: "n" });
+    expect(() => parseUpOptions({ image: "x:1" }, [a, b])).toThrow(/--image x:1 is ambiguous with 2 emulators/);
+    expect(() => parseUpOptions({ setting: ["FLOCI_A"] }, [a])).toThrow(/expected <KEY>=<VALUE>/);
+  });
+
+  test("the options apply to up only", async () => {
+    const err = stderr();
+    const exit = await runEmulator({ args: makeArgs({ path: "status", loopback: true }), plugins: [plugin("aws", floci())], serializers: [] });
+    expect(exit).toBe(1);
+    expect(err.join("\n")).toContain("--loopback applies to `chant emulator up` only");
+  });
+});

package/src/cli/handlers/emulator.ts

@@ -1,9 +1,9 @@
 import { exec, execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { emulatorLifecycle, emulatorsOf, type EmulatorCapability } from "../../op";
+import { checkSettings, emulatorLifecycle, emulatorsOf, type EmulatorCapability, type EmulatorUpArgs } from "../../op";
 import type { LexiconPlugin } from "../../lexicon";
 import { formatError, formatWarning, formatSuccess } from "../format";
-import type { CommandContext } from "../registry";
+import type { CommandContext, ParsedArgs } from "../registry";
 
 const execAsync = promisify(exec);
 const execFileAsync = promisify(execFile);
@@ -116,13 +116,60 @@ export function parsePortMappings(values: readonly string[], targets: readonly E
   return ports;
 }
 
+/** The `up` options other than the port (#3952), per selected emulator. */
+type UpOptions = Pick<EmulatorUpArgs, "image" | "network" | "settings" | "loopback">;
+
+/**
+ * `--image`, `--network`, `--setting` and `--loopback` as each selected
+ * emulator's `up` options (#3952). `--image` needs exactly one emulator
+ * selected, the way a bare `--port` does. A `--setting` goes to each emulator
+ * whose settings prefix its key starts with, and a key that no selected
+ * emulator takes is refused rather than passed to a container as plain env.
+ */
+export function parseUpOptions(
+  args: Pick<ParsedArgs, "image" | "network" | "setting" | "loopback">,
+  targets: readonly EmulatorCapability[],
+): Map<EmulatorCapability, UpOptions> {
+  if (args.image !== undefined && targets.length !== 1) {
+    throw new Error(`--image ${args.image} is ambiguous with ${targets.length} emulators selected; pick one with --lexicon <name>`);
+  }
+  const settings = new Map<EmulatorCapability, Record<string, string>>();
+  for (const value of args.setting ?? []) {
+    const match = /^([^=]+)=(.*)$/s.exec(value);
+    if (!match) throw new Error(`--setting ${value}: expected <KEY>=<VALUE>, e.g. --setting FLOCI_<NAME>=<value>`);
+    const [, key, val] = match as unknown as [string, string, string];
+    const takers = targets.filter((t) => t.spec.settingsPrefix && key.startsWith(t.spec.settingsPrefix));
+    if (takers.length === 0) {
+      const prefixes = targets.filter((t) => t.spec.settingsPrefix).map((t) => `${t.spec.settingsPrefix}* (${t.spec.name})`);
+      throw new Error(`--setting ${key}: no selected emulator takes it; ${prefixes.length ? `the selected ones take ${prefixes.join(", ")}` : "the selected ones take no settings"}`);
+    }
+    for (const t of takers) {
+      const own = { ...settings.get(t), [key]: val };
+      checkSettings(t.spec, own);
+      settings.set(t, own);
+    }
+  }
+  const out = new Map<EmulatorCapability, UpOptions>();
+  for (const t of targets) {
+    const opts: UpOptions = {};
+    if (args.image !== undefined) opts.image = args.image;
+    if (args.network !== undefined) opts.network = args.network;
+    if (args.loopback) opts.loopback = true;
+    const own = settings.get(t);
+    if (own) opts.settings = own;
+    out.set(t, opts);
+  }
+  return out;
+}
+
 /**
  * `chant emulator --help` (#3673): the subcommands and flags, and for each
  * configured lexicon's emulator the port, endpoint and sign-in a client uses.
  */
 export function formatEmulatorHelp(plugins: readonly LexiconPlugin[]): string {
   const lines = [
-    "Usage: chant emulator <up|down|status> [--lexicon <name>] [--port <container-port>=<host-port>] [--json]",
+    "Usage: chant emulator <up|down|status> [--lexicon <name>] [--port <container-port>=<host-port>] [--image <ref>]",
+    "       [--network <name>] [--setting <KEY>=<VALUE>] [--loopback] [--json]",
     "",
     "Boot, stop or inspect the local emulators of the project's configured lexicons.",
     "",
@@ -137,6 +184,11 @@ export function formatEmulatorHelp(plugins: readonly LexiconPlugin[]): string {
     "  --lexicon <name>     Act on one lexicon's emulators only.",
     "  --port <c>=<h>       up: publish container port <c> on host port <h>; repeatable.",
     "                       A bare <h> works when one emulator is selected.",
+    "  --image <ref>        up: start this image instead of the pinned default; one emulator only.",
+    "  --network <name>     up: join each started container to this Docker network.",
+    "  --setting <K>=<V>    up: pass an emulator setting as -e K=V; repeatable. The key must",
+    "                       start with the emulator's prefix (FLOCI_ for aws).",
+    "  --loopback           up: publish ports on 127.0.0.1 only, not on every interface.",
     "  --json               Print the machine-readable report on stdout.",
     "",
   ];
@@ -195,9 +247,18 @@ export async function runEmulator(ctx: CommandContext): Promise<number> {
   }
 
   let ports: Map<number, number>;
+  let upOptions: Map<EmulatorCapability, UpOptions>;
   try {
     if (args.port?.length && action !== "up") throw new Error("--port applies to `chant emulator up` only");
+    const upOnly = [
+      args.image !== undefined && "--image",
+      args.network !== undefined && "--network",
+      args.setting?.length && "--setting",
+      args.loopback && "--loopback",
+    ].filter(Boolean);
+    if (upOnly.length && action !== "up") throw new Error(`${upOnly.join(", ")} applies to \`chant emulator up\` only`);
     ports = parsePortMappings(args.port ?? [], targets.map((t) => t.cap));
+    upOptions = parseUpOptions(args, targets.map((t) => t.cap));
   } catch (err) {
     console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
     return 1;
@@ -209,7 +270,7 @@ export async function runEmulator(ctx: CommandContext): Promise<number> {
     if (action === "up") {
       const port = ports.get(cap.spec.containerPort);
       try {
-        const { endpoint } = await lc.up(port === undefined ? {} : { port });
+        const { endpoint } = await lc.up({ ...upOptions.get(cap), ...(port === undefined ? {} : { port }) });
         reports.push({ lexicon, name: cap.spec.name, endpoint, env: cap.env(endpoint) });
       } catch (err) {
         console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));

package/src/cli/handlers/graph.ts

@@ -2,7 +2,7 @@ import { dirname, resolve } from "node:path";
 import { discoverOps } from "../../op/discover";
 import { discover } from "../../discovery/index";
 import { partitionByLexicon, computeStackGraph, build, mergeBuildRootEntities } from "../../build";
-import { applyLexiconGraphEdges, buildGraphIr, buildLiveGraphIr, collectUnobserved, overlayGraphs, sourceOverlayGraphs, GRAPH_IR_VERSION, type GraphIR, type IRPipeline, type LexiconGraphEdges, type LiveObservation } from "../../graph-ir";
+import { applyLexiconGraphEdges, applyLexiconOutputs, buildGraphIr, buildLiveGraphIr, collectUnobserved, overlayGraphs, sourceOverlayGraphs, GRAPH_IR_VERSION, type GraphIR, type IRPipeline, type LexiconGraphEdges, type LexiconWorkspaceOutputs, type LiveObservation } from "../../graph-ir";
 import { behaviourOverlay } from "../../behaviour-overlay";
 import type { SerializerResult } from "../../serializer";
 import { applyBehaviourOverlay, behaviourRequestFromIr } from "../../behaviour-graph";
@@ -746,6 +746,26 @@ function withLexiconEdges(ir: GraphIR, plugins: LexiconPlugin[], entities: Map<s
   return reports.length === 0 ? ir : applyLexiconGraphEdges(ir, reports);
 }
 
+/**
+ * Add the outputs the lexicons' `workspaceOutputs` hooks report (#3931) to
+ * the IR's `exports`: a sql table and each of its columns, which `chant
+ * workspace graph` resolves member links against. A hook that throws costs
+ * its own outputs and a warning, not the graph.
+ */
+function withLexiconOutputs(ir: GraphIR, plugins: LexiconPlugin[], entities: Map<string, import("../../declarable").Declarable>): GraphIR {
+  const reports: LexiconWorkspaceOutputs[] = [];
+  for (const p of plugins) {
+    if (!p.workspaceOutputs) continue;
+    try {
+      const report = p.workspaceOutputs(entities);
+      if (report) reports.push(report);
+    } catch (err) {
+      console.error(formatWarning({ message: `the ${p.name} lexicon's workspaceOutputs failed (${err instanceof Error ? err.message : String(err)}); its outputs are left out` }));
+    }
+  }
+  return reports.length === 0 ? ir : applyLexiconOutputs(ir, reports);
+}
+
 /** Returned instead of a graph when the prediction cannot be attempted honestly. */
 const REFUSED = Symbol("behaviour-refused");
 
@@ -888,6 +908,7 @@ async function runGraphView(
       ? ctx.plugins
       : await loadPlugins(await projectLexiconsOrNone(projectPath));
     ir = withLexiconEdges(ir, plugins as LexiconPlugin[], result.entities);
+    ir = withLexiconOutputs(ir, plugins as LexiconPlugin[], result.entities);
     const predicted = await predictOntoIr(ir, plugins as LexiconPlugin[], ctx.args, {
       // No environment on the declared path: the file is not deployed anywhere
       // yet, and naming one would claim it was.

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

@@ -39,6 +39,7 @@ vi.mock("../../config", async () => {
 });
 
 vi.mock("../../components/cli-support", () => ({
+  isComponentList: (selector: string) => selector.includes(","),
   resolveComponentTargets: (...args: unknown[]) => resolveTargetsMock(...args),
 }));
 
@@ -286,6 +287,12 @@ describe("chant components rollback", () => {
     expect(appendReleaseRecordMock.mock.calls[0][0]).not.toHaveProperty("promotedFrom");
   });
 
+  test("a comma list is refused: rollback acts on one component (#3950)", async () => {
+    expect(await runComponentsRollback(rb({ component: "api,web" }))).toBe(1);
+    expect(errors.join("\n")).toMatch(/--component takes one component name, not a list/);
+    expect(ran).toEqual([]);
+  });
+
   test("a digest the environment never recorded fails clearly", async () => {
     expect(await runComponentsRollback(rb({ digest: "sha256:elsewhere" }))).toBe(1);
     expect(errors.join("\n")).toMatch(/sha256:elsewhere is not recorded for "api" in "prod"/);

package/src/cli/handlers/promote.ts

@@ -25,7 +25,7 @@ import {
   type ReleaseRecord,
   type ReleaseRecordInput,
 } from "../../lifecycle/release-ledger";
-import { resolveComponentTargets } from "../../components/cli-support";
+import { isComponentList, resolveComponentTargets } from "../../components/cli-support";
 import { applyConfigDefaults } from "../../components/config-defaults";
 import { fanOutRegistry } from "../../components/fan-out-support";
 import { renderDriverHuman } from "../../components/driver-output";
@@ -107,6 +107,12 @@ async function loadProject(ctx: CommandContext, selector: string) {
     for (const message of paramsResolution.errors) console.error(message);
     return 1;
   }
+  // A comma list is `chant run --components`' selector (#3950), which pulls in
+  // dependencies; promote, rollback and redeploy act on the one named component.
+  if (isComponentList(selector)) {
+    console.error(formatError({ message: `--component takes one component name, not a list ("${selector}")` }));
+    return 1;
+  }
   const targets = await resolveComponentTargets(projectPath, selector, args.sandbox, paramsResolution.provenance);
   if (!targets.success) {
     console.error(formatError({ message: targets.error ?? "Could not discover components" }));

package/src/cli/handlers/run-no-record.e2e.test.ts

@@ -0,0 +1,87 @@
+/**
+ * #3955 — `chant run <op> --no-record` through the real CLI: the run executes,
+ * says at its start and end that it recorded nothing, and leaves
+ * `chant/lifecycle` where it was, both in the checkout and on origin. A plain
+ * run beside it records, so the unchanged ref is the flag's doing.
+ */
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { cleanScratch, commitAll, git, repo, REPO } from "../../workspace/__fixtures__/contract-repo";
+import { pushLifecycleStatus, writeBlobToPath } from "../../lifecycle/git";
+
+const MAIN = join(REPO, "packages/core/src/cli/main.ts");
+const LOADER = pathToFileURL(join(REPO, "node_modules/tsx/dist/loader.mjs")).href;
+
+/** An Op entity as `Op()` exports it, written as a literal so the fixture needs no import to resolve. */
+function opModule(name: string, steps: unknown[]): string {
+  return `export const op = ${JSON.stringify({ entityType: "Chant::Op", props: { name, overview: name, phases: [{ name: "Main", steps }] } })};\n`;
+}
+
+const SHELL = { kind: "activity", fn: "shellCmd", profile: "atMostOnce", args: { cmd: "echo ran" } };
+
+let dir: string;
+let remote: string;
+
+beforeAll(async () => {
+  remote = repo({}, false);
+  git(remote, "config", "core.bare", "true");
+  dir = repo(
+    {
+      "chant.config.ts": "export default { lexicons: [] };\n",
+      "ops/hello.op.ts": opModule("hello", [SHELL]),
+      "ops/gated.op.ts": opModule("gated", [{ kind: "gate", gate: "approve-prod" }, SHELL]),
+    },
+    false,
+  );
+  git(dir, "config", "user.name", "Run Test");
+  git(dir, "config", "user.email", "run@example.com");
+  commitAll(dir, "c0");
+  git(dir, "remote", "add", "origin", join(remote, ".git"));
+  await writeBlobToPath("seed", "seed.json", "{}\n", "seed", { cwd: dir });
+  expect((await pushLifecycleStatus({ cwd: dir })).status).toBe("pushed");
+});
+afterAll(cleanScratch);
+
+function chant(args: string[], env: Record<string, string> = {}): { status: number | null; stderr: string } {
+  const r = spawnSync(process.execPath, ["--import", LOADER, MAIN, ...args], {
+    cwd: dir,
+    encoding: "utf8",
+    env: { ...process.env, NO_COLOR: "1", TSX_DISABLE_CACHE: "1", CHANT_NO_RECORD: "", ...env },
+  });
+  return { status: r.status, stderr: r.stderr };
+}
+
+function ledgerRefs(): { local: string; origin: string } {
+  return { local: git(dir, "rev-parse", "refs/heads/chant/lifecycle"), origin: git(dir, "ls-remote", "origin", "refs/heads/chant/lifecycle").split(/\s/)[0]! };
+}
+
+describe("chant run --no-record (#3955)", () => {
+  test("runs the Op, says so at the start and the end, and leaves the ledger ref unchanged here and on origin", () => {
+    const before = ledgerRefs();
+    const r = chant(["run", "hello", "--no-record"]);
+    expect(r.status, r.stderr).toBe(0);
+    expect(r.stderr).toContain("not recording (--no-record): nothing this run writes goes on chant/lifecycle");
+    expect(r.stderr).toMatch(/not recorded \(--no-record\): nothing went on chant\/lifecycle and nothing was pushed; 1 ledger write was dropped \(1 file\)/);
+    expect(ledgerRefs()).toEqual(before);
+  });
+
+  test("CHANT_NO_RECORD=1 fails a gate without writing a pending fact", () => {
+    const before = ledgerRefs();
+    const r = chant(["run", "gated"], { CHANT_NO_RECORD: "1" });
+    expect(r.status).toBe(1);
+    expect(r.stderr).toContain('gate "approve-prod" of "gated" cannot be passed under --no-record');
+    expect(r.stderr).toContain("not recorded (CHANT_NO_RECORD=1)");
+    expect(ledgerRefs()).toEqual(before);
+  });
+
+  test("a plain run of the same Op records its run", () => {
+    const before = ledgerRefs();
+    const r = chant(["run", "hello"]);
+    expect(r.status, r.stderr).toBe(0);
+    expect(r.stderr).not.toContain("not recording");
+    // The run record moves the local branch; it is pushed by the next write that pushes.
+    expect(ledgerRefs().local).not.toBe(before.local);
+  });
+});

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

@@ -29,16 +29,16 @@ export async function runOpWaveCommand(ctx: CommandContext): Promise<number> {
   if (!specFile || args.wave === undefined) {
     console.error(formatError({
       message: "`chant run wave` needs --spec <file> and --wave <k>",
-      hint: "Run it as a generated Op waves pipeline does: chant run wave --spec <file> --wave <k> [--decide | --share <i>]",
+      hint: "Run it as a generated Op waves pipeline does: chant run wave --spec <file> --wave <k> [--decide | --share <i> | --group <name> [--share <i>]]",
     }));
     return 1;
   }
-  if (args.decide && args.share !== undefined) {
-    console.error(formatError({ message: "--decide and --share are two different jobs; pass one" }));
+  if (args.decide && (args.share !== undefined || args.group !== undefined)) {
+    console.error(formatError({ message: `--decide and --${args.share !== undefined ? "share" : "group"} are two different jobs; pass one` }));
     return 1;
   }
   let spec: OpWavesSpec | undefined;
-  const job = args.share !== undefined ? { share: args.share } : {};
+  const job = { ...(args.share !== undefined ? { share: args.share } : {}), ...(args.group !== undefined ? { group: args.group } : {}) };
   try {
     const path = resolve(specFile);
     spec = parseOpWavesSpec(readFileSync(path, "utf-8"), `--spec ${specFile}`);
@@ -48,6 +48,7 @@ export async function runOpWaveCommand(ctx: CommandContext): Promise<number> {
       wave: args.wave,
       ...(args.decide ? { decide: true } : {}),
       ...(args.share !== undefined ? { share: args.share } : {}),
+      ...(args.group !== undefined ? { group: args.group } : {}),
       ...(args.base ? { base: args.base } : {}),
     });
     if (args.json) console.log(JSON.stringify(result, null, 2));