@kungfu-tech/buildchain 3.0.9-alpha.0 → 3.0.9-alpha.2

package/packages/core/release-blocker-priority.js

@@ -0,0 +1,192 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+  devDeliveryContentRoot,
+  devDeliveryExactRoot as exactRoot,
+  devDeliveryExactSha as exactSha,
+  devDeliveryPositiveInteger as positiveInteger,
+  devDeliveryProtectedBase as protectedBase,
+  devDeliveryRepository as repository,
+  devDeliveryText as text,
+  devDeliveryTimestamp as timestamp,
+} from "./dev-delivery-common.js";
+import { validateReleaseBlockerRepair } from "./release-train.js";
+
+export const RELEASE_BLOCKER_PRIORITY_CLAIM_SCHEMA =
+  "kungfu.buildchain.release-blocker-priority-claim/v1";
+
+function exactFields(value, fields, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  const actual = Object.keys(value).sort();
+  const expected = [...fields].sort();
+  if (
+    actual.length !== expected.length ||
+    actual.some((field, index) => field !== expected[index])
+  ) {
+    throw new Error(`${label} has an invalid field set`);
+  }
+}
+
+export function createReleaseBlockerPriorityClaim(repairInput, input = {}) {
+  const repair = validateReleaseBlockerRepair(repairInput);
+  if (!repair.publication.eligible || repair.devLanding.status !== "landed") {
+    throw new Error(
+      "release-blocker priority requires an exact settled dev landing",
+    );
+  }
+  const body = {
+    schema: RELEASE_BLOCKER_PRIORITY_CLAIM_SCHEMA,
+    repository: repository(repair.successorTrain.releaseCut.repository),
+    protectedBase: protectedBase(repair.successorTrain.releaseCut.sourceBranch),
+    assignmentRoot: exactRoot(input.assignmentRoot, "assignmentRoot"),
+    initiativeRoot: exactRoot(input.initiativeRoot, "initiativeRoot"),
+    repairRoot: exactRoot(repair.repairRoot, "repairRoot"),
+    priorCutRoot: exactRoot(
+      repair.priorTrain.releaseCut.cutRoot,
+      "priorCutRoot",
+    ),
+    successorCutRoot: exactRoot(
+      repair.successorTrain.releaseCut.cutRoot,
+      "successorCutRoot",
+    ),
+    candidateGeneration: positiveInteger(
+      repair.successorTrain.releaseCut.generation,
+      "candidateGeneration",
+    ),
+    cutCandidateSha: exactSha(repair.cutLanding.landedSha, "cutCandidateSha"),
+    sourceHead: exactSha(repair.devLanding.landedSha, "sourceHead"),
+    sourcePatchRoot: exactRoot(repair.patchRoot, "sourcePatchRoot"),
+    cutLandingEvidenceRoot: exactRoot(
+      repair.cutLanding.evidenceRoot,
+      "cutLandingEvidenceRoot",
+    ),
+    devLandingEvidenceRoot: exactRoot(
+      repair.devLanding.evidenceRoot,
+      "devLandingEvidenceRoot",
+    ),
+    publicationGateRoot: exactRoot(
+      repair.publication.gateRoot,
+      "publicationGateRoot",
+    ),
+    issuedAt: timestamp(input.issuedAt, "issuedAt"),
+  };
+  return { ...body, claimRoot: devDeliveryContentRoot(body) };
+}
+
+export function normalizeReleaseBlockerPriorityClaim(
+  input,
+  candidate,
+  expected,
+) {
+  exactFields(
+    input,
+    [
+      "schema",
+      "repository",
+      "protectedBase",
+      "assignmentRoot",
+      "initiativeRoot",
+      "repairRoot",
+      "priorCutRoot",
+      "successorCutRoot",
+      "candidateGeneration",
+      "cutCandidateSha",
+      "sourceHead",
+      "sourcePatchRoot",
+      "cutLandingEvidenceRoot",
+      "devLandingEvidenceRoot",
+      "publicationGateRoot",
+      "issuedAt",
+      "claimRoot",
+    ],
+    "releaseBlockerPriority",
+  );
+  const body = {
+    schema: text(input.schema),
+    repository: repository(input.repository),
+    protectedBase: protectedBase(input.protectedBase),
+    assignmentRoot: exactRoot(
+      input.assignmentRoot,
+      "releaseBlockerPriority.assignmentRoot",
+    ),
+    initiativeRoot: exactRoot(
+      input.initiativeRoot,
+      "releaseBlockerPriority.initiativeRoot",
+    ),
+    repairRoot: exactRoot(
+      input.repairRoot,
+      "releaseBlockerPriority.repairRoot",
+    ),
+    priorCutRoot: exactRoot(
+      input.priorCutRoot,
+      "releaseBlockerPriority.priorCutRoot",
+    ),
+    successorCutRoot: exactRoot(
+      input.successorCutRoot,
+      "releaseBlockerPriority.successorCutRoot",
+    ),
+    candidateGeneration: positiveInteger(
+      input.candidateGeneration,
+      "releaseBlockerPriority.candidateGeneration",
+    ),
+    cutCandidateSha: exactSha(
+      input.cutCandidateSha,
+      "releaseBlockerPriority.cutCandidateSha",
+    ),
+    sourceHead: exactSha(input.sourceHead, "releaseBlockerPriority.sourceHead"),
+    sourcePatchRoot: exactRoot(
+      input.sourcePatchRoot,
+      "releaseBlockerPriority.sourcePatchRoot",
+    ),
+    cutLandingEvidenceRoot: exactRoot(
+      input.cutLandingEvidenceRoot,
+      "releaseBlockerPriority.cutLandingEvidenceRoot",
+    ),
+    devLandingEvidenceRoot: exactRoot(
+      input.devLandingEvidenceRoot,
+      "releaseBlockerPriority.devLandingEvidenceRoot",
+    ),
+    publicationGateRoot: exactRoot(
+      input.publicationGateRoot,
+      "releaseBlockerPriority.publicationGateRoot",
+    ),
+    issuedAt: timestamp(input.issuedAt, "releaseBlockerPriority.issuedAt"),
+  };
+  if (body.schema !== RELEASE_BLOCKER_PRIORITY_CLAIM_SCHEMA) {
+    throw new Error("releaseBlockerPriority schema is unsupported");
+  }
+  if (input.claimRoot !== devDeliveryContentRoot(body)) {
+    throw new Error("releaseBlockerPriority claimRoot drift");
+  }
+  if (
+    body.repository !== expected.repository ||
+    body.protectedBase !== expected.protectedBase
+  ) {
+    throw new Error("releaseBlockerPriority queue route mismatch");
+  }
+  if (
+    body.assignmentRoot !== candidate.assignmentRoot ||
+    body.initiativeRoot !== candidate.initiativeRoot
+  ) {
+    throw new Error("releaseBlockerPriority Work identity mismatch");
+  }
+  if (
+    body.sourceHead !== candidate.sourceHead ||
+    body.sourcePatchRoot !== candidate.sourcePatchRoot
+  ) {
+    throw new Error("releaseBlockerPriority source identity mismatch");
+  }
+  return { ...body, claimRoot: input.claimRoot };
+}
+
+export function compareReleaseBlockerPriority(left, right) {
+  const leftBlocker =
+    left.priority.releaseBlocker && left.candidate.priority === "ordinary";
+  const rightBlocker =
+    right.priority.releaseBlocker && right.candidate.priority === "ordinary";
+  if (leftBlocker === rightBlocker) return 0;
+  const peer = leftBlocker ? right : left;
+  return peer.candidate.priority === "ordinary" ? (leftBlocker ? -1 : 1) : 0;
+}

package/packages/core/release-train.js

@@ -8,6 +8,8 @@ export const RELEASE_TRAIN_TRANSITION_CONTRACT =
   "kungfu-buildchain-release-train-transition/v1";
 export const RELEASE_TRAIN_OBSERVATION_CONTRACT =
   "kungfu-buildchain-release-train-observation/v1";
+export const RELEASE_BLOCKER_REPAIR_CONTRACT =
+  "kungfu-buildchain-release-blocker-repair/v1";
 export const LEGACY_DEV_ALPHA_CANDIDATE_STATE_SCHEMA =
   "kungfu-buildchain-dev-alpha-candidate-state/v1";
 
@@ -22,6 +24,7 @@ export const RELEASE_TRAIN_STATES = Object.freeze([
 ]);
 
 export const RELEASE_TRAIN_SUPERSESSION_CAUSES = Object.freeze([
+  "release-blocker-repair",
   "incompatible-semantics",
   "alpha-base-incompatibility",
   "invalid-authority",
@@ -518,3 +521,220 @@ export function readReleaseTrain(input) {
   }
   throw new Error("unsupported Release Train record");
 }
+
+function releaseBlockerLanding(input, label, { allowConflict = false } = {}) {
+  const status = text(input?.status, `${label}.status`);
+  if (status !== "landed" && !(allowConflict && status === "conflict")) {
+    throw new Error(
+      `${label}.status must be ${allowConflict ? "landed or conflict" : "landed"}`,
+    );
+  }
+  const landing = {
+    status,
+    baseSha: exactSha(input.baseSha, `${label}.baseSha`),
+    landedSha:
+      status === "landed"
+        ? exactSha(input.landedSha, `${label}.landedSha`)
+        : "",
+    patchRoot: contentRoot(input.patchRoot, `${label}.patchRoot`),
+    evidenceRoot: contentRoot(input.evidenceRoot, `${label}.evidenceRoot`),
+  };
+  return landing;
+}
+
+function releaseBlockerPublication(patchRoot, devLanding) {
+  const eligible =
+    devLanding.status === "landed" && devLanding.patchRoot === patchRoot;
+  const body = {
+    eligible,
+    reason:
+      devLanding.status === "conflict"
+        ? "dev-forward-port-conflict"
+        : eligible
+          ? "exact-cut-dev-patch-settled"
+          : "cut-dev-patch-root-mismatch",
+    requiredPatchRoot: patchRoot,
+    observedDevPatchRoot: devLanding.patchRoot,
+    devLandingStatus: devLanding.status,
+  };
+  return { ...body, gateRoot: releaseTrainRoot(body) };
+}
+
+function buildReleaseBlockerRepair(activeTrainInput, input = {}) {
+  const activeTrain = validateReleaseTrain(activeTrainInput);
+  if (activeTrain.state.status !== "repair-required") {
+    throw new Error(
+      "release-blocker repair requires the active train to be repair-required",
+    );
+  }
+  const expectedStateRoot = contentRoot(
+    input.expectedStateRoot,
+    "expectedStateRoot",
+  );
+  if (expectedStateRoot !== activeTrain.state.stateRoot) {
+    throw new Error("release-blocker repair compare-and-swap failed");
+  }
+  const patchRoot = contentRoot(input.patchRoot, "patchRoot");
+  const blockerRoot = contentRoot(input.blockerRoot, "blockerRoot");
+  const authorityRoots = sortedRoots(input.authorityRoots, "authorityRoots");
+  const createdAt = timestamp(input.createdAt, "createdAt");
+  const cutLanding = releaseBlockerLanding(
+    {
+      status: "landed",
+      baseSha: activeTrain.releaseCut.candidateSha,
+      landedSha: input.cutCandidateSha,
+      patchRoot: input.cutPatchRoot,
+      evidenceRoot: input.cutLandingEvidenceRoot,
+    },
+    "cutLanding",
+  );
+  if (cutLanding.patchRoot !== patchRoot) {
+    throw new Error(
+      "cut landing must preserve the declared release-blocker patch root",
+    );
+  }
+  const devLanding = releaseBlockerLanding(
+    {
+      status: input.devLandingStatus,
+      baseSha: input.devBaseSha,
+      landedSha: input.devLandingSha,
+      patchRoot: input.devPatchRoot,
+      evidenceRoot: input.devLandingEvidenceRoot,
+    },
+    "devLanding",
+    { allowConflict: true },
+  );
+  const priorCut = activeTrain.releaseCut;
+  const successorTrain = createReleaseTrain({
+    repository: priorCut.repository,
+    sourceBranch: priorCut.sourceBranch,
+    targetBranch: priorCut.targetBranch,
+    originDevSha: priorCut.originDevSha,
+    candidateSha: cutLanding.landedSha,
+    candidateTreeSha: exactSha(
+      input.cutCandidateTreeSha,
+      "cutCandidateTreeSha",
+    ),
+    alphaBaseSha: priorCut.alphaBaseSha,
+    buildchainRuntimeSha: priorCut.buildchainRuntimeSha,
+    generation: priorCut.generation + 1,
+    authorityRoots: [
+      ...new Set([...priorCut.authorityRoots, ...authorityRoots]),
+    ].sort(),
+    supersession: {
+      cause: "release-blocker-repair",
+      priorCutRoot: priorCut.cutRoot,
+    },
+    createdAt,
+  });
+  const supersededTrain = transitionReleaseTrain(activeTrain, {
+    to: "superseded",
+    expectedStateRoot,
+    event: "release-blocker-successor-cut",
+    reason:
+      "a rooted release-blocker repair advanced the active candidate generation",
+    authorityRoots,
+    supersessionCause: "release-blocker-repair",
+    replacementCutRoot: successorTrain.releaseCut.cutRoot,
+    replacementCandidateSha: successorTrain.releaseCut.candidateSha,
+    recordedAt: createdAt,
+  });
+  const publication = releaseBlockerPublication(patchRoot, devLanding);
+  const body = {
+    schemaVersion: 1,
+    contract: RELEASE_BLOCKER_REPAIR_CONTRACT,
+    blockerRoot,
+    patchRoot,
+    priorTrain: activeTrain,
+    supersededTrain,
+    successorTrain,
+    cutLanding,
+    devLanding,
+    candidateBuild: {
+      eligible: true,
+      candidateSha: successorTrain.releaseCut.candidateSha,
+      candidateTreeSha: successorTrain.releaseCut.candidateTreeSha,
+      generation: successorTrain.releaseCut.generation,
+      cutRoot: successorTrain.releaseCut.cutRoot,
+      reason: "rooted-cut-landing",
+    },
+    publication,
+    authorityRoots,
+    createdAt,
+  };
+  return { ...body, repairRoot: releaseTrainRoot(body) };
+}
+
+export function createReleaseBlockerRepair(activeTrainInput, input = {}) {
+  return buildReleaseBlockerRepair(activeTrainInput, input);
+}
+
+export function validateReleaseBlockerRepair(input) {
+  if (
+    input?.contract !== RELEASE_BLOCKER_REPAIR_CONTRACT ||
+    Number(input?.schemaVersion) !== 1
+  ) {
+    throw new Error(
+      `release-blocker repair must use ${RELEASE_BLOCKER_REPAIR_CONTRACT}`,
+    );
+  }
+  const rebuilt = buildReleaseBlockerRepair(input.priorTrain, {
+    expectedStateRoot: input.priorTrain?.state?.stateRoot,
+    blockerRoot: input.blockerRoot,
+    patchRoot: input.patchRoot,
+    cutCandidateSha: input.cutLanding?.landedSha,
+    cutCandidateTreeSha: input.successorTrain?.releaseCut?.candidateTreeSha,
+    cutPatchRoot: input.cutLanding?.patchRoot,
+    cutLandingEvidenceRoot: input.cutLanding?.evidenceRoot,
+    devLandingStatus: input.devLanding?.status,
+    devBaseSha: input.devLanding?.baseSha,
+    devLandingSha: input.devLanding?.landedSha,
+    devPatchRoot: input.devLanding?.patchRoot,
+    devLandingEvidenceRoot: input.devLanding?.evidenceRoot,
+    authorityRoots: input.authorityRoots,
+    createdAt: input.createdAt,
+  });
+  if (input.repairRoot !== rebuilt.repairRoot) {
+    throw new Error("release-blocker repair root does not match its content");
+  }
+  if (releaseTrainRoot(input) !== releaseTrainRoot(rebuilt)) {
+    throw new Error(
+      "release-blocker repair content drifted from its rooted contract",
+    );
+  }
+  return clone(input);
+}
+
+export function settleReleaseBlockerDevLanding(repairInput, input = {}) {
+  const repair = validateReleaseBlockerRepair(repairInput);
+  if (
+    contentRoot(input.expectedRepairRoot, "expectedRepairRoot") !==
+    repair.repairRoot
+  ) {
+    throw new Error(
+      "release-blocker repair settlement compare-and-swap failed",
+    );
+  }
+  const patchRoot = contentRoot(input.patchRoot, "patchRoot");
+  if (patchRoot !== repair.patchRoot) {
+    throw new Error(
+      "dev landing settlement must preserve the release-blocker patch root",
+    );
+  }
+  return buildReleaseBlockerRepair(repair.priorTrain, {
+    expectedStateRoot: repair.priorTrain.state.stateRoot,
+    blockerRoot: repair.blockerRoot,
+    patchRoot: repair.patchRoot,
+    cutCandidateSha: repair.cutLanding.landedSha,
+    cutCandidateTreeSha: repair.successorTrain.releaseCut.candidateTreeSha,
+    cutPatchRoot: repair.cutLanding.patchRoot,
+    cutLandingEvidenceRoot: repair.cutLanding.evidenceRoot,
+    devLandingStatus: "landed",
+    devBaseSha: input.devBaseSha,
+    devLandingSha: input.devLandingSha,
+    devPatchRoot: patchRoot,
+    devLandingEvidenceRoot: input.devLandingEvidenceRoot,
+    authorityRoots: repair.authorityRoots,
+    createdAt: repair.createdAt,
+  });
+}

package/scripts/buildchain-channel-router.mjs

@@ -105,8 +105,24 @@ export function resolveBuildchainChannel({
     if (channel !== "auto" && explicitRef.kind !== "override" && channel !== explicitRef.kind) {
       throw new Error(`buildchain-channel=${channel} conflicts with buildchain-ref=${explicitRef.ref}`);
     }
-    if (channel !== "auto" && explicitRef.kind === "override") {
-      throw new Error("train, authority, and exact-SHA buildchain-ref overrides require buildchain-channel=auto");
+    if (explicitRef.kind === "override") {
+      const lane = resolveBuildchainChannel({
+        requestedChannel: channel,
+        requestedRef: "",
+        publishChannel,
+        eventName,
+        gitRef,
+        releasePrerelease,
+        routerRef: `v${major}`,
+        packageVersion,
+      });
+      return {
+        ...lane,
+        major,
+        buildchainRef: explicitRef.ref,
+        selectionSource: "explicit-buildchain-ref+channel-evidence",
+        reason: `trusted runtime override ${explicitRef.ref} bound to ${lane.channel}`,
+      };
     }
     return {
       channel: explicitRef.kind,

package/scripts/buildchain-contract-lock.mjs

@@ -69,6 +69,10 @@ export function checkBuildchainContractLock({
   runtimeSha = env("BUILDCHAIN_RUNTIME_SHA"),
   runtimeClass = env("BUILDCHAIN_RUNTIME_CLASS"),
   compatibilityPolicy = env("BUILDCHAIN_CONTRACT_COMPATIBILITY_POLICY"),
+  workflowShellRef = env("BUILDCHAIN_WORKFLOW_SHELL_REF"),
+  expectedChannel = env("BUILDCHAIN_EXPECTED_CHANNEL"),
+  expectedMajor = env("BUILDCHAIN_EXPECTED_MAJOR"),
+  allowOpaqueRuntime = boolEnv("BUILDCHAIN_ALLOW_OPAQUE_RUNTIME"),
   issueMode = env("BUILDCHAIN_CONTRACT_DRIFT_ISSUE_MODE", "compatible-and-breaking"),
   issueBodyPath = env("BUILDCHAIN_CONTRACT_DRIFT_ISSUE_BODY", ".buildchain/contract-drift/issue-body.md"),
   repository = env("GITHUB_REPOSITORY"),
@@ -84,6 +88,10 @@ export function checkBuildchainContractLock({
     runtimeSha,
     runtimeClass,
     compatibilityPolicy,
+    workflowShellRef,
+    expectedChannel,
+    expectedMajor,
+    allowOpaqueRuntime,
   });
   const shouldIssue = issueModeAllows(issueMode, evaluation);
   if (shouldIssue) {
@@ -104,6 +112,8 @@ export function checkBuildchainContractLock({
     `- Compatible: \`${evaluation.compatible ? "true" : "false"}\``,
     `- Runtime ref: \`${runtimeRef || "(unknown)"}\``,
     `- Runtime SHA: \`${runtimeSha || "(unknown)"}\``,
+    `- Workflow shell ref: \`${workflowShellRef || "(unknown)"}\``,
+    evaluation.channelBinding ? `- Bound channel: \`${evaluation.channelBinding.channel || "(unknown)"}\`` : "",
     `- Contract digest: \`${current.contractDigest}\``,
     `- Compatibility digest: \`${current.compatibilityDigest}\``,
     `- Compatibility proof registry: \`${current.compatibilityProofRegistryRoot || "(legacy)"}\``,
@@ -128,7 +138,7 @@ export function checkBuildchainContractLock({
     "current-buildchain-sha": runtimeSha || "",
   });
   if (!evaluation.ok) {
-    throw new Error(`Buildchain contract drift is not compatible: ${(evaluation.reasons || []).join("; ")}`);
+    throw new Error(`Buildchain contract lock rejected: ${(evaluation.reasons || []).join("; ")}`);
   }
   return { evaluation, current, shouldIssue };
 }

package/scripts/check-inventory.mjs

@@ -215,7 +215,7 @@ const selfDogfoodAlphaEvaluation = evaluateBuildchainContractLock({
   }),
   runtimeRef: `v${selfDogfoodMajor}-alpha`,
   runtimeSha: "current-development-contract",
-  runtimeClass: "alpha",
+  runtimeClass: "alpha", workflowShellRef: `v${selfDogfoodMajor}-alpha`,
 });
 if (
   !canAdmitSelfDogfoodLockEvaluation({
@@ -304,7 +304,7 @@ if (!promotionOverrideAuthorization.includes("promotion runtime override is only
 }
 for (const requiredSnippet of [
   "buildchain-channel:",
-  "uses: ./.github/workflows/.build.yml",
+  "uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3-alpha", "uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3\n",
   "needs.resolve-channel.outputs.buildchain-ref",
   "needs.resolve-channel.outputs.contract-lock-path",
 ]) {