@kungfu-tech/buildchain 4.0.1-alpha.9 → 4.0.1

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",
+      },
+    );
+    const emptySourcePatch = sourcePatch.length === 0;
+    if (emptySourcePatch && commits.length !== 1)
+      throw new ProjectCutAdmissionError("empty-source-composition", "an empty source composition must be exactly one linear commit");
+    if (!emptySourcePatch) 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",
+      },
+    );
+    const compositionDrifted = emptySourcePatch ? replayPatch.length !== 0 ||
+      sourceNames !== "" || replayNames !== "" : patchId(cwd, sourcePatch) !==
+      patchId(cwd, replayPatch) || sourceNames !== replayNames;
+    if (compositionDrifted) {
+      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) }
+      : {}),
+  };
+}

package/scripts/promotion-routing-evidence.mjs

@@ -1,9 +1,7 @@
 #!/usr/bin/env node
-
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-
 function createPromotionRoutingEvidence({
   env = process.env,
   cwd = process.cwd(),
@@ -55,13 +53,45 @@ function createPromotionRoutingEvidence({
   }
   return { routing, routingPath, candidatePath };
 }
-
+function bundlePromotionControllerEvidence({
+  env = process.env,
+  cwd = process.cwd(),
+} = {}) {
+  const finalizationNeeded = env.FINALIZATION_NEEDED === "true";
+  const files = [
+    [env.RELEASE_CANDIDATE_PASSPORT, "release-candidate-passport.json"],
+    [env.PUBLISH_EVIDENCE, "publish-evidence.json"],
+    ...(!finalizationNeeded
+      ? [[env.RELEASE_PASSPORT, "release-passport.json"]]
+      : []),
+    ...(env.PUBLICATION_COMMIT_ENABLED === "true" && !finalizationNeeded
+      ? [[env.PUBLICATION_COMMIT_EVIDENCE, "publication-commit-evidence.json"]]
+      : []),
+    ...(!finalizationNeeded ? [
+      [env.RELEASE_ACTIVATION_RECEIPTS, "release-activation-receipt-set.json"],
+      [env.RELEASED_PRODUCT_EVIDENCE, "released-product-evidence.json"],
+      [env.RELEASE_PROPAGATION_CAPTURE, "release-propagation-capture.json"],
+    ].filter(([source]) => source) : []),
+  ];
+  const outputDir = path.join(cwd, ".buildchain/controller/promotion-evidence");
+  fs.mkdirSync(outputDir, { recursive: true });
+  for (const [source, name] of files) {
+    if (!source || !fs.existsSync(path.resolve(cwd, source)))
+      throw new Error(`promotion controller evidence is missing: ${source || name}`);
+    fs.copyFileSync(path.resolve(cwd, source), path.join(outputDir, name));
+  }
+  return { files: files.map(([, name]) => name), outputDir };
+}
 if (
   process.argv[1] &&
   import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href
 ) {
   try {
-    createPromotionRoutingEvidence();
+    if (process.argv[2] === "bundle-controller-evidence") {
+      bundlePromotionControllerEvidence();
+    } else {
+      createPromotionRoutingEvidence();
+    }
   } catch (error) {
     console.error(
       `promotion routing evidence failed: ${error instanceof Error ? error.message : String(error)}`,
@@ -69,5 +99,4 @@ if (
     process.exitCode = 1;
   }
 }
-
-export { createPromotionRoutingEvidence };
+export { bundlePromotionControllerEvidence, createPromotionRoutingEvidence };

package/scripts/release-candidate-resolver.mjs

@@ -9,6 +9,8 @@ import { pipeline } from "node:stream/promises";
 import { pathToFileURL } from "node:url";
 import { createResolvedPublicationSealedBundle } from "./publication-candidate-sealer.mjs";
 import { writeGitHubOutputs } from "./build-contract-core.mjs";
+import { v4ContentRoot } from "../packages/core/v4-canonical-contracts.js";
+import { v4PublicationQualificationRoot, validateV4PublicationQualificationReceipt } from "../packages/core/v4-publication-qualification.js";
 
 const DEFAULT_WORKFLOW_FILE = "build-surface-fixture.yml";
 
@@ -434,6 +436,42 @@ function findDownloadedFile(root, filename) {
   return "";
 }
 
+function resolveV4PublicationEvidence(passportDir, passport, outputPath) {
+  const stageCapsulesPath = findDownloadedFile(passportDir, "release-candidate-stage-capsules.json");
+  const publicationQualificationPath = findDownloadedFile(passportDir, "release-candidate-publication-qualification.json");
+  if (!passport.consumerPolicy?.receiptRoot) {
+    return {
+      paths: {
+        stageCapsules: stageCapsulesPath ? outputPath(stageCapsulesPath) : "",
+        publicationQualification: publicationQualificationPath ? outputPath(publicationQualificationPath) : "",
+      },
+      publicationQualificationRoot: "",
+    };
+  }
+  if (!stageCapsulesPath || !publicationQualificationPath) {
+    throw new Error("v4 release candidate is missing Stage Capsules or publication qualification receipt");
+  }
+  const stageCapsules = JSON.parse(fs.readFileSync(stageCapsulesPath, "utf8"));
+  const qualification = JSON.parse(fs.readFileSync(publicationQualificationPath, "utf8"));
+  validateV4PublicationQualificationReceipt(qualification, {
+    repository: passport.repository,
+    candidateRoot: `sha256:${passport.candidateHash}`,
+    sourceSha: passport.source.headSha,
+    sourceRoot: v4ContentRoot("candidate-identity", passport.source),
+    artifactRoot: v4PublicationQualificationRoot(stageCapsules.capsules.map(({ publicationArtifact }) => publicationArtifact)),
+    policyDigest: passport.consumerPolicy.receiptRoot,
+  });
+  if (stageCapsules.publicationQualificationRoot !== qualification.receiptRoot) throw new Error("Stage Capsules do not bind the publication qualification receipt");
+  if (stageCapsules.capsules.some(({ capsule }) => capsule.identity.qualificationRoot !== qualification.receiptRoot)) throw new Error("a Stage Capsule does not bind the publication qualification receipt");
+  return {
+    paths: {
+      stageCapsules: outputPath(stageCapsulesPath),
+      publicationQualification: outputPath(publicationQualificationPath),
+    },
+    publicationQualificationRoot: qualification.receiptRoot,
+  };
+}
+
 export async function resolveReleaseCandidateArtifacts({
   repository,
   targetRef,
@@ -667,6 +705,7 @@ export async function resolveReleaseCandidateArtifacts({
     throw new Error("downloaded release-candidate artifacts did not contain release-candidate-passport.json and build-summary.json");
   }
   const passport = JSON.parse(fs.readFileSync(passportPath, "utf8"));
+  const v4Publication = resolveV4PublicationEvidence(passportDir, passport, outputPath);
   const platformManifestPaths = findDownloadedFiles(payloadDir, "manifest.json");
   const githubArtifactAttestationPolicyPaths = findDownloadedFiles(
     payloadDir,
@@ -722,6 +761,7 @@ export async function resolveReleaseCandidateArtifacts({
     paths: {
       passport: outputPath(passportPath),
       buildSummary: outputPath(buildSummaryPath),
+      ...v4Publication.paths,
       payloads: outputPath(payloadDir),
       platformManifests: platformManifestPaths.map(outputPath),
       githubArtifactAttestationPolicies: githubArtifactAttestationPolicyPaths.map(outputPath),
@@ -738,6 +778,7 @@ export async function resolveReleaseCandidateArtifacts({
     githubArtifactAttestationPolicyCount: githubArtifactAttestationPolicyPaths.length,
     npmTarballCount: npmTarballPaths.length,
     publishRequiredArtifacts: generatedRequiredArtifacts,
+    publicationQualificationRoot: v4Publication.publicationQualificationRoot,
   };
 }
 
@@ -766,6 +807,9 @@ export async function resolveReleaseCandidateArtifactsCli() {
     "promote-only-release-candidate": String(result.enabled === true),
     "release-candidate-passport-path": result.paths?.passport || "",
     "release-candidate-build-summary-path": result.paths?.buildSummary || "",
+    "release-candidate-stage-capsules-path": result.paths?.stageCapsules || "",
+    "release-candidate-publication-qualification-path": result.paths?.publicationQualification || "",
+    "release-candidate-publication-qualification-root": result.publicationQualificationRoot || "",
     "release-candidate-version": result.version || "",
     "release-candidate-source-sha": result.artifacts?.sourceSha || "",
     "release-candidate-artifact": result.artifacts?.passport || "",

package/scripts/release-line-policy.mjs

@@ -47,16 +47,27 @@ export function parseVersionStateRef(ref) {
 
 export function parseReleaseLineRecoveryRef(ref) {
   const normalizedRef = normalizeRef(ref);
-  const match = normalizedRef.match(/^fix\/release-line-v(\d+)-v(\d+\.\d+)-[0-9A-Za-z._-]+$/);
+  const match = normalizedRef.match(/^fix\/(alpha|release)-line-v(\d+)-v(\d+\.\d+)-[0-9A-Za-z._-]+$/);
   if (!match) return undefined;
   return {
-    major: Number(match[1]),
-    loose: Number(match[2]),
-    normalizedRef: `release/v${match[1]}/v${match[2]}`,
-    lineSuffix: `/v${match[1]}/v${match[2]}`,
+    channel: match[1],
+    major: Number(match[2]),
+    loose: Number(match[3]),
+    normalizedRef: `${match[1]}/v${match[2]}/v${match[3]}`,
   };
 }
 
+function getRecoveryBumpKeyword({ target, baseRef, baseChannel, version, looseVersionNumber, headRef }) {
+  if (!target) return "";
+  if (baseChannel !== target.channel || target.normalizedRef !== normalizeRef(baseRef)) {
+    throw new Error(`Versions not match for head/base refs: ${headRef} -> ${baseRef}`);
+  }
+  if (target.major !== version.major || target.loose !== looseVersionNumber) {
+    throw new Error(`The version of head ref ${headRef} does not match current ${version.version}`);
+  }
+  return baseChannel === "release" ? "patch" : "prerelease";
+}
+
 export function parsePublishGateChannelRef(ref) {
   const normalizedRef = normalizeRef(ref);
   const match = normalizedRef.match(/^publish-gate\/(alpha|release)\/(v(\d+)\/v(\d+\.\d+))\/[^/]+$/);
@@ -131,6 +142,14 @@ export function getBumpKeyword({ cwd = process.cwd(), headRef, baseRef, loose =
   const authorityTarget = parseAuthorityRef(baseRef);
   const headChannel = getChannel(headRef);
   const baseChannel = getChannel(baseRef);
+  const recoveryKeyword = getRecoveryBumpKeyword({
+    target: releaseLineRecoveryTarget,
+    baseRef,
+    baseChannel,
+    version,
+    looseVersionNumber,
+    headRef,
+  });
   const key = `${headChannel}->${baseChannel}`;
   const keywords = {
     "dev->alpha": "prerelease",
@@ -157,16 +176,7 @@ export function getBumpKeyword({ cwd = process.cwd(), headRef, baseRef, loose =
     return "none";
   }
 
-  if (releaseLineRecoveryTarget) {
-    if (baseChannel !== "release" || releaseLineRecoveryTarget.normalizedRef !== normalizeRef(baseRef)) {
-      throw new Error(`Versions not match for head/base refs: ${headRef} -> ${baseRef}`);
-    }
-    const mismatchMsg = `The version of head ref ${headRef} does not match current ${version.version}`;
-    if (releaseLineRecoveryTarget.major !== version.major || releaseLineRecoveryTarget.loose !== looseVersionNumber) {
-      throw new Error(mismatchMsg);
-    }
-    return "patch";
-  }
+  if (recoveryKeyword) return recoveryKeyword;
 
   if (publishGateTarget) {
     if (publishGateTarget.channel !== baseChannel || publishGateTarget.normalizedRef !== normalizeRef(baseRef)) {

package/scripts/release-tail.mjs

@@ -42,7 +42,8 @@ export async function runReleaseTailCli(args = process.argv.slice(2)) {
   const [mode = "status", ...options] = args;
   if (mode === "rehearse") {
     const capsulePath = flag(options, "capsule");
-    const candidateRoot = flag(options, "candidate-root");
+    const candidateRoot =
+      flag(options, "candidate-root") || flag(options, "capsule-root");
     const statePath = flag(options, "state");
     const evidencePath = flag(options, "evidence");
     for (const [name, value] of Object.entries({
@@ -59,6 +60,22 @@ export async function runReleaseTailCli(args = process.argv.slice(2)) {
         "local rehearsal --mode must be simulate or replay; authorized provider rehearsal uses the reusable workflow",
       );
     try {
+      const environmentInput = flag(options, "environment-json");
+      const environment = environmentInput
+        ? readJson(environmentInput, "--environment-json")
+        : {};
+      if (
+        !environment ||
+        typeof environment !== "object" ||
+        Array.isArray(environment) ||
+        Object.keys(environment).length > 0
+      ) {
+        const error = new Error(
+          "--environment-json must be an empty object; v4 binds every semantic input into the source-bound capsule",
+        );
+        error.code = "ambient-environment-forbidden";
+        throw error;
+      }
       const result = await executeV4PublicationRehearsal({
         capsule: readJson(capsulePath, "--capsule"),
         candidateRoot,
@@ -143,7 +160,7 @@ export async function runReleaseTailCli(args = process.argv.slice(2)) {
     return report;
   }
   throw new Error(
-    "usage: buildchain release-tail <plan|init|status|verify|compat|rehearse> [--declaration <json-or-path>] [--capsule <absolute-path>] [--candidate-root <absolute-path>] [--mode <simulate|replay>] [--state <absolute-path>] [--evidence <absolute-path>] [--hooks-json <json-or-path>] [--output <path>]",
+    "usage: buildchain release-tail <plan|init|status|verify|compat|rehearse> [--declaration <json-or-path>] [--capsule <absolute-path>] [--candidate-root <absolute-path>|--capsule-root <absolute-path>] [--environment-json <empty-json-or-path>] [--mode <simulate|replay>] [--state <absolute-path>] [--evidence <absolute-path>] [--hooks-json <json-or-path>] [--output <path>]",
   );
 }