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

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,7 +63,9 @@ 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,
   type FactoryProofGateReason,
   factoryProofGateScript,
@@ -72,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,
@@ -90,6 +117,10 @@ export {
   type VitestTestStatus,
   writeVitestProfile,
 } from "./vitest-profile.ts";
+export {
+  readVitestProfileDocument,
+  type VitestProfileReadResult,
+} from "./vitest-profile-reader.ts";
 export {
   assertWorkflowShellParses,
   workflowRunBlocks,

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

@@ -57,6 +57,15 @@ export const FACTORY_PROOF_GATE_APP_ID = "4314840";
 /** Step id the guard condition refers to. */
 export const FACTORY_PROOF_GATE_STEP_ID = "factory-proof";
 
+/**
+ * Human-visible name of the gate step as the Actions jobs API serves it. A
+ * read-only run analyzer (`psf ci:analyze`, #647) matches on this name to
+ * classify a run as proof-reuse versus full fallback, so it is exported from
+ * exactly the module that writes it — matching on a re-typed copy would drift.
+ */
+export const FACTORY_PROOF_GATE_STEP_NAME =
+  "Check for factory proof of this head";
+
 /**
  * The shell the gate runs under, and it is a correctness requirement rather
  * than a preference.
@@ -98,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.
@@ -120,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)
  *
@@ -170,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;
@@ -262,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
@@ -319,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)
@@ -326,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")
@@ -349,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")
@@ -404,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
@@ -442,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) ;;
@@ -468,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"; }
@@ -480,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\`."
     ;;
@@ -515,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}'
     ;;
@@ -546,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();
 
@@ -619,7 +705,7 @@ export const factoryProofGateStep = (
     }),
     id: FACTORY_PROOF_GATE_STEP_ID,
     if: FACTORY_PROOF_GATE_IF,
-    name: "Check for factory proof of this head",
+    name: FACTORY_PROOF_GATE_STEP_NAME,
     run: factoryProofGateScript(options),
     // Never omit: the runner's default `run:` shell supplies `-e`, which
     // voids the fail-open design. See FACTORY_PROOF_GATE_SHELL.

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),
+  });