@intentius/chant 0.124.8 → 0.124.9

package/src/op/op-waves.ts

@@ -53,9 +53,21 @@
  * 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.
+ *
+ * ## A gate that asks a decision point (#3836)
+ *
+ * With `point` (on the spec, or on a wave, whose own wins), read at base like
+ * the policy, a wave that needs an approval asks that workspace decision
+ * point instead of reading the ledger for a `chant approve`, the way an Op
+ * gate with a `point` does (#3170): `gate.planDigest` is the wave's set
+ * digest, so each plan is its own question. An open question waits (exit 3,
+ * the pending fact cites it), an answer the gate passes on records the
+ * resolution that cites it and the wave goes on, and any other answer refuses
+ * the wave (exit 8). See `./op-waves-run.ts`.
  */
 
 import type { OpEnvironment, OpSetupStep } from "../lexicon";
+import { gatePointProblems, type GatePoint } from "./gate-point";
 import { notifyConfigProblem, type NotifyConfig } from "../notify";
 
 /**
@@ -92,6 +104,40 @@ export const GATE_APPROVAL_SOURCES: readonly GateApprovalSource[] = ["ledger", "
 /** What a failing hook does: fail the wave, or hold it for an approval of its set digest. */
 export type OpWaveHookFailure = "fail" | "approve";
 
+/**
+ * The decision point a wave's gate asks (#3836): a point's name, or `{ name,
+ * inputs?, pass?, store?, timeout? }` as an Op gate's `point` takes, plus the
+ * pending fact's `timeout` (default 48h). The point must declare the input
+ * `gate.planDigest`, which is the wave's set digest.
+ */
+export type OpWavePoint = GatePoint & {
+  /** How long the pending fact that cites an open question stands, such as `"48h"`. */
+  timeout?: string;
+};
+
+/** A wave's or a spec's `point` as an {@link OpWavePoint}, or undefined when it names none. */
+export function opWavePointOf(point: string | OpWavePoint | undefined): OpWavePoint | undefined {
+  if (point === undefined) return undefined;
+  return typeof point === "string" ? { name: point } : point;
+}
+
+/** What is wrong with a wave's `point`, empty when nothing is (#3836). */
+export function opWavePointProblems(point: unknown): string[] {
+  if (point !== null && typeof point === "object" && !Array.isArray(point) && "timeout" in point) {
+    const { timeout, ...rest } = point as Record<string, unknown>;
+    const problems = gatePointProblems(rest);
+    if (typeof timeout !== "string" || !/^(\d+(ms|s|m|h|d))+$/.test(timeout)) problems.push("`point.timeout` is a duration such as \"48h\"");
+    return problems;
+  }
+  return gatePointProblems(point);
+}
+
+/** The point wave `name`'s gate asks (#3836): the wave's own, else the spec's, else none. */
+export function opWavePointAt(spec: Pick<OpWavesSpec, "point" | "waves">, name: string): OpWavePoint | undefined {
+  const wave = spec.waves.find((w) => w.name === name);
+  return opWavePointOf(wave?.point ?? spec.point);
+}
+
 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. */
@@ -181,6 +227,11 @@ export interface OpWave {
    * Like `gate`, the runner reads it from the spec file at the base commit.
    */
   approval?: GateApprovalSource;
+  /**
+   * The decision point this wave's gate asks (#3836), in place of the spec's.
+   * Read at base like `gate`. See {@link OpWavesSpec.point}.
+   */
+  point?: string | OpWavePoint;
   /**
    * Split the wave into a deciding job and this many share jobs, each
    * applying a slice of the runs. Default 1: one job plans, decides and
@@ -266,6 +317,15 @@ export interface OpWavesSpec {
    * the rules (`@intentius/chant/override-gate`).
    */
   override?: OpWavesOverride;
+  /**
+   * The decision point every wave's gate asks (#3836), unless a wave names its
+   * own. Read at the base commit, like the policy: a wave that needs an
+   * approval asks the point with `gate.planDigest` set to its set digest, and
+   * only an answer the point's `pass` names (default yes) for that digest
+   * lets it apply. `chant approve` does not pass such a gate, and the wave's
+   * `approval` mode does not apply: the point's deciders and quorum decide.
+   */
+  point?: string | OpWavePoint;
   waves: OpWave[];
   /**
    * A scheduled job that starts again a wave job whose approval has arrived
@@ -442,6 +502,10 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
       if (typeof value !== "string" || value.trim() === "") throw new Error(`${where}: override.overriders must be a path, such as ".chant/overriders".`);
     }
   }
+  if (spec.point !== undefined) {
+    const problems = opWavePointProblems(spec.point);
+    if (problems.length > 0) throw new Error(`${where}: ${problems.join("; ")}.`);
+  }
   if (spec.neverOverMcp !== undefined && typeof spec.neverOverMcp !== "boolean") throw new Error(`${where}: neverOverMcp must be true or false.`);
   if (spec.notify !== undefined) {
     const problem = notifyConfigProblem(spec.notify, "notify");
@@ -461,6 +525,10 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
       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.point !== undefined) {
+      const problems = opWavePointProblems(wave.point);
+      if (problems.length > 0) throw new Error(`${where}: wave "${wave.name}": ${problems.join("; ")}.`);
+    }
     if (wave.discover !== undefined && typeof wave.discover !== "boolean") throw new Error(`${where}: wave "${wave.name}" has discover ${JSON.stringify(wave.discover)}; use true or false.`);
     if (wave.rest !== undefined && typeof wave.rest !== "boolean") throw new Error(`${where}: wave "${wave.name}" has rest ${JSON.stringify(wave.rest)}; use true or false.`);
     if (wave.discover) {

package/src/workspace/identity.test.ts

@@ -202,7 +202,10 @@ describe.skipIf(!hasSshKeygen)("identity.gates", () => {
 
     const roster = memoryGateLedgerPort({ pending: [pending], resolutions: [approval("alex")] });
     expect((await evaluateGate(roster, input)).satisfied).toBe(true);
-    expect((await evaluateGate({ ...roster, approvalRule: async () => rule }, input)).satisfied).toBe(false);
+    const held = await evaluateGate({ ...roster, approvalRule: async () => rule }, input);
+    expect(held.satisfied).toBe(false);
+    // #3841: the approval the rule refused is named, with why.
+    expect(!held.satisfied && held.refused?.map((x) => [x.resolution.resolvedBy, x.reason])).toEqual([["alex", expect.stringMatching(/not signed/)]]);
     const sealed = memoryGateLedgerPort({ pending: [pending], resolutions: [approval("alex"), signed(alice, approval("github:alice"))] });
     const check = await evaluateGate({ ...sealed, approvalRule: async () => rule }, input);
     expect(check.satisfied && check.resolution.resolvedBy).toBe("github:alice");

package/src/workspace/identity.ts

@@ -179,8 +179,9 @@ export function gateAdmissionFrom(source: GateRuleSource, gate: string): GateAdm
  * The rule for `gate` in the workspace holding `cwd`, read at base (the
  * target branch tip), or null when there is no declaration or it names none.
  * What a run, `chant approve` and `workspace status` ask before counting an
- * approval.
+ * approval. `base` names the commit to read at instead, as an op wave reads
+ * every rule at its `--base` (#3841).
  */
-export function gateAdmission(cwd: string, gate: string): GateAdmission | null {
-  return gateAdmissionFrom(scopeSource(cwd), gate);
+export function gateAdmission(cwd: string, gate: string, base?: string): GateAdmission | null {
+  return gateAdmissionFrom(scopeSource(cwd, base), gate);
 }

package/src/workspace/write-scope.ts

@@ -368,11 +368,12 @@ function readAt(cwd: string, at?: string): { declaration: Declaration; rootOnDis
  * The scope for a write from `cwd`: the declaration and the trust policy at
  * the base revision (`origin/HEAD`, `main` or `master`), so a write can't
  * widen its own scope by editing its copy of the declaration. Without a base,
- * or without a declaration at it, the working tree's declaration.
+ * or without a declaration at it, the working tree's declaration. `at` names
+ * the base instead, as an op wave's `--base` does (#3841).
  */
-export function scopeSource(cwd: string): ScopeSource {
+export function scopeSource(cwd: string, at?: string): ScopeSource {
   const top = gitRoot(cwd);
-  const base = top ? resolveBase(top) : null;
+  const base = top ? resolveBase(top, at) : null;
   const policy = top && base ? policyAtBase(top, base) : emptyPolicy(null);
   const withClasses = (read: NonNullable<ReturnType<typeof readAt>>) => {
     const { tree, ...rest } = read;