@kungfu-tech/buildchain 4.0.1-alpha.2 → 4.0.1-alpha.21

package/packages/core/legacy-kfd-adopter-driver.js

@@ -0,0 +1,167 @@
+import {
+  ADOPTER_PROTOCOL_DRIVER_INTERFACE,
+  adopterDeliveryGateDigest,
+  defineAdopterProtocolDriver,
+} from "./adopter-delivery-gate.js";
+import {
+  KFD_LEGACY_SUPPORT_MATRIX_CONTRACT,
+  validateKfdAdopterManifestGate,
+  validateKfdLegacySupportMatrixProjection,
+} from "./kfd-adopter-manifest.js";
+
+export const LEGACY_KFD_ADOPTER_PROTOCOL_ID =
+  "buildchain.kfd-adopter/legacy-support-matrix";
+export const LEGACY_KFD_ADOPTER_PROTOCOL_VERSION = "1.0.0";
+export const LEGACY_KFD_ADOPTER_DRIVER_REPORT_CONTRACT =
+  "kungfu-buildchain-legacy-kfd-adopter-driver-report";
+
+function issue(code, path, message) {
+  return { code, path, message };
+}
+
+function normalizedIssues(entries) {
+  return (entries ?? []).map(({ code, path, message }) => ({
+    code,
+    path: path ? `/${path.replaceAll(".", "/")}` : "/declaration",
+    message,
+  }));
+}
+
+function sameJson(left, right) {
+  try {
+    return adopterDeliveryGateDigest(left) === adopterDeliveryGateDigest(right);
+  } catch {
+    return false;
+  }
+}
+
+function bindingIssues(request, manifest) {
+  const issues = [];
+  if (
+    request.project.instanceId !== manifest?.manifestId ||
+    request.project.adopterId !== manifest?.adopter?.id
+  ) {
+    issues.push(
+      issue(
+        "delivery-legacy-project-binding-mismatch",
+        "/project",
+        "Delivery project identity must match the standard adopter manifest.",
+      ),
+    );
+  }
+  if (!sameJson(request.artifact, manifest?.adopter?.artifact)) {
+    issues.push(
+      issue(
+        "delivery-legacy-artifact-binding-mismatch",
+        "/artifact",
+        "Delivery artifact must match the standard adopter manifest artifact.",
+      ),
+    );
+  }
+  return issues;
+}
+
+function invalidContextResult(issues) {
+  const report = {
+    schemaVersion: 1,
+    contract: LEGACY_KFD_ADOPTER_DRIVER_REPORT_CONTRACT,
+    valid: false,
+    qualifying: false,
+    selfCertified: false,
+    independentlyCertified: false,
+    manifestRoot: null,
+    manifestGateRoot: null,
+    legacyProjectionRoot: null,
+    legacyProjection: null,
+    adapterIssues: issues,
+    nonClaims: [
+      "The legacy support matrix is a one-way projection, not declaration authority.",
+      "Buildchain carries the existing standard manifest decision and does not certify KFD adoption.",
+    ],
+  };
+  return {
+    valid: false,
+    report,
+    reportRoot: adopterDeliveryGateDigest(report),
+    issues,
+  };
+}
+
+export function createLegacyKfdAdopterProtocolDriver() {
+  return defineAdopterProtocolDriver({
+    interface: ADOPTER_PROTOCOL_DRIVER_INTERFACE,
+    id: LEGACY_KFD_ADOPTER_PROTOCOL_ID,
+    version: LEGACY_KFD_ADOPTER_PROTOCOL_VERSION,
+    verify({ request, context }) {
+      const manifest = context?.adopterManifest;
+      const manifestGate = context?.adopterManifestGate;
+      if (!manifest || !manifestGate) {
+        return invalidContextResult([
+          issue(
+            "delivery-legacy-verification-context-invalid",
+            "/protocol",
+            "The exact standard adopter manifest and manifest gate are required.",
+          ),
+        ]);
+      }
+
+      const source = manifest?.adopter?.artifact?.coordinate?.match(
+        /^([^@\s]+)@([0-9a-f]{40})$/,
+      );
+      const gateValidation = validateKfdAdopterManifestGate(manifestGate, {
+        expectedAdopterId: manifest?.adopter?.id,
+        expectedSourceRepository: source?.[1] ?? "",
+        expectedSourceSha: source?.[2] ?? "",
+        checkedAt: manifestGate?.checkedAt,
+      });
+      const projectionValidation = validateKfdLegacySupportMatrixProjection(
+        request.declaration,
+        { manifest, manifestGate },
+      );
+      const adapterIssues = [
+        ...bindingIssues(request, manifest),
+        ...normalizedIssues(gateValidation.issues),
+        ...normalizedIssues(projectionValidation.issues),
+      ];
+      if (
+        request.declaration?.contract !== KFD_LEGACY_SUPPORT_MATRIX_CONTRACT
+      ) {
+        adapterIssues.push(
+          issue(
+            "delivery-legacy-contract-invalid",
+            "/declaration/contract",
+            `Legacy declaration must use ${KFD_LEGACY_SUPPORT_MATRIX_CONTRACT}.`,
+          ),
+        );
+      }
+
+      const valid =
+        gateValidation.valid &&
+        projectionValidation.valid &&
+        adapterIssues.length === 0;
+      const report = {
+        schemaVersion: 1,
+        contract: LEGACY_KFD_ADOPTER_DRIVER_REPORT_CONTRACT,
+        valid,
+        qualifying: false,
+        selfCertified: false,
+        independentlyCertified: false,
+        manifestRoot: manifestGate?.authority?.manifestRoot ?? null,
+        manifestGateRoot: manifestGate?.gateRoot ?? null,
+        legacyProjectionRoot: adopterDeliveryGateDigest(request.declaration),
+        legacyProjection: structuredClone(request.declaration),
+        adapterIssues,
+        nonClaims: [
+          "The legacy support matrix is a one-way projection, not declaration authority.",
+          "Buildchain carries the existing standard manifest decision and does not certify KFD adoption.",
+        ],
+      };
+      return {
+        valid,
+        report,
+        reportRoot: adopterDeliveryGateDigest(report),
+        issues: adapterIssues,
+      };
+    },
+  });
+}

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) };
+}