@patronage/factory-ci 1.0.0-alpha.37 → 1.0.0-alpha.39

package/README.md

@@ -459,7 +459,7 @@ import { previewProofLifecycle } from "@patronage/factory-ci";
 
 Events:
 
-- `begin` — the pre-deploy gate. Refuses a draft, a closed PR, a dirty or mismatched worktree, and any stage the disposable grammar does not own for this PR head. Does not create a registration.
+- `begin` — the pre-deploy gate. A mismatched branch name is accepted at the PR head SHA. A dirty tree or a SHA mismatch is refused, as are a draft, a closed PR, and any stage the disposable grammar does not own for this PR head. Does not create a registration.
 - `register` — the same identity gate, plus passed smoke, passed convergence, and a passing three-way-bound evidence envelope at this head. Writes a registration with `cleanup.outcome: "pending"`. Cleanup, smoke, and convergence status live only on their nested objects, so no top-level copy can diverge from them. Machine evidence is that envelope; this module never posts a PR comment.
 - `cleanup` — records an explicit passed or failed outcome onto an existing registration. Cleanup is never inferred from whether the stage still exists. `recover` is the failed-to-resolved re-entry of this event.
 

package/dist/.build-fingerprint.json

@@ -1,3 +1,3 @@
 {
-  "fingerprint": "d4ebf8af4787cc4426a8c73b8f84098d818fc0f34fab36f6afc21e49e0b619a5"
+  "fingerprint": "96dfad08bf2d426a9c9efe5b3b753fc99f7a3cee0d83d36766dd8aa15417f5d1"
 }

package/dist/index.d.ts

@@ -178,7 +178,10 @@ declare const localPreviewStage: (options: LocalPreviewStageOptions) => LocalPre
  *
  * Proof sits entirely on one side of GitHub's draft/ready boundary
  * (paitronage#1089): a draft candidate cannot begin or register. Machine
- * evidence is the envelope at head (#355), never a PR comment.
+ * evidence is the envelope at head (#355), never a PR comment. The SHA and
+ * repository bind that proof (#1312): a detached HEAD or a branch name that
+ * differs from the PR head is the same commit, and the registration records
+ * `branch: "(detached)"`.
  */
 type PreviewProofCleanupStatus = "failed" | "passed" | "pending";
 interface PreviewProofCandidate {
@@ -206,6 +209,13 @@ interface PreviewProofCleanupOutcome {
   readonly runUrl?: string;
 }
 interface PreviewProofRegistration {
+  /**
+   * Present only when the checkout is detached or its branch name is not the
+   * PR head. The `(detached)` sentinel is on the lifecycle registration
+   * `transition` returns, and `previewProofInventory` does not persist it.
+   * It is not a branch to check out.
+   */
+  readonly branch?: "(detached)";
   readonly cleanup: {
     readonly evidence: readonly string[];
     readonly outcome: PreviewProofCleanupStatus;

package/dist/index.js

@@ -74,6 +74,12 @@ const factoryCandidateOrPushCondition = (candidateCondition) => {
 //#endregion
 //#region src/preview-proof-lifecycle.ts
 const EMPTY_STATE = Object.freeze({ registrations: Object.freeze([]) });
+const DETACHED_PROOF_BRANCH = "(detached)";
+/**
+* The branch name adds no guarantee. Record the sentinel unless the checkout
+* is actually on the PR head branch.
+*/
+const proofBranch = (candidate) => candidate.branch.length > 0 && candidate.branch === candidate.prHeadRef ? void 0 : DETACHED_PROOF_BRANCH;
 const registrationKey$1 = (row) => `${row.stack}:${row.stage}`;
 const disposableStage = (stage, candidate) => {
 	const parsed = parseLocalPreviewStage(stage, {
@@ -88,9 +94,7 @@ const assertAdmissibleCandidate = (candidate, stage) => {
 	if (candidate.prState !== "OPEN") throw new Error("Preview proof requires an open pull request.");
 	const errors = [];
 	if (candidate.dirty) errors.push("Worktree must be clean.");
-	if (!candidate.branch) errors.push("Detached HEAD is not trusted for preview proof.");
 	if (candidate.headSha !== candidate.prHeadSha) errors.push("HEAD is stale for the current PR head.");
-	if (candidate.branch !== candidate.prHeadRef) errors.push("Current branch does not match the PR head branch.");
 	if (candidate.repository !== candidate.prRepository) errors.push("PR head repository does not match the current repository.");
 	if (errors.length > 0) throw new Error(errors.join("\n"));
 	return disposableStage(stage, candidate);
@@ -116,7 +120,9 @@ const transition = (state, event) => {
 		if (event.convergence.status !== "passed") throw new Error("Preview proof requires passed convergence evidence.");
 		if (!event.stack || !event.url) throw new Error("Preview proof registration requires a stack and URL.");
 		assertPassingEnvelope(event.evidence, event.candidate.headSha);
+		const branch = proofBranch(event.candidate);
 		return replaceRegistration$1(state, {
+			...branch === void 0 ? {} : { branch },
 			cleanup: {
 				evidence: [],
 				outcome: "pending"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patronage/factory-ci",
-  "version": "1.0.0-alpha.37",
+  "version": "1.0.0-alpha.39",
   "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",

package/src/preview-proof-lifecycle.ts

@@ -11,7 +11,10 @@ import type { LocalPreviewStage } from "./disposable-stage.ts";
  *
  * Proof sits entirely on one side of GitHub's draft/ready boundary
  * (paitronage#1089): a draft candidate cannot begin or register. Machine
- * evidence is the envelope at head (#355), never a PR comment.
+ * evidence is the envelope at head (#355), never a PR comment. The SHA and
+ * repository bind that proof (#1312): a detached HEAD or a branch name that
+ * differs from the PR head is the same commit, and the registration records
+ * `branch: "(detached)"`.
  */
 
 export type PreviewProofCleanupStatus = "failed" | "passed" | "pending";
@@ -44,6 +47,13 @@ export interface PreviewProofCleanupOutcome {
 }
 
 export interface PreviewProofRegistration {
+  /**
+   * Present only when the checkout is detached or its branch name is not the
+   * PR head. The `(detached)` sentinel is on the lifecycle registration
+   * `transition` returns, and `previewProofInventory` does not persist it.
+   * It is not a branch to check out.
+   */
+  readonly branch?: "(detached)";
   readonly cleanup: {
     readonly evidence: readonly string[];
     readonly outcome: PreviewProofCleanupStatus;
@@ -111,6 +121,19 @@ const EMPTY_STATE: PreviewProofLifecycleState = Object.freeze({
   registrations: Object.freeze([]),
 });
 
+const DETACHED_PROOF_BRANCH = "(detached)" as const;
+
+/**
+ * The branch name adds no guarantee. Record the sentinel unless the checkout
+ * is actually on the PR head branch.
+ */
+const proofBranch = (
+  candidate: PreviewProofCandidate
+): typeof DETACHED_PROOF_BRANCH | undefined =>
+  candidate.branch.length > 0 && candidate.branch === candidate.prHeadRef
+    ? undefined
+    : DETACHED_PROOF_BRANCH;
+
 const registrationKey = (row: {
   readonly stack: string;
   readonly stage: string;
@@ -149,15 +172,9 @@ const assertAdmissibleCandidate = (
   if (candidate.dirty) {
     errors.push("Worktree must be clean.");
   }
-  if (!candidate.branch) {
-    errors.push("Detached HEAD is not trusted for preview proof.");
-  }
   if (candidate.headSha !== candidate.prHeadSha) {
     errors.push("HEAD is stale for the current PR head.");
   }
-  if (candidate.branch !== candidate.prHeadRef) {
-    errors.push("Current branch does not match the PR head branch.");
-  }
   if (candidate.repository !== candidate.prRepository) {
     errors.push("PR head repository does not match the current repository.");
   }
@@ -233,8 +250,10 @@ const transition = (
       throw new Error("Preview proof registration requires a stack and URL.");
     }
     assertPassingEnvelope(event.evidence, event.candidate.headSha);
+    const branch = proofBranch(event.candidate);
 
     return replaceRegistration(state, {
+      ...(branch === undefined ? {} : { branch }),
       cleanup: { evidence: [], outcome: "pending" },
       convergence: {
         detail: event.convergence.detail,