@intentius/chant 0.124.39 → 0.124.41

package/dist/op/op-waves-run.js

@@ -54,9 +54,11 @@ import { dirname, isAbsolute, join, posix } from "node:path";
 import { decideWaveGate, runWaveLoop, waveDigestMembers, waveSetDigest, writeWaveRecordFile, } from "../wave-engine.js";
 import { approveCommand, evaluateGate, gitGateLedgerPort } from "./gate.js";
 import { isApprovalSpent } from "../lifecycle/gate-applied.js";
+import { samePlanDigest } from "../lifecycle/plan-digest.js";
 import { isLifecycleLocalNote } from "../lifecycle/local-note.js";
 import { ciRunIdFromEnv } from "./gate-run-locator.js";
-import { OP_WAVE_DEFAULT_APPLY, OP_WAVE_GATE_POLICIES, OP_WAVE_HOOK_MOMENTS, GATE_APPROVAL_SOURCES, assertOpWaveHooks, assertOpWavesSpec, opWaveApplyHooksRunBy, opWaveGateName, opWaveHooksAt, opWavePointAt, opWavePointProblems, opWaveRecordPath, opWaveGroupRuns, opWaveGroupsProblem, opWaveShare, } from "./op-waves.js";
+import { quorumProblems, quorumRuleLine, quorumRulesFor, quorumWaiting, ruleNeedsProof, samePrincipal, trustQuorumJudge, } from "./gate-quorum.js";
+import { OP_WAVE_DEFAULT_APPLY, OP_WAVE_GATE_POLICIES, OP_WAVE_HOOK_MOMENTS, GATE_APPROVAL_SOURCES, assertOpWaveHooks, assertOpWavesSpec, opWaveApplyHooksRunBy, opWaveGateName, opWaveHooksAt, opWaveHookRuns, opWavePointAt, opWavePointProblems, opWaveRecordPath, opWaveGroupRuns, opWaveGroupsProblem, opWaveShare, } from "./op-waves.js";
 /** Pending-fact keys chant writes itself, which a plans file's `pending` may not set (#3821). */
 export const OP_WAVE_PENDING_RESERVED = [
     "version", "kind", "op", "gate", "timestamp", "expiresAt", "planDigest", "runId", "url", "resume",
@@ -126,7 +128,7 @@ export function readOpWavePolicy(specFile, name, base, cwd, show = gitShowAtBase
     const spend = spec.approvals?.spend === true;
     const neverOverMcp = spec.neverOverMcp === true;
     // #3836: the gate's decision point, the spec's for a wave the base does not have yet.
-    const asks = pointAtBase(spec, name, `${specFile} at ${sha.slice(0, 12)}`);
+    const asks = { ...pointAtBase(spec, name, `${specFile} at ${sha.slice(0, 12)}`), ...quorumAtBase(spec, `${specFile} at ${sha.slice(0, 12)}`) };
     const wave = spec.waves.find((w) => w.name === name);
     if (!wave)
         return { ...absent, spend, neverOverMcp, ...asks };
@@ -146,6 +148,16 @@ export function readOpWavePolicy(specFile, name, base, cwd, show = gitShowAtBase
     }
     return rules;
 }
+/** The approval rules at base (#4290), or why they cannot be read. A spec at base with none has none. */
+function quorumAtBase(spec, where) {
+    const raw = spec.approvals?.quorum;
+    if (raw === undefined)
+        return {};
+    const problems = Array.isArray(raw) ? quorumProblems(raw, "approvals.quorum", { notAuthor: true }) : ["`approvals.quorum` must be a list of rules"];
+    if (problems.length > 0)
+        return { quorumRefused: `the approval rules in ${where} cannot be read (${problems.join("; ")})` };
+    return raw.length > 0 ? { quorum: raw } : {};
+}
 /** The point wave `name` asks at base (#3836), or why it cannot be asked. */
 function pointAtBase(spec, name, where) {
     const raw = spec.waves.find((w) => w.name === name)?.point ?? spec.point;
@@ -200,11 +212,13 @@ function planRun(opts, waveName, run) {
     return member(run.target, op, file);
 }
 function member(target, op, file) {
-    const denied = file.denied;
-    if (denied !== undefined) {
-        const d = denied;
+    for (const key of ["denied", "held"]) {
+        const value = file[key];
+        if (value === undefined)
+            continue;
+        const d = value;
         if (!d || typeof d !== "object" || !Array.isArray(d.rules) || d.rules.length === 0 || !d.rules.every((r) => typeof r === "string" && r.trim() !== "") || (d.reason !== undefined && typeof d.reason !== "string")) {
-            throw new Error(`the plan of ${target} has denied ${JSON.stringify(denied)}; a denial is { "rules": ["<rule id>", ...], "reason"?: "<text>" }`);
+            throw new Error(`the plan of ${target} has ${key} ${JSON.stringify(value)}; ${key === "denied" ? "a denial" : "a hold"} is { "rules": ["<rule id>", ...], "reason"?: "<text>" }`);
         }
     }
     return {
@@ -214,6 +228,7 @@ function member(target, op, file) {
         ...(file.destructive === true ? { destructive: true } : {}),
         ...(file.empty === true ? { empty: true } : {}),
         ...(file.denied ? { denied: { rules: file.denied.rules, ...(file.denied.reason ? { reason: file.denied.reason } : {}) } } : {}),
+        ...(file.held ? { held: { rules: [...new Set(file.held.rules)].sort(), ...(file.held.reason ? { reason: file.held.reason } : {}) } } : {}),
     };
 }
 /** Write the `{runs}` file: the runs, with their plans once planned. */
@@ -295,7 +310,7 @@ function planRuns(at, runs, discover = false) {
     const members = runs.map((run) => {
         const m = member(run.target, run.op ?? spec.op, byTarget.get(run.target));
         const path = join(cwd, opWavePlanPath(spec, k, run.target));
-        writeFileSync(path, JSON.stringify({ planDigest: m.planDigest, ...(m.destructive ? { destructive: true } : {}), ...(m.empty ? { empty: true } : {}), ...(m.denied ? { denied: m.denied } : {}) }) + "\n");
+        writeFileSync(path, JSON.stringify({ planDigest: m.planDigest, ...(m.destructive ? { destructive: true } : {}), ...(m.empty ? { empty: true } : {}), ...(m.denied ? { denied: m.denied } : {}), ...(m.held ? { held: m.held } : {}) }) + "\n");
         return m;
     });
     const overriders = Array.isArray(parsed) ? undefined : parsed.overriders;
@@ -385,12 +400,18 @@ function runHookList(at, moment, hooks, runs, runsPath, extraEnv = {}) {
         return out;
     const { name: specName, op, waveName, k, cwd, exec, log } = at;
     // #3821: a hook that holds the wave on another gate names it in this file.
-    const holdPath = `.chant/op-waves/${specName}/wave-${k}/hold.json`;
+    const holdPath = at.holdPath ?? `.chant/op-waves/${specName}/wave-${k}/hold.json`;
     const env = { CHANT_OP_WAVES: specName, CHANT_WAVE: waveName, CHANT_WAVE_NUMBER: String(k), CHANT_HOOK: moment, CHANT_RUNS: runsPath, CHANT_HOLD: holdPath, ...extraEnv };
     for (const hook of hooks) {
         const name = hook.name ?? (hook.command.join(" ").length > 60 ? `${hook.command.join(" ").slice(0, 57)}...` : hook.command.join(" "));
+        // #4288: a hook with `targets` is for the runs they match. Once for the wave, it runs when one matches or no run is known yet.
+        const mine = opWaveHookRuns(hook, runs);
+        if (hook.targets && (hook.perRun ? mine.length === 0 : mine.length === 0 && runs.length > 0)) {
+            log(`${moment} hook ${name}: no run matches its targets (${hook.targets.join(", ")}), so it did not run`);
+            continue;
+        }
         const calls = hook.perRun
-            ? runs.map((run) => ({
+            ? mine.map((run) => ({
                 target: run.target,
                 argv: opWaveArgv(hook.command, { op: run.op, wave: waveName, target: run.target, runs: runsPath, ...(run.plan ? { plan: run.plan } : {}) }),
                 env: { ...env, CHANT_TARGET: run.target, ...(run.plan ? { CHANT_PLAN: run.plan } : {}) },
@@ -508,6 +529,32 @@ async function runHooks(ctx, moment, hooks, runs, members, digest, extraEnv = {}
     }
     return back;
 }
+/**
+ * Run one moment's hooks outside an Op waves job (#4288): the pull-request
+ * jobs, or a product's own stage, with the same `targets`, `perRun`,
+ * `onFailure` and argv filling a wave job uses. A hook that holds on another
+ * gate (`CHANT_HOLD`) is counted as a plain hold; settling that gate is the
+ * caller's.
+ */
+export function runStageHooks(moment, hooks, options) {
+    const cwd = options.cwd ?? process.cwd();
+    const log = options.log ?? ((line) => console.error(line));
+    const place = { name: options.name, op: options.op, waveName: options.wave, k: options.k ?? 0, cwd, exec: options.exec ?? spawnExec, log, holdPath: options.holdFile };
+    const out = runHookList(place, moment, hooks, options.runs, options.runsFile, options.env);
+    return { outcomes: out.outcomes, ...(out.failed ? { failed: out.failed } : {}), holds: [...out.holds, ...out.otherGates.map((g) => `${g.label} (on ${g.request.op ?? options.name} / ${g.request.gate})`)] };
+}
+/**
+ * The hooks that run before a job plans (#4288): `before-observe`, then
+ * `before-plan`. A failure or a hold on another gate in the first ends it
+ * there; the holds of both add up.
+ */
+async function runBeforePlanHooks(ctx, hooks, runs) {
+    const observe = await runHooks(ctx, "before-observe", hooks?.["before-observe"], runs);
+    if (observe.failed || observe.waitingOn)
+        return observe;
+    const plan = await runHooks(ctx, "before-plan", hooks?.["before-plan"], runs);
+    return { ...plan, holds: [...observe.holds, ...plan.holds] };
+}
 /** How many gates one hook call holds a wave on in turn (#3847): the first hold and the holds its approved re-runs ask for. */
 export const OP_WAVE_MAX_CHAINED_HOLDS = 10;
 /**
@@ -827,7 +874,7 @@ async function planOpWave(options, { k, pass }) {
             log(`${part} of wave ${k} (${wave.name}) holds none of the wave's runs; nothing to apply`);
             return { end: result };
         }
-        const before = await runHooks(ctx, "before-plan", decision.hooks?.["before-plan"], slice);
+        const before = await runBeforePlanHooks(ctx, decision.hooks, slice);
         if (before.failed)
             return { end: failed(ctx, `a hook before the plan failed, so nothing in ${part} of wave ${k} was planned or applied`) };
         if (before.waitingOn)
@@ -850,6 +897,14 @@ async function planOpWave(options, { k, pass }) {
     // #3836: a point at base that cannot be asked fails the wave; the ledger never stands in for it.
     if (rules.pointRefused)
         return { end: failed(ctx, `wave ${k} (${wave.name}): ${rules.pointRefused}, so nothing in it was planned or applied`) };
+    // #4290: rules at base that cannot be read fail the wave; fewer approvers never stand in for them.
+    if (rules.quorumRefused)
+        return { end: failed(ctx, `wave ${k} (${wave.name}): ${rules.quorumRefused}, so nothing in it was planned or applied`) };
+    if (rules.quorum && rules.point)
+        return { end: failed(ctx, `wave ${k} (${wave.name}): approvals.quorum and a decision point are both set at ${base.slice(0, 12)}; a gate that asks a point takes its deciders from the point, so nothing in it was planned or applied`) };
+    if (JSON.stringify(spec.approvals?.quorum ?? null) !== JSON.stringify(rules.quorum ?? null)) {
+        log(`wave ${k} (${wave.name}): its approval rules are read at ${base.slice(0, 12)}, and this change's differ; the ones at base hold`);
+    }
     const own = opWavePointAt(spec, wave.name);
     if (JSON.stringify(own) !== JSON.stringify(rules.point)) {
         log(`wave ${k} (${wave.name}): its gate's decision point is read at ${base.slice(0, 12)} (${rules.point?.name ?? "none"}), and this change's differs (${own?.name ?? "none"}); the one at base holds`);
@@ -880,7 +935,7 @@ async function planOpWave(options, { k, pass }) {
         ...(neverOverMcp ? { neverOverMcp: true } : {}),
         ...(rules.point ? { point: { ...rules.point } } : {}),
     };
-    const before = await runHooks(ctx, "before-plan", rules.hooks["before-plan"], wave.runs);
+    const before = await runBeforePlanHooks(ctx, rules.hooks, wave.runs);
     if (before.failed)
         return { end: failed(ctx, `a hook before the plan failed, so nothing in wave ${k} was planned or applied`) };
     if (before.waitingOn)
@@ -948,6 +1003,10 @@ async function decideOpWave(options, { prior }, planned, digest) {
     const { policy, source, base } = planned.rules;
     decision.digest = digest;
     decision.members = members;
+    // #4290: the rules at base whose targets glob matches one of the wave's runs.
+    const takes = planned.rules.quorum ? quorumRulesFor(planned.rules.quorum, members.map((m) => m.member)) : [];
+    if (takes.length > 0)
+        decision.quorum = takes;
     if (extras)
         decision.extras = extras;
     if (pending)
@@ -956,6 +1015,10 @@ async function decideOpWave(options, { prior }, planned, digest) {
     if (after.failed)
         return { end: failed(ctx, `a hook after the plan failed, so nothing in wave ${k} was applied`) };
     holds.push(...planned.before, ...after.holds);
+    // #4294: a run the product's policy holds makes the wave wait for a person, as a held hook does.
+    for (const m of members)
+        if (m.held)
+            holds.push(`policy on ${m.member} (${m.held.rules.join(", ")})${m.held.reason ? `: ${m.held.reason}` : ""}`);
     if (holds.length > 0)
         decision.heldBy = holds;
     if (after.waitingOn)
@@ -1225,6 +1288,8 @@ function failed(ctx, line) {
 async function settleGate(options, ctx, decision) {
     if (decision.point)
         return settlePointGate(options, ctx, decision, decision.point);
+    if (decision.quorum?.length)
+        return settleQuorumGate(options, ctx, decision, decision.quorum);
     const { spec, k, wave, cwd } = ctx;
     const { gate, digest, approval, base, policy, members } = decision;
     const { ledger, port } = await gatePort(options, cwd, gate, approval, base);
@@ -1280,6 +1345,120 @@ async function settleGate(options, ctx, decision) {
     decision.status = "waiting";
     decision.approve = approveCommand(spec.name, gate, undefined, digest, approval === "sealed");
 }
+/**
+ * Decide a gate under approval rules (#4290): the rules at base the wave's
+ * targets take, each met by distinct human approvers of the digest. Roles
+ * come from `.chant/trust.json` at base, for an approver a seal proves, or
+ * under `pr-review` the merged pull request's review read from the forge in
+ * this run. That review is written to the ledger once per approving
+ * reviewer, so each counts on their own. `notAuthor` reads the author from
+ * the same pull request; with none, no approver can show they are someone
+ * else and the rule waits.
+ */
+async function settleQuorumGate(options, ctx, decision, rules) {
+    const { spec, k, wave, cwd, log } = ctx;
+    const { gate, digest, approval, base, policy, members } = decision;
+    const { ledger, port } = await gatePort(options, cwd, gate, approval, base);
+    const now = options.now ?? new Date().toISOString();
+    const spent = decision.spend === "base" ? ((await ledger.readApplied?.(spec.name)) ?? []).filter((a) => a.gate === gate) : undefined;
+    const review = await import("./gate-review.js");
+    const trust = (options.trust ?? ((b) => review.trustPolicyAt(cwd, b)))(base);
+    const label = `wave ${k} (${wave.name})`;
+    // The merged pull request: its author for notAuthor, and its review under pr-review.
+    let merged = null;
+    let unknown;
+    const asks = approval === "pr-review" || rules.some((r) => r.notAuthor);
+    const head = asks ? (options.head ?? execFileSync("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf-8" }).trim()) : "";
+    if (asks) {
+        try {
+            merged = await (options.reviews ?? review.reviewSourceFromEnv()).mergedReview(head);
+            if (!merged)
+                unknown = `no merged pull request produced ${head.slice(0, 12)}`;
+        }
+        catch (err) {
+            unknown = `the forge's review could not be read: ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    if (unknown && rules.some((r) => r.notAuthor))
+        log(`${label}: ${unknown}, so the change's author is not known`);
+    if (approval === "pr-review" && unknown)
+        decision.review = { reason: unknown };
+    let reviewed;
+    if (approval === "pr-review" && merged) {
+        const plans = merged.approvers.length === 0 ? null : await (options.headPlans ?? ((name, h) => readHeadPlans(name, h, cwd)))(spec.name, merged.head);
+        const { reviewApproval } = await import("../gate-decision.js");
+        const outcome = reviewApproval(merged, plans?.waves.find((w) => w.wave === k)?.digest, digest);
+        decision.review = outcome.review;
+        const reviewSpent = spent !== undefined && isApprovalSpent(spent, { gate, planDigest: digest, review: { head: merged.head } });
+        if (reviewSpent)
+            decision.review = { ...outcome.review, reason: `a wave already applied ${digest} under the review of #${merged.pr} at ${merged.head.slice(0, 12)}, so the review is spent` };
+        if (outcome.approved && !reviewSpent) {
+            reviewed = { head: merged.head, approvers: merged.approvers };
+            // Each approving reviewer once, so the rules count them one by one.
+            const had = (await ledger.read(spec.name)).resolutions.filter((r) => r.gate === gate && r.review?.head === merged.head && samePlanDigest(r.planDigest, digest));
+            const note = `approved by the review of #${merged.pr} at ${merged.head.slice(0, 12)}: ${merged.approvers.join(", ")}`;
+            for (const who of merged.approvers) {
+                if (had.some((r) => samePrincipal(r.resolvedBy, who)))
+                    continue;
+                await ledger.appendResolution?.({
+                    op: spec.name,
+                    gate,
+                    resolvedBy: who,
+                    timestamp: now,
+                    planDigest: digest,
+                    approver: { kind: "human" },
+                    gitSha: head,
+                    ...(ciRunIdFromEnv() ? { runId: ciRunIdFromEnv() } : {}),
+                    note,
+                    ...(merged.url ? { url: merged.url } : {}),
+                    review: { pr: merged.pr, head: merged.head, approvers: merged.approvers },
+                });
+            }
+        }
+    }
+    const judge = trustQuorumJudge({
+        signers: trust,
+        roles: trust.roles,
+        ...(merged ? { authors: [merged.author] } : {}),
+        ...(reviewed ? { review: reviewed } : {}),
+    });
+    const held = decision.heldBy?.length ? `, held by ${decision.heldBy.join(", ")}` : "";
+    const check = await decideWaveGate(port, {
+        op: spec.name,
+        gate,
+        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 } : {}),
+        fields: { ...decision.pending, approvalMode: approval },
+        ...(decision.neverOverMcp ? { neverOverMcp: true } : {}),
+        approval: { quorum: rules, mode: "log-only" },
+        judge,
+    });
+    if (check.satisfied) {
+        const by = (check.approvals ?? [check.resolution]).map((r) => r.resolvedBy);
+        decision.status = "approved";
+        decision.via = reviewed && check.resolution.review?.head === reviewed.head ? "pr-review" : "ledger";
+        decision.approvedBy = by.join(", ");
+        decision.approvedAt = check.resolution.timestamp;
+        log(`${label}: the approval rules at ${base.slice(0, 12)} are met by ${by.join(", ")}`);
+        return;
+    }
+    logRefused(log, label, check);
+    decision.pendingFact = check.pending;
+    decision.recorded = check.recorded;
+    decision.waitingSince = check.pending.timestamp;
+    if (check.mismatch)
+        decision.mismatch = check.mismatch;
+    if (check.quorum?.rules) {
+        decision.quorumProgress = check.quorum.rules;
+        for (const p of check.quorum.rules)
+            log(`${label}: approval rule ${quorumRuleLine(p)}`);
+        log(`${label}: the approval rules at ${base.slice(0, 12)} are not met (${quorumWaiting(check.quorum.rules)}), so it waits for more approvals of ${digest}`);
+    }
+    decision.status = "waiting";
+    decision.approve = approveCommand(spec.name, gate, undefined, digest, approval === "sealed" || rules.some(ruleNeedsProof));
+}
 /**
  * Decide a gate that asks a decision point (#3836), as an Op gate with a
  * `point` is decided (#3170): ask it with `gate.planDigest` set to the set

package/dist/op/op-waves.d.ts

@@ -43,6 +43,14 @@
  * `chant/lifecycle`, as terragucci's wave gate does, and that approval is
  * spent: the same digest needs a new approval to apply again.
  *
+ * ## Approval rules (#4290)
+ *
+ * With `approvals: { quorum: [...] }` (read at base), a wave takes each rule
+ * whose `targets` glob matches one of its runs' targets and waits until each
+ * is met: `count` distinct people, from `roles` when it names them (granted
+ * in `.chant/trust.json` at base), one of them not the author with
+ * `notAuthor`. See `./gate-quorum.ts`.
+ *
  * ## Wave-level commands and hooks (#3762)
  *
  * A product whose tool plans a whole wave in one call (Terragrunt's `run
@@ -68,6 +76,7 @@
 import type { OpEnvironment, OpSetupStep } from "../lexicon.js";
 import type { CiRunner } from "../ci-jobs.js";
 import { type GatePoint } from "./gate-point.js";
+import { type GateQuorumRule } from "./gate-quorum.js";
 import { type NotifyConfig } from "../notify.js";
 /**
  * The variables a wave job reads its notify secrets from, for the lexicons
@@ -128,13 +137,23 @@ export interface OpWaveHook {
     onFailure?: OpWaveHookFailure;
     /** Run once per run of the wave, rather than once for the wave. */
     perRun?: boolean;
+    /**
+     * The runs the hook is for (#4288): targets, or patterns where `*` matches
+     * within one `/` segment and `**` across segments, as a job group's `runs`.
+     * A `perRun` hook runs for the matching runs only. A hook that runs once
+     * for the wave runs when any run matches, or when no run is known yet (a
+     * `discover` wave before its plan). Absent: every run.
+     */
+    targets?: string[];
 }
 /** The stages a hook runs around. */
-export type OpWaveHookStage = "plan" | "apply" | "gate";
+export type OpWaveHookStage = "observe" | "plan" | "apply" | "gate";
 /** When a hook runs. */
-export type OpWaveHookMoment = "before-plan" | "after-plan" | "after-gate" | "before-apply" | "after-apply";
+export type OpWaveHookMoment = "before-observe" | "before-plan" | "after-plan" | "after-gate" | "before-apply" | "after-apply";
 /**
- * Every moment, in the order a wave reaches them. `after-gate` (#3821) runs
+ * Every moment, in the order a wave reaches them. `before-observe` (#4288)
+ * runs before anything reads live state: ahead of `before-plan` in every job
+ * that plans, the deciding job's and each share's. `after-gate` (#3821) runs
  * once the gate decided, whatever it decided: approved, let through,
  * waiting, or refused by a policy denial.
  */
@@ -149,7 +168,9 @@ export type OpWaveApplyHooksRunner = "chant" | "apply";
 export declare const OP_WAVE_APPLY_HOOKS_RUNNERS: readonly OpWaveApplyHooksRunner[];
 /** Stage hooks (#3762), read from the spec at the base commit like the gate policy. */
 export interface OpWaveHooks {
+    /** `before.observe` (#4288) runs before anything reads live state, ahead of `before.plan`. */
     before?: {
+        observe?: OpWaveHook[];
         plan?: OpWaveHook[];
         apply?: OpWaveHook[];
     };
@@ -418,6 +439,18 @@ export interface OpWavesApprovals {
      * approval of a digest passes that digest as often as it is planned.
      */
     spend?: boolean;
+    /**
+     * Approval rules (#4290): a wave takes each rule whose `targets` glob
+     * matches one of its runs' targets (a rule with no `targets` covers every
+     * wave), and applies once each is met by distinct human approvers of its
+     * set digest. Read at the base commit, with the roles from
+     * `.chant/trust.json` there, so a change cannot loosen the rules its own
+     * wave is judged by. A role, or `notAuthor`, counts only a proven
+     * approver: a seal that verifies against the signers at base, or under
+     * `pr-review` the merged pull request's review. `notAuthor` reads the
+     * author from that pull request. See `./gate-quorum.ts`.
+     */
+    quorum?: GateQuorumRule[];
 }
 /** The scheduled resume job of an Op waves pipeline (#3683). */
 export interface OpWavesResume {
@@ -462,6 +495,13 @@ export declare function assertOpWavesSpec(spec: OpWavesSpec): void;
  * across segments.
  */
 export declare function opWaveRunMatches(pattern: string, target: string): boolean;
+/**
+ * The runs of `runs` hook `hook` is for (#4288): those its `targets` match,
+ * or every run when it names none.
+ */
+export declare function opWaveHookRuns<T extends {
+    target: string;
+}>(hook: Pick<OpWaveHook, "targets">, runs: readonly T[]): T[];
 /** The runs of `runs` that job group `group` holds (#3914). */
 export declare function opWaveGroupRuns<T extends {
     target: string;
@@ -473,6 +513,18 @@ export declare function opWaveGroupRuns<T extends {
 export declare function opWaveGroupsProblem(wave: Pick<OpWave, "name" | "jobs">, targets: readonly string[]): string | undefined;
 /** Refuse hooks no runner could run, naming what is wrong (#3762). */
 export declare function assertOpWaveHooks(where: string, hooks: OpWaveHooks | undefined): void;
+/**
+ * The moments a pull-request job runs hooks at (#4288): `pr-plan` and
+ * `pr-record` run the observe and plan moments, and `pr-apply` the apply
+ * moments too. The pull request's gate has no `after-gate` moment.
+ */
+export declare const PR_LOOP_HOOK_MOMENTS: readonly OpWaveHookMoment[];
+/**
+ * Refuse `ci.hooks` a pull-request job could not run (#4288): what
+ * {@link assertOpWaveHooks} refuses, plus `after.gate` and `apply.runBy`,
+ * since chant itself runs a pull request's apply.
+ */
+export declare function assertPrLoopHooks(where: string, hooks: OpWaveHooks | undefined): void;
 /** The hooks of each moment for wave `name`: the spec's, then the wave's own. */
 export declare function opWaveHooksAt(spec: Pick<OpWavesSpec, "hooks" | "waves">, name: string): Record<OpWaveHookMoment, OpWaveHook[]>;
 /** Who runs wave `name`'s apply-stage hooks (#3804): the wave's `hooks.apply.runBy`, else the spec's, else `chant`. */

package/dist/op/op-waves.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"op-waves.d.ts","sourceRoot":"","sources":["../../src/op/op-waves.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"op-waves.d.ts","sourceRoot":"","sources":["../../src/op/op-waves.ts"],"names":[],"mappings":"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"}

package/dist/op/op-waves.js

@@ -43,6 +43,14 @@
  * `chant/lifecycle`, as terragucci's wave gate does, and that approval is
  * spent: the same digest needs a new approval to apply again.
  *
+ * ## Approval rules (#4290)
+ *
+ * With `approvals: { quorum: [...] }` (read at base), a wave takes each rule
+ * whose `targets` glob matches one of its runs' targets and waits until each
+ * is met: `count` distinct people, from `roles` when it names them (granted
+ * in `.chant/trust.json` at base), one of them not the author with
+ * `notAuthor`. See `./gate-quorum.ts`.
+ *
  * ## Wave-level commands and hooks (#3762)
  *
  * A product whose tool plans a whole wave in one call (Terragrunt's `run
@@ -66,6 +74,7 @@
  * the wave (exit 8). See `./op-waves-run.ts`.
  */
 import { gatePointProblems } from "./gate-point.js";
+import { quorumProblems } from "./gate-quorum.js";
 import { notifyConfigProblem } from "../notify.js";
 import { WAVE_GATE_NAME_PATTERN, waveGateNameFrom, waveShare } from "../wave-layout.js";
 /**
@@ -102,11 +111,13 @@ export function opWavePointAt(spec, name) {
 }
 export const OP_WAVE_HOOK_FAILURES = ["fail", "approve"];
 /**
- * Every moment, in the order a wave reaches them. `after-gate` (#3821) runs
+ * Every moment, in the order a wave reaches them. `before-observe` (#4288)
+ * runs before anything reads live state: ahead of `before-plan` in every job
+ * that plans, the deciding job's and each share's. `after-gate` (#3821) runs
  * once the gate decided, whatever it decided: approved, let through,
  * waiting, or refused by a policy denial.
  */
-export const OP_WAVE_HOOK_MOMENTS = ["before-plan", "after-plan", "after-gate", "before-apply", "after-apply"];
+export const OP_WAVE_HOOK_MOMENTS = ["before-observe", "before-plan", "after-plan", "after-gate", "before-apply", "after-apply"];
 export const OP_WAVE_APPLY_HOOKS_RUNNERS = ["chant", "apply"];
 export const OP_WAVES_DIGEST_OVER = ["all", "changing"];
 /** The default gate name pattern. */
@@ -171,13 +182,25 @@ export function assertOpWavesSpec(spec) {
     if (spec.approvals !== undefined) {
         const a = spec.approvals;
         if (a === null || typeof a !== "object" || Array.isArray(a))
-            throw new Error(`${where}: \`approvals\` must be { "spend"?: true | false }.`);
+            throw new Error(`${where}: \`approvals\` must be { "spend"?: true | false, "quorum"?: [...] }.`);
         for (const [key, value] of Object.entries(a)) {
+            if (key === "quorum") {
+                // #4290: approval rules, read at base like the policy.
+                if (!Array.isArray(value))
+                    throw new Error(`${where}: approvals.quorum must be a list of rules, each { "targets"?, "count", "roles"?, "notAuthor"? }.`);
+                const problems = quorumProblems(value, "approvals.quorum", { notAuthor: true });
+                if (problems.length > 0)
+                    throw new Error(`${where}: ${problems.join("; ")}.`);
+                continue;
+            }
             if (key !== "spend")
-                throw new Error(`${where}: approvals.${key} is not a setting; the one there is approvals.spend.`);
+                throw new Error(`${where}: approvals.${key} is not a setting; the ones there are approvals.spend and approvals.quorum.`);
             if (typeof value !== "boolean")
                 throw new Error(`${where}: approvals.spend must be true or false.`);
         }
+        if (a.quorum?.length && (spec.point !== undefined || spec.waves.some((w) => w.point !== undefined))) {
+            throw new Error(`${where}: approvals.quorum and a decision point are both set; a gate that asks a point takes its deciders and quorum from the point, so drop one of them.`);
+        }
     }
     if (spec.gateName !== undefined) {
         if (typeof spec.gateName !== "string" || !spec.gateName.includes("{k}") || /\s/.test(spec.gateName)) {
@@ -394,6 +417,15 @@ export function opWaveRunMatches(pattern, target) {
     }
     return new RegExp(`^${re}$`).test(target);
 }
+/**
+ * The runs of `runs` hook `hook` is for (#4288): those its `targets` match,
+ * or every run when it names none.
+ */
+export function opWaveHookRuns(hook, runs) {
+    if (!hook.targets)
+        return [...runs];
+    return runs.filter((run) => hook.targets.some((pattern) => opWaveRunMatches(pattern, run.target)));
+}
 /** The runs of `runs` that job group `group` holds (#3914). */
 export function opWaveGroupRuns(group, runs) {
     return runs.filter((run) => group.runs.some((pattern) => opWaveRunMatches(pattern, run.target)));
@@ -422,7 +454,7 @@ export function assertOpWaveHooks(where, hooks) {
     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"? } }.`);
+        throw new Error(`${where}: \`hooks\` must be { "before"?: { "observe"?, "plan"?, "apply"? }, "after"?: { "plan"?, "gate"?, "apply"? } }.`);
     }
     for (const [side, stages] of Object.entries(hooks)) {
         if (side === "apply") {
@@ -443,8 +475,10 @@ export function assertOpWaveHooks(where, hooks) {
             const at = `hooks.${side}.${stage}`;
             if (stage === "gate" && side === "before")
                 throw new Error(`${where}: ${at} is not a moment; a hook runs after the gate (hooks.after.gate), or before the plan or the apply.`);
-            if (stage !== "plan" && stage !== "apply" && stage !== "gate")
-                throw new Error(`${where}: ${at} is not a stage; a hook runs before or after plan or apply, or after the gate.`);
+            if (stage === "observe" && side === "after")
+                throw new Error(`${where}: ${at} is not a moment; a hook runs before the observe (hooks.before.observe), or after the plan, which reads what the observe saw.`);
+            if (stage !== "observe" && stage !== "plan" && stage !== "apply" && stage !== "gate")
+                throw new Error(`${where}: ${at} is not a stage; a hook runs before the observe, before or after plan or apply, or after the gate.`);
             if (!Array.isArray(list))
                 throw new Error(`${where}: ${at} must be a list of hooks.`);
             list.forEach((hook, i) => {
@@ -463,18 +497,39 @@ export function assertOpWaveHooks(where, hooks) {
                 }
                 if (hook.perRun !== undefined && typeof hook.perRun !== "boolean")
                     throw new Error(`${where}: ${which}.perRun must be true or false.`);
+                if (hook.targets !== undefined && (!Array.isArray(hook.targets) || hook.targets.length === 0 || !hook.targets.every((t) => typeof t === "string" && t !== ""))) {
+                    throw new Error(`${where}: ${which}.targets must be a non-empty list of targets or patterns, such as ["prod/*"].`);
+                }
                 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}"))) {
+                else if (side === "before" && (stage === "plan" || stage === "observe") && hook.command.some((part) => part.includes("{plan}"))) {
                     throw new Error(`${where}: ${which} runs before the plan, so it has no {plan} yet.`);
                 }
             });
         }
     }
 }
+/**
+ * The moments a pull-request job runs hooks at (#4288): `pr-plan` and
+ * `pr-record` run the observe and plan moments, and `pr-apply` the apply
+ * moments too. The pull request's gate has no `after-gate` moment.
+ */
+export const PR_LOOP_HOOK_MOMENTS = ["before-observe", "before-plan", "after-plan", "before-apply", "after-apply"];
+/**
+ * Refuse `ci.hooks` a pull-request job could not run (#4288): what
+ * {@link assertOpWaveHooks} refuses, plus `after.gate` and `apply.runBy`,
+ * since chant itself runs a pull request's apply.
+ */
+export function assertPrLoopHooks(where, hooks) {
+    assertOpWaveHooks(where, hooks);
+    if (hooks?.after?.gate !== undefined)
+        throw new Error(`${where}: hooks.after.gate runs in an Op waves job only; a pull-request job runs hooks before the observe, before and after the plan, and before and after the apply.`);
+    if (hooks?.apply !== undefined)
+        throw new Error(`${where}: hooks.apply.runBy is for an Op waves spec; chant runs a pull request's apply, so it runs the apply-stage hooks itself.`);
+}
 /** The hooks of each moment for wave `name`: the spec's, then the wave's own. */
 export function opWaveHooksAt(spec, name) {
     const wave = spec.waves.find((w) => w.name === name);