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

package/README.md

@@ -397,6 +397,8 @@ Persistence is an injectable GitHub transport in the same style as `mintInstalla
 
 Pass `{ store }` to substitute the GitHub adapter. `previewProofInventory.memoryStore()` is an in-memory `list`/`put` port for tests. `githubStore({ token, fetch, timeoutMs? })` is the GitHub-backed implementation. Stack names stay caller strings.
 
+Transient transport failures — a network-level rejection such as EPIPE, a timeout, a 408/429/5xx, or a response body that dies mid-read — are retried with doubling backoff up to three transport attempts in total (the first attempt plus two retries), and then throw `PreviewProofTransportError` (attempt count, last transient status, credential-free reason); a permanent HTTP refusal throws `GitHubApiError` without retrying (#830). Either failure from `persist` or `recordCleanup` is an evidence-registration failure, not a failed deployment: retain the healthy disposable stage, record the proof BLOCKED (never PASS), and re-run registration at the same head — writes are keyed by stack and stage, so resuming needs no redeploy. Admission stays fail-closed on its own: an unregistered proof never satisfies the preview demand.
+
 ### GitHub App installation tokens
 
 ```ts

package/dist/index.d.ts

@@ -286,6 +286,15 @@ declare const previewProofLifecycle: {
  * secrets. Cleanup writes go through `previewProofLifecycle.transition` with
  * `{ type: "cleanup" }`. Outcomes are never inferred from whether a stage
  * still exists.
+ *
+ * Transient transport failures are retried with bounded backoff and then
+ * surface as `PreviewProofTransportError` (#830). A failure from `persist` or
+ * `recordCleanup` is an evidence-registration failure, never a failed
+ * deployment: the caller retains the healthy disposable stage, records its own
+ * proof BLOCKED (never PASS), and re-runs registration at the same head —
+ * writes are keyed by stack and stage, so resuming needs no redeploy.
+ * Admission stays fail-closed on its own: an unregistered proof never
+ * satisfies the preview demand.
  */
 /** Check-run name that carries one registration JSON payload. Not a gate. */
 declare const PREVIEW_PROOF_INVENTORY_CHECK_NAME = "patronage-factory/preview-proof";
@@ -344,6 +353,21 @@ interface PreviewProofInventoryCleanupInput {
   stack: string;
   stage: string;
 }
+/**
+ * The transport gave out — a network-level rejection (EPIPE, DNS, an aborted
+ * or timed-out request) or a transient HTTP status — and bounded retries did
+ * not recover it. GitHub never judged the content, so this is never a
+ * validation verdict and never a deployment failure. Only a bounded reason
+ * string is retained: the raw transport error can hold the request and its
+ * `Authorization` header, so it is deliberately discarded.
+ */
+declare class PreviewProofTransportError extends Error {
+  /** How many transport attempts were made before giving up. */
+  readonly attempts: number;
+  /** The last transient HTTP status, when the server answered at all. */
+  readonly status?: number;
+  constructor(reason: string, attempts: number, status?: number);
+}
 declare const previewProofInventory: {
   readonly githubStore: (transport: PreviewProofInventoryTransport) => PreviewProofInventoryStore;
   readonly list: (input: PreviewProofInventoryListInput, access: PreviewProofInventoryAccess) => Promise<readonly PreviewProofRegistration[]>;
@@ -1342,4 +1366,4 @@ declare const assertWorkflowShellParses: (yaml: string, options: {
   readonly source: string;
 }) => void;
 //#endregion
-export { type BundleAlchemyEntryOptions, type CheckoutStepOptions, EXECUTE_ALCHEMY_ENTRY_MAX_BUFFER, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT, FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT, FACTORY_CANDIDATE_IMPACT_INERT_OUTPUT, FACTORY_CANDIDATE_IMPACT_STEP_ID, FACTORY_CANDIDATE_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_CANDIDATE_PULL_REQUEST_TYPES, FACTORY_LIFECYCLE_CONTRACT_JOB_ID, FACTORY_LIFECYCLE_CONTRACT_JOB_NAME, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_ID, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_NAME, 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_PR_STATUS_HUD_APP_TOKEN_STEP_ID, FACTORY_PR_STATUS_HUD_CONCURRENCY, FACTORY_PR_STATUS_HUD_IF, FACTORY_PR_STATUS_HUD_JOB_ID, FACTORY_PR_STATUS_HUD_JOB_NAME, FACTORY_PR_STATUS_HUD_PERMISSIONS, FACTORY_PR_STATUS_HUD_PLAN_PATH, FACTORY_PUSH_IDENTITY_SCHEMA_VERSION, type FactoryCandidateImpactWorkflow, type FactoryCandidateImpactWorkflowOptions, type FactoryLifecycleContractLane, type FactoryLifecycleContractLaneOptions, type FactoryPrStatusHudWorkflow, type FactoryPrStatusHudWorkflowOptions, type FactoryPreviewCleanupAuditJob, type FactoryPreviewCleanupDestroyJob, type FactoryPreviewCleanupTopology, type FactoryPreviewCleanupTopologyOptions, type FactoryProductionImpactWorkflow, type FactoryProductionImpactWorkflowOptions, type FactoryProofGateOptions, type FactoryProofGateReason, type FactoryProofGateStep, type FactoryProofReusePresentationOptions, type FactoryProofReuseSummaryStep, type FactoryProofTimingStartStep, type FactoryPushIdentityConsumer, type FactoryPushIdentityConsumerOptions, type FactoryPushIdentityDisposition, type FactoryPushIdentityEnvelope, type FactoryPushIdentityProducer, type FactoryPushIdentityProducerOptions, type FactoryWorkflowArtifact, type FactoryWorkflowOptions, type FactoryWorkflowSetupOptions, GitHubApiError, type GithubAppCredentials, type GithubAppTokenOptions, type InstallStepOptions, type LocalPreviewStage, type LocalPreviewStageOptions, NODE_PNPM_ACTION_FAMILY_NODE24, type NodePnpmActionFamily, PREVIEW_PROOF_INVENTORY_CHECK_NAME, type ParseLocalPreviewStageExpected, type ParsedLocalPreviewStage, type PinnedAction, type PreviewProofCandidate, type PreviewProofCleanupOutcome, type PreviewProofCleanupStatus, type PreviewProofEnvelopeEvidence, type PreviewProofInventoryAccess, type PreviewProofInventoryCleanupInput, type PreviewProofInventoryListInput, type PreviewProofInventoryPersistInput, type PreviewProofInventoryStore, type PreviewProofInventoryTransport, type PreviewProofLifecycleEvent, type PreviewProofLifecycleState, type PreviewProofRegistration, type PreviewProofResolveQuery, 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, factoryCandidateImpactWorkflow, factoryCandidateOrPushCondition, factoryLifecycleContractLane, factoryPrStatusHudWorkflow, factoryPreviewCleanupTopology, factoryProductionImpactWorkflow, factoryProofGateScript, factoryProofGateStep, factoryProofReuseSummaryStep, factoryProofTimingStartStep, factoryPushIdentityConsumer, factoryPushIdentityProducer, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, previewCleanupDestroyJobId, previewProofInventory, previewProofLifecycle, productionImpactTargetOutput, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };
+export { type BundleAlchemyEntryOptions, type CheckoutStepOptions, EXECUTE_ALCHEMY_ENTRY_MAX_BUFFER, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT, FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT, FACTORY_CANDIDATE_IMPACT_INERT_OUTPUT, FACTORY_CANDIDATE_IMPACT_STEP_ID, FACTORY_CANDIDATE_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_CANDIDATE_PULL_REQUEST_TYPES, FACTORY_LIFECYCLE_CONTRACT_JOB_ID, FACTORY_LIFECYCLE_CONTRACT_JOB_NAME, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_ID, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_NAME, 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_PR_STATUS_HUD_APP_TOKEN_STEP_ID, FACTORY_PR_STATUS_HUD_CONCURRENCY, FACTORY_PR_STATUS_HUD_IF, FACTORY_PR_STATUS_HUD_JOB_ID, FACTORY_PR_STATUS_HUD_JOB_NAME, FACTORY_PR_STATUS_HUD_PERMISSIONS, FACTORY_PR_STATUS_HUD_PLAN_PATH, FACTORY_PUSH_IDENTITY_SCHEMA_VERSION, type FactoryCandidateImpactWorkflow, type FactoryCandidateImpactWorkflowOptions, type FactoryLifecycleContractLane, type FactoryLifecycleContractLaneOptions, type FactoryPrStatusHudWorkflow, type FactoryPrStatusHudWorkflowOptions, type FactoryPreviewCleanupAuditJob, type FactoryPreviewCleanupDestroyJob, type FactoryPreviewCleanupTopology, type FactoryPreviewCleanupTopologyOptions, type FactoryProductionImpactWorkflow, type FactoryProductionImpactWorkflowOptions, type FactoryProofGateOptions, type FactoryProofGateReason, type FactoryProofGateStep, type FactoryProofReusePresentationOptions, type FactoryProofReuseSummaryStep, type FactoryProofTimingStartStep, type FactoryPushIdentityConsumer, type FactoryPushIdentityConsumerOptions, type FactoryPushIdentityDisposition, type FactoryPushIdentityEnvelope, type FactoryPushIdentityProducer, type FactoryPushIdentityProducerOptions, type FactoryWorkflowArtifact, type FactoryWorkflowOptions, type FactoryWorkflowSetupOptions, GitHubApiError, type GithubAppCredentials, type GithubAppTokenOptions, type InstallStepOptions, type LocalPreviewStage, type LocalPreviewStageOptions, NODE_PNPM_ACTION_FAMILY_NODE24, type NodePnpmActionFamily, PREVIEW_PROOF_INVENTORY_CHECK_NAME, type ParseLocalPreviewStageExpected, type ParsedLocalPreviewStage, type PinnedAction, type PreviewProofCandidate, type PreviewProofCleanupOutcome, type PreviewProofCleanupStatus, type PreviewProofEnvelopeEvidence, type PreviewProofInventoryAccess, type PreviewProofInventoryCleanupInput, type PreviewProofInventoryListInput, type PreviewProofInventoryPersistInput, type PreviewProofInventoryStore, type PreviewProofInventoryTransport, type PreviewProofLifecycleEvent, type PreviewProofLifecycleState, type PreviewProofRegistration, type PreviewProofResolveQuery, PreviewProofTransportError, 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, factoryCandidateImpactWorkflow, factoryCandidateOrPushCondition, factoryLifecycleContractLane, factoryPrStatusHudWorkflow, factoryPreviewCleanupTopology, factoryProductionImpactWorkflow, factoryProofGateScript, factoryProofGateStep, factoryProofReuseSummaryStep, factoryProofTimingStartStep, factoryPushIdentityConsumer, factoryPushIdentityProducer, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, previewCleanupDestroyJobId, previewProofInventory, previewProofLifecycle, productionImpactTargetOutput, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };

package/dist/index.js

@@ -2,6 +2,7 @@ import { createRequire } from "node:module";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { build } from "esbuild";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { createSign, randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { execFileSync, spawn, spawnSync } from "node:child_process";
@@ -1172,12 +1173,25 @@ const assertProofReuseCoverage = (input) => {
 * secrets. Cleanup writes go through `previewProofLifecycle.transition` with
 * `{ type: "cleanup" }`. Outcomes are never inferred from whether a stage
 * still exists.
+*
+* Transient transport failures are retried with bounded backoff and then
+* surface as `PreviewProofTransportError` (#830). A failure from `persist` or
+* `recordCleanup` is an evidence-registration failure, never a failed
+* deployment: the caller retains the healthy disposable stage, records its own
+* proof BLOCKED (never PASS), and re-runs registration at the same head —
+* writes are keyed by stack and stage, so resuming needs no redeploy.
+* Admission stays fail-closed on its own: an unregistered proof never
+* satisfies the preview demand.
 */
 /** Check-run name that carries one registration JSON payload. Not a gate. */
 const PREVIEW_PROOF_INVENTORY_CHECK_NAME = "patronage-factory/preview-proof";
 const INVENTORY_KIND = "patronage-factory-preview-proof";
 const INVENTORY_SCHEMA_VERSION = 1;
 const DEFAULT_TIMEOUT_MS = 5e3;
+/** Total transport attempts per request, the first one included. */
+const TRANSPORT_RETRY_ATTEMPTS = 3;
+/** Delay before the first retry; each further retry doubles it. */
+const TRANSPORT_RETRY_BACKOFF_MS = 500;
 const CHECK_RUNS_PER_PAGE = 100;
 const COMMITS_PER_PAGE = 100;
 const MAX_CHECK_RUN_PAGES = 10;
@@ -1309,20 +1323,93 @@ const memoryStore = () => {
 		}
 	};
 };
+/**
+* The transport gave out — a network-level rejection (EPIPE, DNS, an aborted
+* or timed-out request) or a transient HTTP status — and bounded retries did
+* not recover it. GitHub never judged the content, so this is never a
+* validation verdict and never a deployment failure. Only a bounded reason
+* string is retained: the raw transport error can hold the request and its
+* `Authorization` header, so it is deliberately discarded.
+*/
+var PreviewProofTransportError = class extends Error {
+	/** How many transport attempts were made before giving up. */
+	attempts;
+	/** The last transient HTTP status, when the server answered at all. */
+	status;
+	constructor(reason, attempts, status) {
+		super(`Preview proof inventory transport failed after ${attempts} attempt(s): ${reason}`);
+		this.name = "PreviewProofTransportError";
+		this.attempts = attempts;
+		if (status !== void 0) this.status = status;
+	}
+};
+/**
+* Transient statuses are the ones where GitHub never judged the content — a
+* request timeout (408), a rate limit (429), or the server failing (5xx) — so
+* the same bytes can still succeed. Every other non-2xx is GitHub refusing
+* this request and repeats on retry.
+*/
+const isTransientStatus = (status) => status === 408 || status === 429 || status >= 500;
+/**
+* A bounded, credential-free description of a transport failure. The raw
+* error may retain the request and its `Authorization` header; only the name
+* and a truncated message survive.
+*/
+const boundedTransportReason = (error) => error instanceof Error ? `${error.name}: ${error.message}`.slice(0, 200) : "unknown transport error";
+const defaultTransportWait = (ms) => setTimeout$1(ms);
+let transportWait = defaultTransportWait;
+/**
+* One transport attempt. A transient failure is reported as an outcome so the
+* caller can retry; a permanent HTTP refusal throws `GitHubApiError` here.
+*/
+const githubJsonAttempt = async (request, url, token, init, timeoutMs) => {
+	let response;
+	try {
+		response = await request(url, {
+			body: init.body,
+			headers: {
+				Accept: "application/vnd.github+json",
+				Authorization: `Bearer ${token}`,
+				"X-GitHub-Api-Version": GITHUB_API_VERSION,
+				...init.body === void 0 ? {} : { "Content-Type": "application/json" }
+			},
+			method: init.method,
+			signal: AbortSignal.timeout(timeoutMs)
+		});
+	} catch (error) {
+		return {
+			ok: false,
+			reason: boundedTransportReason(error)
+		};
+	}
+	if (!response.ok) {
+		if (!isTransientStatus(response.status)) throw new GitHubApiError(response.status, response.statusText);
+		return {
+			ok: false,
+			reason: `GitHub API ${response.status} ${response.statusText}`,
+			status: response.status
+		};
+	}
+	try {
+		return {
+			ok: true,
+			value: await response.json()
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			reason: boundedTransportReason(error)
+		};
+	}
+};
 const githubJson = async (request, url, token, init, timeoutMs) => {
-	const response = await request(url, {
-		body: init.body,
-		headers: {
-			Accept: "application/vnd.github+json",
-			Authorization: `Bearer ${token}`,
-			"X-GitHub-Api-Version": GITHUB_API_VERSION,
-			...init.body === void 0 ? {} : { "Content-Type": "application/json" }
-		},
-		method: init.method,
-		signal: AbortSignal.timeout(timeoutMs)
-	});
-	if (!response.ok) throw new GitHubApiError(response.status, response.statusText);
-	return await response.json();
+	let outcome = await githubJsonAttempt(request, url, token, init, timeoutMs);
+	for (let attempt = 2; attempt <= TRANSPORT_RETRY_ATTEMPTS && !outcome.ok; attempt += 1) {
+		await transportWait(TRANSPORT_RETRY_BACKOFF_MS * 2 ** (attempt - 2));
+		outcome = await githubJsonAttempt(request, url, token, init, timeoutMs);
+	}
+	if (outcome.ok) return outcome.value;
+	throw new PreviewProofTransportError(outcome.reason, TRANSPORT_RETRY_ATTEMPTS, outcome.status);
 };
 const githubGraphql = async (request, token, timeoutMs, query, variables) => {
 	const served = await githubJson(request, "https://api.github.com/graphql", token, {
@@ -3199,4 +3286,4 @@ const assertWorkflowShellParses = (yaml, options) => {
 	throw new Error(`${options.source} emits shell bash cannot parse; the runner would treat it as a no-op:\n${detail}`);
 };
 //#endregion
-export { EXECUTE_ALCHEMY_ENTRY_MAX_BUFFER, FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT, FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT, FACTORY_CANDIDATE_IMPACT_INERT_OUTPUT, FACTORY_CANDIDATE_IMPACT_STEP_ID, FACTORY_CANDIDATE_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_CANDIDATE_PULL_REQUEST_TYPES, FACTORY_LIFECYCLE_CONTRACT_JOB_ID, FACTORY_LIFECYCLE_CONTRACT_JOB_NAME, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_ID, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_NAME, 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_PR_STATUS_HUD_APP_TOKEN_STEP_ID, FACTORY_PR_STATUS_HUD_CONCURRENCY, FACTORY_PR_STATUS_HUD_IF, FACTORY_PR_STATUS_HUD_JOB_ID, FACTORY_PR_STATUS_HUD_JOB_NAME, FACTORY_PR_STATUS_HUD_PERMISSIONS, FACTORY_PR_STATUS_HUD_PLAN_PATH, FACTORY_PUSH_IDENTITY_SCHEMA_VERSION, GitHubApiError, NODE_PNPM_ACTION_FAMILY_NODE24, PREVIEW_PROOF_INVENTORY_CHECK_NAME, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, VitestProfileError, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryCandidateImpactWorkflow, factoryCandidateOrPushCondition, factoryLifecycleContractLane, factoryPrStatusHudWorkflow, factoryPreviewCleanupTopology, factoryProductionImpactWorkflow, factoryProofGateScript, factoryProofGateStep, factoryProofReuseSummaryStep, factoryProofTimingStartStep, factoryPushIdentityConsumer, factoryPushIdentityProducer, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, previewCleanupDestroyJobId, previewProofInventory, previewProofLifecycle, productionImpactTargetOutput, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };
+export { EXECUTE_ALCHEMY_ENTRY_MAX_BUFFER, FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT, FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT, FACTORY_CANDIDATE_IMPACT_INERT_OUTPUT, FACTORY_CANDIDATE_IMPACT_STEP_ID, FACTORY_CANDIDATE_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_CANDIDATE_PULL_REQUEST_TYPES, FACTORY_LIFECYCLE_CONTRACT_JOB_ID, FACTORY_LIFECYCLE_CONTRACT_JOB_NAME, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_ID, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_NAME, 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_PR_STATUS_HUD_APP_TOKEN_STEP_ID, FACTORY_PR_STATUS_HUD_CONCURRENCY, FACTORY_PR_STATUS_HUD_IF, FACTORY_PR_STATUS_HUD_JOB_ID, FACTORY_PR_STATUS_HUD_JOB_NAME, FACTORY_PR_STATUS_HUD_PERMISSIONS, FACTORY_PR_STATUS_HUD_PLAN_PATH, FACTORY_PUSH_IDENTITY_SCHEMA_VERSION, GitHubApiError, NODE_PNPM_ACTION_FAMILY_NODE24, PREVIEW_PROOF_INVENTORY_CHECK_NAME, PreviewProofTransportError, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, VitestProfileError, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryCandidateImpactWorkflow, factoryCandidateOrPushCondition, factoryLifecycleContractLane, factoryPrStatusHudWorkflow, factoryPreviewCleanupTopology, factoryProductionImpactWorkflow, factoryProofGateScript, factoryProofGateStep, factoryProofReuseSummaryStep, factoryProofTimingStartStep, factoryPushIdentityConsumer, factoryPushIdentityProducer, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, previewCleanupDestroyJobId, previewProofInventory, previewProofLifecycle, productionImpactTargetOutput, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patronage/factory-ci",
-  "version": "1.0.0-alpha.20",
+  "version": "1.0.0-alpha.21",
   "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",
@@ -36,17 +36,19 @@
   "devDependencies": {
     "@types/node": "24.13.3",
     "@vitest/coverage-v8": "4.1.10",
+    "knip": "6.27.0",
     "oxfmt": "0.59.0",
-    "oxlint": "1.74.0",
+    "oxlint": "1.76.0",
     "tsdown": "0.21.10",
     "typescript": "5.9.3",
-    "ultracite": "7.9.4",
+    "ultracite": "7.10.5",
     "vitest": "4.1.10"
   },
   "engines": {
     "node": "^24.0.0"
   },
   "scripts": {
+    "cleanup:check": "knip --files --dependencies",
     "prebuild": "bash ../scripts/ensure-worktree-bootstrap.sh",
     "build": "tsdown",
     "precheck": "bash ../scripts/ensure-worktree-bootstrap.sh",

package/src/index.ts

@@ -50,6 +50,7 @@ export {
   type PreviewProofInventoryPersistInput,
   type PreviewProofInventoryStore,
   type PreviewProofInventoryTransport,
+  PreviewProofTransportError,
 } from "./preview-proof-inventory.ts";
 export {
   type CheckoutStepOptions,

package/src/preview-proof-inventory.ts

@@ -1,3 +1,5 @@
+import { setTimeout as sleep } from "node:timers/promises";
+
 import { parseLocalPreviewStage } from "./disposable-stage.ts";
 import { GitHubApiError } from "./github-app-token.ts";
 import type {
@@ -18,6 +20,15 @@ import { FACTORY_PROOF_GATE_APP_ID } from "./proof-reuse-gate.ts";
  * secrets. Cleanup writes go through `previewProofLifecycle.transition` with
  * `{ type: "cleanup" }`. Outcomes are never inferred from whether a stage
  * still exists.
+ *
+ * Transient transport failures are retried with bounded backoff and then
+ * surface as `PreviewProofTransportError` (#830). A failure from `persist` or
+ * `recordCleanup` is an evidence-registration failure, never a failed
+ * deployment: the caller retains the healthy disposable stage, records its own
+ * proof BLOCKED (never PASS), and re-runs registration at the same head —
+ * writes are keyed by stack and stage, so resuming needs no redeploy.
+ * Admission stays fail-closed on its own: an unregistered proof never
+ * satisfies the preview demand.
  */
 
 /** Check-run name that carries one registration JSON payload. Not a gate. */
@@ -27,6 +38,10 @@ export const PREVIEW_PROOF_INVENTORY_CHECK_NAME =
 const INVENTORY_KIND = "patronage-factory-preview-proof";
 const INVENTORY_SCHEMA_VERSION = 1;
 const DEFAULT_TIMEOUT_MS = 5000;
+/** Total transport attempts per request, the first one included. */
+const TRANSPORT_RETRY_ATTEMPTS = 3;
+/** Delay before the first retry; each further retry doubles it. */
+const TRANSPORT_RETRY_BACKOFF_MS = 500;
 const CHECK_RUNS_PER_PAGE = 100;
 const COMMITS_PER_PAGE = 100;
 const MAX_CHECK_RUN_PAGES = 10;
@@ -319,6 +334,126 @@ export const memoryStore = (): PreviewProofInventoryStore => {
   };
 };
 
+/**
+ * The transport gave out — a network-level rejection (EPIPE, DNS, an aborted
+ * or timed-out request) or a transient HTTP status — and bounded retries did
+ * not recover it. GitHub never judged the content, so this is never a
+ * validation verdict and never a deployment failure. Only a bounded reason
+ * string is retained: the raw transport error can hold the request and its
+ * `Authorization` header, so it is deliberately discarded.
+ */
+export class PreviewProofTransportError extends Error {
+  /** How many transport attempts were made before giving up. */
+  readonly attempts: number;
+  /** The last transient HTTP status, when the server answered at all. */
+  readonly status?: number;
+
+  constructor(reason: string, attempts: number, status?: number) {
+    super(
+      `Preview proof inventory transport failed after ${attempts} attempt(s): ${reason}`
+    );
+    this.name = "PreviewProofTransportError";
+    this.attempts = attempts;
+    if (status !== undefined) {
+      this.status = status;
+    }
+  }
+}
+
+/**
+ * Transient statuses are the ones where GitHub never judged the content — a
+ * request timeout (408), a rate limit (429), or the server failing (5xx) — so
+ * the same bytes can still succeed. Every other non-2xx is GitHub refusing
+ * this request and repeats on retry.
+ */
+const isTransientStatus = (status: number): boolean =>
+  status === 408 || status === 429 || status >= 500;
+
+/**
+ * A bounded, credential-free description of a transport failure. The raw
+ * error may retain the request and its `Authorization` header; only the name
+ * and a truncated message survive.
+ */
+const boundedTransportReason = (error: unknown): string =>
+  error instanceof Error
+    ? `${error.name}: ${error.message}`.slice(0, 200)
+    : "unknown transport error";
+
+type TransportWait = (ms: number) => Promise<void>;
+
+const defaultTransportWait: TransportWait = (ms) => sleep(ms);
+
+let transportWait: TransportWait = defaultTransportWait;
+
+/** Package-test seam. Not re-exported from `index.ts`. */
+export const setPreviewProofTransportWaitForTests = (
+  next?: TransportWait
+): void => {
+  transportWait = next ?? defaultTransportWait;
+};
+
+/**
+ * One GitHub JSON request with bounded retries (#830). Each attempt gets a
+ * fresh timeout signal. A transient failure — network rejection, timeout,
+ * transient HTTP status, or a body that dies mid-read — retries with doubling
+ * backoff and exhausts into `PreviewProofTransportError`; a permanent HTTP
+ * refusal throws `GitHubApiError` on its first response. Retrying a write is
+ * safe: check-run payloads are idempotent per stack and stage, and a
+ * duplicated create is resolved by the newest-run read
+ * (`compareCheckRunsNewestFirst`).
+ */
+type TransportOutcome =
+  | { ok: true; value: unknown }
+  | { ok: false; reason: string; status?: number };
+
+/**
+ * One transport attempt. A transient failure is reported as an outcome so the
+ * caller can retry; a permanent HTTP refusal throws `GitHubApiError` here.
+ */
+const githubJsonAttempt = async (
+  request: typeof fetch,
+  url: string,
+  token: string,
+  init: { body?: string; method: "GET" | "PATCH" | "POST" },
+  timeoutMs: number
+): Promise<TransportOutcome> => {
+  let response: Response;
+  try {
+    response = await request(url, {
+      body: init.body,
+      headers: {
+        Accept: "application/vnd.github+json",
+        Authorization: `Bearer ${token}`,
+        "X-GitHub-Api-Version": GITHUB_API_VERSION,
+        ...(init.body === undefined
+          ? {}
+          : { "Content-Type": "application/json" }),
+      },
+      method: init.method,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (error) {
+    return { ok: false, reason: boundedTransportReason(error) };
+  }
+  if (!response.ok) {
+    if (!isTransientStatus(response.status)) {
+      throw new GitHubApiError(response.status, response.statusText);
+    }
+    return {
+      ok: false,
+      reason: `GitHub API ${response.status} ${response.statusText}`,
+      status: response.status,
+    };
+  }
+  try {
+    return { ok: true, value: (await response.json()) as unknown };
+  } catch (error) {
+    // A 2xx whose body dies mid-read is the transport failing, not GitHub
+    // refusing: the EPIPE that motivated #830 lands exactly here.
+    return { ok: false, reason: boundedTransportReason(error) };
+  }
+};
+
 const githubJson = async (
   request: typeof fetch,
   url: string,
@@ -326,23 +461,27 @@ const githubJson = async (
   init: { body?: string; method: "GET" | "PATCH" | "POST" },
   timeoutMs: number
 ): Promise<unknown> => {
-  const response = await request(url, {
-    body: init.body,
-    headers: {
-      Accept: "application/vnd.github+json",
-      Authorization: `Bearer ${token}`,
-      "X-GitHub-Api-Version": GITHUB_API_VERSION,
-      ...(init.body === undefined
-        ? {}
-        : { "Content-Type": "application/json" }),
-    },
-    method: init.method,
-    signal: AbortSignal.timeout(timeoutMs),
-  });
-  if (!response.ok) {
-    throw new GitHubApiError(response.status, response.statusText);
+  let outcome = await githubJsonAttempt(request, url, token, init, timeoutMs);
+
+  for (
+    let attempt = 2;
+    attempt <= TRANSPORT_RETRY_ATTEMPTS && !outcome.ok;
+    attempt += 1
+  ) {
+    // oxlint-disable-next-line no-await-in-loop -- bounded backoff between sequential retries
+    await transportWait(TRANSPORT_RETRY_BACKOFF_MS * 2 ** (attempt - 2));
+    // oxlint-disable-next-line no-await-in-loop -- retries are sequential by design
+    outcome = await githubJsonAttempt(request, url, token, init, timeoutMs);
   }
-  return (await response.json()) as unknown;
+
+  if (outcome.ok) {
+    return outcome.value;
+  }
+  throw new PreviewProofTransportError(
+    outcome.reason,
+    TRANSPORT_RETRY_ATTEMPTS,
+    outcome.status
+  );
 };
 
 const githubGraphql = async (

package/src/vitest-profile-reader.ts

@@ -216,5 +216,10 @@ export const readVitestProfileDocument = (
     return { kind: "unrecognized", reason: summary };
   }
 
+  // Every field above is checked against the profile contract, but the checks
+  // return reasons rather than narrowing `value`. Rebuilding the document
+  // field-by-field here would copy the writer's shape into the reader and let
+  // the two drift. Keep the one double assertion; the checks are the proof.
+  // oxlint-disable-next-line anti-slop/no-chained-type-assertions
   return { kind: "profile", profile: value as unknown as VitestProfile };
 };