@patronage/factory-ci 0.2.0 → 1.0.0-alpha.10

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;
@@ -193,9 +214,11 @@ const isProofReuseCommand = (value: unknown): value is ProofReuseCommand => {
  *
  * `undefined` means the selection is unusable — not an array, empty, or
  * carrying an entry whose `command` is blank or whose `name` is not a plain
- * command identity. An empty required set would make *every* passing proof
- * trivially covering, so it is never silently treated as "requires nothing";
- * callers must refuse instead.
+ * command identity, or carrying duplicate names. A name is the executable
+ * authorization identity recorded in proof, so two commands may never collapse
+ * behind one. An empty required set would make *every* passing proof trivially
+ * covering, so it is never silently treated as "requires nothing"; callers
+ * must refuse instead.
  */
 export const proofReuseRequiredCommands = (
   commands: readonly ProofReuseCommand[]
@@ -206,12 +229,61 @@ export const proofReuseRequiredCommands = (
   if (!commands.every(isProofReuseCommand)) {
     return;
   }
-  return [...new Set(commands.map(({ name }) => name))].toSorted();
+  const names = commands.map(({ name }) => name);
+  if (new Set(names).size !== names.length) {
+    return;
+  }
+  return names.toSorted();
 };
 
+/**
+ * Resolve command *identities* to their `ProofReuseCommand` objects (ADR
+ * 0021).
+ *
+ * Selection by name is deliberately a consumer decision (proof-surfaces.ts in
+ * software-factory-hq, the `paitronage:verify` filter in paitronage's
+ * `verify.ts`): only the consumer knows which named commands a guarded
+ * surface requires. What both of those implementations independently
+ * hand-rolled is the same lookup — find each name in the profile's command
+ * catalog, and refuse to silently shrink the required set when a name has no
+ * entry. That lookup is what this function is: the mechanic, not the
+ * selection.
+ *
+ * Throwing at generation time (rather than returning `undefined` or an empty
+ * array) is deliberate: a name with no catalog entry is a mistake in the
+ * generator source, not a runtime condition a consumer should have to check
+ * for, and a required set that quietly loses an entry is exactly what makes a
+ * passing proof trivially "covering".
+ *
+ * `selectionLabel` names the failure, nothing else: it is not part of the
+ * selection this function resolves, only prose a consumer supplies for its
+ * own thrown error (e.g. HQ's surface name, "core" or "docs"). The message
+ * deliberately says "the profile's command catalog" rather than naming
+ * `software-factory.profile.json`: a fleet-generic library must not assume
+ * every consumer's catalog is that exact file, so this wording differs
+ * on purpose from the HQ-local message it replaced.
+ */
+export const resolveProofReuseCommands = (
+  catalog: readonly ProofReuseCommand[],
+  names: readonly string[],
+  selectionLabel?: string
+): readonly ProofReuseCommand[] =>
+  names.map((name) => {
+    const command = catalog.find((entry) => entry.name === name);
+    if (!command) {
+      const location = selectionLabel
+        ? `Proof-reuse selection for the ${selectionLabel} surface names`
+        : "Proof-reuse selection names";
+      throw new Error(
+        `${location} "${name}", which the profile's command catalog does not define.`
+      );
+    }
+    return { command: command.command, name: command.name };
+  });
+
 /**
  * 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
@@ -268,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)
@@ -275,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")
@@ -298,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")
@@ -353,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
@@ -391,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) ;;
@@ -417,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"; }
@@ -429,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\`."
     ;;
@@ -464,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}'
     ;;
@@ -495,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();
 
@@ -568,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.
@@ -579,10 +716,8 @@ export interface ProofReuseCoverageInput {
   /** The same selection handed to the gate for this surface. */
   readonly commands: readonly ProofReuseCommand[];
   /**
-   * Skipped work covered under a different command string, keyed by the
-   * skipped string with the reason as its value. Deliberately explicit: a
-   * prose rationale for why some narrower command is "equivalent enough" is
-   * exactly what this assertion exists to force into the open.
+   * @deprecated Ignored. Consumer prose cannot authorize executable coverage;
+   * retained only so the 0.2.1 security patch remains source-compatible.
    */
   readonly equivalents?: Readonly<Record<string, string>>;
   /**
@@ -617,7 +752,6 @@ export interface ProofReuseCoverageReport {
  */
 export const proofReuseCoverage = ({
   commands,
-  equivalents = {},
   skipped,
 }: ProofReuseCoverageInput): ProofReuseCoverageReport => {
   const requiredCommands = proofReuseRequiredCommands(commands) ?? [];
@@ -630,15 +764,7 @@ export const proofReuseCoverage = ({
     ...new Set(
       (Array.isArray(skipped) ? skipped : [])
         .map((command) => String(command).trim())
-        .filter(
-          (command) =>
-            command.length > 0 &&
-            // `Object.hasOwn`, never `in`: `in` walks the prototype chain, so
-            // a skipped command named `toString` or `constructor` would report
-            // itself as a declared equivalent of nothing. This assertion's only
-            // job is to fail loudly.
-            !(proven.has(command) || Object.hasOwn(equivalents, command))
-        )
+        .filter((command) => command.length > 0 && !proven.has(command))
     ),
   ].toSorted();
 

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