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

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.
 
@@ -256,6 +254,42 @@ const jobs = [
 
 The audit job is `always()` so a failed destroy still runs the stage-wide check. It does not receive a stack name or path filter — per-stack audit filters are rejected because they trade away the whole-stage guarantee (paitronage#1143). `previewCleanupDestroyJobId(stack)` is the same id mapping callers can use when they assemble destroy jobs by hand.
 
+### Merge-freeze writer job
+
+```ts
+import { factoryMergeFreezeJob } from "@patronage/factory-ci";
+
+const freeze = factoryMergeFreezeJob({
+  createGithubAppToken: workflowArtifact.actions.createGithubAppToken,
+  needs: [changes, core, docs],
+});
+
+const jobs = [
+  changes,
+  core,
+  docs,
+  job(freeze.jobId, {
+    name: freeze.jobName,
+    needs: freeze.needs,
+    if: freeze.if,
+    runsOn: "ubuntu-latest",
+    permissions: freeze.permissions,
+    timeoutMinutes: 10,
+    steps: freeze.steps,
+  }),
+];
+```
+
+A consumer's generated merge-target-push Verify workflow is the only producer of `patronage-factory/merge-freeze` generations (#356, ADR 0016 as amended; #429, #872). A red merge-target Verify completes a generation active, a green one completes it inactive, and `pr:ready` reads the generation on the candidate's own base tip. No command, scheduled job, or second workflow writes that check run; the operator override (`demand:waive --demand merge-freeze`) waives the demand for one candidate and never writes here.
+
+`factoryMergeFreezeJob` owns everything a reader trusts: the check name (`FACTORY_MERGE_FREEZE_CHECK_NAME`), the pinned Patronage Factory App identity, the `actions/create-github-app-token` inputs, the `needs.*.result` fold (`FACTORY_MERGE_FREEZE_VERIFY_RESULT_EXPRESSION`), the merge-target condition (`FACTORY_MERGE_FREEZE_IF`, built from `FACTORY_MERGE_TARGET_REF_CONDITION`), and the job's least-privilege `permissions` (an empty block: the App installation token carries the check-run write, the job uses no `GITHUB_TOKEN` scope, and it never checks out the repository). The caller owns the runner, the timeout, and the `needs` list.
+
+That `needs` list is the whole trust input: it must name **every authoritative verification leaf**, because the fold is what decides active or inactive. An empty list is refused — a fold over no needed job always reports success, which would report a merge target nothing verified as green.
+
+`if` is `always() && github.event_name == 'push' && (main or epic/**)`. Each clause is load-bearing. `always()` keeps the red path running when a needed job failed. `push` keeps a `pull_request` run from writing a generation at its synthetic merge SHA. The namespace is literal by decision — `main` plus repository-owned `epic/**` integration branches — so a consumer's `push` trigger branch list names the same two things.
+
+The job needs no checkout and no install: it mints an App installation token, then makes two Checks API calls. The write is deliberately fail-closed, the opposite of the proof-reuse gate's fail-open shell. The step runs under the runner's default `bash -e {0}`, so any API refusal aborts it, the generation stays absent or `in_progress`, and every arming-time read of that tip refuses until a later push writes a green generation. `factoryMergeFreezeScript()` is that script alone, for a consumer test that executes it against a stubbed `gh` and parses the emitted payload with the factory package's `validateMergeFreezeState` — the round trip that keeps writer and reader from drifting.
+
 ### Generated shell
 
 ```ts
@@ -315,6 +349,8 @@ The **proof-reuse gate** decides whether a hosted job may reuse the local verifi
 
 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.
 
+`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.
+
 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.
 
 The only thing a consumer chooses is **what its surface requires**, expressed as the plain profile command objects that surface selects — a repository with distinct core and docs jobs selects distinct sets and gets distinct required coverage. `proofReuseRequiredCommands()` is the single derivation both the gate and the assertion go through. Identities are baked into the emitted script, so they are held to a plain `[A-Za-z0-9_][\w.:@/-]*` allow-list and shell-quoted at the interpolation site; a selection carrying anything else is unusable and degrades to a gate that always refuses.
@@ -341,7 +377,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.
 
@@ -368,7 +404,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.
@@ -391,7 +427,7 @@ Registration is a consumer-readable read model. Cleanup outcomes are recorded by
 
 Persistence is an injectable GitHub transport in the same style as `mintInstallationToken`: the caller passes `fetch` and a token. This package does not read operator config or hold secrets. Records bind to the Patronage Factory GitHub App (`FACTORY_PROOF_GATE_APP_ID`) and the disposable-stage grammar. Check-runs named `patronage-factory/preview-proof` (`PREVIEW_PROOF_INVENTORY_CHECK_NAME`) carry the registration JSON. This API does not POST or PATCH issue comments.
 
-`list({ owner, repo, pr }, { token })` works with a workflow `GITHUB_TOKEN` (read). `persist` and `recordCleanup` write App-owned check-runs, which GitHub only allows the producing App to update. Pass an installation token the caller minted (`mintInstallationToken`); a job `GITHUB_TOKEN` cannot write those records. There is no `psf` command for this surface.
+`list({ owner, repo, pr }, { token })` works with a workflow `GITHUB_TOKEN` (read). Give that job `permissions: PREVIEW_PROOF_INVENTORY_LIST_PERMISSIONS` (also `previewProofInventory.listPermissions`): `checks: read`, `contents: read`, `pull-requests: read`. A job that omits `pull-requests: read` gets 403 on the PR commit listing for a same-repository PR and discovers nothing (#859). `persist` and `recordCleanup` write App-owned check-runs, which GitHub only allows the producing App to update. Pass an installation token the caller minted (`mintInstallationToken`); a job `GITHUB_TOKEN` cannot write those records. There is no `psf` command for this surface.
 
 `recordCleanup` loads the PR's registrations, applies `previewProofLifecycle.transition(..., { type: "cleanup" })`, then persists. Failed then passed uses that same event; in-memory re-entry from a failed outcome is `previewProofLifecycle.recover`, which calls that transition. Unknown stack or stage, and an identity mismatch on the disposable stage or head SHA, fail closed. Check-runs from another App, including `github-actions`, are ignored.
 

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;
@@ -298,6 +307,20 @@ declare const previewProofLifecycle: {
  */
 /** Check-run name that carries one registration JSON payload. Not a gate. */
 declare 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.
+ */
+declare const PREVIEW_PROOF_INVENTORY_LIST_PERMISSIONS: Readonly<{
+  readonly checks: "read";
+  readonly contents: "read";
+  readonly "pull-requests": "read";
+}>;
 interface PreviewProofInventoryStore {
   list: (input: {
     owner: string;
@@ -371,6 +394,11 @@ declare class PreviewProofTransportError extends Error {
 declare const previewProofInventory: {
   readonly githubStore: (transport: PreviewProofInventoryTransport) => PreviewProofInventoryStore;
   readonly list: (input: PreviewProofInventoryListInput, access: PreviewProofInventoryAccess) => Promise<readonly PreviewProofRegistration[]>;
+  readonly listPermissions: Readonly<{
+    readonly checks: "read";
+    readonly contents: "read";
+    readonly "pull-requests": "read";
+  }>;
   readonly memoryStore: () => PreviewProofInventoryStore;
   readonly persist: (input: PreviewProofInventoryPersistInput, access: PreviewProofInventoryAccess) => Promise<void>;
   readonly recordCleanup: (input: PreviewProofInventoryCleanupInput, access: PreviewProofInventoryAccess) => Promise<PreviewProofRegistration>;
@@ -499,22 +527,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. */
@@ -537,6 +555,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;
@@ -546,8 +579,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.
  *
@@ -663,6 +696,36 @@ declare const FACTORY_PROOF_GATE_GUARD = "steps.factory-proof.outputs.reuse-proo
  * the default branch.
  */
 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).
+ *
+ * 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.
+ */
+declare 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.
+ */
+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.
@@ -746,6 +809,13 @@ 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;
 }
@@ -763,6 +833,7 @@ interface FactoryProofGateOptions {
  */
 declare const factoryProofGateScript: ({
   commands,
+  reuse,
   surface
 }: FactoryProofGateOptions) => string;
 interface FactoryProofGateStep {
@@ -772,7 +843,7 @@ 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;
@@ -785,7 +856,9 @@ 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
@@ -880,8 +953,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>>;
 }
 /**
@@ -930,6 +1008,144 @@ interface FactoryLifecycleContractLane {
  */
 declare const factoryLifecycleContractLane: (declaration?: FactoryLifecycleContractLaneOptions) => FactoryLifecycleContractLane | undefined;
 //#endregion
+//#region src/merge-freeze-job.d.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. */
+declare const FACTORY_MERGE_FREEZE_CHECK_NAME = "patronage-factory/merge-freeze";
+declare const FACTORY_MERGE_FREEZE_JOB_ID = "freeze";
+declare const FACTORY_MERGE_FREEZE_JOB_NAME = "Report the merge freeze";
+/** Step id the token step exposes its installation token under. */
+declare 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.
+ */
+declare 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.
+ */
+declare const FACTORY_MERGE_TARGET_REF_CONDITION: string;
+/**
+ * `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.
+ */
+declare const FACTORY_MERGE_FREEZE_IF: string;
+/**
+ * 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).
+ */
+declare const FACTORY_MERGE_FREEZE_PERMISSIONS: Readonly<{}>;
+/**
+ * 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.
+ */
+declare const factoryMergeFreezeScript: () => string;
+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;
+}
+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.
+ */
+declare const factoryMergeFreezeJob: <TNeed>(options: FactoryMergeFreezeJobOptions<TNeed>) => FactoryMergeFreezeJob<TNeed>;
+//#endregion
 //#region src/pr-status-hud-workflow.d.ts
 declare const FACTORY_PR_STATUS_HUD_JOB_ID = "status-hud";
 declare const FACTORY_PR_STATUS_HUD_JOB_NAME = "Present PR status HUD";
@@ -946,9 +1162,9 @@ interface FactoryPrStatusHudWorkflowOptions {
   readonly createGithubAppToken: PinnedAction;
 }
 /**
- * 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).
  */
 declare const FACTORY_PR_STATUS_HUD_PERMISSIONS: Readonly<{
   readonly checks: "read";
@@ -1023,8 +1239,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>>;
 }
 /**
@@ -1047,7 +1268,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;
@@ -1366,4 +1592,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_PREVIEW_CLEANUP_AUDIT_JOB_ID, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_NAME, FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT, FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT, FACTORY_PRODUCTION_IMPACT_STEP_ID, FACTORY_PRODUCTION_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_PROOF_GATE_APP_ID, FACTORY_PROOF_GATE_CHECK_NAME, FACTORY_PROOF_GATE_GUARD, FACTORY_PROOF_GATE_IF, FACTORY_PROOF_GATE_MODE_OUTPUT, FACTORY_PROOF_GATE_OUTPUT, FACTORY_PROOF_GATE_REASONS, FACTORY_PROOF_GATE_REASON_OUTPUT, FACTORY_PROOF_GATE_SHELL, FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT, FACTORY_PROOF_GATE_STEP_ID, FACTORY_PROOF_GATE_STEP_NAME, FACTORY_PR_STATUS_HUD_APP_TOKEN_STEP_ID, FACTORY_PR_STATUS_HUD_CONCURRENCY, FACTORY_PR_STATUS_HUD_IF, FACTORY_PR_STATUS_HUD_JOB_ID, FACTORY_PR_STATUS_HUD_JOB_NAME, FACTORY_PR_STATUS_HUD_PERMISSIONS, FACTORY_PR_STATUS_HUD_PLAN_PATH, FACTORY_PUSH_IDENTITY_SCHEMA_VERSION, type FactoryCandidateImpactWorkflow, type FactoryCandidateImpactWorkflowOptions, type FactoryLifecycleContractLane, type FactoryLifecycleContractLaneOptions, type FactoryPrStatusHudWorkflow, type FactoryPrStatusHudWorkflowOptions, type FactoryPreviewCleanupAuditJob, type FactoryPreviewCleanupDestroyJob, type FactoryPreviewCleanupTopology, type FactoryPreviewCleanupTopologyOptions, type FactoryProductionImpactWorkflow, type FactoryProductionImpactWorkflowOptions, type FactoryProofGateOptions, type FactoryProofGateReason, 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, 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, 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, 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 };