@intentius/chant 0.124.13 → 0.124.14

package/dist/fold-provenance.js

@@ -0,0 +1,414 @@
+/**
+ * Fold provenance (#2161) — which composite parameter produced which emitted field.
+ *
+ * A composite is the one lossy thing chant emits. It takes a few typed
+ * arguments and expands to several resources, so a return leg that regenerates
+ * source from live produces flat typed resources and the composite is gone. The
+ * projection is not invertible from its output alone, which is the view-update
+ * problem landing on chant's record.
+ *
+ * chant can answer it where a general generator cannot, and for one reason: the
+ * evaluated subset is restricted on purpose. `discovery/fold-import.ts` already
+ * interprets an admissible factory body rather than calling it, so the
+ * expression each member property was WRITTEN as is in hand at build time. The
+ * same pass records where the field came from, in `discovery/param-deps.ts`'s
+ * {@link import("./discovery/param-deps.js").collectCompositeOrigins}.
+ *
+ * ## Four answers, and the fourth is a real one
+ *
+ * Every emitted path gets one of {@link FoldFieldOrigin}'s four kinds. Three of
+ * them are findings; `unknown` is the fourth, and it is a legal answer rather
+ * than a gap. A build that expanded a composite without interpreting its body
+ * (the run path, a factory outside the admissible subset, a sandboxed child
+ * whose provenance did not survive the wire) knows the field came from a
+ * composite and cannot say which parameter. Recording that is the whole point:
+ * an unknown must never fall through to `direct`, because `direct` licenses
+ * editing the field in the user's source and an unattributed composite field is
+ * exactly the case where that produces a flattened resource.
+ *
+ * `direct` is claimed only where the build has a provenance record AND that
+ * record says no composite expanded the entity. Absence of a record is
+ * `unknown`, never `direct`.
+ *
+ * ## Beside the output, never in it
+ *
+ * The record is build metadata, not declared configuration, and it must not
+ * reach the document an applier writes. It rides two channels, both outside the
+ * apply-bound document, and neither is a new mechanism:
+ *
+ *  - per entity, the non-enumerable symbol-keyed side channel `./provenance.ts`
+ *    already owns, invisible to every serializer and to every spread;
+ *  - per build, {@link import("./build.js").BuildResult.foldProvenance}, a sibling
+ *    of `buildParams` and `lexiconVersions`.
+ *
+ * Nothing is added to `SerializeContext`. That is the same posture
+ * `./effect-receipt.ts` takes at the same seam, one notch stricter: a receipt
+ * rides `SerializeContext.receipts` so a lexicon MAY render it outside
+ * `Resources`, whereas provenance has no rendering and is simply never handed
+ * to a serializer at all. `fold-provenance-exclusion.test.ts` drives a real
+ * build through a spy serializer and a mock applier to hold that line.
+ *
+ * ## The return leg
+ *
+ * {@link resolveDriftedField} is the consumer. #2160 has already ruled out the
+ * fields nobody declared, so a drifted field reaching it is one source actually
+ * declared, and the origin decides what may be proposed:
+ *
+ *  - a composite parameter: propose changing that parameter, naming the file,
+ *    the composite call and the parameter path. One line, composite intact.
+ *  - a literal the composite fixes: refuse by name. The choice is to
+ *    parameterize the field or stop using the composite there, and neither is
+ *    something chant may pick.
+ *  - a direct declaration: today's behaviour, unchanged.
+ *  - unknown: today's behaviour, and say that is what happened.
+ *
+ * Proposing is as far as this goes. Rewriting a parameter in the user's source
+ * is a source-edit problem (the generator half of `chant import` emits whole
+ * files and nothing maps a property path back to a location in a `.ts` file),
+ * so a proposal here is a described action: it names the file, the composite
+ * call and the parameter path, and performs no edit.
+ */
+import { isResourceDeclarable } from "./declarable.js";
+import { relative, isAbsolute } from "node:path";
+import { originOfPath, } from "./provenance.js";
+/** True for an ordinary `{}`, false for an array, a class instance, an `AttrRef`. */
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Every property path an entity's `props` emits, in `EntityProvenance.paths`'
+ * grammar: dotted names only, plain objects descended into, everything else
+ * attributed whole at its own path.
+ *
+ * Arrays are deliberately not indexed. An index-shaped key would not survive an
+ * element moving, and the recorder that produces origins cannot index either,
+ * so indexing here would manufacture paths nothing can ever attribute. The diff
+ * addresses array elements with `[#key]`/`[n]` and `originOfPath` resolves
+ * those against the dotted key that covers them, which is the join between the
+ * two grammars.
+ *
+ * An empty object is a value, and a leaf. An `undefined` value is not emitted
+ * and yields no path.
+ */
+export function emittedFieldPaths(props) {
+    const out = [];
+    const walk = (value, prefix) => {
+        if (value === undefined)
+            return;
+        if (isPlainObject(value)) {
+            const keys = Object.keys(value).sort();
+            if (keys.length === 0) {
+                if (prefix)
+                    out.push(prefix);
+                return;
+            }
+            for (const key of keys)
+                walk(value[key], prefix ? `${prefix}.${key}` : key);
+            return;
+        }
+        if (prefix)
+            out.push(prefix);
+    };
+    walk(props, "");
+    return out;
+}
+/**
+ * The four-way answer for one path, from the recorded {@link PathOrigin} and
+ * the entity's own provenance.
+ *
+ * `origin` is what {@link originOfPath} resolved for the path, so a coarse key
+ * recorded at an ancestor governs a leaf, exactly as it does everywhere else.
+ */
+export function classifyFieldOrigin(origin, provenance) {
+    if (!provenance)
+        return { kind: "unknown", reason: "no-provenance" };
+    const instance = provenance.compositeInstance;
+    const call = provenance.compositeCall;
+    switch (origin?.kind) {
+        case "composite-parameter":
+            return {
+                kind: "composite-parameter",
+                composite: origin.composite,
+                ...(instance ? { instance } : {}),
+                parameters: [...origin.parameters],
+                ...(call ? { call: { ...call } } : {}),
+                ...(origin.arguments ? { arguments: origin.arguments.map((a) => ({ ...a })) } : {}),
+            };
+        case "composite-literal":
+            return {
+                kind: "composite-literal",
+                composite: origin.composite,
+                ...(instance ? { instance } : {}),
+                ...(call ? { call: { ...call } } : {}),
+            };
+        case "composite":
+            // The coarse kind: a composite expanded this, and nothing said which
+            // parameter. Not a parameter, not a fixed literal, and above all not a
+            // direct declaration.
+            return { kind: "unknown", reason: "composite-not-interpreted" };
+        case "authored":
+            // chant#3608 — `authored` is the file's own root record, and it reaches
+            // a path only when nothing finer did. On an entity a composite wrote (a
+            // member destructured from a composite the fold invoked) that means the
+            // fold could not attribute the path, which is `unknown`, never `direct`.
+            return provenance.composite
+                ? { kind: "unknown", reason: "composite-not-interpreted" }
+                : { kind: "direct" };
+        case "host":
+            // INTENTIUS/typescript-as-data#248 — host code produced the value, so
+            // editing the declaration edits a call, not the value it returned.
+            return { kind: "unknown", reason: origin.reason };
+        case "build-param":
+            // A build parameter governs the expression the AUTHOR wrote in their own
+            // source, so the declaration is still theirs to edit.
+            return { kind: "direct" };
+        case undefined:
+            return provenance.composite
+                ? { kind: "unknown", reason: "composite-not-interpreted" }
+                : { kind: "direct" };
+    }
+}
+/** One entity's fold provenance, or `undefined` when it emits no properties at all. */
+export function foldProvenanceOfEntity(entity, provenance) {
+    if (!isResourceDeclarable(entity))
+        return undefined;
+    const paths = emittedFieldPaths(entity.props);
+    if (paths.length === 0)
+        return undefined;
+    const fields = {};
+    for (const path of paths) {
+        fields[path] = classifyFieldOrigin(originOfPath(provenance?.paths, path), provenance);
+    }
+    return {
+        ...(provenance?.sourceFile ? { sourceFile: provenance.sourceFile } : {}),
+        ...(provenance?.composite ? { composite: provenance.composite } : {}),
+        ...(provenance?.compositeInstance ? { instance: provenance.compositeInstance } : {}),
+        ...(provenance?.compositeCall ? { compositeCall: { ...provenance.compositeCall } } : {}),
+        fields,
+    };
+}
+/**
+ * A whole build's fold provenance.
+ *
+ * `provenanceOf` is injected rather than read off the entity here so the same
+ * function serves a build (where it is `getProvenance`) and a test with a
+ * hand-written record. Entities with no properties are absent; sorted, because
+ * a build's outputs are compared byte for byte.
+ */
+export function foldProvenanceOfEntities(entities, provenanceOf) {
+    const out = {};
+    for (const name of [...entities.keys()].sort()) {
+        const entity = entities.get(name);
+        const record = foldProvenanceOfEntity(entity, provenanceOf(entity));
+        if (record)
+            out[name] = record;
+    }
+    return out;
+}
+/** One-line rendering of a field origin, for a report. */
+export function describeFoldFieldOrigin(origin) {
+    switch (origin.kind) {
+        case "composite-parameter":
+            return `parameter ${origin.parameters.join(", ")} of ${compositeCall(origin.composite, origin.instance)}`;
+        case "composite-literal":
+            return `fixed by ${compositeCall(origin.composite, origin.instance)}`;
+        case "direct":
+            return "declared directly";
+        case "unknown":
+            return `origin unknown (${unknownOriginText(origin.reason)})`;
+    }
+}
+/** Why an origin could not be determined, in words a report can print. */
+export function unknownOriginText(reason) {
+    switch (reason) {
+        case "composite-not-interpreted":
+            return "expanded by a composite whose factory this build did not interpret";
+        case "no-provenance":
+            return "this build recorded no provenance for the entity";
+        case "host-call":
+            return "the value is what a host call returned";
+        case "host-value":
+            return "the value is one a host package exports";
+    }
+}
+/** `AutoscaledService composite call \`api\``, or just the composite when the call has no name. */
+function compositeCall(composite, instance) {
+    return instance ? `the \`${instance}\` call of composite ${composite}` : `composite ${composite}`;
+}
+/** A file as a report prints it: relative to `root` when it is inside it, otherwise as recorded. */
+function displayFile(file, root) {
+    if (!root || !isAbsolute(file))
+        return file;
+    const rel = relative(root, file);
+    return rel && !rel.startsWith("..") && !isAbsolute(rel) ? rel : file;
+}
+/** `src/app.ts:12`, relative to `root` when it is inside it. */
+export function formatSourceLocation(location, root) {
+    return `${displayFile(location.file, root)}:${location.line}`;
+}
+/** ` in src/app.infra.ts`, or nothing when the build recorded no file. */
+function inFile(sourceFile, root) {
+    return sourceFile ? ` in ${displayFile(sourceFile, root)}` : "";
+}
+/**
+ * The composite call as the author wrote the arguments that govern a field:
+ * `WebApp({ replicas: 3 })`, or `WebApp({ iam: { path: "/service/" } })` for a
+ * nested parameter. Only arguments actually written at the call appear; when
+ * none is, the call is shown as `WebApp(...)`.
+ */
+export function describeCompositeArguments(composite, locations) {
+    const written = locations.filter((a) => a.text !== undefined);
+    if (written.length === 0)
+        return `${composite}(...)`;
+    const parts = written.map((a) => {
+        const outer = a.parameter.split(".").slice(0, -1);
+        return outer.reduceRight((inner, key) => `${key}: { ${inner} }`, a.text);
+    });
+    return `${composite}({ ${parts.join(", ")} })`;
+}
+/**
+ * Where a composite-parameter field was set, as `at src/app.ts:12`: the first
+ * argument written at the call, else the call, else the declaring file.
+ */
+function parameterSite(origin, sourceFile, root) {
+    const written = origin.arguments?.find((a) => a.text !== undefined);
+    const location = written ?? origin.call ?? origin.arguments?.[0];
+    if (location)
+        return ` at ${formatSourceLocation(location, root)}`;
+    return inFile(sourceFile, root);
+}
+/** ` at src/app.ts:10` for the composite call, else the declaring file. */
+function callSite(call, sourceFile, root) {
+    return call ? ` at ${formatSourceLocation(call, root)}` : inFile(sourceFile, root);
+}
+/** A value as a report prints it. */
+function renderValue(value) {
+    if (value === undefined)
+        return "unset";
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+/**
+ * Classify one drifted field by its origin.
+ *
+ * The caller has already established this is drift in #2160's sense: a path
+ * source declared, whose live value moved. Undeclared fields are held
+ * elsewhere and never reach here, so the only question left is which of the
+ * four origins produced the field.
+ *
+ * `entityType` names the resource in the summary line, and `root` (the
+ * project directory) makes the file names in it relative. Both are optional;
+ * without them the summary uses the entity name alone and absolute files.
+ */
+export function resolveDriftedField(input) {
+    const origin = classifyFieldOrigin(input.origin, input.provenance);
+    const sourceFile = input.provenance?.sourceFile;
+    const root = input.root;
+    const move = `${renderValue(input.declared)} to ${renderValue(input.live)}`;
+    const subject = `${input.path} on ${input.entityType ? `${input.entityType} ` : ""}${input.entity}`;
+    const summary = (() => {
+        switch (origin.kind) {
+            case "composite-parameter":
+                return (`${subject} comes from ${describeCompositeArguments(origin.composite, origin.arguments ?? [])}` +
+                    `${parameterSite(origin, sourceFile, root)}` +
+                    (origin.arguments?.some((a) => a.text !== undefined)
+                        ? ""
+                        : ` (parameter ${origin.parameters.join(", ")}, not written at the call)`));
+            case "composite-literal":
+                return (`${subject} is fixed inside composite ${origin.composite}; ` +
+                    `no argument to the call${callSite(origin.call, sourceFile, root)} moves it`);
+            case "direct":
+                return `${subject} is declared directly${inFile(sourceFile, root)}`;
+            case "unknown":
+                return `${subject} has an unknown origin: ${unknownOriginText(origin.reason)}`;
+        }
+    })();
+    const resolution = (() => {
+        switch (origin.kind) {
+            case "composite-parameter": {
+                const parameters = origin.parameters;
+                return {
+                    kind: "propose-parameter",
+                    composite: origin.composite,
+                    ...(origin.instance ? { instance: origin.instance } : {}),
+                    ...(sourceFile ? { sourceFile } : {}),
+                    parameters: [...parameters],
+                    description: `change ${parameters.length === 1 ? "parameter" : "parameters"} ` +
+                        `${parameters.map((p) => `\`${p}\``).join(", ")} of ` +
+                        `${compositeCall(origin.composite, origin.instance)}${parameterSite(origin, sourceFile, root)} ` +
+                        `so \`${input.path}\` moves from ${move}. The composite stays.`,
+                };
+            }
+            case "composite-literal":
+                return {
+                    kind: "refuse-fixed",
+                    composite: origin.composite,
+                    ...(origin.instance ? { instance: origin.instance } : {}),
+                    ...(sourceFile ? { sourceFile } : {}),
+                    description: `refused: \`${input.path}\` is fixed by ${compositeCall(origin.composite, origin.instance)}` +
+                        `${callSite(origin.call, sourceFile, root)}, so no argument at the call site moves it. ` +
+                        `Parameterize the field in composite ${origin.composite}, or stop using the composite here.`,
+                };
+            case "direct":
+                return {
+                    kind: "edit-declaration",
+                    ...(sourceFile ? { sourceFile } : {}),
+                    description: `change the declared value of \`${input.path}\`${inFile(sourceFile, root)} from ${move}.`,
+                };
+            case "unknown":
+                return {
+                    kind: "fall-back",
+                    reason: origin.reason,
+                    ...(sourceFile ? { sourceFile } : {}),
+                    description: `origin unknown (${unknownOriginText(origin.reason)}), so falling back to changing the ` +
+                        `declared value of \`${input.path}\`${inFile(sourceFile, root)} from ${move}.`,
+                };
+        }
+    })();
+    return {
+        entity: input.entity,
+        path: input.path,
+        ...("declared" in input ? { declared: input.declared } : {}),
+        ...("live" in input ? { live: input.live } : {}),
+        origin,
+        summary,
+        resolution,
+    };
+}
+/**
+ * Every drifted field in a deep diff, classified.
+ *
+ * Reads `drifted` only. `unclaimed` is somebody else's field and
+ * `accepted` is a difference the baseline holds back, and neither may become an
+ * update, so neither is offered a resolution.
+ *
+ * A drift row of kind `absent` has no live value: the field is declared and the
+ * cloud does not have it. That is still drift on a declared path, and the same
+ * four origins decide what may be proposed about it.
+ */
+export function resolveDeepDrift(drifted, provenanceOf, options = {}) {
+    const out = [];
+    for (const entity of drifted) {
+        const provenance = provenanceOf(entity.name);
+        for (const change of entity.changes) {
+            out.push(resolveDriftedField({
+                entity: entity.name,
+                entityType: entity.type,
+                path: change.path,
+                ...("declared" in change ? { declared: change.declared } : {}),
+                ...("live" in change ? { live: change.live } : {}),
+                ...(change.origin ? { origin: change.origin } : {}),
+                ...(provenance ? { provenance } : {}),
+                ...(options.root ? { root: options.root } : {}),
+            }));
+        }
+    }
+    return out;
+}

package/dist/gate-decision.js

@@ -0,0 +1,260 @@
+/**
+ * A gate's decision for a plan digest, and the seal check it needs, for a
+ * tool that runs from one bundled file (#3763, decision #3756).
+ *
+ * `@intentius/chant/gate-decision` holds what a tool needs to decide a
+ * plan-bound gate the way chant's own wave gate does (`chant run wave`,
+ * `./op/op-waves-run.ts`) under each approval mode:
+ *
+ * - `ledger`: an approval of this digest on `chant/lifecycle`, newer than the
+ *   gate's newest pending fact ({@link decideGateApproval}).
+ * - `sealed`: the same, counting only an approval whose seal verifies for its
+ *   approver against the signers file at base ({@link gateSignersAt},
+ *   {@link gateSealRefusal}). The seal is checked with node:crypto, so the job
+ *   needs no ssh-keygen.
+ * - `pr-review`: the same as `ledger`, or else the merged pull request's
+ *   approving review, when its head planned this digest
+ *   ({@link reviewApproval}).
+ *
+ * A gate the declaration at base names under `identity.gates` counts only a
+ * sealed approval from its class: {@link identityGateAdmissionAt} reads that
+ * rule from a bare clone at base and judges by `admitApprover`, the function
+ * chant's `gateAdmission` judges by (#3862); pass its `refuses` to
+ * {@link decideGateApproval}.
+ *
+ * With `spend` (#3784), an approval a wave already applied under is spent and
+ * counts for nothing, as terragucci's wave gate has it: the caller hands in
+ * the lines of `_gates/<op>/applied.jsonl` ({@link parseAppliedGateLines}).
+ *
+ * The module reads the ledger lines and the review it is handed; reading
+ * them is the caller's. It imports no TypeScript, esbuild, zod, lint, fold or
+ * codegen module, and none of chant's git ledger code, which
+ * `gate-decision-bundle.test.ts` holds it to. Its rules are chant's own:
+ * `./lifecycle/gate-ledger-select.ts` is what `evaluateGate` decides by, and
+ * `gate-decision.test.ts` decides the same ledgers both ways.
+ */
+import { spawnSync } from "node:child_process";
+import { isPendingGateExpired, latestPendingGate, latestResolutionForPlan, } from "./lifecycle/gate-ledger-select.js";
+import { samePlanDigest } from "./lifecycle/plan-digest.js";
+import { isApprovalSpent } from "./lifecycle/gate-applied.js";
+import { gateSealRefusal } from "./workspace/trust/gate-seal.js";
+import { DEFAULT_SIGNERS_PATH, TRUST_CONFIG_PATH, parseAllowedSigners, trustConfigProblems, } from "./workspace/trust/trust-files.js";
+import { parseJsonText } from "./workspace/jsonc.js";
+import { CORE_CLASSES, admitApprover } from "./workspace/identity-gate-rule.js";
+export { GATE_APPROVAL_SOURCES } from "./op/op-waves.js";
+export { isPendingGateExpired, latestPendingGate, latestResolutionForPlan, latestResolutionSince, } from "./lifecycle/gate-ledger-select.js";
+export { GATE_SEAL_NAMESPACE, gateSealPayload, gateSealRefusal, sshKeyFingerprint, verifySshSignatureWith, } from "./workspace/trust/gate-seal.js";
+export { DEFAULT_SIGNERS_PATH, TRUST_CONFIG_PATH, parseAllowedSigners, trustConfigProblems, } from "./workspace/trust/trust-files.js";
+export { CORE_CLASSES, admitApprover, grantedClasses, } from "./workspace/identity-gate-rule.js";
+export { appliedGateApplies, appliedGatePath, isApprovalSpent, parseAppliedGateLines, } from "./lifecycle/gate-applied.js";
+// ── reading at base ──────────────────────────────────────────────────────
+function git(repo, args) {
+    return spawnSync("git", args, { cwd: repo, encoding: "utf-8" });
+}
+/** A file's text at `base`, or undefined when `base` holds no file at `path`. */
+function showAt(repo, base, path) {
+    const r = git(repo, ["cat-file", "blob", `${base}:${path}`]);
+    return r.status === 0 ? r.stdout : undefined;
+}
+/**
+ * The commit a gate's rule is read at when the default branch applies its
+ * own commit: the first parent of HEAD, the branch as it stood before the
+ * merge, so a merge that adds a signer or drops a gate does not judge its own
+ * apply. A shallow checkout fetches that one commit from `origin`. A root
+ * commit has no parent and is its own base. Throws when it cannot be read.
+ */
+export function baseCommit(repo) {
+    const head = git(repo, ["rev-parse", "--verify", "-q", "HEAD^{commit}"]);
+    const sha = head.stdout.trim();
+    if (head.status !== 0 || !sha)
+        throw new Error(`${repo} has no commit checked out, so the gate cannot be decided`);
+    // The commit object's first `parent` line: a shallow clone keeps it even when it lacks the parent itself.
+    const header = git(repo, ["cat-file", "commit", sha]).stdout.split("\n\n")[0] ?? "";
+    const parent = /^parent ([0-9a-f]{40,64})$/m.exec(header)?.[1];
+    if (!parent)
+        return sha;
+    const has = () => git(repo, ["cat-file", "-e", `${parent}^{commit}`]).status === 0;
+    if (!has())
+        git(repo, ["fetch", "-q", "--depth=1", "origin", parent]);
+    if (!has())
+        throw new Error(`cannot fetch ${parent.slice(0, 12)}, the commit before this one, so the gate cannot be decided`);
+    return parent;
+}
+/** The signers and role grants at `base`, as chant's trust policy reads them. */
+function trustAt(repo, base) {
+    const off = (problems) => ({ signers: { base, signersPath: DEFAULT_SIGNERS_PATH, active: false, signers: [], problems }, roles: {} });
+    const configText = showAt(repo, base, TRUST_CONFIG_PATH);
+    let signersPath = DEFAULT_SIGNERS_PATH;
+    let roles = {};
+    if (configText !== undefined) {
+        let raw;
+        try {
+            raw = JSON.parse(configText);
+        }
+        catch (err) {
+            return off([`${TRUST_CONFIG_PATH} is not JSON: ${err instanceof Error ? err.message : String(err)}`]);
+        }
+        const problems = trustConfigProblems(raw);
+        if (problems.length > 0)
+            return off([`${TRUST_CONFIG_PATH} is invalid: ${problems.join("; ")}`]);
+        signersPath = raw.signers ?? DEFAULT_SIGNERS_PATH;
+        roles = raw.roles ?? {};
+    }
+    const text = showAt(repo, base, signersPath);
+    return { signers: { base, signersPath, active: text !== undefined, signers: text === undefined ? [] : parseAllowedSigners(text).signers, problems: [] }, roles };
+}
+/**
+ * The signers at `base`: the file `.chant/trust.json` names there, else
+ * `.chant/allowed_signers`, read as chant's trust policy reads it. A
+ * trust.json that is not valid (`trustConfigProblems`) turns attestation
+ * off, as it does in chant, so a sealed gate passes nothing. `base` is a
+ * commit the repository holds, such as {@link baseCommit}'s answer.
+ */
+export function gateSignersAt(repo, base) {
+    return trustAt(repo, base).signers;
+}
+/** The declaration at `base`, parsed, or null when there is none. Throws when it cannot be parsed. */
+function declarationAt(repo, base) {
+    for (const file of ["chant.workspace.json", "chant.workspace.jsonc"]) {
+        const text = showAt(repo, base, file);
+        if (text === undefined)
+            continue;
+        const parsed = parseJsonText(text, { jsonc: file.endsWith(".jsonc") });
+        if (!parsed.ok)
+            throw new Error(`${file} at base is not valid JSON (${parsed.message}), so the gate cannot be decided`);
+        return { file, value: parsed.value };
+    }
+    return null;
+}
+function identityGatesOf(declaration) {
+    const gates = declaration?.identity?.gates ?? {};
+    return Object.entries(gates).map(([gate, entry]) => ({ gate, class: typeof entry?.class === "string" ? entry.class : null }));
+}
+/**
+ * The gates `chant.workspace.json` (or `.jsonc`) at `base` names under
+ * `identity.gates`: each counts only a sealed approval, from its class when
+ * it names one. {@link identityGateAdmissionAt} judges an approval by one.
+ * Empty when there is no declaration at base. Throws when the declaration
+ * there cannot be parsed, since the gate cannot be decided.
+ */
+export function identityGatesAt(repo, base) {
+    const declaration = declarationAt(repo, base);
+    return declaration === null ? [] : identityGatesOf(declaration.value);
+}
+/**
+ * The `identity.gates` rule for `gate` at `base`, or null when the
+ * declaration there names none: what chant's `gateAdmission(cwd, gate, base)`
+ * answers, read from a bare clone. An approval counts when its seal verifies
+ * for its approver against the signers at base and, when the gate names a
+ * class, the role grants in `.chant/trust.json` at base put the approver in
+ * it. Both judge with the same function ({@link admitApprover}).
+ *
+ * The classes are the four core ones, then `classes`, the domain classes the
+ * caller read from the pinned packages (`./workspace-principals`), in pin
+ * order. This reader loads no package. A gate whose class is in neither
+ * refuses every approval, and when the declaration at base pins anything the
+ * reason says the pins were not read, since one of them may supply it.
+ * Throws when the declaration at base cannot be parsed.
+ */
+export function identityGateAdmissionAt(repo, base, gate, opts = {}) {
+    const declaration = declarationAt(repo, base);
+    const requirement = declaration === null ? undefined : identityGatesOf(declaration.value).find((g) => g.gate === gate);
+    if (!requirement)
+        return null;
+    const { signers, roles } = trustAt(repo, base);
+    const pins = declaration.value.pins;
+    const rule = {
+        gate,
+        class: requirement.class,
+        signers,
+        roles,
+        classes: [...CORE_CLASSES, ...(opts.classes ?? [])],
+        ...(Array.isArray(pins) && pins.length > 0
+            ? { unknownClass: `is not a core class, and this reader does not load the classes the pinned packages in ${declaration.file} at base supply` }
+            : {}),
+    };
+    return { requirement, refuses: (a) => admitApprover(rule, a) };
+}
+/**
+ * Whether the merged pull request's review approves `digest` (#3684): a
+ * writer other than its author approved its head, and the head planned this
+ * digest (`headDigest`, from the plans `chant run wave --record-plans`
+ * recorded for the head; undefined when none were). Reading the review and
+ * the plans is the caller's; under `pr-review` the caller records the
+ * approval on the ledger when this approves.
+ */
+export function reviewApproval(merged, headDigest, digest) {
+    const seen = { pr: merged.pr, head: merged.head, ...(merged.url ? { url: merged.url } : {}) };
+    if (merged.approvers.length === 0) {
+        const why = merged.refused.length > 0 ? merged.refused.join("; ") : "nobody approved it";
+        return { approved: false, review: { ...seen, reason: `no writer other than its author approved the head of #${merged.pr}: ${why}` } };
+    }
+    if (headDigest === undefined) {
+        return {
+            approved: false,
+            review: { ...seen, approvers: merged.approvers, reason: `no plans are recorded for the head ${merged.head.slice(0, 12)} of #${merged.pr} (its pipeline runs \`chant run wave --record-plans\`)` },
+        };
+    }
+    if (headDigest !== digest) {
+        return {
+            approved: false,
+            review: { ...seen, approvers: merged.approvers, reason: `the plan moved after the review: the head planned ${headDigest}, and the merge plans ${digest}` },
+        };
+    }
+    return { approved: true, review: { ...seen, approvers: merged.approvers } };
+}
+const EPOCH = new Date(0).toISOString();
+/**
+ * Decide a plan-bound gate against its ledger lines, as chant's wave gate
+ * does: an approval counts when it names this gate and digest (and
+ * environment, when set), is newer than the gate's newest pending fact, and
+ * passes the mode's rule: any under `ledger` and `pr-review`, a verified seal
+ * under `sealed`. With none, `pr-review` takes the review's answer. Writes
+ * nothing: recording a pending fact, or the review's approval, is the
+ * caller's.
+ */
+export function decideGateApproval(input) {
+    const { gate, planDigest, environment: env } = input;
+    const mode = input.mode ?? "ledger";
+    const pending = env === undefined ? input.ledger.pending : input.ledger.pending.filter((p) => p.environment === env);
+    const mine = (env === undefined ? input.ledger.resolutions : input.ledger.resolutions.filter((r) => r.environment === undefined || r.environment === env)).filter((r) => r.gate === gate);
+    const sealed = mode === "sealed";
+    const noSigners = { base: null, signersPath: DEFAULT_SIGNERS_PATH, active: false, signers: [], problems: ["no signers were read for this sealed gate"] };
+    const why = (r) => input.refuses?.(r) ?? (sealed ? gateSealRefusal(input.signers ?? noSigners, r) : null);
+    const standingFact = latestPendingGate(pending, gate);
+    const since = standingFact?.timestamp ?? EPOCH;
+    const counted = [];
+    const uncounted = [];
+    let spent;
+    for (const r of mine) {
+        if (input.spend && isApprovalSpent(input.ledger.applied ?? [], r)) {
+            if (new Date(r.timestamp).getTime() >= new Date(since).getTime() && (!spent || new Date(r.timestamp).getTime() >= new Date(spent.timestamp).getTime()))
+                spent = r;
+            continue;
+        }
+        const reason = why(r);
+        if (reason === null)
+            counted.push(r);
+        else if (samePlanDigest(r.planDigest, planDigest) && new Date(r.timestamp).getTime() >= new Date(since).getTime())
+            uncounted.push({ resolution: r, reason });
+    }
+    const found = latestResolutionForPlan(counted, gate, since, planDigest);
+    if (found.resolution)
+        return { status: "approved", via: "ledger", resolution: found.resolution };
+    const reviewSpent = input.spend === true && input.review?.approved === true &&
+        isApprovalSpent(input.ledger.applied ?? [], { gate, planDigest, review: { ...(input.review.review.head ? { head: input.review.review.head } : {}) } });
+    if (mode === "pr-review" && input.review?.approved && !reviewSpent)
+        return { status: "approved", via: "pr-review", review: input.review.review };
+    const now = input.now ?? new Date().toISOString();
+    const standing = standingFact && !isPendingGateExpired(standingFact, now) && samePlanDigest(standingFact.planDigest, planDigest) ? standingFact : undefined;
+    return {
+        status: "waiting",
+        ...(standing ? { standing } : {}),
+        ...(found.mismatched ? { mismatched: found.mismatched } : {}),
+        uncounted: uncounted.sort((a, b) => new Date(a.resolution.timestamp).getTime() - new Date(b.resolution.timestamp).getTime()),
+        ...(mode === "pr-review" && input.review
+            ? { review: reviewSpent ? { ...input.review.review, reason: `a wave already applied this digest under the review of ${input.review.review.head?.slice(0, 12) ?? "its head"}, so the review is spent` } : input.review.review }
+            : {}),
+        ...(spent ? { spent } : {}),
+    };
+}