@kungfu-tech/buildchain 4.0.1-alpha.5 → 4.0.1-alpha.8

package/packages/core/adopter-delivery-vectors.js

@@ -0,0 +1,158 @@
+import vectorSuite from "./adopter-delivery-vectors.json" with { type: "json" };
+
+import { adopterDeliveryGateDigest } from "./adopter-delivery-gate.js";
+
+export const ADOPTER_DELIVERY_VECTOR_SUITE_CONTRACT =
+  "kungfu-buildchain-adopter-delivery-vectors/v1";
+
+const ROOT_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const REQUIRED_CASES = new Map([
+  ["golden-two-driver-offline-replay", "golden"],
+  ["negative-driver-mismatch", "negative"],
+  ["negative-category-conflict", "negative"],
+  ["negative-evidence-substitution", "negative"],
+  ["negative-stale-package-cut", "negative"],
+  ["fault-driver-throw", "fault"],
+]);
+
+function freezeJson(value) {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) freezeJson(child);
+  }
+  return value;
+}
+
+function issue(code, path, message) {
+  return { code, path, message };
+}
+
+function suiteDigest(suite) {
+  const preimage = structuredClone(suite);
+  delete preimage.suiteRoot;
+  return adopterDeliveryGateDigest(preimage);
+}
+
+export function validateAdopterDeliveryVectorSuite(suite) {
+  const issues = [];
+  if (!suite || typeof suite !== "object" || Array.isArray(suite)) {
+    return {
+      valid: false,
+      issues: [
+        issue(
+          "adopter-delivery-vectors.invalid",
+          "/",
+          "Vector suite must be a JSON object.",
+        ),
+      ],
+    };
+  }
+  if (
+    suite.schemaVersion !== 1 ||
+    suite.contract !== ADOPTER_DELIVERY_VECTOR_SUITE_CONTRACT
+  ) {
+    issues.push(
+      issue(
+        "adopter-delivery-vectors.contract",
+        "/contract",
+        "Vector suite contract is unsupported.",
+      ),
+    );
+  }
+  if (!Array.isArray(suite.cases)) {
+    issues.push(
+      issue(
+        "adopter-delivery-vectors.cases",
+        "/cases",
+        "Vector suite cases must be an array.",
+      ),
+    );
+  } else {
+    const seen = new Set();
+    for (const [index, entry] of suite.cases.entries()) {
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        issues.push(
+          issue(
+            "adopter-delivery-vectors.case",
+            `/cases/${index}`,
+            "Vector case must be an object.",
+          ),
+        );
+        continue;
+      }
+      if (typeof entry.id !== "string" || seen.has(entry.id)) {
+        issues.push(
+          issue(
+            "adopter-delivery-vectors.case-id",
+            `/cases/${index}/id`,
+            "Vector case id must be non-empty and unique.",
+          ),
+        );
+      }
+      seen.add(entry.id);
+      if (!entry.expected || typeof entry.expected !== "object") {
+        issues.push(
+          issue(
+            "adopter-delivery-vectors.expected",
+            `/cases/${index}/expected`,
+            "Vector case must declare its expected result.",
+          ),
+        );
+      }
+    }
+    for (const [id, className] of REQUIRED_CASES) {
+      const entry = suite.cases.find((candidate) => candidate?.id === id);
+      if (!entry || entry.class !== className) {
+        issues.push(
+          issue(
+            "adopter-delivery-vectors.required-case",
+            "/cases",
+            `Required ${className} vector ${id} is missing.`,
+          ),
+        );
+      }
+    }
+  }
+  if (!ROOT_PATTERN.test(suite.suiteRoot ?? "")) {
+    issues.push(
+      issue(
+        "adopter-delivery-vectors.root",
+        "/suiteRoot",
+        "Vector suite root must be a canonical sha256 root.",
+      ),
+    );
+  } else {
+    try {
+      if (suiteDigest(suite) !== suite.suiteRoot) {
+        issues.push(
+          issue(
+            "adopter-delivery-vectors.root",
+            "/suiteRoot",
+            "Vector suite root does not match the exact JSON closure.",
+          ),
+        );
+      }
+    } catch {
+      issues.push(
+        issue(
+          "adopter-delivery-vectors.root",
+          "/suiteRoot",
+          "Vector suite must contain finite acyclic JSON.",
+        ),
+      );
+    }
+  }
+  return { valid: issues.length === 0, issues };
+}
+
+export const ADOPTER_DELIVERY_VECTOR_SUITE = freezeJson(
+  structuredClone(vectorSuite),
+);
+
+export function getAdopterDeliveryVector(id) {
+  const entry = ADOPTER_DELIVERY_VECTOR_SUITE.cases.find(
+    (candidate) => candidate.id === id,
+  );
+  if (!entry) throw new RangeError(`Unknown adopter delivery vector: ${id}`);
+  return structuredClone(entry);
+}

package/packages/core/adopter-delivery-vectors.json

@@ -0,0 +1,77 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-adopter-delivery-vectors/v1",
+  "rootAlgorithm": "sha256-buildchain-canonical-json-v1",
+  "authorities": {
+    "kfdPackage": "@kungfu-tech/kfd@1.0.0-alpha.65",
+    "categoryProfileVectors": "@kungfu-tech/kfd/adopter-conformance/category-profile-vectors.json",
+    "categoryInstanceVectors": "@kungfu-tech/kfd/adopter-conformance/category-instance-vectors.json"
+  },
+  "cases": [
+    {
+      "id": "golden-two-driver-offline-replay",
+      "class": "golden",
+      "surface": "protocol-neutral-gate",
+      "operation": "evaluate identical exact requests with two isolated protocol drivers and replay each request offline",
+      "expected": {
+        "statuses": ["passed", "passed"],
+        "issueCodes": [],
+        "deterministicRoots": true,
+        "qualifying": false,
+        "selfCertified": false
+      }
+    },
+    {
+      "id": "negative-driver-mismatch",
+      "class": "negative",
+      "surface": "protocol-neutral-gate",
+      "operation": "select an exact protocol identity and version that are not registered",
+      "expected": {
+        "status": "failed",
+        "issueCodes": ["delivery-driver-unknown"]
+      }
+    },
+    {
+      "id": "negative-category-conflict",
+      "class": "negative",
+      "surface": "published-kfd-category-driver",
+      "operation": "append a duplicate published category profile to the exact KFD instance selection",
+      "expected": {
+        "status": "failed",
+        "issueCodes": ["acp-composition-invalid"]
+      }
+    },
+    {
+      "id": "negative-evidence-substitution",
+      "class": "negative",
+      "surface": "release-passport-binding",
+      "operation": "substitute the artifact root in artifact evidence after binding the passport",
+      "expected": {
+        "status": "failed",
+        "issueCodes": ["adopterDelivery.artifactEvidence"]
+      }
+    },
+    {
+      "id": "negative-stale-package-cut",
+      "class": "negative",
+      "surface": "published-kfd-category-driver",
+      "operation": "replace the KFD instance package version with an uninstalled stale cut",
+      "expected": {
+        "status": "failed",
+        "issueCodes": ["delivery-kfd-package-cut-mismatch"]
+      }
+    },
+    {
+      "id": "fault-driver-throw",
+      "class": "fault",
+      "surface": "protocol-neutral-gate",
+      "operation": "throw a private exception from the selected protocol driver",
+      "expected": {
+        "status": "failed",
+        "issueCodes": ["delivery-driver-error"],
+        "privateDetailRedacted": true
+      }
+    }
+  ],
+  "suiteRoot": "sha256:c978707556406ffda4ef4192032332c01c2da1cebb6ad8c4f0edfc65d5cef0c7"
+}

package/packages/core/buildchain-agent-manuals.js

@@ -30,6 +30,7 @@ export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
   { id: "kfd-agent-hub", title: "KFD Agent Hub Builder flow", path: "docs/kfd-agent-hub.md", plane: "use" },
   { id: "lifecycle-protocol", title: "Lifecycle protocol", path: "docs/lifecycle-protocol.md", plane: "use" },
   { id: "reusable-build-surface", title: "Reusable build surface", path: "docs/reusable-build-surface.md", plane: "use" },
+  { id: "v4-adopter-delivery", title: "V4 public adopter delivery", path: "docs/v4-adopter-delivery.md", plane: "verify" },
   { id: "publish-transaction", title: "Publish transaction", path: "docs/publish-transaction.md", plane: "verify" },
   { id: "release-tail-contract", title: "Declarative release-tail contract", path: "docs/release-tail-contract.md", plane: "verify" },
   { id: "release-tail-provider-plane", title: "Declarative release-tail provider plane", path: "docs/release-tail-provider-plane.md", plane: "use" },

package/packages/core/buildchain-config.js

@@ -236,6 +236,16 @@ export function normalizeBuildchainConfig(config) {
   if (normalized.publication !== undefined) {
     normalized.publication = normalizePublicationSection(normalized.publication);
   }
+  if (normalized.publication_rehearsal !== undefined) {
+    normalized.publication_rehearsal = normalizePublicationRehearsalSection(
+      normalized.publication_rehearsal,
+    );
+  }
+  if (normalized.adopter_delivery !== undefined) {
+    normalized.adopter_delivery = normalizeAdopterDeliverySection(
+      normalized.adopter_delivery,
+    );
+  }
   if (normalized.consumers !== undefined) {
     normalized.consumers = normalizeConsumersSection(normalized.consumers);
   }
@@ -700,6 +710,80 @@ function normalizePublicationSection(publication) {
   };
 }
 
+function normalizePublicationRehearsalSection(rehearsal) {
+  assertPlainObject(rehearsal, "publication_rehearsal");
+  const allowed = ["contract", "capsule_path", "candidate_root", "state_path", "evidence_path", "effect_default"];
+  const unknown = Object.keys(rehearsal).filter((key) => !allowed.includes(key));
+  if (unknown.length > 0) {
+    throw new Error(`publication_rehearsal contains unsupported fields: ${unknown.join(", ")}`);
+  }
+  const normalized = {
+    contract: assertString(rehearsal.contract, "publication_rehearsal.contract"),
+    capsulePath: posixPath(assertString(rehearsal.capsule_path, "publication_rehearsal.capsule_path")),
+    candidateRoot: posixPath(assertString(rehearsal.candidate_root, "publication_rehearsal.candidate_root")),
+    statePath: posixPath(assertString(rehearsal.state_path, "publication_rehearsal.state_path")),
+    evidencePath: posixPath(assertString(rehearsal.evidence_path, "publication_rehearsal.evidence_path")),
+    effectDefault: assertString(rehearsal.effect_default, "publication_rehearsal.effect_default"),
+  };
+  if (
+    normalized.contract !== "buildchain-v4-publication-rehearsal-capsule/v1" ||
+    normalized.effectDefault !== "disabled"
+  ) {
+    throw new Error("publication_rehearsal must use the v4 capsule contract with effect_default = disabled");
+  }
+  for (const [key, value] of Object.entries({
+    capsule_path: normalized.capsulePath,
+    candidate_root: normalized.candidateRoot,
+    state_path: normalized.statePath,
+    evidence_path: normalized.evidencePath,
+  })) {
+    if (value.startsWith("/") || value.includes("\\") || value.split("/").includes("..")) {
+      throw new Error(`publication_rehearsal.${key} must be repository-relative`);
+    }
+  }
+  return normalized;
+}
+
+function normalizeAdopterDeliverySection(delivery) {
+  assertPlainObject(delivery, "adopter_delivery");
+  const allowed = ["contract", "input_path", "readback_path", "bootstrap_path", "archive_path", "result_path", "driver_selector", "artifact_profile_selector"];
+  const unknown = Object.keys(delivery).filter((key) => !allowed.includes(key));
+  if (unknown.length > 0) {
+    throw new Error(`adopter_delivery contains unsupported fields: ${unknown.join(", ")}`);
+  }
+  const normalized = {
+    contract: assertString(delivery.contract, "adopter_delivery.contract"),
+    inputPath: posixPath(assertString(delivery.input_path, "adopter_delivery.input_path")),
+    readbackPath: posixPath(assertString(delivery.readback_path, "adopter_delivery.readback_path")),
+    bootstrapPath: posixPath(assertString(delivery.bootstrap_path, "adopter_delivery.bootstrap_path")),
+    archivePath: posixPath(assertString(delivery.archive_path, "adopter_delivery.archive_path")),
+    resultPath: posixPath(assertString(delivery.result_path, "adopter_delivery.result_path")),
+    driverSelector: assertString(delivery.driver_selector, "adopter_delivery.driver_selector"),
+    artifactProfileSelector: assertString(delivery.artifact_profile_selector, "adopter_delivery.artifact_profile_selector"),
+  };
+  if (normalized.contract !== "kungfu-buildchain-v4-adopter-delivery/v1") {
+    throw new Error("adopter_delivery contract is unsupported");
+  }
+  if (
+    !["json-assertion", "kfd-category", "legacy-kfd"].includes(normalized.driverSelector) ||
+    !["git-commit", "package"].includes(normalized.artifactProfileSelector)
+  ) {
+    throw new Error("adopter_delivery selector is unsupported");
+  }
+  for (const [key, value] of Object.entries({
+    input_path: normalized.inputPath,
+    readback_path: normalized.readbackPath,
+    bootstrap_path: normalized.bootstrapPath,
+    archive_path: normalized.archivePath,
+    result_path: normalized.resultPath,
+  })) {
+    if (value.startsWith("/") || value.includes("\\") || value.split("/").includes("..")) {
+      throw new Error(`adopter_delivery.${key} must be repository-relative`);
+    }
+  }
+  return normalized;
+}
+
 function normalizePublicationArchive(archive = undefined) {
   if (archive === undefined) {
     return undefined;

package/packages/core/buildchain-delivery-bootstrap.js

@@ -0,0 +1,240 @@
+import { adopterDeliveryGateDigest } from "./adopter-delivery-gate.js";
+import { validateAdopterDeliveryGateResult } from "./adopter-delivery-passport.js";
+
+export const BUILDCHAIN_DELIVERY_BOOTSTRAP_CONTRACT =
+  "kungfu-buildchain-delivery-infrastructure-bootstrap/v1";
+
+const ROOT_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const SHA_PATTERN = /^[0-9a-f]{40}$/;
+const SEMVER_PATTERN =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+
+function issue(code, message) {
+  return { code, message };
+}
+
+function exactRoot(value) {
+  return ROOT_PATTERN.test(value ?? "");
+}
+
+function exactCut(cut) {
+  return (
+    cut &&
+    typeof cut === "object" &&
+    typeof cut.version === "string" &&
+    SHA_PATTERN.test(cut.sourceCommit ?? "") &&
+    exactRoot(cut.packageRoot) &&
+    exactRoot(cut.gateRoot) &&
+    typeof cut.protocol?.id === "string" &&
+    typeof cut.protocol?.version === "string" &&
+    exactRoot(cut.protocol?.root) &&
+    typeof cut.profile?.id === "string" &&
+    typeof cut.profile?.version === "string" &&
+    exactRoot(cut.profile?.root)
+  );
+}
+
+function parseSemver(value) {
+  const match = SEMVER_PATTERN.exec(value ?? "");
+  if (!match) return null;
+  return {
+    core: match.slice(1, 4).map(Number),
+    prerelease: match[4] ? match[4].split(".") : [],
+  };
+}
+
+function compareIdentifier(left, right) {
+  const leftNumber = /^\d+$/.test(left) ? Number(left) : null;
+  const rightNumber = /^\d+$/.test(right) ? Number(right) : null;
+  if (leftNumber !== null && rightNumber !== null) {
+    return Math.sign(leftNumber - rightNumber);
+  }
+  if (leftNumber !== null) return -1;
+  if (rightNumber !== null) return 1;
+  return left === right ? 0 : left < right ? -1 : 1;
+}
+
+function compareSemver(leftValue, rightValue) {
+  const left = parseSemver(leftValue);
+  const right = parseSemver(rightValue);
+  if (!left || !right) return null;
+  for (let index = 0; index < left.core.length; index += 1) {
+    if (left.core[index] !== right.core[index]) {
+      return Math.sign(left.core[index] - right.core[index]);
+    }
+  }
+  if (left.prerelease.length === 0 || right.prerelease.length === 0) {
+    if (left.prerelease.length === right.prerelease.length) return 0;
+    return left.prerelease.length === 0 ? 1 : -1;
+  }
+  const width = Math.max(left.prerelease.length, right.prerelease.length);
+  for (let index = 0; index < width; index += 1) {
+    if (left.prerelease[index] === undefined) return -1;
+    if (right.prerelease[index] === undefined) return 1;
+    const comparison = compareIdentifier(
+      left.prerelease[index],
+      right.prerelease[index],
+    );
+    if (comparison !== 0) return comparison;
+  }
+  return 0;
+}
+
+function sameProtocol(left, right) {
+  return (
+    left?.id === right?.id &&
+    left?.version === right?.version &&
+    left?.root === right?.root
+  );
+}
+
+function validTransition(transition, authority, candidate) {
+  if (!transition || typeof transition !== "object") return false;
+  const body = structuredClone(transition);
+  const transitionRoot = body.transitionRoot;
+  delete body.transitionRoot;
+  return (
+    exactRoot(transitionRoot) &&
+    adopterDeliveryGateDigest(body) === transitionRoot &&
+    body.fromGateRoot === authority.gateRoot &&
+    body.toGateRoot === candidate.gateRoot &&
+    body.fromProtocolRoot === authority.protocol.root &&
+    body.toProtocolRoot === candidate.protocol.root &&
+    body.fromProfileRoot === authority.profile.root &&
+    body.toProfileRoot === candidate.profile.root &&
+    exactRoot(body.compatibilityProofRoot) &&
+    exactRoot(body.independentReviewRoot)
+  );
+}
+
+function validateWarrant(warrant, candidate) {
+  return (
+    warrant &&
+    typeof warrant === "object" &&
+    warrant.outcome === "merged" &&
+    warrant.sourceHead === candidate.sourceCommit &&
+    exactRoot(warrant.sourceProofRoot) &&
+    exactRoot(warrant.nativeProofRoot) &&
+    exactRoot(warrant.integrationProofRoot)
+  );
+}
+
+export function qualifyBuildchainDeliveryInfrastructureBootstrap({
+  authority,
+  candidate,
+  gateResult,
+  warrant,
+  transitionEvidence,
+} = {}) {
+  const issues = [];
+  if (!exactCut(authority)) {
+    issues.push(
+      issue("bootstrap.authority.cut", "N-1 authority cut is incomplete"),
+    );
+  }
+  if (!exactCut(candidate)) {
+    issues.push(
+      issue("bootstrap.candidate.cut", "candidate cut is incomplete"),
+    );
+  }
+  if (authority?.protected !== true || authority?.published !== true) {
+    issues.push(
+      issue(
+        "bootstrap.authority.release",
+        "N-1 authority must be both protected and publicly released",
+      ),
+    );
+  }
+  if (candidate?.authorityVersion !== authority?.version) {
+    issues.push(
+      issue(
+        "bootstrap.authority.stale",
+        "candidate must name the exact N-1 authority version",
+      ),
+    );
+  }
+  const versionOrder = compareSemver(authority?.version, candidate?.version);
+  if (versionOrder === null || versionOrder >= 0) {
+    issues.push(
+      issue(
+        "bootstrap.authority.order",
+        "N-1 authority version must precede the candidate version",
+      ),
+    );
+  }
+  if (
+    authority?.sourceCommit === candidate?.sourceCommit ||
+    authority?.packageRoot === candidate?.packageRoot
+  ) {
+    issues.push(
+      issue(
+        "bootstrap.self-authorization",
+        "candidate source or package cannot serve as its own N-1 authority",
+      ),
+    );
+  }
+
+  const gateValidation = validateAdopterDeliveryGateResult(gateResult);
+  if (!gateValidation.passed) {
+    issues.push(
+      issue(
+        "bootstrap.gate.failed",
+        "candidate must retain a passed public adopter delivery gate result",
+      ),
+    );
+  }
+  if (
+    gateResult?.artifact?.root !== candidate?.packageRoot ||
+    gateResult?.project?.adopterId !== "kungfu-systems/buildchain"
+  ) {
+    issues.push(
+      issue(
+        "bootstrap.gate.candidate",
+        "gate result must bind the exact Buildchain candidate package",
+      ),
+    );
+  }
+  if (!validateWarrant(warrant, candidate)) {
+    issues.push(
+      issue(
+        "bootstrap.warrant",
+        "merged Delivery Warrant evidence must bind the candidate source",
+      ),
+    );
+  }
+
+  const transitionRequired =
+    !sameProtocol(authority?.protocol, candidate?.protocol) ||
+    !sameProtocol(authority?.profile, candidate?.profile) ||
+    authority?.gateRoot !== candidate?.gateRoot;
+  if (
+    transitionRequired &&
+    !validTransition(transitionEvidence, authority, candidate)
+  ) {
+    issues.push(
+      issue(
+        "bootstrap.transition",
+        "gate, protocol, or profile changes require exact independent transition evidence",
+      ),
+    );
+  }
+
+  const result = {
+    schemaVersion: 1,
+    contract: BUILDCHAIN_DELIVERY_BOOTSTRAP_CONTRACT,
+    status: issues.length === 0 ? "passed" : "failed",
+    authority: structuredClone(authority ?? null),
+    candidate: structuredClone(candidate ?? null),
+    gateResultRoot: gateResult?.gateRoot ?? null,
+    warrant: structuredClone(warrant ?? null),
+    transitionRequired,
+    transitionEvidenceRoot: transitionEvidence?.transitionRoot ?? null,
+    issues,
+    qualifying: false,
+    selfCertified: false,
+    releaseAuthorized: false,
+    finalAuthority: "protected-n-minus-one-plus-exact-delivery-evidence",
+  };
+  result.bootstrapRoot = adopterDeliveryGateDigest(result);
+  return result;
+}