@patronage/factory-ci 0.1.2 → 0.2.0

package/dist/index.js

@@ -241,4 +241,518 @@ const executeAlchemyEntry = async (options) => {
 	};
 };
 //#endregion
-export { NODE_PNPM_ACTION_FAMILY_NODE24, bundleAlchemyEntry, executeAlchemyEntry, factoryWorkflow, isLocalPreviewStage, localPreviewStage, parseLocalPreviewStage };
+//#region src/proof-reuse-gate.ts
+/**
+* The GitHub-side **proof-reuse gate** (ADR 0022, #309, #317).
+*
+* It answers one question, before checkout and before install: may this job
+* reuse the local verification the factory already published for *this exact
+* head*? Refusing runs hosted CI; it never fails the candidate. Three
+* repositories had independently grown their own answer to that question and
+* had already drifted apart, so the answer lives here once, with the App
+* identity, check name, step identity, output names, guard, and every trust
+* predicate fixed rather than consumer-configurable.
+*
+* What a consumer chooses is only *what its guarded surface requires*: the
+* plain profile command objects that surface selects. Everything else below is
+* the same for every consumer and every surface.
+*/
+/**
+* Escaped so the emitted text carries a GitHub Actions expression rather than
+* this file carrying a JavaScript template hole.
+*/
+const githubExpression = (expression) => `\${{ ${expression} }}`;
+/** A braced shell expansion that has to survive TypeScript interpolation. */
+const shellExpansion = (expression) => `\${${expression}}`;
+/**
+* Single-quote a value for the emitted script. Every non-literal value that
+* reaches the script goes through this.
+*
+* `JSON.stringify` is *not* a shell quoter — it escapes `"` and `\` and leaves
+* `'` untouched — so interpolating a JSON document straight into a
+* single-quoted assignment lets one apostrophe in a profile command name close
+* the assignment and run the remainder as shell. Names are charset-validated
+* before they get here; this is the second layer, so the interpolation stays
+* safe if that validation is ever loosened.
+*/
+const shellSingleQuote = (value) => `'${value.replaceAll("'", String.raw`'\''`)}'`;
+/**
+* The check run the gate reads. Fixed: `patronage-factory/pr-verify` is also
+* postable as a *commit status* by any token with write access, so only the
+* Checks API is ever consulted and only under this exact name.
+*/
+const FACTORY_PROOF_GATE_CHECK_NAME = "patronage-factory/pr-verify";
+/**
+* The Patronage Factory GitHub App, pinned (ADR 0022). A runner has no
+* operator user config to read the producing App identity from, and the
+* identity is a trust predicate, so it is not a repository variable a consumer
+* can point somewhere else. Neither the id nor the slug is a secret: GitHub
+* returns `app.id` on every check run it serves.
+*/
+const FACTORY_PROOF_GATE_APP_ID = "4314840";
+/** Step id the guard condition refers to. */
+const FACTORY_PROOF_GATE_STEP_ID = "factory-proof";
+/**
+* The shell the gate runs under, and it is a correctness requirement rather
+* than a preference.
+*
+* GitHub's default for a `run:` step is `bash -e {0}`: **errexit comes from
+* the invocation, not from the script**, and no `set +e` in the script body
+* can be relied on to express the intent because the abort happens at the
+* failing command. The whole fail-open design below — every path reaching one
+* final `GITHUB_OUTPUT` write, no `set -e` — is void under that default. It
+* was: the gate died at a `read` returning 1 at EOF, two seconds in, with no
+* stdout, no verdict and no `reason`, so reuse collapsed to never *and* the
+* signal built to reveal that could not fire (#319).
+*
+* A `shell:` value containing `{0}` is used verbatim by the runner, so this
+* form supplies no `-e`. The shorthand `shell: bash` must never be used here:
+* it expands to `bash --noprofile --norc -eo pipefail {0}`. `pipefail` is set
+* by the script itself.
+*
+* The script is additionally written to survive errexit anyway. Both layers
+* are deliberate: this one states the contract, that one means a runner which
+* ignores it still gets a decision.
+*/
+const FACTORY_PROOF_GATE_SHELL = "bash --noprofile --norc {0}";
+/** Output the verdict is written to. `true` — and only `true` — skips. */
+const FACTORY_PROOF_GATE_OUTPUT = "reuse-proof";
+/**
+* Machine-readable refusal category. Fleet-status reads this: it is what makes
+* a reuse-collapses-to-never regression visible instead of hidden behind
+* fail-open, which by construction looks exactly like healthy full CI.
+*/
+const FACTORY_PROOF_GATE_REASON_OUTPUT = "reason";
+/**
+* Recorded verification mode, when the gate could read one. Diagnostic
+* metadata only — never an authorization condition (ADR 0022). A reduced-mode
+* proof that executed every command the surface requires is reusable.
+*/
+const FACTORY_PROOF_GATE_MODE_OUTPUT = "mode";
+/**
+* Guard for every step the gate protects. Deliberately `!= 'true'` and not
+* `== 'false'`: an unset, empty, or garbled output must run the suite.
+*/
+const FACTORY_PROOF_GATE_GUARD = `steps.${FACTORY_PROOF_GATE_STEP_ID}.outputs.${FACTORY_PROOF_GATE_OUTPUT} != 'true'`;
+/**
+* Pull requests only. A push to a protected branch must never skip: deploy
+* gates wait for a green required check at the *merged* SHA, and no local
+* proof was ever written for that tree.
+*/
+const FACTORY_PROOF_GATE_IF = "github.event_name == 'pull_request'";
+/**
+* The complete refusal vocabulary. Deliberately few, because these are the
+* only distinctions the gate can honestly make from one Checks API read.
+*
+* - `proven`     a covering, passing, unambiguous proof for this exact head
+* - `none`       no App-verified factory check run at this commit
+* - `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
+* - `ambiguous`  two newest generations share the greatest start time
+* - `error`      the gate could not reach a decision (fail open)
+*
+* There is no `reduced`: mode stopped being an authorization condition in
+* ADR 0022, so a narrower run that still executed every required command is
+* indistinguishable from a full one *for this surface*, which is the point.
+*/
+const FACTORY_PROOF_GATE_REASONS = [
+	"proven",
+	"none",
+	"pending",
+	"failed",
+	"unreadable",
+	"incomplete",
+	"ambiguous",
+	"error"
+];
+/**
+* Command identities are baked into the emitted script, so their charset is a
+* safety property, not a style rule. `surface` has always gone through
+* `safeLabel` for this reason; `name` needs the same treatment.
+*
+* Deliberately a strict allow-list rather than a quote-escaper: a name is an
+* identifier, and every identity across the fleet's profiles today is
+* `[a-z0-9:-]`. Anything outside this — hostile or merely a stray apostrophe —
+* makes the whole selection unusable, which degrades to the refusing script.
+* A stray apostrophe reaching interpolation would otherwise kill the step with
+* a bash syntax error *before* the single `GITHUB_OUTPUT` write, so reuse
+* would collapse to never with no `reason` written at all — the silent
+* regression the vocabulary exists to make visible.
+*/
+const COMMAND_IDENTITY = /^\w[\w.:@/-]*$/u;
+const COMMAND_IDENTITY_MAX_LENGTH = 120;
+const isProofReuseCommand = (value) => {
+	if (!(value && typeof value === "object")) return false;
+	const entry = value;
+	return typeof entry.command === "string" && entry.command.length > 0 && typeof entry.name === "string" && entry.name.length <= COMMAND_IDENTITY_MAX_LENGTH && COMMAND_IDENTITY.test(entry.name);
+};
+/**
+* The command identities a guarded surface requires, derived from the profile
+* command objects that surface selected. This is the single derivation: the
+* gate script and the static coverage assertion both go through it, so a
+* consumer can never have one notion of "required" at generation time and
+* another at assertion time.
+*
+* `undefined` means the selection is unusable — not an array, empty, or
+* carrying an entry whose `command` is blank or whose `name` is not a plain
+* command identity. An empty required set would make *every* passing proof
+* trivially covering, so it is never silently treated as "requires nothing";
+* callers must refuse instead.
+*/
+const proofReuseRequiredCommands = (commands) => {
+	if (!(Array.isArray(commands) && commands.length > 0)) return;
+	if (!commands.every(isProofReuseCommand)) return;
+	return [...new Set(commands.map(({ name }) => name))].toSorted();
+};
+/**
+* jq program: every page of the Checks API result in, three sanitized lines
+* (`reason`, `mode`, missing 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
+* one document and not wrapped in an array. That is why the script invokes
+* `jq -s` and why this program opens with `.[] | (.check_runs // [])[]`. A
+* test double that emits `[{ "check_runs": [...] }]` instead is a different
+* shape: `jq` fails with `Cannot index array with string ("check_runs")`, the
+* script lands on `reason=error`, and — because the gate fails open — the
+* result looks exactly like healthy full CI. Stub `gh` with a bare response
+* object per page.
+*
+* `binding` recovers the machine-readable payload from `output.text`
+* (preferred) or `output.summary`, which the factory writes as a fenced JSON
+* document. Anything unparseable degrades to `null`, and therefore to a
+* refusal.
+*
+* This is the *second* parser of that payload: `parsePrVerifyCheckPayload`
+* (`software-factory/src/pr-verify-check-payload.ts`) regex-extracts the fenced
+* block, while this one strips fence lines and `fromjson`s what remains. The
+* one input that separates them is prose around the fence, which parses there
+* and refuses here. Both halves of that are asserted in the test suite rather
+* than asserted here in prose — the exact shape the renderer emits is proven,
+* and the divergent shape is proven to fail safe. Two parsers of one payload
+* can drift; what must not drift silently is which direction they drift in.
+*
+* Ordering is by `started_at` alone, normalized to whole seconds. Two
+* generations that share the greatest start time are `ambiguous` rather than
+* arbitrarily resolved: the gate cannot tell which one describes the tree, and
+* silently picking either is exactly the kind of coin-flip authorization this
+* whole mechanism exists to remove. Sub-second precision is dropped so
+* `…:00Z` and `…:00.000Z` compare equal; two genuine verification generations
+* starting within the same second at the same head is not a real state, and
+* collapsing them errs toward refusing.
+*
+* The comparison is lexical, which is correct only for fixed-width UTC. A
+* `+HH:MM` offset would sort by its literal text rather than by its instant,
+* and an absent `started_at` would sort to the bottom. The Checks API returns
+* neither today, so this is guarded rather than merely noted: every candidate
+* must carry a canonical UTC timestamp, and one that does not makes the newest
+* generation unestablishable, which is `ambiguous`. Refusing costs a hosted
+* run; ranking an unorderable set could authorize the wrong one.
+*/
+const GATE_JQ = String.raw`
+def binding:
+  [ .output.text, .output.summary ]
+  | map(select(type == "string"))
+  | map(split("\n") | map(select(startswith("${"```"}") | not)) | join("\n"))
+  | map(. as $body | try ($body | fromjson) catch null)
+  | map(select(type == "object"))
+  | .[0];
+
+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$");
+
+[ .[]
+  | (.check_runs // [])[]
+  | select(.name == $name)
+  | select(((.app.id // "") | tostring) == $app)
+  | { started: startedAt,
+      status: (.status // ""),
+      conclusion: (.conclusion // ""),
+      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", "", ""]
+   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
+     | (if $run.status != "completed" then "pending"
+        elif $run.conclusion != "success" then "failed"
+        elif (($run.binding | type) != "object")
+          or ($proof.kind != "pr-verify-proof-binding")
+          or ($proof.schemaVersion != 1)
+          or ($proof.headSha != $sha)
+          or ($proof.repository != $repository) then "unreadable"
+        elif $proof.outcome != "passed" then "failed"
+        elif ($required | length) == 0 then "incomplete"
+        elif ($missing | length) != 0 then "incomplete"
+        else "proven"
+        end) as $reason
+     | [$reason, $mode, ($missing | join(", "))]
+   end)
+| map(gsub("[\\r\\n\\t]"; " "))
+| join("\n")
+`.trim();
+/**
+* Every refusal ends on the same line. `pr:verify` is the command that
+* produces the proof this job looks for, so it is the corrective action
+* whatever the refusal was.
+*
+* It is phrased as an option, not a reprimand. A pull request opened by hand
+* has no factory proof and never will; the full suite running for it is the
+* designed behavior, not a mistake to report.
+*/
+const CORRECTIVE_LINE = "Run `psf pr:verify` before publishing to reuse local proof and avoid a duplicate server run.";
+/**
+* Emitted when a consumer's command selection is unusable. Mirrors the
+* retired hosted docs-only detector: a malformed profile slice degrades to the
+* conservative answer at *runtime* rather than throwing at generation time,
+* because the input is JSON that may be absent or reshaped. The loud signal is
+* the static coverage assertion, plus `reason=error` on the step output.
+*/
+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")}"`;
+/** Surface labels reach markdown, so only a plain, bounded label survives. */
+const safeLabel = (surface) => {
+	const cleaned = (typeof surface === "string" ? surface : "").replaceAll(/[^\w -]/gu, "").trim().slice(0, 60);
+	return cleaned.length > 0 ? cleaned : "verification";
+};
+const gateScript = (required, surface) => String.raw`
+set -uo pipefail
+
+CHECK_NAME=${shellSingleQuote(FACTORY_PROOF_GATE_CHECK_NAME)}
+FACTORY_APP_ID=${shellSingleQuote(FACTORY_PROOF_GATE_APP_ID)}
+REQUIRED_COMMANDS=${shellSingleQuote(JSON.stringify(required))}
+SURFACE=${shellSingleQuote(surface)}
+
+reason=error
+detail=''
+mode=''
+missing=''
+
+# 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
+  detail='no pull request head SHA'
+elif [ -z "${shellExpansion("GITHUB_REPOSITORY:-")}" ]; then
+  detail='no repository name'
+elif ! response=$(gh api --method GET --paginate \
+    "repos/$GITHUB_REPOSITORY/commits/$HEAD_SHA/check-runs" \
+    -f "check_name=$CHECK_NAME" \
+    -f filter=all \
+    -f per_page=100 2>&1); then
+  detail="checks API unreadable: $response"
+elif ! finding=$(printf '%s' "$response" | jq -r -s \
+    --arg name "$CHECK_NAME" \
+    --arg app "$FACTORY_APP_ID" \
+    --arg sha "$HEAD_SHA" \
+    --arg repository "$GITHUB_REPOSITORY" \
+    --argjson required "$REQUIRED_COMMANDS" \
+    '${GATE_JQ}' 2>&1); then
+  detail="unreadable proof binding: $finding"
+else
+  # Three separate reads, not one IFS split: tab is IFS whitespace, so a
+  # split would collapse the empty fields the vocabulary relies on.
+  #
+  # The trailing "|| :" on each read is load-bearing. "missing" is empty for
+  # every verdict except "incomplete", so jq's third field is the empty
+  # string, command substitution strips the trailing newline, and the third
+  # read reaches EOF -- having correctly assigned "" -- and returns 1. Under
+  # an errexit shell that return value kills the step before the single
+  # GITHUB_OUTPUT write below, which is exactly how this gate failed in
+  # hosted CI on every decidable verdict while every test passed (#319).
+  {
+    IFS= read -r reason || :
+    IFS= read -r mode || :
+    IFS= read -r missing || :
+  } <<< "$finding"
+  case "$reason" in
+    proven | none | pending | failed | unreadable | incomplete | ambiguous) ;;
+    *)
+      detail="unexpected gate result: $reason"
+      reason=error
+      ;;
+  esac
+fi
+
+# The binding is App-verified, but it still reaches markdown. Only a plain
+# lowercase token is quoted back; anything else is reported as unknown.
+case "$mode" in
+  '') ;;
+  *[!a-z-]*) mode='unknown' ;;
+esac
+
+verdict=false
+if [ "$reason" = 'proven' ]; then
+  verdict=true
+fi
+
+# detail can carry arbitrary gh or jq error text. Collapse it to one bounded
+# 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)
+
+SUMMARY="${shellExpansion("GITHUB_STEP_SUMMARY:-/dev/null")}"
+say() { printf '%s\n' "$1" >> "$SUMMARY"; }
+
+say "## Proof reuse: $SURFACE"
+say ''
+
+case "$reason" in
+  proven)
+    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."
+    say "- Covers head: \`$HEAD_SHA\`"
+    say "- Recorded mode: \`$mode\` (diagnostic only), outcome \`passed\`."
+    ;;
+  none)
+    say 'Ran the full suite. No trusted factory proof covers this commit.'
+    say ''
+    say "The factory GitHub App has published no \`$CHECK_NAME\` check run at head \`$HEAD_SHA\`. Proof is keyed to the commit, so proof written for any other commit is not visible here. A pull request opened by hand carries no factory proof at all, which is normal."
+    say ''
+    say '${CORRECTIVE_LINE}'
+    ;;
+  pending)
+    say 'Ran the full suite. The factory proof for this commit had not finished when this job read it.'
+    say ''
+    say "The newest \`$CHECK_NAME\` check run at head \`$HEAD_SHA\` was still in progress. The gate reads one snapshot at job start and does not wait."
+    say ''
+    say "Let \`psf pr:verify\` finish before publishing, so its proof is on the commit before this job reads it."
+    ;;
+  failed)
+    say 'Ran the full suite. The factory proof for this commit records no pass.'
+    say ''
+    say "The newest \`$CHECK_NAME\` check run at head \`$HEAD_SHA\` finished without a passing conclusion, so it establishes nothing about this tree."
+    say ''
+    say '${CORRECTIVE_LINE}'
+    ;;
+  unreadable)
+    say 'Ran the full suite. The factory check run for this commit carries no proof this job can read.'
+    say ''
+    say "The newest \`$CHECK_NAME\` check run at head \`$HEAD_SHA\` passed, but it carries no machine-readable binding naming this repository and this head, or one written to a schema this job does not recognize."
+    say ''
+    say '${CORRECTIVE_LINE}'
+    ;;
+  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 ''
+    say '${CORRECTIVE_LINE}'
+    ;;
+  ambiguous)
+    say 'Ran the full suite. The newest factory proof for this commit is ambiguous.'
+    say ''
+    say "Two \`$CHECK_NAME\` check runs at head \`$HEAD_SHA\` share the greatest start time, so there is no single newest generation to trust. The gate refuses rather than picking one."
+    say ''
+    say '${CORRECTIVE_LINE}'
+    ;;
+  *)
+    say 'Ran the full suite. The proof gate could not reach a decision.'
+    say ''
+    say 'The gate fails open by design: when it cannot tell whether proof exists, every command runs. Nothing about this pull request is implied.'
+    say ''
+    say "    $detail"
+    ;;
+esac
+say ''
+
+if [ "$verdict" != 'true' ]; then
+  echo "No reusable factory proof for ${shellExpansion("HEAD_SHA:-<unknown>")}; running the $SURFACE suite ($reason). $detail"
+fi
+
+# The only write. A crash before this line leaves the output unset, the guard
+# reads empty, and every guarded step runs — the fail-open path.
+{
+  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")}"
+`.trim();
+/**
+* The gate script. Exported so it can be executed directly under test against
+* a stubbed `gh`, rather than only asserted against as workflow text — the
+* script is the security boundary, and asserting on generated YAML would leave
+* its actual decisions untested.
+*
+* Note the deliberate absence of `set -e`: every failure path has to reach the
+* final write, and that write must emit `false`. Omitting it is necessary but
+* not sufficient — the runner supplies `-e` unless the step declares
+* `FACTORY_PROOF_GATE_SHELL` — so the script is also written to reach that
+* write under errexit, and the tests execute it both ways.
+*/
+const factoryProofGateScript = ({ commands, surface }) => {
+	const required = proofReuseRequiredCommands(commands);
+	return required ? gateScript(required, safeLabel(surface)) : UNUSABLE_SELECTION_SCRIPT;
+};
+/**
+* The step itself, structurally accepted by gagen's `step()` without adding a
+* gagen runtime dependency. It belongs first in the job it guards: one Checks
+* API read with the default `GITHUB_TOKEN` (`checks: read`), no checkout, no
+* install, so a proven head costs a runner nothing beyond job startup.
+*
+* A **step, not a job**, and that is not a style preference. A separate gate
+* job that errored would leave the guarded job `skipped`, and a summary job
+* that only fails on `failure`/`cancelled` would still report green — a Checks
+* API outage would silently skip verification. As a step it fails open by
+* construction: the step errors, the output is never written, the guard reads
+* empty, and every command runs.
+*/
+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")
+	}),
+	id: FACTORY_PROOF_GATE_STEP_ID,
+	if: FACTORY_PROOF_GATE_IF,
+	name: "Check for factory proof of this head",
+	run: factoryProofGateScript(options),
+	shell: FACTORY_PROOF_GATE_SHELL
+});
+/**
+* The static coverage assertion, as a report.
+*
+* Runtime command coverage is authoritative — the gate's `incomplete` refusal
+* is the backstop that cannot be bypassed. This is the compile-time guard in
+* front of it: it fails a consumer's build the moment a workflow skips work
+* that no selected profile command runs, rather than letting the drift show up
+* as CI quietly verifying nothing. The drift is real history: #227 wired a
+* workspace member into CI while the profile never learned about it.
+*/
+const proofReuseCoverage = ({ commands, equivalents = {}, skipped }) => {
+	const requiredCommands = proofReuseRequiredCommands(commands) ?? [];
+	const proven = new Set(requiredCommands.length > 0 ? commands.map(({ command }) => command.trim()) : []);
+	const uncovered = [...new Set((Array.isArray(skipped) ? skipped : []).map((command) => String(command).trim()).filter((command) => command.length > 0 && !(proven.has(command) || Object.hasOwn(equivalents, command))))].toSorted();
+	return Object.freeze({
+		covered: requiredCommands.length > 0 && uncovered.length === 0,
+		requiredCommands,
+		uncovered
+	});
+};
+/** `proofReuseCoverage`, as a build failure. */
+const assertProofReuseCoverage = (input) => {
+	const report = proofReuseCoverage(input);
+	if (report.covered) return report;
+	const surface = safeLabel(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 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@patronage/factory-ci",
-  "version": "0.1.2",
-  "description": "Deep CI and deploy building blocks for Patronage factory projects: workflow source artifacts, Alchemy entry execution, and disposable-stage semantics",
+  "version": "0.2.0",
+  "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",
     "cloudflare",

package/src/index.ts

@@ -3,9 +3,9 @@
  * repeat across Patronage factory projects (#266, #268).
  *
  * A pure library: no `bin`, no `alchemy` or `effect` dependency, no config
- * surface of its own. Everything takes a plain typed options object; mapping
- * `software-factory.profile.json` into those objects is the profile's job, not
- * this package's (ADR 0021).
+ * surface of its own. Everything takes plain typed values; callers pass
+ * canonical policy from `software-factory.profile.json` without this package
+ * loading or owning that profile (ADR 0021).
  */
 
 export {
@@ -41,3 +41,26 @@ export {
   type ExecuteAlchemyEntryResult,
   executeAlchemyEntry,
 } from "./execute-alchemy-entry.ts";
+export {
+  assertProofReuseCoverage,
+  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_REASON_OUTPUT,
+  FACTORY_PROOF_GATE_REASONS,
+  FACTORY_PROOF_GATE_SHELL,
+  FACTORY_PROOF_GATE_STEP_ID,
+  type FactoryProofGateOptions,
+  type FactoryProofGateReason,
+  factoryProofGateScript,
+  type FactoryProofGateStep,
+  factoryProofGateStep,
+  type ProofReuseCommand,
+  proofReuseCoverage,
+  type ProofReuseCoverageInput,
+  type ProofReuseCoverageReport,
+  proofReuseRequiredCommands,
+} from "./proof-reuse-gate.ts";