@intentius/chant 0.124.13 → 0.124.14

package/dist/op/gate-review.js

@@ -0,0 +1,290 @@
+/**
+ * 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 { readFileSync } from "node:fs";
+import { gateSealRefusal } from "../workspace/trust/gate-seal.js";
+import { readTrustPolicy } from "../workspace/trust/policy.js";
+import { gitRevisionSource } from "../workspace/record-source.js";
+import { forgePrincipalOf, ForgeApiError } from "../pr-forge.js";
+export { GATE_APPROVAL_SOURCES } from "./op-waves.js";
+// ── sealed ────────────────────────────────────────────────────────────────
+/** The signers policy at `base`, read from the repository at `cwd`. */
+export function trustPolicyAt(cwd, base) {
+    return readTrustPolicy(gitRevisionSource(cwd, base), base);
+}
+/**
+ * The rule a `sealed` gate judges approvals by: a seal that verifies for the
+ * approver against `policy`, the signers at base, checked with node:crypto
+ * (#3785), so an apply job needs no ssh-keygen. With no signers file at
+ * base nothing verifies, so nothing passes the gate.
+ */
+export function sealedApprovalRule(gate, policy) {
+    return {
+        requirement: { gate, class: null },
+        refuses(approval) {
+            return gateSealRefusal(policy, approval);
+        },
+    };
+}
+/** Both rules at once: an approval counts only when neither refuses it. */
+export function bothRules(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    return { requirement: a.requirement, refuses: (r) => a.refuses(r) ?? b.refuses(r) };
+}
+// ── pr-review ─────────────────────────────────────────────────────────────
+// The record and its reader live apart, so a bundle can import them without git (#3865).
+export { HEAD_PLANS_DIR, headPlansPath } from "../lifecycle/wave-plans.js";
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const trimSlash = (s) => s.replace(/\/+$/, "");
+function client(base, headers, fetchImpl) {
+    return async (path) => {
+        const url = `${trimSlash(base)}${path}`;
+        const res = await fetchImpl(url, { method: "GET", headers });
+        const text = await res.text();
+        if (!res.ok)
+            throw new ForgeApiError("GET", url, res.status, text);
+        return text ? JSON.parse(text) : null;
+    };
+}
+const hostOf = (url, fallback) => {
+    try {
+        return url ? new URL(url).host.toLowerCase() : fallback;
+    }
+    catch {
+        return fallback;
+    }
+};
+/** GitHub or Forgejo, which share the pull request and review shapes. */
+function githubShapedReviews(kind, opts) {
+    const get = client(opts.apiBase, kind === "github"
+        ? { Authorization: `Bearer ${opts.token}`, Accept: "application/vnd.github+json" }
+        : { Authorization: `token ${opts.token}`, Accept: "application/json" }, opts.fetch ?? globalThis.fetch);
+    const repo = `/repos/${opts.repo}`;
+    const who = (login) => forgePrincipalOf(kind, opts.host, login);
+    const page = kind === "github" ? "per_page=100" : "limit=50";
+    async function prFor(sha) {
+        if (kind === "forgejo") {
+            try {
+                const pr = await get(`${repo}/commits/${sha}/pull`);
+                return isObject(pr) && typeof pr.number === "number" ? pr.number : null;
+            }
+            catch (err) {
+                if (err instanceof ForgeApiError && err.status === 404)
+                    return null;
+                throw err;
+            }
+        }
+        const prs = await get(`${repo}/commits/${sha}/pulls`);
+        if (!Array.isArray(prs))
+            return null;
+        const merged = prs.filter((p) => isObject(p) && p.merged_at);
+        const pick = (merged.find((p) => isObject(p) && p.merge_commit_sha === sha) ?? merged[0]);
+        return pick && typeof pick.number === "number" ? pick.number : null;
+    }
+    async function writer(login) {
+        const p = await get(`${repo}/collaborators/${encodeURIComponent(login)}/permission`);
+        return isObject(p) && ["admin", "maintain", "write", "owner"].includes(String(p.role_name ?? p.permission));
+    }
+    return {
+        kind,
+        async mergedReview(sha) {
+            const number = await prFor(sha);
+            if (number === null)
+                return null;
+            const pr = await get(`${repo}/pulls/${number}`);
+            if (!isObject(pr) || !isObject(pr.user) || !isObject(pr.head))
+                throw new Error(`pull request #${number} came back without its author or head`);
+            const authorLogin = String(pr.user.login);
+            const head = String(pr.head.sha);
+            const reviews = await get(`${repo}/pulls/${number}/reviews?${page}`);
+            // A reviewer's newest deciding review is their standing one.
+            const standing = new Map();
+            for (const r of Array.isArray(reviews) ? reviews : []) {
+                if (!isObject(r) || !isObject(r.user) || typeof r.state !== "string")
+                    continue;
+                const state = r.state.toUpperCase();
+                if (state === "COMMENTED" || state === "COMMENT" || state === "PENDING")
+                    continue;
+                standing.set(String(r.user.login), r);
+            }
+            const approvers = [];
+            const refused = [];
+            let changesRequested = false;
+            for (const [login, r] of standing) {
+                const state = r.dismissed === true ? "DISMISSED" : String(r.state).toUpperCase();
+                if (login.toLowerCase() === authorLogin.toLowerCase()) {
+                    if (state === "APPROVED")
+                        refused.push(`${who(login)} is the author, whose own review never counts`);
+                    continue;
+                }
+                const isWriter = kind === "forgejo" ? r.official === true : await writer(login);
+                if (state === "REQUEST_CHANGES" || state === "CHANGES_REQUESTED") {
+                    if (isWriter)
+                        changesRequested = true;
+                    refused.push(`${who(login)} requests changes`);
+                    continue;
+                }
+                if (state !== "APPROVED")
+                    continue;
+                if (!isWriter)
+                    refused.push(`${who(login)} approved without write access${kind === "forgejo" ? " (the review is not official)" : ""}`);
+                else if (r.commit_id !== head || r.stale === true)
+                    refused.push(`${who(login)} approved ${String(r.commit_id ?? "another commit").slice(0, 12)}, not the head ${head.slice(0, 12)}`);
+                else
+                    approvers.push(who(login));
+            }
+            return {
+                pr: number,
+                ...(typeof pr.html_url === "string" ? { url: pr.html_url } : {}),
+                author: who(authorLogin),
+                head,
+                approvers: changesRequested ? [] : approvers.sort(),
+                refused,
+            };
+        },
+    };
+}
+/** A GitHub reader of pull request reviews. The token needs `pull-requests: read`. */
+export function githubReviews(opts) {
+    return githubShapedReviews("github", opts);
+}
+/** A Forgejo (or Gitea) reader of pull request reviews. */
+export function forgejoReviews(opts) {
+    return githubShapedReviews("forgejo", opts);
+}
+/** A GitLab reader of merge request approvals. The token needs `read_api`. */
+export function gitlabReviews(opts) {
+    const get = client(opts.apiBase, { "PRIVATE-TOKEN": opts.token }, opts.fetch ?? globalThis.fetch);
+    const project = `/projects/${encodeURIComponent(decodeURIComponent(opts.repo))}`;
+    const who = (login) => forgePrincipalOf("gitlab", opts.host, login);
+    return {
+        kind: "gitlab",
+        async mergedReview(sha) {
+            const mrs = await get(`${project}/repository/commits/${sha}/merge_requests`);
+            const merged = Array.isArray(mrs)
+                ? mrs.find((m) => isObject(m) && m.state === "merged" && (m.merge_commit_sha === sha || m.squash_commit_sha === sha)) ??
+                    mrs.find((m) => isObject(m) && m.state === "merged")
+                : undefined;
+            if (!isObject(merged) || typeof merged.iid !== "number")
+                return null;
+            const iid = merged.iid;
+            const author = isObject(merged.author) ? String(merged.author.username) : "";
+            const head = String(merged.sha);
+            const settings = await get(`${project}/approvals`);
+            const resets = isObject(settings) && settings.reset_approvals_on_push === true;
+            const approvals = await get(`${project}/merge_requests/${iid}/approvals`);
+            const by = isObject(approvals) && Array.isArray(approvals.approved_by) ? approvals.approved_by : [];
+            const approvers = [];
+            const refused = [];
+            for (const a of by) {
+                const user = isObject(a) && isObject(a.user) ? a.user : undefined;
+                if (!user || typeof user.username !== "string")
+                    continue;
+                const login = user.username;
+                if (login.toLowerCase() === author.toLowerCase()) {
+                    refused.push(`${who(login)} is the author, whose own approval never counts`);
+                    continue;
+                }
+                if (!resets) {
+                    refused.push(`${who(login)}'s approval names no commit, and the project keeps approvals after a new push (turn on "Remove all approvals when commits are added")`);
+                    continue;
+                }
+                const member = await get(`${project}/members/all/${String(user.id)}`).catch((err) => {
+                    if (err instanceof ForgeApiError && err.status === 404)
+                        return null;
+                    throw err;
+                });
+                if (!isObject(member) || typeof member.access_level !== "number" || member.access_level < 30) {
+                    refused.push(`${who(login)} approved without the Developer role`);
+                    continue;
+                }
+                approvers.push(who(login));
+            }
+            return {
+                pr: iid,
+                ...(typeof merged.web_url === "string" ? { url: merged.web_url } : {}),
+                author: who(author),
+                head,
+                approvers: approvers.sort(),
+                refused,
+            };
+        },
+    };
+}
+/**
+ * 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 function reviewSourceFromEnv(env = process.env, fetchImpl) {
+    const f = fetchImpl ? { fetch: fetchImpl } : {};
+    if (env.GITLAB_CI === "true") {
+        const token = env.CHANT_FORGE_TOKEN ?? env.GITLAB_TOKEN;
+        if (!env.CI_API_V4_URL || !env.CI_PROJECT_ID || !token) {
+            throw new Error("a pr-review gate on GitLab needs CI_API_V4_URL, CI_PROJECT_ID and CHANT_FORGE_TOKEN (a token with read_api)");
+        }
+        return gitlabReviews({ apiBase: env.CI_API_V4_URL, repo: env.CI_PROJECT_ID, token, host: env.CI_SERVER_HOST ?? hostOf(env.CI_SERVER_URL, "gitlab.com"), ...f });
+    }
+    const token = env.CHANT_FORGE_TOKEN ?? env.GITHUB_TOKEN ?? env.GH_TOKEN;
+    if (!env.GITHUB_REPOSITORY || !token) {
+        throw new Error("a pr-review gate needs GITHUB_REPOSITORY and a token (GITHUB_TOKEN with pull-requests: read, or CHANT_FORGE_TOKEN)");
+    }
+    const forgejo = env.FORGEJO_ACTIONS === "true" || env.GITEA_ACTIONS === "true";
+    const host = hostOf(env.GITHUB_SERVER_URL, "github.com");
+    const opts = { apiBase: env.GITHUB_API_URL ?? (forgejo ? `${trimSlash(env.GITHUB_SERVER_URL ?? "")}/api/v1` : "https://api.github.com"), repo: env.GITHUB_REPOSITORY, token, host, ...f };
+    return forgejo ? forgejoReviews(opts) : githubReviews(opts);
+}
+/**
+ * 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 function pullRequestHeadFromEnv(env = process.env) {
+    if (env.GITLAB_CI === "true") {
+        if (!env.CI_MERGE_REQUEST_IID)
+            return undefined;
+        return env.CI_MERGE_REQUEST_SOURCE_BRANCH_SHA || env.CI_COMMIT_SHA || undefined;
+    }
+    if (!env.GITHUB_EVENT_PATH)
+        return undefined;
+    try {
+        const event = JSON.parse(readFileSync(env.GITHUB_EVENT_PATH, "utf-8"));
+        const sha = event.pull_request?.head?.sha;
+        return typeof sha === "string" && sha !== "" ? sha : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/op/gate-run-locator.js

@@ -0,0 +1,85 @@
+/**
+ * Where a CI job that waits at a gate runs, and what its forge needs to start
+ * it again (#3683). Read from the job's environment when a pending fact is
+ * recorded; `../gate-resume-run.ts` uses it to resume the job. It imports nothing
+ * at run time, so `@intentius/chant/point-decision` records it on the pending
+ * fact of a gate that asks a decision point too (#3835).
+ */
+const trimSlash = (s) => s.replace(/\/+$/, "");
+/**
+ * The locator of the CI job this process runs in, or undefined outside CI or
+ * when the environment lacks a part a resume needs. Forgejo Actions sets the
+ * `GITHUB_*` variables too, and is told apart by `FORGEJO_ACTIONS` or
+ * `GITEA_ACTIONS`.
+ */
+export function resolveGateRunLocator(env = process.env) {
+    if (env.GITLAB_CI === "true") {
+        if (!env.CI_API_V4_URL || !env.CI_PROJECT_ID || !env.CI_PIPELINE_ID || !env.CI_JOB_ID)
+            return undefined;
+        return {
+            forge: "gitlab",
+            api: trimSlash(env.CI_API_V4_URL),
+            repo: env.CI_PROJECT_ID,
+            run: env.CI_PIPELINE_ID,
+            job: env.CI_JOB_ID,
+            ...(env.CI_JOB_NAME ? { jobName: env.CI_JOB_NAME } : {}),
+            ...(env.CI_JOB_URL ? { url: env.CI_JOB_URL } : {}),
+        };
+    }
+    if (env.GITHUB_ACTIONS !== "true" || !env.GITHUB_REPOSITORY || !env.GITHUB_RUN_ID)
+        return undefined;
+    const forgejo = env.FORGEJO_ACTIONS === "true" || env.GITEA_ACTIONS === "true";
+    const server = env.GITHUB_SERVER_URL ? trimSlash(env.GITHUB_SERVER_URL) : undefined;
+    const url = server ? `${server}/${env.GITHUB_REPOSITORY}/actions/runs/${env.GITHUB_RUN_ID}` : undefined;
+    if (forgejo) {
+        const workflow = forgejoWorkflowFile(env);
+        const api = env.GITHUB_API_URL ?? (server ? `${server}/api/v1` : undefined);
+        if (!api || !workflow || !env.GITHUB_REF_NAME)
+            return undefined;
+        return {
+            forge: "forgejo",
+            api: trimSlash(api),
+            repo: env.GITHUB_REPOSITORY,
+            run: env.GITHUB_RUN_ID,
+            workflow,
+            ref: env.GITHUB_REF_NAME,
+            ...(url ? { url } : {}),
+        };
+    }
+    const attempt = Number(env.GITHUB_RUN_ATTEMPT);
+    return {
+        forge: "github",
+        api: trimSlash(env.GITHUB_API_URL ?? "https://api.github.com"),
+        repo: env.GITHUB_REPOSITORY,
+        run: env.GITHUB_RUN_ID,
+        ...(Number.isInteger(attempt) && attempt > 0 ? { attempt } : {}),
+        ...(url ? { url } : {}),
+    };
+}
+/**
+ * The workflow file a Forgejo run came from, by its base name. Forgejo names
+ * a workflow by its file (`GITHUB_WORKFLOW`, `deploy.yml`); `GITHUB_WORKFLOW_REF`
+ * (`owner/repo/.forgejo/workflows/deploy.yml@refs/heads/main`) says it too.
+ */
+function forgejoWorkflowFile(env) {
+    const fromRef = env.GITHUB_WORKFLOW_REF?.split("@")[0]?.split("/").pop();
+    if (fromRef && /\.ya?ml$/.test(fromRef))
+        return fromRef;
+    const name = env.GITHUB_WORKFLOW;
+    return name && /\.ya?ml$/.test(name) ? name.split("/").pop() : undefined;
+}
+/** Whether `value` is a {@link GateRunLocator} a resume can use. */
+export function isGateRunLocator(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const v = value;
+    if (typeof v.api !== "string" || typeof v.repo !== "string" || typeof v.run !== "string")
+        return false;
+    if (v.forge === "github")
+        return true;
+    if (v.forge === "gitlab")
+        return typeof v.job === "string";
+    if (v.forge === "forgejo")
+        return typeof v.workflow === "string" && typeof v.ref === "string";
+    return false;
+}

package/dist/op/gate-summary.js

@@ -0,0 +1,100 @@
+/**
+ * The pending-gate block a CI run leaves where people actually look (#2243).
+ *
+ * A gated run already prints the gate, the approve command and the expiry to
+ * stderr (`./local-output.ts`'s `renderHuman`). In CI that lands in a log
+ * nobody opens unless the run is red, which is exactly the run this stops
+ * being red. GitHub Actions, Forgejo Actions and Gitea all give a step a
+ * markdown scratchpad through `GITHUB_STEP_SUMMARY`, rendered at the top of
+ * the run page; anything else that sets the variable gets the same block.
+ *
+ * GitLab CI sets no such variable and has no step summary at all: a job's
+ * surfaces are its log and its artifacts (#2256). So `CHANT_GATE_SUMMARY`
+ * names a second path, which the generated GitLab job sets to a file it also
+ * declares under `artifacts:`. Same block, same rule, one more variable.
+ *
+ * That is the whole forge coupling: two environment variables, appended to
+ * whichever is set, and nothing at all when neither is. No API call, no
+ * token, no flag to turn it on.
+ */
+import { appendFileSync } from "node:fs";
+import { gateLedgerPath } from "../lifecycle/gate-ledger.js";
+import { resolveMemberLedger } from "../lifecycle/member-ledger.js";
+import { approveCommand } from "./gate.js";
+import { LIFECYCLE_LOCAL_NOTE, isLifecycleLocalNote } from "../lifecycle/local-note.js";
+/**
+ * `{ ledgerPrefix }` for the project at `cwd` when it is a workspace member,
+ * else `{}`. A summary is a report, so a declaration that cannot be read
+ * leaves the path as it is rather than failing the report.
+ */
+export async function summaryLedgerPrefix(cwd = process.cwd()) {
+    try {
+        const { prefix } = await resolveMemberLedger(cwd);
+        return prefix ? { ledgerPrefix: prefix } : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * The markdown block itself. Pure, so a test reads what CI would render
+ * without touching a file: op, gate, the exact `chant approve` line, and the
+ * ledger path the pending fact was appended to.
+ */
+export function gatedRunSummaryMarkdown(summary) {
+    const lines = [
+        `### Waiting on gate \`${summary.gate}\``,
+        "",
+        `Op \`${summary.op}\` reached a gate nobody has approved, recorded the pending fact, and stopped. Nothing failed.`,
+        "",
+    ];
+    if (summary.description) {
+        lines.push(summary.description, "");
+    }
+    if (summary.planDigest) {
+        lines.push(`This approves one plan, \`${summary.planDigest}\`, and not the next run (#2300). ` +
+            "Change the configuration after approving and the next run refuses rather than applying.", "");
+    }
+    lines.push("Approve it, then re-run this workflow:", "", "```", `${approveCommand(summary.op, summary.gate, summary.environment, undefined, summary.sealed === true)} --approver <you>`, "```", "", `Ledger: \`${gateLedgerPath(summary.op, summary.ledgerPrefix)}\` on the \`chant/lifecycle\` branch.`);
+    if (summary.expiresAt)
+        lines.push(`Expires: ${summary.expiresAt}`);
+    if (summary.url)
+        lines.push(`Approve at: ${summary.url}`);
+    if (summary.pushed === false && isLifecycleLocalNote(summary.pushWarning)) {
+        lines.push("", `The pending fact was ${LIFECYCLE_LOCAL_NOTE}.`);
+    }
+    else if (summary.pushed === false) {
+        lines.push("", `**This pending fact was not pushed to the remote** (${summary.pushWarning ?? "no reason given"}). ` +
+            "It exists only in this job's checkout. An operator working from a clone of the remote cannot " +
+            "see it to approve it until it reaches \`chant/lifecycle\` there.");
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Append {@link gatedRunSummaryMarkdown} to the file `GITHUB_STEP_SUMMARY`
+ * names, or, where the forge sets no such variable, the one
+ * `CHANT_GATE_SUMMARY` names (#2256) — when it is set and the file can be
+ * written.
+ *
+ * The forge's own variable wins where both are set: a step summary is
+ * rendered on the run page, an artifact has to be downloaded, and writing
+ * both would put the same block in two places on a forge that already shows
+ * one of them.
+ *
+ * Returns the path written, or `undefined` when there was nothing to write to.
+ * A write that fails is swallowed: a run that already decided its outcome must
+ * not turn into a different one because a CI scratchpad was read-only.
+ */
+export function writeGatedRunSummary(summary, env = process.env) {
+    const path = env.GITHUB_STEP_SUMMARY || env.CHANT_GATE_SUMMARY;
+    if (!path)
+        return undefined;
+    try {
+        appendFileSync(path, gatedRunSummaryMarkdown(summary));
+        return path;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/op/gate-wait.js

@@ -0,0 +1,56 @@
+/**
+ * A step whose command stopped at a gate of its own (#2779).
+ *
+ * Some chant commands decide a gate themselves rather than through a `gate`
+ * step: `chant workspace upgrade` stages its patch, records
+ * `workspace-upgrade` / `<scope>` pending on the gate ledger, and exits 3.
+ * An Op step that runs such a command stops its run at that gate by throwing
+ * {@link GateWait} with the pending fact the command recorded. The executor
+ * ends the run there with status `gated`, as it does at a pending `gate`
+ * step: no later step runs, no `onFailure` phase runs, a work lease is
+ * released `gated`, and the run ledger names the gate, with the op it is
+ * recorded under when that isn't the run's own.
+ *
+ * Nothing waits. After `chant approve <op> <gate>` the next run runs the
+ * command again, the command finds the approval, and the step goes on. A
+ * local steward re-runs its own gated run on the first round after the
+ * approval (`./operator.ts`).
+ *
+ * `shell()` throws it for an exit code named in `gatedExit`
+ * (`./activities/shell.ts`); an activity of a lexicon can throw it too.
+ */
+var _a;
+/** The marker {@link GateWait} carries, so a copy of core linked twice still recognises it. */
+const GATE_WAIT = Symbol.for("chant.op.GateWait");
+/**
+ * Thrown by an activity whose command stopped at a gate. Not a failure: the
+ * executor ends the run with status `gated` (see the module doc).
+ */
+export class GateWait extends Error {
+    constructor(pending) {
+        super(`stopped at gate ${pending.op} / ${pending.gate}: approve it with \`chant approve ${pending.op} ${pending.gate}\` and run again`);
+        this.pending = pending;
+        this[_a] = true;
+        this.name = "GateWait";
+    }
+}
+_a = GATE_WAIT;
+/** Is this a {@link GateWait}? Duck-typed on the shared symbol. */
+export function isGateWait(err) {
+    return !!err && typeof err === "object" && err[GATE_WAIT] === true && "pending" in err;
+}
+/**
+ * `value` as a pending gate fact, or undefined when it isn't one: it needs
+ * the `op`, `gate`, `timestamp` and `expiresAt` every pending line on the
+ * gate ledger carries.
+ */
+export function asPendingGate(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const v = value;
+    for (const key of ["op", "gate", "timestamp", "expiresAt"]) {
+        if (typeof v[key] !== "string" || v[key] === "")
+            return undefined;
+    }
+    return { ...v, version: 1, kind: "pending" };
+}