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

package/README.md

@@ -20,7 +20,10 @@ The admission rule is **upstream on repetition**: nothing enters this package un
 
 ```ts
 import {
+  FACTORY_CANDIDATE_PULL_REQUEST_TYPES,
+  factoryProductionImpactWorkflow,
   factoryWorkflow,
+  factoryCandidateOrPushCondition,
   NODE_PNPM_ACTION_FAMILY_NODE24,
 } from "@patronage/factory-ci";
 ```
@@ -47,6 +50,7 @@ const generated = factoryWorkflow({
     regenerate: "pnpm workflows:generate",
   },
   setup: {
+    checkout: { fetchDepth: 0, ref: "${{ github.sha }}" },
     setupNode: { cacheDependencyPath: "pnpm-lock.yaml" },
   },
 });
@@ -59,6 +63,45 @@ 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.
 
+Candidate lifecycle support follows the same boundary. Use `FACTORY_CANDIDATE_PULL_REQUEST_TYPES` for the pull-request trigger matrix and `factoryCandidateOrPushCondition()` on each substantive job. With an optional caller-owned path condition, the helper emits the GitHub expression that runs merge-target pushes unconditionally and runs pull-request work only when GitHub's draft boolean says the pull request is a Candidate:
+
+```ts
+const changes = job("changes", {
+  if: factoryCandidateOrPushCondition(),
+  // caller-owned runner, permissions, and steps
+});
+
+const core = job("core", {
+  if: factoryCandidateOrPushCondition("needs.changes.outputs.core == 'true'"),
+  // caller-owned topology
+});
+```
+
+Migration: upgrade `@patronage/factory-ci`, apply the shared trigger types and job condition in the TypeScript workflow source, then regenerate and commit the emitted YAML. Draft `opened` and `synchronize` events will stop running substantive Verify work. Promotion through `ready_for_review`, later non-draft Candidate events, and merge-target pushes continue to run their applicable battery. A skipped draft run is presentation, not proof.
+
+Production impact support follows the same ownership line. A generated deploy workflow declares only its target names and consumes the returned decision step and fail-open `demandedIf(target)` expressions:
+
+```ts
+const impact = factoryProductionImpactWorkflow({
+  targets: profile.impact?.targets.map(({ name }) => name) ?? [],
+});
+
+const decide = job("impact", {
+  outputs: impact.decisionJobOutputs,
+  steps: [...setupSteps, impact.decisionStep],
+});
+
+const deployWebsite = job("deploy-website", {
+  if: impact.demandedIf("website", "impact"),
+  needs: [decide],
+  // consumer-owned runner, credentials, deploy commands, and convergence
+});
+```
+
+The step calls `psf production:impact` with the merge push's exact `before` and `after` commits. It is `continue-on-error`, and every generated target condition keeps work demanded unless the command succeeded, reported a usable decision, and explicitly withdrew that target. The artifact with an empty target list generates no deploy jobs because job creation remains with the consumer. This package does not own target declarations, deploy topology, credentials, commands, or convergence/no-op proof.
+
+The decision checkout must make both push identities reachable. Use `factoryWorkflow({ setup: { checkout: { fetchDepth: 0, ref: "${{ github.sha }}" } } })`; a shallow checkout is safe but deliberately refuses withdrawal because the `before` commit is unreadable.
+
 ### Generated shell
 
 ```ts
@@ -90,6 +133,8 @@ import {
   assertProofReuseCoverage,
   FACTORY_PROOF_GATE_GUARD,
   factoryProofGateStep,
+  factoryProofReuseSummaryStep,
+  factoryProofTimingStartStep,
 } from "@patronage/factory-ci";
 
 import profile from "../../software-factory.profile.json" with { type: "json" };
@@ -102,14 +147,16 @@ const core = job("core", {
   permissions: { checks: "read", contents: "read" },
   steps: [
     step(factoryProofGateStep({ commands: coreCommands, surface: "core" })),
+    step(factoryProofTimingStartStep()),
     ...guardedSteps.map((s) => ({ ...s, if: FACTORY_PROOF_GATE_GUARD })),
+    step(factoryProofReuseSummaryStep({ surface: "core" })),
   ],
 });
 ```
 
 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.
+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. Coverage is the union of `executedCommands` and commands released by `notRequiredCommands` only after the gate validates each release against that same proof binding's command-to-target map and identity-bound impact stamp. Missing, malformed, duplicated, affected, unknown, or differently bound release data refuses reuse and runs the hosted surface. `mode` is reported as diagnostic metadata, never authorized on: a reduced-mode proof whose executed and stamp-authorized released commands cover a surface 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.
 
@@ -121,6 +168,8 @@ The gate is a **step, not a job**, marked `continue-on-error`, with no `set -e`.
 
 `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. Coverage is exact executable coverage. The deprecated `equivalents` input remains only for patch-release source compatibility and is ignored; prose cannot authorize a skip. 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.
 
+`factoryProofTimingStartStep()` and `factoryProofReuseSummaryStep()` replace consumer-local proof timing summaries without taking over workflow topology. Put the start step immediately after the gate and the summary step after the guarded work. The helpers keep the established `Start CI timing` / `Record proof-reuse timing` names and distinguish pull-request reuse, pull-request full fallback, and merge-target full execution where the PR-only gate is explicitly not applicable. Reuse links the exact source check and bound head; every path emits a cheap Actions notice. Both steps are `continue-on-error`: missing timing support or an unwritable presentation destination cannot change a required job's conclusion. These helpers change no trust predicate or guard.
+
 ### Alchemy entries
 
 ```ts
@@ -205,7 +254,7 @@ The credential env-block helper that the audit found repeated was deliberately c
 
 ## Releases
 
-Attended and hand-cut, on the same terms as `@patronage/alchemy-d1-state`: bump the version, run the workspace checks, read the `npm pack --dry-run` file list, publish, tag `factory-ci@<version>`. There is no changesets setup and no automatic release trigger, by design. Consumers pin exact versions.
+Attended and hand-cut, on the same terms as `@patronage/alchemy-d1-state`: bump the version, run the workspace checks, read the `npm pack --dry-run` file list, build and approve one pnpm tarball, publish that exact tarball with an explicit channel tag, then tag `factory-ci@<version>`. Publishing the package directory is not allowed because its `prepack` build would replace the reviewed bytes. There is no changesets setup and no automatic release trigger, by design. Consumers pin exact versions.
 
 ## License
 

package/dist/index.d.ts

@@ -54,6 +54,21 @@ declare const NODE_PNPM_ACTION_FAMILY_NODE24: {
   };
 };
 //#endregion
+//#region src/candidate-lifecycle.d.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.
+ */
+declare const FACTORY_CANDIDATE_PULL_REQUEST_TYPES: readonly ["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.
+ */
+declare const factoryCandidateOrPushCondition: (candidateCondition?: string) => string;
+//#endregion
 //#region src/bundle-alchemy-entry.d.ts
 interface BundleAlchemyEntryOptions {
   /** The Alchemy entry to bundle, e.g. `alchemy.run.ts`. */
@@ -148,12 +163,16 @@ declare const localPreviewStage: (options: LocalPreviewStageOptions) => LocalPre
 //#endregion
 //#region src/factory-workflow.d.ts
 interface WorkflowStep {
+  readonly continueOnError?: boolean;
+  readonly env?: Readonly<Record<string, string>>;
+  readonly id?: string;
   readonly name: string;
   readonly uses?: string;
   readonly with?: Readonly<Record<string, string>>;
   readonly run?: string;
 }
 interface CheckoutStepOptions {
+  readonly fetchDepth?: number;
   readonly name?: string;
   readonly ref?: string;
 }
@@ -324,6 +343,13 @@ declare const FACTORY_PROOF_GATE_CHECK_NAME = "patronage-factory/pr-verify";
 declare const FACTORY_PROOF_GATE_APP_ID = "4314840";
 /** Step id the guard condition refers to. */
 declare 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.
+ */
+declare 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.
@@ -361,6 +387,8 @@ declare const FACTORY_PROOF_GATE_REASON_OUTPUT = "reason";
  * proof that executed every command the surface requires is reusable.
  */
 declare const FACTORY_PROOF_GATE_MODE_OUTPUT = "mode";
+/** Exact Checks API URL of the proof generation selected by the gate. */
+declare 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.
@@ -381,7 +409,8 @@ declare 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)
  *
@@ -540,6 +569,64 @@ declare const proofReuseCoverage: ({
 /** `proofReuseCoverage`, as a build failure. */
 declare const assertProofReuseCoverage: (input: ProofReuseCoverageInput) => ProofReuseCoverageReport;
 //#endregion
+//#region src/proof-reuse-presentation.d.ts
+/** Generic timing and presentation steps around the proof-reuse gate (#652). */
+declare const FACTORY_PROOF_TIMING_STEP_ID = "ci-timing";
+declare const FACTORY_PROOF_TIMING_START_STEP_NAME = "Start CI timing";
+declare const FACTORY_PROOF_TIMING_SUMMARY_STEP_NAME = "Record proof-reuse timing";
+interface FactoryProofReusePresentationOptions {
+  /** Human-readable name of the guarded suite. */
+  readonly surface: string;
+}
+interface FactoryProofTimingStartStep {
+  readonly continueOnError: true;
+  readonly id: typeof FACTORY_PROOF_TIMING_STEP_ID;
+  readonly name: typeof FACTORY_PROOF_TIMING_START_STEP_NAME;
+  readonly run: string;
+}
+declare const factoryProofTimingStartStep: () => FactoryProofTimingStartStep;
+declare const factoryProofReuseSummaryScript: ({
+  surface
+}: FactoryProofReusePresentationOptions) => string;
+interface FactoryProofReuseSummaryStep {
+  readonly continueOnError: true;
+  readonly env: Readonly<Record<string, string>>;
+  readonly if: "always()";
+  readonly name: typeof FACTORY_PROOF_TIMING_SUMMARY_STEP_NAME;
+  readonly run: string;
+}
+declare const factoryProofReuseSummaryStep: (options: FactoryProofReusePresentationOptions) => FactoryProofReuseSummaryStep;
+//#endregion
+//#region src/production-impact-workflow.d.ts
+declare const FACTORY_PRODUCTION_IMPACT_STEP_ID = "production_impact";
+declare const FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT = "decision";
+declare const FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT = "basis";
+declare const FACTORY_PRODUCTION_IMPACT_UNSUBSCRIBED_OUTPUT = "unsubscribed_paths";
+/** Stable GitHub-output key for one declared target. */
+declare const productionImpactTargetOutput: (targetName: string) => string;
+interface FactoryProductionImpactWorkflowOptions {
+  readonly after?: string;
+  readonly before?: string;
+  readonly cli?: string;
+  readonly profilePath?: string;
+  readonly targets: readonly string[];
+}
+interface FactoryProductionImpactWorkflow {
+  /** Outputs for a caller-owned decision job that subsequent jobs may consume. */
+  readonly decisionJobOutputs: Readonly<Record<string, string>>;
+  readonly decisionStep: WorkflowStep;
+  /** A fail-open condition: only an explicit usable withdrawal skips work. */
+  readonly demandedIf: (targetName: string, decisionJob?: string) => string;
+  readonly targetOutputs: Readonly<Record<string, string>>;
+}
+/**
+ * Generate the small factory-owned decision seam for a consumer production
+ * workflow. Consumers retain jobs, deploy commands, credentials, topology,
+ * and convergence checks; this artifact supplies only the decision step and
+ * per-target withdrawal conditions.
+ */
+declare const factoryProductionImpactWorkflow: (options: FactoryProductionImpactWorkflowOptions) => FactoryProductionImpactWorkflow;
+//#endregion
 //#region src/vitest-profile.d.ts
 /** Schema version of the emitted profile document. */
 declare const VITEST_PROFILE_SCHEMA_VERSION = 1;
@@ -750,6 +837,26 @@ declare const writeVitestProfile: (outputPath: string, profile: VitestProfile) =
  */
 declare const runVitestProfile: (options: VitestProfileOptions, dependencies?: VitestProfileDependencies) => Promise<VitestProfile>;
 //#endregion
+//#region src/vitest-profile-reader.d.ts
+/**
+ * Outcome of reading one candidate document. `unrecognized` carries the first
+ * reason the document failed — an analyzer reports it verbatim rather than
+ * treating an unreadable profile as an empty one.
+ */
+type VitestProfileReadResult = {
+  kind: "profile";
+  profile: VitestProfile;
+} | {
+  kind: "unrecognized";
+  reason: string;
+};
+/**
+ * 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.
+ */
+declare const readVitestProfileDocument: (value: unknown) => VitestProfileReadResult;
+//#endregion
 //#region src/workflow-shell-lint.d.ts
 /**
  * Parse-check the shell embedded in generated workflow YAML (#376).
@@ -801,4 +908,4 @@ declare const assertWorkflowShellParses: (yaml: string, options: {
   readonly source: string;
 }) => void;
 //#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, GitHubApiError, type GithubAppCredentials, type GithubAppTokenOptions, 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, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, type VitestJsonReport, type VitestProfile, type VitestProfileDependencies, type VitestProfileDurationSummary, type VitestProfileEnvironment, VitestProfileError, type VitestProfileOptions, type VitestProfileSample, type VitestProfileSampleExecution, type VitestTestStatus, type WorkflowShellParseFailure, type WorkflowStep, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryProofGateScript, factoryProofGateStep, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, proofReuseCoverage, proofReuseRequiredCommands, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };
+export { type BundleAlchemyEntryOptions, type CheckoutStepOptions, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, 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, type FactoryProductionImpactWorkflow, type FactoryProductionImpactWorkflowOptions, type FactoryProofGateOptions, type FactoryProofGateReason, type FactoryProofGateStep, type FactoryProofReusePresentationOptions, type FactoryProofReuseSummaryStep, type FactoryProofTimingStartStep, type FactoryWorkflowArtifact, type FactoryWorkflowOptions, type FactoryWorkflowSetupOptions, GitHubApiError, type GithubAppCredentials, type GithubAppTokenOptions, 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, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, type VitestJsonReport, type VitestProfile, type VitestProfileDependencies, type VitestProfileDurationSummary, type VitestProfileEnvironment, VitestProfileError, type VitestProfileOptions, type VitestProfileReadResult, type VitestProfileSample, type VitestProfileSampleExecution, type VitestTestStatus, type WorkflowShellParseFailure, type WorkflowStep, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryCandidateOrPushCondition, factoryProductionImpactWorkflow, factoryProofGateScript, factoryProofGateStep, factoryProofReuseSummaryScript, factoryProofReuseSummaryStep, factoryProofTimingStartStep, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, productionImpactTargetOutput, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };