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

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

@@ -0,0 +1,259 @@
+import {
+  ADOPTER_DELIVERY_GATE_RESULT_CONTRACT,
+  adopterDeliveryGateDigest,
+} from "./adopter-delivery-gate.js";
+
+export const ADOPTER_DELIVERY_PASSPORT_BINDING_CONTRACT =
+  "kungfu-buildchain-adopter-delivery-passport-binding";
+
+const ROOT_PATTERN = /^sha256:[0-9a-f]{64}$/;
+
+function issue(code, message, details = {}) {
+  return { code, message, details };
+}
+
+function validateRootedJson(value, rootField, code, label) {
+  const root = value?.[rootField];
+  if (!ROOT_PATTERN.test(root ?? "")) {
+    return [issue(code, `${label} must be a canonical sha256 root`)];
+  }
+  try {
+    const preimage = structuredClone(value);
+    delete preimage[rootField];
+    return adopterDeliveryGateDigest(preimage) === root
+      ? []
+      : [issue(code, `${label} does not match its exact JSON closure`)];
+  } catch {
+    return [issue(code, `${label} requires finite acyclic JSON`)];
+  }
+}
+
+function validateGateIdentity(result) {
+  const issues = [];
+  if (
+    result.schemaVersion !== 1 ||
+    result.contract !== ADOPTER_DELIVERY_GATE_RESULT_CONTRACT
+  ) {
+    issues.push(
+      issue(
+        "adopterDelivery.gateResult.contract",
+        "adopter delivery gate result contract is unsupported",
+      ),
+    );
+  }
+  if (
+    !result.project ||
+    !result.artifact ||
+    !result.protocol ||
+    !result.artifactProfile
+  ) {
+    issues.push(
+      issue(
+        "adopterDelivery.gateResult.closure",
+        "gate result must retain project, artifact, protocol, and artifact-profile bindings",
+      ),
+    );
+  }
+  if (!ROOT_PATTERN.test(result.artifact?.root ?? "")) {
+    issues.push(
+      issue(
+        "adopterDelivery.gateResult.artifact.root",
+        "delivery artifact root must be a canonical sha256 root",
+      ),
+    );
+  }
+  if (result.qualifying !== false || result.selfCertified !== false) {
+    issues.push(
+      issue(
+        "adopterDelivery.gateResult.nonClaims",
+        "delivery evidence must remain non-qualifying and non-self-certifying",
+      ),
+    );
+  }
+  return issues;
+}
+
+function validatePassedGate(result) {
+  if (result.status !== "passed") {
+    return result.status === "failed"
+      ? []
+      : [
+          issue(
+            "adopterDelivery.gateResult.status",
+            "gate status must be passed or failed",
+          ),
+        ];
+  }
+  const passed =
+    result.protocol?.loaded === true &&
+    ROOT_PATTERN.test(result.protocol?.reportRoot ?? "") &&
+    result.artifactProfile?.loaded === true &&
+    result.artifactProfile?.valid === true &&
+    result.semanticReport !== null &&
+    (result.issues?.length ?? -1) === 0;
+  return passed
+    ? []
+    : [
+        issue(
+          "adopterDelivery.gateResult.status",
+          "a passed gate must retain successful exact driver and artifact-profile evidence",
+        ),
+      ];
+}
+
+export function validateAdopterDeliveryGateResult(result) {
+  if (!result || typeof result !== "object" || Array.isArray(result)) {
+    return {
+      valid: false,
+      passed: false,
+      issues: [
+        issue(
+          "adopterDelivery.gateResult",
+          "adopter delivery gate result must be an object",
+        ),
+      ],
+    };
+  }
+  const issues = [
+    ...validateGateIdentity(result),
+    ...validateRootedJson(
+      result,
+      "gateRoot",
+      "adopterDelivery.gateResult.gateRoot",
+      "adopter delivery gate root",
+    ),
+    ...validatePassedGate(result),
+  ];
+  const valid = issues.length === 0;
+  return { valid, passed: valid && result.status === "passed", issues };
+}
+
+export function createAdopterDeliveryPassportBinding(gateResult) {
+  const normalized = structuredClone(gateResult);
+  const validation = validateAdopterDeliveryGateResult(normalized);
+  const binding = {
+    schemaVersion: 1,
+    contract: ADOPTER_DELIVERY_PASSPORT_BINDING_CONTRACT,
+    valid: validation.passed,
+    qualifying: false,
+    selfCertified: false,
+    gateResult: normalized,
+    validationIssues: validation.issues,
+    nonClaims: [
+      "A passing adopter delivery gate does not grant runtime permission or release authority.",
+      "The selected protocol driver retains semantic authority; Buildchain only binds its exact result into delivery evidence.",
+    ],
+  };
+  binding.bindingRoot = adopterDeliveryGateDigest(binding);
+  return binding;
+}
+
+export function normalizeAdopterDeliveryPassportBinding(value) {
+  if (!value) return undefined;
+  return value.contract === ADOPTER_DELIVERY_PASSPORT_BINDING_CONTRACT
+    ? structuredClone(value)
+    : createAdopterDeliveryPassportBinding(value);
+}
+
+export function validateAdopterDeliveryPassportBinding(
+  binding,
+  { expectedProjectRepository = "" } = {},
+) {
+  if (!binding || typeof binding !== "object" || Array.isArray(binding)) {
+    return [
+      issue(
+        "adopterDelivery.binding",
+        "adopter delivery passport binding must be an object",
+      ),
+    ];
+  }
+  const gateValidation = validateAdopterDeliveryGateResult(binding.gateResult);
+  const issues = [
+    ...validateRootedJson(
+      binding,
+      "bindingRoot",
+      "adopterDelivery.binding.bindingRoot",
+      "adopter delivery binding root",
+    ),
+    ...gateValidation.issues,
+  ];
+  if (
+    binding.schemaVersion !== 1 ||
+    binding.contract !== ADOPTER_DELIVERY_PASSPORT_BINDING_CONTRACT
+  ) {
+    issues.push(
+      issue(
+        "adopterDelivery.binding.contract",
+        "adopter delivery passport binding contract is unsupported",
+      ),
+    );
+  }
+  if (
+    binding.valid !== gateValidation.passed ||
+    binding.qualifying !== false ||
+    binding.selfCertified !== false
+  ) {
+    issues.push(
+      issue(
+        "adopterDelivery.binding.status",
+        "binding status must preserve a passing non-authoritative gate result",
+      ),
+    );
+  }
+  if (!gateValidation.passed) {
+    issues.push(
+      issue(
+        "adopterDelivery.status",
+        "release passport requires a passed adopter delivery gate",
+      ),
+    );
+  }
+  if (
+    expectedProjectRepository &&
+    binding.gateResult?.project?.adopterId !== expectedProjectRepository
+  ) {
+    issues.push(
+      issue(
+        "adopterDelivery.project",
+        "delivery project must match the release passport product repository",
+      ),
+    );
+  }
+  return issues;
+}
+
+function sameJson(left, right) {
+  try {
+    return adopterDeliveryGateDigest(left) === adopterDeliveryGateDigest(right);
+  } catch {
+    return false;
+  }
+}
+
+export function validateAdopterDeliveryReleaseEvidence({
+  binding,
+  artifactBinding,
+  expectedProjectRepository = "",
+} = {}) {
+  if (!binding && !artifactBinding) return [];
+  if (!binding) {
+    return [
+      issue(
+        "adopterDelivery.passport",
+        "artifact evidence cannot introduce delivery authority absent from the passport",
+      ),
+    ];
+  }
+  const issues = validateAdopterDeliveryPassportBinding(binding, {
+    expectedProjectRepository,
+  });
+  if (!artifactBinding || !sameJson(artifactBinding, binding)) {
+    issues.push(
+      issue(
+        "adopterDelivery.artifactEvidence",
+        "passport and artifact evidence must bind the same exact delivery result",
+      ),
+    );
+  }
+  return issues;
+}

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

@@ -10,6 +10,7 @@ export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
   { id: "github-governance-authority", title: "GitHub governance authority", path: "docs/github-governance-authority.md", plane: "verify" },
   { id: "release-candidate", title: "Release Candidate Passport", path: "docs/release-candidate.md", plane: "verify" },
   { id: "release-train", title: "Release Train and Release Cut", path: "docs/release-train.md", plane: "verify" },
+  { id: "next-development-transition", title: "Next-development transition", path: "docs/next-development-transition.md", plane: "verify" },
   { id: "release-propagation", title: "Release propagation", path: "docs/release-propagation.md", plane: "use" },
   { id: "readme-badges", title: "README badge blocks", path: "docs/readme-badges.md", plane: "use" },
   { id: "homebrew", title: "Homebrew distribution indexes", path: "docs/homebrew.md", plane: "use" },
@@ -29,10 +30,12 @@ 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" },
   { id: "release-governance", title: "Release governance", path: "docs/release-governance.md", plane: "why" },
+  { id: "v4-compatibility-facts", title: "Buildchain v4 compatibility Facts", path: "docs/v4-compatibility-facts.md", plane: "verify" },
   { id: "release-flow", title: "Release flow", path: "docs/release-flow.md", plane: "verify" },
   { id: "runtime-train-validation", title: "Runtime train validation", path: "docs/runtime-train-validation.md", plane: "verify" },
   { id: "versioning", title: "Versioning", path: "docs/versioning.md", plane: "why" },