@patronage/factory-ci 1.0.0-alpha.21 → 1.0.0-alpha.23

package/src/preview-proof-lifecycle.ts

@@ -49,9 +49,7 @@ export interface PreviewProofRegistration {
     readonly outcome: PreviewProofCleanupStatus;
     readonly runUrl?: string;
   };
-  readonly cleanupStatus: PreviewProofCleanupStatus;
   readonly convergence: { readonly detail: string; readonly status: "passed" };
-  readonly convergenceStatus: "passed";
   readonly headSha: string;
   readonly pr: number;
   readonly proof: {
@@ -61,7 +59,6 @@ export interface PreviewProofRegistration {
     readonly patchId: string;
   };
   readonly smoke: { readonly detail: string; readonly outcome: "passed" };
-  readonly smokeStatus: "passed";
   readonly source: "local-self-certified";
   readonly stack: string;
   readonly stage: LocalPreviewStage;
@@ -239,12 +236,10 @@ const transition = (
 
     return replaceRegistration(state, {
       cleanup: { evidence: [], outcome: "pending" },
-      cleanupStatus: "pending",
       convergence: {
         detail: event.convergence.detail,
         status: "passed",
       },
-      convergenceStatus: "passed",
       headSha: event.candidate.headSha,
       pr: event.candidate.pr,
       proof: {
@@ -254,7 +249,6 @@ const transition = (
         patchId: event.evidence.patchId,
       },
       smoke: { detail: event.smoke.detail, outcome: "passed" },
-      smokeStatus: "passed",
       source: "local-self-certified",
       stack: event.stack,
       stage,
@@ -286,7 +280,6 @@ const transition = (
   return replaceRegistration(state, {
     ...existing,
     cleanup,
-    cleanupStatus: event.outcome,
   });
 };
 
@@ -300,7 +293,7 @@ const recover = (
       row.stack === event.stack &&
       row.stage === event.stage
   );
-  if (existing?.cleanupStatus !== "failed") {
+  if (existing?.cleanup.outcome !== "failed") {
     throw new Error(
       "Preview proof recovery re-enters cleanup only from a failed outcome."
     );

package/src/production-impact-workflow.ts

@@ -1,4 +1,5 @@
 import type { WorkflowStep } from "./factory-workflow.ts";
+import { impactDemandConditions } from "./impact-demand-condition.ts";
 
 export const FACTORY_PRODUCTION_IMPACT_STEP_ID = "production_impact";
 export const FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT = "decision";
@@ -36,8 +37,13 @@ export 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;
+  /**
+   * A fail-open cross-job condition: only an explicit usable withdrawal skips
+   * work. The decision job id is required.
+   */
+  readonly demandedIf: (targetName: string, decisionJob: string) => string;
+  /** The same fail-open condition for a step in the decision job. */
+  readonly demandedIfAtStep: (targetName: string) => string;
   readonly targetOutputs: Readonly<Record<string, string>>;
 }
 
@@ -79,6 +85,13 @@ export const factoryProductionImpactWorkflow = (
     run: `${cli} production:impact --before "$FACTORY_BEFORE_SHA" --after "$FACTORY_AFTER_SHA" --github-output "$GITHUB_OUTPUT" --github-summary "$GITHUB_STEP_SUMMARY"${profile}`,
   };
 
+  const conditions = impactDemandConditions({
+    decisionOutput: FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT,
+    label: "production",
+    stepId: FACTORY_PRODUCTION_IMPACT_STEP_ID,
+    targetOutputs,
+  });
+
   return Object.freeze({
     decisionJobOutputs: Object.freeze({
       basis: `\${{ steps.${FACTORY_PRODUCTION_IMPACT_STEP_ID}.outputs.${FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT} }}`,
@@ -92,18 +105,8 @@ export const factoryProductionImpactWorkflow = (
       ),
     }),
     decisionStep: Object.freeze(decisionStep),
-    demandedIf: (targetName: string, decisionJob?: string) => {
-      const output = targetOutputs[targetName];
-      if (output === undefined) {
-        throw new Error(`Unknown production impact target "${targetName}".`);
-      }
-      const source = decisionJob
-        ? `needs.${decisionJob}`
-        : `steps.${FACTORY_PRODUCTION_IMPACT_STEP_ID}`;
-      const outcome = decisionJob ? "result" : "outcome";
-      const condition = `${source}.${outcome} != 'success' || ${source}.outputs.${FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT} != 'usable' || ${source}.outputs.${output} != 'withdrawn'`;
-      return decisionJob ? `always() && (${condition})` : condition;
-    },
+    demandedIf: conditions.demandedIf,
+    demandedIfAtStep: conditions.demandedIfAtStep,
     targetOutputs: Object.freeze(targetOutputs),
   });
 };

package/src/proof-reuse-gate.ts

@@ -142,6 +142,41 @@ export const FACTORY_PROOF_GATE_GUARD = `steps.${FACTORY_PROOF_GATE_STEP_ID}.out
 export const FACTORY_PROOF_GATE_IF =
   "github.event_name == 'pull_request' || (github.event_name == 'push' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch))";
 
+/**
+ * Pull requests only — the condition a consumer gets with
+ * `reuse: "pull-request"` (#873).
+ *
+ * A repository may want its default-branch pushes to always execute the full
+ * hosted suite, whatever proof exists: the merged commit is what the fleet
+ * deploys, so a periodic unconditional run of every command is a deliberate
+ * cost some consumers choose to pay. This condition is that choice, expressed
+ * once here rather than as a consumer-written override string. The mode also
+ * skips the push-event merge fallback, so no push path can reuse proof even if
+ * the workflow reaches the step through some other trigger.
+ *
+ * Which branches trigger the workflow at all stays repository-owned. This
+ * condition only keeps the gate from consulting proof outside a pull request.
+ */
+export const FACTORY_PROOF_GATE_PULL_REQUEST_IF =
+  "github.event_name == 'pull_request'";
+
+/**
+ * Which events may reuse proof.
+ *
+ * A two-value enum, not a free-text condition: a string lets a consumer write
+ * a condition this package cannot reason about — one that reuses proof on an
+ * unproven ref — and the emitted condition is a trust predicate. The consumer
+ * chooses the mode; `factory-ci` owns what each mode emits.
+ *
+ * - `pull-request-and-default-branch` (default) pull requests plus pushes to
+ *   the merge target, with the merge fallback. Today's behaviour.
+ * - `pull-request` pull requests only. Default-branch pushes execute the full
+ *   hosted suite, and the merge fallback is not emitted.
+ */
+export type FactoryProofGateReuse =
+  | "pull-request"
+  | "pull-request-and-default-branch";
+
 /**
  * The complete refusal vocabulary. Deliberately few, because these are the
  * only distinctions the gate can honestly make from its Checks API reads.
@@ -210,7 +245,7 @@ const COMMAND_IDENTITY_MAX_LENGTH = 120;
  * 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 TRUSTED_IMPACT_STAMP_VERSION = 4;
 
 const isProofReuseCommand = (value: unknown): value is ProofReuseCommand => {
   if (!(value && typeof value === "object")) {
@@ -429,7 +464,9 @@ def releaseAuthorized($release; $commands; $stamp):
             type == "object"
             and (.name | nonemptyString)
             and (.basis | nonemptyString)
-            and ((.impact == "affected") or (.impact == "not-affected"))))
+            and ((.impact == "affected") or (.impact == "not-affected"))
+            and ((.subscribedPaths | type) == "array")
+            and (.subscribedPaths | all(.[]; type == "string"))))
           and ($stamp.targets | distinctNames)
           and (([$releases[].name] - $executed | length) == ($releases | length))
           and ($releases | all(.[]; releaseAuthorized(.; $commands; $stamp)))
@@ -488,7 +525,99 @@ const safeLabel = (surface: string): string => {
   return cleaned.length > 0 ? cleaned : "verification";
 };
 
-const gateScript = (required: readonly string[], surface: string): string =>
+/**
+ * The push-event merge fallback (#611), emitted only for the default reuse
+ * mode. `reuse: "pull-request"` omits it: that mode's whole point is that a
+ * default-branch push executes everything, so a push path that could still
+ * reuse proof would contradict the condition above it.
+ */
+const MERGE_FALLBACK_BLOCK = String.raw`# Merge fallback (#611). A squash merge mints a new commit, so the direct
+# read at a pushed merge-target head finds nothing even when the factory
+# proved the producing pull request head. Only when the direct read found no
+# generation at all on a push event, look up the producing pull request and
+# reuse its head proof — and only when the merge commit's TREE id equals the
+# proven head's tree id, which makes the pushed content byte-identical to
+# what was verified (a clean squash of an unchanged tip). Patch identity was
+# considered and rejected as the comparator: git patch-id normalizes
+# whitespace and ignores base motion, so an identical patch can still
+# produce an integrated tree that was never tested. Everything else — no
+# unique merged producing PR, an unreadable commit, a proof that is anything
+# but proven, or tree drift from a dirty or stale merge — leaves the direct
+# "none" refusal standing, so the full suite runs (fail open).
+if [ "$reason" = 'none' ] && [ "${shellExpansion("GITHUB_EVENT_NAME:-")}" = 'push' ]; then
+  producing_head=''
+  merge_tree=''
+  head_tree=''
+  if ! producing_pulls=$(gh api --method GET --paginate \
+      "repos/$GITHUB_REPOSITORY/commits/$HEAD_SHA/pulls" \
+      -f per_page=100 2>&1); then
+    detail="producing pull request unreadable: $producing_pulls"
+  elif ! producing_head=$(printf '%s' "$producing_pulls" | jq -r -s \
+      --arg sha "$HEAD_SHA" \
+      '[ add[]?
+         | select((.merged_at // null) != null)
+         | select((.merge_commit_sha // "") == $sha)
+         | ((.head.sha // "") | tostring) ]
+       | if length == 1 then .[0] else "" end' 2>&1); then
+    detail="producing pull request unreadable: $producing_head"
+    producing_head=''
+  elif ! [[ "$producing_head" =~ ^[0-9a-f]{40}$ ]]; then
+    detail='no single merged producing pull request at this commit'
+    producing_head=''
+  elif ! merge_commit=$(gh api --method GET \
+      "repos/$GITHUB_REPOSITORY/commits/$HEAD_SHA" 2>&1); then
+    detail="merge commit unreadable: $merge_commit"
+  elif ! merge_tree=$(printf '%s' "$merge_commit" | jq -r \
+      '(.commit.tree.sha // "") | tostring' 2>&1); then
+    detail="merge commit unreadable: $merge_tree"
+    merge_tree=''
+  elif ! [[ "$merge_tree" =~ ^[0-9a-f]{40}$ ]]; then
+    detail='merge commit carries no readable tree id'
+    merge_tree=''
+  elif ! head_commit=$(gh api --method GET \
+      "repos/$GITHUB_REPOSITORY/commits/$producing_head" 2>&1); then
+    detail="producing head commit unreadable: $head_commit"
+  elif ! head_tree=$(printf '%s' "$head_commit" | jq -r \
+      '(.commit.tree.sha // "") | tostring' 2>&1); then
+    detail="producing head commit unreadable: $head_tree"
+    head_tree=''
+  elif ! [[ "$head_tree" =~ ^[0-9a-f]{40}$ ]]; then
+    detail='producing head commit carries no readable tree id'
+    head_tree=''
+  elif [ "$merge_tree" != "$head_tree" ]; then
+    detail='tree drift: the merge result is not the proven head tree'
+    merge_tree=''
+  fi
+  if [[ "$producing_head" =~ ^[0-9a-f]{40}$ ]] \
+      && [[ "$merge_tree" =~ ^[0-9a-f]{40}$ ]] \
+      && [ "$merge_tree" = "$head_tree" ]; then
+    gate_lookup "$producing_head"
+    if [ "$lookup_reason" = 'proven' ]; then
+      reason=proven
+      mode="$lookup_mode"
+      missing=''
+      source_url="$lookup_url"
+      proof_head="$producing_head"
+      merge_note="the merge result's tree is byte-identical to the tree proven at pull request head $producing_head"
+    else
+      detail="producing pull request proof not reusable ($lookup_reason)"
+    fi
+  fi
+fi`;
+
+/**
+ * The fallback with the blank lines that surround it, or nothing at all. Kept
+ * as one piece so the default mode emits the exact script it emitted before
+ * this option existed.
+ */
+const mergeFallbackSection = (reuse: FactoryProofGateReuse): string =>
+  reuse === "pull-request" ? "\n" : `\n${MERGE_FALLBACK_BLOCK}\n\n`;
+
+const gateScript = (
+  required: readonly string[],
+  surface: string,
+  reuse: FactoryProofGateReuse
+): string =>
   String.raw`
 set -uo pipefail
 
@@ -576,82 +705,7 @@ else
   missing="$lookup_missing"
   source_url="$lookup_url"
 fi
-
-# Merge fallback (#611). A squash merge mints a new commit, so the direct
-# read at a pushed merge-target head finds nothing even when the factory
-# proved the producing pull request head. Only when the direct read found no
-# generation at all on a push event, look up the producing pull request and
-# reuse its head proof — and only when the merge commit's TREE id equals the
-# proven head's tree id, which makes the pushed content byte-identical to
-# what was verified (a clean squash of an unchanged tip). Patch identity was
-# considered and rejected as the comparator: git patch-id normalizes
-# whitespace and ignores base motion, so an identical patch can still
-# produce an integrated tree that was never tested. Everything else — no
-# unique merged producing PR, an unreadable commit, a proof that is anything
-# but proven, or tree drift from a dirty or stale merge — leaves the direct
-# "none" refusal standing, so the full suite runs (fail open).
-if [ "$reason" = 'none' ] && [ "${shellExpansion("GITHUB_EVENT_NAME:-")}" = 'push' ]; then
-  producing_head=''
-  merge_tree=''
-  head_tree=''
-  if ! producing_pulls=$(gh api --method GET --paginate \
-      "repos/$GITHUB_REPOSITORY/commits/$HEAD_SHA/pulls" \
-      -f per_page=100 2>&1); then
-    detail="producing pull request unreadable: $producing_pulls"
-  elif ! producing_head=$(printf '%s' "$producing_pulls" | jq -r -s \
-      --arg sha "$HEAD_SHA" \
-      '[ add[]?
-         | select((.merged_at // null) != null)
-         | select((.merge_commit_sha // "") == $sha)
-         | ((.head.sha // "") | tostring) ]
-       | if length == 1 then .[0] else "" end' 2>&1); then
-    detail="producing pull request unreadable: $producing_head"
-    producing_head=''
-  elif ! [[ "$producing_head" =~ ^[0-9a-f]{40}$ ]]; then
-    detail='no single merged producing pull request at this commit'
-    producing_head=''
-  elif ! merge_commit=$(gh api --method GET \
-      "repos/$GITHUB_REPOSITORY/commits/$HEAD_SHA" 2>&1); then
-    detail="merge commit unreadable: $merge_commit"
-  elif ! merge_tree=$(printf '%s' "$merge_commit" | jq -r \
-      '(.commit.tree.sha // "") | tostring' 2>&1); then
-    detail="merge commit unreadable: $merge_tree"
-    merge_tree=''
-  elif ! [[ "$merge_tree" =~ ^[0-9a-f]{40}$ ]]; then
-    detail='merge commit carries no readable tree id'
-    merge_tree=''
-  elif ! head_commit=$(gh api --method GET \
-      "repos/$GITHUB_REPOSITORY/commits/$producing_head" 2>&1); then
-    detail="producing head commit unreadable: $head_commit"
-  elif ! head_tree=$(printf '%s' "$head_commit" | jq -r \
-      '(.commit.tree.sha // "") | tostring' 2>&1); then
-    detail="producing head commit unreadable: $head_tree"
-    head_tree=''
-  elif ! [[ "$head_tree" =~ ^[0-9a-f]{40}$ ]]; then
-    detail='producing head commit carries no readable tree id'
-    head_tree=''
-  elif [ "$merge_tree" != "$head_tree" ]; then
-    detail='tree drift: the merge result is not the proven head tree'
-    merge_tree=''
-  fi
-  if [[ "$producing_head" =~ ^[0-9a-f]{40}$ ]] \
-      && [[ "$merge_tree" =~ ^[0-9a-f]{40}$ ]] \
-      && [ "$merge_tree" = "$head_tree" ]; then
-    gate_lookup "$producing_head"
-    if [ "$lookup_reason" = 'proven' ]; then
-      reason=proven
-      mode="$lookup_mode"
-      missing=''
-      source_url="$lookup_url"
-      proof_head="$producing_head"
-      merge_note="the merge result's tree is byte-identical to the tree proven at pull request head $producing_head"
-    else
-      detail="producing pull request proof not reusable ($lookup_reason)"
-    fi
-  fi
-fi
-
-# The binding is App-verified, but it still reaches markdown. Only a plain
+${mergeFallbackSection(reuse)}# 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
   '') ;;
@@ -770,6 +824,13 @@ export interface FactoryProofGateOptions {
    * therefore requires a different coverage.
    */
   readonly commands: readonly ProofReuseCommand[];
+  /**
+   * Which events may reuse proof. Defaults to
+   * `"pull-request-and-default-branch"`, the behaviour every consumer has
+   * today. `"pull-request"` makes default-branch pushes execute the full
+   * hosted suite (#873).
+   */
+  readonly reuse?: FactoryProofGateReuse;
   /** Names the suite in the job summary. Changes no trust decision. */
   readonly surface: string;
 }
@@ -788,11 +849,12 @@ export interface FactoryProofGateOptions {
  */
 export const factoryProofGateScript = ({
   commands,
+  reuse = "pull-request-and-default-branch",
   surface,
 }: FactoryProofGateOptions): string => {
   const required = proofReuseRequiredCommands(commands);
   return required
-    ? gateScript(required, safeLabel(surface))
+    ? gateScript(required, safeLabel(surface), reuse)
     : UNUSABLE_SELECTION_SCRIPT;
 };
 
@@ -803,7 +865,9 @@ export interface FactoryProofGateStep {
     HEAD_SHA: string;
   }>;
   readonly id: typeof FACTORY_PROOF_GATE_STEP_ID;
-  readonly if: typeof FACTORY_PROOF_GATE_IF;
+  readonly if:
+    | typeof FACTORY_PROOF_GATE_IF
+    | typeof FACTORY_PROOF_GATE_PULL_REQUEST_IF;
   readonly name: string;
   readonly run: string;
   readonly shell: typeof FACTORY_PROOF_GATE_SHELL;
@@ -817,7 +881,9 @@ export interface FactoryProofGateStep {
  * `checks: read`; the push-event merge fallback additionally reads the
  * producing pull request (`pull-requests: read`) and the two commit objects
  * whose tree ids it compares (`contents: read`). A job that grants less
- * loses only the fallback — the failed read degrades to the full suite.
+ * loses only the fallback — the failed read degrades to the full suite. A
+ * consumer that passes `reuse: "pull-request"` emits neither the push clause
+ * nor the fallback, and needs only `checks: read` (#873).
  *
  * 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
@@ -841,7 +907,10 @@ export const factoryProofGateStep = (
       ),
     }),
     id: FACTORY_PROOF_GATE_STEP_ID,
-    if: FACTORY_PROOF_GATE_IF,
+    if:
+      options.reuse === "pull-request"
+        ? FACTORY_PROOF_GATE_PULL_REQUEST_IF
+        : FACTORY_PROOF_GATE_IF,
     name: FACTORY_PROOF_GATE_STEP_NAME,
     run: factoryProofGateScript(options),
     // Never omit: the runner's default `run:` shell supplies `-e`, which

package/src/push-identity-workflow.ts

@@ -1,18 +1,28 @@
+import { UPLOAD_ARTIFACT } from "./actions.ts";
 import type { PinnedAction } from "./actions.ts";
 import type { WorkflowStep } from "./factory-workflow.ts";
 import { assertPinnedAction } from "./pinned-action.ts";
 
+/** `owner/repo` slice of the catalog's `UPLOAD_ARTIFACT` pin, derived rather
+ * than repeated as a literal, so a repository rename here cannot drift from
+ * the pin it validates against. */
+const UPLOAD_ARTIFACT_REPOSITORY = UPLOAD_ARTIFACT.uses.slice(
+  0,
+  UPLOAD_ARTIFACT.uses.indexOf("@")
+);
+
 export const FACTORY_PUSH_IDENTITY_SCHEMA_VERSION = 1;
-export const FACTORY_PUSH_IDENTITY_ARTIFACT_PREFIX = "factory-push-identity";
-export const FACTORY_PUSH_IDENTITY_RECORD_STEP_ID =
-  "factory_push_identity_record";
-export const FACTORY_PUSH_IDENTITY_LOOKUP_STEP_ID =
-  "factory_push_identity_lookup";
-export const FACTORY_PUSH_IDENTITY_DOWNLOAD_STEP_ID =
-  "factory_push_identity_download";
-export const FACTORY_PUSH_IDENTITY_CHECKOUT_STEP_ID =
-  "factory_push_identity_checkout";
-export const FACTORY_PUSH_IDENTITY_VALIDATE_STEP_ID = "factory_push_identity";
+/**
+ * The artifact prefix and the five step IDs are module-private. Alpha.13
+ * removed them from the public surface (#719). A caller reads a step ID from
+ * the builder's returned `steps` (`step.id`) or from `artifactName`.
+ */
+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";
 
 /** Versioned document uploaded by a push-triggered verification run. */
 export interface FactoryPushIdentityEnvelope {
@@ -270,7 +280,12 @@ printf 'disposition=%s\nreason=%s\nbefore=%s\nafter=%s\nprovenance=%s\n' \
 } >> "$GITHUB_STEP_SUMMARY"`;
 
 export interface FactoryPushIdentityProducerOptions {
-  /** Explicit caller-owned upload-artifact pin from its workflow artifact. */
+  /**
+   * Explicit caller-owned upload-artifact pin from its workflow artifact.
+   * Pass factory-ci's `UPLOAD_ARTIFACT` catalog export (or another
+   * `actions/upload-artifact` pin); the caller wires the step, the catalog
+   * only names the pin.
+   */
   readonly uploadArtifact: PinnedAction;
   /** Optional consumer trigger policy combined with the required push event. */
   readonly if?: string;
@@ -291,7 +306,7 @@ export const factoryPushIdentityProducer = (
   assertPinnedAction(
     "uploadArtifact",
     options.uploadArtifact,
-    "actions/upload-artifact"
+    UPLOAD_ARTIFACT_REPOSITORY
   );
   const condition = options.if
     ? `github.event_name == 'push' && (${options.if})`