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

package/scripts/resume-from-candidate-run.mjs

@@ -4,9 +4,10 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { writeGitHubOutputs } from "./build-contract-core.mjs";
+import { compareSemver } from "./publication-registry-hydrate.mjs";
 import { normalizeAnchorProvenance, normalizeCandidateRun, recoverCandidateProvenance } from "./release-candidate-anchor-provenance.mjs";
 export { resolveAnchorRecoveryRequest } from "./release-candidate-anchor-provenance.mjs";
 import {
@@ -40,10 +41,7 @@ import {
   verifyV4RuntimeAuthorizationReceipt,
 } from "../packages/core/v4-runtime-ref-resume-authority.js";
 
-function env(name, fallback = "") {
-  return process.env[name] || fallback;
-}
-
+function env(name, fallback = "") { return process.env[name] || fallback; }
 function requiredEnv(name) {
   const value = env(name).trim();
   if (!value) throw new Error(`${name} is required for candidate recovery`);
@@ -56,9 +54,7 @@ function splitRepository(repository) {
   return { owner: match[1], repo: match[2], fullName: `${match[1]}/${match[2]}` };
 }
 
-function splitPatterns(value = "") {
-  return String(value || "").split(/\r?\n|,/).map((entry) => entry.trim()).filter(Boolean);
-}
+function splitPatterns(value = "") { return String(value || "").split(/\r?\n|,/).map((entry) => entry.trim()).filter(Boolean); }
 
 function patternMatcher(pattern) {
   const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replaceAll("*", ".*");
@@ -111,15 +107,17 @@ function readOnlyJson(files, label) {
   return JSON.parse(fs.readFileSync(files[0].absolutePath, "utf8"));
 }
 
-function trackedRuntimePersistenceScan() {
+export function trackedRuntimePersistenceScan({
+  runtimeRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."),
+} = {}) {
   const paths = execFileSync(
     "git",
-    ["ls-files", ".github/workflows", ".github/actions", ".buildchain"],
+    ["-C", runtimeRoot, "ls-files", ".github/workflows", ".github/actions", ".buildchain"],
     { encoding: "utf8" },
   )
     .split(/\r?\n/)
     .filter((entry) => /\.(?:json|toml|ya?ml)$/u.test(entry));
-  return scanV4RuntimeSelectorPersistence({ root: process.cwd(), paths });
+  return scanV4RuntimeSelectorPersistence({ root: runtimeRoot, paths });
 }
 
 export function verifyReleaseCandidateStageCapsules({ sidecar, passport, downloads }) {
@@ -201,23 +199,36 @@ export function verifyReleaseCandidateStageCapsules({ sidecar, passport, downloa
 export function validateV4RuntimeResumePublicReadback({
   targetRef,
   targetSha,
+  targetVersion,
   alphaSha,
   exactTagSha,
   tagLineage,
+  runtimeLineage,
+  floatingTargetLineage,
   runtimeSha,
   version,
   transaction,
   main,
   npm,
 }) {
+  const channelVersion = npm["dist-tags"]?.alpha;
+  let channelDidNotRegress = false;
+  try {
+    channelDidNotRegress = compareSemver(channelVersion, version) >= 0;
+  } catch { channelDidNotRegress = false; }
   if (
     transaction?.target_ref !== targetRef ||
     transaction?.version !== version ||
     exactTagSha !== transaction?.source_sha ||
     !["ahead", "identical"].includes(tagLineage?.status) ||
-    alphaSha !== runtimeSha ||
+    !["ahead", "identical"].includes(runtimeLineage?.status) ||
+    !["ahead", "identical"].includes(floatingTargetLineage?.status) ||
+    !alphaSha ||
     !targetSha ||
-    npm["dist-tags"]?.alpha !== version ||
+    !runtimeSha ||
+    channelVersion !== targetVersion ||
+    !channelDidNotRegress ||
+    !npm.versions?.[channelVersion]?.dist?.integrity ||
     npm.versions?.[version]?.dist?.integrity !== main.digest
   ) {
     throw new Error(
@@ -236,21 +247,12 @@ export async function readPublicResumeState({
   apiUrl,
   fetchImpl,
 }) {
-  const readRef = async (ref) =>
-    (await githubJson({
-      apiUrl,
-      token,
-      fetchImpl,
-      path: `/repos/${repoInfo.owner}/${repoInfo.repo}/git/ref/${ref}`,
-    })).object?.sha || "";
+  const readRef = async (ref) => (await githubJson({ apiUrl, token, fetchImpl,
+    path: `/repos/${repoInfo.owner}/${repoInfo.repo}/git/ref/${ref}` })).object?.sha || "";
   const main = transaction?.artifacts?.find((entry) => entry.kind === "npm" && entry.required !== false);
-  if (!main || main.ref !== version || !main.digest) {
-    throw new Error(
-      "cross-runtime recovery requires exact durable npm publication evidence",
-    );
-  }
-  const packageUrl =
-    `https://registry.npmjs.org/${encodeURIComponent(main.name)}`;
+  if (!main || main.ref !== version || !main.digest)
+    throw new Error("cross-runtime recovery requires exact durable npm publication evidence");
+  const packageUrl = `https://registry.npmjs.org/${encodeURIComponent(main.name)}`;
   const exactTag = transaction.exact_tag || `v${version}`;
   const [targetSha, alphaSha, exactTagSha, npmResponse] = await Promise.all([
     readRef(`heads/${targetRef}`),
@@ -262,24 +264,18 @@ export async function readPublicResumeState({
     throw new Error(`npm public readback failed with HTTP ${npmResponse.status}`);
   }
   const npm = await npmResponse.json();
-  const tagLineage = await githubJson({
-    apiUrl,
-    token,
-    fetchImpl,
-    path: `/repos/${repoInfo.owner}/${repoInfo.repo}/compare/${exactTagSha}...${targetSha}`,
-  });
-  validateV4RuntimeResumePublicReadback({
-    targetRef,
-    targetSha,
-    alphaSha,
-    exactTagSha,
-    tagLineage,
-    runtimeSha,
-    version,
-    transaction,
-    main,
-    npm,
-  });
+  const [tagLineage, runtimeLineage, floatingTargetLineage, targetPackageFile] = await Promise.all([
+    githubJson({ apiUrl, token, fetchImpl, path: `/repos/${repoInfo.owner}/${repoInfo.repo}/compare/${exactTagSha}...${targetSha}` }),
+    githubJson({ apiUrl, token, fetchImpl, path: `/repos/${repoInfo.owner}/${repoInfo.repo}/compare/${runtimeSha}...${alphaSha}` }),
+    githubJson({ apiUrl, token, fetchImpl, path: `/repos/${repoInfo.owner}/${repoInfo.repo}/compare/${alphaSha}...${targetSha}` }),
+    githubJson({ apiUrl, token, fetchImpl, path: `/repos/${repoInfo.owner}/${repoInfo.repo}/contents/package.json?ref=${encodeURIComponent(targetSha)}` }),
+  ]);
+  if (targetPackageFile?.type !== "file" || targetPackageFile.encoding !== "base64" || !targetPackageFile.content)
+    throw new Error("cross-runtime recovery requires protected target version state");
+  const targetVersion = JSON.parse(Buffer.from(String(targetPackageFile.content).replace(/\s/g, ""), "base64").toString("utf8")).version;
+  validateV4RuntimeResumePublicReadback({ targetRef, targetSha, targetVersion, alphaSha,
+    exactTagSha, tagLineage, runtimeLineage, floatingTargetLineage, runtimeSha,
+    version, transaction, main, npm });
   const body = {
     schemaVersion: 1,
     contract: "kungfu-buildchain-v4-runtime-resume-public-readback/v1",
@@ -296,11 +292,16 @@ export async function readPublicResumeState({
       version,
       distTag: "alpha",
       integrity: npm.versions[version].dist.integrity,
+      targetVersion, distTagVersion: npm["dist-tags"].alpha,
+      distTagIntegrity: npm.versions[npm["dist-tags"].alpha].dist.integrity,
     },
   };
   return { ...body, root: v4RuntimeResumeDocumentRoot(body) };
 }
 
+export const resolveV4RuntimeResumePublicRuntimeSha = (material) =>
+  material?.buildAttempt?.runtimeSha || "";
+
 function prepareRuntimeResumeEvidence({
   repoInfo,
   targetRef,
@@ -312,15 +313,13 @@ function prepareRuntimeResumeEvidence({
   recovery,
   outputDir,
 }) {
-  const authorizationPath = path.resolve(
-    ".buildchain/release-candidate/v4-runtime-authorization.json",
-  );
-  if (!fs.existsSync(authorizationPath)) {
-    throw new Error(
-      "cross-runtime recovery requires a fresh runtime authorization receipt",
-    );
-  }
-  const delegated = readOnlyJson([{ absolutePath: authorizationPath }], "runtime authorization");
+  const authorizationPath = path.resolve(".buildchain/release-candidate/v4-runtime-authorization.json");
+  const delegatedRaw = env("BUILDCHAIN_RUNTIME_AUTHORIZATION_JSON").trim();
+  const delegatedRoot = env("BUILDCHAIN_RUNTIME_AUTHORIZATION_ROOT").trim();
+  const authorizationFileExists = fs.existsSync(authorizationPath);
+  if (!authorizationFileExists && (!delegatedRaw || !delegatedRoot)) throw new Error("cross-runtime recovery requires a fresh runtime authorization receipt");
+  const delegated = authorizationFileExists ? readOnlyJson([{ absolutePath: authorizationPath }], "runtime authorization") : JSON.parse(delegatedRaw);
+  if (!authorizationFileExists && delegated.receiptRoot !== delegatedRoot) throw new Error("fresh recovery runtime authorization handoff root mismatch");
   const delegatedVerification = verifyV4RuntimeAuthorizationReceipt({
     receipt: delegated.receipt,
     receiptRoot: delegated.receiptRoot,
@@ -437,7 +436,7 @@ export async function finalizeRuntimeResumeEvidence({
   const readback = await readPublicResumeState({
     repoInfo,
     targetRef,
-    runtimeSha: material.runtimeSha,
+    runtimeSha: resolveV4RuntimeResumePublicRuntimeSha(material),
     version,
     transaction,
     token,
@@ -456,7 +455,7 @@ export async function finalizeRuntimeResumeEvidence({
     resumePlanRoot: material.resumePlanRoot,
     finalPublicReadbackRoot: readback.root,
     floatingRefBefore: material.floatingRefBefore,
-    floatingRefAfter: { ref: "v4-alpha", sha: material.runtimeSha },
+    floatingRefAfter: { ref: "v4-alpha", sha: readback.refs.floating.sha },
   });
   const evidence = {
     authorization: material.authorization,
@@ -696,14 +695,26 @@ export function createRecoveredPublicationCandidate({
   };
   return { ...payload, candidateDigest: publicationArtifactCandidateDigest(payload) };
 }
-
-export function createRecoveredPublication({ downloads, bundleRoot, repository, passport, candidateRuntimeSha, publishArtifactKind, publishPackageMain, releasePatterns, platformManifests }) {
-  const allFiles = downloads.flatMap((download) => download.files.map((file) => ({
-    path: path.relative(bundleRoot, file.absolutePath).split(path.sep).join("/"),
-    size: file.size,
-    sha256: file.sha256.replace(/^sha256:/, ""),
-    absolutePath: file.absolutePath,
-  }))).sort((left, right) => left.path.localeCompare(right.path));
+export function resolveRecoveredPublicationVersion({ artifactVersion, channel, rematerializeOnResume = false } = {}) {
+  const version = String(artifactVersion || "").trim(), match = version.match(/^(\d+\.\d+\.\d+)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u);
+  if (!match) throw new Error(`recovered npm artifact has invalid publication version: ${version || "<empty>"}`);
+  return channel === "release" && rematerializeOnResume ? match[1] : version;
+}
+export function resolveRecoveredCandidateVersion({ artifactVersion, publicationVersion, channel, rematerializeOnResume = false, targetRef = "", candidateRef = "" } = {}) {
+  const version = String(artifactVersion || "").trim(), target = String(targetRef || "").replace(/^refs\/heads\//u, ""), candidate = String(candidateRef || "").replace(/^refs\/heads\//u, "");
+  if (channel !== "release" || !rematerializeOnResume) return version;
+  const prefix = `publish-gate/${target}/`;
+  if (!target || !candidate.startsWith(prefix)) throw new Error(`stable recovery candidate ref must descend from ${prefix || "publish-gate/<target>/"}`);
+  const candidateVersion = candidate.slice(prefix.length);
+  if (!/^\d+\.\d+\.\d+-alpha\.\d+$/u.test(candidateVersion)) throw new Error(`stable recovery candidate ref must bind an exact alpha version, got ${candidateVersion || "<empty>"}`);
+  if (candidateVersion.replace(/-alpha\.\d+$/u, "") !== publicationVersion) throw new Error(`stable recovery candidate ${candidateVersion} does not match publication ${publicationVersion || "<empty>"}`);
+  if ((version.match(/^(\d+\.\d+\.\d+)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u)?.[1] || "") !== publicationVersion) throw new Error(`recovered npm artifact version ${version || "<empty>"} does not match publication ${publicationVersion}`);
+  return candidateVersion;
+}
+export function createRecoveredPublication({ downloads, bundleRoot, repository, passport, candidateRuntimeSha, publishArtifactKind, publishPackageMain, releasePatterns, platformManifests, channel, targetRef = "", candidateRef = "", rematerializeOnResume = false }) {
+  const allFiles = downloads.flatMap((download) => download.files.map((file) => ({ path: path.relative(bundleRoot, file.absolutePath).split(path.sep).join("/"),
+    size: file.size, sha256: file.sha256.replace(/^sha256:/, ""), absolutePath: file.absolutePath })))
+    .sort((left, right) => left.path.localeCompare(right.path));
   const kind = String(publishArtifactKind || "npm");
   const releaseMatchers = splitPatterns(releasePatterns).map(patternMatcher);
   const releaseAssets = allFiles.filter((file) => releaseMatchers.some((matcher) => matcher.test(path.basename(file.path))));
@@ -711,12 +722,8 @@ export function createRecoveredPublication({ downloads, bundleRoot, repository,
     createRecoveredPublicationCandidate({ allFiles, repository, passport, candidateRuntimeSha });
     const version = String(passport.target?.version || "").trim();
     if (!version) throw new Error("candidate recovery requires a passport publication version");
-    return {
-      manifest: undefined,
-      npmArtifacts: [],
-      allFiles,
-      releaseAssets,
-      version,
+    return { manifest: undefined, npmArtifacts: [], allFiles, releaseAssets,
+      version, candidateVersion: version,
       publishRequiredArtifacts: generatePublishRequiredArtifacts({ manifests: platformManifests, version, kind }),
     };
   }
@@ -728,12 +735,9 @@ export function createRecoveredPublication({ downloads, bundleRoot, repository,
   const npmReleaseAssets = allFiles.filter((file) => releaseMatchers.length
     ? releaseMatchers.some((matcher) => matcher.test(path.basename(file.path)))
     : file.path.toLowerCase().endsWith(".tgz"));
-  const candidate = createRecoveredPublicationCandidate({
-    allFiles,
-    repository,
-    passport,
-    candidateRuntimeSha,
-  });
+  const publicationVersion = resolveRecoveredPublicationVersion({ artifactVersion: main.metadata.ref, channel, rematerializeOnResume });
+  const candidateVersion = resolveRecoveredCandidateVersion({ artifactVersion: main.metadata.ref, publicationVersion, channel, rematerializeOnResume, targetRef, candidateRef });
+  const candidate = createRecoveredPublicationCandidate({ allFiles, repository, passport, candidateRuntimeSha });
   const manifest = createPublicationSealedBundle({
     candidate,
     packageName: main.metadata.name,
@@ -747,12 +751,12 @@ export function createRecoveredPublication({ downloads, bundleRoot, repository,
     npmArtifacts,
     allFiles,
     releaseAssets: npmReleaseAssets,
-    version: manifest.npm.version,
+    version: publicationVersion, candidateVersion,
     publishRequiredArtifacts: generatePublishRequiredArtifacts({
       kind: "npm",
       tarballPaths: npmArtifacts.map((entry) => entry.file.absolutePath),
       mainPackage: publishPackageMain,
-    }),
+    }).map((artifact) => rematerializeOnResume ? { ...artifact, ref: publicationVersion } : artifact),
   };
 }
 
@@ -810,7 +814,7 @@ async function resolveTargetAdvance({ observedTargetSha, targetSha, transactionI
   return { status: comparison.status, mergeIsAncestor: ["ahead", "identical"].includes(comparison.status) };
 }
 
-async function resolveRecoveryTransaction({
+export async function resolveRecoveryTransaction({
   repoInfo,
   apiUrl,
   token,
@@ -818,22 +822,21 @@ async function resolveRecoveryTransaction({
   transactionId,
   publicationVersion,
 }) {
-  const byId = await readExistingTransactionById({
-    repoInfo,
-    apiUrl,
-    token,
-    fetchImpl,
-    transactionId,
-  });
-  const version = byId?.version || publicationVersion;
-  const transaction = byId || await readExistingTransaction({
-    repoInfo,
-    apiUrl,
-    token,
-    fetchImpl,
-    version,
-  });
-  return { version, transaction };
+  let transaction = publicationVersion
+    ? await readExistingTransaction({
+        repoInfo,
+        apiUrl,
+        token,
+        fetchImpl,
+        version: publicationVersion,
+      })
+    : undefined;
+  if (transactionId && transaction?.id !== transactionId) {
+    transaction = transactionId
+      ? await readExistingTransactionById({ repoInfo, apiUrl, token, fetchImpl, transactionId })
+      : undefined;
+  }
+  return { version: transaction?.version || publicationVersion, transaction };
 }
 
 function resolveRecoveredStageCapsules({
@@ -862,7 +865,7 @@ export async function resumeFromCandidateRun({
   channel, targetRef, targetSha,
   expectedSourceTree = "", expectedCandidateRoot = "",
   candidateRuntimeSha, runtimeSha,
-  transactionId = "", artifactName = "", artifactPatterns = "", releasePatterns = "",
+  transactionId = "", artifactName = "", artifactPatterns = "", releasePatterns = "", rematerializeOnResume = false,
   requiredArtifactCount = 0,
   publishArtifactKind = "npm", publishPackageMain = "",
   outputDir = ".buildchain/release-candidate-recovery",
@@ -905,7 +908,7 @@ export async function resumeFromCandidateRun({
       publishArtifactKind,
       publishPackageMain,
       releasePatterns,
-      platformManifests: platformManifestEvidence.manifests,
+      platformManifests: platformManifestEvidence.manifests, channel, targetRef, candidateRef: pullRequest.head?.ref || "", rematerializeOnResume,
     });
     const stageCapsules = resolveRecoveredStageCapsules({
       candidateRuntimeSha,
@@ -915,7 +918,7 @@ export async function resumeFromCandidateRun({
       downloads,
     });
     const {
-      version: candidateVersion,
+      version: publicationVersion,
       transaction: existingTransaction,
     } = await resolveRecoveryTransaction({
       repoInfo,
@@ -973,7 +976,7 @@ export async function resumeFromCandidateRun({
       platformManifestEvidence: platformManifestEvidence.evidence,
       productPayloadManifests,
       artifacts: downloads.map((download) => download.record),
-      publicationVersion: candidateVersion,
+      publicationVersion,
       currentToolingSha: runtimeSha,
       recoveryRunId,
     });
@@ -989,7 +992,7 @@ export async function resumeFromCandidateRun({
           repoInfo,
           targetRef,
           runtimeSha,
-          version: candidateVersion,
+          version: publicationVersion,
           passport,
           sidecar: stageCapsuleSidecar,
           stageCapsules,
@@ -1004,7 +1007,7 @@ export async function resumeFromCandidateRun({
       repository: repoInfo.fullName,
       run: { id: runId, url: run.html_url || "", name: run.name },
       artifacts: { passport: selected.passport.name, summary: selected.summary.name, payloads: chosen.map((artifact) => artifact.name), sourceSha: selected.sourceSha },
-      version: candidateVersion,
+      version: publicationVersion, candidateVersion: publication.candidateVersion,
       candidateRoot: recovery.receipt.recovered.candidateRoot,
       artifactRoot: recovery.receipt.recovered.artifactRoot,
       receipt: recovery.receipt,
@@ -1045,7 +1048,7 @@ export async function resumeFromCandidateRunCli() {
       expectedCandidateRoot: env("BUILDCHAIN_RESUME_EXPECTED_CANDIDATE_ROOT"),
       candidateRuntimeSha: requiredEnv("BUILDCHAIN_RESUME_EXPECTED_CANDIDATE_RUNTIME_SHA"),
       runtimeSha: requiredEnv("BUILDCHAIN_RESUME_RUNTIME_SHA"),
-      transactionId: env("BUILDCHAIN_RESUME_TRANSACTION_ID"),
+      transactionId: env("BUILDCHAIN_RESUME_TRANSACTION_ID"), rematerializeOnResume: env("BUILDCHAIN_PUBLISH_REMATERIALIZE_ON_RESUME") === "true",
       artifactName: env("BUILDCHAIN_ARTIFACT_NAME"),
       artifactPatterns: env("BUILDCHAIN_ARTIFACT_PATTERNS"),
       releasePatterns: env("BUILDCHAIN_GITHUB_RELEASE_PAYLOAD_PATTERNS"),
@@ -1059,7 +1062,7 @@ export async function resumeFromCandidateRunCli() {
       "release-candidate-action": result.action,
       "release-candidate-passport-path": result.paths.passport,
       "release-candidate-build-summary-path": result.paths.buildSummary,
-      "release-candidate-version": result.version,
+      "release-candidate-version": result.candidateVersion, "release-candidate-publication-version": result.version,
       "release-candidate-source-sha": result.artifacts.sourceSha,
       "release-candidate-artifact": result.artifacts.passport,
       "release-candidate-build-summary-artifact": result.artifacts.summary,