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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patronage/factory-ci",
-  "version": "1.0.0-alpha.21",
+  "version": "1.0.0-alpha.23",
   "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",
@@ -48,7 +48,7 @@
     "node": "^24.0.0"
   },
   "scripts": {
-    "cleanup:check": "knip --files --dependencies",
+    "cleanup:check": "knip --files --dependencies --exports",
     "prebuild": "bash ../scripts/ensure-worktree-bootstrap.sh",
     "build": "tsdown",
     "precheck": "bash ../scripts/ensure-worktree-bootstrap.sh",

package/src/actions.ts

@@ -52,3 +52,16 @@ export const NODE_PNPM_ACTION_FAMILY_NODE24 = {
     uses: "pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271",
   },
 } as const satisfies NodePnpmActionFamily;
+
+/**
+ * The one `actions/upload-artifact` pin every workflow generator shares
+ * (#887). Two callers pinned two different commits of the same tag family;
+ * naming the pin here makes that drift impossible the same way the Node/pnpm
+ * family does. A caller passes this through `factoryWorkflow`'s
+ * `additionalActions.uploadArtifact` explicitly — the catalog names the pin,
+ * it does not inject the upload step.
+ */
+export const UPLOAD_ARTIFACT = {
+  tag: "v4.6.2",
+  uses: "actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02",
+} as const satisfies PinnedAction;

package/src/candidate-impact-workflow.ts

@@ -1,4 +1,5 @@
 import type { WorkflowStep } from "./factory-workflow.ts";
+import { impactDemandConditions } from "./impact-demand-condition.ts";
 import { productionImpactTargetOutput } from "./production-impact-workflow.ts";
 
 export const FACTORY_CANDIDATE_IMPACT_STEP_ID = "candidate_impact";
@@ -23,8 +24,13 @@ export interface FactoryCandidateImpactWorkflow {
   /** Outputs for a caller-owned decision job that subsequent jobs may consume. */
   readonly decisionJobOutputs: Readonly<Record<string, string>>;
   readonly decisionStep: WorkflowStep;
-  /** A fail-open condition: only an explicit usable withdrawal skips work. */
-  readonly demandedIf: (targetName: string, decisionJob?: string) => string;
+  /**
+   * A fail-open cross-job condition: only an explicit usable withdrawal skips
+   * work. The decision job id is required.
+   */
+  readonly demandedIf: (targetName: string, decisionJob: string) => string;
+  /** The same fail-open condition for a step in the decision job. */
+  readonly demandedIfAtStep: (targetName: string) => string;
   readonly targetOutputs: Readonly<Record<string, string>>;
 }
 
@@ -74,6 +80,13 @@ export const factoryCandidateImpactWorkflow = (
     run: `${cli} candidate:impact --base "$FACTORY_BASE_SHA" --head "$FACTORY_HEAD_SHA" --github-output "$GITHUB_OUTPUT" --github-summary "$GITHUB_STEP_SUMMARY"${profile}`,
   };
 
+  const conditions = impactDemandConditions({
+    decisionOutput: FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT,
+    label: "candidate",
+    stepId: FACTORY_CANDIDATE_IMPACT_STEP_ID,
+    targetOutputs,
+  });
+
   return Object.freeze({
     decisionJobOutputs: Object.freeze({
       basis: `\${{ steps.${FACTORY_CANDIDATE_IMPACT_STEP_ID}.outputs.${FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT} }}`,
@@ -88,18 +101,8 @@ export const factoryCandidateImpactWorkflow = (
       ),
     }),
     decisionStep: Object.freeze(decisionStep),
-    demandedIf: (targetName: string, decisionJob?: string) => {
-      const output = targetOutputs[targetName];
-      if (output === undefined) {
-        throw new Error(`Unknown candidate impact target "${targetName}".`);
-      }
-      const source = decisionJob
-        ? `needs.${decisionJob}`
-        : `steps.${FACTORY_CANDIDATE_IMPACT_STEP_ID}`;
-      const outcome = decisionJob ? "result" : "outcome";
-      const condition = `${source}.${outcome} != 'success' || ${source}.outputs.${FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT} != 'usable' || ${source}.outputs.${output} != 'withdrawn'`;
-      return decisionJob ? `always() && (${condition})` : condition;
-    },
+    demandedIf: conditions.demandedIf,
+    demandedIfAtStep: conditions.demandedIfAtStep,
     targetOutputs: Object.freeze(targetOutputs),
   });
 };

package/src/execute-alchemy-entry.ts

@@ -27,22 +27,12 @@ export const setExecuteAlchemyEntrySpawnForTests = (
   spawnImplementation = next ?? spawnSync;
 };
 
-export interface ExecuteAlchemyEntryOptions {
+interface ExecuteAlchemyEntryCommon {
   /**
    * CLI arguments before the bundled entry. The absolute entry path is always
    * appended as the final argument.
    */
   readonly args: readonly string[];
-  /**
-   * Bundle the consumer entry before execution. Required unless `bundledEntry`
-   * is set. Ignored when `bundledEntry` is set.
-   */
-  readonly bundle?: BundleAlchemyEntryOptions;
-  /**
-   * Already-bundled entry path. When set, skips the internal bundle step and
-   * appends this path as the CLI's final argument.
-   */
-  readonly bundledEntry?: string;
   /** Child working directory. Defaults to the bundle root, then process.cwd. */
   readonly cwd?: string;
   /** Child environment. Defaults to process.env. */
@@ -66,6 +56,27 @@ export interface ExecuteAlchemyEntryOptions {
   readonly stdio?: "inherit" | "pipe";
 }
 
+/**
+ * Exactly one entry source. The union refuses `bundle` and `bundledEntry`
+ * together, and refuses neither, so no runtime check is needed.
+ */
+export type ExecuteAlchemyEntryOptions = ExecuteAlchemyEntryCommon &
+  (
+    | {
+        /** Bundle the consumer entry before execution. */
+        readonly bundle: BundleAlchemyEntryOptions;
+        readonly bundledEntry?: never;
+      }
+    | {
+        readonly bundle?: never;
+        /**
+         * Already-bundled entry path. Skips the internal bundle step and
+         * appends this path as the CLI's final argument.
+         */
+        readonly bundledEntry: string;
+      }
+  );
+
 export interface ExecuteAlchemyEntryResult {
   readonly bundledEntry: string;
   readonly stderr: string | null;
@@ -75,16 +86,10 @@ export interface ExecuteAlchemyEntryResult {
 const resolveBundledEntry = async (
   options: ExecuteAlchemyEntryOptions
 ): Promise<string> => {
-  if (options.bundledEntry !== undefined) {
-    return path.resolve(
-      options.cwd ?? options.bundle?.absWorkingDir ?? process.cwd(),
-      options.bundledEntry
-    );
-  }
-  if (options.bundle === undefined) {
-    throw new Error("executeAlchemyEntry requires bundle or bundledEntry.");
+  if (options.bundledEntry === undefined) {
+    return await bundleAlchemyEntry(options.bundle);
   }
-  return await bundleAlchemyEntry(options.bundle);
+  return path.resolve(options.cwd ?? process.cwd(), options.bundledEntry);
 };
 
 const captured = (
@@ -101,8 +106,8 @@ const captured = (
  * Bundle a consumer-owned Alchemy entry, resolve that consumer's Alchemy CLI,
  * run it under the current Node binary, and return only on a successful exit.
  *
- * Pass `bundledEntry` to skip the bundle step and reuse an already-bundled
- * path. Captured stdout and stderr (`stdio: "pipe"`) can be redacted through
+ * Options carry exactly one entry source: `bundle` to bundle now, or
+ * `bundledEntry` to reuse an already-bundled path. Captured stdout and stderr (`stdio: "pipe"`) can be redacted through
  * `redact` before they are returned; `stdio: "inherit"` still streams the
  * child unredacted.
  *

package/src/impact-demand-condition.ts

@@ -0,0 +1,67 @@
+/**
+ * Per-target withdrawal conditions for the candidate and production impact
+ * routing seams. Both seams emit the same condition text, so one
+ * implementation owns it.
+ *
+ * A cross-job condition and a same-job condition read different GitHub
+ * expression sources. `demandedIf` requires the decision job id and reads
+ * `needs.<job>`; `demandedIfAtStep` reads `steps.<stepId>` and takes no job
+ * id. The caller picks the seam by name, so an omitted job id can no longer
+ * emit a same-job condition where a cross-job condition was meant.
+ */
+
+interface ImpactDemandConditionOptions {
+  /** Output key that carries the decision verdict. */
+  readonly decisionOutput: string;
+  /** Seam name used in the unknown-target error. */
+  readonly label: string;
+  /** Id of the decision step inside the decision job. */
+  readonly stepId: string;
+  /** Target name to GitHub output key. */
+  readonly targetOutputs: Readonly<Record<string, string>>;
+}
+
+interface ImpactDemandConditions {
+  /**
+   * Cross-job condition for a job that lists the decision job in `needs`.
+   * The decision job id is required.
+   */
+  readonly demandedIf: (targetName: string, decisionJob: string) => string;
+  /** Same-job condition for a step that follows the decision step. */
+  readonly demandedIfAtStep: (targetName: string) => string;
+}
+
+export const impactDemandConditions = (
+  options: ImpactDemandConditionOptions
+): ImpactDemandConditions => {
+  const targetOutput = (targetName: string): string => {
+    const output = options.targetOutputs[targetName];
+    if (output === undefined) {
+      throw new Error(
+        `Unknown ${options.label} impact target "${targetName}".`
+      );
+    }
+    return output;
+  };
+
+  const condition = (
+    source: string,
+    outcomeKey: string,
+    output: string
+  ): string =>
+    `${source}.${outcomeKey} != 'success' || ${source}.outputs.${options.decisionOutput} != 'usable' || ${source}.outputs.${output} != 'withdrawn'`;
+
+  return Object.freeze({
+    demandedIf: (targetName: string, decisionJob: string) => {
+      const output = targetOutput(targetName);
+      if (decisionJob.trim().length === 0) {
+        throw new Error(
+          `A cross-job ${options.label} impact condition requires the decision job id.`
+        );
+      }
+      return `always() && (${condition(`needs.${decisionJob}`, "result", output)})`;
+    },
+    demandedIfAtStep: (targetName: string) =>
+      condition(`steps.${options.stepId}`, "outcome", targetOutput(targetName)),
+  });
+};

package/src/index.ts

@@ -12,6 +12,7 @@ export {
   NODE_PNPM_ACTION_FAMILY_NODE24,
   type NodePnpmActionFamily,
   type PinnedAction,
+  UPLOAD_ARTIFACT,
 } from "./actions.ts";
 export {
   FACTORY_CANDIDATE_PULL_REQUEST_TYPES,
@@ -43,6 +44,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 +85,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 +94,7 @@ export {
   FACTORY_PROOF_GATE_STEP_NAME,
   type FactoryProofGateOptions,
   type FactoryProofGateReason,
+  type FactoryProofGateReuse,
   factoryProofGateScript,
   type FactoryProofGateStep,
   factoryProofGateStep,
@@ -125,6 +129,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,

package/src/merge-freeze-job.ts

@@ -0,0 +1,237 @@
+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.
+ *
+ * Those two API calls are what the reader's two settling phases observe
+ * (#890). Before the POST the merge target carries no generation at all, which
+ * a reader reports as `awaiting-generation` while the pushed hosted verify run
+ * is still pending. Between the POST and the PATCH the generation exists with
+ * no `output.text`, which a reader reports as `running-generation`. Only the
+ * PATCH writes a verdict, so neither phase is one.
+ *
+ * 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;
@@ -178,7 +193,7 @@ const readCleanup = (value: Record<string, unknown>) => {
     return null;
   }
   const evidence = readStringArray(value.cleanup.evidence);
-  if (evidence === null || value.cleanupStatus !== value.cleanup.outcome) {
+  if (evidence === null) {
     return null;
   }
   return typeof value.cleanup.runUrl === "string" &&
@@ -197,10 +212,8 @@ const readPassingChecks = (value: Record<string, unknown>) => {
   }
   if (
     value.convergence.status !== "passed" ||
-    value.convergenceStatus !== "passed" ||
     typeof value.convergence.detail !== "string" ||
     value.smoke.outcome !== "passed" ||
-    value.smokeStatus !== "passed" ||
     typeof value.smoke.detail !== "string"
   ) {
     return null;
@@ -261,14 +274,11 @@ const readPreviewProofRegistration = (
   }
   return {
     cleanup,
-    cleanupStatus: cleanup.outcome,
     convergence: passing.convergence,
-    convergenceStatus: "passed",
     headSha: identity.headSha,
     pr: identity.pr,
     proof,
     smoke: passing.smoke,
-    smokeStatus: "passed",
     source: "local-self-certified",
     stack: identity.stack,
     stage: identity.stage,
@@ -317,7 +327,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 {
@@ -588,7 +599,7 @@ const checkRunOutput = (registration: PreviewProofRegistration) => {
   const title =
     `Preview proof ${registration.stack}/${registration.stage}`.slice(0, 255);
   return {
-    summary: `cleanup ${registration.cleanupStatus}`,
+    summary: `cleanup ${registration.cleanup.outcome}`,
     text: JSON.stringify({
       kind: INVENTORY_KIND,
       registration,
@@ -967,7 +978,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 +1184,7 @@ const recordCleanup = async (
 export const previewProofInventory = {
   githubStore,
   list,
+  listPermissions: PREVIEW_PROOF_INVENTORY_LIST_PERMISSIONS,
   memoryStore,
   persist,
   recordCleanup,