@kungfu-tech/buildchain 4.1.6 → 4.1.7

package/packages/core/build/summary/historical-outputs.js

@@ -0,0 +1,88 @@
+import { readJson } from "../plan/values.js";
+
+// Project provider-confirmed evidence; this never grants publication authority.
+export function historicalBuildOutputs(
+  plan,
+  artifacts,
+  controller,
+  summary,
+  file,
+) {
+  const runtime = summary.runtime;
+  const source = summary.publishSource;
+  const gate = summary.publishGate;
+  const json = (value) => JSON.stringify(value);
+  const name = (reference) => reference?.name || "";
+  const outputs = {
+    "buildchain-channel": plan.identity.channel,
+    "buildchain-channel-selection-source": "called-workflow",
+    "buildchain-channel-reason": `Selected by ${plan.identity.ref}`,
+    "runner-preset": plan.environment.runners.preset,
+    "platforms-json": json(
+      plan.platforms.map((platform) => ({
+        ...platform,
+        runner: json(platform.runner),
+      })),
+    ),
+    "runner-routing-json": plan.routing ? json(plan.routing) : "",
+    "platform-count": plan.platforms.length,
+    "linux-container-enabled": plan.container.enabled,
+    "linux-container-image": plan.container.image,
+    "build-summary-artifact": name(artifacts.summary),
+    "credential-island-macos-artifact": name(artifacts.credential?.payload),
+    "credential-island-macos-manifest-artifact": name(
+      artifacts.credential?.manifest,
+    ),
+    "build-diagnostics-summary-artifact": name(artifacts.diagnostics),
+    "release-candidate-passport-artifact": name(artifacts.release_candidate),
+    "release-candidate-artifact": name(artifacts.release_candidate),
+    "release-candidate-passport-json": artifacts.release_candidate
+      ? json(
+          readJson(
+            file(".buildchain/artifacts/release-candidate-passport.json"),
+          ),
+        )
+      : "",
+    "build-summary-json": json(summary),
+    "artifact-coordinates-json": json(
+      readJson(file(".buildchain/artifacts/artifact-coordinates.json")),
+    ),
+    "build-diagnostics-summary-json": json(
+      readJson(file(".buildchain/artifacts/diagnostics-summary.json")),
+    ),
+    "trusted-event": gate.trustedEvent,
+    "buildchain-runtime-ref": runtime.ref,
+    "buildchain-runtime-sha": runtime.sha,
+    "buildchain-runtime-class": runtime.class,
+    "buildchain-runtime-override": runtime.override,
+    "buildchain-runtime-trust-decision": runtime.trustDecision,
+    "buildchain-contract-lock-status": plan.admission.lock_status,
+    "buildchain-contract-lock-drift": plan.admission.lock_drift,
+    "buildchain-contract-digest": plan.admission.contract_digest,
+    "publish-channel": gate.channel,
+    "publish-allowed": gate.allowed,
+    "publish-reason": gate.reason,
+    "publish-source-ref": source.ref,
+    "publish-source-sha": source.sha,
+    "publish-source-tree-sha": plan.source.tree_sha,
+    "publish-source-locked": source.locked,
+    "publish-source-channel": source.channel,
+    "publish-source-line": source.line,
+    "publish-source-consumer-version": source.consumerVersion,
+    "release-manifest-json": source.releaseManifest,
+    "controller-plan-artifact": name(artifacts.controller_plan),
+    "controller-plan-json": json(plan.controller),
+    "controller-plan-digest": plan.controller.digest,
+    "controller-receipt-artifact": name(artifacts.controller_receipt),
+    "controller-receipt-json": json(controller.receipt),
+    "controller-receipt-digest": controller.receipt.digest,
+    "controller-receipt-status": controller.receipt.status,
+  };
+  return Object.fromEntries(
+    Object.entries(outputs).map(([key, value]) => {
+      if (value === undefined)
+        throw new Error(`Missing historical build evidence: ${key}`);
+      return [key, String(value)];
+    }),
+  );
+}

package/packages/core/contracts/runtime-contract-inspection.js

@@ -113,3 +113,11 @@ export function assertRuntimeContractAccepted(result) {
       `Buildchain contract lock rejected: ${(result.evaluation.reasons || []).join("; ")}`,
     );
 }
+
+// Compare lock metadata with the selected runtime, independently of checkout paths.
+export function runtimeContractLockDrift(lock, runtimeSha, contractDigest) {
+  if (lock.schema === "buildchain.consumer-contract-lock/v2")
+    return lock.runtime.sha !== runtimeSha;
+  return lock.buildchain.resolvedSha !== runtimeSha ||
+    lock.buildchain.contractDigest !== contractDigest;
+}

package/packages/core/dev-delivery/candidate/submission.js

@@ -1,3 +1,4 @@
+import { devDeliverySourceBinding } from "../dev-delivery-candidate-identity.js";
 export function deliverySubmissionRequest(
   input,
   { repository, branch, sourceProofRoot, affectedPaths },
@@ -9,7 +10,7 @@ export function deliverySubmissionRequest(
     branch,
     pullRequestNumber: Number(input["expected-pr-number"]),
     sourceHead: input["expected-head-sha"],
-    sourceRoot: input["source-root"],
+    ...devDeliverySourceBinding({ sourceRoot: input["source-root"], assignmentRoot: input["assignment-root"], initiativeRoot: input["initiative-root"] }),
     sourceIdentityRoot: input["source-identity-root"],
     sourcePatchRoot: input["source-patch-root"],
     sourceProofRoot,

package/packages/core/dev-delivery/commands/dev-delivery-authority-command-adapters.mjs

@@ -1,3 +1,4 @@
+import { devDeliverySourceBinding } from "../dev-delivery-candidate-identity.js";
 import fs from "node:fs";
 import path from "node:path";
 import {
@@ -55,7 +56,7 @@ function submitCandidate(state, options) {
     {
       pullRequestNumber: options.pullRequestNumber,
       sourceHead: options.sourceHead,
-      sourceRoot: options.sourceRoot,
+      ...devDeliverySourceBinding(options),
       sourceIdentityRoot: options.sourceIdentityRoot,
       sourcePatchRoot: options.sourcePatchRoot,
       sourceProofRoot: options.sourceProofRoot,

package/packages/core/dev-delivery/commands/dev-delivery-authority.mjs

@@ -7,7 +7,11 @@ import {
 } from "../dev-delivery-authority-landing.js";
 import { defaultDevDeliveryStateRef } from "../warrant/values.js";
 import { GitHubDevDeliveryStore } from "../../providers/dev-delivery/store.js";
-import { flag, hasFlag } from "./dev-delivery-warrant-options.mjs";
+import {
+  flag,
+  hasFlag,
+  historicalDeliveryRootOptions,
+} from "./dev-delivery-warrant-options.mjs";
 import { runDevDeliveryAuthorityCommandAdapter } from "./dev-delivery-authority-command-adapters.mjs";
 function text(value = "") {
   return String(value ?? "").trim();
@@ -247,10 +251,7 @@ export function devDeliveryAuthorityCliOptions(
       environment.BUILDCHAIN_WORK_SOURCE_ROOT ||
         environment.BUILDCHAIN_DEV_DELIVERY_SOURCE_ROOT,
     ),
-    // Retired roots remain readable in persisted historical candidates.
-    // New authority submissions accept only the Work sourceRoot above.
-    // Retired CLI flags are intentionally ignored by this parser.
-    // This prevents producers from reconstructing obsolete identities.
+    ...historicalDeliveryRootOptions(rest, environment),
     sourceIdentityRoot: flag(
       rest,
       "source-identity-root",

package/packages/core/dev-delivery/commands/dev-delivery-warrant-options.mjs

@@ -79,8 +79,9 @@ export function devDeliveryCliOptions(args = [], environment = process.env) {
       "source-root",
       environment.BUILDCHAIN_WORK_SOURCE_ROOT ||
         environment.BUILDCHAIN_DEV_DELIVERY_SOURCE_ROOT ||
-        sourceRootFromGitHubEvent(environment),
+        rootFromGitHubEvent(environment),
     ),
+    ...historicalDeliveryRootOptions(rest, environment),
     // prettier-ignore
     ...{ expectedSourceHead: flag(rest, "expected-source-head", environment.BUILDCHAIN_DEV_DELIVERY_EXPECTED_SOURCE_HEAD), observedSourceHead: flag(rest, "observed-source-head", environment.BUILDCHAIN_DEV_DELIVERY_OBSERVED_SOURCE_HEAD) },
 
@@ -278,6 +279,24 @@ export function devDeliveryCliOptions(args = [], environment = process.env) {
 }
 
 // prettier-ignore
-function sourceRootFromGitHubEvent(environment) {
-  try { const event = JSON.parse(fs.readFileSync(environment.GITHUB_EVENT_PATH, "utf8")); return event.client_payload?.candidate?.sourceRoot || JSON.parse(event.inputs?.["native-roots-json"] || "{}").sourceRoot || ""; } catch { return ""; }
+function rootFromGitHubEvent(environment, key = "sourceRoot") {
+  try { const event = JSON.parse(fs.readFileSync(environment.GITHUB_EVENT_PATH, "utf8")); return event.client_payload?.candidate?.[key] || JSON.parse(event.inputs?.["native-roots-json"] || "{}")[key] || ""; } catch { return ""; }
+}
+
+export function historicalDeliveryRootOptions(args, environment) {
+  const result = {};
+  for (const [key, name] of [
+    ["assignmentRoot", "assignment-root"],
+    ["initiativeRoot", "initiative-root"],
+  ]) {
+    const value = flag(
+      args,
+      name,
+      environment[
+        `BUILDCHAIN_DEV_DELIVERY_${name.replaceAll("-", "_").toUpperCase()}`
+      ] || rootFromGitHubEvent(environment, key),
+    );
+    if (value) result[key] = value;
+  }
+  return result;
 }

package/packages/core/dev-delivery/dev-delivery-candidate-identity.js

@@ -18,9 +18,18 @@ export const EXACT_DEV_DELIVERY_PROOF_FIELDS = Object.freeze([
   "sourceWorkflowRunId",
 ]);
 export function devDeliverySourceBinding(input = {}) {
-  if (Object.hasOwn(input, "assignmentRoot") || Object.hasOwn(input, "initiativeRoot"))
-    throw new Error("provide sourceRoot alone; obsolete producer roots are unsupported");
-  return { sourceRoot: exactRoot(input.sourceRoot, "sourceRoot") };
+  const legacy = ["assignmentRoot", "initiativeRoot"].some(
+    (key) => Object.hasOwn(input, key) && input[key] !== undefined && input[key] !== "",
+  );
+  if (!legacy) return { sourceRoot: exactRoot(input.sourceRoot, "sourceRoot") };
+  if (input.sourceRoot)
+    throw new Error("provide sourceRoot alone; do not mix historical producer roots");
+  // Keep the original identity preimage so persisted queues and Warrants survive
+  // a runtime upgrade without changing candidate IDs or their receipt roots.
+  return {
+    assignmentRoot: exactRoot(input.assignmentRoot, "assignmentRoot"),
+    initiativeRoot: exactRoot(input.initiativeRoot, "initiativeRoot"),
+  };
 }
 export function matchesExactDevDeliveryCandidate(existing, attempted) {
   return (
@@ -44,7 +53,7 @@ export function reuseExactActiveDevDeliverySourceProof(active, input) {
   );
   const exact =
     admittedPhase &&
-    ["sourceRoot"].every(
+    ["sourceRoot", "assignmentRoot", "initiativeRoot"].every(
       (field) => active[field] === input[field],
     ) &&
     [

package/packages/core/dev-delivery/dev-delivery-warrant.js

@@ -1,3 +1,4 @@
+import { devDeliverySourceBinding } from "./dev-delivery-candidate-identity.js";
 import {
   devDeliveryClone as clone,
   devDeliveryContentRoot,
@@ -489,6 +490,8 @@ function createDevDeliverySuccessorWake(queue, now) {
         "pullRequestNumber",
         "sourceHead",
         "sourceRoot",
+        "assignmentRoot",
+        "initiativeRoot",
         "sourceIdentityRoot",
         "sourcePatchRoot",
         "sourceProofRoot",
@@ -584,5 +587,5 @@ export function observeDevDeliveryQueue(
 }
 
 function candidateSourceBinding(candidate) {
-  return { sourceRoot: candidate.sourceRoot };
+  return devDeliverySourceBinding(candidate);
 }

package/packages/core/dev-delivery/warrant/handoff.js

@@ -1,3 +1,4 @@
+import { devDeliverySourceBinding } from "../dev-delivery-candidate-identity.js";
 import path from "node:path";
 import { requireValue } from "../../runtime/action-process.mjs";
 import { writeJson } from "../native/files.js";
@@ -19,7 +20,7 @@ export function handoffInputs(
     "expected-pr-number": warrant.pullRequestNumber,
     "expected-head-sha": warrant.sourceHead,
     "source-workflow-run-id": warrant.sourceWorkflowRunId,
-    "native-roots-json": JSON.stringify({ sourceRoot: warrant.sourceRoot }),
+    "native-roots-json": JSON.stringify(devDeliverySourceBinding(warrant)),
     "source-identity-root": warrant.sourceIdentityRoot,
     "source-patch-root": warrant.sourcePatchRoot,
     "plan-root": warrant.planRoot,

package/packages/core/dev-delivery/warrant/transitions.js

@@ -13,7 +13,7 @@ import {
   settleDevDeliveryTerminalEvent,
   submitDevDeliveryCandidate,
 } from "../dev-delivery-warrant.js";
-import { reuseExactActiveDevDeliverySourceProof } from "../dev-delivery-candidate-identity.js";
+import { devDeliverySourceBinding, reuseExactActiveDevDeliverySourceProof } from "../dev-delivery-candidate-identity.js";
 import { runDeliveryWarrantReadCandidate } from "../delivery-warrant-read-candidate.js";
 
 import {
@@ -83,7 +83,7 @@ export function transitionFor(command, queue, options) {
         "pullRequestNumber",
       ),
       sourceHead: exactSha(options.sourceHead, "sourceHead"),
-      sourceRoot: exactRoot(options.sourceRoot, "sourceRoot"),
+      ...devDeliverySourceBinding(options),
       sourceIdentityRoot: exactRoot(
         options.sourceIdentityRoot,
         "sourceIdentityRoot",

package/packages/core/governance/buildchain-publication-authority.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { readConsumerUpgrade, renderCompatibilityWorkflow } from "../consumer/compatibility-workflows.js";
 
 import { createPublicationAuthorityRegistry } from "../publication/publication-authority.js";
 
@@ -70,16 +71,11 @@ export function buildchainPublicationAuthorityDescriptors({ root = process.cwd()
     environmentMode,
     runnerPolicy: publicationCapable ? "qualified-measured" : "unqualified",
   }));
-  const taxonomyPath = path.join(root, "architecture/workflow-taxonomy.json");
-  if (!fs.existsSync(taxonomyPath)) return descriptors;
-  const taxonomy = JSON.parse(fs.readFileSync(taxonomyPath, "utf8"));
-  for (const entry of taxonomy.entries) {
-    if (!entry.compatibility) continue;
-    const previous = descriptors.find((item) => item.workflowPath === entry.compatibility.path);
+  for (const entry of readConsumerUpgrade(root)?.entries || []) {
+    const previous = descriptors.find((item) => item.workflowPath === entry.target);
     if (!previous) continue;
-    const prefix = entry.role === "component" ? "." : `${entry.role}-`;
-    const workflowPath = `.github/workflows/${prefix}${entry.category}-${entry.purpose}.yml`;
-    if (fs.readFileSync(path.join(root, workflowPath), "utf8") !== fs.readFileSync(path.join(root, entry.compatibility.path), "utf8")) {
+    const workflowPath = entry.path;
+    if (fs.readFileSync(path.join(root, workflowPath), "utf8") !== renderCompatibilityWorkflow(entry, fs.readFileSync(path.join(root, entry.target), "utf8"))) {
       throw new Error(`publication authority alias differs from canonical workflow: ${workflowPath}`);
     }
     descriptors.push({ ...previous, workflowPath, publisherWorkflowPath: previous.publisherWorkflowPath === previous.workflowPath ? workflowPath : previous.publisherWorkflowPath });

package/packages/core/release/github-release-metadata.js

@@ -0,0 +1,58 @@
+import fs from "node:fs";
+import path from "node:path";
+import { historicalPromotionContext } from "./promotion/compatibility-context.js";
+
+export const RELEASE_METADATA_NAME = "buildchain.release-metadata.json";
+const schema = "buildchain.github-release-metadata/v1";
+
+// The metadata is an ordinary content-rooted release asset. The provider reads
+// it only after validating every local asset against its qualified root.
+export function historicalReleaseMetadata(context, outputDir) {
+  const inputs = historicalPromotionContext(context)?.inputs;
+  if (
+    !inputs ||
+    !(inputs["github-release-title"] || inputs["github-release-notes"])
+  )
+    return [];
+  const metadata = {
+    schema,
+    ...(inputs["github-release-title"]
+      ? { name: inputs["github-release-title"] }
+      : {}),
+    ...(inputs["github-release-notes"]
+      ? { body: inputs["github-release-notes"] }
+      : {}),
+  };
+  fs.mkdirSync(outputDir, { recursive: true });
+  const file = path.join(outputDir, RELEASE_METADATA_NAME);
+  fs.writeFileSync(file, `${JSON.stringify(metadata, null, 2)}\n`);
+  return [file];
+}
+
+export function releaseMetadata(artifacts) {
+  const files = artifacts.filter(({ name }) => name === RELEASE_METADATA_NAME);
+  if (!files.length) return null;
+  if (files.length !== 1) throw new Error("Ambiguous GitHub Release metadata");
+  const value = JSON.parse(fs.readFileSync(files[0].path, "utf8"));
+  if (
+    !value ||
+    value.schema !== schema ||
+    Object.keys(value).some(
+      (key) => !["schema", "name", "body"].includes(key),
+    ) ||
+    !["name", "body"].some((key) => typeof value[key] === "string") ||
+    ["name", "body"].some(
+      (key) => Object.hasOwn(value, key) && typeof value[key] !== "string",
+    )
+  )
+    throw new Error("Invalid GitHub Release metadata");
+  const { schema: _schema, ...fields } = value;
+  return fields;
+}
+
+export function releaseMetadataMatches(metadata, release) {
+  return (
+    !metadata ||
+    Object.entries(metadata).every(([key, value]) => release[key] === value)
+  );
+}

package/packages/core/release/promote-candidate/action.js

@@ -1,5 +1,5 @@
 import * as github from "@actions/github";
-import { publishWithDiscussion } from "../discussion/publication.js";
+import { publishCandidate } from "./publication.js";
 import { selectedRecordRuntime } from "../discussion/session.js";
 export async function candidatePublicationAction(core, env) {
   const required = new Set([
@@ -39,6 +39,8 @@ export async function candidatePublicationAction(core, env) {
       "publish-package-main",
       "publish-package-set-order",
       "publisher-workflow-sha",
+      "publisher-workflow-path",
+      "historical-inputs-json",
       "repository",
       "required-artifacts-path",
       "required-status-check",
@@ -70,7 +72,7 @@ export async function candidatePublicationAction(core, env) {
   request["artifact-paths"] = core
     .getMultilineInput("artifact-paths")
     .filter(Boolean);
-  return publishWithDiscussion(request, {
+  return publishCandidate(request, {
     octokit: github.getOctokit(request.token),
     mutationOctokit: github.getOctokit(
       request["mutation-token"] || request.token,

package/packages/core/release/promote-candidate/preparation.js

@@ -1,3 +1,4 @@
+import { verifyHistoricalEvidence } from "../promotion/historical-evidence.js";
 import {
   resolveCandidateBuildSummaryPath,
   resolveCandidateProviderInputs,
@@ -28,6 +29,11 @@ export async function prepareCandidatePublication(
     declaredPath: request["candidate-build-summary-path"],
   });
   const candidate = read(candidatePassportPath);
+  verifyHistoricalEvidence({
+    context: request["historical-inputs-json"],
+    candidateDirectory: path.resolve(".buildchain/release-candidate"),
+    sourceSha: candidate.source?.headSha,
+  });
   const stageCapsules = read(request["stage-capsules-path"]);
   const qualification = read(request["publication-qualification-path"]);
   const token = request["token"];

package/packages/core/release/promote-candidate/publication.js

@@ -0,0 +1,36 @@
+import { assertHistoricalPromotionEffects } from "../promotion/compatibility-qualification.js";
+import { publishWithDiscussion } from "../discussion/publication.js";
+import { promoteReleaseCandidate } from "./transaction.js";
+import {
+  historicalPromotionContext,
+  HISTORICAL_PUBLISHER,
+} from "../promotion/compatibility-context.js";
+
+// Both transports execute the same qualified provider transaction. Historical
+// callers did not grant Discussions access; their evidence stays in the existing
+// Actions artifacts and provider receipts instead of creating a Discussion.
+export function publishCandidate(
+  request,
+  context,
+  {
+    historical = promoteReleaseCandidate,
+    current = publishWithDiscussion,
+  } = {},
+) {
+  assertHistoricalPromotionEffects(request);
+  const retained = historicalPromotionContext(
+    request["historical-inputs-json"],
+  );
+  if (
+    Boolean(retained) !==
+    (request["publisher-workflow-path"] === HISTORICAL_PUBLISHER)
+  )
+    throw new Error(
+      "Historical publisher requires its admitted compatibility context",
+    );
+  if (retained && request["resume-discussion-id"])
+    throw new Error(
+      "Historical publication cannot resume a Discussion transaction",
+    );
+  return (retained ? historical : current)(request, context);
+}

package/packages/core/release/promote-candidate/release-documents.js

@@ -50,7 +50,7 @@ export async function createReleaseDocuments({
     schema: RELEASE_INVOCATION_CONTRACT,
     publisher: {
       repository: "kungfu-systems/buildchain",
-      workflow: ".github/workflows/.release-promote.yml",
+      workflow: request["publisher-workflow-path"] || ".github/workflows/.release-promote.yml",
       workflowSha: request["publisher-workflow-sha"],
       job: "apply",
     },

package/packages/core/release/promotion/candidate.js

@@ -1,3 +1,4 @@
+import { historicalRecoveryPins, verifyHistoricalCandidateRuntime } from "./compatibility-qualification.js";
 import { recoverDiscussionCandidate } from "../discussion/recovery.js";
 import { resolveReleaseCandidateArtifacts } from "../candidate/resolve.js";
 import { resumeFromCandidateRun } from "../recovery/candidate.js";
@@ -20,6 +21,7 @@ export async function qualifyPromotionCandidate(
     recoverDiscussion = recoverDiscussionCandidate,
   } = {},
 ) {
+  const expectedRuntime = historicalRecoveryPins(request, runtimeSha);
   const shared = {
     token,
     apiUrl,
@@ -41,7 +43,7 @@ export async function qualifyPromotionCandidate(
       targetRef: intent["target-ref"],
     });
   if (request["resume-candidate-run-id"])
-    return recover({
+    return verifyHistoricalCandidateRuntime(await recover({
       ...shared,
       repository: request["resume-candidate-repository"],
       targetRepository: repository,
@@ -63,7 +65,7 @@ export async function qualifyPromotionCandidate(
       runtimeRoot,
       recoveryRunId,
       recoveryRunAttempt,
-    });
+    }), expectedRuntime);
   return fresh({
     ...shared,
     repository,

package/packages/core/release/promotion/compatibility-context.js

@@ -0,0 +1,93 @@
+import fs from "node:fs";
+import path from "node:path";
+import { installationRoot } from "../../runtime/installation-root.js";
+
+export const HISTORICAL_PROMOTION_SCHEMA = "buildchain.historical-promotion/v1";
+export const HISTORICAL_PUBLISHER = ".github/workflows/.release-historical.yml";
+let fields, current;
+function loadHistoricalFields() {
+  if (fields) return;
+  const root = installationRoot(import.meta.url);
+  fields = JSON.parse(
+    fs.readFileSync(
+      path.join(
+        root,
+        "contracts/fixtures/consumer-upgrade/release-v4.0.0.json",
+      ),
+      "utf8",
+    ),
+  ).inputs;
+  current = JSON.parse(
+    fs.readFileSync(
+      path.join(root, "contracts/promotion-request-v1.schema.json"),
+      "utf8",
+    ),
+  ).properties;
+}
+export const historicalEvidenceFileKeys = [
+  "release-passport-kfd-1-witness-jsons",
+  "release-passport-kfd-2-claim-jsons",
+  "release-passport-kfd-3-prebuild-witness-jsons",
+  "release-passport-kfd-3-artifact-witness-jsons",
+  "release-passport-impact-json",
+];
+const excluded = new Set([
+  "buildchain-channel",
+  "buildchain-repository",
+  "buildchain-ref",
+  "buildchain-contract-lock-path",
+  "buildchain-alpha-contract-lock-path",
+  "buildchain-stable-contract-lock-path",
+  "branch-protection-bypass-users",
+  "branch-protection-bypass-teams",
+]);
+
+export function historicalPromotionContext(value) {
+  if (!value) return null;
+  loadHistoricalFields();
+  const context = typeof value === "string" ? JSON.parse(value) : value;
+  if (
+    !context ||
+    context.schema !== HISTORICAL_PROMOTION_SCHEMA ||
+    Object.keys(context).some((key) => !["schema", "inputs"].includes(key)) ||
+    !context.inputs ||
+    typeof context.inputs !== "object" ||
+    Array.isArray(context.inputs)
+  )
+    throw new Error("Invalid historical promotion context");
+  for (const [key, value] of Object.entries(context.inputs)) {
+    const field = fields[key];
+    if (
+      !field ||
+      excluded.has(key) ||
+      (current[key] &&
+        ![
+          "publish-artifact-kind",
+          "publish-mode",
+          ...historicalEvidenceFileKeys,
+        ].includes(key)) ||
+      typeof value !== field.type ||
+      (field.type === "number" && !Number.isFinite(value))
+    )
+      throw new Error(`Unsupported historical promotion context field: ${key}`);
+    if (
+      /^resume-.*runtime-sha$/u.test(key) &&
+      value &&
+      !/^[a-f0-9]{40}$/u.test(value)
+    )
+      throw new Error(`Historical ${key} requires an exact runtime SHA`);
+    if (key === "publish-mode" && value !== "publish-final-version")
+      throw new Error(
+        "Historical publish-mode translation requires publish-final-version",
+      );
+    if (key === "publish-artifact-kind" && value !== "binary")
+      throw new Error("Historical artifact-kind translation requires binary");
+  }
+  return context;
+}
+
+export function historicalPublisherPath(value) {
+  return historicalPromotionContext(value)
+    ? HISTORICAL_PUBLISHER
+    : ".github/workflows/.release-promote.yml";
+}

package/packages/core/release/promotion/compatibility-qualification.js

@@ -0,0 +1,48 @@
+import { historicalEvidenceKeys } from "./historical-evidence.js";
+import fs from "node:fs";
+import { historicalPromotionContext } from "./compatibility-context.js";
+
+export function historicalRecoveryPins(request, runtimeSha) {
+  const inputs = historicalPromotionContext(
+    request["historical-inputs-json"],
+  )?.inputs;
+  if (!inputs) return "";
+  const selected = inputs["resume-buildchain-runtime-sha"];
+  if (selected && selected !== runtimeSha)
+    throw new Error("Historical recovery runtime does not match its exact pin");
+  const expected = inputs["resume-expected-candidate-runtime-sha"] || "";
+  if (expected && !request["resume-candidate-run-id"])
+    throw new Error(
+      "Historical candidate runtime pin requires a candidate recovery run",
+    );
+  return expected;
+}
+
+export function verifyHistoricalCandidateRuntime(candidate, expected) {
+  if (expected) {
+    const passport = JSON.parse(
+      fs.readFileSync(candidate.paths.passport, "utf8"),
+    );
+    if (passport.buildchain?.sha !== expected)
+      throw new Error(
+        "Historical recovered candidate does not match its runtime pin",
+      );
+  }
+  return candidate;
+}
+
+// A retained input must never be accepted and then silently ignored. Each
+// command requires its original execution/evidence contract before enabling it.
+export function assertHistoricalPromotionEffects(request) {
+  const inputs =
+    historicalPromotionContext(request["historical-inputs-json"])?.inputs || {};
+  for (const [key, value] of Object.entries(inputs))
+    if (
+      key.endsWith("-command") &&
+      value &&
+      !historicalEvidenceKeys.includes(key)
+    )
+      throw new Error(
+        `Historical promotion command adapter is not implemented: ${key}`,
+      );
+}