@intentius/chant 0.116.0 → 0.118.0

package/dist/op/gate-review.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Approval modes for a gate (#3684): which approvals of a wave's digest
+ * count.
+ *
+ * - `ledger` (the default): any resolution on `chant/lifecycle` that names
+ *   the digest, as `chant approve` writes it. Anyone who can push to the
+ *   branch can approve, in anyone's name.
+ * - `sealed`: a resolution counts only when its seal (`chant approve --sign`)
+ *   verifies against the signers file read at the base commit, for the
+ *   approver it names. A key that the change being applied adds to the
+ *   signers file is not at base, so it cannot approve that change.
+ * - `pr-review`: a resolution counts as under `ledger`, and so does the
+ *   forge review of the pull request that merged the applied commit: an
+ *   approving review of the pull request's head, by a writer other than its
+ *   author. It approves the digest that head planned, which the pull
+ *   request's pipeline records on `chant/lifecycle` with `chant run wave
+ *   --record-plans` ({@link HeadPlans}). A plan that moved after the review
+ *   waits for a `chant approve` of the new digest.
+ *
+ * What counts as an approving review, per forge:
+ *
+ * | Forge | Counts | Writer |
+ * |---|---|---|
+ * | GitHub | the reviewer's newest deciding review is `APPROVED` and names the head (`commit_id`) | `GET /repos/{repo}/collaborators/{login}/permission` is `admin`, `maintain` or `write` |
+ * | Forgejo | the same, not dismissed and not stale | the review is `official`, which Forgejo sets for a reviewer with write access |
+ * | GitLab | the merge request's approvals, when the project removes approvals on a new push (`reset_approvals_on_push`), since a GitLab approval names no commit | the approver's access level is Developer (30) or higher |
+ *
+ * A standing review that requests changes, from a writer, holds the review
+ * back. The author's own review never counts.
+ */
+import { type TrustPolicy } from "../workspace/trust/policy.js";
+import { type ForgeFetch, type ForgeKind } from "../pr-forge.js";
+import type { GateApprovalRule } from "./gate.js";
+export { GATE_APPROVAL_SOURCES, type GateApprovalSource } from "./op-waves.js";
+/** The signers policy at `base`, read from the repository at `cwd`. */
+export declare function trustPolicyAt(cwd: string, base: string): TrustPolicy;
+/**
+ * The rule a `sealed` gate judges approvals by: a seal that verifies for the
+ * approver against `policy`, the signers at base. With no signers file at
+ * base nothing verifies, so nothing passes the gate.
+ */
+export declare function sealedApprovalRule(gate: string, policy: TrustPolicy): GateApprovalRule;
+/** Both rules at once: an approval counts only when neither refuses it. */
+export declare function bothRules(a: GateApprovalRule | null, b: GateApprovalRule | null): GateApprovalRule | null;
+/** The digests each wave planned at one commit, recorded for a review of it to approve. */
+export interface HeadPlans {
+    version: 1;
+    /** The Op waves spec's name. */
+    name: string;
+    /** The commit the waves were planned at: a pull request's head. */
+    head: string;
+    timestamp: string;
+    waves: Array<{
+        wave: number;
+        name: string;
+        digest: string;
+    }>;
+}
+/** Where {@link HeadPlans} for `head` live on `chant/lifecycle`: `_wave-plans/<name>/<head>.json`. */
+export declare const HEAD_PLANS_DIR = "_wave-plans";
+export declare function headPlansPath(name: string, head: string): {
+    dir: string;
+    file: string;
+};
+/** The merged pull request's review, as a `pr-review` gate reads it. */
+export interface MergedReview {
+    pr: number;
+    url?: string;
+    /** The author, as a principal (`github:<login>`). */
+    author: string;
+    /** The pull request's head commit. */
+    head: string;
+    /** Writers other than the author whose approval of the head stands, as principals. */
+    approvers: string[];
+    /** Why a review did not count, one line each. */
+    refused: string[];
+}
+/** What a `pr-review` gate asks of the forge. */
+export interface ReviewSource {
+    kind: ForgeKind;
+    /** The merged pull request whose merge produced `sha`, with its review, or null when none did. */
+    mergedReview(sha: string): Promise<MergedReview | null>;
+}
+export interface ReviewSourceOptions {
+    apiBase: string;
+    /** `owner/name` on GitHub and Forgejo, the project id on GitLab. */
+    repo: string;
+    token: string;
+    /** The forge's host, for naming people. */
+    host: string;
+    fetch?: ForgeFetch;
+}
+/** A GitHub reader of pull request reviews. The token needs `pull-requests: read`. */
+export declare function githubReviews(opts: ReviewSourceOptions): ReviewSource;
+/** A Forgejo (or Gitea) reader of pull request reviews. */
+export declare function forgejoReviews(opts: ReviewSourceOptions): ReviewSource;
+/** A GitLab reader of merge request approvals. The token needs `read_api`. */
+export declare function gitlabReviews(opts: ReviewSourceOptions): ReviewSource;
+/**
+ * The review source for the CI job this runs in: GitLab CI, Forgejo Actions
+ * or GitHub Actions, told apart as `./gate-resume.ts` does. The token is
+ * `CHANT_FORGE_TOKEN`, else `GITHUB_TOKEN`/`GH_TOKEN` or `GITLAB_TOKEN`.
+ * Throws naming what is missing.
+ */
+export declare function reviewSourceFromEnv(env?: Record<string, string | undefined>, fetchImpl?: ForgeFetch): ReviewSource;
+/**
+ * The head of the pull request a CI job runs for, from its environment: the
+ * event payload's `pull_request.head.sha` on GitHub and Forgejo (whose
+ * checkout is a merge preview, not the head), and on GitLab the merge
+ * request's source commit. Undefined outside a pull request's pipeline.
+ */
+export declare function pullRequestHeadFromEnv(env?: Record<string, string | undefined>): string | undefined;
+//# sourceMappingURL=gate-review.d.ts.map

package/dist/op/gate-review.d.ts.map

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

package/dist/op/gate.d.ts.map

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

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

@@ -11,13 +11,20 @@
  *   needs an approval waits on `<gate>-wave-<k>` bound to
  *   {@link waveSetDigest} over its members, and exits 3 when nobody approved
  *   that digest.
+ * - Which approvals count is the wave's `approval`, read at base like its
+ *   policy (#3684): `ledger`, `sealed` or `pr-review` (`./gate-review.ts`).
+ *   Under `pr-review` the pull request's pipeline runs `--record-plans`
+ *   ({@link recordOpWaveHeadPlans}), which plans every wave at the head and
+ *   records the digests a review of that head approves.
  * - Apply: each run's `apply` command. A share job (`--share i`) re-plans its
  *   slice first and refuses, without applying it, a run whose plan digest is
  *   not the one the deciding job recorded (exit 4).
  */
 import { type WaveMember } from "../gated-waves.js";
 import { type GateLedgerPort } from "./gate.js";
-import { type OpWaveGatePolicy, type OpWavesSpec } from "./op-waves.js";
+import type { HeadPlans, ReviewSource } from "./gate-review.js";
+import type { TrustPolicy } from "../workspace/trust/policy.js";
+import { type GateApprovalSource, type OpWaveGatePolicy, type OpWavesSpec } from "./op-waves.js";
 /** What a run's plan command writes to `{plan}`. */
 export interface OpWavePlanFile {
     planDigest: string;
@@ -42,6 +49,8 @@ export interface OpWaveDecision {
     op: string;
     gate: string;
     policy: OpWaveGatePolicy;
+    /** Which approvals count, read at base with the policy (#3684). */
+    approval: GateApprovalSource;
     policySource: OpWavePolicySource;
     /** The base commit the policy was read at. */
     base: string;
@@ -50,6 +59,16 @@ export interface OpWaveDecision {
     /** `approved`: an approval of this digest stands. `not-required`: the policy lets it through. `waiting`: neither. */
     status: "approved" | "not-required" | "waiting";
     approvedBy?: string;
+    /** How the approval arrived: a resolution on the ledger, or the merged pull request's review (#3684). */
+    via?: "ledger" | "pr-review";
+    /** The review that approved the wave, or why the review did not, under `pr-review`. */
+    review?: {
+        pr?: number;
+        head?: string;
+        approvers?: string[];
+        url?: string;
+        reason?: string;
+    };
     /** The command that approves this digest, when waiting. */
     approve?: string;
 }
@@ -69,6 +88,7 @@ export declare function parseOpWavesSpec(text: string, where: string): OpWavesSp
  */
 export declare function readOpWavePolicy(specFile: string, name: string, base: string, cwd: string, show?: OpWaveShowAtBase): {
     policy: OpWaveGatePolicy;
+    approval: GateApprovalSource;
     source: OpWavePolicySource;
     base: string;
 };
@@ -98,6 +118,14 @@ export interface RunOpWaveOptions {
     show?: OpWaveShowAtBase;
     now?: string;
     log?: (line: string) => void;
+    /** The applied commit, which a `pr-review` gate finds the merged pull request by. Default `git rev-parse HEAD`. */
+    head?: string;
+    /** The forge's reviews, for a `pr-review` gate. Default: the CI job's forge (`reviewSourceFromEnv`). */
+    reviews?: ReviewSource;
+    /** The plans recorded for a pull request's head. Default: read from `chant/lifecycle`. */
+    headPlans?: (name: string, head: string) => Promise<HeadPlans | null>;
+    /** The signers policy at base, for a `sealed` gate. Default: read from the base commit. */
+    trust?: (base: string) => TrustPolicy;
 }
 export interface RunOpWaveResult {
     /** 0 applied (or decided), 1 a run failed, 3 waiting for an approval, 4 a plan moved since the decision. */
@@ -112,4 +140,22 @@ export interface RunOpWaveResult {
 export declare function opWaveNeedsApproval(policy: OpWaveGatePolicy, members: readonly OpWaveMember[]): boolean;
 /** Plan, decide and apply one wave, or one part of a wide wave. */
 export declare function runOpWave(options: RunOpWaveOptions): Promise<RunOpWaveResult>;
+export interface RecordHeadPlansOptions {
+    spec: OpWavesSpec;
+    cwd?: string;
+    exec?: OpWaveExec;
+    /** The commit the plans are for. Default: the pull request's head from the CI job's environment, else `git rev-parse HEAD`. */
+    head?: string;
+    now?: string;
+    /** Write the record. Default: append to `chant/lifecycle` and push. */
+    write?: (plans: HeadPlans) => Promise<void>;
+}
+/**
+ * `chant run wave --spec <file> --record-plans` (#3684): plan every wave at a
+ * pull request's head and record each wave's digest on `chant/lifecycle`,
+ * `_wave-plans/<name>/<head>.json`. A `pr-review` wave reads it after the
+ * merge: the review of that head approves the digests it planned, and only
+ * those.
+ */
+export declare function recordOpWaveHeadPlans(options: RecordHeadPlansOptions): Promise<HeadPlans>;
 //# sourceMappingURL=op-waves-run.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"op-waves-run.d.ts","sourceRoot":"","sources":["../../src/op/op-waves-run.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"op-waves-run.d.ts","sourceRoot":"","sources":["../../src/op/op-waves-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,OAAO,EAA+B,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC9E,OAAO,EAAmD,KAAK,cAAc,EAAE,MAAM,QAAQ,CAAC;AAC9F,OAAO,KAAK,EAAE,SAAS,EAAgB,YAAY,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAOL,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EAErB,KAAK,WAAW,EACjB,MAAM,YAAY,CAAC;AAEpB,oDAAoD;AACpD,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,sFAAsF;IACtF,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,gCAAgC;IAChC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,kDAAkD;AAClD,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,uCAAuC;AACvC,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,gBAAgB,CAAC;AAE3D,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,gBAAgB,CAAC;IACzB,mEAAmE;IACnE,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,YAAY,EAAE,kBAAkB,CAAC;IACjC,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,qHAAqH;IACrH,MAAM,EAAE,UAAU,GAAG,cAAc,GAAG,SAAS,CAAC;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yGAAyG;IACzG,GAAG,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAC;IAC7B,uFAAuF;IACvF,MAAM,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7F,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,gFAAgF;AAChF,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;AAQjE,kGAAkG;AAClG,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAoBjH,2DAA2D;AAC3D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAazE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,gBAAgC,GACrC;IAAE,MAAM,EAAE,gBAAgB,CAAC;IAAC,QAAQ,EAAE,kBAAkB,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAgBtG;AAED,0CAA0C;AAC1C,wBAAgB,UAAU,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,EAAE,CAIpI;AAED,oCAAoC;AACpC,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpG;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe;IACf,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,mHAAmH;IACnH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wGAAwG;IACxG,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,0FAA0F;IAC1F,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IACtE,2FAA2F;IAC3F,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,WAAW,CAAC;CACvC;AAED,MAAM,WAAW,eAAe;IAC9B,4GAA4G;IAC5G,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AA8BD,mFAAmF;AACnF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,OAAO,CAKvG;AAED,mEAAmE;AACnE,wBAAsB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAgHnF;AA+FD,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,WAAW,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,+HAA+H;IAC/H,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,SAAS,CAAC,CAmB/F"}

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

@@ -27,6 +27,12 @@
  * the same digest a component fan-out's wave binds). Whether it waits at all
  * is the wave's gate policy, read from the base commit's copy of the spec
  * file, so a change cannot loosen the rule that gates its own merge.
+ *
+ * So is which approvals count (#3684), the wave's `approval`: `ledger` (any
+ * `chant approve` of the digest), `sealed` (only one whose seal verifies
+ * 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`.
  */
 import type { OpEnvironment, OpSetupStep } from "../lexicon.js";
 /** When a wave waits for an approval. */
@@ -38,6 +44,15 @@ export type OpWaveGatePolicy =
 /** Never: only review and branch protection stand in front of the wave. */
  | "never";
 export declare const OP_WAVE_GATE_POLICIES: readonly OpWaveGatePolicy[];
+/** Which approvals of a gate's digest count (#3684). See `./gate-review.ts`. */
+export type GateApprovalSource = 
+/** Any resolution on `chant/lifecycle` that names the digest. */
+"ledger"
+/** As `ledger`, and the merged pull request's review of its head, by a writer other than its author. */
+ | "pr-review"
+/** Only a resolution sealed by a key the signers file at base lists for its approver. */
+ | "sealed";
+export declare const GATE_APPROVAL_SOURCES: readonly GateApprovalSource[];
 /** 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. */
@@ -55,6 +70,11 @@ export interface OpWave {
      * spec file at the base commit, never from the change being applied.
      */
     gate?: OpWaveGatePolicy;
+    /**
+     * Which approvals of the wave's digest count (#3684). Default `"ledger"`.
+     * Like `gate`, the runner reads it from the spec file at the base commit.
+     */
+    approval?: GateApprovalSource;
     /**
      * 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
@@ -97,7 +117,26 @@ export interface OpWavesSpec {
     /** Apply one run whose plan is at `{plan}`. Default `chant run {op} --env {target}`. */
     apply?: string[];
     waves: OpWave[];
+    /**
+     * A scheduled job that starts again a wave job whose approval has arrived
+     * (#3683): it runs `chant run resume --op <name>`, which re-runs the
+     * GitHub run, retries the GitLab job or dispatches the Forgejo workflow.
+     * It approves nothing. Absent, no such job is rendered and an approval is
+     * followed by `chant approve --resume` or a re-run by hand.
+     */
+    resume?: OpWavesResume;
+}
+/** The scheduled resume job of an Op waves pipeline (#3683). */
+export interface OpWavesResume {
+    /**
+     * Five-field cron, such as `"*\/10 * * * *"`. GitHub and Forgejo put it
+     * in the workflow; GitLab runs the job in a pipeline schedule you create,
+     * which sets the cron.
+     */
+    schedule: string;
 }
+/** The command a resume job runs. */
+export declare function opWavesResumeCommand(spec: Pick<OpWavesSpec, "name">): string[];
 /** The default apply command. */
 export declare const OP_WAVE_DEFAULT_APPLY: string[];
 /** Where the runner keeps a wave's decision; a wide wave's deciding job hands it to its share jobs. */

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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE7D,yCAAyC;AACzC,MAAM,MAAM,gBAAgB;AAC1B,2CAA2C;AACzC,QAAQ;AACV,gDAAgD;GAC9C,gBAAgB;AAClB,2EAA2E;GACzE,OAAO,CAAC;AAEZ,eAAO,MAAM,qBAAqB,EAAE,SAAS,gBAAgB,EAA0C,CAAC;AAExG,gGAAgG;AAChG,MAAM,WAAW,SAAS;IACxB,2FAA2F;IAC3F,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,2DAA2D;AAC3D,MAAM,WAAW,MAAM;IACrB,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,EAAE,CAAC;IAClB;;;OAGG;IACH,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qGAAqG;IACrG,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,iFAAiF;IACjF,KAAK,CAAC,EAAE,WAAW,EAAE,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,kHAAkH;IAClH,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,wFAAwF;IACxF,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,iCAAiC;AACjC,eAAO,MAAM,qBAAqB,UAAgD,CAAC;AAEnF,uGAAuG;AACvG,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtF;AAED,yBAAyB;AACzB,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,2FAA2F;IAC3F,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;IAClC,+BAA+B;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,kCAAkC;IAClC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAID,4DAA4D;AAC5D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAoCzD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,CAAC,EAAE,CAOhH;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,CA0B3E;AAED,iCAAiC;AACjC,wBAAgB,QAAQ,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,GAAG,MAAM,CAEhF"}
+{"version":3,"file":"op-waves.d.ts","sourceRoot":"","sources":["../../src/op/op-waves.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.116.0",
+  "version": "0.118.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/build.ts

@@ -19,6 +19,7 @@ import { discover, type DiscoveryResult, type FoldDecision } from "./discovery/i
 import { decodeEntitySet, type DiscoveredEntitiesJson } from "./discovery/entity-wire";
 import { buildDependencyGraph } from "./discovery/graph";
 import { topologicalSort } from "./sort";
+import { statSync } from "node:fs";
 import { resolve } from "node:path";
 
 /**
@@ -641,6 +642,15 @@ function generateManifest(
   };
 }
 
+/** The directory a build discovered from, for build-root contributors; undefined when the build's path is not one (an entity-set JSON's label). */
+function sourceDirOf(path: string): string | undefined {
+  try {
+    return statSync(path).isDirectory() ? resolve(path) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /** What merging build-root contributions produced: non-fatal render notes and
  * fatal messages (a failed contributor, a name collision). */
 export interface BuildRootMergeResult {
@@ -667,6 +677,7 @@ export interface BuildRootMergeResult {
 export async function mergeBuildRootEntities(
   entities: Map<string, Declarable>,
   contributors: ReadonlyArray<BuildRootContributor>,
+  sourceDir?: string,
 ): Promise<BuildRootMergeResult> {
   const warnings: string[] = [];
   const errors: string[] = [];
@@ -677,7 +688,7 @@ export async function mergeBuildRootEntities(
       // ciphertext file to resolve). Contributors run in order, so this also
       // carries what earlier contributors added; the merge below is still the
       // only writer, which is what keeps the collision refusal meaningful.
-      const contribution = await contribute({ entities });
+      const contribution = await contribute({ entities, ...(sourceDir !== undefined ? { sourceDir } : {}) });
       warnings.push(...(contribution.warnings ?? []));
       for (const [name, entity] of contribution.entities) {
         if (entities.has(name)) {
@@ -809,7 +820,7 @@ async function buildFromDiscoveryResult(
   // object, and re-running the contributors there would duplicate every
   // contributed entity once per child.
   if (!parentBuildStack && options?.buildRoots) {
-    const merged = await mergeBuildRootEntities(discoveryResult.entities, options.buildRoots);
+    const merged = await mergeBuildRootEntities(discoveryResult.entities, options.buildRoots, sourceDirOf(resolvedPathForChildStack));
     warnings.push(...merged.warnings);
     for (const message of merged.errors) {
       errors.push(new BuildErrorClass("", message));

package/src/cli/commands/build.ts

@@ -922,7 +922,8 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
   const resourceCount = result.entities.size;
   const fileCount = result.sourceFileCount;
 
-  if (fileCount === 0 && errors.length === 0) {
+  // A build root (a lexicon's own source files, a rendered overlay) can declare everything without one .ts file.
+  if (fileCount === 0 && resourceCount === 0 && errors.length === 0) {
     console.error(formatInfo("No source files found — create .ts files in the target directory"));
   }
 

package/src/cli/handlers/gate-resume.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from "vitest";
+import type { GateResolutionRecord, PendingGateRecord } from "../../lifecycle/gate-ledger";
+import type { ForgeFetch } from "../../pr-forge";
+import { parseArgs } from "../main";
+import { resumeStanding } from "./gate-resume";
+
+const DIGEST = `sha256:${"a".repeat(64)}`;
+const standing: PendingGateRecord = {
+  version: 1,
+  kind: "pending",
+  op: "migrations",
+  gate: "migrations-wave-2",
+  timestamp: "2026-10-01T00:00:00Z",
+  expiresAt: "2026-10-03T00:00:00Z",
+  planDigest: DIGEST,
+  resume: { forge: "github", api: "https://api.github.com", repo: "acme/db", run: "42", attempt: 1 },
+};
+const approval: GateResolutionRecord = { version: 1, op: "migrations", gate: "migrations-wave-2", resolvedBy: "alice", timestamp: "2026-10-01T01:00:00Z", planDigest: DIGEST };
+
+describe("resumeStanding (#3683)", () => {
+  test("no approval, no call", async () => {
+    const fetch: ForgeFetch = async () => {
+      throw new Error("no call expected");
+    };
+    expect(await resumeStanding(standing, [], { env: { GITHUB_TOKEN: "t" }, fetch })).toMatchObject({ status: "not-approved" });
+  });
+
+  test("approved: re-runs the run the pending fact names", async () => {
+    const calls: string[] = [];
+    const fetch: ForgeFetch = async (url, init) => {
+      calls.push(`${init.method} ${new URL(url).pathname}`);
+      const body = init.method === "GET" ? { status: "completed", conclusion: "failure", run_attempt: 1 } : null;
+      return { ok: true, status: 200, text: async () => (body ? JSON.stringify(body) : "") };
+    };
+    const report = await resumeStanding(standing, [approval], { env: { GITHUB_TOKEN: "t" }, fetch });
+    expect(report).toMatchObject({ status: "resumed", approvedBy: "alice" });
+    expect(calls).toEqual(["GET /repos/acme/db/actions/runs/42", "POST /repos/acme/db/actions/runs/42/rerun-failed-jobs"]);
+  });
+
+  test("a fact recorded outside CI, or no token, resumes nothing and says why", async () => {
+    const { resume: _none, ...local } = standing;
+    expect(await resumeStanding(local, [approval], { env: { GITHUB_TOKEN: "t" } })).toMatchObject({ status: "no-job" });
+    expect(await resumeStanding(standing, [approval], { env: {} })).toMatchObject({ status: "no-token" });
+  });
+
+  test("`--resume` takes no value on approve, and keeps its file on the applies", () => {
+    expect(parseArgs(["approve", "migrations", "migrations-wave-2", "--resume"]).resumeRun).toBe(true);
+    expect(parseArgs(["approve", "migrations", "g", "--resume", "--sign"])).toMatchObject({ resumeRun: true, sign: true });
+    expect(parseArgs(["components", "pr-apply", "--resume", "attempt.json"]).resume).toBe("attempt.json");
+  });
+});

package/src/cli/handlers/gate-resume.ts

@@ -0,0 +1,166 @@
+/**
+ * `chant approve <op> <gate> --resume` and `chant run resume` (#3683): start
+ * the CI job that waits at a gate again once its approval has arrived. See
+ * `../../op/gate-resume.ts` for what each forge is asked and the token it
+ * needs. Neither approves anything.
+ */
+
+import {
+  GATES_DIR,
+  isPendingGateExpired,
+  readGateLedger,
+  type GateResolutionRecord,
+  type PendingGateRecord,
+} from "../../lifecycle/gate-ledger";
+import { listFilesInDir, requireLifecycleLedger } from "../../lifecycle/git";
+import {
+  isGateRunLocator,
+  resolutionAnswering,
+  resumeGateRun,
+  resumeTokenFromEnv,
+  type GateResumeOutcome,
+} from "../../op/gate-resume";
+import type { ForgeFetch } from "../../pr-forge";
+import { formatError, formatInfo, formatSuccess, formatWarning } from "../format";
+import type { CommandContext } from "../registry";
+
+/** One waiting gate and what resuming it did. */
+export interface GateResumeReport {
+  op: string;
+  gate: string;
+  environment?: string;
+  /** `resumed` and `skipped` come from the forge; the rest are decided before any call. */
+  status: GateResumeOutcome["status"] | "not-approved" | "no-job" | "no-token" | "failed";
+  message: string;
+  approvedBy?: string;
+  url?: string;
+}
+
+/** The newest pending fact per gate and environment: the facts a run still waits on. */
+function standingFacts(pending: readonly PendingGateRecord[], gate?: string): PendingGateRecord[] {
+  const newest = new Map<string, PendingGateRecord>();
+  for (const p of pending) {
+    if (gate !== undefined && p.gate !== gate) continue;
+    const key = `${p.gate}\u0000${p.environment ?? ""}`;
+    const prior = newest.get(key);
+    if (!prior || new Date(p.timestamp).getTime() >= new Date(prior.timestamp).getTime()) newest.set(key, p);
+  }
+  return [...newest.values()];
+}
+
+export interface ResumeGateOptions {
+  env?: Record<string, string | undefined>;
+  fetch?: ForgeFetch;
+  now?: string;
+  dryRun?: boolean;
+}
+
+/** Resume the job behind one standing pending fact, when an approval answers it. */
+export async function resumeStanding(
+  standing: PendingGateRecord,
+  resolutions: readonly GateResolutionRecord[],
+  opts: ResumeGateOptions = {},
+): Promise<GateResumeReport> {
+  const base = {
+    op: standing.op,
+    gate: standing.gate,
+    ...(standing.environment !== undefined ? { environment: standing.environment } : {}),
+    ...(standing.resume?.url ? { url: standing.resume.url } : {}),
+  };
+  const answer = resolutionAnswering(resolutions, standing);
+  if (!answer) return { ...base, status: "not-approved", message: "no approval answers it yet" };
+  const approvedBy = { approvedBy: answer.resolvedBy };
+  if (!isGateRunLocator(standing.resume)) {
+    return { ...base, ...approvedBy, status: "no-job", message: "its pending fact names no CI job (it was recorded outside CI); run it again by hand" };
+  }
+  const loc = standing.resume;
+  if (opts.dryRun) return { ...base, ...approvedBy, status: "skipped", message: `would resume ${loc.forge} run ${loc.run} (--dry-run)` };
+  const token = resumeTokenFromEnv(loc.forge, opts.env ?? process.env);
+  if (!token) {
+    return {
+      ...base,
+      ...approvedBy,
+      status: "no-token",
+      message: `no token to call ${loc.forge} with: set CHANT_FORGE_TOKEN (or ${loc.forge === "gitlab" ? "GITLAB_TOKEN" : "GITHUB_TOKEN"})`,
+    };
+  }
+  try {
+    const outcome = await resumeGateRun(loc, { token, since: answer.timestamp, ...(opts.fetch ? { fetch: opts.fetch } : {}) });
+    return { ...base, ...approvedBy, status: outcome.status, message: outcome.status === "resumed" ? outcome.how : outcome.reason };
+  } catch (err) {
+    return { ...base, ...approvedBy, status: "failed", message: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/** Resume every job waiting on `op`'s gates (or one gate) whose approval arrived. */
+export async function resumeOpGates(op: string, gate: string | undefined, opts: ResumeGateOptions = {}): Promise<GateResumeReport[]> {
+  const ledger = await readGateLedger(op);
+  const now = opts.now ?? new Date().toISOString();
+  const reports: GateResumeReport[] = [];
+  for (const standing of standingFacts(ledger.pending, gate)) {
+    if (isPendingGateExpired(standing, now)) continue;
+    reports.push(await resumeStanding(standing, ledger.resolutions, opts));
+  }
+  return reports;
+}
+
+function printReport(r: GateResumeReport): void {
+  const where = `${r.op} / ${r.gate}${r.environment !== undefined ? ` (${r.environment})` : ""}`;
+  const by = r.approvedBy ? `, approved by ${r.approvedBy}` : "";
+  const link = r.url ? ` ${r.url}` : "";
+  if (r.status === "resumed") console.error(formatSuccess(`${where}${by}: ${r.message}${link}`));
+  else if (r.status === "failed" || r.status === "no-token") {
+    console.error(formatError({
+      message: `${where}${by}: not resumed: ${r.message}`,
+      hint: "GitHub needs actions: write; GitLab a token with the api scope and the Developer role; Forgejo a token with write:repository.",
+    }));
+  } else console.error(formatInfo(`${where}${by}: not resumed: ${r.message}${link}`));
+}
+
+/**
+ * What `chant approve --resume` runs once the approval is recorded and
+ * pushed. Returns the exit code: 0 when the job was resumed or had nothing to
+ * resume, 1 when a forge call failed or no token was found.
+ */
+export async function resumeAfterApproval(op: string, gate: string, environment: string | undefined, pushed: boolean): Promise<number> {
+  if (!pushed) {
+    console.error(formatWarning({
+      message: "Not resuming: the approval did not reach the remote, so the resumed job would not see it.",
+      hint: "Push chant/lifecycle, then run `chant run resume --op " + op + "`.",
+    }));
+    return 1;
+  }
+  const reports = (await resumeOpGates(op, gate)).filter((r) => environment === undefined || r.environment === environment);
+  if (reports.length === 0) {
+    console.error(formatInfo(`No pending fact for ${op} / ${gate} is waiting, so there is nothing to resume.`));
+    return 0;
+  }
+  for (const r of reports) printReport(r);
+  return reports.some((r) => r.status === "failed" || r.status === "no-token") ? 1 : 0;
+}
+
+/**
+ * `chant run resume [--op <op>] [--dry-run] [--json]`: the scheduled job.
+ * Reads every gate ledger on `chant/lifecycle` (or `--op`'s), and starts
+ * again each CI job that waits at a gate an approval now answers.
+ */
+export async function runResumeCommand(ctx: CommandContext): Promise<number> {
+  try {
+    await requireLifecycleLedger();
+  } catch (err) {
+    console.error(formatError({ message: `Cannot read the gate ledgers: ${err instanceof Error ? err.message : String(err)}` }));
+    return 1;
+  }
+  const ops = ctx.args.op
+    ? [ctx.args.op]
+    : (await listFilesInDir(GATES_DIR)).filter((f) => f.endsWith(".jsonl")).map((f) => f.slice(0, -".jsonl".length));
+  const reports: GateResumeReport[] = [];
+  for (const op of ops) reports.push(...(await resumeOpGates(op, undefined, { dryRun: ctx.args.dryRun === true })));
+  if (ctx.args.json) console.log(JSON.stringify({ reports }, null, 2));
+  else {
+    for (const r of reports.filter((r) => r.status !== "not-approved")) printReport(r);
+    const waiting = reports.filter((r) => r.status === "not-approved").length;
+    console.error(formatInfo(`${reports.filter((r) => r.status === "resumed").length} resumed, ${waiting} still waiting for an approval.`));
+  }
+  return reports.some((r) => r.status === "failed" || r.status === "no-token") ? 1 : 0;
+}

package/src/cli/handlers/operator.ts

@@ -911,6 +911,12 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
   });
   if (!outcome.ok) return 1;
 
+  // #3683: start the CI job that waits at this gate again.
+  if (ctx.args.resumeRun || ctx.args.resume !== undefined) {
+    const { resumeAfterApproval } = await import("./gate-resume");
+    return resumeAfterApproval(opName, gate, outcome.record.environment, outcome.pushed);
+  }
+
   console.error(formatInfo(
     `This records the resolution as a fact; it does not itself re-run anything. ` +
       (opName === FAN_OUT_GATE_OP
@@ -988,7 +994,7 @@ export interface GateApprovalOptions {
 }
 
 export type GateApprovalOutcome =
-  | { ok: true; record: GateResolutionRecord }
+  | { ok: true; record: GateResolutionRecord; pushed: boolean }
   | { ok: false };
 
 /**
@@ -1313,7 +1319,7 @@ export async function recordGateApproval(
       console.error(formatInfo(line));
     }
   }
-  return { ok: true, record };
+  return { ok: true, record, pushed };
 }
 
 /**