@patronage/factory-ci 1.0.0-alpha.21 → 1.0.0-alpha.22

package/dist/index.js

@@ -519,6 +519,22 @@ const FACTORY_PROOF_GATE_GUARD = `steps.${FACTORY_PROOF_GATE_STEP_ID}.outputs.${
 */
 const FACTORY_PROOF_GATE_IF = "github.event_name == 'pull_request' || (github.event_name == 'push' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch))";
 /**
+* Pull requests only — the condition a consumer gets with
+* `reuse: "pull-request"` (#873).
+*
+* A repository may want its default-branch pushes to always execute the full
+* hosted suite, whatever proof exists: the merged commit is what the fleet
+* deploys, so a periodic unconditional run of every command is a deliberate
+* cost some consumers choose to pay. This condition is that choice, expressed
+* once here rather than as a consumer-written override string. The mode also
+* skips the push-event merge fallback, so no push path can reuse proof even if
+* the workflow reaches the step through some other trigger.
+*
+* Which branches trigger the workflow at all stays repository-owned. This
+* condition only keeps the gate from consulting proof outside a pull request.
+*/
+const FACTORY_PROOF_GATE_PULL_REQUEST_IF = "github.event_name == 'pull_request'";
+/**
 * The complete refusal vocabulary. Deliberately few, because these are the
 * only distinctions the gate can honestly make from its Checks API reads.
 * The merge fallback adds no words: a fallback that establishes nothing
@@ -814,7 +830,92 @@ const safeLabel$1 = (surface) => {
 	const cleaned = (typeof surface === "string" ? surface : "").replaceAll(/[^\w -]/gu, "").trim().slice(0, 60);
 	return cleaned.length > 0 ? cleaned : "verification";
 };
-const gateScript = (required, surface) => String.raw`
+/**
+* The push-event merge fallback (#611), emitted only for the default reuse
+* mode. `reuse: "pull-request"` omits it: that mode's whole point is that a
+* default-branch push executes everything, so a push path that could still
+* reuse proof would contradict the condition above it.
+*/
+const MERGE_FALLBACK_BLOCK = String.raw`# Merge fallback (#611). A squash merge mints a new commit, so the direct
+# read at a pushed merge-target head finds nothing even when the factory
+# proved the producing pull request head. Only when the direct read found no
+# generation at all on a push event, look up the producing pull request and
+# reuse its head proof — and only when the merge commit's TREE id equals the
+# proven head's tree id, which makes the pushed content byte-identical to
+# what was verified (a clean squash of an unchanged tip). Patch identity was
+# considered and rejected as the comparator: git patch-id normalizes
+# whitespace and ignores base motion, so an identical patch can still
+# produce an integrated tree that was never tested. Everything else — no
+# unique merged producing PR, an unreadable commit, a proof that is anything
+# but proven, or tree drift from a dirty or stale merge — leaves the direct
+# "none" refusal standing, so the full suite runs (fail open).
+if [ "$reason" = 'none' ] && [ "${shellExpansion$1("GITHUB_EVENT_NAME:-")}" = 'push' ]; then
+  producing_head=''
+  merge_tree=''
+  head_tree=''
+  if ! producing_pulls=$(gh api --method GET --paginate \
+      "repos/$GITHUB_REPOSITORY/commits/$HEAD_SHA/pulls" \
+      -f per_page=100 2>&1); then
+    detail="producing pull request unreadable: $producing_pulls"
+  elif ! producing_head=$(printf '%s' "$producing_pulls" | jq -r -s \
+      --arg sha "$HEAD_SHA" \
+      '[ add[]?
+         | select((.merged_at // null) != null)
+         | select((.merge_commit_sha // "") == $sha)
+         | ((.head.sha // "") | tostring) ]
+       | if length == 1 then .[0] else "" end' 2>&1); then
+    detail="producing pull request unreadable: $producing_head"
+    producing_head=''
+  elif ! [[ "$producing_head" =~ ^[0-9a-f]{40}$ ]]; then
+    detail='no single merged producing pull request at this commit'
+    producing_head=''
+  elif ! merge_commit=$(gh api --method GET \
+      "repos/$GITHUB_REPOSITORY/commits/$HEAD_SHA" 2>&1); then
+    detail="merge commit unreadable: $merge_commit"
+  elif ! merge_tree=$(printf '%s' "$merge_commit" | jq -r \
+      '(.commit.tree.sha // "") | tostring' 2>&1); then
+    detail="merge commit unreadable: $merge_tree"
+    merge_tree=''
+  elif ! [[ "$merge_tree" =~ ^[0-9a-f]{40}$ ]]; then
+    detail='merge commit carries no readable tree id'
+    merge_tree=''
+  elif ! head_commit=$(gh api --method GET \
+      "repos/$GITHUB_REPOSITORY/commits/$producing_head" 2>&1); then
+    detail="producing head commit unreadable: $head_commit"
+  elif ! head_tree=$(printf '%s' "$head_commit" | jq -r \
+      '(.commit.tree.sha // "") | tostring' 2>&1); then
+    detail="producing head commit unreadable: $head_tree"
+    head_tree=''
+  elif ! [[ "$head_tree" =~ ^[0-9a-f]{40}$ ]]; then
+    detail='producing head commit carries no readable tree id'
+    head_tree=''
+  elif [ "$merge_tree" != "$head_tree" ]; then
+    detail='tree drift: the merge result is not the proven head tree'
+    merge_tree=''
+  fi
+  if [[ "$producing_head" =~ ^[0-9a-f]{40}$ ]] \
+      && [[ "$merge_tree" =~ ^[0-9a-f]{40}$ ]] \
+      && [ "$merge_tree" = "$head_tree" ]; then
+    gate_lookup "$producing_head"
+    if [ "$lookup_reason" = 'proven' ]; then
+      reason=proven
+      mode="$lookup_mode"
+      missing=''
+      source_url="$lookup_url"
+      proof_head="$producing_head"
+      merge_note="the merge result's tree is byte-identical to the tree proven at pull request head $producing_head"
+    else
+      detail="producing pull request proof not reusable ($lookup_reason)"
+    fi
+  fi
+fi`;
+/**
+* The fallback with the blank lines that surround it, or nothing at all. Kept
+* as one piece so the default mode emits the exact script it emitted before
+* this option existed.
+*/
+const mergeFallbackSection = (reuse) => reuse === "pull-request" ? "\n" : `\n${MERGE_FALLBACK_BLOCK}\n\n`;
+const gateScript = (required, surface, reuse) => String.raw`
 set -uo pipefail
 
 CHECK_NAME=${shellSingleQuote(FACTORY_PROOF_GATE_CHECK_NAME)}
@@ -901,82 +1002,7 @@ else
   missing="$lookup_missing"
   source_url="$lookup_url"
 fi
-
-# Merge fallback (#611). A squash merge mints a new commit, so the direct
-# read at a pushed merge-target head finds nothing even when the factory
-# proved the producing pull request head. Only when the direct read found no
-# generation at all on a push event, look up the producing pull request and
-# reuse its head proof — and only when the merge commit's TREE id equals the
-# proven head's tree id, which makes the pushed content byte-identical to
-# what was verified (a clean squash of an unchanged tip). Patch identity was
-# considered and rejected as the comparator: git patch-id normalizes
-# whitespace and ignores base motion, so an identical patch can still
-# produce an integrated tree that was never tested. Everything else — no
-# unique merged producing PR, an unreadable commit, a proof that is anything
-# but proven, or tree drift from a dirty or stale merge — leaves the direct
-# "none" refusal standing, so the full suite runs (fail open).
-if [ "$reason" = 'none' ] && [ "${shellExpansion$1("GITHUB_EVENT_NAME:-")}" = 'push' ]; then
-  producing_head=''
-  merge_tree=''
-  head_tree=''
-  if ! producing_pulls=$(gh api --method GET --paginate \
-      "repos/$GITHUB_REPOSITORY/commits/$HEAD_SHA/pulls" \
-      -f per_page=100 2>&1); then
-    detail="producing pull request unreadable: $producing_pulls"
-  elif ! producing_head=$(printf '%s' "$producing_pulls" | jq -r -s \
-      --arg sha "$HEAD_SHA" \
-      '[ add[]?
-         | select((.merged_at // null) != null)
-         | select((.merge_commit_sha // "") == $sha)
-         | ((.head.sha // "") | tostring) ]
-       | if length == 1 then .[0] else "" end' 2>&1); then
-    detail="producing pull request unreadable: $producing_head"
-    producing_head=''
-  elif ! [[ "$producing_head" =~ ^[0-9a-f]{40}$ ]]; then
-    detail='no single merged producing pull request at this commit'
-    producing_head=''
-  elif ! merge_commit=$(gh api --method GET \
-      "repos/$GITHUB_REPOSITORY/commits/$HEAD_SHA" 2>&1); then
-    detail="merge commit unreadable: $merge_commit"
-  elif ! merge_tree=$(printf '%s' "$merge_commit" | jq -r \
-      '(.commit.tree.sha // "") | tostring' 2>&1); then
-    detail="merge commit unreadable: $merge_tree"
-    merge_tree=''
-  elif ! [[ "$merge_tree" =~ ^[0-9a-f]{40}$ ]]; then
-    detail='merge commit carries no readable tree id'
-    merge_tree=''
-  elif ! head_commit=$(gh api --method GET \
-      "repos/$GITHUB_REPOSITORY/commits/$producing_head" 2>&1); then
-    detail="producing head commit unreadable: $head_commit"
-  elif ! head_tree=$(printf '%s' "$head_commit" | jq -r \
-      '(.commit.tree.sha // "") | tostring' 2>&1); then
-    detail="producing head commit unreadable: $head_tree"
-    head_tree=''
-  elif ! [[ "$head_tree" =~ ^[0-9a-f]{40}$ ]]; then
-    detail='producing head commit carries no readable tree id'
-    head_tree=''
-  elif [ "$merge_tree" != "$head_tree" ]; then
-    detail='tree drift: the merge result is not the proven head tree'
-    merge_tree=''
-  fi
-  if [[ "$producing_head" =~ ^[0-9a-f]{40}$ ]] \
-      && [[ "$merge_tree" =~ ^[0-9a-f]{40}$ ]] \
-      && [ "$merge_tree" = "$head_tree" ]; then
-    gate_lookup "$producing_head"
-    if [ "$lookup_reason" = 'proven' ]; then
-      reason=proven
-      mode="$lookup_mode"
-      missing=''
-      source_url="$lookup_url"
-      proof_head="$producing_head"
-      merge_note="the merge result's tree is byte-identical to the tree proven at pull request head $producing_head"
-    else
-      detail="producing pull request proof not reusable ($lookup_reason)"
-    fi
-  fi
-fi
-
-# The binding is App-verified, but it still reaches markdown. Only a plain
+${mergeFallbackSection(reuse)}# The binding is App-verified, but it still reaches markdown. Only a plain
 # lowercase token is quoted back; anything else is reported as unknown.
 case "$mode" in
   '') ;;
@@ -1099,9 +1125,9 @@ fi
 * `FACTORY_PROOF_GATE_SHELL` — so the script is also written to reach that
 * write under errexit, and the tests execute it both ways.
 */
-const factoryProofGateScript = ({ commands, surface }) => {
+const factoryProofGateScript = ({ commands, reuse = "pull-request-and-default-branch", surface }) => {
 	const required = proofReuseRequiredCommands(commands);
-	return required ? gateScript(required, safeLabel$1(surface)) : UNUSABLE_SELECTION_SCRIPT;
+	return required ? gateScript(required, safeLabel$1(surface), reuse) : UNUSABLE_SELECTION_SCRIPT;
 };
 /**
 * The step itself, structurally accepted by gagen's `step()` without adding a
@@ -1111,7 +1137,9 @@ const factoryProofGateScript = ({ commands, surface }) => {
 * `checks: read`; the push-event merge fallback additionally reads the
 * producing pull request (`pull-requests: read`) and the two commit objects
 * whose tree ids it compares (`contents: read`). A job that grants less
-* loses only the fallback — the failed read degrades to the full suite.
+* loses only the fallback — the failed read degrades to the full suite. A
+* consumer that passes `reuse: "pull-request"` emits neither the push clause
+* nor the fallback, and needs only `checks: read` (#873).
 *
 * A **step, not a job**, and that is not a style preference. A separate gate
 * job that errored would leave the guarded job `skipped`, and a summary job
@@ -1127,7 +1155,7 @@ const factoryProofGateStep = (options) => Object.freeze({
 		HEAD_SHA: githubExpression$1("github.event.pull_request.head.sha || github.sha")
 	}),
 	id: FACTORY_PROOF_GATE_STEP_ID,
-	if: FACTORY_PROOF_GATE_IF,
+	if: options.reuse === "pull-request" ? FACTORY_PROOF_GATE_PULL_REQUEST_IF : FACTORY_PROOF_GATE_IF,
 	name: FACTORY_PROOF_GATE_STEP_NAME,
 	run: factoryProofGateScript(options),
 	shell: FACTORY_PROOF_GATE_SHELL
@@ -1185,6 +1213,20 @@ const assertProofReuseCoverage = (input) => {
 */
 /** Check-run name that carries one registration JSON payload. Not a gate. */
 const PREVIEW_PROOF_INVENTORY_CHECK_NAME = "patronage-factory/preview-proof";
+/**
+* Least privilege for a job whose `GITHUB_TOKEN` calls `list`. A
+* `permissions` block zeroes every unlisted scope, and `list` reads five
+* endpoints: `pulls/{pr}`, `pulls/{pr}/commits`, and the GraphQL force-push
+* timeline (`pull-requests`), `compare` (`contents`), and
+* `commits/{sha}/check-runs` (`checks`). A job
+* that omits `pull-requests: read` fails with 403 on a same-repository PR
+* and skips every destroy matrix (#859). Give the discovery job this object.
+*/
+const PREVIEW_PROOF_INVENTORY_LIST_PERMISSIONS = Object.freeze({
+	checks: "read",
+	contents: "read",
+	"pull-requests": "read"
+});
 const INVENTORY_KIND = "patronage-factory-preview-proof";
 const INVENTORY_SCHEMA_VERSION = 1;
 const DEFAULT_TIMEOUT_MS = 5e3;
@@ -1311,6 +1353,7 @@ const assertPersistableRegistration = (registration) => {
 const registrationKey = (row) => `${row.stack}:${row.stage}`;
 const replaceRegistration = (rows, next) => [...rows.filter((row) => registrationKey(row) !== registrationKey(next)), next];
 const memoryKey = (owner, repo, pr) => `${owner}/${repo}#${pr}`;
+/** Reached by callers as `previewProofInventory.memoryStore`. */
 const memoryStore = () => {
 	const byPr = /* @__PURE__ */ new Map();
 	return {
@@ -1601,6 +1644,7 @@ const takeNewestRegistrations = (runsBySha, pr) => {
 	}
 	return [...byKey.values()];
 };
+/** Reached by callers as `previewProofInventory.githubStore`. */
 const githubStore = (transport) => {
 	const request = transport.fetch ?? fetch;
 	const timeoutMs = transport.timeoutMs ?? DEFAULT_TIMEOUT_MS;
@@ -1695,6 +1739,7 @@ const recordCleanup = async (input, access) => {
 const previewProofInventory = {
 	githubStore,
 	list,
+	listPermissions: PREVIEW_PROOF_INVENTORY_LIST_PERMISSIONS,
 	memoryStore,
 	persist,
 	recordCleanup
@@ -2106,6 +2151,173 @@ const factoryLifecycleContractLane = (declaration) => {
 	});
 };
 //#endregion
+//#region src/merge-freeze-job.ts
+/**
+* The merge-freeze writer job (#356, ADR 0016 as amended; #429 for the
+* merge-target namespace; #872 for this package).
+*
+* A consumer's generated merge-target-push Verify workflow is the ONLY
+* producer of `patronage-factory/merge-freeze` generations: a red
+* push-triggered Verify completes a generation active, a green one completes
+* it inactive, and no command, scheduled job, or second workflow writes this
+* check run. The operator override (`demand:waive --demand merge-freeze`)
+* waives the demand for one candidate during a fix-forward; it never writes
+* here.
+*
+* The write mirrors what the factory package's merge-freeze reader parses:
+* create the run `in_progress` with no `started_at` (GitHub stamps the
+* generation clock — the ordering rule itself is owned by the reader), then
+* PATCH it completed with the reader-shaped state payload in `output.text`.
+* The consumer's workflow test executes this exact script against a stubbed
+* `gh` and parses the emitted payload with `validateMergeFreezeState`, so
+* writer and reader cannot drift silently.
+*
+* Failure posture is deliberately fail-closed and the opposite of the
+* proof-reuse gate's fail-open shell: this step runs under the runner's
+* default `bash -e {0}`, so any API refusal aborts the step, the generation
+* stays absent or `in_progress`, and every `pr:ready` arming-time read of
+* that tip (#477) refuses until a later push writes a green generation.
+*
+* **Ownership line.** This package owns the check name, the App identity, the
+* `create-github-app-token` inputs, the result fold, the merge-target `if`,
+* and the job's `permissions`. The caller owns the runner, the `needs` list
+* of every authoritative verification leaf, the timeout, and any extra env.
+*/
+/** The one check-run name every merge-freeze reader pins. */
+const FACTORY_MERGE_FREEZE_CHECK_NAME = "patronage-factory/merge-freeze";
+const FACTORY_MERGE_FREEZE_JOB_ID = "freeze";
+const FACTORY_MERGE_FREEZE_JOB_NAME = "Report the merge freeze";
+/** Step id the token step exposes its installation token under. */
+const FACTORY_MERGE_FREEZE_APP_TOKEN_STEP_ID = "factory-app-token";
+/**
+* The GitHub Actions expression that folds the needed jobs' results into the
+* one word the script branches on. It mirrors the `verify` summary job's
+* failure condition exactly: any failed or cancelled needed job is a red
+* merge target.
+*/
+const FACTORY_MERGE_FREEZE_VERIFY_RESULT_EXPRESSION = `\${{ (contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')) && 'failure' || 'success' }}`;
+/**
+* The literal factory merge-target namespace, as a `github.ref` predicate
+* (#429).
+*
+* `main` plus the repository-owned `epic/**` integration branches, and
+* nothing else. Deliberately literal rather than profile-declared: one
+* implementation per contract, no configuration machinery for a two-element
+* namespace whose second element is a namespace prefix the repository itself
+* owns. `epic/` needs the trailing slash — `startsWith` would otherwise admit
+* `epicness/…`, which is not a merge target.
+*
+* A caller's `push` trigger branch list names the same namespace. That list
+* decides which events produce a run at all; this predicate decides which of
+* those runs may write a generation.
+*/
+const FACTORY_MERGE_TARGET_REF_CONDITION = ["github.ref == 'refs/heads/main'", "startsWith(github.ref, 'refs/heads/epic/')"].join(" || ");
+/**
+* `always()` is load-bearing: the red path is the whole point, so the job must
+* run when a needed verification job failed. `github.event_name == 'push'` is
+* load-bearing twice over: a `pull_request` run must never write a generation
+* (its `github.sha` is a synthetic merge commit that no base tip is ever read
+* at), and a `pull_request` trigger with an `epic/**` base list would
+* otherwise reach this job.
+*/
+const FACTORY_MERGE_FREEZE_IF = `always() && github.event_name == 'push' && (${FACTORY_MERGE_TARGET_REF_CONDITION})`;
+/**
+* Least privilege for the writer job: no `GITHUB_TOKEN` scope at all.
+*
+* Both Checks API calls run under the App installation token minted in the
+* first step (`GH_TOKEN: steps.factory-app-token.outputs.token`), and the job
+* never checks out the repository. So the job uses no `GITHUB_TOKEN` scope,
+* and an empty block is the honest declaration. A `checks: write` here would
+* hand every adopter an unused write scope (#884).
+*/
+const FACTORY_MERGE_FREEZE_PERMISSIONS = Object.freeze({});
+/**
+* The script the freeze step runs. Environment contract:
+* - `GH_TOKEN`: an installation token for the pinned Patronage Factory App —
+*   the check run must carry that App's identity or every reader rejects it.
+* - `VERIFY_RESULT`: `success` or `failure` (see the fold expression above).
+* - `GITHUB_SHA` / `GITHUB_REPOSITORY` / `GITHUB_SERVER_URL` /
+*   `GITHUB_RUN_ID` / `GITHUB_REF_NAME`: runner-provided.
+*
+* `GITHUB_REF_NAME` is the merge target this run pushed to — `main` or an
+* `epic/**` integration branch (#429). The job is gated to `push` events on
+* exactly those refs, so the branch name is always the short name of a
+* repository-owned merge target and never a pull-request merge ref. It
+* appears in both recovery sentences because a reader of an epic-targeting
+* candidate must be told which branch to fix forward on: the generation lives
+* on that branch's tip, and only a later green push to THAT branch clears it.
+*/
+const factoryMergeFreezeScript = () => [
+	`sha="$GITHUB_SHA"`,
+	`branch="$GITHUB_REF_NAME"`,
+	`repo="$GITHUB_REPOSITORY"`,
+	`run_url="$GITHUB_SERVER_URL/$repo/actions/runs/$GITHUB_RUN_ID"`,
+	`created=$(gh api --method POST "repos/$repo/check-runs" \\`,
+	`  -f "name=${FACTORY_MERGE_FREEZE_CHECK_NAME}" \\`,
+	`  -f "head_sha=$sha" \\`,
+	`  -f "status=in_progress" \\`,
+	`  -f "details_url=$run_url" \\`,
+	`  -f "output[title]=merge freeze generation in progress" \\`,
+	`  -f "output[summary]=This generation blocks factory merge handoffs until the merge-target Verify result is recorded.")`,
+	`id=$(jq -r '.id' <<<"$created")`,
+	`case "$id" in`,
+	`  ''|*[!0-9]*) echo "unusable check-run id: $id" >&2; exit 1;;`,
+	`esac`,
+	`if [ "$VERIFY_RESULT" = 'success' ]; then`,
+	`  active=false; outcome=inactive; conclusion=success`,
+	`  reason="Merge-target Verify passed on $branch at $sha ($run_url)."`,
+	`else`,
+	`  active=true; outcome=active; conclusion=failure`,
+	`  reason="Merge-target Verify failed on $branch at $sha; fix forward or revert on $branch and let the next green Verify push on $branch clear this freeze ($run_url)."`,
+	`fi`,
+	`state=$(jq -cn --argjson active "$active" --argjson id "$id" --arg headSha "$sha" --arg outcome "$outcome" --arg reason "$reason" \\`,
+	`  '{active: $active, generationId: $id, headSha: $headSha, outcome: $outcome, reason: $reason, recordedAt: (now | todate), schemaVersion: 1}')`,
+	`gh api --method PATCH "repos/$repo/check-runs/$id" \\`,
+	`  -f "status=completed" \\`,
+	`  -f "conclusion=$conclusion" \\`,
+	`  -f "details_url=$run_url" \\`,
+	`  -f "output[title]=merge freeze $outcome" \\`,
+	`  -f "output[summary]=$reason" \\`,
+	`  -f "output[text]=$state" >/dev/null`,
+	`echo "merge-freeze generation $id completed $outcome on $branch at $sha"`
+].join("\n");
+/**
+* Build the merge-freeze writer job.
+*
+* An empty `needs` list is refused: a fold over no verification leaf is
+* always `success`, so such a job would write a green generation for a merge
+* target nothing verified — the exact failure the freeze exists to prevent.
+*/
+const factoryMergeFreezeJob = (options) => {
+	assertPinnedAction("createGithubAppToken", options.createGithubAppToken, "actions/create-github-app-token");
+	if (options.needs.length === 0) throw new Error("factoryMergeFreezeJob needs at least one verification job: a fold over no needed job always reports success, so the freeze would report a merge target nothing verified as green.");
+	const mintStep = Object.freeze({
+		id: FACTORY_MERGE_FREEZE_APP_TOKEN_STEP_ID,
+		name: "Mint the factory App token",
+		uses: options.createGithubAppToken.uses,
+		with: Object.freeze({
+			"client-id": FACTORY_PROOF_GATE_APP_ID,
+			"private-key": `\${{ secrets.FACTORY_GITHUB_APP_PRIVATE_KEY }}`
+		})
+	});
+	const reportStep = Object.freeze({
+		env: Object.freeze({
+			GH_TOKEN: `\${{ steps.${FACTORY_MERGE_FREEZE_APP_TOKEN_STEP_ID}.outputs.token }}`,
+			VERIFY_RESULT: options.verifyResultExpression ?? FACTORY_MERGE_FREEZE_VERIFY_RESULT_EXPRESSION
+		}),
+		name: "Complete the merge-freeze generation",
+		run: factoryMergeFreezeScript()
+	});
+	return Object.freeze({
+		if: FACTORY_MERGE_FREEZE_IF,
+		jobId: FACTORY_MERGE_FREEZE_JOB_ID,
+		jobName: FACTORY_MERGE_FREEZE_JOB_NAME,
+		needs: Object.freeze([...options.needs]),
+		permissions: FACTORY_MERGE_FREEZE_PERMISSIONS,
+		steps: Object.freeze([mintStep, reportStep])
+	});
+};
+//#endregion
 //#region src/pr-status-hud-workflow.ts
 const FACTORY_PR_STATUS_HUD_JOB_ID = "status-hud";
 const FACTORY_PR_STATUS_HUD_JOB_NAME = "Present PR status HUD";
@@ -2118,15 +2330,11 @@ const FACTORY_PR_STATUS_HUD_PLAN_PATH = ".factory-memory/preview-plan.json";
 */
 const FACTORY_PR_STATUS_HUD_IF = "always() && github.event_name == 'pull_request' && github.event.pull_request.draft != true";
 /**
-* Least privilege for the job that runs the present step. A `permissions`
-* block zeroes every unlisted GITHUB_TOKEN scope, and the inventory list
-* reads pull requests, commits, and check-runs with that token (#825).
+* Least privilege for the job that runs the present step. The present step
+* is an inventory `list`, so the job needs exactly the inventory's read
+* permissions (#825, #859).
 */
-const FACTORY_PR_STATUS_HUD_PERMISSIONS = Object.freeze({
-	checks: "read",
-	contents: "read",
-	"pull-requests": "read"
-});
+const FACTORY_PR_STATUS_HUD_PERMISSIONS = PREVIEW_PROOF_INVENTORY_LIST_PERMISSIONS;
 const FACTORY_PR_STATUS_HUD_CONCURRENCY = Object.freeze({
 	cancelInProgress: false,
 	group: `status-hud-\${{ github.repository }}-\${{ github.event.pull_request.number }}`
@@ -2221,6 +2429,11 @@ const factoryPreviewCleanupTopology = (options) => {
 //#endregion
 //#region src/push-identity-workflow.ts
 const FACTORY_PUSH_IDENTITY_SCHEMA_VERSION = 1;
+/**
+* The artifact prefix and the five step IDs are module-private. Alpha.13
+* removed them from the public surface (#719). A caller reads a step ID from
+* the builder's returned `steps` (`step.id`) or from `artifactName`.
+*/
 const FACTORY_PUSH_IDENTITY_ARTIFACT_PREFIX = "factory-push-identity";
 const FACTORY_PUSH_IDENTITY_RECORD_STEP_ID = "factory_push_identity_record";
 const FACTORY_PUSH_IDENTITY_LOOKUP_STEP_ID = "factory_push_identity_lookup";
@@ -3286,4 +3499,4 @@ const assertWorkflowShellParses = (yaml, options) => {
 	throw new Error(`${options.source} emits shell bash cannot parse; the runner would treat it as a no-op:\n${detail}`);
 };
 //#endregion
-export { EXECUTE_ALCHEMY_ENTRY_MAX_BUFFER, FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT, FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT, FACTORY_CANDIDATE_IMPACT_INERT_OUTPUT, FACTORY_CANDIDATE_IMPACT_STEP_ID, FACTORY_CANDIDATE_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_CANDIDATE_PULL_REQUEST_TYPES, FACTORY_LIFECYCLE_CONTRACT_JOB_ID, FACTORY_LIFECYCLE_CONTRACT_JOB_NAME, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_ID, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_NAME, FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT, FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT, FACTORY_PRODUCTION_IMPACT_STEP_ID, FACTORY_PRODUCTION_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_PROOF_GATE_APP_ID, FACTORY_PROOF_GATE_CHECK_NAME, FACTORY_PROOF_GATE_GUARD, FACTORY_PROOF_GATE_IF, FACTORY_PROOF_GATE_MODE_OUTPUT, FACTORY_PROOF_GATE_OUTPUT, FACTORY_PROOF_GATE_REASONS, FACTORY_PROOF_GATE_REASON_OUTPUT, FACTORY_PROOF_GATE_SHELL, FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT, FACTORY_PROOF_GATE_STEP_ID, FACTORY_PROOF_GATE_STEP_NAME, FACTORY_PR_STATUS_HUD_APP_TOKEN_STEP_ID, FACTORY_PR_STATUS_HUD_CONCURRENCY, FACTORY_PR_STATUS_HUD_IF, FACTORY_PR_STATUS_HUD_JOB_ID, FACTORY_PR_STATUS_HUD_JOB_NAME, FACTORY_PR_STATUS_HUD_PERMISSIONS, FACTORY_PR_STATUS_HUD_PLAN_PATH, FACTORY_PUSH_IDENTITY_SCHEMA_VERSION, GitHubApiError, NODE_PNPM_ACTION_FAMILY_NODE24, PREVIEW_PROOF_INVENTORY_CHECK_NAME, PreviewProofTransportError, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, VitestProfileError, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryCandidateImpactWorkflow, factoryCandidateOrPushCondition, factoryLifecycleContractLane, factoryPrStatusHudWorkflow, factoryPreviewCleanupTopology, factoryProductionImpactWorkflow, factoryProofGateScript, factoryProofGateStep, factoryProofReuseSummaryStep, factoryProofTimingStartStep, factoryPushIdentityConsumer, factoryPushIdentityProducer, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, previewCleanupDestroyJobId, previewProofInventory, previewProofLifecycle, productionImpactTargetOutput, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };
+export { EXECUTE_ALCHEMY_ENTRY_MAX_BUFFER, FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT, FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT, FACTORY_CANDIDATE_IMPACT_INERT_OUTPUT, FACTORY_CANDIDATE_IMPACT_STEP_ID, FACTORY_CANDIDATE_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_CANDIDATE_PULL_REQUEST_TYPES, FACTORY_LIFECYCLE_CONTRACT_JOB_ID, FACTORY_LIFECYCLE_CONTRACT_JOB_NAME, FACTORY_MERGE_FREEZE_APP_TOKEN_STEP_ID, FACTORY_MERGE_FREEZE_CHECK_NAME, FACTORY_MERGE_FREEZE_IF, FACTORY_MERGE_FREEZE_JOB_ID, FACTORY_MERGE_FREEZE_JOB_NAME, FACTORY_MERGE_FREEZE_PERMISSIONS, FACTORY_MERGE_FREEZE_VERIFY_RESULT_EXPRESSION, FACTORY_MERGE_TARGET_REF_CONDITION, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_ID, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_NAME, FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT, FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT, FACTORY_PRODUCTION_IMPACT_STEP_ID, FACTORY_PRODUCTION_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_PROOF_GATE_APP_ID, FACTORY_PROOF_GATE_CHECK_NAME, FACTORY_PROOF_GATE_GUARD, FACTORY_PROOF_GATE_IF, FACTORY_PROOF_GATE_MODE_OUTPUT, FACTORY_PROOF_GATE_OUTPUT, FACTORY_PROOF_GATE_PULL_REQUEST_IF, FACTORY_PROOF_GATE_REASONS, FACTORY_PROOF_GATE_REASON_OUTPUT, FACTORY_PROOF_GATE_SHELL, FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT, FACTORY_PROOF_GATE_STEP_ID, FACTORY_PROOF_GATE_STEP_NAME, FACTORY_PR_STATUS_HUD_APP_TOKEN_STEP_ID, FACTORY_PR_STATUS_HUD_CONCURRENCY, FACTORY_PR_STATUS_HUD_IF, FACTORY_PR_STATUS_HUD_JOB_ID, FACTORY_PR_STATUS_HUD_JOB_NAME, FACTORY_PR_STATUS_HUD_PERMISSIONS, FACTORY_PR_STATUS_HUD_PLAN_PATH, FACTORY_PUSH_IDENTITY_SCHEMA_VERSION, GitHubApiError, NODE_PNPM_ACTION_FAMILY_NODE24, PREVIEW_PROOF_INVENTORY_CHECK_NAME, PREVIEW_PROOF_INVENTORY_LIST_PERMISSIONS, PreviewProofTransportError, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, VitestProfileError, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryCandidateImpactWorkflow, factoryCandidateOrPushCondition, factoryLifecycleContractLane, factoryMergeFreezeJob, factoryMergeFreezeScript, factoryPrStatusHudWorkflow, factoryPreviewCleanupTopology, factoryProductionImpactWorkflow, factoryProofGateScript, factoryProofGateStep, factoryProofReuseSummaryStep, factoryProofTimingStartStep, factoryPushIdentityConsumer, factoryPushIdentityProducer, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, previewCleanupDestroyJobId, previewProofInventory, previewProofLifecycle, productionImpactTargetOutput, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patronage/factory-ci",
-  "version": "1.0.0-alpha.21",
+  "version": "1.0.0-alpha.22",
   "description": "Deep CI and deploy building blocks for Patronage factory projects: workflow source artifacts, hosted diff classification, Alchemy entry execution, and disposable-stage semantics",
   "keywords": [
     "alchemy",

package/src/index.ts

@@ -43,6 +43,7 @@ export {
 } from "./preview-proof-lifecycle.ts";
 export {
   PREVIEW_PROOF_INVENTORY_CHECK_NAME,
+  PREVIEW_PROOF_INVENTORY_LIST_PERMISSIONS,
   previewProofInventory,
   type PreviewProofInventoryAccess,
   type PreviewProofInventoryCleanupInput,
@@ -83,6 +84,7 @@ export {
   FACTORY_PROOF_GATE_IF,
   FACTORY_PROOF_GATE_MODE_OUTPUT,
   FACTORY_PROOF_GATE_OUTPUT,
+  FACTORY_PROOF_GATE_PULL_REQUEST_IF,
   FACTORY_PROOF_GATE_REASON_OUTPUT,
   FACTORY_PROOF_GATE_REASONS,
   FACTORY_PROOF_GATE_SHELL,
@@ -91,6 +93,7 @@ export {
   FACTORY_PROOF_GATE_STEP_NAME,
   type FactoryProofGateOptions,
   type FactoryProofGateReason,
+  type FactoryProofGateReuse,
   factoryProofGateScript,
   type FactoryProofGateStep,
   factoryProofGateStep,
@@ -125,6 +128,20 @@ export {
   type FactoryLifecycleContractLaneOptions,
   factoryLifecycleContractLane,
 } from "./lifecycle-contract-lane.ts";
+export {
+  FACTORY_MERGE_FREEZE_APP_TOKEN_STEP_ID,
+  FACTORY_MERGE_FREEZE_CHECK_NAME,
+  FACTORY_MERGE_FREEZE_IF,
+  FACTORY_MERGE_FREEZE_JOB_ID,
+  FACTORY_MERGE_FREEZE_JOB_NAME,
+  FACTORY_MERGE_FREEZE_PERMISSIONS,
+  FACTORY_MERGE_FREEZE_VERIFY_RESULT_EXPRESSION,
+  FACTORY_MERGE_TARGET_REF_CONDITION,
+  type FactoryMergeFreezeJob,
+  factoryMergeFreezeJob,
+  type FactoryMergeFreezeJobOptions,
+  factoryMergeFreezeScript,
+} from "./merge-freeze-job.ts";
 export {
   FACTORY_PR_STATUS_HUD_APP_TOKEN_STEP_ID,
   FACTORY_PR_STATUS_HUD_CONCURRENCY,