@intentius/chant 0.124.15 → 0.124.17

package/src/components/discover.ts

@@ -51,6 +51,7 @@ import { hasDiscoveryMarkerSync } from "../discovery/files";
 import { resolveDiscoveryGlobs } from "../config";
 import { walkDiscovery, workspaceMemberDirs } from "../discovery/walk";
 import { ensureTypeScriptLoader } from "../ts-loader";
+import { esModuleNamespace } from "../module-interop";
 
 /** One discovered component, paired with the file it was exported from. */
 export interface DiscoveredComponent {
@@ -214,7 +215,7 @@ async function importAndCollectComponents(
       // a bare "." path) would otherwise be treated by `import()` as a bare
       // package specifier and fail with "Cannot find package 'x.component.ts'".
       ensureTypeScriptLoader();
-      const exports = await import(pathToFileURL(resolve(filePath)).href);
+      const exports = esModuleNamespace(await import(pathToFileURL(resolve(filePath)).href));
       modules.push({ file: filePath, exports });
     } catch (err) {
       importErrors.push(new DiscoveryError(filePath, err instanceof Error ? err.message : String(err), "import"));

package/src/components/fan-out-record.ts

@@ -27,9 +27,8 @@
  * per-wave CI job hands to the next.
  */
 
-import { dirname } from "node:path";
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { readWaveRecords, type WaveRecord } from "../gated-waves";
+import { existsSync, readFileSync } from "node:fs";
+import { readWaveRecords, writeWaveRecordFile, type WaveRecord } from "../wave-engine";
 import type { ChangeSetDocument } from "../change-set";
 import type { PrMember } from "../pr-loop";
 
@@ -126,8 +125,5 @@ export function readFanOutAttempt(path: string): FanOutAttempt | undefined {
  * write leaves the previous record whole rather than half a JSON document.
  */
 export function writeFanOutAttempt(path: string, attempt: FanOutAttempt): void {
-  mkdirSync(dirname(path), { recursive: true });
-  const temporary = `${path}.${process.pid}.tmp`;
-  writeFileSync(temporary, JSON.stringify(attempt, null, 2) + "\n");
-  renameSync(temporary, path);
+  writeWaveRecordFile(path, attempt);
 }

package/src/components/fan-out-run.ts

@@ -31,8 +31,10 @@
  * ## Or one approval per wave
  *
  * `waveGate` (#3049) is the other mode. Each wave is planned once the waves
- * before it applied, and its gate binds that wave's set digest
- * (`../gated-waves.ts`). See {@link runGatedWaves}.
+ * before it applied, and its gate binds that wave's set digest. Gate names,
+ * the digest and the gate decision come from the wave engine
+ * (`../wave-engine.ts`, #3766), which `chant run wave` uses too. See
+ * {@link runGatedWaves}.
  */
 
 import {
@@ -50,7 +52,7 @@ import type { CapabilityRegistry } from "./capability";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import type { DeployContext } from "./capability";
 import { planWaveComponent, type WaveComponentPlan } from "./wave-plan";
-import { waveGateName, waveSetDigest, type WaveMember, type WaveRecord } from "../gated-waves";
+import { decideWaveGate, waveGateName, waveSetDigest, type WaveMember, type WaveRecord } from "../wave-engine";
 
 /**
  * One gate per wave (#3049), each bound to its wave's set digest. The other
@@ -452,10 +454,10 @@ async function runGatedWaves(
       continue;
     }
 
-    const check = await evaluateGate(gates.port, {
+    const check = await decideWaveGate(gates.port, {
       op: waveGate.op,
       gate: gateName,
-      planDigest: digest,
+      digest,
       description: waveGate.description ?? `wave ${waveNum} of ${plan.waves.length}: ${toRun.join(", ")}`,
       ...(waveGate.timeout ? { timeout: waveGate.timeout } : {}),
       ...(options.now ? { now: options.now } : {}),

package/src/config-sandbox.ts

@@ -1,5 +1,6 @@
 import { dirname } from "node:path";
 import { importConfigModule, requireConfigModule, type ConfigModuleNamespace } from "./config-import";
+import { esModuleNamespace } from "./module-interop";
 
 /**
  * chant #1113 — decides WHERE a project's `chant.config.ts` is evaluated.
@@ -84,7 +85,10 @@ export function resetSandboxConfigEvaluationForTests(): void {
  * evaluated, never how its result is read.
  */
 export function selectConfigExport(namespace: ConfigModuleNamespace): unknown {
-  return namespace.default ?? namespace.config ?? namespace;
+  // A config tsx compiled as CommonJS arrives as `{ default: module.exports }`
+  // under a native import (#3897); read the module's own namespace instead.
+  const ns = esModuleNamespace(namespace);
+  return ns.default ?? ns.config ?? ns;
 }
 
 /**

package/src/discovery/import.ts

@@ -1,5 +1,6 @@
 import { DiscoveryError } from "../errors";
 import { ensureTypeScriptLoader } from "../ts-loader";
+import { esModuleNamespace } from "../module-interop";
 
 /**
  * Modules whose evaluation threw, and the error each threw with (#2368).
@@ -59,7 +60,7 @@ export async function importModule(
 
   try {
     ensureTypeScriptLoader();
-    return await import(path);
+    return esModuleNamespace(await import(path));
   } catch (error) {
     const message =
       error instanceof Error ? error.message : "Unknown import error";

package/src/discovery/sandbox/driver.ts

@@ -59,6 +59,8 @@ const POST_SYNTH_MODULE = join(dirname(DISCOVERY_DIR), "lint", "post-synth.ts");
 // file, so the driver's `setBuildParams` call below mutates the one object
 // every bundled import observes.
 const PARAMS_MODULE = join(dirname(DISCOVERY_DIR), "params.ts");
+// #3897: a project file tsx compiled as CommonJS reads as its own namespace.
+const INTEROP_MODULE = join(dirname(DISCOVERY_DIR), "module-interop.ts");
 
 export interface GenerateDriverOptions {
   /** Absolute paths to the run-fallback files this build decided NOT to fold — see `discover()`'s fold/taint loop in `../index.ts`. */
@@ -130,6 +132,7 @@ export function generateDriverSource(options: GenerateDriverOptions): string {
     `import { classifyChildError } from ${lit(CHILD_ERRORS_MODULE)};`,
     `import { getProvenance } from ${lit(PROVENANCE_MODULE)};`,
     `import { setBuildParams } from ${lit(PARAMS_MODULE)};`,
+    `import { esModuleNamespace } from ${lit(INTEROP_MODULE)};`,
     `import { writeSync } from "node:fs";`,
     ``,
     `const BUILD_ROOT = ${lit(buildRoot)};`,
@@ -181,7 +184,7 @@ export function generateDriverSource(options: GenerateDriverOptions): string {
     lines.push(
       `  importing = ${lit(file)};`,
       `  try {`,
-      `    const mod = await import(${lit(file)});`,
+      `    const mod = esModuleNamespace(await import(${lit(file)}));`,
       `    modules.push({ file: ${lit(file)}, exports: mod });`,
       `  } catch (err) {`,
       `    errors.push(classifyChildError(${lit(file)}, err).toJSON());`,
@@ -261,6 +264,7 @@ export function generateConfigDriverSource(configPath: string): string {
   return [
     `import { classifyChildError } from ${lit(CHILD_ERRORS_MODULE)};`,
     `import { scanConfigWireSafety } from ${lit(CONFIG_WIRE_MODULE)};`,
+    `import { esModuleNamespace } from ${lit(INTEROP_MODULE)};`,
     `import { writeSync } from "node:fs";`,
     ``,
     ...sendFunctionSource(),
@@ -268,7 +272,7 @@ export function generateConfigDriverSource(configPath: string): string {
     `async function main() {`,
     `  let namespace;`,
     `  try {`,
-    `    namespace = await import(${lit(configPath)});`,
+    `    namespace = esModuleNamespace(await import(${lit(configPath)}));`,
     `  } catch (err) {`,
     `    await send({ kind: "chant-config", ok: false, error: classifyChildError(${lit(configPath)}, err).toJSON() });`,
     `    return;`,
@@ -337,6 +341,7 @@ export function generatePolicyDriverSource(policyPaths: readonly string[]): stri
     `import { classifyChildError } from ${lit(CHILD_ERRORS_MODULE)};`,
     `import { decodePolicyBuildResult, scanPolicyDiagnostics, PolicyWireError } from ${lit(POLICY_WIRE_MODULE)};`,
     `import { runPostSynthChecks, isPostSynthCheck } from ${lit(POST_SYNTH_MODULE)};`,
+    `import { esModuleNamespace } from ${lit(INTEROP_MODULE)};`,
     `import { writeSync } from "node:fs";`,
     ``,
     ...sendFunctionSource(),
@@ -382,7 +387,7 @@ export function generatePolicyDriverSource(policyPaths: readonly string[]): stri
   for (const policyPath of policyPaths) {
     lines.push(
       `  try {`,
-      `    const mod = await import(${lit(policyPath)});`,
+      `    const mod = esModuleNamespace(await import(${lit(policyPath)}));`,
       `    for (const value of Object.values(mod)) {`,
       `      if (isPostSynthCheck(value)) checks.push(guard(value, ${lit(policyPath)}));`,
       `    }`,

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

@@ -46,6 +46,7 @@ describe("the gate-decision bundle", () => {
       "packages/core/src/notify.ts",
       "packages/core/src/op/gate-point.ts",
       "packages/core/src/op/op-waves.ts",
+      "packages/core/src/wave-layout.ts",
       "packages/core/src/workspace/class-data.ts",
       "packages/core/src/workspace/identity-gate-rule.ts",
       "packages/core/src/workspace/jsonc.ts",

package/src/gated-waves.ts

@@ -2,12 +2,17 @@
  * Gated waves (#3049): one change rolled out across many roots, a wave at a
  * time, each wave behind its own gate bound to that wave's set digest.
  *
- * `chant components fan-out --wave-gate` is the runner. This module holds the
- * parts that need no runner: how a set of roots is cut into waves, what a
- * wave's digest is, what its gate is called, and what the attempt record says
- * about each wave. They are kept apart from the runner because terragucci
- * calls them from its CI stages as one bundled file with no TypeScript
- * toolchain (#3421). Everything here imports `./change-set` and nothing else,
+ * Two runners use it (#3766): `chant components fan-out --wave-gate` and the
+ * Op waves spec's `chant run wave` (`./op/op-waves-run.ts`). This module
+ * holds the parts that need no runner: how a set of roots is cut into waves,
+ * what a wave's digest is and which members it covers, what its gate is
+ * called, and what the attempt record says about each wave. A gate name
+ * pattern and the share split of a wide wave are in `./wave-layout.ts`;
+ * `./wave-engine.ts` puts them together with the gate decision call and the
+ * record file writer, which need the gate ledger and the filesystem.
+ *
+ * They are kept apart from the runners because terragucci calls them from
+ * its CI stages as one bundled file with no TypeScript toolchain (#3421). Everything here imports `./change-set` and nothing else,
  * and `gated-waves-bundle.test.ts` holds that.
  *
  * ## The set digest
@@ -144,6 +149,23 @@ export function waveGateName(gate: string, wave: number): string {
   return `${gate}-wave-${wave}`;
 }
 
+/** Which members a wave's set digest covers (#3821). */
+export type WaveDigestOver = "all" | "changing";
+
+/**
+ * The members a wave's set digest is taken over (#3821, #3766). `all` (the
+ * default): every member. `changing`: the members whose plan is not
+ * `empty`, or every member when all of them are empty. `extras`, members
+ * that are no run (such as a wave's cost), are always in it.
+ */
+export function waveDigestMembers<M extends WaveMember & { empty?: boolean }>(
+  members: readonly M[],
+  options: { over?: WaveDigestOver; extras?: readonly WaveMember[] } = {},
+): WaveMember[] {
+  const changing = options.over === "changing" ? members.filter((m) => m.empty !== true) : [];
+  return [...(changing.length > 0 ? changing : members), ...(options.extras ?? [])];
+}
+
 /** Where a wave got to. */
 export type WaveStatus =
   /** Planned, and its gate is not approved for this digest. Nothing in it ran. */

package/src/lexicon-module.ts

@@ -28,6 +28,7 @@ import { createRequire } from "node:module";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 import { ensureTypeScriptLoader } from "./ts-loader";
+import { esModuleNamespace } from "./module-interop";
 
 /**
  * One `lexicons` entry: a package-backed name, or a name plus the module that
@@ -181,7 +182,7 @@ export async function importLexiconModule(name: string): Promise<Record<string,
   if (path === undefined) return undefined;
   try {
     ensureTypeScriptLoader();
-    return (await import(path)) as Record<string, unknown>;
+    return esModuleNamespace((await import(path)) as Record<string, unknown>);
   } catch (err) {
     throw new Error(
       `lexicon "${name}" is declared with module ${path}, which could not be loaded: ` +
@@ -262,12 +263,12 @@ export function resolveFromProject(spec: string, fromDir: string = process.cwd()
 export async function importLexiconPackage(spec: string, fromDir: string = process.cwd()): Promise<Record<string, unknown>> {
   try {
     ensureTypeScriptLoader();
-    return (await import(spec)) as Record<string, unknown>;
+    return esModuleNamespace((await import(spec)) as Record<string, unknown>);
   } catch (err) {
     const pkg = packageNameOf(spec);
     if (pkg === undefined || !isPackageNotFound(err, pkg)) throw err;
     const resolved = resolveFromProject(spec, fromDir);
     if (resolved === undefined) throw err;
-    return (await import(pathToFileURL(resolved).href)) as Record<string, unknown>;
+    return esModuleNamespace((await import(pathToFileURL(resolved).href)) as Record<string, unknown>);
   }
 }

package/src/lint/policy-import.ts

@@ -24,6 +24,7 @@
  */
 
 import { ensureTypeScriptLoader } from "../ts-loader";
+import { esModuleNamespace } from "../module-interop";
 
 /** Whether this process must run project policy modules inside the sandbox boundary instead of here. */
 let armed = false;
@@ -69,5 +70,5 @@ export async function importPolicyModule(policyPath: string): Promise<PolicyModu
     );
   }
   ensureTypeScriptLoader();
-  return (await import(policyPath)) as PolicyModuleNamespace;
+  return esModuleNamespace((await import(policyPath)) as PolicyModuleNamespace);
 }

package/src/lint/rule-loader.ts

@@ -2,6 +2,7 @@ import { readdirSync, existsSync } from "fs";
 import { dirname, join, resolve } from "path";
 import type { LintRule } from "./rule";
 import { ensureTypeScriptLoader } from "../ts-loader";
+import { esModuleNamespace } from "../module-interop";
 
 /**
  * Type guard to check if a value conforms to the LintRule interface.
@@ -84,7 +85,7 @@ export async function loadLocalRules(projectDir: string): Promise<LintRule[]> {
     let mod: Record<string, unknown>;
     try {
       ensureTypeScriptLoader();
-      mod = await import(filePath);
+      mod = esModuleNamespace(await import(filePath));
     } catch (err) {
       throw new Error(
         `Failed to load rule file "${file}": ${err instanceof Error ? err.message : String(err)}`,

package/src/module-interop.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "vitest";
+import { selectConfigExport } from "./config-sandbox";
+import { esModuleNamespace } from "./module-interop";
+
+/** What node's native import() hands back for a CommonJS module tsx compiled from `export default`. */
+function commonJsNamespace(exports: Record<string, unknown>): Record<string, unknown> {
+  const moduleExports: Record<string, unknown> = { ...exports };
+  Object.defineProperty(moduleExports, "__esModule", { value: true });
+  return { ...exports, default: moduleExports };
+}
+
+describe("esModuleNamespace (#3897)", () => {
+  test("a CommonJS __esModule namespace reads as the module's own exports", () => {
+    const config = { lexicons: ["terraform"] };
+    const helper = () => 1;
+    const ns = esModuleNamespace(commonJsNamespace({ default: config, helper }));
+    expect(ns.default).toBe(config);
+    expect(ns.helper).toBe(helper);
+    expect(Object.keys(ns)).not.toContain("__esModule");
+  });
+
+  test("a CommonJS module with no default export has none after unwrapping", () => {
+    const ns = esModuleNamespace(commonJsNamespace({ config: { lexicons: ["aws"] } }));
+    expect(ns.default).toBeUndefined();
+    expect(ns.config).toEqual({ lexicons: ["aws"] });
+  });
+
+  test("an enumerable __esModule marker is left out too", () => {
+    const ns = esModuleNamespace({ default: { __esModule: true, default: 1 } });
+    expect(ns).toEqual({ default: 1 });
+  });
+
+  test("an ES module whose default export has a default key is unchanged", () => {
+    const namespace = { default: { default: { lexicons: ["aws"] } } };
+    expect(esModuleNamespace(namespace)).toBe(namespace);
+  });
+
+  test("a default without the marker set to true is unchanged", () => {
+    const namespace = { default: { __esModule: "yes", default: 1 } };
+    expect(esModuleNamespace(namespace)).toBe(namespace);
+    const primitive = { default: 3 };
+    expect(esModuleNamespace(primitive)).toBe(primitive);
+    const empty = {};
+    expect(esModuleNamespace(empty)).toBe(empty);
+  });
+});
+
+describe("selectConfigExport (#3897)", () => {
+  test("a config tsx compiled as CommonJS selects the config object, not {default: config}", () => {
+    const config = { lexicons: ["terraform"], terraform: { roots: { estate: { dir: "estate" } } } };
+    expect(selectConfigExport(commonJsNamespace({ default: config }))).toBe(config);
+  });
+
+  test("an ES module config that legitimately has a default key keeps it", () => {
+    const config = { default: { lexicons: ["aws"] }, lexicons: ["aws"] };
+    expect(selectConfigExport({ default: config })).toBe(config);
+  });
+
+  test("a require()d CommonJS config still selects its default", () => {
+    const config = { lexicons: ["aws"] };
+    const moduleExports: Record<string, unknown> = { default: config };
+    Object.defineProperty(moduleExports, "__esModule", { value: true });
+    expect(selectConfigExport(moduleExports)).toBe(config);
+  });
+});

package/src/module-interop.ts

@@ -0,0 +1,39 @@
+/**
+ * The namespace a project module was authored with, whichever module format
+ * tsx compiled it to (#3897).
+ *
+ * A `.ts` file with no `"type": "module"` `package.json` above it is compiled
+ * by tsx as CommonJS: `exports.default = ...` plus a non-enumerable
+ * `__esModule: true` marker. The compiled CLI loads project files with a
+ * native `import()`, and Node hands a CommonJS module back as a namespace
+ * whose `default` is the whole `module.exports`. So `export default x` arrives
+ * as `namespace.default.default`. Under the source CLI tsx's ESM loader sits
+ * in front of the `import()` and does this interop itself, which is why the
+ * nesting only showed up once the CLI ran compiled (#3879).
+ *
+ * When `namespace.default` carries the `__esModule` marker, the module's real
+ * namespace is that exports object: this returns a copy of it with the marker
+ * left out. Anything else, including an ES module whose default export is an
+ * object that happens to have a `default` key, is returned unchanged.
+ */
+export function esModuleNamespace<T extends Record<string, unknown>>(namespace: T): T {
+  // `in` before the read: a vitest factory mock throws on reading an export
+  // it does not define, and most modules have no `default` at all.
+  if (namespace === null || typeof namespace !== "object" || !("default" in namespace)) return namespace;
+  const exported = namespace.default;
+  if (!isCommonJsEsModule(exported)) return namespace;
+  const unwrapped: Record<string, unknown> = {};
+  for (const key of Object.keys(exported)) {
+    if (key !== "__esModule") unwrapped[key] = exported[key];
+  }
+  return unwrapped as T;
+}
+
+/** A CommonJS `module.exports` that a compiler marked as an ES module. */
+function isCommonJsEsModule(value: unknown): value is Record<string, unknown> {
+  return (
+    value !== null &&
+    (typeof value === "object" || typeof value === "function") &&
+    (value as { __esModule?: unknown }).__esModule === true
+  );
+}

package/src/op/discover.ts

@@ -7,6 +7,7 @@ import { hasDiscoveryMarkerSync } from "../discovery/files";
 import { resolveDiscoveryGlobs } from "../config";
 import { isStewardDeclaration, type StewardDeclaration } from "./steward";
 import { ensureTypeScriptLoader } from "../ts-loader";
+import { esModuleNamespace } from "../module-interop";
 
 export interface DiscoveredOp {
   config: OpConfig;
@@ -152,7 +153,7 @@ export async function discoverOps(opts?: { cwd?: string }): Promise<OpDiscoveryR
   for (const filePath of files) {
     try {
       ensureTypeScriptLoader();
-      const mod = (await import(filePath)) as Record<string, unknown>;
+      const mod = esModuleNamespace((await import(filePath)) as Record<string, unknown>);
       const exported = opsExportedBy(mod);
 
       // A file may hold a steward and no Op (#2731): the steward sits beside
@@ -223,7 +224,7 @@ export async function discoverStewards(opts?: { cwd?: string }): Promise<Steward
     let mod: Record<string, unknown>;
     try {
       ensureTypeScriptLoader();
-      mod = (await import(filePath)) as Record<string, unknown>;
+      mod = esModuleNamespace((await import(filePath)) as Record<string, unknown>);
     } catch (err) {
       errors.push(`${filePath}: ${err instanceof Error ? err.message : String(err)}`);
       continue;

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

@@ -51,7 +51,7 @@
 import { execFileSync, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, posix } from "node:path";
-import { waveSetDigest, type WaveMember } from "../gated-waves";
+import { decideWaveGate, waveDigestMembers, waveSetDigest, writeWaveRecordFile, type WaveMember } from "../wave-engine";
 import type { ReviewApproval } from "../gate-decision";
 import { approveCommand, evaluateGate, gitGateLedgerPort, type GateCheck, type GateDigestMismatch, type GateLedgerPort } from "./gate";
 import type { GateAnswerRef, PendingGateRecord } from "../lifecycle/gate-ledger";
@@ -817,8 +817,7 @@ function pendingFields(value: unknown, where: string): Record<string, unknown> |
  * file's members that are no run (a cost), are always in it.
  */
 export function opWaveSetDigest(spec: Pick<OpWavesSpec, "digest">, members: ReadonlyArray<WaveMember & { empty?: boolean }>, extras: readonly WaveMember[] = []): string {
-  const changing = spec.digest?.over === "changing" ? members.filter((m) => m.empty !== true) : [];
-  return waveSetDigest([...(changing.length > 0 ? changing : members), ...extras]);
+  return waveSetDigest(waveDigestMembers(members, { ...(spec.digest?.over ? { over: spec.digest.over } : {}), extras }));
 }
 
 /** What one moment's hooks came to. */
@@ -1627,10 +1626,10 @@ async function settleGate(options: RunOpWaveOptions, ctx: WaveContext, decision:
   // #3784: under the spend rule at base, an approval a wave already applied under counts for nothing.
   const spent: AppliedGateRecord[] | undefined = decision.spend === "base" ? ((await ledger.readApplied?.(spec.name)) ?? []).filter((a) => a.gate === gate) : undefined;
   const held = decision.heldBy?.length ? `, held by ${decision.heldBy.join(", ")}` : "";
-  const check = await evaluateGate(port, {
+  const check = await decideWaveGate(port, {
     op: spec.name,
     gate,
-    planDigest: digest,
+    digest,
     description: (typeof decision.pending?.description === "string" ? decision.pending.description : undefined) ?? `wave ${k} (${wave.name}): ${members.length} run${members.length === 1 ? "" : "s"}, gate ${policy}, approval ${approval}${held}`,
     now,
     ...(spent ? { spent } : {}),
@@ -1728,7 +1727,7 @@ async function settlePointGate(options: RunOpWaveOptions, ctx: WaveContext, deci
 /** Write the decision record, with every hook's outcome so far (#3804). */
 function writeRecord(recordPath: string, decision: OpWaveDecision, result: RunOpWaveResult): void {
   if (result.hooks.length > 0) decision.outcomes = [...result.hooks];
-  writeFileSync(recordPath, JSON.stringify(decision, null, 2) + "\n");
+  writeWaveRecordFile(recordPath, decision);
 }
 
 /**

package/src/op/op-waves.ts

@@ -69,6 +69,7 @@
 import type { OpEnvironment, OpSetupStep } from "../lexicon";
 import { gatePointProblems, type GatePoint } from "./gate-point";
 import { notifyConfigProblem, type NotifyConfig } from "../notify";
+import { WAVE_GATE_NAME_PATTERN, waveGateNameFrom, waveShare } from "../wave-layout";
 
 /**
  * The variables a wave job reads its notify secrets from, for the lexicons
@@ -361,11 +362,11 @@ export interface OpWavesDigest {
 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}";
+export const OP_WAVE_DEFAULT_GATE_NAME = WAVE_GATE_NAME_PATTERN;
 
 /** 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));
+  return waveGateNameFrom(spec.gateName, spec.gate ?? spec.name, k);
 }
 
 /** Where a wave reads who may override a policy denial (#3821). */
@@ -638,12 +639,7 @@ export function opWaveApplyHooksRunBy(spec: Pick<OpWavesSpec, "hooks" | "waves">
  * by target, cut into contiguous slices whose sizes differ by at most one.
  */
 export function opWaveShare<T extends { target: string }>(runs: readonly T[], share: number, shares: number): T[] {
-  const sorted = [...runs].sort((a, b) => (a.target < b.target ? -1 : a.target > b.target ? 1 : 0));
-  const base = Math.floor(sorted.length / shares);
-  const extra = sorted.length % shares;
-  const start = (share - 1) * base + Math.min(share - 1, extra);
-  const size = base + (share <= extra ? 1 : 0);
-  return sorted.slice(start, start + size);
+  return waveShare(runs, share, shares, (run) => run.target);
 }
 
 /**

package/src/package-version.ts

@@ -0,0 +1,11 @@
+/**
+ * `@intentius/chant`'s own version, read from its package.json as a file. The
+ * path is the same from `src/` and `dist/`. The slim wave-job runtime (#3896)
+ * has no package.json beside it, and its build writes the version in here.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+export function readChantPackageVersion(): string {
+  return (JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf-8")) as { version: string }).version;
+}

package/src/wave-engine.test.ts

@@ -0,0 +1,107 @@
+/**
+ * One wave engine under both runners (#3766): the same runs, planned to the
+ * same digests, are the same set digest and the same gate name whether
+ * `chant run wave` (an Op waves spec) or `chant components fan-out
+ * --wave-gate` decides the wave. An approval recorded through one matches a
+ * wave the other plans.
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { describe, expect, test } from "vitest";
+import { memoryGateLedgerPort } from "./op/gate";
+import { runOpWave, type OpWaveExec, type OpWaveShowAtBase } from "./op/op-waves-run";
+import { opWaveGateName, opWaveShare, type OpWavesSpec } from "./op/op-waves";
+import { planFanOut } from "./components/fan-out";
+import { runFanOut } from "./components/fan-out-run";
+import { CapabilityRegistry } from "./components/capability";
+import type { DriverComponent } from "./components/driver";
+import { waveGateName, waveGateNameFrom, waveSetDigest, waveShare, WAVE_GATE_NAME_PATTERN } from "./wave-engine";
+
+const digest = (n: string) => `sha256:${n.repeat(64)}`;
+/** The runs both runners plan: a member name and its plan digest. */
+const RUNS: Record<string, string> = { "tenant-b": digest("b"), "tenant-a": digest("a"), "tenant-c": digest("c") };
+const NOW = "2026-10-11T00:00:00Z";
+
+async function throughOpWaves(): Promise<{ digest: string; gate: string; pending: string | undefined }> {
+  const spec: OpWavesSpec = {
+    name: "rollout",
+    op: "migrate",
+    plan: ["tool", "plan", "{target}", "--out", "{plan}"],
+    apply: ["tool", "apply", "{target}", "--plan", "{plan}"],
+    waves: [{ name: "tenants", runs: Object.keys(RUNS).map((target) => ({ target })) }],
+  };
+  const cwd = mkdtempSync(join(tmpdir(), "wave-engine-"));
+  try {
+    const exec: OpWaveExec = (argv, dir) => {
+      if (argv[1] === "plan") writeFileSync(join(dir, argv[4]!), JSON.stringify({ planDigest: RUNS[argv[2]!] }));
+      return 0;
+    };
+    const show: OpWaveShowAtBase = () => ({ sha: "b".repeat(40), text: JSON.stringify(spec) });
+    const gates = memoryGateLedgerPort();
+    const result = await runOpWave({ spec, specFile: "waves.json", wave: 1, cwd, exec, show, gates, now: NOW });
+    expect(result.exitCode).toBe(3);
+    return { digest: result.decision!.digest, gate: result.decision!.gate, pending: gates.appended[0]?.planDigest };
+  } finally {
+    rmSync(cwd, { recursive: true, force: true });
+  }
+}
+
+async function throughFanOut(): Promise<{ digest: string; gate: string; pending: string | undefined }> {
+  const components: DriverComponent[] = Object.keys(RUNS).map((name) => ({ name, deploy: [{ phase: "Apply", steps: [] }] }));
+  const plan = planFanOut({ components, changed: Object.keys(RUNS) });
+  const gates = memoryGateLedgerPort();
+  const result = await runFanOut(plan, components, new CapabilityRegistry(), {
+    env: "prod",
+    gates,
+    now: NOW,
+    waveGate: {
+      op: "rollout",
+      gate: "rollout",
+      planComponent: async (component) => ({
+        component: component.name,
+        members: [{ member: component.name, planDigest: RUNS[component.name]! }],
+        plans: {},
+        parts: [],
+      }),
+    },
+  });
+  expect(result.status).toBe("gated");
+  const wave = result.waves![0]!;
+  return { digest: wave.digest, gate: wave.gate, pending: gates.appended[0]?.planDigest };
+}
+
+describe("one wave engine (#3766)", () => {
+  test("the same runs bind the same set digest and gate through both runners", async () => {
+    const expected = waveSetDigest(Object.entries(RUNS).map(([member, planDigest]) => ({ member, planDigest })));
+    const op = await throughOpWaves();
+    const fan = await throughFanOut();
+    expect(op.digest).toBe(expected);
+    expect(fan.digest).toBe(expected);
+    expect(op.pending).toBe(expected);
+    expect(fan.pending).toBe(expected);
+    expect(op.gate).toBe("rollout-wave-1");
+    expect(fan.gate).toBe(op.gate);
+  });
+
+  test("gate names: the default pattern is waveGateName's name, and a spec's pattern still wins", () => {
+    for (const k of [1, 2, 12]) {
+      expect(waveGateNameFrom(undefined, "deploy", k)).toBe(waveGateName("deploy", k));
+      expect(waveGateNameFrom(WAVE_GATE_NAME_PATTERN, "deploy", k)).toBe(`deploy-wave-${k}`);
+      expect(opWaveGateName({ name: "deploy" }, k)).toBe(waveGateName("deploy", k));
+    }
+    expect(opWaveGateName({ name: "x", gate: "tg", gateName: "wave-{k}" }, 3)).toBe("wave-3");
+    expect(opWaveGateName({ name: "x", gateName: "{gate}/{k}" }, 3)).toBe("x/3");
+  });
+
+  test("the share split is the Op waves split by target", () => {
+    const runs = ["t5", "t1", "t4", "t2", "t3"].map((target) => ({ target }));
+    for (const shares of [1, 2, 3, 5]) {
+      for (let share = 1; share <= shares; share++) {
+        expect(waveShare(runs, share, shares, (r) => r.target)).toEqual(opWaveShare(runs, share, shares));
+      }
+    }
+    expect(opWaveShare(runs, 1, 2).map((r) => r.target)).toEqual(["t1", "t2", "t3"]);
+  });
+});