@patronage/factory-ci 1.0.0-alpha.8 → 1.0.0-alpha.9

package/README.md

@@ -20,7 +20,10 @@ The admission rule is **upstream on repetition**: nothing enters this package un
 
 ```ts
 import {
+  FACTORY_CANDIDATE_PULL_REQUEST_TYPES,
+  factoryProductionImpactWorkflow,
   factoryWorkflow,
+  factoryCandidateOrPushCondition,
   NODE_PNPM_ACTION_FAMILY_NODE24,
 } from "@patronage/factory-ci";
 ```
@@ -47,6 +50,7 @@ const generated = factoryWorkflow({
     regenerate: "pnpm workflows:generate",
   },
   setup: {
+    checkout: { fetchDepth: 0, ref: "${{ github.sha }}" },
     setupNode: { cacheDependencyPath: "pnpm-lock.yaml" },
   },
 });
@@ -59,6 +63,45 @@ workflow({/* caller-owned jobs and topology */}).writeOrLint({
 
 The **runner is not this package's business**. Jobs, runners, permissions, workflow topology, and deploy policy remain with the caller. The returned values are plain structural objects; this package does not depend on gagen.
 
+Candidate lifecycle support follows the same boundary. Use `FACTORY_CANDIDATE_PULL_REQUEST_TYPES` for the pull-request trigger matrix and `factoryCandidateOrPushCondition()` on each substantive job. With an optional caller-owned path condition, the helper emits the GitHub expression that runs merge-target pushes unconditionally and runs pull-request work only when GitHub's draft boolean says the pull request is a Candidate:
+
+```ts
+const changes = job("changes", {
+  if: factoryCandidateOrPushCondition(),
+  // caller-owned runner, permissions, and steps
+});
+
+const core = job("core", {
+  if: factoryCandidateOrPushCondition("needs.changes.outputs.core == 'true'"),
+  // caller-owned topology
+});
+```
+
+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:
+
+```ts
+const impact = factoryProductionImpactWorkflow({
+  targets: profile.impact?.targets.map(({ name }) => name) ?? [],
+});
+
+const decide = job("impact", {
+  outputs: impact.decisionJobOutputs,
+  steps: [...setupSteps, impact.decisionStep],
+});
+
+const deployWebsite = job("deploy-website", {
+  if: impact.demandedIf("website", "impact"),
+  needs: [decide],
+  // consumer-owned runner, credentials, deploy commands, and convergence
+});
+```
+
+The step calls `psf production:impact` with the merge push's exact `before` and `after` commits. It is `continue-on-error`, and every generated target condition keeps work demanded unless the command succeeded, reported a usable decision, and explicitly withdrew that target. The artifact with an empty target list generates no deploy jobs because job creation remains with the consumer. This package does not own target declarations, deploy topology, credentials, commands, or convergence/no-op proof.
+
+The decision checkout must make both push identities reachable. Use `factoryWorkflow({ setup: { checkout: { fetchDepth: 0, ref: "${{ github.sha }}" } } })`; a shallow checkout is safe but deliberately refuses withdrawal because the `before` commit is unreadable.
+
 ### Generated shell
 
 ```ts
@@ -90,6 +133,8 @@ import {
   assertProofReuseCoverage,
   FACTORY_PROOF_GATE_GUARD,
   factoryProofGateStep,
+  factoryProofReuseSummaryStep,
+  factoryProofTimingStartStep,
 } from "@patronage/factory-ci";
 
 import profile from "../../software-factory.profile.json" with { type: "json" };
@@ -102,14 +147,16 @@ const core = job("core", {
   permissions: { checks: "read", contents: "read" },
   steps: [
     step(factoryProofGateStep({ commands: coreCommands, surface: "core" })),
+    step(factoryProofTimingStartStep()),
     ...guardedSteps.map((s) => ({ ...s, if: FACTORY_PROOF_GATE_GUARD })),
+    step(factoryProofReuseSummaryStep({ surface: "core" })),
   ],
 });
 ```
 
 The **proof-reuse gate** decides whether a hosted job may reuse the local verification the factory already published for this exact head (ADR 0022). Refusing runs hosted CI; it never fails the candidate. The App identity, check name, step id, output names, guard, and every trust predicate are fixed here rather than consumer-configurable — three repositories had grown three answers to the same question and had already drifted.
 
-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. `mode` is reported as diagnostic metadata, never authorized on: a reduced-mode proof that ran everything a surface requires is reusable.
+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.
 
@@ -121,6 +168,8 @@ The gate is a **step, not a job**, marked `continue-on-error`, with no `set -e`.
 
 `assertProofReuseCoverage({ commands, skipped, surface })` is the compile-time guard in front of the runtime `incomplete` refusal: hand it the same selection and the command strings the workflow would skip, and it fails the consumer's build when the two drift apart. Coverage is exact executable coverage. The deprecated `equivalents` input remains only for patch-release source compatibility and is ignored; prose cannot authorize a skip. Extracting the skipped strings stays with the consumer — this package never parses workflow source, because establishing trust that way is what killed an earlier attempt.
 
+`factoryProofTimingStartStep()` and `factoryProofReuseSummaryStep()` replace consumer-local proof timing summaries without taking over workflow topology. Put the start step immediately after the gate and the summary step after the guarded work. The helpers keep the established `Start CI timing` / `Record proof-reuse timing` names and distinguish pull-request reuse, pull-request full fallback, and merge-target full execution where the PR-only gate is explicitly not applicable. Reuse links the exact source check and bound head; every path emits a cheap Actions notice. Both steps are `continue-on-error`: missing timing support or an unwritable presentation destination cannot change a required job's conclusion. These helpers change no trust predicate or guard.
+
 ### Alchemy entries
 
 ```ts
@@ -205,7 +254,7 @@ The credential env-block helper that the audit found repeated was deliberately c
 
 ## Releases
 
-Attended and hand-cut, on the same terms as `@patronage/alchemy-d1-state`: bump the version, run the workspace checks, read the `npm pack --dry-run` file list, publish, tag `factory-ci@<version>`. There is no changesets setup and no automatic release trigger, by design. Consumers pin exact versions.
+Attended and hand-cut, on the same terms as `@patronage/alchemy-d1-state`: bump the version, run the workspace checks, read the `npm pack --dry-run` file list, build and approve one pnpm tarball, publish that exact tarball with an explicit channel tag, then tag `factory-ci@<version>`. Publishing the package directory is not allowed because its `prepack` build would replace the reviewed bytes. There is no changesets setup and no automatic release trigger, by design. Consumers pin exact versions.
 
 ## License
 

package/dist/index.d.ts

@@ -54,6 +54,21 @@ declare const NODE_PNPM_ACTION_FAMILY_NODE24: {
   };
 };
 //#endregion
+//#region src/candidate-lifecycle.d.ts
+/**
+ * Pull-request events that can create or refresh a Factory candidate run.
+ *
+ * GitHub's draft boolean remains the lifecycle authority: these triggers make
+ * a run visible, while `factoryCandidateOrPushCondition` keeps substantive
+ * jobs idle until the pull request is a candidate.
+ */
+declare const FACTORY_CANDIDATE_PULL_REQUEST_TYPES: readonly ["opened", "synchronize", "reopened", "ready_for_review"];
+/**
+ * Build a GitHub Actions job condition for candidate PRs and merge-target
+ * pushes. The caller owns triggers, jobs, runners, permissions, and topology.
+ */
+declare const factoryCandidateOrPushCondition: (candidateCondition?: string) => string;
+//#endregion
 //#region src/bundle-alchemy-entry.d.ts
 interface BundleAlchemyEntryOptions {
   /** The Alchemy entry to bundle, e.g. `alchemy.run.ts`. */
@@ -148,12 +163,16 @@ declare const localPreviewStage: (options: LocalPreviewStageOptions) => LocalPre
 //#endregion
 //#region src/factory-workflow.d.ts
 interface WorkflowStep {
+  readonly continueOnError?: boolean;
+  readonly env?: Readonly<Record<string, string>>;
+  readonly id?: string;
   readonly name: string;
   readonly uses?: string;
   readonly with?: Readonly<Record<string, string>>;
   readonly run?: string;
 }
 interface CheckoutStepOptions {
+  readonly fetchDepth?: number;
   readonly name?: string;
   readonly ref?: string;
 }
@@ -368,6 +387,8 @@ declare const FACTORY_PROOF_GATE_REASON_OUTPUT = "reason";
  * proof that executed every command the surface requires is reusable.
  */
 declare const FACTORY_PROOF_GATE_MODE_OUTPUT = "mode";
+/** Exact Checks API URL of the proof generation selected by the gate. */
+declare const FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT = "source-check-url";
 /**
  * Guard for every step the gate protects. Deliberately `!= 'true'` and not
  * `== 'false'`: an unset, empty, or garbled output must run the suite.
@@ -388,7 +409,8 @@ declare const FACTORY_PROOF_GATE_IF = "github.event_name == 'pull_request'";
  * - `pending`    the newest generation had not completed when this job read it
  * - `failed`     the newest generation records no pass
  * - `unreadable` it passed but carries no binding for this repository and head
- * - `incomplete` it passed but did not execute every required command
+ * - `incomplete` its executed plus stamp-authorized released commands do not
+ *                cover every required command
  * - `ambiguous`  two newest generations share the greatest start time
  * - `error`      the gate could not reach a decision (fail open)
  *
@@ -547,6 +569,64 @@ declare const proofReuseCoverage: ({
 /** `proofReuseCoverage`, as a build failure. */
 declare const assertProofReuseCoverage: (input: ProofReuseCoverageInput) => ProofReuseCoverageReport;
 //#endregion
+//#region src/proof-reuse-presentation.d.ts
+/** Generic timing and presentation steps around the proof-reuse gate (#652). */
+declare const FACTORY_PROOF_TIMING_STEP_ID = "ci-timing";
+declare const FACTORY_PROOF_TIMING_START_STEP_NAME = "Start CI timing";
+declare const FACTORY_PROOF_TIMING_SUMMARY_STEP_NAME = "Record proof-reuse timing";
+interface FactoryProofReusePresentationOptions {
+  /** Human-readable name of the guarded suite. */
+  readonly surface: string;
+}
+interface FactoryProofTimingStartStep {
+  readonly continueOnError: true;
+  readonly id: typeof FACTORY_PROOF_TIMING_STEP_ID;
+  readonly name: typeof FACTORY_PROOF_TIMING_START_STEP_NAME;
+  readonly run: string;
+}
+declare const factoryProofTimingStartStep: () => FactoryProofTimingStartStep;
+declare const factoryProofReuseSummaryScript: ({
+  surface
+}: FactoryProofReusePresentationOptions) => string;
+interface FactoryProofReuseSummaryStep {
+  readonly continueOnError: true;
+  readonly env: Readonly<Record<string, string>>;
+  readonly if: "always()";
+  readonly name: typeof FACTORY_PROOF_TIMING_SUMMARY_STEP_NAME;
+  readonly run: string;
+}
+declare const factoryProofReuseSummaryStep: (options: FactoryProofReusePresentationOptions) => FactoryProofReuseSummaryStep;
+//#endregion
+//#region src/production-impact-workflow.d.ts
+declare const FACTORY_PRODUCTION_IMPACT_STEP_ID = "production_impact";
+declare const FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT = "decision";
+declare const FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT = "basis";
+declare const FACTORY_PRODUCTION_IMPACT_UNSUBSCRIBED_OUTPUT = "unsubscribed_paths";
+/** Stable GitHub-output key for one declared target. */
+declare const productionImpactTargetOutput: (targetName: string) => string;
+interface FactoryProductionImpactWorkflowOptions {
+  readonly after?: string;
+  readonly before?: string;
+  readonly cli?: string;
+  readonly profilePath?: string;
+  readonly targets: readonly string[];
+}
+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;
+  readonly targetOutputs: Readonly<Record<string, string>>;
+}
+/**
+ * Generate the small factory-owned decision seam for a consumer production
+ * workflow. Consumers retain jobs, deploy commands, credentials, topology,
+ * and convergence checks; this artifact supplies only the decision step and
+ * per-target withdrawal conditions.
+ */
+declare const factoryProductionImpactWorkflow: (options: FactoryProductionImpactWorkflowOptions) => FactoryProductionImpactWorkflow;
+//#endregion
 //#region src/vitest-profile.d.ts
 /** Schema version of the emitted profile document. */
 declare const VITEST_PROFILE_SCHEMA_VERSION = 1;
@@ -828,4 +908,4 @@ declare const assertWorkflowShellParses: (yaml: string, options: {
   readonly source: string;
 }) => void;
 //#endregion
-export { type BundleAlchemyEntryOptions, type CheckoutStepOptions, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, 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_STEP_ID, FACTORY_PROOF_GATE_STEP_NAME, type FactoryProofGateOptions, type FactoryProofGateReason, type FactoryProofGateStep, type FactoryWorkflowArtifact, type FactoryWorkflowOptions, type FactoryWorkflowSetupOptions, GitHubApiError, type GithubAppCredentials, type GithubAppTokenOptions, type InstallStepOptions, type LocalPreviewStage, type LocalPreviewStageOptions, NODE_PNPM_ACTION_FAMILY_NODE24, type NodePnpmActionFamily, type ParseLocalPreviewStageExpected, type ParsedLocalPreviewStage, type PinnedAction, 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, factoryProofGateScript, factoryProofGateStep, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };
+export { type BundleAlchemyEntryOptions, type CheckoutStepOptions, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, FACTORY_CANDIDATE_PULL_REQUEST_TYPES, 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_PROOF_TIMING_START_STEP_NAME, FACTORY_PROOF_TIMING_STEP_ID, FACTORY_PROOF_TIMING_SUMMARY_STEP_NAME, type FactoryProductionImpactWorkflow, type FactoryProductionImpactWorkflowOptions, type FactoryProofGateOptions, type FactoryProofGateReason, type FactoryProofGateStep, type FactoryProofReusePresentationOptions, type FactoryProofReuseSummaryStep, type FactoryProofTimingStartStep, type FactoryWorkflowArtifact, type FactoryWorkflowOptions, type FactoryWorkflowSetupOptions, GitHubApiError, type GithubAppCredentials, type GithubAppTokenOptions, type InstallStepOptions, type LocalPreviewStage, type LocalPreviewStageOptions, NODE_PNPM_ACTION_FAMILY_NODE24, type NodePnpmActionFamily, type ParseLocalPreviewStageExpected, type ParsedLocalPreviewStage, type PinnedAction, 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, factoryCandidateOrPushCondition, factoryProductionImpactWorkflow, factoryProofGateScript, factoryProofGateStep, factoryProofReuseSummaryScript, factoryProofReuseSummaryStep, factoryProofTimingStartStep, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, productionImpactTargetOutput, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };

package/dist/index.js

@@ -32,6 +32,32 @@ const NODE_PNPM_ACTION_FAMILY_NODE24 = {
 	}
 };
 //#endregion
+//#region src/candidate-lifecycle.ts
+/**
+* Pull-request events that can create or refresh a Factory candidate run.
+*
+* GitHub's draft boolean remains the lifecycle authority: these triggers make
+* a run visible, while `factoryCandidateOrPushCondition` keeps substantive
+* jobs idle until the pull request is a candidate.
+*/
+const FACTORY_CANDIDATE_PULL_REQUEST_TYPES = Object.freeze([
+	"opened",
+	"synchronize",
+	"reopened",
+	"ready_for_review"
+]);
+/**
+* Build a GitHub Actions job condition for candidate PRs and merge-target
+* pushes. The caller owns triggers, jobs, runners, permissions, and topology.
+*/
+const factoryCandidateOrPushCondition = (candidateCondition) => {
+	return ["github.event_name == 'push'", `(${[
+		"github.event_name == 'pull_request'",
+		"github.event.pull_request.draft != true",
+		...candidateCondition ? [candidateCondition] : []
+	].join(" && ")})`].join(" || ");
+};
+//#endregion
 //#region src/bundle-alchemy-entry.ts
 /**
 * Alchemy and Effect must resolve from the *consumer's* node_modules at run
@@ -208,15 +234,26 @@ const assertAdditionalActions = (actions) => {
 		assertPinnedAction(name, action);
 	}
 };
+const checkoutInputs = (checkout) => {
+	if (checkout === void 0) return;
+	const inputs = {};
+	if (checkout.fetchDepth !== void 0) {
+		if (!Number.isSafeInteger(checkout.fetchDepth) || checkout.fetchDepth < 0) throw new Error("checkout.fetchDepth must be a non-negative integer.");
+		inputs["fetch-depth"] = String(checkout.fetchDepth);
+	}
+	if (checkout.ref) inputs.ref = checkout.ref;
+	return Object.keys(inputs).length > 0 ? inputs : void 0;
+};
 const setupSteps = (family, setup = {}) => {
 	const installRun = setup.install?.run ?? "pnpm install --frozen-lockfile";
 	if (/(?:^|\s)--ignore-scripts(?:\s|$)/u.test(installRun)) throw new Error("The install step must not use --ignore-scripts; workspace prepare scripts build required package artifacts.");
 	const { checkout, setupNode } = setup;
+	const checkoutWith = checkoutInputs(checkout);
 	return Object.freeze([
 		{
 			name: checkout?.name ?? "Checkout",
 			uses: family.checkout.uses,
-			...checkout?.ref ? { with: { ref: checkout.ref } } : {}
+			...checkoutWith ? { with: checkoutWith } : {}
 		},
 		usesStep("Setup pnpm", family.setupPnpm),
 		{
@@ -403,9 +440,9 @@ const executeAlchemyEntry = async (options) => {
 * Escaped so the emitted text carries a GitHub Actions expression rather than
 * this file carrying a JavaScript template hole.
 */
-const githubExpression = (expression) => `\${{ ${expression} }}`;
+const githubExpression$1 = (expression) => `\${{ ${expression} }}`;
 /** A braced shell expansion that has to survive TypeScript interpolation. */
-const shellExpansion = (expression) => `\${${expression}}`;
+const shellExpansion$1 = (expression) => `\${${expression}}`;
 /**
 * Single-quote a value for the emitted script. Every non-literal value that
 * reaches the script goes through this.
@@ -478,6 +515,8 @@ const FACTORY_PROOF_GATE_REASON_OUTPUT = "reason";
 * proof that executed every command the surface requires is reusable.
 */
 const FACTORY_PROOF_GATE_MODE_OUTPUT = "mode";
+/** Exact Checks API URL of the proof generation selected by the gate. */
+const FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT = "source-check-url";
 /**
 * Guard for every step the gate protects. Deliberately `!= 'true'` and not
 * `== 'false'`: an unset, empty, or garbled output must run the suite.
@@ -498,7 +537,8 @@ const FACTORY_PROOF_GATE_IF = "github.event_name == 'pull_request'";
 * - `pending`    the newest generation had not completed when this job read it
 * - `failed`     the newest generation records no pass
 * - `unreadable` it passed but carries no binding for this repository and head
-* - `incomplete` it passed but did not execute every required command
+* - `incomplete` its executed plus stamp-authorized released commands do not
+*                cover every required command
 * - `ambiguous`  two newest generations share the greatest start time
 * - `error`      the gate could not reach a decision (fail open)
 *
@@ -532,6 +572,13 @@ const FACTORY_PROOF_GATE_REASONS = [
 */
 const COMMAND_IDENTITY = /^\w[\w.:@/-]*$/u;
 const COMMAND_IDENTITY_MAX_LENGTH = 120;
+/**
+* The impact-stamp interpretation the paired factory packages currently
+* share. A release recorded under any other version is an unmodelled input and
+* 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 isProofReuseCommand = (value) => {
 	if (!(value && typeof value === "object")) return false;
 	const entry = value;
@@ -599,7 +646,7 @@ const resolveProofReuseCommands = (catalog, names, selectionLabel) => names.map(
 });
 /**
 * jq program: every page of the Checks API result in, three sanitized lines
-* (`reason`, `mode`, missing commands) out.
+* (`reason`, `mode`, uncovered commands) out.
 *
 * The input is what `gh api --paginate` actually writes: the pages
 * *concatenated* as a stream of top-level response objects, not merged into
@@ -656,6 +703,20 @@ def startedAt: (.started_at // "") | tostring;
 def rankable:
   test("^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]+)?Z$");
 
+def nonemptyString:
+  type == "string" and length > 0;
+
+def distinctNames:
+  (map(.name) | length) == (map(.name) | unique | length);
+
+def releaseAuthorized($release; $commands; $stamp):
+  ([ $commands[] | select(.name == $release.name) ]) as $commandRows
+  | ([ $stamp.targets[] | select(.name == $release.impactTarget) ]) as $targetRows
+  | ($commandRows | length) == 1
+    and $commandRows[0].impactTarget == $release.impactTarget
+    and ($targetRows | length) == 1
+    and $targetRows[0].impact == "not-affected";
+
 [ .[]
   | (.check_runs // [])[]
   | select(.name == $name)
@@ -663,20 +724,60 @@ def rankable:
   | { started: startedAt,
       status: (.status // ""),
       conclusion: (.conclusion // ""),
+      url: ((.html_url // "") | tostring),
       binding: binding }
 ] as $runs
 | ($runs | map(.started | rankable) | all) as $orderable
 | ($runs | map(.started | sub("\\.[0-9]+Z$"; "Z")) | max) as $newest
 | [ $runs[] | select((.started | sub("\\.[0-9]+Z$"; "Z")) == $newest) ] as $generation
-| (if ($runs | length) == 0 then ["none", "", ""]
-   elif ($orderable | not) then ["ambiguous", "", ""]
-   elif ($generation | length) != 1 then ["ambiguous", "", ""]
+| (if ($runs | length) == 0 then ["none", "", "", ""]
+   elif ($orderable | not) then ["ambiguous", "", "", ""]
+   elif ($generation | length) != 1 then ["ambiguous", "", "", ""]
    else
      $generation[0] as $run
      | (if ($run.binding | type) == "object" then $run.binding else {} end) as $proof
      | (($proof.mode // "") | tostring) as $mode
      | (($proof.executedCommands // []) | map(select(type == "string"))) as $executed
-     | ($required - $executed) as $missing
+     | ($proof | has("notRequiredCommands")) as $hasReleases
+     | (if $hasReleases then $proof.notRequiredCommands else [] end) as $releases
+     | ($proof.verificationCommands // null) as $commands
+     | ($proof.impactStamp // null) as $stamp
+     | (if ($hasReleases | not) then true
+        else
+          ($proof.proofSchemaVersion == 4)
+          and ($releases | type) == "array"
+          and ($releases | length) > 0
+          and ($releases | all(.[];
+            type == "object"
+            and (.name | nonemptyString)
+            and (.impactTarget | nonemptyString)
+            and (.basis | nonemptyString)))
+          and ($releases | distinctNames)
+          and ($commands | type) == "array"
+          and ($commands | all(.[];
+            type == "object"
+            and (.name | nonemptyString)
+            and ((has("impactTarget") | not) or (.impactTarget | nonemptyString))))
+          and ($commands | distinctNames)
+          and ($stamp | type) == "object"
+          and ($stamp.stampVersion == ${TRUSTED_IMPACT_STAMP_VERSION})
+          and ($stamp.basis == "target-scoped")
+          and (($stamp.reasons | type) == "array")
+          and ($stamp.reasons | all(.[]; type == "string"))
+          and (($stamp.unsubscribedPaths | type) == "array")
+          and ($stamp.unsubscribedPaths | all(.[]; type == "string"))
+          and (($stamp.targets | type) == "array")
+          and ($stamp.targets | all(.[];
+            type == "object"
+            and (.name | nonemptyString)
+            and (.basis | nonemptyString)
+            and ((.impact == "affected") or (.impact == "not-affected"))))
+          and ($stamp.targets | distinctNames)
+          and (([$releases[].name] - $executed | length) == ($releases | length))
+          and ($releases | all(.[]; releaseAuthorized(.; $commands; $stamp)))
+        end) as $releasesValid
+     | (if $releasesValid then [$releases[].name] else [] end) as $released
+     | ($required - $executed - $released) as $missing
      | (if $run.status != "completed" then "pending"
         elif $run.conclusion != "success" then "failed"
         elif (($run.binding | type) != "object")
@@ -686,10 +787,11 @@ def rankable:
           or ($proof.repository != $repository) then "unreadable"
         elif $proof.outcome != "passed" then "failed"
         elif ($required | length) == 0 then "incomplete"
+        elif ($releasesValid | not) then "incomplete"
         elif ($missing | length) != 0 then "incomplete"
         else "proven"
         end) as $reason
-     | [$reason, $mode, ($missing | join(", "))]
+     | [$reason, $mode, ($missing | join(", ")), $run.url]
    end)
 | map(gsub("[\\r\\n\\t]"; " "))
 | join("\n")
@@ -714,9 +816,9 @@ const CORRECTIVE_LINE = "Run `psf pr:verify` before publishing to reuse local pr
 const UNUSABLE_SELECTION_SCRIPT = String.raw`{
   printf '${FACTORY_PROOF_GATE_OUTPUT}=false\n'
   printf '${FACTORY_PROOF_GATE_REASON_OUTPUT}=error\n'
-} >> "${shellExpansion("GITHUB_OUTPUT:-/dev/null")}"`;
+} >> "${shellExpansion$1("GITHUB_OUTPUT:-/dev/null")}"`;
 /** Surface labels reach markdown, so only a plain, bounded label survives. */
-const safeLabel = (surface) => {
+const safeLabel$1 = (surface) => {
 	const cleaned = (typeof surface === "string" ? surface : "").replaceAll(/[^\w -]/gu, "").trim().slice(0, 60);
 	return cleaned.length > 0 ? cleaned : "verification";
 };
@@ -732,14 +834,15 @@ reason=error
 detail=''
 mode=''
 missing=''
+source_url=''
 
 # filter=all with full pagination is load-bearing (ADR 0022). GitHub's
 # default "latest" filter is ordered by completion, so a newer generation
 # that is still running can be hidden behind an older completed one — the
 # gate would then read a stale pass as current.
-if [ -z "${shellExpansion("HEAD_SHA:-")}" ]; then
+if [ -z "${shellExpansion$1("HEAD_SHA:-")}" ]; then
   detail='no pull request head SHA'
-elif [ -z "${shellExpansion("GITHUB_REPOSITORY:-")}" ]; then
+elif [ -z "${shellExpansion$1("GITHUB_REPOSITORY:-")}" ]; then
   detail='no repository name'
 elif ! response=$(gh api --method GET --paginate \
     "repos/$GITHUB_REPOSITORY/commits/$HEAD_SHA/check-runs" \
@@ -770,6 +873,7 @@ else
     IFS= read -r reason || :
     IFS= read -r mode || :
     IFS= read -r missing || :
+    IFS= read -r source_url || :
   } <<< "$finding"
   case "$reason" in
     proven | none | pending | failed | unreadable | incomplete | ambiguous) ;;
@@ -796,8 +900,11 @@ fi
 # line so it cannot restructure the summary it is written into.
 detail=$(printf '%s' "$detail" | tr '\n\r\t' '   ' | cut -c1-240)
 missing=$(printf '%s' "$missing" | tr '\n\r\t' '   ' | cut -c1-240)
+if ! [[ "$source_url" =~ ^https://github\.com/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+/runs/[0-9]+$ ]]; then
+  source_url=''
+fi
 
-SUMMARY="${shellExpansion("GITHUB_STEP_SUMMARY:-/dev/null")}"
+SUMMARY="${shellExpansion$1("GITHUB_STEP_SUMMARY:-/dev/null")}"
 say() { printf '%s\n' "$1" >> "$SUMMARY"; }
 
 say "## Proof reuse: $SURFACE"
@@ -808,7 +915,11 @@ case "$reason" in
     echo "Factory proof: reusing local verification of $HEAD_SHA; skipping the $SURFACE suite."
     say "Skipped. The factory already verified this exact commit, so this job did not run the $SURFACE suite a second time."
     say ''
-    say "- Reused proof: the \`$CHECK_NAME\` check run published by the pinned factory GitHub App."
+    if [ -n "$source_url" ]; then
+      say "- Reused proof: [\`$CHECK_NAME\`]($source_url), published by the pinned factory GitHub App."
+    else
+      say "- Reused proof: the \`$CHECK_NAME\` check run published by the pinned factory GitHub App."
+    fi
     say "- Covers head: \`$HEAD_SHA\`"
     say "- Recorded mode: \`$mode\` (diagnostic only), outcome \`passed\`."
     ;;
@@ -843,7 +954,7 @@ case "$reason" in
   incomplete)
     say "Ran the full suite. The factory proof for this commit does not cover every command the $SURFACE surface requires."
     say ''
-    say "The newest \`$CHECK_NAME\` check run at head \`$HEAD_SHA\` passed, but its \`executedCommands\` is missing: \`$missing\`"
+    say "The newest \`$CHECK_NAME\` check run at head \`$HEAD_SHA\` passed, but its executed commands plus stamp-authorized \`notRequiredCommands\` do not cover this surface. Missing: \`$missing\`"
     say ''
     say '${CORRECTIVE_LINE}'
     ;;
@@ -865,7 +976,7 @@ esac
 say ''
 
 if [ "$verdict" != 'true' ]; then
-  echo "No reusable factory proof for ${shellExpansion("HEAD_SHA:-<unknown>")}; running the $SURFACE suite ($reason). $detail"
+  echo "No reusable factory proof for ${shellExpansion$1("HEAD_SHA:-<unknown>")}; running the $SURFACE suite ($reason). $detail"
 fi
 
 # The only write. A crash before this line leaves the output unset, the guard
@@ -874,7 +985,8 @@ fi
   printf '${FACTORY_PROOF_GATE_OUTPUT}=%s\n' "$verdict"
   printf '${FACTORY_PROOF_GATE_REASON_OUTPUT}=%s\n' "$reason"
   printf '${FACTORY_PROOF_GATE_MODE_OUTPUT}=%s\n' "$mode"
-} >> "${shellExpansion("GITHUB_OUTPUT:-/dev/null")}"
+  printf '${FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT}=%s\n' "$source_url"
+} >> "${shellExpansion$1("GITHUB_OUTPUT:-/dev/null")}"
 `.trim();
 /**
 * The gate script. Exported so it can be executed directly under test against
@@ -890,7 +1002,7 @@ fi
 */
 const factoryProofGateScript = ({ commands, surface }) => {
 	const required = proofReuseRequiredCommands(commands);
-	return required ? gateScript(required, safeLabel(surface)) : UNUSABLE_SELECTION_SCRIPT;
+	return required ? gateScript(required, safeLabel$1(surface)) : UNUSABLE_SELECTION_SCRIPT;
 };
 /**
 * The step itself, structurally accepted by gagen's `step()` without adding a
@@ -908,8 +1020,8 @@ const factoryProofGateScript = ({ commands, surface }) => {
 const factoryProofGateStep = (options) => Object.freeze({
 	continueOnError: true,
 	env: Object.freeze({
-		GH_TOKEN: githubExpression("secrets.GITHUB_TOKEN"),
-		HEAD_SHA: githubExpression("github.event.pull_request.head.sha")
+		GH_TOKEN: githubExpression$1("secrets.GITHUB_TOKEN"),
+		HEAD_SHA: githubExpression$1("github.event.pull_request.head.sha")
 	}),
 	id: FACTORY_PROOF_GATE_STEP_ID,
 	if: FACTORY_PROOF_GATE_IF,
@@ -941,11 +1053,137 @@ const proofReuseCoverage = ({ commands, skipped }) => {
 const assertProofReuseCoverage = (input) => {
 	const report = proofReuseCoverage(input);
 	if (report.covered) return report;
-	const surface = safeLabel(input.surface ?? "");
+	const surface = safeLabel$1(input.surface ?? "");
 	const problem = report.requiredCommands.length === 0 ? "selects no usable profile commands, so any passing proof would trivially cover it" : `skips work no selected profile command runs: ${report.uncovered.join(", ")}`;
 	throw new Error(`Proof-reuse coverage failed: the ${surface} surface ${problem}. Add the command to software-factory.profile.json (and to this surface's selection), or stop skipping it.`);
 };
 //#endregion
+//#region src/proof-reuse-presentation.ts
+/** Generic timing and presentation steps around the proof-reuse gate (#652). */
+const githubExpression = (expression) => `\${{ ${expression} }}`;
+const shellExpansion = (expression) => `\${${expression}}`;
+const safeLabel = (surface) => {
+	const cleaned = (typeof surface === "string" ? surface : "").replaceAll(/[^\w -]/gu, "").trim().slice(0, 60);
+	return cleaned.length > 0 ? cleaned : "verification";
+};
+const FACTORY_PROOF_TIMING_STEP_ID = "ci-timing";
+const FACTORY_PROOF_TIMING_START_STEP_NAME = "Start CI timing";
+const FACTORY_PROOF_TIMING_SUMMARY_STEP_NAME = "Record proof-reuse timing";
+const factoryProofTimingStartStep = () => Object.freeze({
+	continueOnError: true,
+	id: FACTORY_PROOF_TIMING_STEP_ID,
+	name: FACTORY_PROOF_TIMING_START_STEP_NAME,
+	run: String.raw`started_ms="$(node -e 'process.stdout.write(String(Date.now()))')"
+printf 'started_ms=%s\n' "$started_ms" >> "$GITHUB_OUTPUT"`
+});
+const factoryProofReuseSummaryScript = ({ surface }) => {
+	const label = safeLabel(surface);
+	return String.raw`now_ms="$(node -e 'process.stdout.write(String(Date.now()))')"
+ci_started_ms="${shellExpansion("CI_STARTED_MS:-")}"
+
+SUMMARY="${shellExpansion("GITHUB_STEP_SUMMARY:-/dev/null")}"
+say() { printf '%s\n' "$1" >> "$SUMMARY"; }
+
+say '## ${label} timing'
+say ''
+
+if [ "${shellExpansion("GITHUB_EVENT_NAME:-")}" = 'push' ]; then
+  say '- Path: merge-target full execution'
+  say '- Proof-reuse gate: not applicable on merge-target runs; the full suite ran.'
+  say "- Verified head: \`${shellExpansion("GITHUB_SHA:-unknown")}\`"
+  echo "::notice title=Factory proof reuse::Proof reuse is not applicable on merge-target runs; the full ${label} suite executed."
+elif [ "${shellExpansion("PROOF_REUSED:-")}" = 'true' ]; then
+  say '- Path: trusted local proof reused'
+  if [ -n "${shellExpansion("PROOF_SOURCE_URL:-")}" ]; then
+    say "- Reused proof: [exact source check](${shellExpansion("PROOF_SOURCE_URL")})"
+  fi
+  say "- Bound head: \`${shellExpansion("PROOF_HEAD_SHA:-unknown")}\`"
+  say "- Factory verification mode: ${shellExpansion("PROOF_MODE:-unavailable")} (diagnostic only)"
+  echo "::notice title=Factory proof reuse::Reused trusted local proof for ${label} at ${shellExpansion("PROOF_HEAD_SHA:-unknown")}."
+else
+  say "- Path: full GitHub CI fallback (${shellExpansion("PROOF_REASON:-error")})"
+  say "- Bound head: \`${shellExpansion("PROOF_HEAD_SHA:-unknown")}\`"
+  say "- Factory verification mode: ${shellExpansion("PROOF_MODE:-unavailable")} (diagnostic only)"
+  echo "::notice title=Factory proof reuse::No reusable proof for ${label}; the full hosted suite executed (${shellExpansion("PROOF_REASON:-error")})."
+fi
+
+if [[ "$ci_started_ms" =~ ^[0-9]+$ ]]; then
+  say "- GitHub workflow execution after the proof gate: $((now_ms - ci_started_ms)) ms"
+else
+  say '- GitHub workflow execution after the proof gate: unavailable'
+fi
+say ''`;
+};
+const factoryProofReuseSummaryStep = (options) => Object.freeze({
+	continueOnError: true,
+	env: Object.freeze({
+		CI_STARTED_MS: githubExpression(`steps.${FACTORY_PROOF_TIMING_STEP_ID}.outputs.started_ms`),
+		PROOF_HEAD_SHA: githubExpression("github.event.pull_request.head.sha"),
+		PROOF_MODE: githubExpression(`steps.${FACTORY_PROOF_GATE_STEP_ID}.outputs.${FACTORY_PROOF_GATE_MODE_OUTPUT}`),
+		PROOF_REASON: githubExpression(`steps.${FACTORY_PROOF_GATE_STEP_ID}.outputs.${FACTORY_PROOF_GATE_REASON_OUTPUT}`),
+		PROOF_REUSED: githubExpression(`steps.${FACTORY_PROOF_GATE_STEP_ID}.outputs.${FACTORY_PROOF_GATE_OUTPUT}`),
+		PROOF_SOURCE_URL: githubExpression(`steps.${FACTORY_PROOF_GATE_STEP_ID}.outputs.${FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT}`)
+	}),
+	if: "always()",
+	name: FACTORY_PROOF_TIMING_SUMMARY_STEP_NAME,
+	run: factoryProofReuseSummaryScript(options)
+});
+//#endregion
+//#region src/production-impact-workflow.ts
+const FACTORY_PRODUCTION_IMPACT_STEP_ID = "production_impact";
+const FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT = "decision";
+const FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT = "basis";
+const FACTORY_PRODUCTION_IMPACT_UNSUBSCRIBED_OUTPUT = "unsubscribed_paths";
+const OUTPUT_NAME_PATTERN = /[^a-z0-9_]+/gu;
+const shellQuote = (value) => `'${value.replaceAll("'", `'"'"'`)}'`;
+/** Stable GitHub-output key for one declared target. */
+const productionImpactTargetOutput = (targetName) => {
+	const normalized = targetName.toLowerCase().replaceAll(OUTPUT_NAME_PATTERN, "_").replaceAll(/^_+|_+$/gu, "");
+	if (normalized.length === 0) throw new Error(`Impact target name "${targetName}" has no output-safe characters.`);
+	return `target_${normalized}`;
+};
+/**
+* Generate the small factory-owned decision seam for a consumer production
+* workflow. Consumers retain jobs, deploy commands, credentials, topology,
+* and convergence checks; this artifact supplies only the decision step and
+* per-target withdrawal conditions.
+*/
+const factoryProductionImpactWorkflow = (options) => {
+	const targetOutputs = Object.fromEntries(options.targets.map((target) => [target, productionImpactTargetOutput(target)]));
+	if (new Set(Object.values(targetOutputs)).size !== options.targets.length) throw new Error("Impact target names must map to distinct GitHub output keys.");
+	const before = options.before ?? `\${{ github.event.before }}`;
+	const after = options.after ?? `\${{ github.sha }}`;
+	const cli = options.cli ?? "pnpm exec psf";
+	const profile = options.profilePath ? ` --profile ${shellQuote(options.profilePath)}` : "";
+	const decisionStep = {
+		continueOnError: true,
+		env: {
+			FACTORY_AFTER_SHA: after,
+			FACTORY_BEFORE_SHA: before
+		},
+		id: FACTORY_PRODUCTION_IMPACT_STEP_ID,
+		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}`
+	};
+	return Object.freeze({
+		decisionJobOutputs: Object.freeze({
+			basis: `\${{ steps.${FACTORY_PRODUCTION_IMPACT_STEP_ID}.outputs.${FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT} }}`,
+			decision: `\${{ steps.${FACTORY_PRODUCTION_IMPACT_STEP_ID}.outputs.${FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT} }}`,
+			unsubscribed_paths: `\${{ steps.${FACTORY_PRODUCTION_IMPACT_STEP_ID}.outputs.${FACTORY_PRODUCTION_IMPACT_UNSUBSCRIBED_OUTPUT} }}`,
+			...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;
+		},
+		targetOutputs: Object.freeze(targetOutputs)
+	});
+};
+//#endregion
 //#region src/vitest-profile.ts
 /**
 * Vitest suite profiling — the measurement mechanics behind a CI runner
@@ -1646,4 +1884,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 { 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_STEP_ID, FACTORY_PROOF_GATE_STEP_NAME, GitHubApiError, NODE_PNPM_ACTION_FAMILY_NODE24, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, VitestProfileError, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryProofGateScript, factoryProofGateStep, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };
+export { FACTORY_CANDIDATE_PULL_REQUEST_TYPES, 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_PROOF_TIMING_START_STEP_NAME, FACTORY_PROOF_TIMING_STEP_ID, FACTORY_PROOF_TIMING_SUMMARY_STEP_NAME, GitHubApiError, NODE_PNPM_ACTION_FAMILY_NODE24, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, VitestProfileError, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryCandidateOrPushCondition, factoryProductionImpactWorkflow, factoryProofGateScript, factoryProofGateStep, factoryProofReuseSummaryScript, factoryProofReuseSummaryStep, factoryProofTimingStartStep, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, 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.8",
+  "version": "1.0.0-alpha.9",
   "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",

package/src/candidate-lifecycle.ts

@@ -0,0 +1,29 @@
+/**
+ * Pull-request events that can create or refresh a Factory candidate run.
+ *
+ * GitHub's draft boolean remains the lifecycle authority: these triggers make
+ * a run visible, while `factoryCandidateOrPushCondition` keeps substantive
+ * jobs idle until the pull request is a candidate.
+ */
+export const FACTORY_CANDIDATE_PULL_REQUEST_TYPES = Object.freeze([
+  "opened",
+  "synchronize",
+  "reopened",
+  "ready_for_review",
+] as const);
+
+/**
+ * Build a GitHub Actions job condition for candidate PRs and merge-target
+ * pushes. The caller owns triggers, jobs, runners, permissions, and topology.
+ */
+export const factoryCandidateOrPushCondition = (
+  candidateCondition?: string
+): string => {
+  const candidate = [
+    "github.event_name == 'pull_request'",
+    "github.event.pull_request.draft != true",
+    ...(candidateCondition ? [candidateCondition] : []),
+  ].join(" && ");
+
+  return ["github.event_name == 'push'", `(${candidate})`].join(" || ");
+};

package/src/factory-workflow.ts

@@ -5,6 +5,9 @@ const ACTION_TAG_PATTERN = /^v\d+(?:\.\d+){0,2}$/u;
 const RESERVED_ACTION_NAMES = new Set(["checkout", "setupNode", "setupPnpm"]);
 
 export interface WorkflowStep {
+  readonly continueOnError?: boolean;
+  readonly env?: Readonly<Record<string, string>>;
+  readonly id?: string;
   readonly name: string;
   readonly uses?: string;
   readonly with?: Readonly<Record<string, string>>;
@@ -12,6 +15,7 @@ export interface WorkflowStep {
 }
 
 export interface CheckoutStepOptions {
+  readonly fetchDepth?: number;
   readonly name?: string;
   readonly ref?: string;
 }
@@ -129,6 +133,25 @@ const assertAdditionalActions = (
   }
 };
 
+const checkoutInputs = (
+  checkout: CheckoutStepOptions | undefined
+): Readonly<Record<string, string>> | undefined => {
+  if (checkout === undefined) {
+    return undefined;
+  }
+  const inputs: Record<string, string> = {};
+  if (checkout.fetchDepth !== undefined) {
+    if (!Number.isSafeInteger(checkout.fetchDepth) || checkout.fetchDepth < 0) {
+      throw new Error("checkout.fetchDepth must be a non-negative integer.");
+    }
+    inputs["fetch-depth"] = String(checkout.fetchDepth);
+  }
+  if (checkout.ref) {
+    inputs.ref = checkout.ref;
+  }
+  return Object.keys(inputs).length > 0 ? inputs : undefined;
+};
+
 const setupSteps = (
   family: NodePnpmActionFamily,
   setup: FactoryWorkflowSetupOptions = {}
@@ -141,11 +164,12 @@ const setupSteps = (
   }
 
   const { checkout, setupNode } = setup;
+  const checkoutWith = checkoutInputs(checkout);
   return Object.freeze([
     {
       name: checkout?.name ?? "Checkout",
       uses: family.checkout.uses,
-      ...(checkout?.ref ? { with: { ref: checkout.ref } } : {}),
+      ...(checkoutWith ? { with: checkoutWith } : {}),
     },
     usesStep("Setup pnpm", family.setupPnpm),
     {

package/src/index.ts

@@ -13,6 +13,10 @@ export {
   type NodePnpmActionFamily,
   type PinnedAction,
 } from "./actions.ts";
+export {
+  FACTORY_CANDIDATE_PULL_REQUEST_TYPES,
+  factoryCandidateOrPushCondition,
+} from "./candidate-lifecycle.ts";
 export {
   bundleAlchemyEntry,
   type BundleAlchemyEntryOptions,
@@ -59,6 +63,7 @@ export {
   FACTORY_PROOF_GATE_REASON_OUTPUT,
   FACTORY_PROOF_GATE_REASONS,
   FACTORY_PROOF_GATE_SHELL,
+  FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT,
   FACTORY_PROOF_GATE_STEP_ID,
   FACTORY_PROOF_GATE_STEP_NAME,
   type FactoryProofGateOptions,
@@ -73,6 +78,27 @@ export {
   proofReuseRequiredCommands,
   resolveProofReuseCommands,
 } from "./proof-reuse-gate.ts";
+export {
+  type FactoryProofReusePresentationOptions,
+  type FactoryProofReuseSummaryStep,
+  type FactoryProofTimingStartStep,
+  FACTORY_PROOF_TIMING_START_STEP_NAME,
+  FACTORY_PROOF_TIMING_STEP_ID,
+  FACTORY_PROOF_TIMING_SUMMARY_STEP_NAME,
+  factoryProofReuseSummaryScript,
+  factoryProofReuseSummaryStep,
+  factoryProofTimingStartStep,
+} from "./proof-reuse-presentation.ts";
+export {
+  FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT,
+  FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT,
+  FACTORY_PRODUCTION_IMPACT_STEP_ID,
+  FACTORY_PRODUCTION_IMPACT_UNSUBSCRIBED_OUTPUT,
+  type FactoryProductionImpactWorkflow,
+  type FactoryProductionImpactWorkflowOptions,
+  factoryProductionImpactWorkflow,
+  productionImpactTargetOutput,
+} from "./production-impact-workflow.ts";
 export {
   captureVitestProfileEnvironment,
   normalizeVitestProfileSample,

package/src/production-impact-workflow.ts

@@ -0,0 +1,109 @@
+import type { WorkflowStep } from "./factory-workflow.ts";
+
+export const FACTORY_PRODUCTION_IMPACT_STEP_ID = "production_impact";
+export const FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT = "decision";
+export const FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT = "basis";
+export const FACTORY_PRODUCTION_IMPACT_UNSUBSCRIBED_OUTPUT =
+  "unsubscribed_paths";
+
+const OUTPUT_NAME_PATTERN = /[^a-z0-9_]+/gu;
+const shellQuote = (value: string): string =>
+  `'${value.replaceAll("'", `'"'"'`)}'`;
+
+/** Stable GitHub-output key for one declared target. */
+export const productionImpactTargetOutput = (targetName: string): string => {
+  const normalized = targetName
+    .toLowerCase()
+    .replaceAll(OUTPUT_NAME_PATTERN, "_")
+    .replaceAll(/^_+|_+$/gu, "");
+  if (normalized.length === 0) {
+    throw new Error(
+      `Impact target name "${targetName}" has no output-safe characters.`
+    );
+  }
+  return `target_${normalized}`;
+};
+
+export interface FactoryProductionImpactWorkflowOptions {
+  readonly after?: string;
+  readonly before?: string;
+  readonly cli?: string;
+  readonly profilePath?: string;
+  readonly targets: readonly string[];
+}
+
+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;
+  readonly targetOutputs: Readonly<Record<string, string>>;
+}
+
+/**
+ * Generate the small factory-owned decision seam for a consumer production
+ * workflow. Consumers retain jobs, deploy commands, credentials, topology,
+ * and convergence checks; this artifact supplies only the decision step and
+ * per-target withdrawal conditions.
+ */
+export const factoryProductionImpactWorkflow = (
+  options: FactoryProductionImpactWorkflowOptions
+): FactoryProductionImpactWorkflow => {
+  const targetOutputs = Object.fromEntries(
+    options.targets.map((target) => [
+      target,
+      productionImpactTargetOutput(target),
+    ])
+  );
+  if (new Set(Object.values(targetOutputs)).size !== options.targets.length) {
+    throw new Error(
+      "Impact target names must map to distinct GitHub output keys."
+    );
+  }
+
+  const before = options.before ?? `\${{ github.event.before }}`;
+  const after = options.after ?? `\${{ github.sha }}`;
+  const cli = options.cli ?? "pnpm exec psf";
+  const profile = options.profilePath
+    ? ` --profile ${shellQuote(options.profilePath)}`
+    : "";
+  const decisionStep: WorkflowStep = {
+    continueOnError: true,
+    env: {
+      FACTORY_AFTER_SHA: after,
+      FACTORY_BEFORE_SHA: before,
+    },
+    id: FACTORY_PRODUCTION_IMPACT_STEP_ID,
+    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}`,
+  };
+
+  return Object.freeze({
+    decisionJobOutputs: Object.freeze({
+      basis: `\${{ steps.${FACTORY_PRODUCTION_IMPACT_STEP_ID}.outputs.${FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT} }}`,
+      decision: `\${{ steps.${FACTORY_PRODUCTION_IMPACT_STEP_ID}.outputs.${FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT} }}`,
+      unsubscribed_paths: `\${{ steps.${FACTORY_PRODUCTION_IMPACT_STEP_ID}.outputs.${FACTORY_PRODUCTION_IMPACT_UNSUBSCRIBED_OUTPUT} }}`,
+      ...Object.fromEntries(
+        Object.values(targetOutputs).map((output) => [
+          output,
+          `\${{ steps.${FACTORY_PRODUCTION_IMPACT_STEP_ID}.outputs.${output} }}`,
+        ])
+      ),
+    }),
+    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;
+    },
+    targetOutputs: Object.freeze(targetOutputs),
+  });
+};

package/src/proof-reuse-gate.ts

@@ -107,6 +107,9 @@ export const FACTORY_PROOF_GATE_REASON_OUTPUT = "reason";
  */
 export const FACTORY_PROOF_GATE_MODE_OUTPUT = "mode";
 
+/** Exact Checks API URL of the proof generation selected by the gate. */
+export const FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT = "source-check-url";
+
 /**
  * Guard for every step the gate protects. Deliberately `!= 'true'` and not
  * `== 'false'`: an unset, empty, or garbled output must run the suite.
@@ -129,7 +132,8 @@ export const FACTORY_PROOF_GATE_IF = "github.event_name == 'pull_request'";
  * - `pending`    the newest generation had not completed when this job read it
  * - `failed`     the newest generation records no pass
  * - `unreadable` it passed but carries no binding for this repository and head
- * - `incomplete` it passed but did not execute every required command
+ * - `incomplete` its executed plus stamp-authorized released commands do not
+ *                cover every required command
  * - `ambiguous`  two newest generations share the greatest start time
  * - `error`      the gate could not reach a decision (fail open)
  *
@@ -179,6 +183,14 @@ export interface ProofReuseCommand {
 const COMMAND_IDENTITY = /^\w[\w.:@/-]*$/u;
 const COMMAND_IDENTITY_MAX_LENGTH = 120;
 
+/**
+ * The impact-stamp interpretation the paired factory packages currently
+ * share. A release recorded under any other version is an unmodelled input and
+ * 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 isProofReuseCommand = (value: unknown): value is ProofReuseCommand => {
   if (!(value && typeof value === "object")) {
     return false;
@@ -271,7 +283,7 @@ export const resolveProofReuseCommands = (
 
 /**
  * jq program: every page of the Checks API result in, three sanitized lines
- * (`reason`, `mode`, missing commands) out.
+ * (`reason`, `mode`, uncovered commands) out.
  *
  * The input is what `gh api --paginate` actually writes: the pages
  * *concatenated* as a stream of top-level response objects, not merged into
@@ -328,6 +340,20 @@ def startedAt: (.started_at // "") | tostring;
 def rankable:
   test("^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]+)?Z$");
 
+def nonemptyString:
+  type == "string" and length > 0;
+
+def distinctNames:
+  (map(.name) | length) == (map(.name) | unique | length);
+
+def releaseAuthorized($release; $commands; $stamp):
+  ([ $commands[] | select(.name == $release.name) ]) as $commandRows
+  | ([ $stamp.targets[] | select(.name == $release.impactTarget) ]) as $targetRows
+  | ($commandRows | length) == 1
+    and $commandRows[0].impactTarget == $release.impactTarget
+    and ($targetRows | length) == 1
+    and $targetRows[0].impact == "not-affected";
+
 [ .[]
   | (.check_runs // [])[]
   | select(.name == $name)
@@ -335,20 +361,60 @@ def rankable:
   | { started: startedAt,
       status: (.status // ""),
       conclusion: (.conclusion // ""),
+      url: ((.html_url // "") | tostring),
       binding: binding }
 ] as $runs
 | ($runs | map(.started | rankable) | all) as $orderable
 | ($runs | map(.started | sub("\\.[0-9]+Z$"; "Z")) | max) as $newest
 | [ $runs[] | select((.started | sub("\\.[0-9]+Z$"; "Z")) == $newest) ] as $generation
-| (if ($runs | length) == 0 then ["none", "", ""]
-   elif ($orderable | not) then ["ambiguous", "", ""]
-   elif ($generation | length) != 1 then ["ambiguous", "", ""]
+| (if ($runs | length) == 0 then ["none", "", "", ""]
+   elif ($orderable | not) then ["ambiguous", "", "", ""]
+   elif ($generation | length) != 1 then ["ambiguous", "", "", ""]
    else
      $generation[0] as $run
      | (if ($run.binding | type) == "object" then $run.binding else {} end) as $proof
      | (($proof.mode // "") | tostring) as $mode
      | (($proof.executedCommands // []) | map(select(type == "string"))) as $executed
-     | ($required - $executed) as $missing
+     | ($proof | has("notRequiredCommands")) as $hasReleases
+     | (if $hasReleases then $proof.notRequiredCommands else [] end) as $releases
+     | ($proof.verificationCommands // null) as $commands
+     | ($proof.impactStamp // null) as $stamp
+     | (if ($hasReleases | not) then true
+        else
+          ($proof.proofSchemaVersion == 4)
+          and ($releases | type) == "array"
+          and ($releases | length) > 0
+          and ($releases | all(.[];
+            type == "object"
+            and (.name | nonemptyString)
+            and (.impactTarget | nonemptyString)
+            and (.basis | nonemptyString)))
+          and ($releases | distinctNames)
+          and ($commands | type) == "array"
+          and ($commands | all(.[];
+            type == "object"
+            and (.name | nonemptyString)
+            and ((has("impactTarget") | not) or (.impactTarget | nonemptyString))))
+          and ($commands | distinctNames)
+          and ($stamp | type) == "object"
+          and ($stamp.stampVersion == ${TRUSTED_IMPACT_STAMP_VERSION})
+          and ($stamp.basis == "target-scoped")
+          and (($stamp.reasons | type) == "array")
+          and ($stamp.reasons | all(.[]; type == "string"))
+          and (($stamp.unsubscribedPaths | type) == "array")
+          and ($stamp.unsubscribedPaths | all(.[]; type == "string"))
+          and (($stamp.targets | type) == "array")
+          and ($stamp.targets | all(.[];
+            type == "object"
+            and (.name | nonemptyString)
+            and (.basis | nonemptyString)
+            and ((.impact == "affected") or (.impact == "not-affected"))))
+          and ($stamp.targets | distinctNames)
+          and (([$releases[].name] - $executed | length) == ($releases | length))
+          and ($releases | all(.[]; releaseAuthorized(.; $commands; $stamp)))
+        end) as $releasesValid
+     | (if $releasesValid then [$releases[].name] else [] end) as $released
+     | ($required - $executed - $released) as $missing
      | (if $run.status != "completed" then "pending"
         elif $run.conclusion != "success" then "failed"
         elif (($run.binding | type) != "object")
@@ -358,10 +424,11 @@ def rankable:
           or ($proof.repository != $repository) then "unreadable"
         elif $proof.outcome != "passed" then "failed"
         elif ($required | length) == 0 then "incomplete"
+        elif ($releasesValid | not) then "incomplete"
         elif ($missing | length) != 0 then "incomplete"
         else "proven"
         end) as $reason
-     | [$reason, $mode, ($missing | join(", "))]
+     | [$reason, $mode, ($missing | join(", ")), $run.url]
    end)
 | map(gsub("[\\r\\n\\t]"; " "))
 | join("\n")
@@ -413,6 +480,7 @@ reason=error
 detail=''
 mode=''
 missing=''
+source_url=''
 
 # filter=all with full pagination is load-bearing (ADR 0022). GitHub's
 # default "latest" filter is ordered by completion, so a newer generation
@@ -451,6 +519,7 @@ else
     IFS= read -r reason || :
     IFS= read -r mode || :
     IFS= read -r missing || :
+    IFS= read -r source_url || :
   } <<< "$finding"
   case "$reason" in
     proven | none | pending | failed | unreadable | incomplete | ambiguous) ;;
@@ -477,6 +546,9 @@ fi
 # line so it cannot restructure the summary it is written into.
 detail=$(printf '%s' "$detail" | tr '\n\r\t' '   ' | cut -c1-240)
 missing=$(printf '%s' "$missing" | tr '\n\r\t' '   ' | cut -c1-240)
+if ! [[ "$source_url" =~ ^https://github\.com/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+/runs/[0-9]+$ ]]; then
+  source_url=''
+fi
 
 SUMMARY="${shellExpansion("GITHUB_STEP_SUMMARY:-/dev/null")}"
 say() { printf '%s\n' "$1" >> "$SUMMARY"; }
@@ -489,7 +561,11 @@ case "$reason" in
     echo "Factory proof: reusing local verification of $HEAD_SHA; skipping the $SURFACE suite."
     say "Skipped. The factory already verified this exact commit, so this job did not run the $SURFACE suite a second time."
     say ''
-    say "- Reused proof: the \`$CHECK_NAME\` check run published by the pinned factory GitHub App."
+    if [ -n "$source_url" ]; then
+      say "- Reused proof: [\`$CHECK_NAME\`]($source_url), published by the pinned factory GitHub App."
+    else
+      say "- Reused proof: the \`$CHECK_NAME\` check run published by the pinned factory GitHub App."
+    fi
     say "- Covers head: \`$HEAD_SHA\`"
     say "- Recorded mode: \`$mode\` (diagnostic only), outcome \`passed\`."
     ;;
@@ -524,7 +600,7 @@ case "$reason" in
   incomplete)
     say "Ran the full suite. The factory proof for this commit does not cover every command the $SURFACE surface requires."
     say ''
-    say "The newest \`$CHECK_NAME\` check run at head \`$HEAD_SHA\` passed, but its \`executedCommands\` is missing: \`$missing\`"
+    say "The newest \`$CHECK_NAME\` check run at head \`$HEAD_SHA\` passed, but its executed commands plus stamp-authorized \`notRequiredCommands\` do not cover this surface. Missing: \`$missing\`"
     say ''
     say '${CORRECTIVE_LINE}'
     ;;
@@ -555,6 +631,7 @@ fi
   printf '${FACTORY_PROOF_GATE_OUTPUT}=%s\n' "$verdict"
   printf '${FACTORY_PROOF_GATE_REASON_OUTPUT}=%s\n' "$reason"
   printf '${FACTORY_PROOF_GATE_MODE_OUTPUT}=%s\n' "$mode"
+  printf '${FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT}=%s\n' "$source_url"
 } >> "${shellExpansion("GITHUB_OUTPUT:-/dev/null")}"
 `.trim();
 

package/src/proof-reuse-presentation.ts

@@ -0,0 +1,125 @@
+/** Generic timing and presentation steps around the proof-reuse gate (#652). */
+
+import {
+  FACTORY_PROOF_GATE_MODE_OUTPUT,
+  FACTORY_PROOF_GATE_OUTPUT,
+  FACTORY_PROOF_GATE_REASON_OUTPUT,
+  FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT,
+  FACTORY_PROOF_GATE_STEP_ID,
+} from "./proof-reuse-gate.ts";
+
+const githubExpression = (expression: string): string =>
+  `\${{ ${expression} }}`;
+
+const shellExpansion = (expression: string): string => `\${${expression}}`;
+
+const safeLabel = (surface: string): string => {
+  const cleaned = (typeof surface === "string" ? surface : "")
+    .replaceAll(/[^\w -]/gu, "")
+    .trim()
+    .slice(0, 60);
+  return cleaned.length > 0 ? cleaned : "verification";
+};
+
+export const FACTORY_PROOF_TIMING_STEP_ID = "ci-timing";
+export const FACTORY_PROOF_TIMING_START_STEP_NAME = "Start CI timing";
+export const FACTORY_PROOF_TIMING_SUMMARY_STEP_NAME =
+  "Record proof-reuse timing";
+
+export interface FactoryProofReusePresentationOptions {
+  /** Human-readable name of the guarded suite. */
+  readonly surface: string;
+}
+
+export interface FactoryProofTimingStartStep {
+  readonly continueOnError: true;
+  readonly id: typeof FACTORY_PROOF_TIMING_STEP_ID;
+  readonly name: typeof FACTORY_PROOF_TIMING_START_STEP_NAME;
+  readonly run: string;
+}
+
+export const factoryProofTimingStartStep = (): FactoryProofTimingStartStep =>
+  Object.freeze({
+    continueOnError: true as const,
+    id: FACTORY_PROOF_TIMING_STEP_ID,
+    name: FACTORY_PROOF_TIMING_START_STEP_NAME,
+    run: String.raw`started_ms="$(node -e 'process.stdout.write(String(Date.now()))')"
+printf 'started_ms=%s\n' "$started_ms" >> "$GITHUB_OUTPUT"`,
+  });
+
+export const factoryProofReuseSummaryScript = ({
+  surface,
+}: FactoryProofReusePresentationOptions): string => {
+  const label = safeLabel(surface);
+  return String.raw`now_ms="$(node -e 'process.stdout.write(String(Date.now()))')"
+ci_started_ms="${shellExpansion("CI_STARTED_MS:-")}"
+
+SUMMARY="${shellExpansion("GITHUB_STEP_SUMMARY:-/dev/null")}"
+say() { printf '%s\n' "$1" >> "$SUMMARY"; }
+
+say '## ${label} timing'
+say ''
+
+if [ "${shellExpansion("GITHUB_EVENT_NAME:-")}" = 'push' ]; then
+  say '- Path: merge-target full execution'
+  say '- Proof-reuse gate: not applicable on merge-target runs; the full suite ran.'
+  say "- Verified head: \`${shellExpansion("GITHUB_SHA:-unknown")}\`"
+  echo "::notice title=Factory proof reuse::Proof reuse is not applicable on merge-target runs; the full ${label} suite executed."
+elif [ "${shellExpansion("PROOF_REUSED:-")}" = 'true' ]; then
+  say '- Path: trusted local proof reused'
+  if [ -n "${shellExpansion("PROOF_SOURCE_URL:-")}" ]; then
+    say "- Reused proof: [exact source check](${shellExpansion("PROOF_SOURCE_URL")})"
+  fi
+  say "- Bound head: \`${shellExpansion("PROOF_HEAD_SHA:-unknown")}\`"
+  say "- Factory verification mode: ${shellExpansion("PROOF_MODE:-unavailable")} (diagnostic only)"
+  echo "::notice title=Factory proof reuse::Reused trusted local proof for ${label} at ${shellExpansion("PROOF_HEAD_SHA:-unknown")}."
+else
+  say "- Path: full GitHub CI fallback (${shellExpansion("PROOF_REASON:-error")})"
+  say "- Bound head: \`${shellExpansion("PROOF_HEAD_SHA:-unknown")}\`"
+  say "- Factory verification mode: ${shellExpansion("PROOF_MODE:-unavailable")} (diagnostic only)"
+  echo "::notice title=Factory proof reuse::No reusable proof for ${label}; the full hosted suite executed (${shellExpansion("PROOF_REASON:-error")})."
+fi
+
+if [[ "$ci_started_ms" =~ ^[0-9]+$ ]]; then
+  say "- GitHub workflow execution after the proof gate: $((now_ms - ci_started_ms)) ms"
+else
+  say '- GitHub workflow execution after the proof gate: unavailable'
+fi
+say ''`;
+};
+
+export interface FactoryProofReuseSummaryStep {
+  readonly continueOnError: true;
+  readonly env: Readonly<Record<string, string>>;
+  readonly if: "always()";
+  readonly name: typeof FACTORY_PROOF_TIMING_SUMMARY_STEP_NAME;
+  readonly run: string;
+}
+
+export const factoryProofReuseSummaryStep = (
+  options: FactoryProofReusePresentationOptions
+): FactoryProofReuseSummaryStep =>
+  Object.freeze({
+    continueOnError: true as const,
+    env: Object.freeze({
+      CI_STARTED_MS: githubExpression(
+        `steps.${FACTORY_PROOF_TIMING_STEP_ID}.outputs.started_ms`
+      ),
+      PROOF_HEAD_SHA: githubExpression("github.event.pull_request.head.sha"),
+      PROOF_MODE: githubExpression(
+        `steps.${FACTORY_PROOF_GATE_STEP_ID}.outputs.${FACTORY_PROOF_GATE_MODE_OUTPUT}`
+      ),
+      PROOF_REASON: githubExpression(
+        `steps.${FACTORY_PROOF_GATE_STEP_ID}.outputs.${FACTORY_PROOF_GATE_REASON_OUTPUT}`
+      ),
+      PROOF_REUSED: githubExpression(
+        `steps.${FACTORY_PROOF_GATE_STEP_ID}.outputs.${FACTORY_PROOF_GATE_OUTPUT}`
+      ),
+      PROOF_SOURCE_URL: githubExpression(
+        `steps.${FACTORY_PROOF_GATE_STEP_ID}.outputs.${FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT}`
+      ),
+    }),
+    if: "always()" as const,
+    name: FACTORY_PROOF_TIMING_SUMMARY_STEP_NAME,
+    run: factoryProofReuseSummaryScript(options),
+  });