@patronage/factory-ci 0.1.2 → 0.2.0

package/README.md

@@ -12,7 +12,7 @@ It is a **pure library**. There is no `bin`: anything invocable belongs to `psf`
 
 Three repositories independently built the same scaffolding and then drifted: three wordings of the same setup block, the same `@v4` action tags pinned to different commits because they were generated months apart, two esbuild pre-bundles, two Alchemy CLI wrappers, and one disposable-stage grammar invented twice.
 
-The admission rule is **upstream on repetition**: nothing enters this package until it already repeats across at least two projects. Experiments live in one repository first. The public surface is made of three deep modules, not a workflow framework.
+The admission rule is **upstream on repetition**: nothing enters this package until it already repeats across at least two projects. Experiments live in one repository first. The public surface is made of four deep modules, not a workflow framework.
 
 ## Exports
 
@@ -38,8 +38,8 @@ const generated = factoryWorkflow({
   actionFamily: NODE_PNPM_ACTION_FAMILY_NODE24,
   additionalActions: {
     pathsFilter: {
-      tag: "v3",
-      uses: "dorny/paths-filter@d1c1ffe0248fe513906c8e24db8ea791d46f8590",
+      tag: "v4.0.2",
+      uses: "dorny/paths-filter@7b450fff21473bca461d4b92ce414b9d0420d706",
     },
   },
   generated: {
@@ -59,6 +59,42 @@ workflow({/* caller-owned jobs and topology */}).writeOrLint({
 
 The **runner is not this package's business**. Jobs, runners, permissions, workflow topology, and deploy policy remain with the caller. The returned values are plain structural objects; this package does not depend on gagen.
 
+### Proof reuse
+
+```ts
+import {
+  assertProofReuseCoverage,
+  FACTORY_PROOF_GATE_GUARD,
+  factoryProofGateStep,
+} from "@patronage/factory-ci";
+
+import profile from "../../software-factory.profile.json" with { type: "json" };
+
+const coreCommands = profile.verification.commands.filter(
+  ({ name }) => !name.startsWith("docs:")
+);
+
+const core = job("core", {
+  permissions: { checks: "read", contents: "read" },
+  steps: [
+    step(factoryProofGateStep({ commands: coreCommands, surface: "core" })),
+    ...guardedSteps.map((s) => ({ ...s, if: FACTORY_PROOF_GATE_GUARD })),
+  ],
+});
+```
+
+The **proof-reuse gate** decides whether a hosted job may reuse the local verification the factory already published for this exact head (ADR 0022). Refusing runs hosted CI; it never fails the candidate. The App identity, check name, step id, output names, guard, and every trust predicate are fixed here rather than consumer-configurable — three repositories had grown three answers to the same question and had already drifted.
+
+A proof is reusable only when the complete Checks API result (`filter=all`, every page) establishes one unambiguous newest generation by greatest `started_at`, produced by the pinned App for the exact repository and head, completed successfully with `outcome: passed`, and covering every command identity the guarded surface requires. `mode` is reported as diagnostic metadata, never authorized on: a reduced-mode proof that ran everything a surface requires is reusable.
+
+The only thing a consumer chooses is **what its surface requires**, expressed as the plain profile command objects that surface selects — a repository with distinct core and docs jobs selects distinct sets and gets distinct required coverage. `proofReuseRequiredCommands()` is the single derivation both the gate and the assertion go through. Identities are baked into the emitted script, so they are held to a plain `[A-Za-z0-9_][\w.:@/-]*` allow-list and shell-quoted at the interpolation site; a selection carrying anything else is unusable and degrades to a gate that always refuses.
+
+The gate is a **step, not a job**, marked `continue-on-error`, with no `set -e`. A gate job that errored would leave the guarded job `skipped`, which a summary job that only fails on `failure` / `cancelled` reports as green. As a step it fails open by construction: the step errors, the output is never written, the `!= 'true'` guard reads empty, and every command runs. It writes a machine-readable `reason` output — `proven | none | pending | failed | unreadable | incomplete | ambiguous | error` — so a reuse-collapses-to-never regression is visible instead of hidden behind fail-open.
+
+**Emit the step's `shell` verbatim.** `factoryProofGateStep()` sets `shell: bash --noprofile --norc {0}` (`FACTORY_PROOF_GATE_SHELL`) and a generator that drops it breaks the gate. GitHub's default for `run:` is `bash -e {0}` — errexit arrives from the invocation, not the script, so omitting `set -e` does not achieve it. Under the default the gate dies at the first non-zero command before its single `GITHUB_OUTPUT` write: no verdict, no `reason`, reuse silently collapsed to never while the job looks like healthy full CI. `shell: bash` is not a substitute; it expands to `bash --noprofile --norc -eo pipefail {0}`. The script is written to survive errexit as well, and its tests execute every case under both shells — a harness that runs this script under friendlier flags than the runner does is worse than no harness.
+
+`assertProofReuseCoverage({ commands, skipped, surface })` is the compile-time guard in front of the runtime `incomplete` refusal: hand it the same selection and the command strings the workflow would skip, and it fails the consumer's build when the two drift apart. Extracting the skipped strings stays with the consumer — this package never parses workflow source, because establishing trust that way is what killed an earlier attempt.
+
 ### Alchemy entries
 
 ```ts
@@ -89,7 +125,7 @@ The tests pack the actual tarball, extract it into a throwaway external consumer
 
 ## No configuration surface
 
-Functions take plain typed options objects. Proof and preview configuration lives in the canonical `software-factory.profile.json` schema, never in this package (ADR 0021); mapping a profile into these options is the profile's job.
+Functions take plain typed objects. Proof and preview configuration lives in the canonical `software-factory.profile.json` schema, never in this package (ADR 0021); consumers pass the relevant profile policy directly at generation time.
 
 ## Secrets
 

package/dist/index.d.ts

@@ -225,4 +225,225 @@ interface ExecuteAlchemyEntryResult {
  */
 declare const executeAlchemyEntry: (options: ExecuteAlchemyEntryOptions) => Promise<ExecuteAlchemyEntryResult>;
 //#endregion
-export { type BundleAlchemyEntryOptions, type CheckoutStepOptions, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, type FactoryWorkflowArtifact, type FactoryWorkflowOptions, type FactoryWorkflowSetupOptions, type InstallStepOptions, type LocalPreviewStage, type LocalPreviewStageOptions, NODE_PNPM_ACTION_FAMILY_NODE24, type NodePnpmActionFamily, type ParseLocalPreviewStageExpected, type ParsedLocalPreviewStage, type PinnedAction, type SetupNodeStepOptions, type WorkflowStep, bundleAlchemyEntry, executeAlchemyEntry, factoryWorkflow, isLocalPreviewStage, localPreviewStage, parseLocalPreviewStage };
+//#region src/proof-reuse-gate.d.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.
+ */
+/**
+ * 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.
+ */
+declare 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.
+ */
+declare const FACTORY_PROOF_GATE_APP_ID = "4314840";
+/** Step id the guard condition refers to. */
+declare 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.
+ */
+declare const FACTORY_PROOF_GATE_SHELL = "bash --noprofile --norc {0}";
+/** Output the verdict is written to. `true` — and only `true` — skips. */
+declare 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.
+ */
+declare 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.
+ */
+declare 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.
+ */
+declare const FACTORY_PROOF_GATE_GUARD = "steps.factory-proof.outputs.reuse-proof != '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.
+ */
+declare 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.
+ */
+declare const FACTORY_PROOF_GATE_REASONS: readonly ["proven", "none", "pending", "failed", "unreadable", "incomplete", "ambiguous", "error"];
+type FactoryProofGateReason = (typeof FACTORY_PROOF_GATE_REASONS)[number];
+/**
+ * One entry of a consumer's `verification.commands` (ADR 0021). Only the two
+ * load-bearing fields are declared: `name` is the command *identity* the proof
+ * records in `executedCommands`, `command` is the string the static coverage
+ * assertion matches against the work a reused proof would skip.
+ */
+interface ProofReuseCommand {
+  readonly command: string;
+  readonly name: string;
+}
+/**
+ * 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.
+ */
+declare const proofReuseRequiredCommands: (commands: readonly ProofReuseCommand[]) => readonly string[] | undefined;
+interface FactoryProofGateOptions {
+  /**
+   * The profile command objects this guarded surface selected. A consumer with
+   * distinct core and docs jobs selects distinct sets, and each job's gate
+   * therefore requires a different coverage.
+   */
+  readonly commands: readonly ProofReuseCommand[];
+  /** Names the suite in the job summary. Changes no trust decision. */
+  readonly surface: string;
+}
+/**
+ * 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.
+ */
+declare const factoryProofGateScript: ({
+  commands,
+  surface
+}: FactoryProofGateOptions) => string;
+interface FactoryProofGateStep {
+  readonly continueOnError: true;
+  readonly env: Readonly<{
+    GH_TOKEN: string;
+    HEAD_SHA: string;
+  }>;
+  readonly id: typeof FACTORY_PROOF_GATE_STEP_ID;
+  readonly if: typeof FACTORY_PROOF_GATE_IF;
+  readonly name: string;
+  readonly run: string;
+  readonly shell: typeof FACTORY_PROOF_GATE_SHELL;
+}
+/**
+ * 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.
+ */
+declare const factoryProofGateStep: (options: FactoryProofGateOptions) => FactoryProofGateStep;
+interface ProofReuseCoverageInput {
+  /** The same selection handed to the gate for this surface. */
+  readonly commands: readonly ProofReuseCommand[];
+  /**
+   * Skipped work covered under a different command string, keyed by the
+   * skipped string with the reason as its value. Deliberately explicit: a
+   * prose rationale for why some narrower command is "equivalent enough" is
+   * exactly what this assertion exists to force into the open.
+   */
+  readonly equivalents?: Readonly<Record<string, string>>;
+  /**
+   * The command strings the consumer's workflow would skip when the gate says
+   * `true`, already resolved to the leaves that actually run. Extracting them
+   * is the consumer's job: this package never parses workflow source, because
+   * doing so is what killed #288.
+   */
+  readonly skipped: readonly string[];
+  /** Names the surface in the failure message. */
+  readonly surface?: string;
+}
+interface ProofReuseCoverageReport {
+  /** True only when the selection is usable *and* nothing is uncovered. */
+  readonly covered: boolean;
+  /** Command identities derived from the selection; empty when unusable. */
+  readonly requiredCommands: readonly string[];
+  /** Skipped command strings no selected profile command accounts for. */
+  readonly uncovered: readonly string[];
+}
+/**
+ * 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.
+ */
+declare const proofReuseCoverage: ({
+  commands,
+  equivalents,
+  skipped
+}: ProofReuseCoverageInput) => ProofReuseCoverageReport;
+/** `proofReuseCoverage`, as a build failure. */
+declare const assertProofReuseCoverage: (input: ProofReuseCoverageInput) => ProofReuseCoverageReport;
+//#endregion
+export { type BundleAlchemyEntryOptions, type CheckoutStepOptions, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, 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, type FactoryProofGateOptions, type FactoryProofGateReason, type FactoryProofGateStep, type FactoryWorkflowArtifact, type FactoryWorkflowOptions, type FactoryWorkflowSetupOptions, type InstallStepOptions, type LocalPreviewStage, type LocalPreviewStageOptions, NODE_PNPM_ACTION_FAMILY_NODE24, type NodePnpmActionFamily, type ParseLocalPreviewStageExpected, type ParsedLocalPreviewStage, type PinnedAction, type ProofReuseCommand, type ProofReuseCoverageInput, type ProofReuseCoverageReport, type SetupNodeStepOptions, type WorkflowStep, assertProofReuseCoverage, bundleAlchemyEntry, executeAlchemyEntry, factoryProofGateScript, factoryProofGateStep, factoryWorkflow, isLocalPreviewStage, localPreviewStage, parseLocalPreviewStage, proofReuseCoverage, proofReuseRequiredCommands };