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

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.
@@ -435,6 +472,13 @@ const FACTORY_PROOF_GATE_APP_ID = "4314840";
 /** Step id the guard condition refers to. */
 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.
+*/
+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.
 *
@@ -471,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.
@@ -491,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)
 *
@@ -525,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;
@@ -592,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
@@ -649,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)
@@ -656,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")
@@ -679,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")
@@ -707,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";
 };
@@ -725,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" \
@@ -763,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) ;;
@@ -789,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"
@@ -801,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\`."
     ;;
@@ -836,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}'
     ;;
@@ -858,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
@@ -867,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
@@ -883,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
@@ -901,12 +1020,12 @@ 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,
-	name: "Check for factory proof of this head",
+	name: FACTORY_PROOF_GATE_STEP_NAME,
 	run: factoryProofGateScript(options),
 	shell: FACTORY_PROOF_GATE_SHELL
 });
@@ -934,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
@@ -1261,6 +1506,120 @@ const runVitestProfile = async (options, dependencies = {}) => {
 	return profile;
 };
 //#endregion
+//#region src/vitest-profile-reader.ts
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+const durationSummaryFailure = (value, where) => {
+	if (!isRecord(value)) return `${where} is not an object`;
+	const missing = [
+		"maximum",
+		"mean",
+		"median",
+		"minimum"
+	].find((field) => !isFiniteNumber(value[field]));
+	return missing === void 0 ? void 0 : `${where}.${missing} is not a finite number`;
+};
+const environmentFailure = (value) => {
+	if (!isRecord(value)) return "environment is not an object";
+	if (!(typeof value.cpuModel === "string" || value.cpuModel === null)) return "environment.cpuModel is neither a string nor null";
+	if (!isFiniteNumber(value.cpuCount)) return "environment.cpuCount is not a finite number";
+};
+/** The count fields the writer emits; every one must be a finite number. */
+const COUNT_FIELDS = [
+	"failed",
+	"passed",
+	"pending",
+	"suites",
+	"tests",
+	"todo"
+];
+const runFailure = (value, index) => {
+	if (!isRecord(value)) return `runs[${index}] is not an object`;
+	if (!isFiniteNumber(value.durationMs)) return `runs[${index}].durationMs is not a finite number`;
+	if (value.counts === null) return;
+	if (!isRecord(value.counts)) return `runs[${index}].counts is neither an object nor null`;
+	const { counts } = value;
+	const missing = COUNT_FIELDS.find((field) => !isFiniteNumber(counts[field]));
+	return missing === void 0 ? void 0 : `runs[${index}].counts.${missing} is not a finite number`;
+};
+const slowEntryFailure = (value, where, labelField) => {
+	if (!isRecord(value)) return `${where} is not an object`;
+	if (typeof value[labelField] !== "string") return `${where}.${labelField} is not a string`;
+	if (labelField === "name" && typeof value.file !== "string") return `${where}.file is not a string`;
+	return durationSummaryFailure(value.durationMs, `${where}.durationMs`);
+};
+const summaryFailure = (value) => {
+	if (!isRecord(value)) return "summary is not an object";
+	const durations = durationSummaryFailure(value.durationMs, "summary.durationMs");
+	if (durations !== void 0) return durations;
+	if (!Array.isArray(value.slowFiles)) return "summary.slowFiles is not an array";
+	for (const [index, entry] of value.slowFiles.entries()) {
+		const failure = slowEntryFailure(entry, `summary.slowFiles[${index}]`, "path");
+		if (failure !== void 0) return failure;
+	}
+	if (!Array.isArray(value.slowTests)) return "summary.slowTests is not an array";
+	for (const [index, entry] of value.slowTests.entries()) {
+		const failure = slowEntryFailure(entry, `summary.slowTests[${index}]`, "name");
+		if (failure !== void 0) return failure;
+	}
+};
+/**
+* Check one parsed JSON document against the profile contract the writer
+* emits. Returns the typed profile on success and the first mismatch reason
+* otherwise — never a partially-usable value.
+*/
+const readVitestProfileDocument = (value) => {
+	if (!isRecord(value)) return {
+		kind: "unrecognized",
+		reason: "the document is not an object"
+	};
+	if (value.tool !== "factory-ci-vitest-profile") return {
+		kind: "unrecognized",
+		reason: `tool is ${JSON.stringify(value.tool)} rather than "${VITEST_PROFILE_TOOL}"`
+	};
+	if (value.schemaVersion !== 1) return {
+		kind: "unrecognized",
+		reason: `schemaVersion is ${JSON.stringify(value.schemaVersion)} rather than 1`
+	};
+	if (!(Array.isArray(value.command) && value.command.every((part) => typeof part === "string"))) return {
+		kind: "unrecognized",
+		reason: "command is not an array of strings"
+	};
+	const environment = environmentFailure(value.environment);
+	if (environment !== void 0) return {
+		kind: "unrecognized",
+		reason: environment
+	};
+	if (!isRecord(value.options)) return {
+		kind: "unrecognized",
+		reason: "options is not an object"
+	};
+	if (!isFiniteNumber(value.options.maxWorkers)) return {
+		kind: "unrecognized",
+		reason: "options.maxWorkers is not a finite number"
+	};
+	if (!Array.isArray(value.runs)) return {
+		kind: "unrecognized",
+		reason: "runs is not an array"
+	};
+	for (const [index, run] of value.runs.entries()) {
+		const failure = runFailure(run, index);
+		if (failure !== void 0) return {
+			kind: "unrecognized",
+			reason: failure
+		};
+	}
+	const summary = summaryFailure(value.summary);
+	if (summary !== void 0) return {
+		kind: "unrecognized",
+		reason: summary
+	};
+	return {
+		kind: "profile",
+		profile: value
+	};
+};
+//#endregion
 //#region src/workflow-shell-lint.ts
 const RUN_KEY = /^(?<indent>\s*)(?:-\s+)?run:(?<inline>.*)$/u;
 /**
@@ -1525,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, 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, 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.7",
+  "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(" || ");
+};