@intentius/chant 0.122.0 → 0.123.0

package/src/op/op-waves.ts

@@ -33,9 +33,28 @@
  * against the signers file at base) or `pr-review` (also the merged pull
  * request's review of its head, by a writer other than its author, when the
  * head planned the same digest). See `./gate-review.ts`.
+ *
+ * ## Spent approvals (#3784)
+ *
+ * With `approvals: { spend: true }` (read at base, like the policy), a wave
+ * records each approval it applies under in `_gates/<name>/applied.jsonl` on
+ * `chant/lifecycle`, as terragucci's wave gate does, and that approval is
+ * spent: the same digest needs a new approval to apply again.
+ *
+ * ## Wave-level commands and hooks (#3762)
+ *
+ * A product whose tool plans a whole wave in one call (Terragrunt's `run
+ * --all`, an apply by rows) gives `planWave` and `applyWave` in place of the
+ * per-run `plan` and `apply`: one call plans every run and lists each run's
+ * plan, and the wave's digest and gate come from that list as from per-run
+ * plans. Stage hooks (`hooks`) run commands before and after the plan and the
+ * apply; like the policy they are read from the spec at the base commit, and
+ * one whose `onFailure` is `approve` holds the wave for an approval whatever
+ * its policy says.
  */
 
 import type { OpEnvironment, OpSetupStep } from "../lexicon";
+import { notifyConfigProblem, type NotifyConfig } from "../notify";
 
 /** When a wave waits for an approval. */
 export type OpWaveGatePolicy =
@@ -59,6 +78,41 @@ export type GateApprovalSource =
 
 export const GATE_APPROVAL_SOURCES: readonly GateApprovalSource[] = ["ledger", "pr-review", "sealed"];
 
+/** What a failing hook does: fail the wave, or hold it for an approval of its set digest. */
+export type OpWaveHookFailure = "fail" | "approve";
+
+export const OP_WAVE_HOOK_FAILURES: readonly OpWaveHookFailure[] = ["fail", "approve"];
+
+/** One stage hook (#3762): a command run before or after a wave's plan or apply. */
+export interface OpWaveHook {
+  /** The hook's name in the log and the result. Default: its command. */
+  name?: string;
+  /**
+   * Argv template. `{op}`, `{wave}` and `{runs}` (the runs file, see
+   * `opWaveRunsPath`) are filled in; a `perRun` hook also gets `{target}`
+   * and, once the run is planned, `{plan}`.
+   */
+  command: string[];
+  /** Default `"fail"`. `"approve"` holds the wave for an approval of its set digest whatever its policy says. Not allowed after apply. */
+  onFailure?: OpWaveHookFailure;
+  /** Run once per run of the wave, rather than once for the wave. */
+  perRun?: boolean;
+}
+
+/** The stages a hook runs around. */
+export type OpWaveHookStage = "plan" | "apply";
+
+/** When a hook runs. */
+export type OpWaveHookMoment = "before-plan" | "after-plan" | "before-apply" | "after-apply";
+
+export const OP_WAVE_HOOK_MOMENTS: readonly OpWaveHookMoment[] = ["before-plan", "after-plan", "before-apply", "after-apply"];
+
+/** Stage hooks (#3762), read from the spec at the base commit like the gate policy. */
+export interface OpWaveHooks {
+  before?: { plan?: OpWaveHook[]; apply?: OpWaveHook[] };
+  after?: { plan?: OpWaveHook[]; apply?: OpWaveHook[] };
+}
+
 /** One Op run in a wave: an Op applied to one target (an environment, a database, a tenant). */
 export interface OpWaveRun {
   /** What the run applies to. Unique within its wave; it names the run in the set digest. */
@@ -94,6 +148,8 @@ export interface OpWave {
   variables?: Record<string, string>;
   /** Steps this wave's jobs run after the checkout, as `ScheduledOpSpec.setup`. */
   setup?: OpSetupStep[];
+  /** This wave's stage hooks (#3762), run after the spec's own. Read at the base commit. */
+  hooks?: OpWaveHooks;
 }
 
 /**
@@ -119,11 +175,29 @@ export interface OpWavesSpec {
    * Plan one run and write its plan file to `{plan}`: JSON `{ "planDigest":
    * string, "destructive"?: boolean, "empty"?: boolean }`. `destructive` is
    * what `on-destructive` waits on; a wave whose runs are all `empty` never
-   * waits.
+   * waits. Give this or `planWave`.
    */
-  plan: string[];
+  plan?: string[];
   /** Apply one run whose plan is at `{plan}`. Default `chant run {op} --env {target}`. */
   apply?: string[];
+  /**
+   * Plan every run of a wave in one call (#3762), in place of `plan`. `{runs}`
+   * is a file chant writes, `{ "wave", "number", "runs": [{ "target", "op" }] }`;
+   * the command writes `{plans}`: `{ "runs": [{ "target", "planDigest",
+   * "destructive"?, "empty"? }] }` (or the array alone), one entry per run.
+   */
+  planWave?: string[];
+  /**
+   * Apply a wave's approved set in one call (#3762), in place of `apply`.
+   * `{runs}` lists the runs to apply with the plan digest each was approved
+   * at; `{plans}` is the wave plan's file. A non-zero exit fails every run in
+   * the set.
+   */
+  applyWave?: string[];
+  /** Stage hooks for every wave (#3762), run before each wave's own. Read at the base commit. */
+  hooks?: OpWaveHooks;
+  /** What happens to an approval once a wave applies under it (#3784). Read at the base commit. */
+  approvals?: OpWavesApprovals;
   waves: OpWave[];
   /**
    * A scheduled job that starts again a wave job whose approval has arrived
@@ -133,6 +207,27 @@ export interface OpWavesSpec {
    * followed by `chant approve --resume` or a re-run by hand.
    */
   resume?: OpWavesResume;
+  /**
+   * Tell people when a wave waits for an approval, a share job refuses a run
+   * whose plan moved, or a wave fails (#3761): the environment variables
+   * holding a Slack or Teams incoming webhook's URL, or a generic webhook's
+   * URL and the key its `chant.notify/v1` events are signed with. A failed
+   * delivery is logged and never changes the job's exit code. See
+   * `../notify.ts`.
+   */
+  notify?: NotifyConfig;
+}
+
+/** What happens to an approval once a wave applies under it (#3784). */
+export interface OpWavesApprovals {
+  /**
+   * Spend it. Before a wave applies under an approval it records that in
+   * `_gates/<name>/applied.jsonl` on `chant/lifecycle`, and from then on the
+   * approval counts for nothing: applying the same digest again, by a re-run
+   * or a revert and re-merge, waits for a new approval. Default false: an
+   * approval of a digest passes that digest as often as it is planned.
+   */
+  spend?: boolean;
 }
 
 /** The scheduled resume job of an Op waves pipeline (#3683). */
@@ -184,16 +279,50 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
   const where = `Op waves "${spec.name}"`;
   if (!NAME.test(spec.name)) throw new Error(`${where}: the name must be lowercase letters, digits, "-" and "_"`);
   if (!spec.op) throw new Error(`${where} names no \`op\`. Name the Op a run runs when it names none.`);
-  if (!Array.isArray(spec.plan) || spec.plan.length === 0) {
-    throw new Error(`${where} has no \`plan\` command. Each wave plans its runs to bind its gate to their plan digests.`);
+  if (spec.plan !== undefined && spec.planWave !== undefined) {
+    throw new Error(`${where} has both \`plan\` and \`planWave\`. A wave is planned one run at a time or all at once; give one.`);
   }
-  if (!spec.plan.some((part) => part.includes("{plan}"))) {
-    throw new Error(`${where}: the \`plan\` command never names {plan}, the file it writes the plan digest to.`);
+  if (spec.apply !== undefined && spec.applyWave !== undefined) {
+    throw new Error(`${where} has both \`apply\` and \`applyWave\`. A wave is applied one run at a time or all at once; give one.`);
   }
+  if (spec.planWave !== undefined) {
+    assertArgv(where, "planWave", spec.planWave);
+    if (!spec.planWave.some((part) => part.includes("{plans}"))) {
+      throw new Error(`${where}: the \`planWave\` command never names {plans}, the file it writes each run's plan digest to.`);
+    }
+  } else {
+    if (!Array.isArray(spec.plan) || spec.plan.length === 0) {
+      throw new Error(`${where} has no \`plan\` command. Each wave plans its runs to bind its gate to their plan digests; give \`plan\` or \`planWave\`.`);
+    }
+    assertArgv(where, "plan", spec.plan);
+    if (!spec.plan.some((part) => part.includes("{plan}"))) {
+      throw new Error(`${where}: the \`plan\` command never names {plan}, the file it writes the plan digest to.`);
+    }
+  }
+  if (spec.apply !== undefined) assertArgv(where, "apply", spec.apply);
+  if (spec.applyWave !== undefined) {
+    assertArgv(where, "applyWave", spec.applyWave);
+    if (!spec.applyWave.some((part) => part.includes("{runs}"))) {
+      throw new Error(`${where}: the \`applyWave\` command never names {runs}, the file listing the approved runs it applies.`);
+    }
+  }
+  assertOpWaveHooks(where, spec.hooks);
   if (spec.waves.length === 0) throw new Error(`${where} has no waves.`);
   if (spec.resume !== undefined && (typeof spec.resume.schedule !== "string" || spec.resume.schedule.trim().split(/\s+/).length !== 5)) {
     throw new Error(`${where}: resume.schedule must be a five-field cron expression, such as "*/10 * * * *".`);
   }
+  if (spec.approvals !== undefined) {
+    const a = spec.approvals as unknown;
+    if (a === null || typeof a !== "object" || Array.isArray(a)) throw new Error(`${where}: \`approvals\` must be { "spend"?: true | false }.`);
+    for (const [key, value] of Object.entries(a as Record<string, unknown>)) {
+      if (key !== "spend") throw new Error(`${where}: approvals.${key} is not a setting; the one there is approvals.spend.`);
+      if (typeof value !== "boolean") throw new Error(`${where}: approvals.spend must be true or false.`);
+    }
+  }
+  if (spec.notify !== undefined) {
+    const problem = notifyConfigProblem(spec.notify, "notify");
+    if (problem) throw new Error(`${where}: ${problem}`);
+  }
   const names = new Set<string>();
   for (const wave of spec.waves) {
     if (!NAME.test(wave.name)) {
@@ -207,6 +336,7 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
     if (wave.approval !== undefined && !GATE_APPROVAL_SOURCES.includes(wave.approval)) {
       throw new Error(`${where}: wave "${wave.name}" has approval "${wave.approval}"; use ${GATE_APPROVAL_SOURCES.join(", ")}.`);
     }
+    assertOpWaveHooks(`${where}, wave "${wave.name}"`, wave.hooks);
     if (wave.runs.length === 0) throw new Error(`${where}: wave "${wave.name}" has no runs.`);
     const targets = new Set<string>();
     for (const run of wave.runs) {
@@ -224,6 +354,57 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
   }
 }
 
+function assertArgv(where: string, field: string, argv: unknown): void {
+  if (!Array.isArray(argv) || argv.length === 0 || !argv.every((part) => typeof part === "string") || argv[0] === "") {
+    throw new Error(`${where}: \`${field}\` must be a command as argv, a non-empty array of strings.`);
+  }
+}
+
+/** Refuse hooks no runner could run, naming what is wrong (#3762). */
+export function assertOpWaveHooks(where: string, hooks: OpWaveHooks | undefined): void {
+  if (hooks === undefined) return;
+  if (hooks === null || typeof hooks !== "object" || Array.isArray(hooks)) {
+    throw new Error(`${where}: \`hooks\` must be { "before"?: { "plan"?, "apply"? }, "after"?: { "plan"?, "apply"? } }.`);
+  }
+  for (const [side, stages] of Object.entries(hooks as Record<string, unknown>)) {
+    if (side !== "before" && side !== "after") throw new Error(`${where}: hooks.${side} is not a moment; use hooks.before or hooks.after.`);
+    if (stages === null || typeof stages !== "object" || Array.isArray(stages)) throw new Error(`${where}: hooks.${side} must be { "plan"?: [...], "apply"?: [...] }.`);
+    for (const [stage, list] of Object.entries(stages as Record<string, unknown>)) {
+      const at = `hooks.${side}.${stage}`;
+      if (stage !== "plan" && stage !== "apply") throw new Error(`${where}: ${at} is not a stage; a hook runs before or after plan or apply.`);
+      if (!Array.isArray(list)) throw new Error(`${where}: ${at} must be a list of hooks.`);
+      list.forEach((hook: OpWaveHook, i: number) => {
+        const which = `${at}[${i}]${hook && typeof hook === "object" && typeof hook.name === "string" ? ` (${hook.name})` : ""}`;
+        if (!hook || typeof hook !== "object") throw new Error(`${where}: ${which} must be { "command": [...], "onFailure"?, "perRun"? }.`);
+        assertArgv(where, `${which}.command`, hook.command);
+        if (hook.onFailure !== undefined && !OP_WAVE_HOOK_FAILURES.includes(hook.onFailure)) {
+          throw new Error(`${where}: ${which} has onFailure "${hook.onFailure}"; use ${OP_WAVE_HOOK_FAILURES.join(" or ")}.`);
+        }
+        if (hook.onFailure === "approve" && side === "after" && stage === "apply") {
+          throw new Error(`${where}: ${which} has onFailure "approve", but after the apply there is nothing left to hold. Use "fail".`);
+        }
+        if (hook.perRun !== undefined && typeof hook.perRun !== "boolean") throw new Error(`${where}: ${which}.perRun must be true or false.`);
+        if (!hook.perRun) {
+          const named = hook.command.find((part) => part.includes("{target}") || part.includes("{plan}"));
+          if (named) throw new Error(`${where}: ${which} runs once for the wave, so it has no {target} or {plan} ("${named}"). Set "perRun": true, or read the runs from {runs}.`);
+        } else if (side === "before" && stage === "plan" && hook.command.some((part) => part.includes("{plan}"))) {
+          throw new Error(`${where}: ${which} runs before the plan, so it has no {plan} yet.`);
+        }
+      });
+    }
+  }
+}
+
+/** The hooks of each moment for wave `name`: the spec's, then the wave's own. */
+export function opWaveHooksAt(spec: Pick<OpWavesSpec, "hooks" | "waves">, name: string): Record<OpWaveHookMoment, OpWaveHook[]> {
+  const wave = spec.waves.find((w) => w.name === name);
+  const at = (hooks: OpWaveHooks | undefined, moment: OpWaveHookMoment): OpWaveHook[] => {
+    const [side, stage] = moment.split("-") as ["before" | "after", OpWaveHookStage];
+    return hooks?.[side]?.[stage] ?? [];
+  };
+  return Object.fromEntries(OP_WAVE_HOOK_MOMENTS.map((m) => [m, [...at(spec.hooks, m), ...at(wave?.hooks, m)]])) as Record<OpWaveHookMoment, OpWaveHook[]>;
+}
+
 /**
  * The runs share `share` (1-based) of `shares` applies: the wave's runs sorted
  * by target, cut into contiguous slices whose sizes differ by at most one.

package/src/op/operator.test.ts

@@ -429,6 +429,35 @@ describe("runOperatorForever — interval/timer behavior", () => {
     });
   }, 10_000);
 
+  test("releases the Ops' leases when it stops, so a restarted operator ticks at once (#2879)", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeFixtureConvergeOp(dir, "staging-converge", "staging");
+      const activities = fakeTickActivities(dir, "staging", "staging-converge");
+
+      const controller = new AbortController();
+      const rounds: unknown[] = [];
+      const loop = runOperatorForever({
+        cwd: dir,
+        holder: "op-a",
+        intervalMs: 40,
+        activities,
+        profiles: PROFILES,
+        signal: controller.signal,
+        onRound: () => rounds.push(1),
+      });
+      await waitForRoundCount(rounds, 1);
+      expect((await readLease("staging-converge", { cwd: dir })).record?.holder).toBe("op-a");
+
+      controller.abort();
+      await loop;
+      expect((await readLease("staging-converge", { cwd: dir })).record).toBeUndefined();
+
+      const events = await runOperatorRound({ cwd: dir, holder: "op-b", activities, profiles: PROFILES });
+      expect(events.map((e) => e.kind)).toEqual(["ticked"]);
+    });
+  }, 10_000);
+
   test("default interval is used when none is given", () => {
     expect(DEFAULT_OPERATOR_INTERVAL_MS).toBeGreaterThan(0);
   });

package/src/op/operator.ts

@@ -196,6 +196,17 @@ export function createBesideState(): BesideState {
   return { running: new Map(), started: new Map(), ended: [] };
 }
 
+/**
+ * Release the per-Op leases a stopped operator still holds (#2879), best
+ * effort: a lease that is gone or taken over since is left alone, and one that
+ * can't be released expires on its TTL as before.
+ */
+export async function releaseHeldLeases(held: Map<string, string>, holder: string, opts: { cwd?: string } = {}): Promise<void> {
+  const entries = [...held];
+  held.clear();
+  await Promise.allSettled(entries.map(([op, token]) => releaseLease(op, holder, token, opts)));
+}
+
 /** Wait for every run in flight beside the turns to end. `chant operator --steward --once` does before it exits. */
 export async function waitForBesideRuns(state: BesideState): Promise<void> {
   await Promise.all([...state.running.values()].map((r) => r.handle.done));
@@ -263,6 +274,13 @@ export interface OperatorRoundOptions {
    * it returns.
    */
   besideState?: BesideState;
+  /**
+   * The per-Op leases this process holds after its ticks, Op name to the
+   * token of the newest acquire (#2879). A round records each lease it takes
+   * or renews here. `runOperatorForever` owns one and releases what is left when it stops, so
+   * a restarted operator does not skip its Ops until the old leases expire.
+   */
+  heldLeases?: Map<string, string>;
   /** How a run beside the turns is started. Default: `chant run <op>` in a process of its own ({@link spawnBesideRun}). */
   launchBeside?: BesideLauncher;
   /** The environment the steward operator was started for (`--env`), passed on to a run it starts beside its turns. */
@@ -540,6 +558,7 @@ export async function runOperatorRound(opts: OperatorRoundOptions): Promise<Oper
     }
 
     const lease = acquired.lease as LeaseRecord;
+    opts.heldLeases?.set(config.name, lease.token);
 
     // A local steward is one turn at a time (#2750): a hand run (`chant run
     // <op>`) holds this same lease for as long as it runs, so a round never
@@ -556,12 +575,14 @@ export async function runOperatorRound(opts: OperatorRoundOptions): Promise<Oper
         // catch above: report it and stop, rather than let it propagate and
         // leak the per-op lease this round just took.
         await releaseLease(config.name, holder, lease.token, { cwd: opts.cwd }).catch(() => false);
+        opts.heldLeases?.delete(config.name);
         const message = err instanceof StaleLockError ? err.message : err instanceof Error ? err.message : String(err);
         events.push({ kind: "lease-error", op: stewardTurnLeaseName(steward.name), env, error: message });
         break;
       }
       if (!turn.acquired) {
         await releaseLease(config.name, holder, lease.token, { cwd: opts.cwd }).catch(() => false);
+        opts.heldLeases?.delete(config.name);
         events.push({ kind: "turn-busy", op: config.name, env, steward: steward.name, heldBy: turn.heldBy?.holder });
         break;
       }
@@ -898,6 +919,8 @@ export async function runOperatorForever(opts: OperatorLoopOptions): Promise<voi
   // The runs a steward starts beside its turns (#2861), for the life of the
   // loop. When the loop stops, so do they.
   const besideState = opts.besideState ?? createBesideState();
+  // The per-Op leases the rounds leave held (#2879), released when the loop stops.
+  const heldLeases = opts.heldLeases ?? new Map<string, string>();
   const intervalMs = opts.intervalMs ?? DEFAULT_OPERATOR_INTERVAL_MS;
   const subscribers = opts.subscribers ?? [];
 
@@ -906,13 +929,14 @@ export async function runOperatorForever(opts: OperatorLoopOptions): Promise<voi
   if (subscribers.length === 0) {
     try {
       while (!opts.signal?.aborted) {
-        const events = await runOperatorRound({ ...opts, holder, scheduleState, besideState });
+        const events = await runOperatorRound({ ...opts, holder, scheduleState, besideState, heldLeases });
         opts.onRound?.(events);
         if (opts.signal?.aborted) break;
         await sleepAbortable(intervalMs, opts.signal);
       }
     } finally {
       await stopBesideRuns(besideState);
+      await releaseHeldLeases(heldLeases, holder, { cwd: opts.cwd });
     }
     return;
   }
@@ -965,7 +989,7 @@ export async function runOperatorForever(opts: OperatorLoopOptions): Promise<voi
     while (!opts.signal?.aborted) {
       gate.roundStarted();
       const startedAt = Date.now();
-      const events = await runOperatorRound({ ...opts, holder, scheduleState, besideState });
+      const events = await runOperatorRound({ ...opts, holder, scheduleState, besideState, heldLeases });
       opts.onRound?.(events);
       if (opts.signal?.aborted) break;
 
@@ -980,6 +1004,7 @@ export async function runOperatorForever(opts: OperatorLoopOptions): Promise<voi
   } finally {
     await closeAll();
     await stopBesideRuns(besideState);
+    await releaseHeldLeases(heldLeases, holder, { cwd: opts.cwd });
   }
 }
 

package/src/op/run-context.test.ts

@@ -8,7 +8,7 @@ import type { ActivityFn, ActivityProfile } from "./activity-registry";
 import { runOpLocally } from "./local-executor";
 import { memoryGateLedgerPort } from "./gate";
 import { currentOpRun, type OpRunContext } from "./run-context";
-import { gatePolicyVersion, type GatePolicyRef, type ResolvedGateApproval } from "./gate-approval";
+import { gateContextDigest, gatePolicyVersion, type GatePolicyRef, type ResolvedGateApproval } from "./gate-approval";
 import type { GateResolutionRecord } from "../lifecycle/gate-ledger";
 
 const PROFILES: Record<string, ActivityProfile> = {
@@ -81,7 +81,7 @@ describe("the Op run context (#2522)", () => {
     const permit = (mode: "log-only" | "enforce"): GateResolutionRecord => ({
       version: 1, op: "release", gate: "ship", resolvedBy: "release-bot", timestamp: "2026-09-05T11:00:00.000Z",
       approver: { kind: "agent" },
-      policyDecision: { policy: "ship", version: POLICY.version, mode, decision: "allow", determining: ["ship-0"], errors: [] },
+      policyDecision: { policy: "ship", version: POLICY.version, mode, contextDigest: gateContextDigest(undefined), decision: "allow", determining: ["ship-0"], errors: [] },
     });
 
     async function run(mode: "log-only" | "enforce") {

package/src/op/work-lease-decl.ts

@@ -7,10 +7,11 @@
 
 import { isStepOutputRef } from "./step-output-ref";
 import { parseDuration } from "./duration";
+import { WORK_ITEM_ID_PATTERN, workItemIdProblem } from "../lifecycle/work-item-id";
 import { WORK_LEASE_STEP_ID, type OpConfig, type PhaseDefinition } from "./types";
 
 /** A work item id a lease can be keyed by: the same pattern as `WORK_ITEM_ID_PATTERN` in `../lifecycle/work-lease.ts`. */
-export const WORK_LEASE_ITEM_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+export const WORK_LEASE_ITEM_PATTERN = WORK_ITEM_ID_PATTERN;
 
 /** The ids of the activity steps in an Op's main phases, in order. */
 function mainStepIds(phases: readonly PhaseDefinition[]): string[] {
@@ -42,9 +43,8 @@ export function workLeaseProblems(config: Pick<OpConfig, "name" | "phases" | "wo
     problems.push(`Op "${name}": step id "${WORK_LEASE_STEP_ID}" is reserved for the run's work lease; rename the step`);
   }
   const checkId = (id: unknown) => {
-    if (typeof id !== "string" || !WORK_LEASE_ITEM_PATTERN.test(id) || id.includes("..")) {
-      problems.push(`Op "${name}": workLease.item ${JSON.stringify(id)} can't key a work lease (letters, digits, ".", "_" and "-")`);
-    }
+    const problem = workItemIdProblem(id);
+    if (problem) problems.push(`Op "${name}": workLease.item ${problem}`);
   };
   const item = spec.item;
   if (isStepOutputRef(item)) {

package/src/op/work-lease-run.test.ts

@@ -80,6 +80,11 @@ describe("the declaration", () => {
     ).toThrow(/scheduled, but its workLease names no item/);
     expect(declareSteward({ name: "box", ops: [dispatchOp({ workLease: {} })] }).ops).toHaveLength(1);
     expect(workLeaseProblems(dispatchOp({ workLease: { item: "../x" } }))[0]).toMatch(/can't key a work lease/);
+    for (const item of ["upgrade-.", "x.lock", "x.LOCK", "a..b"]) {
+      expect(workLeaseProblems(dispatchOp({ workLease: { item } }))[0], item).toMatch(/can't key a work lease/);
+    }
+    expect(workLeaseProblems(dispatchOp({ workLease: { item: ["W-1", "upgrade-."] } }))).toHaveLength(1);
+    expect(() => Op(dispatchOp({ workLease: { item: "upgrade-." } }))).toThrow(/can't key a work lease/);
     expect(workLeaseProblems(dispatchOp({ workLease: { item: "W-1", ttl: "1s" } }))[0]).toMatch(/shorter than 3s/);
     expect(workLeaseProblems(dispatchOp({ workLease: { item: stepOutput("nope", "id") } }))[0]).toMatch(/references step "nope"/);
     expect(workLeaseProblems(dispatchOp({ workLease: { item: "W-1" } }, [step("x", {}, { id: WORK_LEASE_STEP_ID })]))[0]).toMatch(/reserved/);

package/src/op/work-lease-run.ts

@@ -64,7 +64,8 @@ import {
   releaseWorkLease,
   renewWorkLease,
   workLeaseRef,
-  WORK_ITEM_ID_PATTERN,
+  isWorkItemId,
+  workItemIdProblem,
   type WorkLease,
 } from "../lifecycle/work-lease";
 import { resolveMemberLedger } from "../lifecycle/member-ledger";
@@ -216,8 +217,8 @@ export class RunWorkLease {
     if (value === undefined || value === null || value === "") return [];
     const list = Array.isArray(value) ? value : [value];
     return list.filter((v) => v !== undefined && v !== null && v !== "").map((v) => {
-      if (typeof v !== "string" || !WORK_ITEM_ID_PATTERN.test(v) || v.includes("..")) {
-        throw new Error(`Op "${this.config.name}": workLease.item resolved to ${JSON.stringify(v)}, which can't key a work lease`);
+      if (!isWorkItemId(v)) {
+        throw new Error(`Op "${this.config.name}": workLease.item resolved to ${JSON.stringify(v)}, which can't key a work lease${typeof v === "string" ? ` (${workItemIdProblem(v)})` : ""}`);
       }
       return v;
     });

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

@@ -0,0 +1,47 @@
+/**
+ * The override gate bundles small (#3760, ruling #3421), as the gate decision
+ * does: terragucci and SQL Yodeler decide overrides from one bundled file
+ * with no TypeScript toolchain. This bundles `@intentius/chant/override-gate`
+ * the way they 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\/fold\//, /\/src\/lint\//, /\/src\/codegen\//, /\/src\/lifecycle\/git\.ts$/, /\/src\/lifecycle\/gate-ledger\.ts$/];
+
+describe("the override-gate bundle", () => {
+  test("holds the decision, the seal check and the digest, and no package or git ledger code", async () => {
+    const result = await build({
+      entryPoints: [join(REPO, "packages", "core", "src", "override-gate.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([]);
+    }
+    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/plan-digest.ts",
+      "packages/core/src/op/gate-name.ts",
+      "packages/core/src/override-gate.ts",
+      "packages/core/src/workspace/trust/gate-seal.ts",
+      "packages/core/src/workspace/trust/trust-files.ts",
+    ]);
+    // About 16 KB today.
+    const bytes = result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0);
+    expect(bytes).toBeLessThan(40 * 1024);
+  });
+});