@patronage/factory-ci 1.0.0-alpha.22 → 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.
 
@@ -379,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.
 
@@ -406,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.

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;
@@ -518,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. */
@@ -556,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;
@@ -565,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.
  *
@@ -939,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>>;
 }
 /**
@@ -1010,6 +1029,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 +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>>;
 }
 /**
@@ -1237,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;
@@ -1556,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_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, 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 };

package/dist/index.js

@@ -32,6 +32,18 @@ const NODE_PNPM_ACTION_FAMILY_NODE24 = {
 		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.
+*/
+const UPLOAD_ARTIFACT = {
+	tag: "v4.6.2",
+	uses: "actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02"
+};
 //#endregion
 //#region src/candidate-lifecycle.ts
 /**
@@ -251,12 +263,10 @@ const transition = (state, event) => {
 				evidence: [],
 				outcome: "pending"
 			},
-			cleanupStatus: "pending",
 			convergence: {
 				detail: event.convergence.detail,
 				status: "passed"
 			},
-			convergenceStatus: "passed",
 			headSha: event.candidate.headSha,
 			pr: event.candidate.pr,
 			proof: {
@@ -269,7 +279,6 @@ const transition = (state, event) => {
 				detail: event.smoke.detail,
 				outcome: "passed"
 			},
-			smokeStatus: "passed",
 			source: "local-self-certified",
 			stack: event.stack,
 			stage,
@@ -288,12 +297,11 @@ const transition = (state, event) => {
 	};
 	return replaceRegistration$1(state, {
 		...existing,
-		cleanup,
-		cleanupStatus: event.outcome
+		cleanup
 	});
 };
 const recover = (state, event) => {
-	if (state.registrations.find((row) => row.pr === event.pr && row.stack === event.stack && row.stage === event.stage)?.cleanupStatus !== "failed") throw new Error("Preview proof recovery re-enters cleanup only from a failed outcome.");
+	if (state.registrations.find((row) => row.pr === event.pr && row.stack === event.stack && row.stage === event.stage)?.cleanup.outcome !== "failed") throw new Error("Preview proof recovery re-enters cleanup only from a failed outcome.");
 	return transition(state, event);
 };
 const previewProofLifecycle = {
@@ -586,7 +594,7 @@ const COMMAND_IDENTITY_MAX_LENGTH = 120;
 * cannot subtract hosted work. This is intentionally fail-closed and moves in
 * lockstep with the proof/check-payload producer.
 */
-const TRUSTED_IMPACT_STAMP_VERSION = 3;
+const TRUSTED_IMPACT_STAMP_VERSION = 4;
 const isProofReuseCommand = (value) => {
 	if (!(value && typeof value === "object")) return false;
 	const entry = value;
@@ -779,7 +787,9 @@ def releaseAuthorized($release; $commands; $stamp):
             type == "object"
             and (.name | nonemptyString)
             and (.basis | nonemptyString)
-            and ((.impact == "affected") or (.impact == "not-affected"))))
+            and ((.impact == "affected") or (.impact == "not-affected"))
+            and ((.subscribedPaths | type) == "array")
+            and (.subscribedPaths | all(.[]; type == "string"))))
           and ($stamp.targets | distinctNames)
           and (([$releases[].name] - $executed | length) == ($releases | length))
           and ($releases | all(.[]; releaseAuthorized(.; $commands; $stamp)))
@@ -1280,7 +1290,7 @@ const readIdentity = (value) => {
 const readCleanup = (value) => {
 	if (!isRecord$1(value.cleanup) || !isCleanupStatus(value.cleanup.outcome)) return null;
 	const evidence = readStringArray(value.cleanup.evidence);
-	if (evidence === null || value.cleanupStatus !== value.cleanup.outcome) return null;
+	if (evidence === null) return null;
 	return typeof value.cleanup.runUrl === "string" && value.cleanup.runUrl.length > 0 ? {
 		evidence,
 		outcome: value.cleanup.outcome,
@@ -1292,7 +1302,7 @@ const readCleanup = (value) => {
 };
 const readPassingChecks = (value) => {
 	if (!isRecord$1(value.convergence) || !isRecord$1(value.smoke)) return null;
-	if (value.convergence.status !== "passed" || value.convergenceStatus !== "passed" || typeof value.convergence.detail !== "string" || value.smoke.outcome !== "passed" || value.smokeStatus !== "passed" || typeof value.smoke.detail !== "string") return null;
+	if (value.convergence.status !== "passed" || typeof value.convergence.detail !== "string" || value.smoke.outcome !== "passed" || typeof value.smoke.detail !== "string") return null;
 	return {
 		convergence: {
 			detail: value.convergence.detail,
@@ -1327,14 +1337,11 @@ const readPreviewProofRegistration = (value) => {
 	if (identity === null || cleanup === null || passing === null || proof === null) return null;
 	return {
 		cleanup,
-		cleanupStatus: cleanup.outcome,
 		convergence: passing.convergence,
-		convergenceStatus: "passed",
 		headSha: identity.headSha,
 		pr: identity.pr,
 		proof,
 		smoke: passing.smoke,
-		smokeStatus: "passed",
 		source: "local-self-certified",
 		stack: identity.stack,
 		stage: identity.stage,
@@ -1492,7 +1499,7 @@ const registrationFromCheckRun = (run, expectedHeadSha) => {
 const checkRunOutput = (registration) => {
 	const title = `Preview proof ${registration.stack}/${registration.stage}`.slice(0, 255);
 	return {
-		summary: `cleanup ${registration.cleanupStatus}`,
+		summary: `cleanup ${registration.cleanup.outcome}`,
 		text: JSON.stringify({
 			kind: INVENTORY_KIND,
 			registration,
@@ -1852,9 +1859,8 @@ const factoryWorkflow = (options) => {
 const EXECUTE_ALCHEMY_ENTRY_MAX_BUFFER = 64 * 1024 * 1024;
 let spawnImplementation = spawnSync;
 const resolveBundledEntry = async (options) => {
-	if (options.bundledEntry !== void 0) return path.resolve(options.cwd ?? options.bundle?.absWorkingDir ?? process.cwd(), options.bundledEntry);
-	if (options.bundle === void 0) throw new Error("executeAlchemyEntry requires bundle or bundledEntry.");
-	return await bundleAlchemyEntry(options.bundle);
+	if (options.bundledEntry === void 0) return await bundleAlchemyEntry(options.bundle);
+	return path.resolve(options.cwd ?? process.cwd(), options.bundledEntry);
 };
 const captured = (text, redact) => {
 	if (text === null || redact === void 0) return text;
@@ -1864,8 +1870,8 @@ const captured = (text, redact) => {
 * 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.
 *
@@ -1971,6 +1977,24 @@ const factoryProofReuseSummaryStep = (options) => Object.freeze({
 	run: factoryProofReuseSummaryScript(options)
 });
 //#endregion
+//#region src/impact-demand-condition.ts
+const impactDemandConditions = (options) => {
+	const targetOutput = (targetName) => {
+		const output = options.targetOutputs[targetName];
+		if (output === void 0) throw new Error(`Unknown ${options.label} impact target "${targetName}".`);
+		return output;
+	};
+	const condition = (source, outcomeKey, output) => `${source}.${outcomeKey} != 'success' || ${source}.outputs.${options.decisionOutput} != 'usable' || ${source}.outputs.${output} != 'withdrawn'`;
+	return Object.freeze({
+		demandedIf: (targetName, decisionJob) => {
+			const output = targetOutput(targetName);
+			if (decisionJob.trim().length === 0) throw new Error(`A cross-job ${options.label} impact condition requires the decision job id.`);
+			return `always() && (${condition(`needs.${decisionJob}`, "result", output)})`;
+		},
+		demandedIfAtStep: (targetName) => condition(`steps.${options.stepId}`, "outcome", targetOutput(targetName))
+	});
+};
+//#endregion
 //#region src/production-impact-workflow.ts
 const FACTORY_PRODUCTION_IMPACT_STEP_ID = "production_impact";
 const FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT = "decision";
@@ -2007,6 +2031,12 @@ const factoryProductionImpactWorkflow = (options) => {
 		name: "Classify production impact",
 		run: `${cli} production:impact --before "$FACTORY_BEFORE_SHA" --after "$FACTORY_AFTER_SHA" --github-output "$GITHUB_OUTPUT" --github-summary "$GITHUB_STEP_SUMMARY"${profile}`
 	};
+	const conditions = impactDemandConditions({
+		decisionOutput: FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT,
+		label: "production",
+		stepId: FACTORY_PRODUCTION_IMPACT_STEP_ID,
+		targetOutputs
+	});
 	return Object.freeze({
 		decisionJobOutputs: Object.freeze({
 			basis: `\${{ steps.${FACTORY_PRODUCTION_IMPACT_STEP_ID}.outputs.${FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT} }}`,
@@ -2015,13 +2045,8 @@ const factoryProductionImpactWorkflow = (options) => {
 			...Object.fromEntries(Object.values(targetOutputs).map((output) => [output, `\${{ steps.${FACTORY_PRODUCTION_IMPACT_STEP_ID}.outputs.${output} }}`]))
 		}),
 		decisionStep: Object.freeze(decisionStep),
-		demandedIf: (targetName, decisionJob) => {
-			const output = targetOutputs[targetName];
-			if (output === void 0) throw new Error(`Unknown production impact target "${targetName}".`);
-			const source = decisionJob ? `needs.${decisionJob}` : `steps.${FACTORY_PRODUCTION_IMPACT_STEP_ID}`;
-			const condition = `${source}.${decisionJob ? "result" : "outcome"} != 'success' || ${source}.outputs.${FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT} != 'usable' || ${source}.outputs.${output} != 'withdrawn'`;
-			return decisionJob ? `always() && (${condition})` : condition;
-		},
+		demandedIf: conditions.demandedIf,
+		demandedIfAtStep: conditions.demandedIfAtStep,
 		targetOutputs: Object.freeze(targetOutputs)
 	});
 };
@@ -2064,6 +2089,12 @@ const factoryCandidateImpactWorkflow = (options) => {
 		name: "Classify candidate impact",
 		run: `${cli} candidate:impact --base "$FACTORY_BASE_SHA" --head "$FACTORY_HEAD_SHA" --github-output "$GITHUB_OUTPUT" --github-summary "$GITHUB_STEP_SUMMARY"${profile}`
 	};
+	const conditions = impactDemandConditions({
+		decisionOutput: FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT,
+		label: "candidate",
+		stepId: FACTORY_CANDIDATE_IMPACT_STEP_ID,
+		targetOutputs
+	});
 	return Object.freeze({
 		decisionJobOutputs: Object.freeze({
 			basis: `\${{ steps.${FACTORY_CANDIDATE_IMPACT_STEP_ID}.outputs.${FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT} }}`,
@@ -2073,13 +2104,8 @@ const factoryCandidateImpactWorkflow = (options) => {
 			...Object.fromEntries(Object.values(targetOutputs).map((output) => [output, `\${{ steps.${FACTORY_CANDIDATE_IMPACT_STEP_ID}.outputs.${output} }}`]))
 		}),
 		decisionStep: Object.freeze(decisionStep),
-		demandedIf: (targetName, decisionJob) => {
-			const output = targetOutputs[targetName];
-			if (output === void 0) throw new Error(`Unknown candidate impact target "${targetName}".`);
-			const source = decisionJob ? `needs.${decisionJob}` : `steps.${FACTORY_CANDIDATE_IMPACT_STEP_ID}`;
-			const condition = `${source}.${decisionJob ? "result" : "outcome"} != 'success' || ${source}.outputs.${FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT} != 'usable' || ${source}.outputs.${output} != 'withdrawn'`;
-			return decisionJob ? `always() && (${condition})` : condition;
-		},
+		demandedIf: conditions.demandedIf,
+		demandedIfAtStep: conditions.demandedIfAtStep,
 		targetOutputs: Object.freeze(targetOutputs)
 	});
 };
@@ -2172,6 +2198,13 @@ const factoryLifecycleContractLane = (declaration) => {
 * `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
@@ -2428,6 +2461,10 @@ const factoryPreviewCleanupTopology = (options) => {
 };
 //#endregion
 //#region src/push-identity-workflow.ts
+/** `owner/repo` slice of the catalog's `UPLOAD_ARTIFACT` pin, derived rather
+* than repeated as a literal, so a repository rename here cannot drift from
+* the pin it validates against. */
+const UPLOAD_ARTIFACT_REPOSITORY = UPLOAD_ARTIFACT.uses.slice(0, UPLOAD_ARTIFACT.uses.indexOf("@"));
 const FACTORY_PUSH_IDENTITY_SCHEMA_VERSION = 1;
 /**
 * The artifact prefix and the five step IDs are module-private. Alpha.13
@@ -2683,7 +2720,7 @@ printf 'disposition=%s\nreason=%s\nbefore=%s\nafter=%s\nprovenance=%s\n' \
 * result when transport is unavailable. Place these steps after verification.
 */
 const factoryPushIdentityProducer = (options) => {
-	assertPinnedAction("uploadArtifact", options.uploadArtifact, "actions/upload-artifact");
+	assertPinnedAction("uploadArtifact", options.uploadArtifact, UPLOAD_ARTIFACT_REPOSITORY);
 	const condition = options.if ? `github.event_name == 'push' && (${options.if})` : "github.event_name == 'push'";
 	const name = artifactName(expression("github.run_id"));
 	return Object.freeze({
@@ -3499,4 +3536,4 @@ const assertWorkflowShellParses = (yaml, options) => {
 	throw new Error(`${options.source} emits shell bash cannot parse; the runner would treat it as a no-op:\n${detail}`);
 };
 //#endregion
-export { EXECUTE_ALCHEMY_ENTRY_MAX_BUFFER, FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT, FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT, FACTORY_CANDIDATE_IMPACT_INERT_OUTPUT, FACTORY_CANDIDATE_IMPACT_STEP_ID, FACTORY_CANDIDATE_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_CANDIDATE_PULL_REQUEST_TYPES, FACTORY_LIFECYCLE_CONTRACT_JOB_ID, FACTORY_LIFECYCLE_CONTRACT_JOB_NAME, FACTORY_MERGE_FREEZE_APP_TOKEN_STEP_ID, FACTORY_MERGE_FREEZE_CHECK_NAME, FACTORY_MERGE_FREEZE_IF, FACTORY_MERGE_FREEZE_JOB_ID, FACTORY_MERGE_FREEZE_JOB_NAME, FACTORY_MERGE_FREEZE_PERMISSIONS, FACTORY_MERGE_FREEZE_VERIFY_RESULT_EXPRESSION, FACTORY_MERGE_TARGET_REF_CONDITION, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_ID, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_NAME, FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT, FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT, FACTORY_PRODUCTION_IMPACT_STEP_ID, FACTORY_PRODUCTION_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_PROOF_GATE_APP_ID, FACTORY_PROOF_GATE_CHECK_NAME, FACTORY_PROOF_GATE_GUARD, FACTORY_PROOF_GATE_IF, FACTORY_PROOF_GATE_MODE_OUTPUT, FACTORY_PROOF_GATE_OUTPUT, FACTORY_PROOF_GATE_PULL_REQUEST_IF, FACTORY_PROOF_GATE_REASONS, FACTORY_PROOF_GATE_REASON_OUTPUT, FACTORY_PROOF_GATE_SHELL, FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT, FACTORY_PROOF_GATE_STEP_ID, FACTORY_PROOF_GATE_STEP_NAME, FACTORY_PR_STATUS_HUD_APP_TOKEN_STEP_ID, FACTORY_PR_STATUS_HUD_CONCURRENCY, FACTORY_PR_STATUS_HUD_IF, FACTORY_PR_STATUS_HUD_JOB_ID, FACTORY_PR_STATUS_HUD_JOB_NAME, FACTORY_PR_STATUS_HUD_PERMISSIONS, FACTORY_PR_STATUS_HUD_PLAN_PATH, FACTORY_PUSH_IDENTITY_SCHEMA_VERSION, GitHubApiError, NODE_PNPM_ACTION_FAMILY_NODE24, PREVIEW_PROOF_INVENTORY_CHECK_NAME, PREVIEW_PROOF_INVENTORY_LIST_PERMISSIONS, PreviewProofTransportError, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, VitestProfileError, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryCandidateImpactWorkflow, factoryCandidateOrPushCondition, factoryLifecycleContractLane, factoryMergeFreezeJob, factoryMergeFreezeScript, factoryPrStatusHudWorkflow, factoryPreviewCleanupTopology, factoryProductionImpactWorkflow, factoryProofGateScript, factoryProofGateStep, factoryProofReuseSummaryStep, factoryProofTimingStartStep, factoryPushIdentityConsumer, factoryPushIdentityProducer, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, previewCleanupDestroyJobId, previewProofInventory, previewProofLifecycle, productionImpactTargetOutput, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };
+export { EXECUTE_ALCHEMY_ENTRY_MAX_BUFFER, FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT, FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT, FACTORY_CANDIDATE_IMPACT_INERT_OUTPUT, FACTORY_CANDIDATE_IMPACT_STEP_ID, FACTORY_CANDIDATE_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_CANDIDATE_PULL_REQUEST_TYPES, FACTORY_LIFECYCLE_CONTRACT_JOB_ID, FACTORY_LIFECYCLE_CONTRACT_JOB_NAME, FACTORY_MERGE_FREEZE_APP_TOKEN_STEP_ID, FACTORY_MERGE_FREEZE_CHECK_NAME, FACTORY_MERGE_FREEZE_IF, FACTORY_MERGE_FREEZE_JOB_ID, FACTORY_MERGE_FREEZE_JOB_NAME, FACTORY_MERGE_FREEZE_PERMISSIONS, FACTORY_MERGE_FREEZE_VERIFY_RESULT_EXPRESSION, FACTORY_MERGE_TARGET_REF_CONDITION, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_ID, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_NAME, FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT, FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT, FACTORY_PRODUCTION_IMPACT_STEP_ID, FACTORY_PRODUCTION_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_PROOF_GATE_APP_ID, FACTORY_PROOF_GATE_CHECK_NAME, FACTORY_PROOF_GATE_GUARD, FACTORY_PROOF_GATE_IF, FACTORY_PROOF_GATE_MODE_OUTPUT, FACTORY_PROOF_GATE_OUTPUT, FACTORY_PROOF_GATE_PULL_REQUEST_IF, FACTORY_PROOF_GATE_REASONS, FACTORY_PROOF_GATE_REASON_OUTPUT, FACTORY_PROOF_GATE_SHELL, FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT, FACTORY_PROOF_GATE_STEP_ID, FACTORY_PROOF_GATE_STEP_NAME, FACTORY_PR_STATUS_HUD_APP_TOKEN_STEP_ID, FACTORY_PR_STATUS_HUD_CONCURRENCY, FACTORY_PR_STATUS_HUD_IF, FACTORY_PR_STATUS_HUD_JOB_ID, FACTORY_PR_STATUS_HUD_JOB_NAME, FACTORY_PR_STATUS_HUD_PERMISSIONS, FACTORY_PR_STATUS_HUD_PLAN_PATH, FACTORY_PUSH_IDENTITY_SCHEMA_VERSION, GitHubApiError, NODE_PNPM_ACTION_FAMILY_NODE24, PREVIEW_PROOF_INVENTORY_CHECK_NAME, PREVIEW_PROOF_INVENTORY_LIST_PERMISSIONS, PreviewProofTransportError, UPLOAD_ARTIFACT, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, VitestProfileError, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryCandidateImpactWorkflow, factoryCandidateOrPushCondition, factoryLifecycleContractLane, factoryMergeFreezeJob, factoryMergeFreezeScript, factoryPrStatusHudWorkflow, factoryPreviewCleanupTopology, factoryProductionImpactWorkflow, factoryProofGateScript, factoryProofGateStep, factoryProofReuseSummaryStep, factoryProofTimingStartStep, factoryPushIdentityConsumer, factoryPushIdentityProducer, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, previewCleanupDestroyJobId, previewProofInventory, previewProofLifecycle, productionImpactTargetOutput, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patronage/factory-ci",
-  "version": "1.0.0-alpha.22",
+  "version": "1.0.0-alpha.23",
   "description": "Deep CI and deploy building blocks for Patronage factory projects: workflow source artifacts, hosted diff classification, Alchemy entry execution, and disposable-stage semantics",
   "keywords": [
     "alchemy",
@@ -48,7 +48,7 @@
     "node": "^24.0.0"
   },
   "scripts": {
-    "cleanup:check": "knip --files --dependencies",
+    "cleanup:check": "knip --files --dependencies --exports",
     "prebuild": "bash ../scripts/ensure-worktree-bootstrap.sh",
     "build": "tsdown",
     "precheck": "bash ../scripts/ensure-worktree-bootstrap.sh",

package/src/actions.ts

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

package/src/candidate-impact-workflow.ts

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

package/src/execute-alchemy-entry.ts

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

package/src/impact-demand-condition.ts

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

package/src/index.ts

@@ -12,6 +12,7 @@ export {
   NODE_PNPM_ACTION_FAMILY_NODE24,
   type NodePnpmActionFamily,
   type PinnedAction,
+  UPLOAD_ARTIFACT,
 } from "./actions.ts";
 export {
   FACTORY_CANDIDATE_PULL_REQUEST_TYPES,

package/src/merge-freeze-job.ts

@@ -23,6 +23,13 @@ import { FACTORY_PROOF_GATE_APP_ID } from "./proof-reuse-gate.ts";
  * `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

package/src/preview-proof-inventory.ts

@@ -193,7 +193,7 @@ const readCleanup = (value: Record<string, unknown>) => {
     return null;
   }
   const evidence = readStringArray(value.cleanup.evidence);
-  if (evidence === null || value.cleanupStatus !== value.cleanup.outcome) {
+  if (evidence === null) {
     return null;
   }
   return typeof value.cleanup.runUrl === "string" &&
@@ -212,10 +212,8 @@ const readPassingChecks = (value: Record<string, unknown>) => {
   }
   if (
     value.convergence.status !== "passed" ||
-    value.convergenceStatus !== "passed" ||
     typeof value.convergence.detail !== "string" ||
     value.smoke.outcome !== "passed" ||
-    value.smokeStatus !== "passed" ||
     typeof value.smoke.detail !== "string"
   ) {
     return null;
@@ -276,14 +274,11 @@ const readPreviewProofRegistration = (
   }
   return {
     cleanup,
-    cleanupStatus: cleanup.outcome,
     convergence: passing.convergence,
-    convergenceStatus: "passed",
     headSha: identity.headSha,
     pr: identity.pr,
     proof,
     smoke: passing.smoke,
-    smokeStatus: "passed",
     source: "local-self-certified",
     stack: identity.stack,
     stage: identity.stage,
@@ -604,7 +599,7 @@ const checkRunOutput = (registration: PreviewProofRegistration) => {
   const title =
     `Preview proof ${registration.stack}/${registration.stage}`.slice(0, 255);
   return {
-    summary: `cleanup ${registration.cleanupStatus}`,
+    summary: `cleanup ${registration.cleanup.outcome}`,
     text: JSON.stringify({
       kind: INVENTORY_KIND,
       registration,

package/src/preview-proof-lifecycle.ts

@@ -49,9 +49,7 @@ export 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: {
@@ -61,7 +59,6 @@ export interface PreviewProofRegistration {
     readonly patchId: string;
   };
   readonly smoke: { readonly detail: string; readonly outcome: "passed" };
-  readonly smokeStatus: "passed";
   readonly source: "local-self-certified";
   readonly stack: string;
   readonly stage: LocalPreviewStage;
@@ -239,12 +236,10 @@ const transition = (
 
     return replaceRegistration(state, {
       cleanup: { evidence: [], outcome: "pending" },
-      cleanupStatus: "pending",
       convergence: {
         detail: event.convergence.detail,
         status: "passed",
       },
-      convergenceStatus: "passed",
       headSha: event.candidate.headSha,
       pr: event.candidate.pr,
       proof: {
@@ -254,7 +249,6 @@ const transition = (
         patchId: event.evidence.patchId,
       },
       smoke: { detail: event.smoke.detail, outcome: "passed" },
-      smokeStatus: "passed",
       source: "local-self-certified",
       stack: event.stack,
       stage,
@@ -286,7 +280,6 @@ const transition = (
   return replaceRegistration(state, {
     ...existing,
     cleanup,
-    cleanupStatus: event.outcome,
   });
 };
 
@@ -300,7 +293,7 @@ const recover = (
       row.stack === event.stack &&
       row.stage === event.stage
   );
-  if (existing?.cleanupStatus !== "failed") {
+  if (existing?.cleanup.outcome !== "failed") {
     throw new Error(
       "Preview proof recovery re-enters cleanup only from a failed outcome."
     );

package/src/production-impact-workflow.ts

@@ -1,4 +1,5 @@
 import type { WorkflowStep } from "./factory-workflow.ts";
+import { impactDemandConditions } from "./impact-demand-condition.ts";
 
 export const FACTORY_PRODUCTION_IMPACT_STEP_ID = "production_impact";
 export const FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT = "decision";
@@ -36,8 +37,13 @@ export 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>>;
 }
 
@@ -79,6 +85,13 @@ export const factoryProductionImpactWorkflow = (
     run: `${cli} production:impact --before "$FACTORY_BEFORE_SHA" --after "$FACTORY_AFTER_SHA" --github-output "$GITHUB_OUTPUT" --github-summary "$GITHUB_STEP_SUMMARY"${profile}`,
   };
 
+  const conditions = impactDemandConditions({
+    decisionOutput: FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT,
+    label: "production",
+    stepId: FACTORY_PRODUCTION_IMPACT_STEP_ID,
+    targetOutputs,
+  });
+
   return Object.freeze({
     decisionJobOutputs: Object.freeze({
       basis: `\${{ steps.${FACTORY_PRODUCTION_IMPACT_STEP_ID}.outputs.${FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT} }}`,
@@ -92,18 +105,8 @@ export const factoryProductionImpactWorkflow = (
       ),
     }),
     decisionStep: Object.freeze(decisionStep),
-    demandedIf: (targetName: string, decisionJob?: string) => {
-      const output = targetOutputs[targetName];
-      if (output === undefined) {
-        throw new Error(`Unknown production impact target "${targetName}".`);
-      }
-      const source = decisionJob
-        ? `needs.${decisionJob}`
-        : `steps.${FACTORY_PRODUCTION_IMPACT_STEP_ID}`;
-      const outcome = decisionJob ? "result" : "outcome";
-      const condition = `${source}.${outcome} != 'success' || ${source}.outputs.${FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT} != 'usable' || ${source}.outputs.${output} != 'withdrawn'`;
-      return decisionJob ? `always() && (${condition})` : condition;
-    },
+    demandedIf: conditions.demandedIf,
+    demandedIfAtStep: conditions.demandedIfAtStep,
     targetOutputs: Object.freeze(targetOutputs),
   });
 };

package/src/proof-reuse-gate.ts

@@ -245,7 +245,7 @@ const COMMAND_IDENTITY_MAX_LENGTH = 120;
  * cannot subtract hosted work. This is intentionally fail-closed and moves in
  * lockstep with the proof/check-payload producer.
  */
-const TRUSTED_IMPACT_STAMP_VERSION = 3;
+const TRUSTED_IMPACT_STAMP_VERSION = 4;
 
 const isProofReuseCommand = (value: unknown): value is ProofReuseCommand => {
   if (!(value && typeof value === "object")) {
@@ -464,7 +464,9 @@ def releaseAuthorized($release; $commands; $stamp):
             type == "object"
             and (.name | nonemptyString)
             and (.basis | nonemptyString)
-            and ((.impact == "affected") or (.impact == "not-affected"))))
+            and ((.impact == "affected") or (.impact == "not-affected"))
+            and ((.subscribedPaths | type) == "array")
+            and (.subscribedPaths | all(.[]; type == "string"))))
           and ($stamp.targets | distinctNames)
           and (([$releases[].name] - $executed | length) == ($releases | length))
           and ($releases | all(.[]; releaseAuthorized(.; $commands; $stamp)))

package/src/push-identity-workflow.ts

@@ -1,7 +1,16 @@
+import { UPLOAD_ARTIFACT } from "./actions.ts";
 import type { PinnedAction } from "./actions.ts";
 import type { WorkflowStep } from "./factory-workflow.ts";
 import { assertPinnedAction } from "./pinned-action.ts";
 
+/** `owner/repo` slice of the catalog's `UPLOAD_ARTIFACT` pin, derived rather
+ * than repeated as a literal, so a repository rename here cannot drift from
+ * the pin it validates against. */
+const UPLOAD_ARTIFACT_REPOSITORY = UPLOAD_ARTIFACT.uses.slice(
+  0,
+  UPLOAD_ARTIFACT.uses.indexOf("@")
+);
+
 export const FACTORY_PUSH_IDENTITY_SCHEMA_VERSION = 1;
 /**
  * The artifact prefix and the five step IDs are module-private. Alpha.13
@@ -271,7 +280,12 @@ printf 'disposition=%s\nreason=%s\nbefore=%s\nafter=%s\nprovenance=%s\n' \
 } >> "$GITHUB_STEP_SUMMARY"`;
 
 export 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;
@@ -292,7 +306,7 @@ export const factoryPushIdentityProducer = (
   assertPinnedAction(
     "uploadArtifact",
     options.uploadArtifact,
-    "actions/upload-artifact"
+    UPLOAD_ARTIFACT_REPOSITORY
   );
   const condition = options.if
     ? `github.event_name == 'push' && (${options.if})`