@patronage/factory-ci 0.2.1 → 1.0.0-alpha.13

package/dist/index.js

@@ -1,8 +1,13 @@
 import { createRequire } from "node:module";
-import { mkdir } from "node:fs/promises";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { build } from "esbuild";
-import { spawnSync } from "node:child_process";
+import { createSign, randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
+import { once } from "node:events";
+import { arch, availableParallelism, cpus, platform, release, totalmem } from "node:os";
+import { performance } from "node:perf_hooks";
 //#region src/actions.ts
 /**
 * The canonical Node 24 family shared by factory-project workflows.
@@ -27,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
@@ -40,6 +71,50 @@ const ALCHEMY_EXTERNALS = [
 	"effect/*"
 ];
 /**
+* The package names behind `ALCHEMY_EXTERNALS`, derived rather than restated so
+* a future external can never be guarded by only one of two lists.
+*/
+const RESERVED_ALIAS_PACKAGES = [...new Set(ALCHEMY_EXTERNALS.map((external) => external.replace(/\/\*$/u, "").toLowerCase()))];
+const reservedAliasKey = (key) => RESERVED_ALIAS_PACKAGES.find((name) => key === name || key.startsWith(`${name}/`));
+/**
+* Refuse an alias *key* that is itself a reserved package or one of its
+* subpaths. esbuild substitutes aliases before it decides what is external, so
+* such a key defeats `external` outright. Keys are compared, never resolved,
+* which is what makes string matching sound here.
+*/
+const assertAliasKeysAreAdmissible = (alias) => {
+	for (const key of Object.keys(alias)) {
+		const reserved = reservedAliasKey(key);
+		if (reserved) throw new Error(`bundleAlchemyEntry cannot alias "${key}": ${reserved} must stay external because its identity is shared with the consumer's runtime, and esbuild applies aliases before external matching. Point the consumer's own resolution at one copy instead.`);
+	}
+};
+/**
+* Whether a bundled input lives inside a reserved package.
+*
+* Metafile inputs are paths esbuild resolved and normalized itself, so
+* comparing whole segments here answers what was *bundled* rather than how the
+* config was spelled. Segments are compared case-insensitively: on a
+* case-insensitive filesystem `node_modules/Effect/…` resolves to the real
+* package and the metafile keeps the caller's spelling.
+*/
+const isReservedInput = (input) => {
+	const segments = input.toLowerCase().split(/[/\\]+/u);
+	return segments.some((segment, position) => position > 0 && segments[position - 1] === "node_modules" && RESERVED_ALIAS_PACKAGES.includes(segment));
+};
+/**
+* Assert the externals contract against the bundle esbuild actually produced.
+*
+* Checking alias *values* instead was unsound by construction: `..` segments,
+* symlinks, and every other spelling of the same file each need another string
+* rule, and the scanner loses. The metafile records the inputs after esbuild's
+* own resolution and normalization, so one check closes the whole class —
+* whatever route reached an identity-sensitive package, it shows up here.
+*/
+const assertNoReservedInputs = (inputs) => {
+	const offenders = inputs.filter(isReservedInput);
+	if (offenders.length > 0) throw new Error(`bundleAlchemyEntry refused a bundle carrying a second copy of an identity-sensitive package: ${offenders.join(", ")}. Those packages must resolve from the consumer's runtime, so nothing may pull their files into the bundle — an alias that re-exports them by bare specifier stays external and is fine.`);
+};
+/**
 * Pre-bundle an Alchemy entry to a single ESM file, keeping `alchemy` and
 * `effect` external (#268).
 *
@@ -53,22 +128,26 @@ const ALCHEMY_EXTERNALS = [
 * Returns the absolute path of the file written.
 */
 const bundleAlchemyEntry = async (options) => {
+	if (options.alias) assertAliasKeysAreAdmissible(options.alias);
 	const root = options.absWorkingDir ? path.resolve(options.absWorkingDir) : process.cwd();
 	const outfile = path.resolve(root, options.outfile);
 	await mkdir(path.dirname(outfile), { recursive: true });
-	await build({
+	const result = await build({
 		absWorkingDir: root,
 		bundle: true,
 		entryPoints: [path.resolve(root, options.entry)],
 		external: ALCHEMY_EXTERNALS,
 		format: "esm",
+		metafile: true,
 		outfile,
 		packages: options.packages ?? "external",
 		platform: "node",
 		sourcemap: options.sourcemap ?? false,
 		target: options.target ?? "node24",
+		...options.alias ? { alias: { ...options.alias } } : {},
 		...options.tsconfig ? { tsconfig: path.resolve(root, options.tsconfig) } : {}
 	});
+	assertNoReservedInputs(Object.keys(result.metafile.inputs));
 	return outfile;
 };
 //#endregion
@@ -122,9 +201,18 @@ const localPreviewStage = (options) => {
 	return `local-pr-${pr}-${normalizedHead.slice(0, shaLength)}`;
 };
 //#endregion
-//#region src/factory-workflow.ts
+//#region src/pinned-action.ts
 const PINNED_ACTION_PATTERN = /^[\w.-]+\/[\w.-]+@[0-9a-f]{40}$/u;
 const ACTION_TAG_PATTERN = /^v\d+(?:\.\d+){0,2}$/u;
+const actionRepository = (action) => action.uses.slice(0, action.uses.indexOf("@"));
+/** Shared validator for every action pin emitted by factory-ci helpers. */
+const assertPinnedAction = (name, action, expectedRepository) => {
+	if (!PINNED_ACTION_PATTERN.test(action.uses)) throw new Error(`${name} must use owner/repository@<40-character commit SHA>, got "${action.uses}".`);
+	if (expectedRepository && actionRepository(action) !== expectedRepository) throw new Error(`${name} must pin ${expectedRepository}, got ${actionRepository(action)}.`);
+	if (!ACTION_TAG_PATTERN.test(action.tag)) throw new Error(`${name} tag must be vN, vN.N, or vN.N.N, got "${action.tag}".`);
+};
+//#endregion
+//#region src/factory-workflow.ts
 const RESERVED_ACTION_NAMES = new Set([
 	"checkout",
 	"setupNode",
@@ -133,12 +221,6 @@ const RESERVED_ACTION_NAMES = new Set([
 const assertSingleLine = (name, value) => {
 	if (value.trim() !== value || value.length === 0 || /[\r\n]/u.test(value)) throw new Error(`${name} must be a single non-empty line.`);
 };
-const actionRepository = (action) => action.uses.slice(0, action.uses.indexOf("@"));
-const assertPinnedAction = (name, action, expectedRepository) => {
-	if (!PINNED_ACTION_PATTERN.test(action.uses)) throw new Error(`${name} must use owner/repository@<40-character commit SHA>, got "${action.uses}".`);
-	if (expectedRepository && actionRepository(action) !== expectedRepository) throw new Error(`${name} must pin ${expectedRepository}, got ${actionRepository(action)}.`);
-	if (!ACTION_TAG_PATTERN.test(action.tag)) throw new Error(`${name} tag must be vN, vN.N, or vN.N.N, got "${action.tag}".`);
-};
 const usesStep = (fallbackName, action) => ({
 	name: fallbackName,
 	uses: action.uses
@@ -155,15 +237,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),
 		{
@@ -210,6 +303,95 @@ const factoryWorkflow = (options) => {
 	});
 };
 //#endregion
+//#region src/github-app-token.ts
+/**
+* Minting a GitHub App installation token: the RS256 app JWT, the optional
+* installation lookup, and the token exchange (#617).
+*
+* Two projects had grown the same three steps independently — the factory's
+* check-run publisher and paitronage's proof-comment publisher — which is the
+* admitted-on-repetition bar. Only the *mechanism* lives here. Where the
+* private key comes from, how the app id is configured, and what the token is
+* then used for stay with each consumer: this module is handed credentials and
+* returns a token.
+*/
+/** The default request budget, matching the factory's other GitHub writes. */
+const DEFAULT_TIMEOUT_MS = 5e3;
+/** Nine-minute JWT lifetime, backdated a minute against runner clock skew. */
+const JWT_BACKDATE_SECONDS = 60;
+const JWT_LIFETIME_SECONDS = 600;
+/** Carries the HTTP status so a caller can tell a retryable failure apart. */
+var GitHubApiError = class extends Error {
+	status;
+	constructor(status, statusText) {
+		super(`GitHub API ${status} ${statusText}`);
+		this.name = "GitHubApiError";
+		this.status = status;
+	}
+};
+const base64url = (value) => Buffer.from(value).toString("base64url");
+/**
+* The signed app JWT GitHub accepts as `Authorization: Bearer` for the App
+* endpoints. `iss` is stringified because GitHub accepts either spelling and a
+* numeric app id must not depend on JSON's number formatting.
+*
+* The signature is produced from the key on disk and returned; the key
+* material itself never leaves this call.
+*/
+const githubAppJwt = (credentials, options = {}) => {
+	const nowMs = (options.now ?? Date.now)();
+	const issuedAt = Math.floor(nowMs / 1e3) - JWT_BACKDATE_SECONDS;
+	const unsigned = `${base64url(JSON.stringify({
+		alg: "RS256",
+		typ: "JWT"
+	}))}.${base64url(JSON.stringify({
+		exp: issuedAt + JWT_LIFETIME_SECONDS,
+		iat: issuedAt,
+		iss: String(credentials.appId)
+	}))}`;
+	const readKey = options.readPrivateKey ?? readFileSync;
+	const signer = createSign("RSA-SHA256");
+	signer.update(unsigned);
+	signer.end();
+	return `${unsigned}.${signer.sign(readKey(credentials.privateKeyPath), "base64url")}`;
+};
+const githubAppJson = async (request, url, jwt, method, timeoutMs) => {
+	const response = await request(url, {
+		headers: {
+			Accept: "application/vnd.github+json",
+			Authorization: `Bearer ${jwt}`,
+			"X-GitHub-Api-Version": "2022-11-28"
+		},
+		method,
+		signal: AbortSignal.timeout(timeoutMs)
+	});
+	if (!response.ok) throw new GitHubApiError(response.status, response.statusText);
+	return await response.json();
+};
+/**
+* Mint an installation access token for one repository.
+*
+* When the credentials omit `installationId`, the installation is discovered
+* from the repository first — the same call every consumer had written for
+* itself. Nothing is cached: the token is returned to the caller and this
+* module keeps no copy.
+*/
+const mintInstallationToken = async (input, options = {}) => {
+	const { credentials } = input;
+	const request = options.fetch ?? fetch;
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const jwt = githubAppJwt(credentials, options);
+	let { installationId } = credentials;
+	if (installationId === void 0) {
+		const installation = await githubAppJson(request, `https://api.github.com/repos/${input.owner}/${input.repo}/installation`, jwt, "GET", timeoutMs);
+		if (typeof installation.id !== "number") throw new TypeError("GitHub App installation response omitted id");
+		installationId = installation.id;
+	}
+	const minted = await githubAppJson(request, `https://api.github.com/app/installations/${installationId}/access_tokens`, jwt, "POST", timeoutMs);
+	if (typeof minted.token !== "string") throw new TypeError("GitHub App token response omitted token");
+	return minted.token;
+};
+//#endregion
 //#region src/execute-alchemy-entry.ts
 /**
 * Bundle a consumer-owned Alchemy entry, resolve that consumer's Alchemy CLI,
@@ -261,9 +443,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.
@@ -293,6 +475,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.
 *
@@ -329,6 +518,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.
@@ -349,7 +540,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)
 *
@@ -383,6 +575,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;
@@ -411,8 +610,46 @@ const proofReuseRequiredCommands = (commands) => {
 	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.
+*/
+const resolveProofReuseCommands = (catalog, names, selectionLabel) => 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
@@ -469,6 +706,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)
@@ -476,20 +727,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")
@@ -499,10 +790,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")
@@ -527,9 +819,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";
 };
@@ -545,14 +837,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" \
@@ -583,6 +876,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) ;;
@@ -609,8 +903,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"
@@ -621,7 +918,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\`."
     ;;
@@ -656,7 +957,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}'
     ;;
@@ -678,7 +979,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
@@ -687,7 +988,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
@@ -703,7 +1005,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
@@ -721,12 +1023,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
 });
@@ -754,9 +1056,1202 @@ 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
-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, NODE_PNPM_ACTION_FAMILY_NODE24, assertProofReuseCoverage, bundleAlchemyEntry, executeAlchemyEntry, factoryProofGateScript, factoryProofGateStep, factoryWorkflow, isLocalPreviewStage, localPreviewStage, parseLocalPreviewStage, proofReuseCoverage, proofReuseRequiredCommands };
+//#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/push-identity-workflow.ts
+const FACTORY_PUSH_IDENTITY_SCHEMA_VERSION = 1;
+const FACTORY_PUSH_IDENTITY_ARTIFACT_PREFIX = "factory-push-identity";
+const FACTORY_PUSH_IDENTITY_RECORD_STEP_ID = "factory_push_identity_record";
+const FACTORY_PUSH_IDENTITY_LOOKUP_STEP_ID = "factory_push_identity_lookup";
+const FACTORY_PUSH_IDENTITY_DOWNLOAD_STEP_ID = "factory_push_identity_download";
+const FACTORY_PUSH_IDENTITY_CHECKOUT_STEP_ID = "factory_push_identity_checkout";
+const FACTORY_PUSH_IDENTITY_VALIDATE_STEP_ID = "factory_push_identity";
+const ARTIFACT_MAX_BYTES = 16384;
+const ENVELOPE_MAX_BYTES = 4096;
+const expression = (value) => `\${{ ${value} }}`;
+const artifactName = (runId) => `${FACTORY_PUSH_IDENTITY_ARTIFACT_PREFIX}-${runId}`;
+const producerScript = String.raw`identity="$RUNNER_TEMP/factory-push-identity.json"
+produced=false
+reason='producer_error'
+before=''
+event_after=''
+rm -f "$identity"
+
+is_hex_sha() {
+  [ "$(printf '%s' "$1" | wc -c | tr -d '[:space:]')" -eq 40 ] &&
+    case "$1" in *[!0-9a-f]*) false;; *) true;; esac
+}
+
+is_nonzero_sha() {
+  is_hex_sha "$1" && [ "$1" != '0000000000000000000000000000000000000000' ]
+}
+
+if [ "$GITHUB_EVENT_NAME" != 'push' ]; then
+  reason='not_push_event'
+elif ! printf '%s' "$GITHUB_REPOSITORY" | grep -Eq '^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$'; then
+  reason='repository_invalid'
+elif ! printf '%s' "$GITHUB_RUN_ID" | grep -Eq '^[1-9][0-9]*$'; then
+  reason='run_id_invalid'
+elif ! before="$(jq -er '.before | select(type == "string")' "$GITHUB_EVENT_PATH" 2>/dev/null)"; then
+  reason='event_before_missing'
+elif ! event_after="$(jq -er '.after | select(type == "string")' "$GITHUB_EVENT_PATH" 2>/dev/null)"; then
+  reason='event_after_missing'
+elif ! is_hex_sha "$before"; then
+  reason='event_before_invalid'
+elif ! is_nonzero_sha "$event_after" || ! is_nonzero_sha "$GITHUB_SHA"; then
+  reason='event_after_invalid'
+elif [ "$event_after" != "$GITHUB_SHA" ]; then
+  reason='event_after_mismatch'
+elif jq -cn \
+  --argjson schemaVersion '${1}' \
+  --arg repository "$GITHUB_REPOSITORY" \
+  --arg runId "$GITHUB_RUN_ID" \
+  --arg before "$before" \
+  --arg after "$event_after" \
+  '{schemaVersion: $schemaVersion, repository: $repository, runId: $runId, before: $before, after: $after}' > "$identity"; then
+  produced=true
+  reason='produced'
+fi
+
+printf 'produced=%s\nreason=%s\n' "$produced" "$reason" >> "$GITHUB_OUTPUT"
+{
+  printf '## Exact push identity producer\n\n'
+  printf -- '- Status: %s\n' "$reason"
+  printf -- '- Repository/run: %s / %s\n' "$GITHUB_REPOSITORY" "$GITHUB_RUN_ID"
+  if [ "$produced" = true ]; then
+    printf -- '- Bound push: %s → %s\n' "$before" "$event_after"
+  else
+    printf -- '- Identity transport was not produced; downstream classification will refuse withdrawal.\n'
+  fi
+} >> "$GITHUB_STEP_SUMMARY"`;
+const lookupScript = String.raw`status='refused'
+reason='artifact_lookup_failed'
+artifact_id=''
+matches="$RUNNER_TEMP/factory-push-identity-artifacts.tsv"
+artifact_name='${FACTORY_PUSH_IDENTITY_ARTIFACT_PREFIX}-'"$EXPECTED_RUN_ID"
+rm -f "$matches"
+
+is_sha() {
+  [ "$(printf '%s' "$1" | wc -c | tr -d '[:space:]')" -eq 40 ] &&
+    [ "$1" != '0000000000000000000000000000000000000000' ] &&
+    case "$1" in *[!0-9a-f]*) false;; *) true;; esac
+}
+
+if [ "$EXPECTED_EVENT_NAME" != 'workflow_run' ]; then
+  reason='event_not_workflow_run'
+elif [ "$EXPECTED_WORKFLOW_EVENT" != 'push' ]; then
+  reason='triggering_workflow_not_push'
+elif [ "$EXPECTED_CONCLUSION" != 'success' ]; then
+  reason='triggering_workflow_not_successful'
+elif [ "$EXPECTED_WORKFLOW_REPOSITORY" != "$EXPECTED_REPOSITORY" ]; then
+  reason='triggering_repository_mismatch'
+elif ! printf '%s' "$EXPECTED_REPOSITORY" | grep -Eq '^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$'; then
+  reason='triggering_repository_invalid'
+elif ! printf '%s' "$EXPECTED_RUN_ID" | grep -Eq '^[1-9][0-9]*$'; then
+  reason='triggering_run_id_invalid'
+elif ! is_sha "$EXPECTED_AFTER_SHA"; then
+  reason='triggering_head_sha_invalid'
+elif ! gh api --paginate \
+  "repos/$EXPECTED_REPOSITORY/actions/runs/$EXPECTED_RUN_ID/artifacts?per_page=100" \
+  --jq ".artifacts[] | select(.name == \"$artifact_name\") | [.id, .size_in_bytes, .expired] | @tsv" \
+  > "$matches" 2>/dev/null; then
+  reason='artifact_lookup_failed'
+else
+  count="$(awk 'END { print NR + 0 }' "$matches")"
+  if [ "$count" -eq 0 ]; then
+    reason='artifact_missing'
+  elif [ "$count" -ne 1 ]; then
+    reason='artifact_duplicate'
+  else
+    IFS="$(printf '\t')" read -r artifact_id artifact_size artifact_expired < "$matches" || true
+    if ! printf '%s' "$artifact_id" | grep -Eq '^[1-9][0-9]*$' ||
+      ! printf '%s' "$artifact_size" | grep -Eq '^[0-9]+$' ||
+      { [ "$artifact_expired" != 'false' ] && [ "$artifact_expired" != 'true' ]; }; then
+      reason='artifact_metadata_invalid'
+      artifact_id=''
+    elif [ "$artifact_expired" = 'true' ]; then
+      reason='artifact_expired'
+      artifact_id=''
+    elif [ "$artifact_size" -gt '${ARTIFACT_MAX_BYTES}' ]; then
+      reason='artifact_oversized'
+      artifact_id=''
+    else
+      status='available'
+      reason='artifact_available'
+    fi
+  fi
+fi
+
+printf 'status=%s\nreason=%s\nartifact_id=%s\n' "$status" "$reason" "$artifact_id" >> "$GITHUB_OUTPUT"`;
+const validationScript = String.raw`disposition='refused'
+reason='validation_error'
+before=''
+after=''
+identity_directory="$RUNNER_TEMP/factory-push-identity"
+identity="$identity_directory/factory-push-identity.json"
+artifact_name='${FACTORY_PUSH_IDENTITY_ARTIFACT_PREFIX}-'"$EXPECTED_RUN_ID"
+
+is_sha() {
+  [ "$(printf '%s' "$1" | wc -c | tr -d '[:space:]')" -eq 40 ] &&
+    [ "$1" != '0000000000000000000000000000000000000000' ] &&
+    case "$1" in *[!0-9a-f]*) false;; *) true;; esac
+}
+
+if [ "$EXPECTED_EVENT_NAME" != 'workflow_run' ]; then
+  reason='event_not_workflow_run'
+elif [ "$EXPECTED_WORKFLOW_EVENT" != 'push' ]; then
+  reason='triggering_workflow_not_push'
+elif [ "$EXPECTED_CONCLUSION" != 'success' ]; then
+  reason='triggering_workflow_not_successful'
+elif [ "$EXPECTED_WORKFLOW_REPOSITORY" != "$EXPECTED_REPOSITORY" ]; then
+  reason='triggering_repository_mismatch'
+elif ! printf '%s' "$EXPECTED_REPOSITORY" | grep -Eq '^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$'; then
+  reason='triggering_repository_invalid'
+elif ! printf '%s' "$EXPECTED_RUN_ID" | grep -Eq '^[1-9][0-9]*$'; then
+  reason='triggering_run_id_invalid'
+elif ! is_sha "$EXPECTED_AFTER_SHA"; then
+  reason='triggering_head_sha_invalid'
+elif [ "$LOOKUP_STATUS" != 'available' ]; then
+  if [ -n "$LOOKUP_REASON" ]; then
+    reason="$LOOKUP_REASON"
+  else
+    reason='artifact_lookup_failed'
+  fi
+elif [ "$DOWNLOAD_OUTCOME" != 'success' ]; then
+  reason='artifact_download_failed'
+elif [ "$CHECKOUT_OUTCOME" != 'success' ]; then
+  reason='checkout_failed'
+elif [ ! -d "$identity_directory" ]; then
+  reason='artifact_contents_missing'
+else
+  entry_count="$(find "$identity_directory" -mindepth 1 -maxdepth 1 -print 2>/dev/null | awk 'END { print NR + 0 }')"
+  if [ "$entry_count" -ne 1 ] || [ ! -f "$identity" ] || [ -L "$identity" ]; then
+    reason='artifact_contents_invalid'
+  else
+    envelope_size="$(wc -c < "$identity" | tr -d '[:space:]')"
+    if ! printf '%s' "$envelope_size" | grep -Eq '^[0-9]+$'; then
+      reason='envelope_size_unreadable'
+    elif [ "$envelope_size" -gt '${ENVELOPE_MAX_BYTES}' ]; then
+      reason='envelope_oversized'
+    elif ! jq -e --argjson schemaVersion '${1}' '
+      type == "object" and
+      keys == ["after", "before", "repository", "runId", "schemaVersion"] and
+      .schemaVersion == $schemaVersion and
+      (.repository | type == "string") and
+      (.runId | type == "string" and test("^[1-9][0-9]*$")) and
+      (.before | type == "string" and test("^[0-9a-f]{40}$") and (test("^0{40}$") | not)) and
+      (.after | type == "string" and test("^[0-9a-f]{40}$") and (test("^0{40}$") | not))
+    ' "$identity" >/dev/null 2>&1; then
+      reason='envelope_malformed'
+    else
+      repository="$(jq -r '.repository' "$identity")"
+      run_id="$(jq -r '.runId' "$identity")"
+      before="$(jq -r '.before' "$identity")"
+      after="$(jq -r '.after' "$identity")"
+
+      if [ "$repository" != "$EXPECTED_REPOSITORY" ]; then
+        reason='envelope_repository_mismatch'
+      elif [ "$run_id" != "$EXPECTED_RUN_ID" ]; then
+        reason='envelope_run_id_mismatch'
+      elif [ "$after" != "$EXPECTED_AFTER_SHA" ]; then
+        reason='envelope_after_mismatch'
+      elif ! actual_head="$(git rev-parse --verify HEAD 2>/dev/null)" || [ "$actual_head" != "$EXPECTED_AFTER_SHA" ]; then
+        reason='checkout_head_mismatch'
+      elif ! git cat-file -e "$before^{commit}" 2>/dev/null || ! git cat-file -e "$after^{commit}" 2>/dev/null; then
+        reason='envelope_commit_unreachable'
+      elif [ "$before" = "$after" ]; then
+        reason='envelope_commits_contradictory'
+      elif ! git merge-base --is-ancestor "$before" "$after"; then
+        reason='before_not_ancestor'
+      else
+        disposition='usable'
+        reason='identity_bound'
+      fi
+    fi
+  fi
+fi
+
+if [ "$disposition" != 'usable' ]; then
+  before=''
+  after=''
+fi
+
+provenance="$(jq -cn \
+  --argjson schemaVersion '${1}' \
+  --arg disposition "$disposition" \
+  --arg reason "$reason" \
+  --arg repository "$EXPECTED_REPOSITORY" \
+  --arg runId "$EXPECTED_RUN_ID" \
+  --arg expectedAfter "$EXPECTED_AFTER_SHA" \
+  --arg artifactName "$artifact_name" \
+  --arg artifactId "$ARTIFACT_ID" \
+  --arg before "$before" \
+  --arg after "$after" \
+  '{schemaVersion: $schemaVersion, disposition: $disposition, reason: $reason, repository: $repository, runId: $runId, expectedAfter: $expectedAfter, artifactName: $artifactName, artifactId: (if $artifactId == "" then null else $artifactId end), before: (if $before == "" then null else $before end), after: (if $after == "" then null else $after end)}')"
+
+printf 'disposition=%s\nreason=%s\nbefore=%s\nafter=%s\nprovenance=%s\n' \
+  "$disposition" "$reason" "$before" "$after" "$provenance" >> "$GITHUB_OUTPUT"
+{
+  printf '## Exact push identity\n\n'
+  printf -- '- Disposition: %s\n' "$disposition"
+  printf -- '- Reason: %s\n' "$reason"
+  printf -- '- Repository/run: %s / %s\n' "$EXPECTED_REPOSITORY" "$EXPECTED_RUN_ID"
+  printf -- '- Expected verified head: %s\n' "$EXPECTED_AFTER_SHA"
+  if [ "$disposition" = 'usable' ]; then
+    printf -- '- Bound push: %s → %s\n' "$before" "$after"
+  else
+    printf -- '- Production impact classification refused; every consumer-owned production target remains demanded.\n'
+  fi
+  printf '\nFactory telemetry provenance: %s\n' "$provenance"
+} >> "$GITHUB_STEP_SUMMARY"`;
+/**
+* Record and upload the exact push-event identity without changing the Verify
+* result when transport is unavailable. Place these steps after verification.
+*/
+const factoryPushIdentityProducer = (options) => {
+	assertPinnedAction("uploadArtifact", options.uploadArtifact, "actions/upload-artifact");
+	const condition = options.if ? `github.event_name == 'push' && (${options.if})` : "github.event_name == 'push'";
+	const name = artifactName(expression("github.run_id"));
+	return Object.freeze({
+		artifactName: name,
+		steps: Object.freeze([{
+			continueOnError: true,
+			id: FACTORY_PUSH_IDENTITY_RECORD_STEP_ID,
+			if: condition,
+			name: "Record exact push identity",
+			run: producerScript
+		}, {
+			continueOnError: true,
+			if: `${condition} && steps.${FACTORY_PUSH_IDENTITY_RECORD_STEP_ID}.outputs.produced == 'true'`,
+			name: "Upload exact push identity",
+			uses: options.uploadArtifact.uses,
+			with: {
+				"if-no-files-found": "error",
+				name,
+				path: `${expression("runner.temp")}/factory-push-identity.json`,
+				"retention-days": "7"
+			}
+		}])
+	});
+};
+/**
+* Download and validate identity from exactly the triggering workflow run in
+* the current repository. Every failure becomes a typed refusal; consumers
+* retain deploy policy, credentials, commands, topology, and convergence.
+*/
+const factoryPushIdentityConsumer = (options) => {
+	assertPinnedAction("checkout", options.checkout, "actions/checkout");
+	assertPinnedAction("downloadArtifact", options.downloadArtifact, "actions/download-artifact");
+	const currentRepository = expression("github.repository");
+	const triggeringRun = expression("github.event.workflow_run.id");
+	const triggeringHead = expression("github.event.workflow_run.head_sha");
+	const lookupOutput = (name) => expression(`steps.${FACTORY_PUSH_IDENTITY_LOOKUP_STEP_ID}.outputs.${name}`);
+	const validateOutput = (name) => expression(`steps.${FACTORY_PUSH_IDENTITY_VALIDATE_STEP_ID}.outputs.${name}`);
+	const contextEnvironment = {
+		EXPECTED_AFTER_SHA: triggeringHead,
+		EXPECTED_CONCLUSION: expression("github.event.workflow_run.conclusion"),
+		EXPECTED_EVENT_NAME: expression("github.event_name"),
+		EXPECTED_REPOSITORY: currentRepository,
+		EXPECTED_RUN_ID: triggeringRun,
+		EXPECTED_WORKFLOW_EVENT: expression("github.event.workflow_run.event"),
+		EXPECTED_WORKFLOW_REPOSITORY: expression("github.event.workflow_run.repository.full_name")
+	};
+	const steps = [
+		{
+			continueOnError: true,
+			env: {
+				GH_TOKEN: expression("github.token"),
+				...contextEnvironment
+			},
+			id: FACTORY_PUSH_IDENTITY_LOOKUP_STEP_ID,
+			name: "Resolve exact push identity artifact",
+			run: lookupScript
+		},
+		{
+			continueOnError: true,
+			id: FACTORY_PUSH_IDENTITY_DOWNLOAD_STEP_ID,
+			if: `steps.${FACTORY_PUSH_IDENTITY_LOOKUP_STEP_ID}.outputs.status == 'available'`,
+			name: "Download exact push identity",
+			uses: options.downloadArtifact.uses,
+			with: {
+				"artifact-ids": lookupOutput("artifact_id"),
+				"github-token": expression("github.token"),
+				path: `${expression("runner.temp")}/factory-push-identity`,
+				repository: currentRepository,
+				"run-id": triggeringRun
+			}
+		},
+		{
+			continueOnError: true,
+			id: FACTORY_PUSH_IDENTITY_CHECKOUT_STEP_ID,
+			if: `steps.${FACTORY_PUSH_IDENTITY_LOOKUP_STEP_ID}.outputs.status == 'available'`,
+			name: "Checkout exact verified head",
+			uses: options.checkout.uses,
+			with: {
+				"fetch-depth": "0",
+				ref: triggeringHead
+			}
+		},
+		{
+			continueOnError: true,
+			env: {
+				ARTIFACT_ID: lookupOutput("artifact_id"),
+				CHECKOUT_OUTCOME: expression(`steps.${FACTORY_PUSH_IDENTITY_CHECKOUT_STEP_ID}.outcome`),
+				DOWNLOAD_OUTCOME: expression(`steps.${FACTORY_PUSH_IDENTITY_DOWNLOAD_STEP_ID}.outcome`),
+				LOOKUP_REASON: lookupOutput("reason"),
+				LOOKUP_STATUS: lookupOutput("status"),
+				...contextEnvironment
+			},
+			id: FACTORY_PUSH_IDENTITY_VALIDATE_STEP_ID,
+			if: "always()",
+			name: "Validate exact push identity",
+			run: validationScript
+		}
+	];
+	return Object.freeze({
+		outputs: Object.freeze({
+			after: validateOutput("after"),
+			before: validateOutput("before"),
+			disposition: validateOutput("disposition"),
+			provenance: validateOutput("provenance"),
+			reason: validateOutput("reason")
+		}),
+		requiredPermissions: Object.freeze({
+			actions: "read",
+			contents: "read"
+		}),
+		steps: Object.freeze(steps),
+		usableIf: `steps.${FACTORY_PUSH_IDENTITY_VALIDATE_STEP_ID}.outputs.disposition == 'usable'`
+	});
+};
+//#endregion
+//#region src/vitest-profile.ts
+/**
+* Vitest suite profiling — the measurement mechanics behind a CI runner
+* comparison (#640, #647).
+*
+* A profile is a machine-readable record of N serial Vitest runs at one worker
+* count, carrying per-file and per-test timings, aggregate duration statistics,
+* and the hardware the samples actually ran on. The hardware capture is the
+* point: the #640 Depot comparison only resolved because every sample recorded
+* its `cpuModel`, which split otherwise-identical 4-CPU runs into two
+* non-overlapping populations.
+*
+* Everything a repository decides stays with the repository: worker counts,
+* sample counts, output paths, runner labels, and which suite to run at all.
+* This module owns the schema, the report parsing, the environment capture, and
+* the atomic write.
+*/
+/** Schema version of the emitted profile document. */
+const VITEST_PROFILE_SCHEMA_VERSION = 1;
+/** `tool` discriminator every emitted profile carries. */
+const VITEST_PROFILE_TOOL = "factory-ci-vitest-profile";
+const RUN_TIMEOUT_MS = 15 * 6e4;
+const TERMINATION_GRACE_MS = 5e3;
+/**
+* A sample failed. The partial profile is already on disk; `exitCode` is the
+* status a caller should exit with.
+*/
+var VitestProfileError = class extends Error {
+	exitCode;
+	constructor(message, exitCode) {
+		super(message);
+		this.name = "VitestProfileError";
+		this.exitCode = exitCode;
+	}
+};
+const durationSummary = (durations) => {
+	const sorted = durations.toSorted((left, right) => left - right);
+	const middle = Math.floor(sorted.length / 2);
+	const median = sorted.length % 2 === 0 ? ((sorted[middle - 1] ?? 0) + (sorted[middle] ?? 0)) / 2 : sorted[middle] ?? 0;
+	return {
+		maximum: sorted.at(-1) ?? 0,
+		mean: durations.reduce((sum, value) => sum + value, 0) / durations.length,
+		median,
+		minimum: sorted[0] ?? 0
+	};
+};
+const relativePath = (cwd, file) => path.relative(cwd, file).split(path.sep).join("/");
+/**
+* Fold one Vitest JSON report into a profile sample: file and test timings,
+* both sorted slowest first, plus the run's counts. A missing report (crash,
+* timeout, unwritable output) yields a sample with `reportAvailable: false`
+* rather than nothing at all.
+*/
+const normalizeVitestProfileSample = (report, input) => {
+	const files = (report?.testResults ?? []).map((file) => ({
+		durationMs: Math.max(0, file.endTime - file.startTime),
+		path: relativePath(input.cwd, file.name),
+		status: file.status
+	})).toSorted((left, right) => right.durationMs - left.durationMs);
+	const tests = (report?.testResults ?? []).flatMap((file) => file.assertionResults.map((test) => ({
+		durationMs: Math.max(0, test.duration ?? 0),
+		file: relativePath(input.cwd, file.name),
+		name: test.fullName,
+		status: test.status
+	}))).toSorted((left, right) => right.durationMs - left.durationMs);
+	return {
+		counts: report ? {
+			failed: report.numFailedTests,
+			passed: report.numPassedTests,
+			pending: report.numPendingTests,
+			suites: report.numTotalTestSuites,
+			tests: report.numTotalTests,
+			todo: report.numTodoTests
+		} : null,
+		durationMs: input.durationMs,
+		endedAt: input.endedAt.toISOString(),
+		exitCode: input.exitCode,
+		failure: input.failure ?? null,
+		files,
+		reportAvailable: report !== null,
+		sample: input.sample,
+		startedAt: input.startedAt.toISOString(),
+		tests
+	};
+};
+const aggregateSlowFiles = (runs, limit) => {
+	const durations = /* @__PURE__ */ new Map();
+	for (const file of runs.flatMap((run) => run.files)) {
+		const recorded = durations.get(file.path) ?? [];
+		recorded.push(file.durationMs);
+		durations.set(file.path, recorded);
+	}
+	return [...durations].map(([filePath, values]) => ({
+		durationMs: durationSummary(values),
+		path: filePath,
+		samples: values.length
+	})).toSorted((left, right) => right.durationMs.median - left.durationMs.median).slice(0, limit);
+};
+const aggregateSlowTests = (runs, limit) => {
+	const timings = /* @__PURE__ */ new Map();
+	for (const test of runs.flatMap((run) => run.tests)) {
+		const key = `${test.file}\0${test.name}`;
+		const recorded = timings.get(key) ?? {
+			durations: [],
+			file: test.file,
+			name: test.name
+		};
+		recorded.durations.push(test.durationMs);
+		timings.set(key, recorded);
+	}
+	return [...timings.values()].map(({ durations, file, name }) => ({
+		durationMs: durationSummary(durations),
+		file,
+		name,
+		samples: durations.length
+	})).toSorted((left, right) => right.durationMs.median - left.durationMs.median).slice(0, limit);
+};
+const gitValue = (cwd, args) => {
+	try {
+		return execFileSync("git", args, {
+			cwd,
+			encoding: "utf-8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim();
+	} catch {
+		return null;
+	}
+};
+const resolveVitestPackage = (cwd) => createRequire(path.join(path.resolve(cwd), "noop.js")).resolve("vitest/package.json");
+/**
+* Record the machine and commit a profile was taken on. Vitest's version is
+* resolved from `cwd`, so it is the consumer's Vitest and not this package's.
+* Git failures degrade to `null` — an artifact from a tarball checkout is still
+* a usable measurement.
+*/
+const captureVitestProfileEnvironment = async (options) => {
+	const gitDirectory = options.gitDirectory ?? options.cwd;
+	let vitestVersion = "unknown";
+	try {
+		vitestVersion = JSON.parse(await readFile(resolveVitestPackage(options.cwd), "utf-8")).version ?? "unknown";
+	} catch {
+		vitestVersion = "unknown";
+	}
+	const processors = cpus();
+	const status = gitValue(gitDirectory, ["status", "--porcelain"]);
+	return {
+		arch: arch(),
+		availableParallelism: availableParallelism(),
+		cpuCount: processors.length,
+		cpuModel: processors[0]?.model ?? null,
+		gitDirty: status === null ? null : status.length > 0,
+		gitHead: gitValue(gitDirectory, ["rev-parse", "HEAD"]),
+		node: process.version,
+		osRelease: release(),
+		platform: platform(),
+		totalMemoryBytes: totalmem(),
+		vitest: vitestVersion
+	};
+};
+const spawnVitest = async ({ cwd, maxWorkers, reportPath, stdio }) => {
+	const vitestCli = path.join(path.dirname(resolveVitestPackage(cwd)), "vitest.mjs");
+	const started = performance.now();
+	const child = spawn(process.execPath, [
+		vitestCli,
+		"run",
+		"--reporter=json",
+		`--outputFile=${reportPath}`,
+		`--maxWorkers=${maxWorkers}`
+	], {
+		cwd,
+		stdio
+	});
+	let timedOut = false;
+	let forceKillTimer;
+	const timeoutTimer = setTimeout(() => {
+		timedOut = true;
+		child.kill("SIGTERM");
+		forceKillTimer = setTimeout(() => {
+			child.kill("SIGKILL");
+		}, TERMINATION_GRACE_MS);
+	}, RUN_TIMEOUT_MS);
+	let exitCode = 0;
+	let failure = null;
+	try {
+		const [code, signal] = await once(child, "exit");
+		exitCode = code ?? (signal ? 1 : 0);
+	} catch (error) {
+		exitCode = 1;
+		failure = `Vitest could not start: ${error instanceof Error ? error.message : String(error)}`;
+	} finally {
+		clearTimeout(timeoutTimer);
+		if (forceKillTimer) clearTimeout(forceKillTimer);
+	}
+	if (timedOut) failure = `Vitest profile sample exceeded ${RUN_TIMEOUT_MS}ms and was terminated.`;
+	let report = null;
+	try {
+		report = JSON.parse(await readFile(reportPath, "utf-8"));
+	} catch (error) {
+		const reportFailure = `Vitest JSON report unavailable: ${error instanceof Error ? error.message : String(error)}`;
+		failure = failure ? `${failure} ${reportFailure}` : reportFailure;
+	}
+	return {
+		durationMs: Math.max(0, performance.now() - started),
+		exitCode: timedOut ? 1 : exitCode,
+		failure,
+		report
+	};
+};
+/**
+* Write a profile document atomically: a partial file must never be readable
+* as a complete measurement, and the profile is rewritten after every sample.
+*/
+const writeVitestProfile = async (outputPath, profile) => {
+	await mkdir(path.dirname(outputPath), { recursive: true });
+	const temporaryPath = `${outputPath}.tmp`;
+	await writeFile(temporaryPath, `${JSON.stringify(profile, null, 2)}\n`, "utf-8");
+	await rename(temporaryPath, outputPath);
+};
+/**
+* Take `samples` serial Vitest runs at one worker count and persist the profile
+* after each one. Samples never overlap: concurrent runs would measure CPU and
+* I/O contention instead of the worker count under test. A failing sample
+* throws `VitestProfileError` with the partial profile already written.
+*/
+const runVitestProfile = async (options, dependencies = {}) => {
+	if (!Number.isSafeInteger(options.samples) || options.samples < 1) throw new Error("runVitestProfile: samples must be a positive integer.");
+	const now = dependencies.now ?? (() => /* @__PURE__ */ new Date());
+	const runSample = dependencies.runSample ?? spawnVitest;
+	const writeResult = dependencies.writeResult ?? writeVitestProfile;
+	const startedAt = now();
+	const rawRoot = path.join(`${options.outputPath}.raw`, randomUUID());
+	await mkdir(rawRoot, { recursive: true });
+	const profile = {
+		command: [
+			"vitest",
+			"run",
+			"--reporter=json",
+			`--maxWorkers=${options.maxWorkers}`
+		],
+		endedAt: startedAt.toISOString(),
+		environment: await captureVitestProfileEnvironment({
+			cwd: options.cwd,
+			gitDirectory: options.gitDirectory
+		}),
+		options: {
+			maxWorkers: options.maxWorkers,
+			samples: options.samples,
+			slowLimit: options.slowLimit
+		},
+		rawReportDirectory: rawRoot,
+		runs: [],
+		schemaVersion: 1,
+		startedAt: startedAt.toISOString(),
+		summary: {
+			durationMs: {
+				maximum: 0,
+				mean: 0,
+				median: 0,
+				minimum: 0
+			},
+			slowFiles: [],
+			slowTests: []
+		},
+		tool: VITEST_PROFILE_TOOL
+	};
+	for (let sample = 1; sample <= options.samples; sample += 1) {
+		let hookFailure;
+		try {
+			options.onSampleStart?.({
+				maxWorkers: options.maxWorkers,
+				sample,
+				samples: options.samples
+			});
+		} catch (error) {
+			hookFailure = { error };
+		}
+		const sampleStartedAt = now();
+		const reportPath = path.join(rawRoot, `sample-${sample}.json`);
+		const execution = await runSample({
+			cwd: options.cwd,
+			maxWorkers: options.maxWorkers,
+			reportPath,
+			sample,
+			stdio: options.stdio ?? "inherit"
+		});
+		const sampleEndedAt = now();
+		const normalized = normalizeVitestProfileSample(execution.report, {
+			cwd: options.cwd,
+			durationMs: execution.durationMs,
+			endedAt: sampleEndedAt,
+			exitCode: execution.exitCode,
+			failure: execution.failure,
+			sample,
+			startedAt: sampleStartedAt
+		});
+		profile.runs.push(normalized);
+		profile.endedAt = sampleEndedAt.toISOString();
+		profile.summary = {
+			durationMs: durationSummary(profile.runs.map((run) => run.durationMs)),
+			slowFiles: aggregateSlowFiles(profile.runs, options.slowLimit),
+			slowTests: aggregateSlowTests(profile.runs, options.slowLimit)
+		};
+		await writeResult(options.outputPath, profile);
+		try {
+			options.onSampleComplete?.({
+				result: normalized,
+				sample,
+				samples: options.samples
+			});
+		} catch (error) {
+			hookFailure ??= { error };
+		}
+		if (execution.exitCode !== 0 || execution.report?.success !== true) throw new VitestProfileError(`Vitest profile sample ${sample} failed; partial results saved.`, execution.exitCode || 1);
+		if (hookFailure) throw hookFailure.error;
+	}
+	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;
+/**
+* GitHub evaluates `${{ }}` before bash ever sees the script, and what it
+* substitutes is not knowable here. Neutralizing each expression to one plain
+* word is what the runner's *shape* looks like: a value in argument position.
+* Leaving them in would make every workflow fail to parse; expanding them to
+* nothing would silently change quoting.
+*
+* Scanned rather than matched with a lazy regex, because `}}` occurs inside
+* Actions string literals: `format('refs/{{0}}', github.ref_name)` escapes a
+* literal brace pair that way, and stopping there would leave half an
+* expression in the script and report a parse error the runner never sees.
+*/
+const neutralizeExpressions = (script) => {
+	let out = "";
+	let cursor = 0;
+	while (cursor < script.length) {
+		const start = script.indexOf("${{", cursor);
+		if (start === -1) {
+			out += script.slice(cursor);
+			break;
+		}
+		out += script.slice(cursor, start);
+		let scan = start + 3;
+		let quote;
+		let end = -1;
+		while (scan < script.length) {
+			const char = script[scan];
+			if (quote === void 0) {
+				if (char === "'" || char === "\"") quote = char;
+				else if (char === "}" && script[scan + 1] === "}") {
+					end = scan + 2;
+					break;
+				}
+			} else if (char === quote) if (script[scan + 1] === quote) scan += 1;
+			else quote = void 0;
+			scan += 1;
+		}
+		if (end === -1) {
+			out += script.slice(start);
+			break;
+		}
+		out += "FACTORY_ACTIONS_EXPRESSION";
+		cursor = end;
+	}
+	return out;
+};
+/** Strip one layer of YAML single quoting from a scalar value. */
+const unquote = (raw) => {
+	const value = raw.trim();
+	if (value.startsWith("'") && value.endsWith("'") && value.length > 1) return value.slice(1, -1).replaceAll("''", "'");
+	return value;
+};
+const indentOf = (line) => line.length - line.trimStart().length;
+/**
+* Where a mapping key sits, counting the `- ` sequence marker as indentation:
+* `- name:` and the `run:` below it are siblings in the same step even though
+* their raw columns differ by two.
+*/
+const keyIndentOf = (line) => indentOf(line) + (line.trimStart().startsWith("- ") ? 2 : 0);
+/** A sibling scalar of the `run:` key under inspection, when the line is one. */
+const keyValueAt = (line, indent, key) => {
+	if (keyIndentOf(line) !== indent) return;
+	const rest = line.trimStart().replace(/^-\s+/u, "");
+	return rest.startsWith(`${key}:`) ? rest.slice(key.length + 1) : void 0;
+};
+/**
+* Every `defaults: { run: { shell } }` in the document, with the span it
+* governs: the mapping that declares it, which is the whole workflow at the
+* top level and one job under `jobs:`.
+*
+* GitHub resolves a step's interpreter as step `shell:`, then the job's
+* default, then the workflow's, then bash. A scanner that only looked at the
+* step would call every step in a `defaults.run.shell: sh` workflow bash and
+* report a pass for scripts `sh` cannot parse — the very false negative this
+* control exists to close.
+*/
+const defaultShellScopes = (lines) => {
+	const scopes = [];
+	for (const [index, line] of lines.entries()) {
+		if (line.trim() !== "defaults:") continue;
+		const depth = keyIndentOf(line);
+		const shell = (() => {
+			let inRun = false;
+			for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
+				const candidate = lines[cursor];
+				if (candidate.trim().length === 0) continue;
+				if (keyIndentOf(candidate) <= depth) return;
+				if (keyValueAt(candidate, depth + 2, "run") !== void 0) {
+					inRun = true;
+					continue;
+				}
+				if (keyIndentOf(candidate) <= depth + 2) {
+					inRun = false;
+					continue;
+				}
+				const value = inRun ? keyValueAt(candidate, depth + 4, "shell") : void 0;
+				if (value !== void 0) return unquote(value);
+			}
+		})();
+		if (shell === void 0) continue;
+		let start = 0;
+		for (let cursor = index - 1; cursor >= 0; cursor -= 1) if (lines[cursor].trim().length > 0 && keyIndentOf(lines[cursor]) < depth) {
+			start = cursor;
+			break;
+		}
+		let end = lines.length;
+		for (let cursor = index + 1; cursor < lines.length; cursor += 1) if (lines[cursor].trim().length > 0 && keyIndentOf(lines[cursor]) < depth) {
+			end = cursor;
+			break;
+		}
+		scopes.push({
+			depth,
+			end,
+			shell,
+			start
+		});
+	}
+	return scopes;
+};
+/** The innermost `defaults.run.shell` governing a line, if any. */
+const inheritedShell = (scopes, index) => scopes.filter((scope) => index >= scope.start && index < scope.end).toSorted((left, right) => right.depth - left.depth).at(0)?.shell;
+/**
+* Every `run:` block in a generated workflow, paired with the `shell:` its
+* step declares.
+*
+* Deliberately a scanner over the emitted text and not a YAML parse: this
+* package takes no dependency it does not need, and the emitted shape is one
+* generator's output, not arbitrary YAML. It reads both block scalars
+* (`run: |-`) and inline scripts.
+*/
+const workflowRunBlocks = (yaml) => {
+	const lines = yaml.split("\n");
+	const scopes = defaultShellScopes(lines);
+	const blocks = [];
+	for (const [index, line] of lines.entries()) {
+		const match = RUN_KEY.exec(line);
+		if (match?.groups === void 0) continue;
+		const keyIndent = keyIndentOf(line);
+		const inline = match.groups.inline.trim();
+		let script;
+		let end = index;
+		if (inline.startsWith(">")) throw new Error(`folded (\`run: >\`) scripts are not supported: YAML folds their line breaks into spaces, so what bash parses is not what is written. Use a literal block (\`run: |\`).`);
+		if (inline.trimStart().startsWith("\"")) throw new Error(`double-quoted \`run:\` scalars are not supported: their YAML escapes would have to be decoded before bash sees them. Use a literal block (\`run: |\`) or an unquoted scalar.`);
+		if (inline.startsWith("|")) {
+			const body = [];
+			for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
+				const candidate = lines[cursor];
+				if (candidate.trim().length > 0 && indentOf(candidate) <= keyIndent) break;
+				body.push(candidate);
+				end = cursor;
+			}
+			const strip = Math.min(...body.filter((entry) => entry.trim().length > 0).map((entry) => indentOf(entry)));
+			script = body.map((entry) => entry.slice(strip)).join("\n");
+		} else if (inline.length > 0) script = unquote(inline);
+		else continue;
+		let shell;
+		let step;
+		const readSibling = (line_) => {
+			shell ??= keyValueAt(line_, keyIndent, "shell");
+			step ??= keyValueAt(line_, keyIndent, "name");
+		};
+		for (let cursor = index; cursor >= 0 && keyIndentOf(lines[cursor]) >= keyIndent; cursor -= 1) {
+			readSibling(lines[cursor]);
+			if (lines[cursor].trimStart().startsWith("- ")) break;
+		}
+		for (let cursor = end + 1; cursor < lines.length; cursor += 1) {
+			if (keyIndentOf(lines[cursor]) < keyIndent || lines[cursor].trimStart().startsWith("- ")) break;
+			readSibling(lines[cursor]);
+		}
+		const effectiveShell = shell === void 0 ? inheritedShell(scopes, index) : unquote(shell);
+		blocks.push({
+			script,
+			...effectiveShell === void 0 ? {} : { shell: effectiveShell },
+			...step === void 0 ? {} : { step: unquote(step) }
+		});
+	}
+	return blocks;
+};
+/** `NAME=value` in a shell command template, as `env` takes them. */
+const ASSIGNMENT = /^[A-Za-z_]\w*=/u;
+/**
+* Interpreters GitHub supports that this control deliberately leaves alone.
+* Named rather than inferred, so an unfamiliar command fails loudly instead of
+* being skipped as though it had been considered.
+*/
+const NON_SHELL_INTERPRETERS = new Set([
+	"cmd",
+	"powershell",
+	"pwsh",
+	"python",
+	"python3"
+]);
+/**
+* The interpreter that will parse a step's script, or `undefined` for one this
+* control leaves alone.
+*
+* A step declaring no shell gets bash: that is GitHub's default for `run:` on
+* Linux runners. A step declaring `sh` gets `sh`, because the runner runs it
+* with `sh` — whose grammar is narrower than bash's, so parsing it with bash
+* would report a pass for a script the runner cannot run. Anything else
+* (pwsh, python, cmd) is not this control's business.
+*/
+const parserFor = (shell) => {
+	if (shell === void 0) return ["bash"];
+	const argv = [];
+	let interpreter;
+	for (const token of shell.trim().split(/\s+/u)) {
+		if (token === "{0}") break;
+		if (interpreter !== void 0) {
+			argv.push(token);
+			continue;
+		}
+		const executable = token.slice(token.lastIndexOf("/") + 1);
+		if (executable === "bash" || executable === "sh") interpreter = token;
+		else if (!(executable === "env" || token.startsWith("-") || ASSIGNMENT.test(token))) {
+			if (NON_SHELL_INTERPRETERS.has(executable)) return;
+			throw new Error(`unrecognized \`shell:\` command: ${shell}. This control parses bash and sh scripts and knowingly skips pwsh, powershell, python, and cmd; it refuses rather than guess at anything else.`);
+		}
+		argv.push(token);
+	}
+	if (interpreter === void 0) throw new Error(`unrecognized \`shell:\` command: ${shell}. No interpreter to parse the script with.`);
+	return argv;
+};
+/** Every `run:` block its interpreter refuses to parse. Empty means sound. */
+const workflowShellParseFailures = (yaml) => {
+	const failures = [];
+	for (const block of workflowRunBlocks(yaml)) {
+		const parser = parserFor(block.shell);
+		if (parser === void 0) continue;
+		const [executable, ...parserArgs] = parser;
+		const script = neutralizeExpressions(block.script);
+		try {
+			execFileSync(executable, [...parserArgs, "-n"], {
+				input: script,
+				stdio: [
+					"pipe",
+					"ignore",
+					"pipe"
+				]
+			});
+		} catch (error) {
+			failures.push({
+				script,
+				...block.step === void 0 ? {} : { step: block.step },
+				stderr: String(error.stderr ?? error).trim()
+			});
+		}
+	}
+	return failures;
+};
+/**
+* Fail the generated-workflow lint when any embedded `run:` block is not
+* parseable bash. Call it on the YAML a generator is about to write, so the
+* defect is caught at generation rather than by the runner.
+*/
+const assertWorkflowShellParses = (yaml, options) => {
+	const failures = workflowShellParseFailures(yaml);
+	if (failures.length === 0) return;
+	const detail = failures.map((failure) => `  - ${failure.step ?? "unnamed step"}: ${failure.stderr.replaceAll("\n", "\n    ")}`).join("\n");
+	throw new Error(`${options.source} emits shell bash cannot parse; the runner would treat it as a no-op:\n${detail}`);
+};
+//#endregion
+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, FACTORY_PUSH_IDENTITY_ARTIFACT_PREFIX, FACTORY_PUSH_IDENTITY_CHECKOUT_STEP_ID, FACTORY_PUSH_IDENTITY_DOWNLOAD_STEP_ID, FACTORY_PUSH_IDENTITY_LOOKUP_STEP_ID, FACTORY_PUSH_IDENTITY_RECORD_STEP_ID, FACTORY_PUSH_IDENTITY_SCHEMA_VERSION, FACTORY_PUSH_IDENTITY_VALIDATE_STEP_ID, 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, factoryPushIdentityConsumer, factoryPushIdentityProducer, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, productionImpactTargetOutput, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };