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

package/packages/core/publication-control-plane-audit.js

@@ -72,77 +72,72 @@ function fact(id, pass, observed) {
   };
 }
 
-export function evaluatePublicationControlPlaneSnapshot({
+function evaluatePublisherPolicy({
+  publisher,
+  publisherMode,
+  packageName,
   repository,
   workflowPath,
-  publisherWorkflowPath = workflowPath,
+  publisherWorkflowPath,
+  workflowFilename,
   environment,
-  branch,
-  packageName,
-  publisherMode = "npm-trusted-publisher",
-  requiredStatusCheck = "check",
-  snapshot,
-  observedAt,
-  expiresAt,
-} = {}) {
-  const workflowFilename = String(publisherWorkflowPath || "").split("/").pop();
-  const providerEnvironment = environment === "none" ? "" : environment;
-  const actions = snapshot?.actions || {};
-  const branchPolicy = snapshot?.branch || {};
-  const environmentPolicy = snapshot?.environment || {};
-  const oidc = snapshot?.oidc || {};
-  const publisher = snapshot?.publisher || {};
-  const runner = snapshot?.runner || {};
-  const npmIdentityPass = publisher.packageName === packageName &&
-    publisher.provider === "github" &&
-    publisher.repository === repository &&
-    publisher.workflowFilename === workflowFilename &&
-    publisher.environment === providerEnvironment &&
-    publisher.longLivedWorkflowCredentialPresent === false;
-  const publisherPass = publisherMode === "npm-trusted-publisher"
-    ? npmIdentityPass && (
+  providerEnvironment,
+}) {
+  if (publisherMode === "npm-trusted-publisher") {
+    const identityPass = publisher.packageName === packageName &&
+      publisher.provider === "github" &&
+      publisher.repository === repository &&
+      publisher.workflowFilename === workflowFilename &&
+      publisher.environment === providerEnvironment &&
+      publisher.longLivedWorkflowCredentialPresent === false;
+    return identityPass && (
       (publisher.enforcement === "audited-control-plane" && publisher.allowPublish === true) ||
       (publisher.enforcement === "provider-at-transaction" &&
         publisher.authorizationDeferred === true &&
         publisher.configurationRead === false)
-    )
-    : publisherMode === "github-token"
-      ? publisher.provider === "github-token" &&
-        publisher.repository === repository &&
-        publisher.workflowPath === workflowPath &&
-        publisher.permissionScoped === true &&
-        publisher.longLivedWorkflowCredentialPresent === false
-      : publisherMode === "oidc-role"
-        ? publisher.provider !== "" &&
-          publisher.repository === repository &&
-          publisher.workflowPath === publisherWorkflowPath &&
-          publisher.environment === environment &&
-          publisher.trustQualifying === true &&
-          /^[0-9a-f]{64}$/i.test(String(publisher.roleDigest || "").replace(/^sha256:/, "")) &&
-          publisher.longLivedWorkflowCredentialPresent === false
-        : false;
-  const credentialIsolationPass = publisherMode === "github-token"
+    );
+  }
+  if (publisherMode === "github-token") {
+    return publisher.provider === "github-token" &&
+      publisher.repository === repository &&
+      publisher.workflowPath === workflowPath &&
+      publisher.permissionScoped === true &&
+      publisher.longLivedWorkflowCredentialPresent === false;
+  }
+  if (publisherMode !== "oidc-role") return false;
+  return publisher.provider !== "" &&
+    publisher.repository === repository &&
+    publisher.workflowPath === publisherWorkflowPath &&
+    publisher.environment === environment &&
+    publisher.trustQualifying === true &&
+    /^[0-9a-f]{64}$/i.test(String(publisher.roleDigest || "").replace(/^sha256:/, "")) &&
+    publisher.longLivedWorkflowCredentialPresent === false;
+}
+
+function evaluateCredentialIsolation({ oidc, publisherMode, publisherWorkflowPath, providerEnvironment }) {
+  return publisherMode === "github-token"
     ? oidc.githubTokenJobScoped === true && oidc.longLivedCredentialPresent === false
     : oidc.workflowPath === publisherWorkflowPath &&
       oidc.environment === providerEnvironment &&
       oidc.idTokenJobScoped === true &&
       oidc.longLivedCredentialPresent === false;
-  const configuredBranchPolicyPass = branchPolicy.ref === branch &&
-    branchPolicy.strict === true &&
-    Number(branchPolicy.requiredApprovals || 0) >= 1 &&
-    branchPolicy.requireConversationResolution === true &&
-    branchPolicy.enforceAdmins === true;
-  const declaredRequiredStatusCheck = branchPolicy.declaredRequiredStatusCheck || branchPolicy.requiredStatusCheck;
-  const resolvedRequiredStatusCheck = branchPolicy.requiredStatusCheck;
-  const requiredStatusCheckBindingPass = declaredRequiredStatusCheck === requiredStatusCheck && (
-    resolvedRequiredStatusCheck === declaredRequiredStatusCheck ||
-    (
-      resolvedRequiredStatusCheck.startsWith(`${declaredRequiredStatusCheck} / `) &&
-      branchPolicy.requiredStatusCheckMatchCount === 1
-    )
-  );
+}
+
+function requiredStatusCheckBinding(branchPolicy, requiredStatusCheck) {
+  const declared = branchPolicy.declaredRequiredStatusCheck || branchPolicy.requiredStatusCheck;
+  const resolved = branchPolicy.requiredStatusCheck;
+  return {
+    resolved,
+    pass: declared === requiredStatusCheck && (
+      resolved === declared ||
+      (resolved.startsWith(`${declared} / `) && branchPolicy.requiredStatusCheckMatchCount === 1)
+    ),
+  };
+}
+
+function sourceAuthorizationPass(branchPolicy) {
   const authorizationSha = branchPolicy.authorizationSha || branchPolicy.sourceSha;
-  const sourceAuthorizationPass = branchPolicy.sourceSha === authorizationSha || (
+  return branchPolicy.sourceSha === authorizationSha || (
     branchPolicy.releaseReconciliation?.qualifying === true &&
     branchPolicy.releaseReconciliation.parentSha === authorizationSha &&
     /^\d+\.\d+\.\d+$/.test(String(branchPolicy.releaseReconciliation.version || "")) &&
@@ -150,74 +145,103 @@ export function evaluatePublicationControlPlaneSnapshot({
     Array.isArray(branchPolicy.releaseReconciliation.changedPaths) &&
     branchPolicy.releaseReconciliation.changedPaths.length > 0
   );
-  const sourceBranchBindingPass = branchPolicy.sourceSha === branchPolicy.headSha ||
-    branchPolicy.sourceContainedInBranch === true;
-  const providerTransactionBranchPass = branchPolicy.ref === branch &&
+}
+
+function evaluateConfiguredBranchPolicy(branchPolicy, branch) {
+  return branchPolicy.ref === branch &&
+    branchPolicy.strict === true &&
+    Number(branchPolicy.requiredApprovals || 0) >= 1 &&
+    branchPolicy.requireConversationResolution === true &&
+    branchPolicy.enforceAdmins === true;
+}
+
+function evaluateProviderBranchPolicy(branchPolicy, branch, requiredCheck) {
+  return branchPolicy.ref === branch &&
     branchPolicy.policyMode === "provider-enforced-transaction" &&
     branchPolicy.protected === true &&
     branchPolicy.enforcementLevel === "everyone" &&
     Array.isArray(branchPolicy.requiredStatusChecks) &&
-    requiredStatusCheckBindingPass &&
-    branchPolicy.requiredStatusChecks.includes(resolvedRequiredStatusCheck) &&
+    requiredCheck.pass &&
+    branchPolicy.requiredStatusChecks.includes(requiredCheck.resolved) &&
     branchPolicy.requiredCheckPassed === true &&
     /^[0-9a-f]{40}$/i.test(String(branchPolicy.requiredCheckSha || "")) &&
-    branchPolicy.requiredCheckSha === branchPolicy.pullRequestHeadSha &&
-    sourceBranchBindingPass &&
-    sourceAuthorizationPass &&
+    branchPolicy.requiredCheckSha === branchPolicy.pullRequestHeadSha;
+}
+
+function evaluateProviderPullRequest(branchPolicy, branch, repository) {
+  return (branchPolicy.sourceSha === branchPolicy.headSha || branchPolicy.sourceContainedInBranch === true) &&
+    sourceAuthorizationPass(branchPolicy) &&
     branchPolicy.mergedPullRequest === true &&
     branchPolicy.baseRef === branch &&
     branchPolicy.headRepository === repository &&
     Number(branchPolicy.approvalCount || 0) >= 1 &&
     branchPolicy.independentApproval === true;
-  const facts = [
-    fact(
-      "actions-policy",
-      actions.defaultWorkflowPermissions === "read" && actions.canApprovePullRequestReviews === false,
-      actions,
-    ),
-    fact(
-      "branch-policy",
-      configuredBranchPolicyPass || providerTransactionBranchPass,
-      branchPolicy,
-    ),
-    fact(
-      "environment-policy",
-      environment === "none"
-        ? environmentPolicy.declared === false && environmentPolicy.exists === false
-        : environmentPolicy.name === environment &&
-          environmentPolicy.declared === true &&
-          environmentPolicy.exists === true &&
-          environmentPolicy.protected === true &&
-          environmentPolicy.branchAuthorized === true &&
-          (environmentPolicy.reviewRequired !== true || environmentPolicy.preventSelfReview === true),
-      environmentPolicy,
-    ),
-    fact(
-      "oidc-policy",
-      credentialIsolationPass,
-      oidc,
-    ),
-    fact(
-      "publisher-policy",
-      publisherPass,
-      publisher,
-    ),
-    fact(
-      "runner-policy",
-      runner.class === "ephemeral" &&
-        runner.label === "ubuntu-24.04" &&
-        runner.githubHosted === true &&
-        runner.selfHostedAuthorized === false,
-      runner,
-    ),
-  ];
-  return createPublicationControlPlaneAudit({
+}
+
+function evaluateBranchPolicy({ branchPolicy, branch, repository, requiredStatusCheck }) {
+  const requiredCheck = requiredStatusCheckBinding(branchPolicy, requiredStatusCheck);
+  return evaluateConfiguredBranchPolicy(branchPolicy, branch) || (
+    evaluateProviderBranchPolicy(branchPolicy, branch, requiredCheck) &&
+    evaluateProviderPullRequest(branchPolicy, branch, repository)
+  );
+}
+
+function evaluateEnvironmentPolicy(environmentPolicy, environment) {
+  return environment === "none"
+    ? environmentPolicy.declared === false && environmentPolicy.exists === false
+    : environmentPolicy.name === environment &&
+      environmentPolicy.declared === true &&
+      environmentPolicy.exists === true &&
+      environmentPolicy.protected === true &&
+      environmentPolicy.branchAuthorized === true &&
+      (environmentPolicy.reviewRequired !== true || environmentPolicy.preventSelfReview === true);
+}
+
+function evaluateRunnerPolicy(runner) {
+  return runner.class === "ephemeral" &&
+    runner.label === "ubuntu-24.04" &&
+    runner.githubHosted === true &&
+    runner.selfHostedAuthorized === false;
+}
+
+function evaluatePublicationControlPlaneSnapshotOptions(options) {
+  const {
     repository,
     workflowPath,
-    publisherWorkflowPath,
+    publisherWorkflowPath = workflowPath,
     environment,
-    facts,
+    branch,
+    packageName,
+    publisherMode = "npm-trusted-publisher",
+    requiredStatusCheck = "check",
+    snapshot,
     observedAt,
     expiresAt,
+  } = options;
+  const workflowFilename = String(publisherWorkflowPath || "").split("/").pop();
+  const providerEnvironment = environment === "none" ? "" : environment;
+  const actions = snapshot?.actions || {};
+  const branchPolicy = snapshot?.branch || {};
+  const environmentPolicy = snapshot?.environment || {};
+  const oidc = snapshot?.oidc || {};
+  const publisher = snapshot?.publisher || {};
+  const runner = snapshot?.runner || {};
+  const facts = [
+    fact("actions-policy", actions.defaultWorkflowPermissions === "read" && actions.canApprovePullRequestReviews === false, actions),
+    fact("branch-policy", evaluateBranchPolicy({ branchPolicy, branch, repository, requiredStatusCheck }), branchPolicy),
+    fact("environment-policy", evaluateEnvironmentPolicy(environmentPolicy, environment), environmentPolicy),
+    fact("oidc-policy", evaluateCredentialIsolation({ oidc, publisherMode, publisherWorkflowPath, providerEnvironment }), oidc),
+    fact("publisher-policy", evaluatePublisherPolicy({
+      publisher, publisherMode, packageName, repository, workflowPath,
+      publisherWorkflowPath, workflowFilename, environment, providerEnvironment,
+    }), publisher),
+    fact("runner-policy", evaluateRunnerPolicy(runner), runner),
+  ];
+  return createPublicationControlPlaneAudit({
+    repository, workflowPath, publisherWorkflowPath, environment, facts, observedAt, expiresAt,
   });
 }
+
+export function evaluatePublicationControlPlaneSnapshot({ repository, workflowPath, publisherWorkflowPath = workflowPath, environment, branch, packageName, publisherMode = "npm-trusted-publisher", requiredStatusCheck = "check", snapshot, observedAt, expiresAt, } = {}) {
+  return evaluatePublicationControlPlaneSnapshotOptions({ repository, workflowPath, publisherWorkflowPath, environment, branch, packageName, publisherMode, requiredStatusCheck, snapshot, observedAt, expiresAt });
+}

package/packages/core/publication-rehearsal-projection.js

@@ -0,0 +1,104 @@
+import {
+  PUBLICATION_REHEARSAL_CAPSULE_CONTRACT,
+  PUBLICATION_REHEARSAL_COMMAND,
+  RELEASE_LOCAL_CONSTRUCTIBILITY_ADR,
+  RELEASE_LOCAL_CONSTRUCTIBILITY_INVARIANT,
+} from "./publication-rehearsal-runtime.js";
+
+export const PUBLICATION_REHEARSAL_AGENT_SECTION_START =
+  "<!-- buildchain:publication-rehearsal:v4:start -->";
+export const PUBLICATION_REHEARSAL_AGENT_SECTION_END =
+  "<!-- buildchain:publication-rehearsal:v4:end -->";
+export const PUBLICATION_REHEARSAL_WORKFLOW_PATH =
+  ".github/workflows/publication-rehearsal.yml";
+
+export function publicationRehearsalToml() {
+  return `[publication_rehearsal]\ncontract = ${JSON.stringify(PUBLICATION_REHEARSAL_CAPSULE_CONTRACT)}\nadr = ${JSON.stringify(RELEASE_LOCAL_CONSTRUCTIBILITY_ADR)}\ninvariant = ${JSON.stringify(RELEASE_LOCAL_CONSTRUCTIBILITY_INVARIANT)}\ncommand = ${JSON.stringify(PUBLICATION_REHEARSAL_COMMAND)}\ncapsule = ".buildchain/publication-rehearsal/capsule.json"\ncandidate_root = ".buildchain/publication-rehearsal/candidate"\nstate = ".buildchain/publication-rehearsal/state.json"\nevidence = ".buildchain/publication-rehearsal/evidence.json"\n`;
+}
+
+export function assertPublicationRehearsalConfig(config) {
+  const section = config?.publication_rehearsal;
+  if (!section || typeof section !== "object" || Array.isArray(section))
+    throw new Error("publication_rehearsal table is missing");
+  const expected = {
+    contract: PUBLICATION_REHEARSAL_CAPSULE_CONTRACT,
+    adr: RELEASE_LOCAL_CONSTRUCTIBILITY_ADR,
+    invariant: RELEASE_LOCAL_CONSTRUCTIBILITY_INVARIANT,
+    command: PUBLICATION_REHEARSAL_COMMAND,
+    capsule: ".buildchain/publication-rehearsal/capsule.json",
+    candidate_root: ".buildchain/publication-rehearsal/candidate",
+    state: ".buildchain/publication-rehearsal/state.json",
+    evidence: ".buildchain/publication-rehearsal/evidence.json",
+  };
+  if (
+    JSON.stringify(Object.keys(section).sort()) !==
+    JSON.stringify(Object.keys(expected).sort())
+  )
+    throw new Error(
+      `publication_rehearsal fields must be exactly: ${Object.keys(expected).sort().join(", ")}`,
+    );
+  for (const [key, value] of Object.entries(expected))
+    if (section[key] !== value)
+      throw new Error(`publication_rehearsal.${key} is stale or unsupported`);
+  return structuredClone(section);
+}
+
+export function appendPublicationRehearsalToml(source) {
+  const current = String(source || "").trimEnd();
+  if (/^\[publication_rehearsal\]$/mu.test(current))
+    throw new Error(
+      "buildchain config already contains a publication_rehearsal table",
+    );
+  return `${current}\n\n${publicationRehearsalToml()}`;
+}
+
+export function projectPublicationRehearsalToml(source) {
+  const current = String(source || "");
+  const start = current.search(/^\[publication_rehearsal\]\s*$/mu);
+  if (start === -1) return appendPublicationRehearsalToml(current);
+  const remainder = current.slice(start);
+  const newline = remainder.indexOf("\n");
+  const nextTable = remainder.slice(newline + 1).search(/^\[[^\n]+\]\s*$/mu);
+  const end =
+    nextTable === -1 ? current.length : start + newline + 1 + nextTable;
+  const prefix = current.slice(0, start).trimEnd();
+  const suffix = current.slice(end).trimStart();
+  return `${prefix}\n\n${publicationRehearsalToml()}${suffix ? `\n${suffix}` : ""}`;
+}
+
+export function publicationRehearsalAgentInstructions() {
+  return `${PUBLICATION_REHEARSAL_AGENT_SECTION_START}\n## Publication rehearsal (required)\n\nBuildchain v4 rehearsal follows \`${RELEASE_LOCAL_CONSTRUCTIBILITY_ADR}\`.\n${RELEASE_LOCAL_CONSTRUCTIBILITY_INVARIANT}\n\nRun the source-bound capsule with:\n\n\`\`\`sh\n${PUBLICATION_REHEARSAL_COMMAND}\n\`\`\`\n\nSimulation and replay evidence never claim production publication authority.\n${PUBLICATION_REHEARSAL_AGENT_SECTION_END}`;
+}
+
+export function mergePublicationRehearsalAgentInstructions(current = "") {
+  const source = String(current || "");
+  const section = publicationRehearsalAgentInstructions();
+  const start = source.indexOf(PUBLICATION_REHEARSAL_AGENT_SECTION_START);
+  const end = source.indexOf(PUBLICATION_REHEARSAL_AGENT_SECTION_END);
+  if ((start === -1) !== (end === -1) || end < start)
+    throw new Error(
+      "AGENTS.md has an incomplete Buildchain publication rehearsal section",
+    );
+  if (start === -1)
+    return source.trim()
+      ? `${source.trimEnd()}\n\n${section}\n`
+      : `# AGENTS.md\n\n${section}\n`;
+  if (
+    source.indexOf(PUBLICATION_REHEARSAL_AGENT_SECTION_START, start + 1) !==
+      -1 ||
+    source.indexOf(PUBLICATION_REHEARSAL_AGENT_SECTION_END, end + 1) !== -1
+  )
+    throw new Error(
+      "AGENTS.md has ambiguous Buildchain publication rehearsal sections",
+    );
+  return `${source.slice(0, start)}${section}${source.slice(
+    end + PUBLICATION_REHEARSAL_AGENT_SECTION_END.length,
+  )}`;
+}
+
+export function publicationRehearsalWorkflow(buildchainRef) {
+  const ref = String(buildchainRef || "").trim();
+  if (!ref)
+    throw new Error("publication rehearsal workflow requires a Buildchain ref");
+  return `name: Publication Rehearsal\n\non:\n  workflow_dispatch:\n    inputs:\n      capsule-path:\n        description: "Source-bound v4 publication rehearsal capsule"\n        required: true\n        default: ".buildchain/publication-rehearsal/capsule.json"\n      candidate-root:\n        description: "Repository-relative candidate root"\n        required: true\n        default: ".buildchain/publication-rehearsal/candidate"\n\npermissions:\n  contents: read\n\njobs:\n  rehearsal:\n    uses: kungfu-systems/buildchain/.github/workflows/release-tail.yml@${ref}\n    with:\n      buildchain-ref: ${ref}\n      rehearsal-capsule-path: \${{ inputs.capsule-path }}\n      candidate-root: \${{ inputs.candidate-root }}\n      rehearsal-mode: simulate\n      state-path: ".buildchain/publication-rehearsal/state.json"\n      rehearsal-evidence-path: ".buildchain/publication-rehearsal/evidence.json"\n`;
+}

package/packages/core/publication-rehearsal-runtime.js

@@ -0,0 +1,190 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { releaseTailRoot } from "./release-tail-provider-plane.js";
+import {
+  V4_PUBLICATION_REHEARSAL_CAPSULE_CONTRACT,
+  V4_PUBLICATION_REHEARSAL_EVIDENCE_CONTRACT,
+  createV4PublicationRehearsalCapsule,
+  executeV4PublicationRehearsal,
+  validateV4PublicationRehearsalCapsule,
+  verifyV4PublicationRehearsalCapsule,
+} from "./v4-publication-rehearsal.js";
+
+export const PUBLICATION_REHEARSAL_CAPSULE_CONTRACT =
+  V4_PUBLICATION_REHEARSAL_CAPSULE_CONTRACT;
+export const PUBLICATION_REHEARSAL_EVIDENCE_CONTRACT =
+  V4_PUBLICATION_REHEARSAL_EVIDENCE_CONTRACT;
+export const PUBLICATION_REHEARSAL_DIAGNOSTIC_CONTRACT =
+  "buildchain-v4-publication-rehearsal-compatibility-diagnostic/v1";
+export const RELEASE_LOCAL_CONSTRUCTIBILITY_ADR =
+  "docs/v4-publication-rehearsal.md";
+export const RELEASE_LOCAL_CONSTRUCTIBILITY_INVARIANT =
+  "Publication rehearsal is source-, candidate-, manifest-, config-, policy-, observation-, and shared-core-bound; rehearsal authority is effect-disabled by default and never grants production authority.";
+export const PUBLICATION_REHEARSAL_COMMAND =
+  'buildchain release-tail rehearse --capsule "$PWD/.buildchain/publication-rehearsal/capsule.json" --candidate-root "$PWD/.buildchain/publication-rehearsal/candidate" --mode simulate --state "$PWD/.buildchain/publication-rehearsal/state.json" --evidence "$PWD/.buildchain/publication-rehearsal/evidence.json"';
+
+const REQUIRED_V4_INPUTS = Object.freeze([
+  "source.repository",
+  "source.revision",
+  "manifest.path",
+  "manifest.root",
+  "config.path",
+  "config.root",
+]);
+
+function migrationReceipt(surface, reasonCode) {
+  const body = {
+    schema: "buildchain-v3-v4-public-surface-migration/v1",
+    surface,
+    status: "migration-required",
+    reasonCode,
+    replacement: {
+      module: "@kungfu-tech/buildchain/v4-publication-rehearsal",
+      capsuleContract: V4_PUBLICATION_REHEARSAL_CAPSULE_CONTRACT,
+      requiredInputs: REQUIRED_V4_INPUTS,
+    },
+    productionAuthority: false,
+  };
+  return { ...body, migrationRoot: releaseTailRoot(body) };
+}
+
+export class PublicationRehearsalError extends Error {
+  constructor(
+    message,
+    {
+      code = "publication-rehearsal-v4-migration-required",
+      classification = "migration",
+      migration = null,
+      cause,
+    } = {},
+  ) {
+    super(message, cause ? { cause } : undefined);
+    this.name = "PublicationRehearsalError";
+    this.rehearsalCode = code;
+    this.rehearsalClass = classification;
+    this.migration = migration;
+    this.bindingRoot = "";
+  }
+}
+
+function hasV4CreationBindings(input) {
+  return Boolean(
+    input?.source?.repository &&
+    input?.source?.revision &&
+    input?.manifest?.path &&
+    input?.manifest?.root &&
+    input?.config?.path &&
+    input?.config?.root,
+  );
+}
+
+function requireV4CreationBindings(input, surface) {
+  if (hasV4CreationBindings(input)) return;
+  const migration = migrationReceipt(surface, "v4-source-binding-required");
+  throw new PublicationRehearsalError(
+    "v3 rehearsal capsules cannot be upgraded implicitly; provide the v4 source, manifest, and config bindings",
+    { migration },
+  );
+}
+
+export function createPublicationRehearsalCapsule(input = {}) {
+  requireV4CreationBindings(
+    input,
+    "@kungfu-tech/buildchain/publication-rehearsal-runtime#createPublicationRehearsalCapsule",
+  );
+  return createV4PublicationRehearsalCapsule(input);
+}
+
+export function normalizePublicationRehearsalCapsule(input) {
+  return validateV4PublicationRehearsalCapsule(input);
+}
+
+export function verifyPublicationRehearsalCapsule({
+  capsule,
+  capsuleRoot,
+  candidateRoot = capsuleRoot,
+} = {}) {
+  return verifyV4PublicationRehearsalCapsule({ capsule, candidateRoot });
+}
+
+export function publicationRehearsalBindingRoot(capsule) {
+  return validateV4PublicationRehearsalCapsule(capsule).capsuleRoot;
+}
+
+export function publicationRehearsalDiagnostic(error, { capsule } = {}) {
+  const migration = error?.migration || null;
+  const body = {
+    contract: PUBLICATION_REHEARSAL_DIAGNOSTIC_CONTRACT,
+    status: "rejected",
+    errorClass: error?.rehearsalClass || (migration ? "migration" : "input"),
+    code:
+      error?.rehearsalCode ||
+      error?.code ||
+      "publication-rehearsal-runtime-error",
+    message: String(error?.message || "publication rehearsal failed"),
+    bindingRoot: capsule?.capsuleRoot || "",
+    migration,
+    productionAuthority: false,
+  };
+  return { ...body, diagnosticRoot: releaseTailRoot(body) };
+}
+
+export async function executePublicationRehearsal({
+  capsule,
+  capsuleRoot,
+  candidateRoot = capsuleRoot,
+  mode = "simulate",
+  environment = {},
+  adapters = {},
+  authority = null,
+  transaction = null,
+  checkpoint,
+} = {}) {
+  if (
+    !environment ||
+    typeof environment !== "object" ||
+    Array.isArray(environment) ||
+    Object.keys(environment).length > 0
+  ) {
+    const migration = migrationReceipt(
+      "@kungfu-tech/buildchain/publication-rehearsal-runtime#executePublicationRehearsal",
+      "ambient-environment-forbidden",
+    );
+    throw new PublicationRehearsalError(
+      "v4 rehearsal accepts no ambient environment; bind every semantic input into the capsule",
+      { code: "undeclared-environment", classification: "input", migration },
+    );
+  }
+  return executeV4PublicationRehearsal({
+    capsule,
+    candidateRoot,
+    mode,
+    adapters,
+    authority,
+    transaction,
+    checkpoint,
+  });
+}
+
+export function resolvePublicationRehearsalFile(capsuleRoot, relativePath) {
+  if (!path.isAbsolute(capsuleRoot))
+    throw new PublicationRehearsalError(
+      "capsuleRoot must be an explicit absolute path",
+      { code: "implicit-workspace-forbidden", classification: "input" },
+    );
+  const base = fs.realpathSync(capsuleRoot);
+  const resolved = path.resolve(base, String(relativePath || ""));
+  if (
+    !resolved.startsWith(`${base}${path.sep}`) ||
+    !fs.existsSync(resolved) ||
+    !fs.statSync(resolved).isFile() ||
+    fs.lstatSync(resolved).isSymbolicLink() ||
+    !fs.realpathSync(resolved).startsWith(`${base}${path.sep}`)
+  )
+    throw new PublicationRehearsalError(
+      "publication rehearsal file must be a regular file inside the explicit candidate root",
+      { code: "capsule-path-ambiguous", classification: "input" },
+    );
+  return resolved;
+}

package/packages/core/release-candidate-recovery.js

@@ -47,6 +47,7 @@ const TRUSTED_ASSOCIATIONS = new Set(["COLLABORATOR", "MEMBER", "OWNER"]);
 const RESUMABLE_TRANSACTION_STATES = new Set([
   "sealed",
   "publishing",
+  "publish_failed",
   "published",
   "package-published",
   "finalizing",
@@ -354,7 +355,7 @@ function validateCandidateProvenance({
   run,
   workflow,
   pullRequest,
-  ancestry,
+  ancestry, targetTree,
   passport,
   anchorProvenance,
   expectedTransactionId,
@@ -383,7 +384,7 @@ function validateCandidateProvenance({
   const boundByNumber = Array.isArray(provenanceRun?.pullRequestNumbers) && provenanceRun.pullRequestNumbers.includes(Number(pullRequest?.number));
   const boundByHead = provenanceRun?.headSha === pullRequest?.headSha && normalizedRef(provenanceRun?.headBranch) === normalizedRef(pullRequest?.headRef);
   if (!boundByNumber && !boundByHead) fail("pr-identity-invalid", "candidate run is not bound to the merged candidate PR", "Select the exact PR-stage Build run.");
-  if (!ancestry?.mergeIsAncestor && ancestry?.status !== "identical") fail("ancestry-invalid", "candidate merge is not an ancestor of the promotion SHA", "Promote a descendant of the verified merged candidate identity.");
+  if (!ancestry?.mergeIsAncestor && ancestry?.status !== "identical" && exactSha(targetTree, "targetTree") !== exactSha(passport?.source?.treeHash, "passport.source.treeHash")) fail("ancestry-invalid", "candidate merge is neither an ancestor nor tree-equivalent to the promotion SHA", "Promote a descendant of the verified merged candidate identity or its exact tree-equivalent protected merge result.");
   return { repository, workflowFile };
 }
 
@@ -428,11 +429,11 @@ function validateRecoveryTransaction({ existingTransaction, expectedTransactionI
   if (expectedTransactionId && !actualTransactionId) fail("transaction-identity-conflict", `expected transaction ${expectedTransactionId} does not exist`, "Remove the stale transaction identity only if no durable transaction was ever sealed; otherwise preserve evidence and enter repair_required.");
   if (expectedTransactionId && expectedTransactionId !== actualTransactionId) fail("transaction-identity-conflict", `existing transaction ${actualTransactionId} conflicts with expected ${expectedTransactionId}`, "Enter repair_required and inspect the durable transaction before any retry.");
   if (existingTransaction) {
-    const expectedIdentity = releaseTransactionId({ repository, version, sourceSha: sha, targetRef: normalizedRef(targetRef) });
+    const expectedIdentity = releaseTransactionId({ repository, version, sourceSha: exactSha(existingTransaction.source_sha, "existingTransaction.source_sha"), targetRef: normalizedRef(targetRef) });
     assertEqual(existingTransaction.id, expectedIdentity, "transaction-identity-conflict", "durable transaction identity", "Enter repair_required; the durable transaction does not belong to this exact publication target.");
     assertEqual(existingTransaction.repository, repository, "transaction-identity-conflict", "durable transaction repository", "Enter repair_required; never cross repository transaction boundaries.");
     assertEqual(normalizedRef(existingTransaction.target_ref), normalizedRef(targetRef), "transaction-identity-conflict", "durable transaction target ref", "Enter repair_required; never retarget a sealed transaction.");
-    assertEqual(existingTransaction.source_sha, sha, "transaction-identity-conflict", "durable transaction source SHA", "Resume with the transaction's exact promotion SHA or enter repair_required.");
+    if (![existingTransaction.source_sha, existingTransaction.release_sha, existingTransaction.release_material_sha].filter(Boolean).includes(sha)) fail("transaction-identity-conflict", "recovery promotion SHA is not bound to the durable transaction", "Resume with the transaction's exact source, release, or release material SHA, or enter repair_required.");
     assertEqual(existingTransaction.version, version, "transaction-identity-conflict", "durable transaction version", "Enter repair_required; never change a sealed publication version.");
     assertEqual(existingTransaction.channel, channel || passport.target.channel, "transaction-identity-conflict", "durable transaction channel", "Enter repair_required; never move a transaction between channels.");
   }
@@ -476,7 +477,7 @@ export function verifyReleaseCandidateRecovery({
   const { repository, workflowFile } = validateCandidateProvenance({
     candidateRepository, targetRepository, expectedRunId, expectedWorkflowFile,
     expectedWorkflowName, targetRef, run, workflow, pullRequest, ancestry,
-    passport, anchorProvenance, expectedTransactionId,
+    targetTree, passport, anchorProvenance, expectedTransactionId,
   });
   const { sha, tree, runtimeSha, toolingSha } = validateCandidateIdentity({
     repository, channel, targetSha, targetTree, expectedSourceTree,