@kungfu-tech/buildchain 4.0.1-alpha.36 → 4.0.1-alpha.38

package/architecture/maintainability-policy.json

@@ -5,12 +5,12 @@
   "enforcementRevision": "5308189b09bcb5a1314195412f2807a40d678838",
   "repositoryBudgets": {
     "baselineRevision": "858dbe00b6206a8f356b4a12d2659bee7a72e71b",
-    "maxHandMaintainedSourceFiles": 427,
-    "maxHandMaintainedSourceLines": 159840,
+    "maxHandMaintainedSourceFiles": 429,
+    "maxHandMaintainedSourceLines": 160394,
     "maxWorkflowFiles": 76,
-    "maxWorkflowLines": 26318,
-    "latestTransition": "Stable promotion forwards the exact sealed-candidate recovery identity into the existing v4 workflow shell.",
-    "latestTransitionRationale": "The generated stable route now forwards the nine existing resume inputs already accepted and independently verified by the v4 private promotion shell. This preserves the original candidate bytes, tree and runtime A while binding recovery runtime B; it does not add a new recovery mode or publication authority. Workflow size grows by exactly nine generated pass-through lines while the source ceiling remains unchanged. These exact 427-file, 159840-source-line, 76-workflow-file and 26318-workflow-line ceilings add no unrelated headroom.",
+    "maxWorkflowLines": 26320,
+    "latestTransition": "Managed Project Cut admission binds exact native-family queue leases before protected Dev delivery.",
+    "latestTransitionRationale": "The bounded Project Cut adapter replays one immutable linear source range onto the exact latest protected base in a temporary index, rejects conflicts or stable patch and path drift, and emits deterministic base, head, fork, candidate tree, family lease, and terminal release roots. It grants no merge authority: the PR engine still owns exact-head status fencing, Warrant verification, independent review, merge-queue admission, protected readback, and lease release. Stable recovery continues to derive publication version state only from the validated candidate without changing sealed identity. These exact 429-file, 160394-source-line, 76-workflow-file and 26320-workflow-line ceilings account for the two bounded source adapters with no unrelated headroom.",
     "rationale": "Bounded modules separate candidate, evidence, native proof and execution, canonical failure verification, closed-set execution transfer, process-boundary verification, Warrant state and qualification, authority state, qualification, Landing acquisition, verified-attempt admission, Landing settlement and fence validation, provider attempt and heartbeat readback, sealed terminal evidence, hosted heartbeat, resume, store, options, command-specific adapters, and CLI orchestration responsibilities. The protected delivery workflow gives candidate and seal jobs no provider write credential, recursively rejects transfer drift, scopes every transfer artifact to the exact provider run attempt, chains every durable heartbeat state and receipt root on a distinct hosted runner domain, and permits qualification or exact failure settlement only after the finalizer verifies live jobs and the latest durable authority state. Public Landing admission and heartbeat always perform non-injectable fresh exact-attempt provider readback, tolerate only a not-yet-materialized seal job while retaining exact native and duplicate-job rejection, and heartbeat-loss coordination never invokes GitHub's run-scoped cancellation API where a successor rerun could race. The hosted process boundary anchors trust in the kernel-resolved versioned Runner.Worker path while accepting an equivalent argv-zero spelling with the same basename; its public boundary marker is allowed only at the one exact non-secret value, so a forged value under the same credential-like name still fails closed. The credentialless transfer seal validates the rooted native reuse decision against the Warrant-bound source, closure, dependency, toolchain, environment and command inputs; qualifiedBase stays in the proof and decision where it is rooted and later independently rechecked, rather than being assumed on the Warrant schema. V2 mutation cannot initialize a second empty authority beside a legacy ref: migration reads and roots the canonical live v1 ref, rechecks it, applies the explicit configured v2 policy, and atomically replaces its bytes through one expected-old non-force update, so old v1 controllers fail closed while the prior commit remains immutable history. Candidate ancestry classifies the GitHub artifact runtime token as credential authority. Every Landing settlement, including an unexpired fence, requires product-owned terminal readback. Terminal cleanup reads the immutable historical attempt, derives workflow and hosted Landing job identity from live run data, reads the exact protected ref head and compares containment against that immutable SHA, and seals merged only when the admitted merge-group head is contained by that protected base; a later different-head merge settles the old attempt as dequeued. Terminal normalization preserves transfer, finalizer boundary, native and seal job, admitted provider attempt, protected-base head, containment result, and terminal readback coordinates. The public reusable workflow truthfully retains its single-flight v1 authority without advertising v2 migration, while bounded v2 remains a separate opt-in CLI, Node API, and schema contract; the tracked self-caller stays on public v4-alpha with matching stable and alpha locks, and transient train selection is dispatch-only. Next-development parity adds one versioned transition authority, one durable controller, one bounded reservation adapter, and pure public-contract recovery evidence while retaining the existing thin floating-channel callers byte-for-byte. The floating-consumer gate reuses the existing contract-world evaluator so SHA drift passes only under the selected lock's compatibility policy, breaking surface drift still fails closed, and external certification reconstructs the receipt from the observed workflow SHA rather than the lock's historical evidence SHA. Tail reseal adds no Stage Capsule effect or general rebuild authority: it verifies the exact retained four-platform bytes, admits one known macOS tail failure through live provider readback, fences signing and finalization to explicit credentials and Warrant identity, and requires standard candidate Passport plus provider and protected readback. Compatibility Facts parity isolates canonical encoding, temporal verification, lifecycle validation, fixture projection, public authority projection, and CLI adaptation into bounded modules; legacy digest and proof arrays are derived only from exact current Fact lineage. Publication Rehearsal adds no production release authority: the content-addressed capsule contract binds source, candidate, manifest, config, canonical data-only provider bindings, provider policy, observations and core version separately from filesystem, runtime and rehearsal-only provider authority; simulate, replay and explicitly authorized provider rehearsal all reuse the release-tail planner, while same-commit local dogfood resolves the new reusable contract and exact current runtime before external callers remain on floating v4-alpha. Cross-runtime candidate recovery preserves original runtime and provider roots and creates resume lineage only after exact public ref, tag, ancestry, npm version and integrity readback. Adopter Delivery restores the reviewed public v3 gate, drivers, Passport binding, N-1 bootstrap and exact archive loader through one public v4 surface while keeping provider and release authority explicit non-claims. Floating Alpha bootstrap uses only the existing exact resolver and protected Alpha private shell to move an otherwise stale floating shell, retains public v4 stable promotion, and removes itself after protected readback. CI lane change-budget enforcement adds a bounded parser, evaluator, guard, and tests without creating another merge authority."
   },
   "sourceBudgets": {

package/dist/site/buildchain-contract.json

@@ -4,7 +4,7 @@
   "product": {
     "name": "Buildchain",
     "package": "@kungfu-tech/buildchain",
-    "version": "4.0.1-alpha.36",
+    "version": "4.0.1-alpha.38",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "majorLine": "v4",
@@ -1492,7 +1492,7 @@
         "durable consumers call the public floating workflow and may route a train or exact runtime only through trusted non-persistent dispatch input"
       ],
       "breakingDigest": "sha256:21b65d0746d2e8b3e8a7df4c6fab295a85c8fd42cc405ec3bc5df5cdab0421f0",
-      "auditDigest": "sha256:1392bc85e8aef8c19161b06764900c2cdb0f0cd57bf65dc95ad578040add7bea"
+      "auditDigest": "sha256:6bd7c071717e16813c03c018e8bf868e54e9f98bff388b6790f6861d18a58831"
     },
     {
       "contractVersion": 1,
@@ -5308,5 +5308,5 @@
   "compatibilityFactCutRoot": "sha256:f61b975d4a96c921cc4bd37fb3ed9a0596b47004fe34dc7219979d697e3707f9",
   "compatibilityProofRegistryRoot": "sha256:b7194b811e4d3af2df4390bc4d1731e16a86215bd64ee18cb630dd5492f4fb63",
   "compatibilityDigest": "sha256:5de1c69386510b74b17eb70141b8bdd07063d62c504f91db5e84b67c6d4b64a2",
-  "contractDigest": "sha256:08da7cb857e3c977a4dd0a918af9659de8628a9404c6a5a907593d8f89d294ae"
+  "contractDigest": "sha256:20999ce26355490a526425b3c0524e6e98cda3fd2b38b30300e69ed0a434b80e"
 }

package/dist/site/buildchain-site.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-bundle",
-  "generatedAt": "2026-08-24T04:04:36.516Z",
-  "publishedAt": "2026-08-24T04:04:36.516Z",
+  "generatedAt": "2026-08-24T12:50:00.932Z",
+  "publishedAt": "2026-08-24T12:50:00.932Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "975c93b1e33d04d6c27e2879651f8dcfd9b5fe42",
+  "sourceRevision": "396e7cb2eb240943f8ac6fa5d25e03cd5fc9051a",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "4.0.1-alpha.36",
+    "version": "4.0.1-alpha.38",
     "versionSource": "package.json#version"
   },
   "source": {

package/dist/site/kfd-claims.json

@@ -21,7 +21,7 @@
     "contract": "kungfu-buildchain-public-surface-reverse-audit",
     "path": "dist/site/public-surface-audit.json",
     "status": "passed",
-    "sha256": "94f0e944155b53b68186da6ff5edaad13f23514e0207e2a9516a8c402f7f44a9",
+    "sha256": "17c50414e9933a686ee5583ea47ceffcaa696b2755775f9ea77d041e78038384",
     "summary": {
       "cliCommandCount": 117,
       "workflowCount": 76,
@@ -246,7 +246,7 @@
       "contract": "kungfu-buildchain-public-surface-reverse-audit",
       "path": "dist/site/public-surface-audit.json",
       "status": "passed",
-      "sha256": "94f0e944155b53b68186da6ff5edaad13f23514e0207e2a9516a8c402f7f44a9",
+      "sha256": "17c50414e9933a686ee5583ea47ceffcaa696b2755775f9ea77d041e78038384",
       "summary": {
         "cliCommandCount": 117,
         "workflowCount": 76,

package/dist/site/kfd-upstream-aggregate.json

@@ -4,7 +4,7 @@
   "product": {
     "id": "kungfu-tech-buildchain",
     "name": "@kungfu-tech/buildchain",
-    "version": "4.0.1-alpha.36",
+    "version": "4.0.1-alpha.38",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "source": {

package/dist/site/public-surface-audit.json

@@ -8846,7 +8846,7 @@
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "ea47a31ce7ef3577f23e22055ab7be7715c3af494bcef63f76b426f2883086aa",
-    "workflowRegistryDigest": "1b21627d15c546740ad5fbf98df3c0ea989009193f86b55a15cf139f45934439",
+    "workflowRegistryDigest": "79e6398226388dd0fddfaeceb13b72e3d7ba35b68ea396114da7fb7873981829",
     "pageRegistryDigest": "619910e5c57fb8e94ea1525de1fb7699c412a8dafd7269bc9354cc6c4fe83f48"
   },
   "comparison": {

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-08-24T04:04:36.516Z",
-  "publishedAt": "2026-08-24T04:04:36.516Z",
+  "generatedAt": "2026-08-24T12:50:00.932Z",
+  "publishedAt": "2026-08-24T12:50:00.932Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "975c93b1e33d04d6c27e2879651f8dcfd9b5fe42",
+  "sourceRevision": "396e7cb2eb240943f8ac6fa5d25e03cd5fc9051a",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "4.0.1-alpha.36",
+    "version": "4.0.1-alpha.38",
     "versionSource": "package.json#version"
   },
   "sourceKind": "package-site-bundle",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-08-24T04:04:36.516Z",
-  "publishedAt": "2026-08-24T04:04:36.516Z",
+  "generatedAt": "2026-08-24T12:50:00.932Z",
+  "publishedAt": "2026-08-24T12:50:00.932Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "975c93b1e33d04d6c27e2879651f8dcfd9b5fe42",
+  "sourceRevision": "396e7cb2eb240943f8ac6fa5d25e03cd5fc9051a",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "4.0.1-alpha.36",
+    "version": "4.0.1-alpha.38",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",

package/dist/site/workflow-registry.json

@@ -2027,7 +2027,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.1-alpha.36",
+      "introducedVersion": "4.0.1-alpha.38",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -2048,7 +2048,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.1-alpha.36",
+      "introducedVersion": "4.0.1-alpha.38",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -2069,7 +2069,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.1-alpha.36",
+      "introducedVersion": "4.0.1-alpha.38",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -2119,7 +2119,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.1-alpha.36",
+      "introducedVersion": "4.0.1-alpha.38",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "4.0.1-alpha.36",
+  "version": "4.0.1-alpha.38",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",

package/scripts/check-project-cut-merge-queue-admission.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import {
+  ProjectCutAdmissionError,
+  qualifyProjectCut,
+  releaseFamilyQueueLease,
+} from "./project-cut-merge-queue-admission.mjs";
+
+function parseArguments(argv) {
+  const options = {};
+  const names = new Map([
+    ["--base", "base"],
+    ["--head", "head"],
+    ["--initiative-id", "initiativeId"],
+    ["--assignment-id", "assignmentId"],
+    ["--delivery-class", "deliveryClass"],
+    ["--queue-attempt", "queueAttempt"],
+    ["--admission-proof-root", "admissionProofRoot"],
+    ["--release-family-marker", "releaseFamilyMarker"],
+    ["--expected-pr-head", "expectedPullRequestHead"],
+    ["--terminal-reason", "terminalReason"],
+    ["--evidence-root", "evidenceRoot"],
+  ]);
+  for (let index = 0; index < argv.length; index += 1) {
+    const name = argv[index];
+    const key = names.get(name);
+    if (!key) throw new Error(`unknown argument: ${name}`);
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith("--"))
+      throw new Error(`${name} requires a value`);
+    if (Object.hasOwn(options, key))
+      throw new Error(`${name} was provided more than once`);
+    options[key] = value;
+    index += 1;
+  }
+  return options;
+}
+
+function markerText(path) {
+  return path === "-"
+    ? fs.readFileSync(0, "utf8")
+    : fs.readFileSync(path, "utf8");
+}
+
+function repairReceipt(error) {
+  return {
+    schema: "project.cut.merge-queue-admission/v1",
+    ok: false,
+    decision: "repair-required",
+    retryable: false,
+    compositionChanged: false,
+    reasonCodes: [error.reasonCode],
+    error: error.message,
+  };
+}
+
+export function main(argv = process.argv.slice(2)) {
+  try {
+    const options = parseArguments(argv);
+    if (options.releaseFamilyMarker) {
+      console.log(
+        JSON.stringify(
+          releaseFamilyQueueLease(
+            markerText(options.releaseFamilyMarker),
+            options,
+          ),
+        ),
+      );
+      return 0;
+    }
+    if (!options.base || !options.head)
+      throw new Error("--base and --head are required");
+    console.log(
+      JSON.stringify(qualifyProjectCut({ cwd: process.cwd(), ...options })),
+    );
+    return 0;
+  } catch (error) {
+    if (error instanceof ProjectCutAdmissionError) {
+      console.log(JSON.stringify(repairReceipt(error)));
+      return 1;
+    }
+    console.error(`project-cut admission error: ${error.message}`);
+    return 2;
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) process.exitCode = main();

package/scripts/dev-pr-auto-merge.mjs

@@ -3,7 +3,7 @@ import crypto from "node:crypto";
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { admitExistingQueueEntry, createDevPrAdmissionReceipt, qualifyAtomicQueueAdmission, readDeliveryWarrantResult, runSourceQualification, runTargetedQueueAdmission, setActiveLeaseStatus, verifyCurrentDeliveryWarrant } from "./dev-pr-delivery-warrant.mjs";
+import { admitExistingQueueEntry, createDevPrAdmissionReceipt, createPreReadinessQueueFence, qualifyAtomicQueueAdmission, readDeliveryWarrantResult, runSourceQualification, runTargetedQueueAdmission, setActiveLeaseStatus, setQueueAdmissionStatus, verifyCurrentDeliveryWarrant } from "./dev-pr-delivery-warrant.mjs";
 import { projectCutQualification } from "./dev-pr-prequeue-guard.mjs";
 const DEFAULT_BLOCK_LABELS = ["blocked", "do-not-merge", "work-in-progress"];
 const DEFAULT_ALLOWED_HEAD_PREFIXES = ["feature/", "fix/", "chore/", "docs/", "ci/", "refactor/"];
@@ -197,12 +197,6 @@ function mergeableAccepted(pr, landingMode = "direct", projectCutQualified = fal
 function rejectBaseMoveBeforeAtomicReplay(options, initialBaseSha, observedBaseSha) {
   return observedBaseSha !== initialBaseSha && options.warrantMode !== "required";
 }
-async function setQueueAdmissionStatus(client, repository, sha, context, state) {
-  if (!context) return null;
-  await client.request("POST", `/repos/${repository.owner}/${repository.repo}/statuses/${sha}`, { body: { state, context, description: state === "success" ? "Buildchain admitted this exact PR head to the merge queue" : "Buildchain rejected merge queue admission for this exact PR head" } });
-  return { context, state, sha };
-}
-
 function skip(reason, details = {}) {
   return { action: "skip", reason, ...details };
 }
@@ -790,8 +784,10 @@ export async function runDevPrAdmission(optionsInput = {}, clientInput) {
     return targetedFailure({ options, pr: {}, state: "missing", reason: "pull-request-not-found" });
   }
 
+  const readinessFence = createPreReadinessQueueFence({ client, options, sleep: delay });
   const reject = async (state, reason, readiness = { observed: hasReadyLabel(pr, options.readyLabel), established: false }) => {
     const result = targetedFailure({ options, pr, state, reason, readiness });
+    await readinessFence.finish(result);
     if (!options.dryRun) result.diagnostic = await publishAdmissionDiagnostic(client, options, result.receipt, result.receiptRoot);
     return result;
   };
@@ -803,6 +799,12 @@ export async function runDevPrAdmission(optionsInput = {}, clientInput) {
   if (pr.draft) return reject("blocked", "draft");
   if (!headPrefixAllowed(pr, options.allowedHeadPrefixes)) return reject("blocked", "head-prefix-not-allowed");
 
+  try {
+    await readinessFence.establish();
+  } catch (error) {
+    return reject("blocked", error.code || "pre-readiness-queue-fence-failed");
+  }
+
   let readiness = { observed: hasReadyLabel(pr, options.readyLabel), established: false };
   if (!readiness.observed) {
     if (options.dryRun) return reject("rejected", "missing-ready-label", readiness);
@@ -825,7 +827,7 @@ export async function runDevPrAdmission(optionsInput = {}, clientInput) {
   }
 
   if (options.qualificationOnly) {
-    return runSourceQualification({
+    const result = await runSourceQualification({
       options, pullRequest: pr, readiness, client, reject,
       evaluate: evaluatePullRequest,
       admissionState: admissionStateFor,
@@ -833,6 +835,7 @@ export async function runDevPrAdmission(optionsInput = {}, clientInput) {
       root: contentRoot,
       publishDiagnostic: publishAdmissionDiagnostic,
     });
+    return readinessFence.finish(result);
   }
 
   const initialQueue = await client.getMergeQueueState(options.targetBranch);
@@ -844,6 +847,7 @@ export async function runDevPrAdmission(optionsInput = {}, clientInput) {
   }
   const matchingEntry = initialQueue.entries.find((entry) =>
     entry.pullRequestNumber === pr.number && entry.pullRequestHeadSha === options.expectedHeadSha);
+  await readinessFence.qualifyExisting(matchingEntry);
   const existing = await admitExistingQueueEntry({
     options, pullRequest: pr, readiness, client, entry: matchingEntry, warrant,
     createReceipt: createAdmissionReceipt,
@@ -852,7 +856,7 @@ export async function runDevPrAdmission(optionsInput = {}, clientInput) {
   });
   if (existing) return existing;
 
-  return runTargetedQueueAdmission({
+  const result = await runTargetedQueueAdmission({
     options, pullRequest: pr, readiness, client, warrant,
     runController: runDevPrAutoMerge,
     admissionState: admissionStateFor,
@@ -860,6 +864,7 @@ export async function runDevPrAdmission(optionsInput = {}, clientInput) {
     root: contentRoot,
     publishDiagnostic: publishAdmissionDiagnostic,
   });
+  return readinessFence.finish(result);
 }
 
 function finalizePatrolResult(result) {
@@ -1132,6 +1137,11 @@ function cliFlag(args, name) {
 
 export function cliOptions(args = [], environment = process.env) {
   const targetPullRequestNumber = cliValue(args, "pull-request", environment.BUILDCHAIN_DEV_PR_EXPECTED_PR_NUMBER);
+  const warrantMode = cliValue(
+    args,
+    "warrant-mode",
+    environment.BUILDCHAIN_DEV_PR_WARRANT_MODE || environment.WARRANT_MODE,
+  );
   return {
     repository: cliValue(args, "repository", environment.BUILDCHAIN_DEV_PR_REPOSITORY || environment.GITHUB_REPOSITORY),
     targetBranch: cliValue(args, "branch", environment.BUILDCHAIN_DEV_PR_TARGET_BRANCH || environment.GITHUB_REF_NAME),
@@ -1141,10 +1151,14 @@ export function cliOptions(args = [], environment = process.env) {
     blockLabels: cliValue(args, "block-labels", environment.BUILDCHAIN_DEV_PR_BLOCK_LABELS),
     allowedHeadPrefixes: cliValue(args, "allowed-head-prefixes", environment.BUILDCHAIN_DEV_PR_ALLOWED_HEAD_PREFIXES),
     requiredChecks: cliValue(args, "required-checks", environment.BUILDCHAIN_DEV_PR_REQUIRED_CHECKS),
-    queueAdmissionContext: cliValue(args, "queue-admission-context", environment.BUILDCHAIN_DEV_PR_QUEUE_ADMISSION_CONTEXT),
+    queueAdmissionContext: cliValue(
+      args,
+      "queue-admission-context",
+      environment.BUILDCHAIN_DEV_PR_QUEUE_ADMISSION_CONTEXT || (warrantMode === "required" ? "Queue admission lease" : ""),
+    ),
     activeLeaseContext: cliValue(args, "active-lease-context", environment.BUILDCHAIN_DEV_PR_ACTIVE_LEASE_CONTEXT),
     diagnosticContext: cliValue(args, "diagnostic-context", environment.BUILDCHAIN_DEV_PR_DIAGNOSTIC_CONTEXT),
-    warrantMode: cliValue(args, "warrant-mode", environment.BUILDCHAIN_DEV_PR_WARRANT_MODE),
+    warrantMode,
     warrantResultPath: cliValue(args, "warrant-result", environment.BUILDCHAIN_DEV_PR_WARRANT_RESULT_PATH),
     projectCutProofPath: cliValue(args, "project-cut-proof", environment.BUILDCHAIN_DEV_PR_PROJECT_CUT_PROOF_PATH),
     sourceProofPath: cliValue(args, "source-proof", environment.BUILDCHAIN_DEV_PR_SOURCE_PROOF_PATH),

package/scripts/dev-pr-delivery-warrant.mjs

@@ -206,6 +206,50 @@ export async function setActiveLeaseStatus(client, repository, sha, context, sta
   return { context, state, sha };
 }
 
+export async function setQueueAdmissionStatus(client, repository, sha, context, state) {
+  if (!context) return null;
+  const descriptions = {
+    pending: "Buildchain is awaiting a qualified Warrant for this exact PR head",
+    success: "Buildchain admitted this exact PR head to the merge queue",
+    failure: "Buildchain rejected merge queue admission for this exact PR head",
+  };
+  await client.request("POST", `/repos/${repository.owner}/${repository.repo}/statuses/${sha}`, {
+    body: { state, context, description: descriptions[state] || descriptions.failure },
+  });
+  return { context, state, sha };
+}
+
+export function createPreReadinessQueueFence({ client, options, sleep }) {
+  let status = null;
+  const write = async (state) => {
+    status = await setQueueAdmissionStatus(client, options.repository, options.expectedHeadSha, options.queueAdmissionContext, state);
+    return status;
+  };
+  return {
+    async establish() {
+      if (options.dryRun || options.warrantMode !== "required") return null;
+      if (!options.queueAdmissionContext) mismatch("queue-admission-context-required-before-readiness");
+      await write("pending");
+      for (let attempt = 1; attempt <= Math.max(1, options.pollMergeableAttempts); attempt += 1) {
+        const checks = await client.listCommitChecks(options.expectedHeadSha);
+        const readback = (checks?.statuses || []).find((entry) => entry.context === options.queueAdmissionContext);
+        if (readback?.state === "pending") return { ...status, readbackAttempts: attempt };
+        if (attempt < options.pollMergeableAttempts) await sleep(options.pollMergeableDelayMs);
+      }
+      await write("failure");
+      mismatch("pre-readiness-queue-fence-readback-mismatch");
+    },
+    async qualifyExisting(entry) {
+      if (entry && status?.state === "pending") await write("success");
+    },
+    async finish(result) {
+      const controllerFailed = result.controller?.evaluated?.some((entry) => entry.queueAdmissionStatus?.state === "failure");
+      if (!result.ok && status?.state === "pending" && !controllerFailed) await write("failure");
+      return result;
+    },
+  };
+}
+
 async function readBackAdmissionStatuses(client, options, expectedHeadSha, sleep) {
   let last = { queueAdmission: null, activeLease: null };
   const attempts = Math.max(1, options.pollMergeableAttempts);

package/scripts/project-cut-merge-queue-admission.mjs

@@ -0,0 +1,394 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const GIT_OID = /^[0-9a-f]{40}$/u;
+const CONTENT_ROOT = /^sha256:[0-9a-f]{64}$/u;
+const FAMILY_ID = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$/u;
+const FAMILY_MARKER =
+  /<!-- kungfu-family-queue-lease:v1 ([A-Za-z0-9_-]+) -->/gu;
+const FAMILY_LEASE_SCHEMA = "kungfu.project-cut.family-queue-lease/v1";
+
+export class ProjectCutAdmissionError extends Error {
+  constructor(reasonCode, message) {
+    super(message);
+    this.name = "ProjectCutAdmissionError";
+    this.reasonCode = reasonCode;
+  }
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value)
+        .filter(([, entry]) => entry !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entry]) => [key, stableValue(entry)]),
+    );
+  }
+  return value;
+}
+
+function canonicalBytes(value) {
+  return Buffer.from(`${JSON.stringify(stableValue(value))}\n`, "utf8");
+}
+
+function contentRoot(value) {
+  return `sha256:${crypto.createHash("sha256").update(canonicalBytes(value)).digest("hex")}`;
+}
+
+function exactRoot(value, label) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (!CONTENT_ROOT.test(normalized))
+    throw new Error(`${label} must be an exact SHA-256 root`);
+  return normalized;
+}
+
+function familyId(value, label) {
+  const normalized = String(value || "").trim();
+  if (!FAMILY_ID.test(normalized)) throw new Error(`${label} is invalid`);
+  return normalized;
+}
+
+function git(
+  cwd,
+  args,
+  {
+    env = {},
+    input = undefined,
+    encoding = "utf8",
+    reason = "git-failed",
+  } = {},
+) {
+  const result = spawnSync("git", args, {
+    cwd,
+    env: { ...process.env, ...env },
+    input,
+    encoding,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  if (result.status !== 0) {
+    const detail = String(result.stderr || result.stdout || "").trim();
+    throw new ProjectCutAdmissionError(
+      reason,
+      `git ${args.join(" ")} failed${detail ? `: ${detail}` : ""}`,
+    );
+  }
+  return encoding === null ? result.stdout : String(result.stdout || "").trim();
+}
+
+function resolveCommit(cwd, revision, label) {
+  const oid = git(cwd, ["rev-parse", "--verify", `${revision}^{commit}`], {
+    reason: `${label}-unresolved`,
+  });
+  if (!GIT_OID.test(oid))
+    throw new ProjectCutAdmissionError(
+      `${label}-unresolved`,
+      `${label} is not an exact commit`,
+    );
+  return oid;
+}
+
+function linearSourceCommits(cwd, fork, head) {
+  const commits = git(
+    cwd,
+    ["rev-list", "--reverse", "--topo-order", `${fork}..${head}`],
+    {
+      reason: "source-history-unreadable",
+    },
+  )
+    .split(/\s+/u)
+    .filter(Boolean);
+  if (commits.length === 0)
+    throw new ProjectCutAdmissionError(
+      "empty-source-range",
+      "source range is empty",
+    );
+  let expectedParent = fork;
+  for (const commit of commits) {
+    const [observed, ...parents] = git(
+      cwd,
+      ["rev-list", "--parents", "-n", "1", commit],
+      {
+        reason: "source-history-unreadable",
+      },
+    ).split(/\s+/u);
+    if (
+      observed !== commit ||
+      parents.length !== 1 ||
+      parents[0] !== expectedParent
+    ) {
+      throw new ProjectCutAdmissionError(
+        "nonlinear-source-range",
+        "source range is not one immutable linear patch series",
+      );
+    }
+    expectedParent = commit;
+  }
+  return commits;
+}
+
+function patchId(cwd, patch) {
+  const output = git(cwd, ["patch-id", "--stable"], {
+    input: patch,
+    encoding: "utf8",
+    reason: "patch-id-failed",
+  });
+  const id = output.split(/\s+/u)[0] || "";
+  if (!GIT_OID.test(id))
+    throw new ProjectCutAdmissionError(
+      "patch-id-failed",
+      "patch has no stable identity",
+    );
+  return id;
+}
+
+function virtualCommitOid(cwd, tree, base, head) {
+  const body = [
+    `tree ${tree}`,
+    `parent ${base}`,
+    "author Buildchain Project Cut <project-cut@kungfu.tech> 0 +0000",
+    "committer Buildchain Project Cut <project-cut@kungfu.tech> 0 +0000",
+    "",
+    `Replay ${head} onto ${base}`,
+    "",
+  ].join("\n");
+  return git(cwd, ["hash-object", "-t", "commit", "--stdin"], {
+    input: body,
+    reason: "candidate-commit-hash-failed",
+  });
+}
+
+function replayProjectCut(cwd, base, head) {
+  const fork = git(cwd, ["merge-base", base, head], {
+    reason: "no-common-fork",
+  });
+  if (!GIT_OID.test(fork))
+    throw new ProjectCutAdmissionError(
+      "no-common-fork",
+      "base and head have no exact fork",
+    );
+  const commits = linearSourceCommits(cwd, fork, head);
+  const temporary = fs.mkdtempSync(
+    path.join(os.tmpdir(), "buildchain-project-cut-"),
+  );
+  const indexPath = path.join(temporary, "index");
+  const indexEnvironment = { GIT_INDEX_FILE: indexPath };
+  try {
+    git(cwd, ["read-tree", base], {
+      env: indexEnvironment,
+      reason: "base-tree-unreadable",
+    });
+    const sourcePatch = git(
+      cwd,
+      ["diff", "--binary", "--full-index", "--no-ext-diff", fork, head],
+      {
+        encoding: null,
+        reason: "source-patch-unreadable",
+      },
+    );
+    git(cwd, ["apply", "--cached", "--3way", "--whitespace=nowarn", "-"], {
+      env: indexEnvironment,
+      input: sourcePatch,
+      encoding: "utf8",
+      reason: "project-cut-conflict",
+    });
+    const candidateTreeOid = git(cwd, ["write-tree"], {
+      env: indexEnvironment,
+      reason: "candidate-tree-unreadable",
+    });
+    const replayPatch = git(
+      cwd,
+      ["diff", "--cached", "--binary", "--full-index", "--no-ext-diff", base],
+      {
+        env: indexEnvironment,
+        encoding: null,
+        reason: "replay-patch-unreadable",
+      },
+    );
+    const sourceNames = git(
+      cwd,
+      ["diff", "--name-status", "--no-renames", fork, head],
+      {
+        reason: "source-paths-unreadable",
+      },
+    );
+    const replayNames = git(
+      cwd,
+      ["diff", "--cached", "--name-status", "--no-renames", base],
+      {
+        env: indexEnvironment,
+        reason: "replay-paths-unreadable",
+      },
+    );
+    if (
+      patchId(cwd, sourcePatch) !== patchId(cwd, replayPatch) ||
+      sourceNames !== replayNames
+    ) {
+      throw new ProjectCutAdmissionError(
+        "composition-drift",
+        "latest-base replay changes the immutable source composition",
+      );
+    }
+    return {
+      baseCommitOid: base,
+      headCommitOid: head,
+      forkCommitOid: fork,
+      candidateCommitOid: virtualCommitOid(cwd, candidateTreeOid, base, head),
+      candidateTreeOid,
+      replayedCommitCount: commits.length,
+    };
+  } finally {
+    fs.rmSync(temporary, { recursive: true, force: true });
+  }
+}
+
+function encodeMarker(payload) {
+  return canonicalBytes(payload)
+    .toString("base64")
+    .replace(/\+/gu, "-")
+    .replace(/\//gu, "_")
+    .replace(/=+$/gu, "");
+}
+
+function decodeMarker(token) {
+  const padded = `${token}${"=".repeat((4 - (token.length % 4)) % 4)}`
+    .replace(/-/gu, "+")
+    .replace(/_/gu, "/");
+  return JSON.parse(Buffer.from(padded, "base64").toString("utf8"));
+}
+
+function familyLease(input, replay) {
+  const binding = {
+    schema: FAMILY_LEASE_SCHEMA,
+    state: "active",
+    initiativeId: familyId(input.initiativeId, "initiativeId"),
+    assignmentId: familyId(input.assignmentId, "assignmentId"),
+    deliveryClass: familyId(input.deliveryClass, "deliveryClass"),
+    admissionProofRoot: exactRoot(
+      input.admissionProofRoot,
+      "admissionProofRoot",
+    ),
+    queueAttempt: String(input.queueAttempt || "").trim(),
+    pullRequestHead: replay.headCommitOid,
+    baseCommitOid: replay.baseCommitOid,
+    forkCommitOid: replay.forkCommitOid,
+    candidateTreeOid: replay.candidateTreeOid,
+  };
+  const expectedAttempt = `${replay.headCommitOid}@${replay.baseCommitOid}`;
+  if (binding.queueAttempt !== expectedAttempt) {
+    throw new ProjectCutAdmissionError(
+      "queue-attempt-drift",
+      `queueAttempt must equal ${expectedAttempt}`,
+    );
+  }
+  const bindingRoot = contentRoot(binding);
+  const statusContext = `Queue family lease/${bindingRoot.slice(7, 23)}`;
+  const payload = { ...binding, bindingRoot, statusContext };
+  const leaseRoot = contentRoot(payload);
+  const sealed = { ...payload, leaseRoot };
+  return {
+    marker: `<!-- kungfu-family-queue-lease:v1 ${encodeMarker(sealed)} -->`,
+    leaseRoot,
+    statusContext,
+    pullRequestHead: replay.headCommitOid,
+  };
+}
+
+export function parseFamilyQueueLeaseMarker(text) {
+  const matches = [...String(text || "").matchAll(FAMILY_MARKER)];
+  if (matches.length !== 1) return null;
+  try {
+    const payload = decodeMarker(matches[0][1]);
+    const { leaseRoot, bindingRoot, statusContext, ...binding } = payload;
+    if (payload.schema !== FAMILY_LEASE_SCHEMA || payload.state !== "active")
+      return null;
+    if (contentRoot(binding) !== bindingRoot) return null;
+    if (statusContext !== `Queue family lease/${bindingRoot.slice(7, 23)}`)
+      return null;
+    if (contentRoot({ ...binding, bindingRoot, statusContext }) !== leaseRoot)
+      return null;
+    if (encodeMarker(payload) !== matches[0][1]) return null;
+    exactRoot(leaseRoot, "leaseRoot");
+    exactRoot(payload.admissionProofRoot, "admissionProofRoot");
+    for (const field of [
+      "pullRequestHead",
+      "baseCommitOid",
+      "forkCommitOid",
+      "candidateTreeOid",
+    ]) {
+      if (!GIT_OID.test(String(payload[field] || ""))) return null;
+    }
+    return payload;
+  } catch {
+    return null;
+  }
+}
+
+export function releaseFamilyQueueLease(markerText, input = {}) {
+  const lease = parseFamilyQueueLeaseMarker(markerText);
+  if (!lease) throw new Error("family queue lease marker is invalid");
+  const expectedHead = String(input.expectedPullRequestHead || "")
+    .trim()
+    .toLowerCase();
+  if (!GIT_OID.test(expectedHead) || expectedHead !== lease.pullRequestHead) {
+    throw new Error("family queue lease pull request head drifted");
+  }
+  const terminalReason = String(input.terminalReason || "").trim();
+  if (!["controller-failed", "merged"].includes(terminalReason))
+    throw new Error("terminalReason is invalid");
+  const evidenceRoot = input.evidenceRoot
+    ? exactRoot(input.evidenceRoot, "evidenceRoot")
+    : null;
+  if (terminalReason === "merged" && !evidenceRoot)
+    throw new Error("merged family lease requires evidenceRoot");
+  const receipt = {
+    schema: "project.cut.family-queue-release/v1",
+    state: "released",
+    leaseRoot: lease.leaseRoot,
+    pullRequestHead: lease.pullRequestHead,
+    terminalReason,
+    evidenceRoot,
+  };
+  return { ...receipt, releaseRoot: contentRoot(receipt) };
+}
+
+export function qualifyProjectCut(input = {}) {
+  const cwd = path.resolve(input.cwd || process.cwd());
+  const base = resolveCommit(cwd, input.base, "base");
+  const head = resolveCommit(cwd, input.head, "head");
+  const replay = replayProjectCut(cwd, base, head);
+  const familyInputs = [
+    input.initiativeId,
+    input.assignmentId,
+    input.deliveryClass,
+    input.queueAttempt,
+    input.admissionProofRoot,
+  ];
+  const familyCount = familyInputs.filter((value) =>
+    String(value || "").trim(),
+  ).length;
+  if (familyCount !== 0 && familyCount !== familyInputs.length) {
+    throw new ProjectCutAdmissionError(
+      "partial-family-binding",
+      "family admission inputs must be all present or all absent",
+    );
+  }
+  return {
+    schema: "project.cut.merge-queue-admission/v1",
+    ok: true,
+    decision: "qualified",
+    retryable: false,
+    compositionChanged: false,
+    reasonCodes: [],
+    ...replay,
+    ...(familyCount === familyInputs.length
+      ? { familyLease: familyLease(input, replay) }
+      : {}),
+  };
+}