@intentius/chant 0.124.13 → 0.124.15

package/dist/op/emulator-freshness.js

@@ -0,0 +1,80 @@
+/**
+ * How far behind an emulator's pinned image is (#1345, generalizing #808 T2).
+ *
+ * This began as `lexicons/fly/src/emulator-freshness.ts`, checking fly's two
+ * pins against their GitHub releases. The other three emulators — Floci for aws,
+ * floci-az, floci-gcp — ran `:latest`, so there was nothing to be behind and
+ * nothing to check: an image could change underneath a passing local test suite
+ * with no record in the repo of what moved.
+ *
+ * With the pin and its upstream declared on {@link EmulatorSpec}, the check
+ * covers every emulator any lexicon ships, and a new one is included by
+ * declaring `upstream` rather than by editing a list here.
+ *
+ * Advisory, never gating. Per the bump policy (#808) a pin moves when a
+ * consuming test needs the newer emulator, not because a release happened.
+ */
+/** The version tag of an image ref (`ghcr.io/x/mudflaps:0.3.1` → `0.3.1`). */
+export function parseVersion(image) {
+    const lastColon = image.lastIndexOf(":");
+    const lastSlash = image.lastIndexOf("/");
+    // A registry port (`localhost:5000/x`) is not a tag.
+    if (lastColon < 0 || lastColon < lastSlash)
+        return "";
+    return image.slice(lastColon + 1).replace(/^v/, "");
+}
+function toParts(version) {
+    return version.replace(/^v/, "").split(".").map((n) => parseInt(n, 10) || 0);
+}
+/** Compare pinned against latest as dotted numeric versions. */
+export function compare(name, pinned, latest) {
+    const p = toParts(pinned);
+    const l = toParts(latest);
+    let behind = false;
+    for (let i = 0; i < Math.max(p.length, l.length); i++) {
+        const a = p[i] ?? 0;
+        const b = l[i] ?? 0;
+        if (b > a) {
+            behind = true;
+            break;
+        }
+        if (b < a)
+            break;
+    }
+    return { name, pinned: pinned.replace(/^v/, ""), latest: latest.replace(/^v/, ""), behind };
+}
+/** The latest release tag for a repo, via the GitHub REST API. */
+export async function latestRelease(repo, fetchImpl = fetch) {
+    const headers = { Accept: "application/vnd.github+json" };
+    if (process.env.GITHUB_TOKEN)
+        headers.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+    const res = await fetchImpl(`https://api.github.com/repos/${repo}/releases/latest`, { headers });
+    if (!res.ok)
+        throw new Error(`releases/latest ${repo}: HTTP ${res.status}`);
+    const body = (await res.json());
+    if (!body.tag_name)
+        throw new Error(`releases/latest ${repo}: no tag_name`);
+    return body.tag_name;
+}
+/**
+ * Check every spec that declares an upstream. A spec without one is skipped
+ * rather than reported — an emulator built from a local image has no release
+ * feed to be behind.
+ */
+export async function checkFreshness(specs, fetchImpl = fetch) {
+    const pinned = specs.filter((s) => s.upstream?.repo && parseVersion(s.image));
+    return Promise.all(pinned.map(async (s) => compare(s.name, parseVersion(s.image), await latestRelease(s.upstream.repo, fetchImpl))));
+}
+/** One-line human summary of a result. */
+export function formatResult(r) {
+    return r.behind
+        ? `⚠ ${r.name}: pinned ${r.pinned}, latest ${r.latest} — behind`
+        : `✓ ${r.name}: pinned ${r.pinned} is current (latest ${r.latest})`;
+}
+/** Emulator images that carry no version tag — `:latest` or none at all. */
+export function unpinned(specs) {
+    return specs.filter((s) => {
+        const version = parseVersion(s.image);
+        return version === "" || version === "latest";
+    });
+}

package/dist/op/emulator-lifecycle.js

@@ -0,0 +1,269 @@
+import { exec, execFile } from "node:child_process";
+import { connect } from "node:net";
+import { promisify } from "node:util";
+import { sleep } from "./activity-runtime.js";
+const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
+/**
+ * True when something accepts TCP connections on 127.0.0.1:`port` (#3673).
+ * `up` asks before `docker run`: a native server there would take every
+ * `localhost` connection meant for the emulator.
+ */
+export function hostPortInUse(port, timeoutMs = 1000) {
+    return new Promise((resolve) => {
+        const socket = connect({ host: "127.0.0.1", port });
+        const done = (inUse) => {
+            socket.destroy();
+            resolve(inUse);
+        };
+        socket.setTimeout(timeoutMs, () => done(false));
+        socket.once("connect", () => done(true));
+        socket.once("error", () => done(false));
+    });
+}
+/**
+ * Parse `docker port <name> <port>/tcp` output (`0.0.0.0:5432`, `[::]:5432`,
+ * one per line). Lines that do not parse are dropped.
+ */
+export function parsePublishedAddresses(stdout) {
+    const out = [];
+    for (const line of stdout.split("\n")) {
+        const match = /^\s*(?:\[([^\]]+)\]|([^\s:]+)):(\d+)\s*$/.exec(line);
+        if (match)
+            out.push({ ip: (match[1] ?? match[2]), port: Number(match[3]) });
+    }
+    return out;
+}
+/**
+ * The hosts a client on this machine dials to reach a published address,
+ * `localhost` first: a wildcard bind (`0.0.0.0`, `::`) answers on the
+ * loopback of its family, and a specific IP only on itself.
+ */
+export function clientHosts(addresses) {
+    const seen = new Set();
+    const hosts = [];
+    const add = (host, port) => {
+        const key = `${host}:${port}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        hosts.push({ host, port });
+    };
+    for (const { ip, port } of addresses) {
+        if (ip === "0.0.0.0" || ip === "127.0.0.1")
+            add("localhost", port);
+    }
+    for (const { ip, port } of addresses) {
+        if (ip === "::" || ip === "::1")
+            add("[::1]", port);
+        else if (ip !== "0.0.0.0" && ip !== "127.0.0.1")
+            add(ip.includes(":") ? `[${ip}]` : ip, port);
+    }
+    return hosts;
+}
+/** `endpoint` with its host replaced by `host` (`localhost` stays as written). */
+export function endpointOnHost(endpoint, host) {
+    if (host === "localhost")
+        return endpoint;
+    const url = new URL(endpoint);
+    url.hostname = host;
+    return url.toString().replace(/\/$/, endpoint.endsWith("/") ? "/" : "");
+}
+/**
+ * Pick the endpoint of a reused container that reaches it (the identity read
+ * inside the container matches the one read through the endpoint), trying
+ * {@link clientHosts} in order. `notes` says when `localhost` reaches another
+ * server and a different address had to be used; `error` says when none of
+ * them reaches the emulator.
+ */
+export async function pickReachableEndpoint(opts) {
+    const { name, hosts, identity, inside } = opts;
+    const misses = [];
+    for (const { host, port } of hosts) {
+        const ep = endpointOnHost(opts.endpoint(port), host);
+        try {
+            const answered = await identity.probe(ep);
+            if (answered.id.trim() === inside) {
+                const notes = misses.length
+                    ? [`emulator "${name}": ${misses.join("; ")}. The emulator answers on ${ep}; use that address.`]
+                    : [];
+                return { endpoint: ep, notes };
+            }
+            misses.push(`${host}:${port} reaches another ${identity.server} (${answered.label}), not the emulator`);
+        }
+        catch (err) {
+            const why = err instanceof Error ? err.message : String(err);
+            misses.push(`${host}:${port} does not answer as the emulator (${why})`);
+        }
+    }
+    const tried = misses.length ? `: ${misses.join("; ")}` : "";
+    return { error: `emulator "${name}" runs, but no address it publishes reaches it${tried}. ${opts.hint}` };
+}
+/** Every emulator a plugin declares, normalized to a list. */
+export function emulatorsOf(declaration) {
+    if (!declaration)
+        return [];
+    return Array.isArray(declaration) ? declaration : [declaration];
+}
+/** Sentinel that cannot collide with a real endpoint or a credential value. */
+const ENDPOINT_PROBE = "chant-endpoint-probe://0";
+/**
+ * The env vars whose value *is* the endpoint, as opposed to the credentials and
+ * region an emulator also needs (#1345).
+ *
+ * Derived by asking `env()` for a sentinel and keeping the keys that carry it,
+ * so a lexicon states the mapping once in the place it already states it. The
+ * alternative — `LEXICON_ENDPOINT_ENV_VAR`, a hand-maintained map in core — held
+ * two of the four lexicons that have one, and its module doc asserted azure had
+ * none while `describe-resources.ts` read `AZURE_ENDPOINT_URL` on every call.
+ */
+export function endpointEnvVars(capability) {
+    return Object.entries(capability.env(ENDPOINT_PROBE))
+        .filter(([, value]) => value === ENDPOINT_PROBE)
+        .map(([key]) => key);
+}
+/**
+ * Build a Docker-lifecycle for a local emulator: an idempotent `up` (reuse a
+ * running container, else `docker run`, then poll health until ready), a `down`
+ * (`docker rm -f`), and the pure command builders each per-cloud wrapper exposes
+ * for testing. Removes the near-duplication across the per-lexicon `floci*.ts`
+ * wrappers — a new cloud is a spec, not a copy.
+ */
+export function emulatorLifecycle(spec) {
+    const ready = spec.ready ?? (() => true);
+    if (spec.healthPath === undefined && !spec.readyCommand?.length) {
+        throw new Error(`emulator "${spec.name}" declares neither a healthPath nor a readyCommand, so nothing can tell when it is ready`);
+    }
+    const runCommand = (args = {}) => {
+        const name = args.name ?? spec.name;
+        const port = args.port ?? spec.containerPort;
+        const image = args.image ?? spec.image;
+        return [
+            "docker", "run", "-d", "--rm", "--name", name, "-p", `${port}:${spec.containerPort}`,
+            ...(spec.runArgs ?? []), ...(args.extraArgs ?? []), image,
+        ].join(" ");
+    };
+    const existsCommand = (name) => `docker ps -q -f name=${name}`;
+    const rmCommand = (name) => `docker rm -f ${name}`;
+    const healthUrl = (port) => `http://localhost:${port}${spec.healthPath ?? ""}`;
+    const endpoint = (port) => (spec.endpoint ? spec.endpoint(port) : `http://localhost:${port}`);
+    const readyExecCommand = (name) => spec.readyCommand?.length ? ["docker", "exec", name, ...spec.readyCommand].join(" ") : undefined;
+    /** One readiness probe: the in-container command when declared, else the HTTP health path. */
+    async function probe(name, port, signal, host = "localhost") {
+        const command = readyExecCommand(name);
+        if (command) {
+            try {
+                await execAsync(command, { signal });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        try {
+            const res = await fetch(endpointOnHost(healthUrl(port), host), { signal });
+            return res.ok && ready(await res.text());
+        }
+        catch {
+            // Not up yet (connection refused / non-2xx) — retry.
+            return false;
+        }
+    }
+    async function up(args = {}, signal) {
+        const name = args.name ?? spec.name;
+        const port = args.port ?? spec.containerPort;
+        const timeoutMs = args.timeoutMs ?? 60000;
+        const intervalMs = args.intervalMs ?? 2000;
+        let running = false;
+        try {
+            const { stdout } = await execAsync(existsCommand(name), { signal });
+            running = Boolean(stdout.trim());
+        }
+        catch {
+            // `docker ps` failed — assume not running and try to start it.
+        }
+        // A reused container publishes what it was started with, which need not
+        // be `port` on localhost: read it from Docker rather than assume it.
+        let hosts = [{ host: "localhost", port }];
+        if (running) {
+            // Progress → stderr, so a `--json` consumer (chant emulator, behold) reads
+            // clean JSON on stdout. runOp/Op activities capture both streams regardless.
+            console.error(`emulator container "${name}" already running — reusing`);
+            let published = [];
+            try {
+                const { stdout } = await execFileAsync("docker", ["port", name, `${spec.containerPort}/tcp`], { signal });
+                published = parsePublishedAddresses(stdout);
+            }
+            catch {
+                // `docker port` fails when nothing is published.
+            }
+            if (published.length === 0) {
+                throw new Error(`emulator "${name}" runs, but publishes no host port for ${spec.containerPort}, so nothing on this machine reaches it. ` +
+                    `Run \`chant emulator down\`, then \`chant emulator up\`.`);
+            }
+            hosts = clientHosts(published);
+            if (args.port !== undefined && !hosts.some((h) => h.port === args.port)) {
+                console.error(`emulator "${name}" was started on host port ${hosts[0].port}, not ${args.port}; reusing it there. ` +
+                    `Run \`chant emulator down\` first to move it.`);
+            }
+        }
+        else {
+            if (await hostPortInUse(port)) {
+                throw new Error(`emulator "${name}": 127.0.0.1:${port} is already held by another process, so localhost:${port} would not reach the emulator. ` +
+                    `Stop that process, or publish the emulator on another port (chant emulator up --port ${spec.containerPort}=<free port>).`);
+            }
+            await execAsync(runCommand({ ...args, name, port }), { signal });
+        }
+        const deadline = Date.now() + timeoutMs;
+        let ok = false;
+        while (Date.now() < deadline) {
+            if (signal?.aborted)
+                throw new Error(`emulator "${name}" wait aborted`);
+            for (const h of hosts) {
+                if (await probe(name, h.port, signal, h.host)) {
+                    ok = true;
+                    break;
+                }
+            }
+            if (ok)
+                break;
+            await sleep(intervalMs, signal);
+        }
+        if (!ok) {
+            throw new Error(`emulator "${name}" did not become ready within ${timeoutMs}ms`);
+        }
+        let ep = endpointOnHost(endpoint(hosts[0].port), hosts[0].host);
+        if (running && spec.identity) {
+            let inside;
+            try {
+                inside = (await execFileAsync("docker", ["exec", name, ...spec.identity.command], { signal })).stdout.trim();
+            }
+            catch {
+                // The container cannot answer for itself; nothing to compare against.
+            }
+            if (inside) {
+                const picked = await pickReachableEndpoint({
+                    name, hosts, endpoint, identity: spec.identity, inside,
+                    hint: `Stop the other server, or run \`chant emulator down\`, then \`chant emulator up --port ${spec.containerPort}=<free port>\`.`,
+                });
+                if ("error" in picked)
+                    throw new Error(picked.error);
+                for (const note of picked.notes)
+                    console.error(note);
+                ep = picked.endpoint;
+            }
+        }
+        console.error(`emulator "${name}" ready on ${ep}`);
+        return { endpoint: ep };
+    }
+    async function down(args = {}, signal) {
+        const name = args.name ?? spec.name;
+        try {
+            await execAsync(rmCommand(name), { signal });
+        }
+        catch {
+            // Already removed (`--rm` on exit, or never started) — treat as success.
+        }
+    }
+    return { runCommand, existsCommand, rmCommand, healthUrl, readyExecCommand, endpoint, up, down };
+}

package/dist/op/factory.js

@@ -0,0 +1,83 @@
+/**
+ * The factory reference Op (#3406, ws-087): the factory's rules declared in
+ * core, and an orchestrator's execution plugged in through hooks.
+ *
+ * ```ts
+ * // ops/factory.op.ts
+ * export default factoryOp({
+ *   builder: "node box/ops/factory/builder.mjs",
+ * });
+ * ```
+ *
+ * One run is one build of one work item, under that item's lease, in a
+ * worktree on `chant/work/<item>`:
+ *
+ *   Pick        factoryPick: the buildable items, in order; the lease claims the first nobody holds
+ *   Ask         factoryAsk: the tier (the item's own, or the slice-tier point) and, for an ask, the
+ *               understand point; an open question stops the run waiting
+ *   Build       factoryBuild: the `builder` hook, unless understand said not to build
+ *   Check       factoryCheck: the `check` hook, or the box's `factory.check`, with its evidence
+ *   Record      factoryRecord: done, dropped, redraft, ask or not_done, which the lease's release
+ *               takes; a not_done attempt is kept at refs/chant/kept/<item>/<token> by the run
+ *
+ * The hooks are commands, run with no shell in the worktree:
+ *
+ * - `builder` (required): how a builder runs, such as Claude Code in the box
+ *   or a `fountainRun` wrapper. It gets FACTORY_ITEM, FACTORY_TIER,
+ *   FACTORY_TOKEN, FACTORY_HOLDER, FACTORY_WORKTREE and FACTORY_CONTEXT, edits
+ *   the worktree, and exits 0 when it finished. It may print a last JSON line
+ *   `{ "reverted": [paths] }` when its guard put changes back.
+ * - `context` (optional): passed to the builder as FACTORY_CONTEXT, the prompt
+ *   and context bundle the orchestrator assembles.
+ * - `check` (optional): the verdict command; the box block's `factory.check`
+ *   when left out. An infra profile names a plan or `chant lint` here.
+ *
+ * Publishing a done item is the box's publisher (ws-088), run later by a
+ * person or a surface with `chant workspace box publish`; it is not a step.
+ */
+import { Op, phase, activity, shell } from "./builders.js";
+import { stepOutput } from "./step-output-ref.js";
+import { workLeaseOutput } from "./work-lease-run.js";
+/** The Op's configuration, for a steward that lists it or a test that runs it. */
+export function factoryOpConfig(options) {
+    if (!options || typeof options.builder !== "string" || options.builder.trim() === "") {
+        throw new Error("factoryOp needs a builder: the command that runs a builder in the run's worktree");
+    }
+    const lease = workLeaseOutput();
+    const kind = options.kind !== undefined ? { kind: options.kind } : {};
+    const at = options.cwd !== undefined ? { cwd: options.cwd } : {};
+    return {
+        name: options.name ?? "factory",
+        overview: "Build the next buildable work item under its lease: pick, ask, build, check and record, by the factory's rules (#3406, ws-087)",
+        workLease: {
+            item: stepOutput("pick", "candidates"),
+            outcome: stepOutput("record", "outcome"),
+            ...kind,
+            ...(options.ttl !== undefined ? { ttl: options.ttl } : {}),
+        },
+        changesCheckout: true,
+        ...(options.schedule ? { schedule: options.schedule } : {}),
+        phases: [
+            ...(options.prepare !== undefined ? [phase("Prepare", [shell(options.prepare, { ...(options.cwd !== undefined ? { cwd: options.cwd } : {}), id: "prepare" })])] : []),
+            phase("Pick", [activity("factoryPick", { ...kind, ...at }, { profile: "fastIdempotent", id: "pick" })]),
+            phase("Ask", [activity("factoryAsk", { lease, ...kind, ...at, ...(options.backends ? { backends: options.backends } : {}) }, { profile: "fastIdempotent", id: "ask" })]),
+            phase("Build", [
+                activity("factoryBuild", { lease, ...at, ask: stepOutput("ask"), builder: options.builder, ...(options.context !== undefined ? { context: options.context } : {}) }, { profile: "atMostOnce", id: "build", timeout: options.buildTimeout ?? "2h" }),
+            ]),
+            phase("Check", [activity("factoryCheck", { lease, ...at, build: stepOutput("build"), ...(options.check !== undefined ? { check: options.check } : {}) }, { profile: "atMostOnce", id: "check" })]),
+            phase("Record", [activity("factoryRecord", { lease, ...at, ask: stepOutput("ask"), build: stepOutput("build"), check: stepOutput("check"), ...(options.after !== undefined ? { after: options.after } : {}) }, { profile: "atMostOnce", id: "record" })]),
+        ],
+    };
+}
+/** The factory reference Op, as an `*.op.ts` file exports it. */
+export function factoryOp(options) {
+    return Op(factoryOpConfig(options));
+}
+/**
+ * The steward's ready step for the factory Op (#382): the keys of the work buildable now, for
+ * `declareSteward({ beside: [{ op: factory, ready: factoryReady({ cwd }) }] })`. `also` names a
+ * command printing a JSON list of more keys, for work the pick can't see yet.
+ */
+export function factoryReady(options = {}) {
+    return activity("factoryReady", { ...options }, { profile: "fastIdempotent" });
+}

package/dist/op/gate-approval.js

@@ -0,0 +1,172 @@
+/**
+ * Gate approval policy as data (#2508).
+ *
+ * A gate used to pass on one recorded approval. This module lets a gate say
+ * more than that, as data that survives into the build output:
+ *
+ * - `quorum`: how many distinct human approvers the gate needs, and
+ *   optionally which roles count toward it.
+ * - `policy`: a policy set a lexicon rendered (the cedar lexicon's
+ *   `gatePolicy()`), evaluated for each approval as a `PassGate` request.
+ * - `mode`: `"log-only"` records the policy's decision next to the approval
+ *   and lets only the quorum bind. `"enforce"` lets a permit pass the gate on
+ *   its own, which is how an agent principal passes a low-risk plan.
+ * - `context`: plan attributes handed to the policy (risk labels, changed
+ *   paths), resolved at run time like a gate's `plan`. A gate whose `plan`
+ *   names a step that returned a change set also gets `context.plan`, that
+ *   change set's summary (#3182, `./gate-plan-context.ts`).
+ *
+ * Core does not know Cedar. A {@link GatePolicyRef} names the lexicon that
+ * made it, and {@link loadGatePolicyEvaluator} imports that lexicon's
+ * `gate-policy` module by the same `@intentius/chant-lexicon-<name>/...`
+ * convention the activity registry uses (`./activity-registry.ts`).
+ *
+ * The policy is evaluated when an approval is recorded (`chant approve`),
+ * because that is the moment the approver is known. The decision is written
+ * on the resolution with the policy's version, and a run counts a recorded
+ * permit only while the gate still declares that same version. Editing the
+ * policy invalidates every permit recorded under the old one, the way a new
+ * plan invalidates every approval recorded for the old plan (#2300). The
+ * decision also records the digest of the context it was asked about, and a
+ * permit counts only while the run resolves that same context (#3774).
+ *
+ * The trust boundary is unchanged from `../lifecycle/gate-ledger.ts`: a
+ * resolution is a local fact, not a signed one, and roles on it are what the
+ * approver claimed.
+ */
+import { createHash } from "node:crypto";
+import { lexiconModulePath, importLexiconPackage } from "../lexicon-module.js";
+import { isStepOutputRef } from "./step-output-ref.js";
+import { GATE_PLAN_CONTEXT_KEY } from "./gate-plan-context.js";
+export const GATE_APPROVAL_MODES = ["log-only", "enforce"];
+/** The version of a gate policy: `sha256:` and the hex digest of its text. A lexicon's helper stamps it, and OPS015 checks it still matches. */
+export function gatePolicyVersion(text) {
+    return `sha256:${createHash("sha256").update(text).digest("hex")}`;
+}
+/**
+ * The digest of a gate's resolved approval context (#3774): `sha256:` and the
+ * hex digest of its JSON with keys sorted at every level. No context and an
+ * empty one digest the same.
+ */
+export function gateContextDigest(context) {
+    return `sha256:${createHash("sha256").update(JSON.stringify(context ?? {}, sortedKeys)).digest("hex")}`;
+}
+function sortedKeys(_key, value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        return Object.fromEntries(Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+    }
+    return value;
+}
+export function isGatePolicyRef(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (v.kind === "gate-policy" &&
+        typeof v.lexicon === "string" && v.lexicon !== "" &&
+        typeof v.name === "string" && v.name !== "" &&
+        typeof v.version === "string" && v.version !== "" &&
+        typeof v.text === "string" && v.text.trim() !== "");
+}
+/**
+ * Everything wrong with an `approval` block, one line each. The `gate()`
+ * builder throws on the first; OPS015 reports all of them over the build
+ * output, where a block could have been written without the builder.
+ */
+export function gateApprovalProblems(approval) {
+    if (typeof approval !== "object" || approval === null || Array.isArray(approval)) {
+        return ["`approval` must be an object"];
+    }
+    const a = approval;
+    const problems = [];
+    if (a.quorum !== undefined) {
+        const q = a.quorum;
+        if (typeof q !== "object" || q === null) {
+            problems.push("`approval.quorum` must be an object");
+        }
+        else {
+            if (typeof q.count !== "number" || !Number.isInteger(q.count) || q.count < 1) {
+                problems.push("`approval.quorum.count` must be an integer of at least 1");
+            }
+            if (q.roles !== undefined) {
+                if (!Array.isArray(q.roles) || q.roles.length === 0 || q.roles.some((r) => typeof r !== "string" || r === "")) {
+                    problems.push("`approval.quorum.roles` must be a non-empty list of role names");
+                }
+            }
+        }
+    }
+    if (a.policy !== undefined) {
+        if (!isGatePolicyRef(a.policy)) {
+            problems.push("`approval.policy` does not resolve to a gate policy set. Build it with the lexicon's helper, " +
+                "for example `gatePolicy(\"ship\", policies)` from @intentius/chant-lexicon-cedar");
+        }
+        else if (a.policy.version !== gatePolicyVersion(a.policy.text)) {
+            problems.push(`\`approval.policy\` "${a.policy.name}" has a version that is not the digest of its text, ` +
+                "so a recorded decision could not be traced to the rule that made it");
+        }
+    }
+    if (a.mode !== undefined && !GATE_APPROVAL_MODES.includes(a.mode)) {
+        problems.push(`\`approval.mode\` must be one of ${GATE_APPROVAL_MODES.map((m) => `"${m}"`).join(", ")}`);
+    }
+    if (a.mode === "enforce" && a.policy === undefined) {
+        problems.push("`approval.mode: \"enforce\"` needs an `approval.policy` to enforce");
+    }
+    if (a.context !== undefined) {
+        if (typeof a.context !== "object" || a.context === null || Array.isArray(a.context)) {
+            problems.push("`approval.context` must be an object of plan attributes");
+        }
+        else if (a.policy === undefined) {
+            problems.push("`approval.context` is only read by a policy, and this gate declares none");
+        }
+        else {
+            for (const [key, value] of Object.entries(a.context)) {
+                if (key === GATE_PLAN_CONTEXT_KEY) {
+                    problems.push(`\`approval.context.${key}\` is reserved: the run fills it with the plan's change-set summary (#3182) ` +
+                        "when the gate's `plan` names the step that planned it");
+                    continue;
+                }
+                if (!isContextValue(value)) {
+                    problems.push(`\`approval.context.${key}\` must be a string, number, boolean, list of strings, or a step output reference`);
+                }
+            }
+        }
+    }
+    return problems;
+}
+function isContextValue(value) {
+    if (typeof value === "string" || typeof value === "boolean")
+        return true;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every((v) => typeof v === "string");
+    return isStepOutputRef(value);
+}
+/** Import `lexicon`'s evaluator. Throws a message that names the package when it is not installed or exports none. */
+export async function loadGatePolicyEvaluator(lexicon) {
+    // chant #2520 — a lexicon declared by module path exports its evaluator from that module.
+    const spec = lexiconModulePath(lexicon) ?? `@intentius/chant-lexicon-${lexicon}/gate-policy`;
+    let mod;
+    try {
+        mod = (await importLexiconPackage(spec));
+    }
+    catch (err) {
+        throw new Error(`the gate's policy is evaluated by ${spec}, which could not be loaded: ` +
+            (err instanceof Error ? err.message : String(err)));
+    }
+    if (typeof mod.evaluateGatePolicy !== "function") {
+        throw new Error(`${spec} exports no evaluateGatePolicy function`);
+    }
+    return mod;
+}
+/** The request a policy is asked about one approval. */
+export function gatePolicyRequest(input) {
+    return {
+        principal: { kind: input.approver.kind, name: input.resolvedBy, roles: input.approver.roles ?? [] },
+        action: "PassGate",
+        resource: { op: input.op, gate: input.gate },
+        context: {
+            ...(input.context ?? {}),
+            ...(input.planDigest !== undefined ? { planDigest: input.planDigest } : {}),
+        },
+    };
+}