@patronage/factory-ci 1.0.0-alpha.36 → 1.0.0-alpha.38

package/README.md

@@ -14,7 +14,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 four deep modules, not a workflow framework.
+The admission rule is **experiment, prove, fan out** (ADR 0036). A mechanism starts as an experiment in one project. When the experiment proves it and the intent is fleet-wide, it moves into the factory: into this package, or into `psf` when it is invocable. Then it fans out to the other projects. A single consumer is a risk to record, not a gate. The public surface is made of deep modules, not a workflow framework.
 
 ## Exports
 
@@ -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.
 
@@ -684,7 +684,7 @@ const result = await runAlchemyLifecycle({
 });
 ```
 
-`runAlchemyLifecycle` is the one operation over an Alchemy plan, deploy, or destroy. It owns the order; a consumer cannot get the order wrong because it does not call the steps. Paitronage and HQ each reconstructed this sequence from the guards below and got different parts wrong (paitronage#1917), which is the repetition that admits it here.
+`runAlchemyLifecycle` is the one operation over an Alchemy plan, deploy, or destroy. It owns the order; a consumer cannot get the order wrong because it does not call the steps. Paitronage and HQ each reconstructed this sequence from the guards below and got different parts wrong (paitronage#1917), which was the evidence that admitted it here.
 
 The consumer passes typed policy and two capabilities. `state` is the store from `@patronage/alchemy-d1-state`: `snapshotStage`, `get`, and `acquireStageOwnership`, whose lease carries `renew`, `release`, `deleteEmptyStage` and `childEnvironment`, matched structurally, so this package learns no table, account, or SQL. `entry` is what `executeAlchemyEntry` needs minus what the lifecycle decides: the arguments are the lifecycle's, stdio is always piped so the plan can be read, and a `bundle` is built once up front, with every child launched in `cwd`, then the bundle root, then this process's directory — the same chain `executeAlchemyEntry` resolves. A bundle that cannot build is `PREPARATION_FAILED` and nothing else: the bundler's own diagnostics are silenced at the source. There is no `redact` and no echo because there is no sink: each child's captured output is parsed and dropped, written nowhere, so nothing in it can reach a job log or an evidence file through this operation. Every child's environment carries the stage lease; see ownership below.
 

package/dist/.build-fingerprint.json

@@ -1,3 +1,3 @@
 {
-  "fingerprint": "b74ad36f28a800fdec15f84e7711704b2b79305d6207efd55f663040f40fe034"
+  "fingerprint": "37346d3a02aec3deb1a18d945ba3947736ce1481755941389579f15affea6130"
 }

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.36",
+  "version": "1.0.0-alpha.38",
   "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,