@intentius/chant 0.124.27 → 0.124.28

package/dist/lifecycle/release-cut.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Cutting a release from a green commit (#4026, ws-104).
+ *
+ * The cut takes the checkout's `HEAD`, refuses it unless it carries a
+ * `ci/green/<sha>` tag and no `ci/revoked/<sha>` tag (ws-103, read from local
+ * tags), and refuses a working tree with uncommitted changes to tracked
+ * files, since the compile would then not be the commit's. It compiles every
+ * environment the member declares, in its promotion order (#4030), and
+ * refuses a component whose build steps differ between environments, since
+ * "built once" can't hold for it. It then builds each component's artifacts
+ * once, stores the release and appends the cut.
+ *
+ * An artifact whose source did not change since the earlier release cut
+ * from the nearest ancestor commit is not built again: the release carries that
+ * release's entry, so a config-only release keeps the same artifact digests.
+ * "Did not change" means git sees no change between the two commits in the
+ * component's own file, the member's `chant.config.ts` and the paths its
+ * build steps read.
+ *
+ * A project with no components (#4046) needs no special case here: its
+ * targets hold the files `chant build --env <env>` writes, each with
+ * `component: null`, and `artifactDigests` is empty.
+ *
+ * Compiling goes through a {@link TargetCompiler}, so a test hands the cut
+ * fixtures and the CLI hands it child processes.
+ *
+ * Who may cut (#4031): when the declaration at base names a `release` gate
+ * in `identity.gates`, a cut must be signed (`--sign`), its signature must
+ * verify for the actor against the signers at base, and when the gate names
+ * a class the actor must be in it. A cut signed without that gate is signed
+ * all the same, and readers report whether the signature verifies. With
+ * `ci.green.signedSince` declared, a green tag counts only with a valid
+ * statement (`../workspace/ci-green.ts`), so a hand-pushed tag cuts nothing.
+ */
+import { type Release, type ReleaseCut } from "./release-store.js";
+import type { CompiledTarget, TargetCompiler } from "../components/release-compile.js";
+/** The stable codes a cut refuses with. */
+export type ReleaseCutCode = "not-a-git-repository" | "release-commit-not-green" | "release-commit-revoked" | "release-worktree-dirty" | "release-no-environments" | "release-no-components" | "release-build-inputs-differ" | "release-unsigned" | "release-signer-refused" | "declaration-invalid";
+export declare class ReleaseCutError extends Error {
+    readonly code: ReleaseCutCode;
+    readonly fix?: string | undefined;
+    constructor(code: ReleaseCutCode, message: string, fix?: string | undefined);
+}
+export interface CutRequest {
+    /** The member's directory. */
+    cwd: string;
+    compiler: TargetCompiler;
+    /** The label, or null to cut without one. */
+    label: string | null;
+    actor: string;
+    /** The environments in promotion order. Read from the member's `chant.config.ts` when absent. */
+    environments?: readonly string[];
+    now?: () => Date;
+    /** The process environment the CI run is read from. */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Sign the cut (#4031): an ssh key file, or true for git's
+     * `user.signingkey`, as `chant approve --sign` takes it. The signature is
+     * over the release digest, the label, the actor and the time, and `actor`
+     * must be the principal the signers file lists the key for.
+     */
+    sign?: string | true;
+}
+export interface CutResult {
+    release: Release;
+    /** The cut line written, or null when this digest was already cut. */
+    cut: ReleaseCut | null;
+    /** The release's label after the cut. */
+    label: string | null;
+    /** Whether the release file was written now, rather than already stored. */
+    stored: boolean;
+    /** The components whose artifacts were taken from an earlier release, and that release's digest. */
+    reused: Array<{
+        component: string;
+        from: string;
+    }>;
+}
+/**
+ * Whether `sha` has a green tag and no revoked tag, read from local tags,
+ * and the tags on it that were ignored for want of a valid statement
+ * (#4031). The tags are judged by `green`, the declaration's `ci.green` at
+ * base, with the runner keys read at its branch's tip; with no `ci.green`,
+ * every tag counts.
+ */
+export declare function greenState(top: string, sha: string, green?: import("../workspace/declaration.js").CiGreen | null): Promise<{
+    state: "green" | "revoked" | "none";
+    ignored: Array<{
+        tag: string;
+        status: string;
+        reason: string;
+    }>;
+}>;
+/** Which components' build steps differ between environments, with the environments they appear in. */
+export declare function differingBuildSteps(targets: readonly CompiledTarget[]): Array<{
+    component: string;
+    envs: string[];
+}>;
+/**
+ * Cut a release of the member at `req.cwd` from its checkout's `HEAD`. Writes
+ * the release and the cut to the local `chant/lifecycle` branch and does not
+ * push. Throws {@link ReleaseCutError} before anything is written when the
+ * commit isn't green, the tree is dirty, or an environment can't be compiled
+ * to the same artifacts, and `ReleaseLabelError` (./release-store.ts) when the
+ * label is taken or the release already carries another one.
+ */
+export declare function cutRelease(req: CutRequest): Promise<CutResult>;
+//# sourceMappingURL=release-cut.d.ts.map

package/dist/lifecycle/release-cut.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-cut.d.ts","sourceRoot":"","sources":["../../src/lifecycle/release-cut.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAUH,OAAO,EAML,KAAK,OAAO,EAEZ,KAAK,UAAU,EAGhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAEpF,2CAA2C;AAC3C,MAAM,MAAM,cAAc,GACtB,sBAAsB,GACtB,0BAA0B,GAC1B,wBAAwB,GACxB,wBAAwB,GACxB,yBAAyB,GACzB,uBAAuB,GACvB,6BAA6B,GAC7B,kBAAkB,GAClB,wBAAwB,GACxB,qBAAqB,CAAC;AAE1B,qBAAa,eAAgB,SAAQ,KAAK;IAEtC,QAAQ,CAAC,IAAI,EAAE,cAAc;IAE7B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM;IAHvB,YACW,IAAI,EAAE,cAAc,EAC7B,OAAO,EAAE,MAAM,EACN,GAAG,CAAC,EAAE,MAAM,YAAA,EAItB;CACF;AAED,MAAM,WAAW,UAAU;IACzB,8BAA8B;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,cAAc,CAAC;IACzB,6CAA6C;IAC7C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,iGAAiG;IACjG,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,uDAAuD;IACvD,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,sEAAsE;IACtE,GAAG,EAAE,UAAU,GAAG,IAAI,CAAC;IACvB,yCAAyC;IACzC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,4EAA4E;IAC5E,MAAM,EAAE,OAAO,CAAC;IAChB,oGAAoG;IACpG,MAAM,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpD;AAcD;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,KAAK,GAAE,OAAO,0BAA0B,EAAE,OAAO,GAAG,IAAW,GAC9D,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IAAC,OAAO,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,CAkBnH;AAED,uGAAuG;AACvG,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,GAAG,KAAK,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAapH;AAiBD;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CA0KpE"}

package/dist/lifecycle/release-cut.js

@@ -0,0 +1,273 @@
+/**
+ * Cutting a release from a green commit (#4026, ws-104).
+ *
+ * The cut takes the checkout's `HEAD`, refuses it unless it carries a
+ * `ci/green/<sha>` tag and no `ci/revoked/<sha>` tag (ws-103, read from local
+ * tags), and refuses a working tree with uncommitted changes to tracked
+ * files, since the compile would then not be the commit's. It compiles every
+ * environment the member declares, in its promotion order (#4030), and
+ * refuses a component whose build steps differ between environments, since
+ * "built once" can't hold for it. It then builds each component's artifacts
+ * once, stores the release and appends the cut.
+ *
+ * An artifact whose source did not change since the earlier release cut
+ * from the nearest ancestor commit is not built again: the release carries that
+ * release's entry, so a config-only release keeps the same artifact digests.
+ * "Did not change" means git sees no change between the two commits in the
+ * component's own file, the member's `chant.config.ts` and the paths its
+ * build steps read.
+ *
+ * A project with no components (#4046) needs no special case here: its
+ * targets hold the files `chant build --env <env>` writes, each with
+ * `component: null`, and `artifactDigests` is empty.
+ *
+ * Compiling goes through a {@link TargetCompiler}, so a test hands the cut
+ * fixtures and the CLI hands it child processes.
+ *
+ * Who may cut (#4031): when the declaration at base names a `release` gate
+ * in `identity.gates`, a cut must be signed (`--sign`), its signature must
+ * verify for the actor against the signers at base, and when the gate names
+ * a class the actor must be in it. A cut signed without that gate is signed
+ * all the same, and readers report whether the signature verifies. With
+ * `ci.green.signedSince` declared, a green tag counts only with a valid
+ * statement (`../workspace/ci-green.ts`), so a hand-pushed tag cuts nothing.
+ */
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import { canonicalJson } from "../effect-receipt.js";
+import { contentDigest } from "../content-digest.js";
+import { getHeadCommit } from "./git.js";
+import { resolveMemberLedger } from "./member-ledger.js";
+import { resolveCiRun } from "./release-ledger.js";
+import { appendCut, makeRelease, persistRelease, readAllReleases, readCuts, } from "./release-store.js";
+export class ReleaseCutError extends Error {
+    constructor(code, message, fix) {
+        super(message);
+        this.code = code;
+        this.fix = fix;
+        this.name = "ReleaseCutError";
+    }
+}
+function git(top, args) {
+    return execFileSync("git", args, { cwd: top, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+function tryGit(top, args) {
+    try {
+        return git(top, args);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether `sha` has a green tag and no revoked tag, read from local tags,
+ * and the tags on it that were ignored for want of a valid statement
+ * (#4031). The tags are judged by `green`, the declaration's `ci.green` at
+ * base, with the runner keys read at its branch's tip; with no `ci.green`,
+ * every tag counts.
+ */
+export async function greenState(top, sha, green = null) {
+    const { readCiTags } = await import("../workspace/ci-green.js");
+    const base = green
+        ? (tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/remotes/origin/${green.branch}^{commit}`]) ??
+            tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/heads/${green.branch}^{commit}`]) ??
+            tryGit(top, ["rev-parse", "HEAD"]))
+        : null;
+    let tags;
+    try {
+        tags = readCiTags(top, green, base);
+    }
+    catch (err) {
+        const { WorkspaceReadError } = await import("../workspace/declaration.js");
+        if (err instanceof WorkspaceReadError)
+            throw new ReleaseCutError("declaration-invalid", err.message);
+        throw err;
+    }
+    const ignored = tags.ignored.get(sha) ?? [];
+    if (tags.revoked.has(sha))
+        return { state: "revoked", ignored };
+    return { state: tags.green.has(sha) ? "green" : "none", ignored };
+}
+/** Which components' build steps differ between environments, with the environments they appear in. */
+export function differingBuildSteps(targets) {
+    const byComponent = new Map();
+    for (const t of targets) {
+        for (const [component, steps] of Object.entries(t.buildSteps)) {
+            if (!byComponent.has(component))
+                byComponent.set(component, new Map());
+            byComponent.get(component).set(t.env, canonicalJson(steps));
+        }
+    }
+    const out = [];
+    for (const [component, perEnv] of byComponent) {
+        if (new Set(perEnv.values()).size > 1)
+            out.push({ component, envs: [...perEnv.keys()] });
+    }
+    return out.sort((a, b) => (a.component < b.component ? -1 : 1));
+}
+/** The earlier release of this member cut from the nearest ancestor of `commit`. */
+async function previousRelease(top, commit, cwd) {
+    const { releases } = await readAllReleases({ cwd });
+    const { cuts } = await readCuts({ cwd });
+    const cutAt = new Map();
+    for (const c of cuts)
+        if (!cutAt.has(c.releaseDigest) || c.timestamp > cutAt.get(c.releaseDigest))
+            cutAt.set(c.releaseDigest, c.timestamp);
+    const candidates = releases
+        .filter((r) => cutAt.has(r.releaseDigest) && r.commit !== commit)
+        .filter((r) => tryGit(top, ["merge-base", "--is-ancestor", r.commit, commit]) !== null)
+        .map((r) => ({ r, depth: Number(tryGit(top, ["rev-list", "--count", r.commit]) ?? 0), at: cutAt.get(r.releaseDigest) }))
+        // The nearest ancestor first, then the newest cut of it.
+        .sort((a, b) => b.depth - a.depth || (b.at < a.at ? -1 : b.at > a.at ? 1 : 0));
+    return candidates[0]?.r;
+}
+/**
+ * Cut a release of the member at `req.cwd` from its checkout's `HEAD`. Writes
+ * the release and the cut to the local `chant/lifecycle` branch and does not
+ * push. Throws {@link ReleaseCutError} before anything is written when the
+ * commit isn't green, the tree is dirty, or an environment can't be compiled
+ * to the same artifacts, and `ReleaseLabelError` (./release-store.ts) when the
+ * label is taken or the release already carries another one.
+ */
+export async function cutRelease(req) {
+    const cwd = resolve(req.cwd);
+    const top = tryGit(cwd, ["rev-parse", "--show-toplevel"]);
+    if (!top)
+        throw new ReleaseCutError("not-a-git-repository", "a release is cut from a commit, and this directory is not in a git repository");
+    const commit = await getHeadCommit({ cwd });
+    // #4031: the declaration at base says whether tags need a statement and who may cut.
+    const { scopeSource } = await import("../workspace/write-scope.js");
+    const { releaseRuleFrom } = await import("../workspace/identity.js");
+    const source = scopeSource(cwd);
+    const { state, ignored } = await greenState(top, commit, source.declaration?.ci?.green ?? null);
+    if (state !== "green") {
+        const why = ignored.length > 0 ? `; ignored: ${ignored.map((t) => `${t.tag} (${t.status}): ${t.reason}`).join("; ")}` : "";
+        throw new ReleaseCutError(state === "revoked" ? "release-commit-revoked" : "release-commit-not-green", state === "revoked"
+            ? `commit ${commit.slice(0, 12)} has a ci/revoked tag: it went red after it was green, so no release is cut from it`
+            : ignored.some((t) => t.tag.startsWith("ci/green/"))
+                ? `commit ${commit.slice(0, 12)} has no ci/green tag that counts, so no release is cut from it${why}`
+                : `commit ${commit.slice(0, 12)} has no ci/green tag, so no release is cut from it`, "Check out a green commit (`chant ci last-green` names the newest) after fetching the tags: git fetch origin --tags");
+    }
+    // Who may cut is the declaration's identity.gates.release, read at base.
+    const releaseRule = releaseRuleFrom(source);
+    if (releaseRule.requirement && req.sign === undefined) {
+        throw new ReleaseCutError("release-unsigned", `chant.workspace.json at base names a release gate in identity.gates${releaseRule.requirement.class !== null ? `, from the class ${releaseRule.requirement.class}` : ""}, and this cut is not signed`, `chant release cut <label> --actor <principal> --sign [<key file>], with a key ${releaseRule.rule.signers.signersPath} at base lists for that principal.`);
+    }
+    const dirty = tryGit(top, ["status", "--porcelain", "--untracked-files=no"]);
+    if (dirty) {
+        throw new ReleaseCutError("release-worktree-dirty", `the working tree has uncommitted changes to tracked files, so a compile here would not be commit ${commit.slice(0, 12)}'s`, "Commit or stash them, or cut from a clean checkout of the commit.");
+    }
+    let envs = req.environments;
+    if (!envs) {
+        const { readMemberPromotionOrder } = await import("../workspace/promotion-order.js");
+        envs = ((await readMemberPromotionOrder(cwd)) ?? []).map((s) => s.name);
+    }
+    if (envs.length === 0) {
+        throw new ReleaseCutError("release-no-environments", "this member's chant.config.ts declares no environments, so there is nothing to compile a release for", "Declare them in promotion order: environments: [\"dev\", \"staging\", \"prod\"]");
+    }
+    const compiled = [];
+    for (const env of envs)
+        compiled.push(await req.compiler.compile(env));
+    // A project with no components compiles to its build output (#4046), so only a target with neither is empty.
+    if (compiled.every((t) => t.components.length === 0 && t.templates.length === 0)) {
+        throw new ReleaseCutError("release-no-components", "no component is enabled in any environment and nothing was compiled, so there is nothing to release", "Enable a component under one environment's parameters, or remove the component files so the project's build output is released.");
+    }
+    const differing = differingBuildSteps(compiled);
+    if (differing.length > 0) {
+        throw new ReleaseCutError("release-build-inputs-differ", `the build steps of ${differing.map((d) => `"${d.component}"`).join(", ")} differ between environments (${[...new Set(differing.flatMap((d) => d.envs))].join(", ")}), ` +
+            "so their artifacts can't be built once for every environment", "Make the build steps read no environment-specific value; pass the value to a deploy step instead.");
+    }
+    // Which environment each component's artifacts are built in: the first one it is enabled in.
+    const firstEnv = new Map();
+    for (const t of compiled)
+        for (const c of t.components)
+            if (!firstEnv.has(c) && (t.buildSteps[c]?.length ?? 0) > 0)
+                firstEnv.set(c, t);
+    // git names paths from its top with symlinks resolved (/private/var on macOS).
+    const realCwd = realpathSync(cwd);
+    const previous = firstEnv.size > 0 ? await previousRelease(top, commit, cwd) : undefined;
+    const reused = [];
+    const artifacts = [];
+    const toBuild = new Map();
+    for (const [component, target] of firstEnv) {
+        const prior = previous?.artifactDigests.filter((a) => a.component === component) ?? [];
+        if (previous && prior.length > 0) {
+            const paths = [target.componentFiles[component], "chant.config.ts", ...(target.buildInputs[component] ?? [])]
+                .filter((p) => typeof p === "string")
+                .map((p) => relative(top, resolve(realCwd, p)))
+                .filter((p) => p !== "" && !p.startsWith(".."));
+            // With no path to compare, the source can't be shown unchanged, so it is built.
+            const changed = paths.length === 0 ? null : tryGit(top, ["diff", "--name-only", previous.commit, commit, "--", ...paths]);
+            if (changed === "") {
+                artifacts.push(...prior);
+                reused.push({ component, from: previous.releaseDigest });
+                continue;
+            }
+        }
+        toBuild.set(target.env, [...(toBuild.get(target.env) ?? []), component]);
+    }
+    for (const env of envs) {
+        const names = toBuild.get(env);
+        if (names)
+            artifacts.push(...(await req.compiler.buildArtifacts(env, names)));
+    }
+    const templates = [];
+    const targets = compiled.map((t) => ({
+        env: t.env,
+        params: t.params,
+        templates: t.templates.map((tpl) => {
+            const digest = contentDigest(tpl.content);
+            templates.push({ digest, content: tpl.content });
+            return { component: tpl.component, path: tpl.path, digest };
+        }),
+    }));
+    const ledger = await resolveMemberLedger(cwd);
+    const release = makeRelease({ member: ledger.members.length > 0 ? ledger.members.join("/") : null, commit, artifactDigests: artifacts, targets });
+    const timestamp = (req.now ?? (() => new Date()))().toISOString();
+    const signed = { releaseDigest: release.releaseDigest, label: req.label, actor: req.actor, timestamp };
+    let signature = null;
+    if (req.sign !== undefined) {
+        const { resolveSigningKey, sealReleaseCut, SealError } = await import("../workspace/trust/seal.js");
+        try {
+            const key = resolveSigningKey(req.sign, cwd);
+            try {
+                signature = sealReleaseCut(key.file, signed).signature;
+            }
+            finally {
+                key.cleanup();
+            }
+        }
+        catch (err) {
+            if (!(err instanceof SealError))
+                throw err;
+            throw new ReleaseCutError("release-signer-refused", `no release was cut: ${err.message}`);
+        }
+    }
+    if (releaseRule.requirement) {
+        const { admitReleaseCut } = await import("../workspace/identity-gate-rule.js");
+        const why = admitReleaseCut(releaseRule.rule, { ...signed, signature });
+        if (why !== null) {
+            throw new ReleaseCutError("release-signer-refused", `no release was cut: ${why}`, `identity.gates.release in chant.workspace.json at base counts only a cut signed by a key ${releaseRule.rule.signers.signersPath} lists for the actor` +
+                (releaseRule.requirement.class !== null ? `, who holds the role of the class ${releaseRule.requirement.class}` : "") +
+                ". Pass --actor <principal> naming that signer.");
+        }
+    }
+    const stored = await persistRelease(release, templates, { cwd });
+    const ci = resolveCiRun(req.env ?? process.env);
+    const outcome = await appendCut({
+        releaseDigest: release.releaseDigest,
+        label: req.label,
+        actor: req.actor,
+        timestamp,
+        runOrigin: ci?.runOrigin ?? null,
+        signature,
+    }, { cwd });
+    return {
+        release,
+        cut: outcome.appended ? outcome.cut : null,
+        label: outcome.appended ? outcome.cut.label : outcome.label,
+        stored: stored.written,
+        reused,
+    };
+}

package/dist/lifecycle/release-ledger.d.ts

@@ -29,6 +29,7 @@
  */
 import { type LegacyDigestFlag } from "./legacy-digest.js";
 import { type LedgerLocation } from "./git.js";
+import type { GateResolutionRecord } from "./gate-ledger.js";
 export { validateReleaseRecord, parseReleaseLedger, releaseLedgerLines, readReleaseRecords, listReleaseEnvironmentsOn } from "./release-read.js";
 export type { LedgerReadPort } from "./ledger-port.js";
 /**
@@ -49,6 +50,35 @@ export interface RunOrigin {
     /** Resolved link to the run, when the environment provided enough to build one. */
     url?: string;
 }
+/**
+ * The gate resolution that admitted a deploy (#4020): the gate's address in the
+ * gate ledger (`_gates/<op>.jsonl`, `op` and `gate`) and when the resolution
+ * was recorded. With `approver` on the same record it names the line a reader
+ * opens to see what was approved. Chant 0.124.28 and newer write it.
+ */
+export interface ReleaseAdmission {
+    /** The op, or for a component gate the component, whose gate ledger holds the resolution. */
+    op: string;
+    /** The gate's name. */
+    gate: string;
+    /** ISO-8601 time the resolution was recorded (`GateResolutionRecord.timestamp`). When several approvals counted, the newest one. */
+    resolvedAt: string;
+}
+/**
+ * The approver and admission a release records for the resolutions of its gate
+ * (#4020): those of `gate` on `op` bound to `planDigest`. The approver is the
+ * distinct `resolvedBy` names, comma joined, as `approver` has always been
+ * written by the release activities; `resolvedAt` is the newest one's time.
+ * Undefined when no resolution is bound to the plan.
+ */
+export declare function admissionOf(resolutions: readonly GateResolutionRecord[], at: {
+    op: string;
+    gate: string;
+    planDigest?: string;
+}): {
+    approver: string;
+    admission: ReleaseAdmission;
+} | undefined;
 /**
  * Points at one earlier release record (#2530, #2531, #2604). A record has no id of its own,
  * so it is named by the environment whose ledger holds it plus the run id and
@@ -118,6 +148,13 @@ export interface ReleaseRecord {
      * the one who triggered the deploy (separation of duties).
      */
     approver?: string;
+    /**
+     * The gate resolution that admitted this deploy (#4020), for a gated change:
+     * which gate (`op` and `gate`) and when it was resolved. The approver is
+     * `approver`. Optional and omitted for an ungated change and for a record
+     * written before 0.124.28, whose gate cannot be recovered from the record.
+     */
+    admission?: ReleaseAdmission;
     /** Optional: the archive's own manifest digest (../components/verbs/build-archive.ts's `manifestDigest`), when the caller has it — lets a reader recover full build contents/provenance, not just the promoted image digest. */
     manifestDigest?: string;
     /**
@@ -167,6 +204,13 @@ export interface ReleaseRecord {
      * partway. Absent on every other record.
      */
     redeploys?: ReleaseRef;
+    /**
+     * Optional: the release this deploy came from (#4026, ws-104), the
+     * `releaseDigest` of `_releases/<releaseDigest>.json`. Written by
+     * `chant components promote --release` since 0.124.28. Absent on every
+     * deploy that was not made from a release.
+     */
+    releaseDigest?: string;
 }
 /** Thrown by `appendReleaseRecord` when the record is missing a required field — a release record can never be recorded partially, since it is never editable afterward. */
 export declare class InvalidReleaseRecordError extends Error {
@@ -200,6 +244,16 @@ export declare function resolveRunId(explicit?: string, env?: NodeJS.ProcessEnv)
     runId: string;
     runOrigin?: RunOrigin;
 };
+/**
+ * The CI run the environment names, with the origin that locates it, or
+ * undefined outside CI (#4020). `resolveRunId` takes its CI branches from
+ * here, and an Op run record takes its `runOrigin` from here, so a run and the
+ * deploy it made name the run the same way.
+ */
+export declare function resolveCiRun(env?: NodeJS.ProcessEnv): {
+    runId: string;
+    runOrigin: RunOrigin;
+} | undefined;
 /**
  * Append one immutable release record to the `<env>` ledger on the
  * `chant/lifecycle` orphan branch. Throws `InvalidReleaseRecordError` before

package/dist/lifecycle/release-ledger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"release-ledger.d.ts","sourceRoot":"","sources":["../../src/lifecycle/release-ledger.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"release-ledger.d.ts","sourceRoot":"","sources":["../../src/lifecycle/release-ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,EAAyC,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC/F,OAAO,EAAwG,KAAK,cAAc,EAAE,MAAM,OAAO,CAAC;AAElJ,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAG1D,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAC9I,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;OAMG;IACH,KAAK,EAAE,QAAQ,GAAG,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC;IAC5C,gHAAgH;IAChH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6FAA6F;IAC7F,EAAE,EAAE,MAAM,CAAC;IACX,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,oIAAoI;IACpI,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,WAAW,EAAE,SAAS,oBAAoB,EAAE,EAC5C,EAAE,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,gBAAgB,CAAA;CAAE,GAAG,SAAS,CAO/D;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,gEAAgE;IAChE,GAAG,EAAE,MAAM,CAAC;IACZ,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,4FAA4F;IAC5F,OAAO,EAAE,CAAC,CAAC;IACX,6FAA6F;IAC7F,SAAS,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;OAOG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,iOAAiO;IACjO,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,gOAAgO;IAChO,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,YAAY,CAAC,EAAE,UAAU,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC3B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,UAAU,CAAC;IACvB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,4KAA4K;AAC5K,qBAAa,yBAA0B,SAAQ,KAAK;aACtB,OAAO,EAAE,MAAM,EAAE;IAA7C,YAA4B,OAAO,EAAE,MAAM,EAAE,EAG5C;CACF;AAED,gIAAgI;AAChI,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,aAAa,EAAE,SAAS,GAAG,OAAO,CAAC,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,CAAC,EAAE,MAAM,EACjB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,CAAA;CAAE,CAQ1C;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,SAAS,CAAA;CAAE,GAAG,SAAS,CAyBtH;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,kBAAkB,EACzB,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,CAAC,CASpD;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,cAAc,GACpB,OAAO,CAAC;IAAE,OAAO,EAAE,aAAa,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAS1D;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAAC,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAEtF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CASvF;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE,CAE1F"}

package/dist/lifecycle/release-ledger.js

@@ -33,6 +33,22 @@ import { appendReleaseRecordLine, readReleaseLedgerLines, listLedgerEnvironments
 import { parseReleaseLedger, validateReleaseRecord } from "./release-read.js";
 // The pure readers live apart, so a bundle can import them without git (#3865).
 export { validateReleaseRecord, parseReleaseLedger, releaseLedgerLines, readReleaseRecords, listReleaseEnvironmentsOn } from "./release-read.js";
+/**
+ * The approver and admission a release records for the resolutions of its gate
+ * (#4020): those of `gate` on `op` bound to `planDigest`. The approver is the
+ * distinct `resolvedBy` names, comma joined, as `approver` has always been
+ * written by the release activities; `resolvedAt` is the newest one's time.
+ * Undefined when no resolution is bound to the plan.
+ */
+export function admissionOf(resolutions, at) {
+    const bound = resolutions.filter((r) => r.gate === at.gate && r.planDigest === at.planDigest);
+    if (bound.length === 0)
+        return undefined;
+    return {
+        approver: [...new Set(bound.map((r) => r.resolvedBy))].join(", "),
+        admission: { op: at.op, gate: at.gate, resolvedAt: bound.map((r) => r.timestamp).sort().at(-1) },
+    };
+}
 /** Thrown by `appendReleaseRecord` when the record is missing a required field — a release record can never be recorded partially, since it is never editable afterward. */
 export class InvalidReleaseRecordError extends Error {
     constructor(missing) {
@@ -63,31 +79,48 @@ export class InvalidReleaseRecordError extends Error {
  * remove.
  */
 export function resolveRunId(explicit, env = process.env) {
-    const githubOrigin = (id) => ({
-        forge: "github",
-        ...(env.GITHUB_REPOSITORY ? { repo: env.GITHUB_REPOSITORY } : {}),
-        ...(env.GITHUB_SERVER_URL && env.GITHUB_REPOSITORY
-            ? { url: `${env.GITHUB_SERVER_URL}/${env.GITHUB_REPOSITORY}/actions/runs/${id}` }
-            : {}),
-    });
-    const gitlabOrigin = () => ({
-        forge: "gitlab",
-        ...(env.CI_PROJECT_PATH ? { repo: env.CI_PROJECT_PATH } : {}),
-        ...(env.CI_PIPELINE_URL ? { url: env.CI_PIPELINE_URL } : {}),
-    });
+    const ci = resolveCiRun(env);
     if (explicit) {
-        if (env.GITHUB_RUN_ID && explicit === env.GITHUB_RUN_ID)
-            return { runId: explicit, runOrigin: githubOrigin(explicit) };
-        if (env.CI_PIPELINE_ID && explicit === env.CI_PIPELINE_ID)
-            return { runId: explicit, runOrigin: gitlabOrigin() };
+        if (ci && explicit === ci.runId)
+            return ci;
         return { runId: explicit };
     }
-    if (env.GITHUB_RUN_ID)
-        return { runId: env.GITHUB_RUN_ID, runOrigin: githubOrigin(env.GITHUB_RUN_ID) };
-    if (env.CI_PIPELINE_ID)
-        return { runId: env.CI_PIPELINE_ID, runOrigin: gitlabOrigin() };
+    if (ci)
+        return ci;
     return { runId: `local-${Date.now()}`, runOrigin: { forge: "local" } };
 }
+/**
+ * The CI run the environment names, with the origin that locates it, or
+ * undefined outside CI (#4020). `resolveRunId` takes its CI branches from
+ * here, and an Op run record takes its `runOrigin` from here, so a run and the
+ * deploy it made name the run the same way.
+ */
+export function resolveCiRun(env = process.env) {
+    if (env.GITHUB_RUN_ID) {
+        const id = env.GITHUB_RUN_ID;
+        return {
+            runId: id,
+            runOrigin: {
+                forge: "github",
+                ...(env.GITHUB_REPOSITORY ? { repo: env.GITHUB_REPOSITORY } : {}),
+                ...(env.GITHUB_SERVER_URL && env.GITHUB_REPOSITORY
+                    ? { url: `${env.GITHUB_SERVER_URL}/${env.GITHUB_REPOSITORY}/actions/runs/${id}` }
+                    : {}),
+            },
+        };
+    }
+    if (env.CI_PIPELINE_ID) {
+        return {
+            runId: env.CI_PIPELINE_ID,
+            runOrigin: {
+                forge: "gitlab",
+                ...(env.CI_PROJECT_PATH ? { repo: env.CI_PROJECT_PATH } : {}),
+                ...(env.CI_PIPELINE_URL ? { url: env.CI_PIPELINE_URL } : {}),
+            },
+        };
+    }
+    return undefined;
+}
 /**
  * Append one immutable release record to the `<env>` ledger on the
  * `chant/lifecycle` orphan branch. Throws `InvalidReleaseRecordError` before