@kungfu-tech/buildchain 2.12.9-alpha.0 → 2.13.0-alpha.0

package/packages/core/artifact-verification-envelope.js

@@ -0,0 +1,386 @@
+import crypto from "node:crypto";
+
+export const ARTIFACT_VERIFICATION_ENVELOPE_CONTRACT =
+  "kungfu-buildchain-artifact-verification-envelope";
+export const ARTIFACT_VERIFICATION_ENVELOPE_CHECK_CONTRACT =
+  "kungfu-buildchain-artifact-verification-envelope-check";
+export const KFX_ADMISSION_INPUTS_CONTRACT =
+  "kungfu-buildchain-kfx-admission-inputs";
+
+const ARTIFACT_VERIFICATION_CONTRACT =
+  "kungfu-buildchain-artifact-verification";
+const KFX_TRUST_INPUTS_SCHEMA = "kungfu.kfx-trust-inputs/v1";
+const KFD_ASSESSMENT_SCHEMA = "kungfu.trust.assessment/v1";
+const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const ROOT_FIELDS = Object.freeze([
+  "packageRoot",
+  "sourceRoot",
+  "dependencyRoot",
+  "buildPlanRoot",
+  "toolchainRoot",
+  "artifactRoot",
+  "qualificationRoot",
+  "verifierRoot",
+]);
+const BINDING_FIELDS = Object.freeze([
+  "schema",
+  ...ROOT_FIELDS,
+  "issuer",
+  "publisher",
+  "contractVersion",
+]);
+
+function stableJson(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableJson).join(",")}]`;
+  }
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function jsonClone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+export function artifactVerificationEnvelopeDigest(value) {
+  return `sha256:${crypto.createHash("sha256").update(stableJson(value)).digest("hex")}`;
+}
+
+function issue(code, message, details = {}) {
+  return { level: "error", code, message, details };
+}
+
+function isObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function isRoot(value) {
+  return SHA256_PATTERN.test(String(value || ""));
+}
+
+function nonEmptyString(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+  return normalized;
+}
+
+function nonNegativeInteger(value, label) {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new Error(`${label} must be a non-negative safe integer`);
+  }
+  return value;
+}
+
+function normalizeBindings(value = {}) {
+  if (!isObject(value)) {
+    throw new Error("bindings must be an object");
+  }
+  const supplied = Object.keys(value).sort();
+  const expected = [...BINDING_FIELDS].sort();
+  if (stableJson(supplied) !== stableJson(expected)) {
+    throw new Error(`bindings must contain exactly: ${BINDING_FIELDS.join(", ")}`);
+  }
+  if (value.schema !== KFX_TRUST_INPUTS_SCHEMA) {
+    throw new Error(`bindings.schema must be ${KFX_TRUST_INPUTS_SCHEMA}`);
+  }
+  const normalized = { schema: KFX_TRUST_INPUTS_SCHEMA };
+  for (const field of ROOT_FIELDS) {
+    const root = String(value[field] || "");
+    if (!isRoot(root)) {
+      throw new Error(`bindings.${field} must be a canonical lowercase sha256 root`);
+    }
+    normalized[field] = root;
+  }
+  normalized.issuer = nonEmptyString(value.issuer, "bindings.issuer");
+  normalized.publisher = nonEmptyString(value.publisher, "bindings.publisher");
+  normalized.contractVersion = nonEmptyString(value.contractVersion, "bindings.contractVersion");
+  return normalized;
+}
+
+function normalizeRevocation(value = {}, { issuedAt } = {}) {
+  if (!isObject(value)) {
+    throw new Error("revocation must be an object");
+  }
+  const revoked = value.revoked === true;
+  const status = nonEmptyString(value.status || (revoked ? "revoked" : "active"), "revocation.status");
+  if (!new Set(["active", "revoked"]).has(status) || revoked !== (status === "revoked")) {
+    throw new Error("revocation.status must agree with revocation.revoked");
+  }
+  const checkedAt = nonNegativeInteger(value.checkedAt ?? issuedAt, "revocation.checkedAt");
+  const root = String(value.root || "");
+  if (!isRoot(root)) {
+    throw new Error("revocation.root must be a canonical lowercase sha256 root");
+  }
+  return {
+    status,
+    revoked,
+    checkedAt,
+    source: nonEmptyString(value.source, "revocation.source"),
+    root,
+  };
+}
+
+function envelopeRoot(value) {
+  const basis = jsonClone(value);
+  if (isObject(basis.envelope)) {
+    delete basis.envelope.root;
+  }
+  return artifactVerificationEnvelopeDigest(basis);
+}
+
+function recomputeKfdReportRoot(report) {
+  const basis = jsonClone(report);
+  delete basis.report_hash;
+  return artifactVerificationEnvelopeDigest(basis);
+}
+
+export function verifyArtifactVerificationEnvelope({
+  envelope,
+  assessmentTime = Math.floor(Date.now() / 1000),
+  expectedEnvelopeRoot = "",
+  expectedIssuer = "",
+  expectedPublisher = "",
+  expectedContractVersion = "",
+} = {}) {
+  const issues = [];
+  const at = Number.isSafeInteger(assessmentTime) && assessmentTime >= 0
+    ? assessmentTime
+    : -1;
+  if (!isObject(envelope)) {
+    issues.push(issue("envelope.object", "artifact verification envelope must be an object"));
+    return {
+      schemaVersion: 1,
+      contract: ARTIFACT_VERIFICATION_ENVELOPE_CHECK_CONTRACT,
+      ok: false,
+      outcome: "fail",
+      assessmentTime,
+      issues,
+    };
+  }
+
+  const metadata = isObject(envelope.envelope) ? envelope.envelope : {};
+  if (
+    metadata.contract !== ARTIFACT_VERIFICATION_ENVELOPE_CONTRACT ||
+    metadata.schemaVersion !== 1 ||
+    metadata.canonicalization !== "buildchain-stable-json/v1"
+  ) {
+    issues.push(issue("envelope.contract", "artifact verification envelope contract metadata is invalid"));
+  }
+  const computedEnvelopeRoot = envelopeRoot(envelope);
+  if (!isRoot(metadata.root) || metadata.root !== computedEnvelopeRoot) {
+    issues.push(issue("envelope.root", "artifact verification envelope root does not match canonical content", {
+      expected: computedEnvelopeRoot,
+      actual: metadata.root || "",
+    }));
+  }
+  if (expectedEnvelopeRoot && metadata.root !== expectedEnvelopeRoot) {
+    issues.push(issue("envelope.root.expected", "artifact verification envelope root does not match the pinned root"));
+  }
+
+  const verificationOk =
+    envelope.contract === ARTIFACT_VERIFICATION_CONTRACT &&
+    envelope.schemaVersion === 1 &&
+    envelope.outcome === "pass" &&
+    envelope.ok === true &&
+    envelope.trust === "pass" &&
+    envelope.passport?.verification?.ok === true &&
+    envelope.passport?.verification?.trust === "pass";
+  if (!verificationOk) {
+    issues.push(issue("verification.invalid", "base artifact verification must be a passing v1 report"));
+  }
+
+  let bindings;
+  try {
+    bindings = normalizeBindings(envelope.bindings);
+  } catch (error) {
+    issues.push(issue("bindings.invalid", error.message));
+  }
+  if (bindings) {
+    const subjectRoot = String(envelope.subject?.digest || "");
+    const matchedRoot = String(envelope.match?.artifact?.digest || "");
+    if (
+      !isRoot(subjectRoot) ||
+      subjectRoot !== matchedRoot ||
+      bindings.artifactRoot !== subjectRoot
+    ) {
+      issues.push(issue("bindings.artifactRoot", "artifact root must match the exact verified subject and passport artifact"));
+    }
+    if (expectedIssuer && bindings.issuer !== expectedIssuer) {
+      issues.push(issue("bindings.issuer", "issuer does not match the expected authority"));
+    }
+    if (expectedPublisher && bindings.publisher !== expectedPublisher) {
+      issues.push(issue("bindings.publisher", "publisher does not match the expected identity"));
+    }
+    if (expectedContractVersion && bindings.contractVersion !== expectedContractVersion) {
+      issues.push(issue("bindings.contractVersion", "verification contract version does not match the expected version"));
+    }
+  }
+
+  const issuedAt = envelope.issuedAt;
+  const expiresAt = envelope.expiresAt;
+  if (
+    at < 0 ||
+    !Number.isSafeInteger(issuedAt) ||
+    issuedAt < 0 ||
+    !Number.isSafeInteger(expiresAt) ||
+    expiresAt <= issuedAt ||
+    at < issuedAt ||
+    at >= expiresAt
+  ) {
+    issues.push(issue("lifecycle.invalid", "envelope must be active at assessmentTime with valid issuedAt/expiresAt bounds"));
+  }
+  const revocation = envelope.revocation;
+  if (
+    !isObject(revocation) ||
+    !isRoot(revocation.root) ||
+    !Number.isSafeInteger(revocation.checkedAt) ||
+    revocation.checkedAt < issuedAt ||
+    (at >= 0 && revocation.checkedAt > at) ||
+    !["active", "revoked"].includes(revocation.status) ||
+    revocation.revoked !== (revocation.status === "revoked") ||
+    envelope.revoked !== revocation.revoked
+  ) {
+    issues.push(issue("lifecycle.revocation", "revocation binding is invalid or inconsistent"));
+  }
+  if (envelope.revoked === true) {
+    issues.push(issue("lifecycle.revoked", "artifact verification envelope has been revoked"));
+  }
+
+  const assessment = envelope.kfdAssessment;
+  const report = isObject(assessment?.report) ? assessment.report : {};
+  if (
+    !isObject(assessment) ||
+    assessment.schema !== KFD_ASSESSMENT_SCHEMA ||
+    assessment.state !== "fresh" ||
+    report.state !== "fresh"
+  ) {
+    issues.push(issue("kfd.assessment.state", "KFD assessment must be a fresh ADR-0052 assessment"));
+  }
+  if (
+    !isRoot(assessment?.assessment_key) ||
+    report.assessment_key !== assessment?.assessment_key
+  ) {
+    issues.push(issue("kfd.assessment.key", "KFD assessment key must be canonical and match the report"));
+  }
+  const computedReportRoot = isObject(report) ? recomputeKfdReportRoot(report) : "";
+  if (!isRoot(report.report_hash) || report.report_hash !== computedReportRoot) {
+    issues.push(issue("kfd.report.root", "KFD report hash does not match canonical report content", {
+      expected: computedReportRoot,
+      actual: report.report_hash || "",
+    }));
+  }
+  if (
+    !String(report.purpose || "").trim() ||
+    !isRoot(report.query_proof_root) ||
+    !isRoot(report.contract_world?.root) ||
+    !isRoot(report.policy?.root) ||
+    !Array.isArray(report.fact_surfaces) ||
+    report.fact_surfaces.length === 0 ||
+    report.fact_surfaces.some((surface) => !isRoot(surface?.root))
+  ) {
+    issues.push(issue("kfd.report.bindings", "KFD report must bind purpose, query proof, contract world, policy, and fact-surface roots"));
+  }
+  if (bindings && bindings.qualificationRoot !== report.report_hash) {
+    issues.push(issue("bindings.qualificationRoot", "qualification root must equal the KFD report hash"));
+  }
+
+  const ok = issues.length === 0;
+  return {
+    schemaVersion: 1,
+    contract: ARTIFACT_VERIFICATION_ENVELOPE_CHECK_CONTRACT,
+    ok,
+    outcome: ok ? "pass" : "fail",
+    assessmentTime,
+    envelopeRoot: metadata.root || "",
+    bindings: bindings || undefined,
+    kfdAssessment: isObject(assessment)
+      ? {
+          state: assessment.state || "",
+          assessmentKey: assessment.assessment_key || "",
+          reportRoot: report.report_hash || "",
+        }
+      : undefined,
+    issues,
+  };
+}
+
+export function sealArtifactVerificationReport({
+  report,
+  bindings,
+  kfdAssessment,
+  issuedAt,
+  expiresAt,
+  revocation,
+} = {}) {
+  if (!isObject(report)) {
+    throw new Error("report must be an artifact verification object");
+  }
+  const normalizedIssuedAt = nonNegativeInteger(issuedAt, "issuedAt");
+  const normalizedExpiresAt = nonNegativeInteger(expiresAt, "expiresAt");
+  if (normalizedExpiresAt <= normalizedIssuedAt) {
+    throw new Error("expiresAt must be greater than issuedAt");
+  }
+  const normalizedRevocation = normalizeRevocation(revocation, {
+    issuedAt: normalizedIssuedAt,
+  });
+  const result = {
+    ...jsonClone(report),
+    issuedAt: normalizedIssuedAt,
+    expiresAt: normalizedExpiresAt,
+    revoked: normalizedRevocation.revoked,
+    revocation: normalizedRevocation,
+    bindings: normalizeBindings(bindings),
+    kfdAssessment: jsonClone(kfdAssessment),
+    envelope: {
+      schemaVersion: 1,
+      contract: ARTIFACT_VERIFICATION_ENVELOPE_CONTRACT,
+      canonicalization: "buildchain-stable-json/v1",
+      root: "",
+    },
+  };
+  result.envelope.root = envelopeRoot(result);
+  const check = verifyArtifactVerificationEnvelope({
+    envelope: result,
+    assessmentTime: normalizedRevocation.checkedAt,
+  });
+  if (!check.ok) {
+    throw new Error(`artifact verification envelope is invalid: ${check.issues.map((entry) => entry.code).join(", ")}`);
+  }
+  return result;
+}
+
+export function projectArtifactVerificationEnvelopeToKfx({
+  envelope,
+  assessmentTime = Math.floor(Date.now() / 1000),
+  expectedEnvelopeRoot = "",
+  expectedIssuer = "",
+  expectedPublisher = "",
+  expectedContractVersion = "",
+} = {}) {
+  const check = verifyArtifactVerificationEnvelope({
+    envelope,
+    assessmentTime,
+    expectedEnvelopeRoot,
+    expectedIssuer,
+    expectedPublisher,
+    expectedContractVersion,
+  });
+  if (!check.ok) {
+    throw new Error(`artifact verification envelope failed closed: ${check.issues.map((entry) => entry.code).join(", ")}`);
+  }
+  return {
+    schemaVersion: 1,
+    contract: KFX_ADMISSION_INPUTS_CONTRACT,
+    envelopeRoot: envelope.envelope.root,
+    attestation: jsonClone(envelope),
+    trustInputs: jsonClone(envelope.bindings),
+    kfdAssessment: jsonClone(envelope.kfdAssessment),
+  };
+}

package/packages/core/buildchain-config.js

@@ -1181,7 +1181,7 @@ export function getPublishContract(loadedConfig) {
   return loadedConfig?.config?.publish;
 }
 
-export function runLifecycleStage({ cwd = process.cwd(), loadedConfig, name, stage, env: extraEnv }) {
+export function runLifecycleStage({ cwd = process.cwd(), loadedConfig, name, stage, env: extraEnv, timeoutMinutes }) {
   const lifecycle = loadedConfig?.config?.lifecycle || {};
   const selected = stage || getLifecycleStage(loadedConfig, name);
   if (!selected) {
@@ -1193,7 +1193,11 @@ export function runLifecycleStage({ cwd = process.cwd(), loadedConfig, name, sta
     ...(selected.env || {}),
     ...(extraEnv || {}),
   };
-  const timeout = selected.timeoutMinutes ? selected.timeoutMinutes * 60_000 : undefined;
+  const effectiveTimeoutMinutes = selected.timeoutMinutes ?? timeoutMinutes;
+  if (effectiveTimeoutMinutes !== undefined && (!Number.isFinite(effectiveTimeoutMinutes) || effectiveTimeoutMinutes <= 0)) {
+    throw new Error("lifecycle timeoutMinutes must be a positive number");
+  }
+  const timeout = effectiveTimeoutMinutes ? effectiveTimeoutMinutes * 60_000 : undefined;
   const execOptions = {
     cwd,
     env,

package/packages/core/controller-evidence.js

@@ -344,7 +344,6 @@ export function createControllerReceipt({ plan, stages = [], evidence = [], reas
   const issues = status === "passed"
     ? missingEvidence.map((kind) => `required controller evidence is missing: ${kind}`)
     : [];
-  const qualifying = status === "passed" && plan.qualifying === true && issues.length === 0;
   const receipt = {
     schemaVersion: 1,
     contract: BUILDCHAIN_CONTROLLER_EVIDENCE_CONTRACT,
@@ -354,11 +353,11 @@ export function createControllerReceipt({ plan, stages = [], evidence = [], reas
     runtime: { ...plan.runtime },
     planDigest: plan.digest,
     status,
-    qualifying,
+    qualifying: status === "passed" && plan.qualifying === true && issues.length === 0,
     stages: normalizedStages,
     evidence: normalizedEvidence,
     issues,
-    ...(reason && !qualifying ? {
+    ...(reason ? {
       reason: {
         code: nonEmptyString(reason.code, "reason.code"),
         summary: nonEmptyString(reason.summary, "reason.summary"),

package/packages/core/index.js

@@ -179,6 +179,16 @@ export {
   verifyArtifactPassport,
 } from "./artifact-passport.js";
 
+export {
+  ARTIFACT_VERIFICATION_ENVELOPE_CHECK_CONTRACT,
+  ARTIFACT_VERIFICATION_ENVELOPE_CONTRACT,
+  KFX_ADMISSION_INPUTS_CONTRACT,
+  artifactVerificationEnvelopeDigest,
+  projectArtifactVerificationEnvelopeToKfx,
+  sealArtifactVerificationReport,
+  verifyArtifactVerificationEnvelope,
+} from "./artifact-verification-envelope.js";
+
 export {
   BUILDCHAIN_CONTRACT_LOCK,
   BUILDCHAIN_RUNTIME_CONTRACT_WORLD,

package/packages/core/release-line-bootstrap.js

@@ -65,6 +65,29 @@ function writeJson(value) {
   return `${JSON.stringify(value, null, 2)}\n`;
 }
 
+function updateReleaseImpactVersionState(cwd, plan) {
+  const filePath = path.join(cwd, ".buildchain", "release-impact.json");
+  if (!fs.existsSync(filePath)) {
+    return;
+  }
+  const current = readJsonIfExists(filePath);
+  if (!current || typeof current !== "object" || Array.isArray(current)) {
+    throw new Error(".buildchain/release-impact.json must be a JSON object");
+  }
+  const next = {
+    ...current,
+    release: {
+      ...(current.release && typeof current.release === "object" ? current.release : {}),
+      version: plan.initialVersion,
+      line: plan.line,
+    },
+  };
+  const content = writeJson(next);
+  if (content !== writeJson(current)) {
+    fs.writeFileSync(filePath, content);
+  }
+}
+
 function discoverVersionStateFiles(cwd, loadedConfig) {
   if (loadedConfig?.config?.version?.files?.length) {
     return discoverConfiguredVersionStateFiles(cwd, loadedConfig);
@@ -212,6 +235,7 @@ export function writeReleaseLineBootstrapVersionState({
   for (const file of changed) {
     fs.writeFileSync(path.join(cwd, file.path), file.content);
   }
+  updateReleaseImpactVersionState(cwd, plan);
   const lifecycleVersionState =
     getLifecycleStage(loadedConfig, "version-state") ||
     getLifecycleStage(loadedConfig, "version_state");

package/scripts/check-inventory.mjs

@@ -21,6 +21,7 @@ const requiredPaths = [
   ".github/pull_request_template.md",
   "bin/buildchain.mjs",
   "packages/core/homebrew.js",
+  "packages/core/artifact-verification-envelope.js",
   "packages/core/build-facts.js",
   "packages/core/publication-package.js",
   "packages/core/release-line-bootstrap.js",
@@ -239,6 +240,9 @@ if (rootPackage.exports?.["./buildchain-contract"] !== "./packages/core/buildcha
 if (rootPackage.exports?.["./controller-evidence"] !== "./packages/core/controller-evidence.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/controller-evidence");
 }
+if (rootPackage.exports?.["./artifact-verification-envelope"] !== "./packages/core/artifact-verification-envelope.js") {
+  throw new Error("root package must export @kungfu-tech/buildchain/artifact-verification-envelope");
+}
 if (rootPackage.exports?.["./issue-reporting"] !== "./packages/core/issue-reporting.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/issue-reporting");
 }
@@ -843,6 +847,7 @@ for (const requiredSnippet of [
   "expected-publication-version: ${{ needs.publication-plan.outputs.version }}",
   "publication-version: ${{ needs.publication-plan.outputs.version }}",
   "name: Plan exact publication version",
+  "name: Install exact publication planning dependencies",
   "DRY_RUN: ${{ inputs.dry-run }}",
   "if (dryRun) {",
   "Enforce Buildchain stable release canary gate",

package/scripts/generate-site-bundle.mjs

@@ -444,6 +444,8 @@ function cliCommandMeta(id) {
     "publication-artifact": { group: "reusable-build", purpose: "Generate publication artifact manifests, passports, and source bundles for paper/report repositories." },
     "publication-artifact-manifest": { group: "reusable-build", purpose: "Write a site-consumable publication artifact manifest, publication passport, and source bundle." },
     "publication-artifact-npm-package": { group: "reusable-build", purpose: "Synthesize the declared npm paper package from a publication artifact manifest, passport, registry, source bundle, and primary artifact." },
+    project: { group: "release-passport-trust", purpose: "Inspect read-only consumer projection command families." },
+    "project-kfx-admission": { group: "release-passport-trust", purpose: "Project one verified sealed envelope into direct KFX admission inputs without reconstructing evidence." },
     "release-dry-run": { group: "governance-versioning", purpose: "Explain what a channel merge would publish before the PR is merged." },
     "release-line-open": { group: "governance-versioning", purpose: "Plan or write the initial version-state commit for a new minor release line." },
     "release-propagation": { group: "site-and-propagation", purpose: "Plan channel-preserving downstream release PRs and write exact upstream release locks." },
@@ -455,6 +457,7 @@ function cliCommandMeta(id) {
     validate: { group: "getting-started", purpose: "Validate .buildchain/buildchain.toml and declared lifecycle surfaces." },
     verify: { group: "release-passport-trust", purpose: "Inspect release and artifact verification command families." },
     "verify-artifact": { group: "release-passport-trust", purpose: "Verify artifact subjects against release passport evidence." },
+    "verify-artifact-envelope": { group: "release-passport-trust", purpose: "Verify exact roots, identity, lifecycle, revocation, and an existing KFD assessment in a sealed artifact envelope." },
     "verify-infra-contract-evidence-bundle": { group: "governance-versioning", purpose: "Fail closed unless an infra-contract lifecycle evidence bundle is complete, hash-bound, and validation-consistent." },
     "verify-observability-log": { group: "observability-diagnostics", purpose: "Verify Buildchain observability log events." },
     "verify-publication-admission": { group: "release-passport-trust", purpose: "Independently verify sealed publication admission, runner provenance, control-plane audit, nonce freshness, and exact artifact bindings." },
@@ -485,6 +488,7 @@ function nodeApiMeta(exportName) {
     "./publication-control-plane-audit": { group: "release-passport-trust", summary: "Read-only publication control-plane snapshot evaluation APIs." },
     "./buildchain-publication-authority": { group: "release-passport-trust", summary: "Buildchain-owned closed-world publication authority descriptor registry." },
     "./artifact-passport": { group: "release-passport-trust", summary: "Artifact passport digest and evidence helper APIs." },
+    "./artifact-verification-envelope": { group: "release-passport-trust", summary: "Sealed exact-root, lifecycle, identity, and existing KFD assessment inputs for KFX admission." },
     "./release-passport": { group: "release-passport-trust", summary: "Release passport collection, verification, explanation, and evidence APIs." },
     "./release-candidate": { group: "reusable-build", summary: "PR-stage release-candidate artifact, passport, and promote-only resolver APIs." },
     "./stable-candidate-ledger": { group: "governance-versioning", summary: "Immutable alpha candidate ledger, qualification, revocation, selection, and exact stable source-lock APIs." },

package/scripts/release-candidate-resolver.mjs

@@ -353,6 +353,9 @@ export async function resolveReleaseCandidateArtifacts({
   outputDir = ".buildchain/release-candidate",
   fetchImpl = globalThis.fetch,
   download = true,
+  waitSeconds = 600,
+  pollIntervalMs = 15000,
+  sleepImpl = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
 } = {}) {
   const repoInfo = splitRepository(repository);
   const sha = assertSha(targetSha, "targetSha");
@@ -377,45 +380,63 @@ export async function resolveReleaseCandidateArtifacts({
   if (!pullRequest) {
     throw new Error(`no same-repository merged channel PR found for ${sha} into ${normalizedTarget}`);
   }
-  const runs = await githubJson({
-    apiUrl,
-    token,
-    fetchImpl,
-    path: `/repos/${repoInfo.owner}/${repoInfo.repo}/actions/workflows/${encodeURIComponent(workflowFile)}/runs?event=pull_request&status=success&per_page=100`,
-  });
-  const candidateRuns = selectReleaseCandidateRuns({
-    runs: Array.isArray(runs.workflow_runs) ? runs.workflow_runs : [],
-    pullRequest,
-    workflowName,
-  });
-  if (!candidateRuns.length) {
-    throw new Error(`no successful ${workflowName} pull_request run found for channel PR #${pullRequest.number}`);
+  const timeoutMs = Number(waitSeconds) * 1000;
+  const intervalMs = Number(pollIntervalMs);
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+    throw new Error(`release-candidate waitSeconds must be a non-negative number, got ${waitSeconds}`);
+  }
+  if (!Number.isFinite(intervalMs) || intervalMs < 0) {
+    throw new Error(`release-candidate pollIntervalMs must be a non-negative number, got ${pollIntervalMs}`);
   }
+  const deadline = Date.now() + timeoutMs;
   let run;
   let artifactResponse;
   let selected;
-  const selectionErrors = [];
-  for (const candidateRun of candidateRuns) {
-    const candidateArtifactResponse = await githubJson({
+  let selectionErrors = [];
+  let candidateRuns = [];
+  while (!selected) {
+    const runs = await githubJson({
       apiUrl,
       token,
       fetchImpl,
-      path: `/repos/${repoInfo.owner}/${repoInfo.repo}/actions/runs/${candidateRun.id}/artifacts?per_page=100`,
+      path: `/repos/${repoInfo.owner}/${repoInfo.repo}/actions/workflows/${encodeURIComponent(workflowFile)}/runs?event=pull_request&status=success&per_page=100`,
     });
-    try {
-      selected = selectReleaseCandidateArtifacts({
-        artifacts: Array.isArray(candidateArtifactResponse.artifacts) ? candidateArtifactResponse.artifacts : [],
-        artifactName,
+    candidateRuns = selectReleaseCandidateRuns({
+      runs: Array.isArray(runs.workflow_runs) ? runs.workflow_runs : [],
+      pullRequest,
+      workflowName,
+    });
+    selectionErrors = [];
+    for (const candidateRun of candidateRuns) {
+      const candidateArtifactResponse = await githubJson({
+        apiUrl,
+        token,
+        fetchImpl,
+        path: `/repos/${repoInfo.owner}/${repoInfo.repo}/actions/runs/${candidateRun.id}/artifacts?per_page=100`,
       });
-      run = candidateRun;
-      artifactResponse = candidateArtifactResponse;
-      break;
-    } catch (error) {
-      selectionErrors.push(`run ${candidateRun.id}: ${error.message}`);
+      try {
+        selected = selectReleaseCandidateArtifacts({
+          artifacts: Array.isArray(candidateArtifactResponse.artifacts) ? candidateArtifactResponse.artifacts : [],
+          artifactName,
+        });
+        run = candidateRun;
+        artifactResponse = candidateArtifactResponse;
+        break;
+      } catch (error) {
+        selectionErrors.push(`run ${candidateRun.id}: ${error.message}`);
+      }
     }
-  }
-  if (!run || !artifactResponse || !selected) {
-    throw new Error(`no successful ${workflowName} pull_request run for channel PR #${pullRequest.number} contained release-candidate artifacts: ${selectionErrors.join("; ")}`);
+    if (selected) break;
+    if (Date.now() >= deadline) {
+      if (!candidateRuns.length) {
+        throw new Error(`no successful ${workflowName} pull_request run found for channel PR #${pullRequest.number} within ${waitSeconds}s`);
+      }
+      throw new Error(`no successful ${workflowName} pull_request run for channel PR #${pullRequest.number} contained release-candidate artifacts within ${waitSeconds}s: ${selectionErrors.join("; ")}`);
+    }
+    console.log(
+      `> waiting for successful ${workflowName} release-candidate evidence for channel PR #${pullRequest.number}`,
+    );
+    await sleepImpl(intervalMs);
   }
   const payloadArtifacts = selectPayloadArtifacts({
     artifacts: Array.isArray(artifactResponse.artifacts) ? artifactResponse.artifacts : [],
@@ -551,6 +572,8 @@ export async function resolveReleaseCandidateArtifactsCli() {
     publishPackageMain: env("BUILDCHAIN_PUBLISH_PACKAGE_MAIN"),
     outputDir: env("BUILDCHAIN_RC_OUTPUT_DIR", ".buildchain/release-candidate"),
     download: releaseCandidateDownloadEnabled(env("BUILDCHAIN_RC_DOWNLOAD", "true")),
+    waitSeconds: env("BUILDCHAIN_RC_WAIT_SECONDS", "600"),
+    pollIntervalMs: env("BUILDCHAIN_RC_POLL_INTERVAL_MS", "15000"),
   });
   writeGitHubOutputs({
     "promote-only-release-candidate": String(result.enabled === true),