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

package/README.md

@@ -79,7 +79,7 @@ const core = job("core", {
 
 Migration: upgrade `@patronage/factory-ci`, apply the shared trigger types and job condition in the TypeScript workflow source, then regenerate and commit the emitted YAML. Draft `opened` and `synchronize` events will stop running substantive Verify work. Promotion through `ready_for_review`, later non-draft Candidate events, and merge-target pushes continue to run their applicable battery. A skipped draft run is presentation, not proof.
 
-Production impact support follows the same ownership line. A generated deploy workflow declares only its target names and consumes the returned decision step and fail-open `demandedIf(target)` expressions:
+Production impact support follows the same ownership line. A generated deploy workflow declares only its target names and consumes the returned decision step and fail-open `demandedIf(target, decisionJob)` expressions:
 
 ```ts
 const impact = factoryProductionImpactWorkflow({
@@ -111,6 +111,7 @@ import {
   factoryPushIdentityProducer,
   factoryWorkflow,
   NODE_PNPM_ACTION_FAMILY_NODE24,
+  UPLOAD_ARTIFACT,
 } from "@patronage/factory-ci";
 
 const workflowArtifact = factoryWorkflow({
@@ -120,10 +121,7 @@ const workflowArtifact = factoryWorkflow({
       tag: "v5.0.0",
       uses: "actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0",
     },
-    uploadArtifact: {
-      tag: "v4.6.2",
-      uses: "actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02",
-    },
+    uploadArtifact: UPLOAD_ARTIFACT,
   },
   generated: {
     source: ".github/workflows/verify.ts",
@@ -165,7 +163,7 @@ The helper selects no action family or action version. Callers pass the explicit
 
 This is identity transport and validation only. The consumer still owns the `workflow_run` trigger and branch policy, job topology and runners, deploy credentials and environments, target declarations, commands, ordering, and convergence/no-op proof. None of those belong in the identity artifact or decision job.
 
-Candidate pull-request routing follows the same ownership line through `factoryCandidateImpactWorkflow` (#741). A generated Verify workflow declares only its target names and consumes the returned decision step and fail-open `demandedIf(target)` expressions, so the profile's canonical impact declarations and dependency graph route the run instead of a repository-maintained path filter:
+Candidate pull-request routing follows the same ownership line through `factoryCandidateImpactWorkflow` (#741). A generated Verify workflow declares only its target names and consumes the returned decision step and fail-open `demandedIf(target, decisionJob)` expressions, so the profile's canonical impact declarations and dependency graph route the run instead of a repository-maintained path filter:
 
 ```ts
 const impact = factoryCandidateImpactWorkflow({
@@ -191,7 +189,7 @@ const core = job("core", {
 });
 ```
 
-`demandedIf(target, decisionJob)` emits `always()` so a failed decision job still demands work, and it checks only the decision job's result. Declare the decision job as the routed job's only `needs`. A routed job with more prerequisites must add its own `needs.<job>.result == 'success'` clauses, because `always()` suppresses GitHub's implicit success gating for every dependency. The production decision seam has the same contract.
+`demandedIf(target, decisionJob)` builds the cross-job condition. The decision job id is required, so a routed job cannot receive a same-job condition by accident. It emits `always()` so a failed decision job still demands work, and it checks only the decision job's result. Declare the decision job as the routed job's only `needs`. A routed job with more prerequisites must add its own `needs.<job>.result == 'success'` clauses, because `always()` suppresses GitHub's implicit success gating for every dependency. `demandedIfAtStep(target)` builds the same fail-open condition for a step inside the decision job, where the decision is read from `steps.<stepId>`. The production decision seam has the same contract.
 
 Trust boundary: candidate routing is a cost control inside the pull request's own CI, not a merge-security control. A `pull_request` run executes the PR's workflow file and install scripts, so a hostile PR can already shape any of its own job outputs — with or without this seam, exactly as with a repository path filter. Merge admission never trusts these outputs: merge-target push verification stays full and unrouted, and the factory proof chain binds to commits, not to job conditions.
 
@@ -334,10 +332,10 @@ const coreCommands = profile.verification.commands.filter(
 );
 
 const core = job("core", {
-  // `pull-requests: read` serves the gate's default-branch merge fallback
-  // (#611). Without it the fallback's PR lookup fails and every merge push
-  // silently pays the full suite.
-  permissions: { checks: "read", contents: "read", "pull-requests": "read" },
+  // `checks: read` is all the default PR-only gate needs. Add
+  // `pull-requests: read` only with `reuse: "pull-request-and-default-branch"`,
+  // where the merge fallback (#611) looks up the producing pull request.
+  permissions: { checks: "read", contents: "read" },
   steps: [
     step(factoryProofGateStep({ commands: coreCommands, surface: "core" })),
     step(factoryProofTimingStartStep()),
@@ -349,9 +347,11 @@ const core = job("core", {
 
 The **proof-reuse gate** decides whether a hosted job may reuse the local verification the factory already published for this exact head (ADR 0022). Refusing runs hosted CI; it never fails the candidate. The App identity, check name, step id, output names, guard, and every trust predicate are fixed here rather than consumer-configurable — three repositories had grown three answers to the same question and had already drifted.
 
-The gate runs on pull requests and on pushes to the default branch (#611). A push run first reads proof at the pushed head. A squash merge mints a new commit, so when that direct read finds no generation at all, a **merge fallback** looks up the single merged pull request whose merge commit is the pushed head and reuses that PR head's proven check run — 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 integrate into a tree nothing verified. No unique producing PR, an unreadable commit, a proof that is anything but proven, or tree drift from a dirty or stale merge all leave the direct refusal standing and run the full suite. The fallback needs `pull-requests: read` and `contents: read` on the job in addition to `checks: read`; a job that grants less loses only the fallback.
+**The gate runs on pull requests only by default** (#863). A merge target's guarantee is about the whole tree, not the diff, and a candidate proof binds only the diff that candidate was scoped to. Every default-branch push therefore executes the full hosted suite, and the job needs only `checks: read`. #931 is the defect this default answers: a `main` push reused an impact-scoped candidate proof, executed no command, and left a red package unnoticed for three days.
+
+`reuse` chooses which events may reuse proof (#873). It takes two values and nothing else, because the emitted condition is a trust predicate: a free-text override lets a consumer reuse proof on a ref nothing proved. `"pull-request"` is the default described above. `"pull-request-and-default-branch"` is the opt-out: it adds pushes to the default branch, and the consumer accepts that an impact-scoped candidate proof may gate a whole tree. Choose it when merge-target runner time matters more than that guarantee.
 
-`reuse` chooses which events may reuse proof (#873). It takes two values and nothing else, because the emitted condition is a trust predicate: a free-text override lets a consumer reuse proof on a ref nothing proved. `"pull-request-and-default-branch"` is the default and the behaviour above. `"pull-request"` emits `github.event_name == 'pull_request'` alone and omits the merge fallback, so every default-branch push executes the full hosted suite and the job needs only `checks: read`. Choose it when the merged commit must be verified in its own right; the consumer then owns that unconditional default-branch cost.
+Under the opt-out, a push run first reads proof at the pushed head. A squash merge mints a new commit, so when that direct read finds no generation at all, a **merge fallback** looks up the single merged pull request whose merge commit is the pushed head and reuses that PR head's proven check run — 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 integrate into a tree nothing verified. No unique producing PR, an unreadable commit, a proof that is anything but proven, or tree drift from a dirty or stale merge all leave the direct refusal standing and run the full suite. The fallback needs `pull-requests: read` and `contents: read` on the job in addition to `checks: read`; a job that grants less loses only the fallback.
 
 A proof is reusable only when the complete Checks API result (`filter=all`, every page) establishes one unambiguous newest generation by greatest `started_at`, produced by the pinned App for the exact repository and head, completed successfully with `outcome: passed`, and covering every command identity the guarded surface requires. Coverage is the union of `executedCommands` and commands released by `notRequiredCommands` only after the gate validates each release against that same proof binding's command-to-target map and identity-bound impact stamp. Missing, malformed, duplicated, affected, unknown, or differently bound release data refuses reuse and runs the hosted surface. `mode` is reported as diagnostic metadata, never authorized on: a reduced-mode proof whose executed and stamp-authorized released commands cover a surface is reusable.
 
@@ -379,7 +379,7 @@ import { bundleAlchemyEntry, executeAlchemyEntry } from "@patronage/factory-ci";
 
 `alias` is a specifier-to-target map handed to esbuild. Substitution runs before the `packages` and `external` decisions, so an aliased bare specifier is inlined even under `packages: "external"` — that is how a repo points a workspace-only or duplicated package at one file. Give absolute paths or package names; which aliases a repo needs is consumer policy and this package ships no defaults. `executeAlchemyEntry` passes its whole `bundle` option through, so the map is available there too. Because substitution runs first, an alias on `alchemy`, `effect`, or any of their subpaths would silently defeat the externals and bundle a second copy, so those keys are rejected outright. Targets are not string-matched — no rule over how a path is spelled can survive `..` segments or symlinks — so instead the build's metafile is checked afterwards and the bundle is rejected if it carries any input from a reserved package, however that file was reached. A consumer shim that re-exports `effect` by bare specifier stays external naturally and is allowed.
 
-`executeAlchemyEntry({ from, bundle, args, ... })` owns the repeated choreography: resolve the consumer's Alchemy CLI from `from`, bundle the entry, run that CLI under the current Node binary with the absolute bundled entry appended, and throw on spawn errors, signals, missing statuses, or non-zero exits. It returns only after status 0. Pass `bundledEntry` (absolute or cwd-relative) to skip the bundle step and reuse a path from a prior `bundleAlchemyEntry` call; `bundle` is then optional. Captured output (`stdio: "pipe"`) honors `maxBuffer` only when the caller supplies it (Node's `spawnSync` default is 1 MiB; pass `EXECUTE_ALCHEMY_ENTRY_MAX_BUFFER` for 64 MiB) and, when supplied, a `redact: (text: string) => string` hook applied to stdout and stderr before they are returned. Default `stdio: "inherit"` still streams the child unredacted. This package does not own a secret-name policy.
+`executeAlchemyEntry({ from, bundle, args, ... })` owns the repeated choreography: resolve the consumer's Alchemy CLI from `from`, bundle the entry, run that CLI under the current Node binary with the absolute bundled entry appended, and throw on spawn errors, signals, missing statuses, or non-zero exits. It returns only after status 0. Options carry exactly one entry source. Pass `bundle` to bundle now, or `bundledEntry` (absolute or cwd-relative) to reuse a path from a prior `bundleAlchemyEntry` call. Passing both, or neither, does not type-check. Captured output (`stdio: "pipe"`) honors `maxBuffer` only when the caller supplies it (Node's `spawnSync` default is 1 MiB; pass `EXECUTE_ALCHEMY_ENTRY_MAX_BUFFER` for 64 MiB) and, when supplied, a `redact: (text: string) => string` hook applied to stdout and stderr before they are returned. Default `stdio: "inherit"` still streams the child unredacted. This package does not own a secret-name policy.
 
 The caller still owns deploy/destroy/plan arguments, stage admission, credentials, environment shaping, destructive-plan guards, and convergence. Failure messages never repeat arguments or environment values.
 
@@ -406,7 +406,7 @@ import { previewProofLifecycle } from "@patronage/factory-ci";
 Events:
 
 - `begin` — the pre-deploy gate. Refuses a draft, a closed PR, a dirty or mismatched worktree, and any stage the disposable grammar does not own for this PR head. Does not create a registration.
-- `register` — the same identity gate, plus passed smoke, passed convergence, and a passing three-way-bound evidence envelope at this head. Writes a registration with `cleanupStatus: "pending"`. Machine evidence is that envelope; this module never posts a PR comment.
+- `register` — the same identity gate, plus passed smoke, passed convergence, and a passing three-way-bound evidence envelope at this head. Writes a registration with `cleanup.outcome: "pending"`. Cleanup, smoke, and convergence status live only on their nested objects, so no top-level copy can diverge from them. Machine evidence is that envelope; this module never posts a PR comment.
 - `cleanup` — records an explicit passed or failed outcome onto an existing registration. Cleanup is never inferred from whether the stage still exists. `recover` is the failed-to-resolved re-entry of this event.
 
 Proof runs entirely on one side of GitHub's draft/ready boundary: both `begin` and `register` refuse `isDraft: true`. Undraft first, then prove. Callers still own deploy, destroy, credentials, smoke probes, envelope emission, and stack names.
@@ -452,9 +452,9 @@ The factory publishes its check runs, and paitronage its proof comments, under t
 
 `mintInstallationToken({ credentials, owner, repo }, options?)` is that mechanism and nothing more. `credentials` is `{ appId, installationId?, privateKeyPath }`: the app id GitHub issued, the installation when a consumer has recorded one, and the path to the private key. The key is a _path_, not key material, so no caller has to hold a secret in memory to make this call — and **where that path comes from stays the consumer's**. Operator config, a secret manager, an environment variable: this package neither reads a config file nor knows a key-path convention. `githubAppJwt(credentials, options?)` is the signing step alone, for a caller that needs the app JWT rather than an installation token.
 
-Nothing is cached. The token is returned to the caller, which owns its lifetime — this module keeps no copy of the token or the key, and never writes either to any output. A failing GitHub response throws `GitHubApiError`, which carries `status` so a caller can tell a retryable failure (422, 429, 5xx) from a wrong-credentials one.
+Nothing is cached. The token is returned to the caller, which owns its lifetime — this module keeps no copy of the token or the key, and never writes either to any output. Mint requests send `Connection: close` and retry transport failures — fetch rejection, timeout, a body that dies mid-read, or 408/429/5xx — with doubling backoff for three attempts by default. Exhaustion throws `GitHubAppTokenTransportError` with the attempt count and a bounded credential-free reason. Any other 4xx is GitHub's verdict and throws `GitHubApiError` on the first response without retrying. The budget is the caller's: `transportAttempts` sets the total attempts, and a caller whose mint is best-effort and already has a fallback passes `1` so the fallback stays prompt. The backoff is fixed and does not scale with `timeoutMs`.
 
-`options` are all injectable seams: `fetch`, `now`, `readPrivateKey`, and a `timeoutMs` per request (five seconds by default). Tests substitute the first three; production passes at most a timeout.
+`options` are all injectable seams: `fetch`, `now`, `readPrivateKey`, `transportAttempts`, and a `timeoutMs` per request (five seconds by default). Tests substitute the seams; production passes at most a timeout and a budget.
 
 ### Vitest suite profiling
 

package/dist/index.d.ts

@@ -53,6 +53,18 @@ declare const NODE_PNPM_ACTION_FAMILY_NODE24: {
     readonly uses: "pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271";
   };
 };
+/**
+ * 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.
+ */
+declare const UPLOAD_ARTIFACT: {
+  readonly tag: "v4.6.2";
+  readonly uses: "actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02";
+};
 //#endregion
 //#region src/candidate-lifecycle.d.ts
 /**
@@ -205,12 +217,10 @@ interface PreviewProofRegistration {
     readonly outcome: PreviewProofCleanupStatus;
     readonly runUrl?: string;
   };
-  readonly cleanupStatus: PreviewProofCleanupStatus;
   readonly convergence: {
     readonly detail: string;
     readonly status: "passed";
   };
-  readonly convergenceStatus: "passed";
   readonly headSha: string;
   readonly pr: number;
   readonly proof: {
@@ -223,7 +233,6 @@ interface PreviewProofRegistration {
     readonly detail: string;
     readonly outcome: "passed";
   };
-  readonly smokeStatus: "passed";
   readonly source: "local-self-certified";
   readonly stack: string;
   readonly stage: LocalPreviewStage;
@@ -462,6 +471,20 @@ interface FactoryWorkflowArtifact<Additional extends Readonly<Record<string, Pin
  */
 declare const factoryWorkflow: <const Additional extends Readonly<Record<string, PinnedAction>> = Record<never, never>>(options: FactoryWorkflowOptions<Additional>) => FactoryWorkflowArtifact<Additional>;
 //#endregion
+//#region src/github-transport.d.ts
+/**
+ * Bounded transport retries could not reach the GitHub App endpoint (#923).
+ * The reason is credential-free, so it is safe to log. Re-exported from
+ * `github-app-token.ts`, which owns the mint surface.
+ */
+declare class GitHubAppTokenTransportError extends Error {
+  /** How many transport attempts were made before giving up. */
+  readonly attempts: number;
+  /** The last transient HTTP status, when the server answered at all. */
+  readonly status?: number;
+  constructor(reason: string, attempts: number, status?: number);
+}
+//#endregion
 //#region src/github-app-token.d.ts
 /**
  * What a consumer must know to mint: the app id, where the private key is, and
@@ -491,6 +514,15 @@ interface GithubAppTokenOptions {
   readPrivateKey?: (privateKeyPath: string) => Buffer | string;
   /** Per-request timeout; defaults to five seconds. */
   timeoutMs?: number;
+  /**
+   * Total transport attempts per request, the first one included. Defaults to
+   * three: a mint that must survive a stale keep-alive socket (#923). A caller
+   * whose mint is best-effort and already has a fallback passes 1, because
+   * retrying against a deliberately short timeout only delays that fallback
+   * (#938). The backoff between attempts is fixed and does not scale with
+   * `timeoutMs`; the two dials are unrelated.
+   */
+  transportAttempts?: number;
 }
 /**
  * The signed app JWT GitHub accepts as `Authorization: Bearer` for the App
@@ -518,22 +550,12 @@ declare const mintInstallationToken: (input: {
 //#region src/execute-alchemy-entry.d.ts
 /** Node's spawnSync default is 1 MiB; Alchemy plans routinely exceed that. */
 declare const EXECUTE_ALCHEMY_ENTRY_MAX_BUFFER: number;
-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. */
@@ -556,6 +578,21 @@ interface ExecuteAlchemyEntryOptions {
   /** Child stdio. Default "inherit". */
   readonly stdio?: "inherit" | "pipe";
 }
+/**
+ * Exactly one entry source. The union refuses `bundle` and `bundledEntry`
+ * together, and refuses neither, so no runtime check is needed.
+ */
+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;
+});
 interface ExecuteAlchemyEntryResult {
   readonly bundledEntry: string;
   readonly stderr: string | null;
@@ -565,8 +602,8 @@ interface ExecuteAlchemyEntryResult {
  * 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.
  *
@@ -581,10 +618,13 @@ declare const executeAlchemyEntry: (options: ExecuteAlchemyEntryOptions) => Prom
  *
  * It answers one question, before checkout and before install: may this job
  * reuse the local verification the factory already published for *this exact
- * head*? On a push to the merge target one fallback extends "this exact head"
- * to "this exact tree": a squash merge whose result tree is byte-identical to
- * the producing pull request's proven head tree reuses that head's proof
- * (#611). Refusing runs hosted CI; it never fails the candidate. Three
+ * head*? By default it asks that only on a pull request, so every
+ * default-branch push executes the full hosted suite (#863). A consumer may
+ * opt into `reuse: "pull-request-and-default-branch"`, where one fallback
+ * extends "this exact head" to "this exact tree": a squash merge whose result
+ * tree is byte-identical to the producing pull request's proven head tree
+ * reuses that head's proof (#611). Refusing runs hosted CI; it never fails
+ * the candidate. Three
  * repositories had independently grown their own answer to that question and
  * had already drifted apart, so the answer lives here once, with the App
  * identity, check name, step identity, output names, guard, and every trust
@@ -662,18 +702,25 @@ declare const FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT = "source-check-url";
  */
 declare const FACTORY_PROOF_GATE_GUARD = "steps.factory-proof.outputs.reuse-proof != 'true'";
 /**
- * Pull requests, plus pushes to the merge target (#611).
+ * Pull requests, plus pushes to the merge target (#611) — the **opt-out**
+ * condition a consumer gets with `reuse: "pull-request-and-default-branch"`.
  *
- * The gate was pull-request-only through 1.0.0-alpha.15: a push to a
- * protected branch always ran the full suite, because no local proof is ever
- * written for the merged SHA. That still holds for the *direct* read — a
- * squash merge mints a new commit — which is why the push path exists only
- * together with the merge fallback below: when no generation exists at the
- * merged SHA, the gate may look up the producing pull request and reuse its
- * head proof, but only when the merge result's tree is exactly the proven
- * head's tree. Deploy gates keep
- * waiting for a green required check at the merged SHA; a reused proof turns
- * that check green through the same guarded steps a pull request uses.
+ * It buys runner time on the merge target and pays for it in coverage. No
+ * local proof is ever written for a merged SHA, so the direct read finds
+ * nothing after a squash merge. The push path therefore exists only together
+ * with the merge fallback below: when no generation exists at the merged SHA,
+ * the gate may look up the producing pull request and reuse its head proof,
+ * but only when the merge result's tree is exactly the proven head's tree.
+ * Deploy gates keep waiting for a green required check at the merged SHA; a
+ * reused proof turns that check green through the same guarded steps a pull
+ * request uses.
+ *
+ * The trade this mode accepts: a candidate's proof may be impact-scoped, and
+ * an impact-scoped proof is a sound gate for the candidate and an unsound
+ * gate for the merge target. #931 is that defect observed — a `main` push
+ * reused a candidate proof, executed no command, and left a red package
+ * unnoticed for three days. Choose this mode only when the consumer accepts
+ * that risk for speed.
  *
  * The push side is deliberately the merge target only — the repository's
  * default branch — not every pushed branch. Which branches trigger a
@@ -683,16 +730,16 @@ declare const FACTORY_PROOF_GATE_GUARD = "steps.factory-proof.outputs.reuse-proo
  */
 declare 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).
+ * Pull requests only — the **default** condition, and the condition a
+ * consumer gets with `reuse: "pull-request"` (#873, default since #863).
  *
- * 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.
+ * A merge target's guarantee is about the whole tree, not the diff. A
+ * candidate proof only ever binds the diff the candidate was scoped to, so
+ * reusing it on the merged commit proves less than the merge target needs.
+ * Every default-branch push therefore executes the full hosted suite,
+ * whatever proof exists. 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.
@@ -706,10 +753,12 @@ declare const FACTORY_PROOF_GATE_PULL_REQUEST_IF = "github.event_name == 'pull_r
  * 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.
+ * - `pull-request` (default) pull requests only. Default-branch pushes
+ *   execute the full hosted suite, and the merge fallback is not emitted.
+ * - `pull-request-and-default-branch` the opt-out: pull requests plus pushes
+ *   to the merge target, with the merge fallback. It is faster on the merge
+ *   target and it lets an impact-scoped candidate proof gate a whole tree
+ *   (#931), so a consumer must ask for it.
  */
 type FactoryProofGateReuse = "pull-request" | "pull-request-and-default-branch";
 /**
@@ -796,10 +845,10 @@ interface FactoryProofGateOptions {
    */
   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).
+   * Which events may reuse proof. Defaults to `"pull-request"`: every
+   * default-branch push executes the full hosted suite (#873, #863).
+   * `"pull-request-and-default-branch"` is the opt-out a consumer chooses for
+   * speed on the merge target, and it accepts #931's risk.
    */
   readonly reuse?: FactoryProofGateReuse;
   /** Names the suite in the job summary. Changes no trust decision. */
@@ -838,13 +887,14 @@ interface FactoryProofGateStep {
  * The step itself, structurally accepted by gagen's `step()` without adding a
  * gagen runtime dependency. It belongs first in the job it guards: a few API
  * reads with the default `GITHUB_TOKEN`, no checkout, no install, so a proven
- * head costs a runner nothing beyond job startup. A pull request needs
- * `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. A
- * consumer that passes `reuse: "pull-request"` emits neither the push clause
- * nor the fallback, and needs only `checks: read` (#873).
+ * head costs a runner nothing beyond job startup. The default
+ * `reuse: "pull-request"` emits neither the push clause nor the fallback, and
+ * needs only `checks: read` (#873, #863). A consumer that opts into
+ * `reuse: "pull-request-and-default-branch"` also runs the push-event merge
+ * fallback, which 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.
  *
  * 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
@@ -939,8 +989,13 @@ 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>>;
 }
 /**
@@ -1010,6 +1065,13 @@ declare const factoryLifecycleContractLane: (declaration?: FactoryLifecycleContr
  * `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
@@ -1213,8 +1275,13 @@ interface FactoryProductionImpactWorkflow {
   /** 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>>;
 }
 /**
@@ -1237,7 +1304,12 @@ interface FactoryPushIdentityEnvelope {
 }
 type FactoryPushIdentityDisposition = "refused" | "usable";
 interface FactoryPushIdentityProducerOptions {
-  /** Explicit caller-owned upload-artifact pin from its workflow artifact. */
+  /**
+   * Explicit caller-owned upload-artifact pin from its workflow artifact.
+   * Pass factory-ci's `UPLOAD_ARTIFACT` catalog export (or another
+   * `actions/upload-artifact` pin); the caller wires the step, the catalog
+   * only names the pin.
+   */
   readonly uploadArtifact: PinnedAction;
   /** Optional consumer trigger policy combined with the required push event. */
   readonly if?: string;
@@ -1556,4 +1628,4 @@ declare const assertWorkflowShellParses: (yaml: string, options: {
   readonly source: string;
 }) => void;
 //#endregion
-export { type BundleAlchemyEntryOptions, type CheckoutStepOptions, EXECUTE_ALCHEMY_ENTRY_MAX_BUFFER, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, 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, type FactoryCandidateImpactWorkflow, type FactoryCandidateImpactWorkflowOptions, type FactoryLifecycleContractLane, type FactoryLifecycleContractLaneOptions, type FactoryMergeFreezeJob, type FactoryMergeFreezeJobOptions, type FactoryPrStatusHudWorkflow, type FactoryPrStatusHudWorkflowOptions, type FactoryPreviewCleanupAuditJob, type FactoryPreviewCleanupDestroyJob, type FactoryPreviewCleanupTopology, type FactoryPreviewCleanupTopologyOptions, type FactoryProductionImpactWorkflow, type FactoryProductionImpactWorkflowOptions, type FactoryProofGateOptions, type FactoryProofGateReason, type FactoryProofGateReuse, type FactoryProofGateStep, type FactoryProofReusePresentationOptions, type FactoryProofReuseSummaryStep, type FactoryProofTimingStartStep, type FactoryPushIdentityConsumer, type FactoryPushIdentityConsumerOptions, type FactoryPushIdentityDisposition, type FactoryPushIdentityEnvelope, type FactoryPushIdentityProducer, type FactoryPushIdentityProducerOptions, type FactoryWorkflowArtifact, type FactoryWorkflowOptions, type FactoryWorkflowSetupOptions, GitHubApiError, type GithubAppCredentials, type GithubAppTokenOptions, type InstallStepOptions, type LocalPreviewStage, type LocalPreviewStageOptions, NODE_PNPM_ACTION_FAMILY_NODE24, type NodePnpmActionFamily, PREVIEW_PROOF_INVENTORY_CHECK_NAME, PREVIEW_PROOF_INVENTORY_LIST_PERMISSIONS, type ParseLocalPreviewStageExpected, type ParsedLocalPreviewStage, type PinnedAction, type PreviewProofCandidate, type PreviewProofCleanupOutcome, type PreviewProofCleanupStatus, type PreviewProofEnvelopeEvidence, type PreviewProofInventoryAccess, type PreviewProofInventoryCleanupInput, type PreviewProofInventoryListInput, type PreviewProofInventoryPersistInput, type PreviewProofInventoryStore, type PreviewProofInventoryTransport, type PreviewProofLifecycleEvent, type PreviewProofLifecycleState, type PreviewProofRegistration, type PreviewProofResolveQuery, PreviewProofTransportError, type ProofReuseCommand, type ProofReuseCoverageInput, type ProofReuseCoverageReport, type SetupNodeStepOptions, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, type VitestJsonReport, type VitestProfile, type VitestProfileDependencies, type VitestProfileDurationSummary, type VitestProfileEnvironment, VitestProfileError, type VitestProfileOptions, type VitestProfileReadResult, type VitestProfileSample, type VitestProfileSampleExecution, type VitestTestStatus, type WorkflowShellParseFailure, type WorkflowStep, 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 };
+export { type BundleAlchemyEntryOptions, type CheckoutStepOptions, EXECUTE_ALCHEMY_ENTRY_MAX_BUFFER, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, 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, type FactoryCandidateImpactWorkflow, type FactoryCandidateImpactWorkflowOptions, type FactoryLifecycleContractLane, type FactoryLifecycleContractLaneOptions, type FactoryMergeFreezeJob, type FactoryMergeFreezeJobOptions, type FactoryPrStatusHudWorkflow, type FactoryPrStatusHudWorkflowOptions, type FactoryPreviewCleanupAuditJob, type FactoryPreviewCleanupDestroyJob, type FactoryPreviewCleanupTopology, type FactoryPreviewCleanupTopologyOptions, type FactoryProductionImpactWorkflow, type FactoryProductionImpactWorkflowOptions, type FactoryProofGateOptions, type FactoryProofGateReason, type FactoryProofGateReuse, type FactoryProofGateStep, type FactoryProofReusePresentationOptions, type FactoryProofReuseSummaryStep, type FactoryProofTimingStartStep, type FactoryPushIdentityConsumer, type FactoryPushIdentityConsumerOptions, type FactoryPushIdentityDisposition, type FactoryPushIdentityEnvelope, type FactoryPushIdentityProducer, type FactoryPushIdentityProducerOptions, type FactoryWorkflowArtifact, type FactoryWorkflowOptions, type FactoryWorkflowSetupOptions, GitHubApiError, GitHubAppTokenTransportError, type GithubAppCredentials, type GithubAppTokenOptions, type InstallStepOptions, type LocalPreviewStage, type LocalPreviewStageOptions, NODE_PNPM_ACTION_FAMILY_NODE24, type NodePnpmActionFamily, PREVIEW_PROOF_INVENTORY_CHECK_NAME, PREVIEW_PROOF_INVENTORY_LIST_PERMISSIONS, type ParseLocalPreviewStageExpected, type ParsedLocalPreviewStage, type PinnedAction, type PreviewProofCandidate, type PreviewProofCleanupOutcome, type PreviewProofCleanupStatus, type PreviewProofEnvelopeEvidence, type PreviewProofInventoryAccess, type PreviewProofInventoryCleanupInput, type PreviewProofInventoryListInput, type PreviewProofInventoryPersistInput, type PreviewProofInventoryStore, type PreviewProofInventoryTransport, type PreviewProofLifecycleEvent, type PreviewProofLifecycleState, type PreviewProofRegistration, type PreviewProofResolveQuery, PreviewProofTransportError, type ProofReuseCommand, type ProofReuseCoverageInput, type ProofReuseCoverageReport, type SetupNodeStepOptions, UPLOAD_ARTIFACT, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, type VitestJsonReport, type VitestProfile, type VitestProfileDependencies, type VitestProfileDurationSummary, type VitestProfileEnvironment, VitestProfileError, type VitestProfileOptions, type VitestProfileReadResult, type VitestProfileSample, type VitestProfileSampleExecution, type VitestTestStatus, type WorkflowShellParseFailure, type WorkflowStep, 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 };