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

package/src/merge-freeze-job.ts

@@ -0,0 +1,230 @@
+import type { PinnedAction } from "./actions.ts";
+import type { WorkflowStep } from "./factory-workflow.ts";
+import { assertPinnedAction } from "./pinned-action.ts";
+import { FACTORY_PROOF_GATE_APP_ID } from "./proof-reuse-gate.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. */
+export const FACTORY_MERGE_FREEZE_CHECK_NAME = "patronage-factory/merge-freeze";
+
+export const FACTORY_MERGE_FREEZE_JOB_ID = "freeze";
+export const FACTORY_MERGE_FREEZE_JOB_NAME = "Report the merge freeze";
+
+/** Step id the token step exposes its installation token under. */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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).
+ */
+export const FACTORY_MERGE_FREEZE_PERMISSIONS = Object.freeze({} as const);
+
+/**
+ * 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.
+ */
+export const factoryMergeFreezeScript = (): string =>
+  [
+    `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");
+
+export interface FactoryMergeFreezeJobOptions<TNeed> {
+  /** The pinned `actions/create-github-app-token` the caller declared. */
+  readonly createGithubAppToken: PinnedAction;
+  /**
+   * Every authoritative verification leaf this generation folds. The elements
+   * are whatever the caller's workflow generator uses for `needs:`; they are
+   * returned unchanged.
+   */
+  readonly needs: readonly TNeed[];
+  /**
+   * Override the result fold. Defaults to
+   * `FACTORY_MERGE_FREEZE_VERIFY_RESULT_EXPRESSION`, which is what a caller
+   * whose summary job folds `needs.*.result` wants. Supply one only when the
+   * caller's red condition is genuinely different.
+   */
+  readonly verifyResultExpression?: string;
+}
+
+export interface FactoryMergeFreezeJob<TNeed> {
+  readonly if: typeof FACTORY_MERGE_FREEZE_IF;
+  readonly jobId: typeof FACTORY_MERGE_FREEZE_JOB_ID;
+  readonly jobName: typeof FACTORY_MERGE_FREEZE_JOB_NAME;
+  readonly needs: readonly TNeed[];
+  readonly permissions: typeof FACTORY_MERGE_FREEZE_PERMISSIONS;
+  readonly steps: readonly WorkflowStep[];
+}
+
+/**
+ * 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.
+ */
+export const factoryMergeFreezeJob = <TNeed>(
+  options: FactoryMergeFreezeJobOptions<TNeed>
+): FactoryMergeFreezeJob<TNeed> => {
+  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."
+    );
+  }
+
+  // Same unscoped mint as the PR status HUD job. A subset (checks/issues/PRs)
+  // 422s: those permissions are not granted to this installation.
+  const mintStep: WorkflowStep = 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` superseded `app-id` in v3.2.0 (#581, #592): both inputs
+      // reach the same underlying `createAppAuth({ appId })` call, which has
+      // always accepted either the numeric App id or the Client id, so a
+      // pinned App id keeps authenticating unchanged.
+      "client-id": FACTORY_PROOF_GATE_APP_ID,
+      "private-key": `\${{ secrets.FACTORY_GITHUB_APP_PRIVATE_KEY }}`,
+    }),
+  });
+  const reportStep: WorkflowStep = 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]),
+  });
+};

package/src/pr-status-hud-workflow.ts

@@ -1,6 +1,7 @@
 import type { PinnedAction } from "./actions.ts";
 import type { WorkflowStep } from "./factory-workflow.ts";
 import { assertPinnedAction } from "./pinned-action.ts";
+import { PREVIEW_PROOF_INVENTORY_LIST_PERMISSIONS } from "./preview-proof-inventory.ts";
 import { FACTORY_PROOF_GATE_APP_ID } from "./proof-reuse-gate.ts";
 
 export const FACTORY_PR_STATUS_HUD_JOB_ID = "status-hud";
@@ -23,15 +24,12 @@ export interface FactoryPrStatusHudWorkflowOptions {
 }
 
 /**
- * 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).
  */
-export const FACTORY_PR_STATUS_HUD_PERMISSIONS = Object.freeze({
-  checks: "read",
-  contents: "read",
-  "pull-requests": "read",
-} as const);
+export const FACTORY_PR_STATUS_HUD_PERMISSIONS =
+  PREVIEW_PROOF_INVENTORY_LIST_PERMISSIONS;
 
 export const FACTORY_PR_STATUS_HUD_CONCURRENCY = Object.freeze({
   cancelInProgress: false,

package/src/preview-proof-inventory.ts

@@ -35,6 +35,21 @@ import { FACTORY_PROOF_GATE_APP_ID } from "./proof-reuse-gate.ts";
 export 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.
+ */
+export const PREVIEW_PROOF_INVENTORY_LIST_PERMISSIONS = Object.freeze({
+  checks: "read",
+  contents: "read",
+  "pull-requests": "read",
+} as const);
+
 const INVENTORY_KIND = "patronage-factory-preview-proof";
 const INVENTORY_SCHEMA_VERSION = 1;
 const DEFAULT_TIMEOUT_MS = 5000;
@@ -317,7 +332,8 @@ const replaceRegistration = (
 const memoryKey = (owner: string, repo: string, pr: number): string =>
   `${owner}/${repo}#${pr}`;
 
-export const memoryStore = (): PreviewProofInventoryStore => {
+/** Reached by callers as `previewProofInventory.memoryStore`. */
+const memoryStore = (): PreviewProofInventoryStore => {
   const byPr = new Map<string, PreviewProofRegistration[]>();
 
   return {
@@ -967,7 +983,8 @@ const takeNewestRegistrations = (
   return [...byKey.values()];
 };
 
-export const githubStore = (
+/** Reached by callers as `previewProofInventory.githubStore`. */
+const githubStore = (
   transport: PreviewProofInventoryTransport
 ): PreviewProofInventoryStore => {
   const request = transport.fetch ?? fetch;
@@ -1172,6 +1189,7 @@ const recordCleanup = async (
 export const previewProofInventory = {
   githubStore,
   list,
+  listPermissions: PREVIEW_PROOF_INVENTORY_LIST_PERMISSIONS,
   memoryStore,
   persist,
   recordCleanup,

package/src/proof-reuse-gate.ts

@@ -142,6 +142,41 @@ export const FACTORY_PROOF_GATE_GUARD = `steps.${FACTORY_PROOF_GATE_STEP_ID}.out
 export 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.
+ */
+export const FACTORY_PROOF_GATE_PULL_REQUEST_IF =
+  "github.event_name == 'pull_request'";
+
+/**
+ * Which events may reuse proof.
+ *
+ * A two-value enum, not a free-text condition: a string lets a consumer write
+ * a condition this package cannot reason about — one that reuses proof on an
+ * unproven ref — and the emitted condition is a trust predicate. The consumer
+ * chooses the mode; `factory-ci` owns what each mode emits.
+ *
+ * - `pull-request-and-default-branch` (default) pull requests plus pushes to
+ *   the merge target, with the merge fallback. Today's behaviour.
+ * - `pull-request` pull requests only. Default-branch pushes execute the full
+ *   hosted suite, and the merge fallback is not emitted.
+ */
+export type FactoryProofGateReuse =
+  | "pull-request"
+  | "pull-request-and-default-branch";
+
 /**
  * The complete refusal vocabulary. Deliberately few, because these are the
  * only distinctions the gate can honestly make from its Checks API reads.
@@ -488,7 +523,99 @@ const safeLabel = (surface: string): string => {
   return cleaned.length > 0 ? cleaned : "verification";
 };
 
-const gateScript = (required: readonly string[], surface: string): string =>
+/**
+ * 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("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: FactoryProofGateReuse): string =>
+  reuse === "pull-request" ? "\n" : `\n${MERGE_FALLBACK_BLOCK}\n\n`;
+
+const gateScript = (
+  required: readonly string[],
+  surface: string,
+  reuse: FactoryProofGateReuse
+): string =>
   String.raw`
 set -uo pipefail
 
@@ -576,82 +703,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("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
   '') ;;
@@ -770,6 +822,13 @@ export interface FactoryProofGateOptions {
    * therefore requires a different coverage.
    */
   readonly commands: readonly ProofReuseCommand[];
+  /**
+   * Which events may reuse proof. Defaults to
+   * `"pull-request-and-default-branch"`, the behaviour every consumer has
+   * today. `"pull-request"` makes default-branch pushes execute the full
+   * hosted suite (#873).
+   */
+  readonly reuse?: FactoryProofGateReuse;
   /** Names the suite in the job summary. Changes no trust decision. */
   readonly surface: string;
 }
@@ -788,11 +847,12 @@ export interface FactoryProofGateOptions {
  */
 export const factoryProofGateScript = ({
   commands,
+  reuse = "pull-request-and-default-branch",
   surface,
 }: FactoryProofGateOptions): string => {
   const required = proofReuseRequiredCommands(commands);
   return required
-    ? gateScript(required, safeLabel(surface))
+    ? gateScript(required, safeLabel(surface), reuse)
     : UNUSABLE_SELECTION_SCRIPT;
 };
 
@@ -803,7 +863,9 @@ export interface FactoryProofGateStep {
     HEAD_SHA: string;
   }>;
   readonly id: typeof FACTORY_PROOF_GATE_STEP_ID;
-  readonly if: typeof FACTORY_PROOF_GATE_IF;
+  readonly if:
+    | typeof FACTORY_PROOF_GATE_IF
+    | typeof FACTORY_PROOF_GATE_PULL_REQUEST_IF;
   readonly name: string;
   readonly run: string;
   readonly shell: typeof FACTORY_PROOF_GATE_SHELL;
@@ -817,7 +879,9 @@ export interface FactoryProofGateStep {
  * `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
@@ -841,7 +905,10 @@ export const factoryProofGateStep = (
       ),
     }),
     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),
     // Never omit: the runner's default `run:` shell supplies `-e`, which

package/src/push-identity-workflow.ts

@@ -3,16 +3,17 @@ import type { WorkflowStep } from "./factory-workflow.ts";
 import { assertPinnedAction } from "./pinned-action.ts";
 
 export const FACTORY_PUSH_IDENTITY_SCHEMA_VERSION = 1;
-export const FACTORY_PUSH_IDENTITY_ARTIFACT_PREFIX = "factory-push-identity";
-export const FACTORY_PUSH_IDENTITY_RECORD_STEP_ID =
-  "factory_push_identity_record";
-export const FACTORY_PUSH_IDENTITY_LOOKUP_STEP_ID =
-  "factory_push_identity_lookup";
-export const FACTORY_PUSH_IDENTITY_DOWNLOAD_STEP_ID =
-  "factory_push_identity_download";
-export const FACTORY_PUSH_IDENTITY_CHECKOUT_STEP_ID =
-  "factory_push_identity_checkout";
-export const FACTORY_PUSH_IDENTITY_VALIDATE_STEP_ID = "factory_push_identity";
+/**
+ * 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";
+const FACTORY_PUSH_IDENTITY_DOWNLOAD_STEP_ID = "factory_push_identity_download";
+const FACTORY_PUSH_IDENTITY_CHECKOUT_STEP_ID = "factory_push_identity_checkout";
+const FACTORY_PUSH_IDENTITY_VALIDATE_STEP_ID = "factory_push_identity";
 
 /** Versioned document uploaded by a push-triggered verification run. */
 export interface FactoryPushIdentityEnvelope {