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

package/packages/core/channel-candidate.js

@@ -97,6 +97,14 @@ export function decideChannelCandidate(input) {
   const sourceSha = sha(input.sourceSha, "sourceSha");
   const targetSha = sha(input.targetSha, "targetSha");
   const selection = normalizeChannelCandidateSelection(input.selection);
+  if (
+    selection?.versionReservation &&
+    selection.versionReservation.candidateSha !== sourceSha
+  ) {
+    throw new Error(
+      "selection version reservation must bind the selected source SHA",
+    );
+  }
   const now = required(input.now || new Date().toISOString(), "now");
   const maxAgeSeconds = Number(input.maxAgeSeconds ?? 7 * 24 * 60 * 60);
   if (!Number.isSafeInteger(maxAgeSeconds) || maxAgeSeconds <= 0) {

package/packages/core/channel-promotion-baseline.js

@@ -1,5 +1,10 @@
 // SPDX-License-Identifier: Apache-2.0
 
+import {
+  nextDevelopmentPatrolContext,
+  normalizeNextDevelopmentVersionReservation,
+} from "./next-development-candidate-reservation.js";
+
 const SHA = /^[0-9a-f]{40}$/;
 
 function text(value = "") {
@@ -59,6 +64,18 @@ export function normalizeChannelCandidateSelection(input) {
           ),
         }
       : {}),
+    ...(input.versionReservation
+      ? {
+          versionReservation: normalizeNextDevelopmentVersionReservation(
+            input.versionReservation,
+            {
+              reservationSha: input.versionReservation.reservationSha,
+              candidateSha: input.versionReservation.candidateSha,
+              targetVersion: input.versionReservation.targetVersion,
+            },
+          ),
+        }
+      : {}),
   };
 }
 
@@ -117,6 +134,7 @@ export async function resolvePatrolSourceInputs({
   let comparison = headComparison;
   let workflowEvidence = [];
   let skippedNewerCommitCount = 0;
+  let versionReservation;
   let qualificationError;
   if (
     headComparison.status === "ahead" &&
@@ -130,6 +148,8 @@ export async function resolvePatrolSourceInputs({
       ),
     ]);
     try {
+      const { preparations, ignoredSourceShas } =
+        nextDevelopmentPatrolContext(sourceHistory);
       const selected = selectQualifiedSource({
         sourceHistory,
         workflowRunsByPath: new Map(
@@ -141,8 +161,39 @@ export async function resolvePatrolSourceInputs({
         requiredWorkflowPaths,
         now: options.now,
         maxAgeSeconds: options.maxAgeSeconds,
+        ignoredSourceShas,
       });
       ({ sourceSha, skippedNewerCommitCount, workflowEvidence } = selected);
+      const selectedIndex = sourceHistory.findIndex((entry) =>
+        (typeof entry === "string" ? entry : entry?.sha) === sourceSha,
+      );
+      const reservation = preparations.find(
+        ({ index }) => index > selectedIndex,
+      )?.preparation;
+      if (reservation) {
+        if (typeof client.readNextDevelopmentVersionReservation !== "function") {
+          throw new Error(
+            "candidate follows next-development preparation but reservation readback is unavailable",
+          );
+        }
+        versionReservation = normalizeNextDevelopmentVersionReservation(
+          await client.readNextDevelopmentVersionReservation({
+            reservationSha: reservation.sha,
+            candidateSha: sourceSha,
+            targetVersion: reservation.targetVersion,
+          }),
+          {
+            reservationSha: reservation.sha,
+            candidateSha: sourceSha,
+            targetVersion: reservation.targetVersion,
+          },
+        );
+        if (versionReservation.status !== "current") {
+          throw new Error(
+            `next-development version reservation is ${versionReservation.status} for candidate ${sourceSha}`,
+          );
+        }
+      }
       if (sourceSha !== observedSourceHeadSha)
         comparison = await client.compare(boundarySha, sourceSha);
     } catch (error) {
@@ -158,6 +209,7 @@ export async function resolvePatrolSourceInputs({
     comparison,
     workflowEvidence,
     skippedNewerCommitCount,
+    versionReservation,
     qualificationError,
   };
 }

package/packages/core/dev-alpha-candidate-selection.js

@@ -82,7 +82,9 @@ export function selectLatestQualifiedSource({
   requiredWorkflowPaths,
   now,
   maxAgeSeconds,
+  ignoredSourceShas = [],
 }) {
+  const ignored = new Set(ignoredSourceShas);
   const latestByPath = new Map(
     requiredWorkflowPaths.map((workflow) => [
       workflow,
@@ -90,7 +92,11 @@ export function selectLatestQualifiedSource({
     ]),
   );
   for (let index = 0; index < sourceHistory.length; index += 1) {
-    const sourceSha = sourceHistory[index];
+    const sourceSha =
+      typeof sourceHistory[index] === "string"
+        ? sourceHistory[index]
+        : sourceHistory[index]?.sha;
+    if (ignored.has(sourceSha)) continue;
     const rows = requiredWorkflowPaths.map((workflow) =>
       latestByPath.get(workflow).get(sourceSha),
     );
@@ -115,7 +121,9 @@ export function selectLatestQualifiedSource({
       };
     }
   }
-  const staleSuccessfulPair = sourceHistory.some((sourceSha) => {
+  const staleSuccessfulPair = sourceHistory.some((entry) => {
+    const sourceSha = typeof entry === "string" ? entry : entry?.sha;
+    if (ignored.has(sourceSha)) return false;
     const rows = requiredWorkflowPaths.map((workflow) =>
       latestByPath.get(workflow).get(sourceSha),
     );

package/packages/core/next-development-candidate-reservation.js

@@ -0,0 +1,186 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import crypto from "node:crypto";
+
+const SHA = /^[0-9a-f]{40}$/u;
+const ROOT = /^sha256:[0-9a-f]{64}$/u;
+
+function text(value = "") {
+  return String(value ?? "").trim();
+}
+
+function exactSha(value, label) {
+  const normalized = text(value).toLowerCase();
+  if (!SHA.test(normalized)) {
+    throw new Error(`${label} must be an exact 40-character SHA`);
+  }
+  return normalized;
+}
+
+function exactRoot(value, label) {
+  const normalized = text(value).toLowerCase();
+  if (!ROOT.test(normalized)) {
+    throw new Error(`${label} must be an exact sha256 content root`);
+  }
+  return normalized;
+}
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, item]) => [key, canonical(item)]),
+    );
+  }
+  return value;
+}
+
+function evidenceRoot(value) {
+  return `sha256:${crypto
+    .createHash("sha256")
+    .update(JSON.stringify(canonical(value)))
+    .digest("hex")}`;
+}
+
+export function nextDevelopmentPreparedVersion(message) {
+  const title = text(message).split("\n", 1)[0];
+  return (
+    title.match(
+      /^(?:chore\(release\): prepare|Prepare)\s+v?([0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?)$/u,
+    )?.[1] || ""
+  );
+}
+
+function preparation(entry) {
+  if (!entry || typeof entry === "string") return undefined;
+  const targetVersion = nextDevelopmentPreparedVersion(entry.message);
+  if (!targetVersion) return undefined;
+  return {
+    sha: exactSha(entry.sha, "sourceHistory.sha"),
+    targetVersion,
+  };
+}
+
+export function nextDevelopmentPatrolContext(sourceHistory) {
+  const preparations = sourceHistory
+    .map((entry, index) => ({ index, preparation: preparation(entry) }))
+    .filter((entry) => entry.preparation);
+  const preparationShas = new Set(
+    preparations.map(({ preparation: item }) => item.sha),
+  );
+  const integrationShas = sourceHistory
+    .filter(
+      (entry) =>
+        entry &&
+        typeof entry !== "string" &&
+        Array.isArray(entry.parents) &&
+        entry.parents.length === 2 &&
+        entry.parents.some((parent) => preparationShas.has(parent)),
+    )
+    .map((entry) => exactSha(entry.sha, "sourceHistory.sha"));
+  return {
+    preparations,
+    ignoredSourceShas: [...preparationShas, ...integrationShas],
+  };
+}
+
+export function normalizeNextDevelopmentVersionReservation(input, expected) {
+  const status = text(input?.status);
+  if (!["current", "absent", "stale"].includes(status)) {
+    throw new Error("next-development version reservation status is invalid");
+  }
+  const normalized = {
+    status,
+    reservationSha: exactSha(
+      input?.reservationSha,
+      "versionReservation.reservationSha",
+    ),
+    candidateSha: exactSha(
+      input?.candidateSha,
+      "versionReservation.candidateSha",
+    ),
+    targetVersion: text(input?.targetVersion),
+    paths: [...new Set((input?.paths || []).map(text))].sort(),
+    evidenceRoot: exactRoot(
+      input?.evidenceRoot,
+      "versionReservation.evidenceRoot",
+    ),
+  };
+  if (
+    normalized.reservationSha !== expected.reservationSha ||
+    normalized.candidateSha !== expected.candidateSha ||
+    normalized.targetVersion !== expected.targetVersion
+  ) {
+    throw new Error("next-development version reservation identity drifted");
+  }
+  if (normalized.paths.length === 0 || normalized.paths.some((path) => !path)) {
+    throw new Error("next-development version reservation paths are required");
+  }
+  return normalized;
+}
+
+function encodeRepositoryPath(value) {
+  return value.split("/").map(encodeURIComponent).join("/");
+}
+
+export async function readGitHubNextDevelopmentVersionReservation({
+  api,
+  owner,
+  repo,
+  reservationSha,
+  candidateSha,
+  targetVersion,
+}) {
+  const commit = await api(
+    `/repos/${owner}/${repo}/commits/${encodeURIComponent(reservationSha)}`,
+  );
+  if (
+    text(commit.sha) !== reservationSha ||
+    nextDevelopmentPreparedVersion(commit.commit?.message) !== targetVersion
+  ) {
+    throw new Error(
+      "next-development preparation commit identity or version drifted",
+    );
+  }
+  const paths = [
+    ...new Set((commit.files || []).map((file) => text(file.filename))),
+  ]
+    .filter(Boolean)
+    .sort();
+  if (paths.length === 0) {
+    throw new Error(
+      "next-development preparation commit has no version-state paths",
+    );
+  }
+  const observations = [];
+  let status = "current";
+  for (const filePath of paths) {
+    const endpoint = `/repos/${owner}/${repo}/contents/${encodeRepositoryPath(filePath)}`;
+    const prepared = await api(
+      `${endpoint}?ref=${encodeURIComponent(reservationSha)}`,
+      { allow404: true },
+    );
+    const candidate = await api(
+      `${endpoint}?ref=${encodeURIComponent(candidateSha)}`,
+      { allow404: true },
+    );
+    const preparedBlob =
+      text(prepared?.type) === "file" ? text(prepared?.sha) : "";
+    const candidateBlob =
+      text(candidate?.type) === "file" ? text(candidate?.sha) : "";
+    if (!candidateBlob) status = "absent";
+    else if (!preparedBlob || candidateBlob !== preparedBlob) status = "stale";
+    observations.push({ path: filePath, preparedBlob, candidateBlob });
+  }
+  const body = {
+    status,
+    reservationSha,
+    candidateSha,
+    targetVersion,
+    paths,
+    observations,
+  };
+  return { ...body, evidenceRoot: evidenceRoot(body) };
+}