@kungfu-tech/buildchain 4.1.0-alpha.0 → 4.1.0-alpha.1

package/packages/core/release/recovery/capsules.js

@@ -1,6 +1,6 @@
 import { domainContentRoot } from "../../contracts/canonical-contracts.js";
 import { validateStageCapsule } from "../../build/stage-capsule.js";
-import { runtimeResumeDocumentRoot } from "../../consumer/runtime-ref-resume-authority.js";
+import { runtimeResumeDocumentRoot } from "./lineage.js";
 export function verifyReleaseCandidateStageCapsules({
   sidecar,
   passport,
@@ -25,7 +25,6 @@ export function verifyReleaseCandidateStageCapsules({
     sidecar.source?.sha !== passport.source.headSha ||
     sidecar.source?.treeSha !== passport.source.treeHash ||
     sidecar.buildAttempt?.id !== expectedAttempt ||
-    sidecar.buildAttempt?.runtimeSha !== passport.buildchain.sha ||
     sidecar.consumerPolicyReceiptRoot !== passport.consumerPolicy?.receiptRoot
   ) {
     throw new Error(
@@ -66,11 +65,7 @@ export function verifyReleaseCandidateStageCapsules({
         new Date(download.artifact.expires_at).toISOString() ||
       entry.capsule.identity.policyRoot !== sidecar.consumerPolicyReceiptRoot ||
       entry.capsule.identity.sourceRoot !==
-        domainContentRoot("candidate-identity", passport.source) ||
-      entry.capsule.identity.runtimeRoot !==
-        domainContentRoot("candidate-identity", {
-          sha: passport.buildchain.sha,
-        })
+        domainContentRoot("candidate-identity", passport.source)
     ) {
       throw new Error(
         `Stage Capsule ${entry.platform} does not bind the verified provider artifact`,
@@ -91,12 +86,9 @@ export function verifyReleaseCandidateStageCapsules({
 }
 
 export function resolveRecoveredStageCapsules({
-  candidateRuntimeSha,
-  runtimeSha,
   sidecar,
   passport,
   downloads,
 }) {
-  if (candidateRuntimeSha === runtimeSha) return [];
   return verifyReleaseCandidateStageCapsules({ sidecar, passport, downloads });
 }

package/packages/core/release/recovery/lineage.js

@@ -0,0 +1,305 @@
+import crypto from "node:crypto";
+export const RUNTIME_RESUME_LINEAGE_CONTRACT =
+  "buildchain.runtime-resume-lineage/v2";
+const EXACT_SHA = /^[0-9a-f]{40}$/u;
+const SHA256_ROOT = /^sha256:[0-9a-f]{64}$/u;
+const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:/-]*$/u;
+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);
+}
+
+export function runtimeResumeDocumentRoot(value) {
+  return `sha256:${crypto.createHash("sha256").update(stableJson(value)).digest("hex")}`;
+}
+
+function exactSha(value, label) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (!EXACT_SHA.test(normalized)) {
+    throw new Error(`${label} must be an exact 40-character Git SHA`);
+  }
+  return normalized;
+}
+
+function root(value, label) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (!SHA256_ROOT.test(normalized)) {
+    throw new Error(`${label} must be a sha256 content root`);
+  }
+  return normalized;
+}
+
+function nonEmpty(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${label} must be non-empty`);
+  return normalized;
+}
+
+function token(value, label) {
+  const normalized = nonEmpty(value, label);
+  if (!TOKEN.test(normalized)) {
+    throw new Error(`${label} must be an ASCII identity token`);
+  }
+  return normalized;
+}
+
+function exactKeys(value, expected, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  const actual = Object.keys(value).sort();
+  const canonical = [...expected].sort();
+  if (
+    actual.length !== canonical.length ||
+    actual.some((key, index) => key !== canonical[index])
+  ) {
+    throw new Error(`${label} has an invalid field set`);
+  }
+}
+
+function sortedUnique(values, label) {
+  if (!Array.isArray(values) || values.length === 0) {
+    throw new Error(`${label} must be a non-empty array`);
+  }
+  const normalized = values.map((value, index) =>
+    token(value, `${label}[${index}]`),
+  );
+  const expected = [...new Set(normalized)].sort((left, right) =>
+    Buffer.from(left).compare(Buffer.from(right)),
+  );
+  if (
+    normalized.length !== expected.length ||
+    normalized.some((value, index) => value !== expected[index])
+  ) {
+    throw new Error(`${label} must be byte-sorted and duplicate-free`);
+  }
+  return normalized;
+}
+
+export function createRuntimeResumeLineage({
+  repository,
+  buildAttempt,
+  resumeAttempt,
+  source,
+  consumerPolicyReceiptRoot,
+  requiredPlatforms,
+  stageCapsules,
+  resumePlanRoot,
+  finalPublicReadbackRoot,
+} = {}) {
+  const buildId = token(buildAttempt?.id, "buildAttempt.id");
+  const resumeId = token(resumeAttempt?.id, "resumeAttempt.id");
+  if (buildId === resumeId) {
+    throw new Error("resume must create a new governed attempt");
+  }
+  const buildRuntimeSha = buildAttempt?.runtimeSha;
+  const resumeRuntimeSha = resumeAttempt?.runtimeSha;
+  const sourceIdentity = {
+    sha: exactSha(source?.sha, "source.sha"),
+    treeSha: exactSha(source?.treeSha, "source.treeSha"),
+  };
+  const policyRoot = root(
+    consumerPolicyReceiptRoot,
+    "consumerPolicyReceiptRoot",
+  );
+  const platforms = sortedUnique(requiredPlatforms, "requiredPlatforms");
+  if (!Array.isArray(stageCapsules))
+    throw new Error("stageCapsules must be an array");
+  const capsuleByPlatform = new Map();
+  for (const [index, capsule] of stageCapsules.entries()) {
+    exactKeys(
+      capsule,
+      [
+        "platform",
+        "capsuleRoot",
+        "identityRoot",
+        "artifactDigest",
+        "sourceSha",
+        "sourceTreeSha",
+        "policyRoot",
+        "buildRuntimeSha",
+        "sealed",
+      ],
+      `stageCapsules[${index}]`,
+    );
+    const platform = token(
+      capsule.platform,
+      `stageCapsules[${index}].platform`,
+    );
+    if (!platforms.includes(platform)) {
+      throw new Error(`stageCapsules[${index}] names an undeclared platform`);
+    }
+    if (capsuleByPlatform.has(platform)) {
+      throw new Error(`duplicate Stage Capsule for ${platform}`);
+    }
+    if (capsule.sealed !== true)
+      throw new Error(`Stage Capsule ${platform} is not sealed`);
+    if (
+      exactSha(capsule.sourceSha, `${platform}.sourceSha`) !==
+        sourceIdentity.sha ||
+      exactSha(capsule.sourceTreeSha, `${platform}.sourceTreeSha`) !==
+        sourceIdentity.treeSha ||
+      root(capsule.policyRoot, `${platform}.policyRoot`) !== policyRoot
+    ) {
+      throw new Error(
+        `Stage Capsule ${platform} identity is stale or ambiguous`,
+      );
+    }
+    capsuleByPlatform.set(platform, {
+      platform,
+      capsuleRoot: root(capsule.capsuleRoot, `${platform}.capsuleRoot`),
+      identityRoot: root(capsule.identityRoot, `${platform}.identityRoot`),
+      artifactDigest: root(
+        capsule.artifactDigest,
+        `${platform}.artifactDigest`,
+      ),
+    });
+  }
+  const reusedCapsules = platforms
+    .filter((platform) => capsuleByPlatform.has(platform))
+    .map((platform) => capsuleByPlatform.get(platform));
+  const rebuildPlatforms = platforms.filter(
+    (platform) => !capsuleByPlatform.has(platform),
+  );
+  const lineage = {
+    schemaVersion: 2,
+    contract: RUNTIME_RESUME_LINEAGE_CONTRACT,
+    status: "qualified",
+    repository: nonEmpty(repository, "repository"),
+    source: sourceIdentity,
+    consumerPolicyReceiptRoot: policyRoot,
+    attempts: {
+      build: { id: buildId, runtimeSha: buildRuntimeSha },
+      resume: { id: resumeId, runtimeSha: resumeRuntimeSha },
+    },
+
+    continuation: {
+      mechanism: "new-governed-attempt",
+      rerunFailedJobs: false,
+      resumePlanRoot: root(resumePlanRoot, "resumePlanRoot"),
+    },
+    stageCapsules: {
+      requiredPlatforms: platforms,
+      reused: reusedCapsules,
+      rebuildPlatforms,
+    },
+    finalPublicReadbackRoot: root(
+      finalPublicReadbackRoot,
+      "finalPublicReadbackRoot",
+    ),
+  };
+  return { lineage, lineageRoot: runtimeResumeDocumentRoot(lineage) };
+}
+
+function validSourceIdentity(source) {
+  return (
+    EXACT_SHA.test(String(source?.sha || "")) &&
+    EXACT_SHA.test(String(source?.treeSha || ""))
+  );
+}
+
+function platformLineageFailures(stageCapsules) {
+  const failures = [];
+  const required = stageCapsules?.requiredPlatforms || [];
+  const reused = stageCapsules?.reused || [];
+  const rebuilt = stageCapsules?.rebuildPlatforms || [];
+  const requiredCanonical = [...new Set(required)].sort();
+  const reusedPlatforms = reused.map((entry) => entry.platform);
+  const rebuiltCanonical = [...new Set(rebuilt)].sort();
+  if (
+    required.length === 0 ||
+    required.length !== requiredCanonical.length ||
+    !required.every((platform, index) => platform === requiredCanonical[index])
+  ) {
+    failures.push("required-platforms-invalid");
+  }
+  if (
+    reusedPlatforms.length !== new Set(reusedPlatforms).size ||
+    rebuilt.length !== rebuiltCanonical.length ||
+    !reusedPlatforms.every((platform) => !rebuilt.includes(platform))
+  ) {
+    failures.push("platform-lineage-ambiguous");
+  }
+  if (
+    [...reusedPlatforms, ...rebuilt].sort().join("\0") !==
+    [...required].sort().join("\0")
+  ) {
+    failures.push("platform-lineage-incomplete");
+  }
+  if (
+    !reused.every((entry) =>
+      [entry.capsuleRoot, entry.identityRoot, entry.artifactDigest].every(
+        (value) => SHA256_ROOT.test(String(value || "")),
+      ),
+    )
+  ) {
+    failures.push("capsule-root-invalid");
+  }
+  return failures;
+}
+
+export function verifyRuntimeResumeLineage({
+  lineage,
+  lineageRoot,
+  repository = "",
+  sourceSha = "",
+  consumerPolicyReceiptRoot = "",
+} = {}) {
+  const failures = [];
+  const check = (condition, code) => {
+    if (!condition) failures.push(code);
+  };
+  check(
+    lineage?.contract === RUNTIME_RESUME_LINEAGE_CONTRACT,
+    "contract-invalid",
+  );
+  check(lineage?.status === "qualified", "status-not-qualified");
+  check(
+    SHA256_ROOT.test(String(lineageRoot || "")) &&
+      lineageRoot === runtimeResumeDocumentRoot(lineage),
+    "lineage-root-mismatch",
+  );
+  check(
+    lineage?.attempts?.build?.id &&
+      lineage?.attempts?.resume?.id &&
+      lineage.attempts.build.id !== lineage.attempts.resume.id,
+    "attempt-not-fresh",
+  );
+  check(validSourceIdentity(lineage?.source), "source-identity-invalid");
+  check(
+    lineage?.continuation?.mechanism === "new-governed-attempt" &&
+      lineage?.continuation?.rerunFailedJobs === false,
+    "continuation-mechanism-invalid",
+  );
+  failures.push(...platformLineageFailures(lineage?.stageCapsules));
+  check(
+    [
+      lineage?.consumerPolicyReceiptRoot,
+      lineage?.continuation?.resumePlanRoot,
+      lineage?.finalPublicReadbackRoot,
+    ].every((value) => SHA256_ROOT.test(String(value || ""))),
+    "evidence-root-invalid",
+  );
+  if (sourceSha)
+    check(lineage?.source?.sha === sourceSha, "source-sha-mismatch");
+  if (consumerPolicyReceiptRoot) {
+    check(
+      lineage?.consumerPolicyReceiptRoot === consumerPolicyReceiptRoot,
+      "consumer-policy-root-mismatch",
+    );
+  }
+  if (repository) {
+    check(lineage?.repository === repository, "repository-mismatch");
+  }
+  return { ok: failures.length === 0, failures };
+}

package/packages/core/release/recovery/provenance.js

@@ -36,8 +36,7 @@ export function resolveAnchorRecoveryRequest({
     !/^[0-9a-f]{40}$/u.test(String(request.supersededCandidate?.sha || "")) ||
     !/^sha256:[0-9a-f]{64}$/u.test(
       String(request.supersededCandidate?.root || ""),
-    ) ||
-    request.runtime?.sha !== passport.buildchain?.sha
+    )
   ) {
     throw new Error(
       "anchored candidate request does not bind the sealed recovery identity",

package/packages/core/release/recovery/publication.js

@@ -13,20 +13,14 @@ export function createRecoveredPublicationCandidate({
   allFiles,
   repository,
   passport,
-  candidateRuntimeSha,
 }) {
-  if (passport.buildchain?.sha !== candidateRuntimeSha) {
-    throw new Error(
-      `recovered publication candidate runtime mismatch: passport=${passport.buildchain?.sha || "<empty>"} expected=${candidateRuntimeSha || "<empty>"}`,
-    );
-  }
   const payload = {
     schemaVersion: 1,
     contract: PUBLICATION_ARTIFACT_CANDIDATE_CONTRACT,
     repository,
     sourceSha: passport.source.headSha,
     sourceTreeSha: passport.source.treeHash,
-    runtimeSha: candidateRuntimeSha,
+    runtimeSha: passport.buildchain?.sha,
     releaseCandidateRoot: `sha256:${passport.candidateHash}`,
     files: allFiles.map(({ path: filePath, size, sha256 }) => ({
       path: filePath,
@@ -45,7 +39,6 @@ export function createRecoveredPublication({
   bundleRoot,
   repository,
   passport,
-  candidateRuntimeSha,
   publishArtifactKind,
   publishPackageMain,
   releasePatterns,
@@ -78,8 +71,7 @@ export function createRecoveredPublication({
       allFiles,
       repository,
       passport,
-      candidateRuntimeSha,
-    });
+        });
     const sealed = resolveOciCandidate({ payloadRoot: bundleRoot, passport });
     return {
       manifest: sealed.manifest,
@@ -97,8 +89,7 @@ export function createRecoveredPublication({
       allFiles,
       repository,
       passport,
-      candidateRuntimeSha,
-    });
+        });
     const version = String(passport.target?.version || "").trim();
     if (!version)
       throw new Error(
@@ -163,8 +154,7 @@ export function createRecoveredPublication({
     allFiles,
     repository,
     passport,
-    candidateRuntimeSha,
-  });
+    });
   const manifest = createPublicationSealedBundle({
     candidate,
     packageName: main.metadata.name,

package/packages/core/release/recovery/readback.js

@@ -1,23 +1,22 @@
 import path from "node:path";
 import { compareSemver } from "../../publication/candidate/registry-hydration.js";
 import { githubJson } from "./../candidate/transport.js";
-import { runtimeResumeDocumentRoot } from "../../consumer/runtime-ref-resume-authority.js";
+import { runtimeResumeDocumentRoot } from "./lineage.js";
 export function validateRuntimeResumePublicReadback({
   targetRef,
   targetSha,
   targetVersion,
-  alphaSha,
+  floatingSha,
   exactTagSha,
   tagLineage,
-  runtimeLineage,
   floatingTargetLineage,
-  runtimeSha,
   version,
   transaction,
   main,
   npm,
 }) {
-  const channelVersion = npm["dist-tags"]?.alpha;
+  const distTag = version.includes("-") ? "alpha" : "latest";
+  const channelVersion = npm["dist-tags"]?.[distTag];
   let channelDidNotRegress = false;
   try {
     channelDidNotRegress = compareSemver(channelVersion, version) >= 0;
@@ -29,18 +28,16 @@ export function validateRuntimeResumePublicReadback({
     transaction?.version !== version ||
     exactTagSha !== transaction?.source_sha ||
     !["ahead", "identical"].includes(tagLineage?.status) ||
-    !["ahead", "identical"].includes(runtimeLineage?.status) ||
     !["ahead", "identical"].includes(floatingTargetLineage?.status) ||
-    !alphaSha ||
+    !floatingSha ||
     !targetSha ||
-    !runtimeSha ||
     channelVersion !== targetVersion ||
     !channelDidNotRegress ||
     !npm.versions?.[channelVersion]?.dist?.integrity ||
     npm.versions?.[version]?.dist?.integrity !== main.digest
   ) {
     throw new Error(
-      "cross-runtime final public readback does not match durable publication bytes and runtime",
+      "cross-runtime final public readback does not match durable publication bytes",
     );
   }
 }
@@ -48,7 +45,6 @@ export function validateRuntimeResumePublicReadback({
 export async function readPublicResumeState({
   repoInfo,
   targetRef,
-  runtimeSha,
   version,
   transaction,
   token,
@@ -73,9 +69,11 @@ export async function readPublicResumeState({
     );
   const packageUrl = `https://registry.npmjs.org/${encodeURIComponent(main.name)}`;
   const exactTag = transaction.exact_tag || `v${version}`;
-  const [targetSha, alphaSha, exactTagSha, npmResponse] = await Promise.all([
+  const floatingRef = `v${version.split(".")[0]}${version.includes("-") ? "-alpha" : ""}`;
+  const distTag = version.includes("-") ? "alpha" : "latest";
+  const [targetSha, floatingSha, exactTagSha, npmResponse] = await Promise.all([
     readRef(`heads/${targetRef}`),
-    readRef("tags/v4-alpha"),
+    readRef(`tags/${floatingRef}`),
     readRef(`tags/${exactTag}`),
     fetchImpl(packageUrl),
   ]);
@@ -85,7 +83,7 @@ export async function readPublicResumeState({
     );
   }
   const npm = await npmResponse.json();
-  const [tagLineage, runtimeLineage, floatingTargetLineage, targetPackageFile] =
+  const [tagLineage, floatingTargetLineage, targetPackageFile] =
     await Promise.all([
       githubJson({
         apiUrl,
@@ -97,13 +95,7 @@ export async function readPublicResumeState({
         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}`,
+        path: `/repos/${repoInfo.owner}/${repoInfo.repo}/compare/${floatingSha}...${targetSha}`,
       }),
       githubJson({
         apiUrl,
@@ -130,13 +122,11 @@ export async function readPublicResumeState({
     targetRef,
     targetSha,
     targetVersion,
-    alphaSha,
+    floatingSha,
     exactTagSha,
     tagLineage,
-    runtimeLineage,
-    floatingTargetLineage,
-    runtimeSha,
-    version,
+      floatingTargetLineage,
+      version,
     transaction,
     main,
     npm,
@@ -149,21 +139,18 @@ export async function readPublicResumeState({
     version,
     refs: {
       target: { ref: targetRef, sha: targetSha },
-      floating: { ref: "v4-alpha", sha: alphaSha },
+      floating: { ref: floatingRef, sha: floatingSha },
       exactTag: { ref: exactTag, sha: exactTagSha },
     },
     npm: {
       package: main.name,
       version,
-      distTag: "alpha",
+      distTag,
       integrity: npm.versions[version].dist.integrity,
       targetVersion,
-      distTagVersion: npm["dist-tags"].alpha,
-      distTagIntegrity: npm.versions[npm["dist-tags"].alpha].dist.integrity,
+      distTagVersion: npm["dist-tags"][distTag],
+      distTagIntegrity: npm.versions[npm["dist-tags"][distTag]].dist.integrity,
     },
   };
   return { ...body, root: runtimeResumeDocumentRoot(body) };
 }
-
-export const resolveRuntimeResumePublicRuntimeSha = (material) =>
-  material?.buildAttempt?.runtimeSha || "";