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

package/packages/core/kfd-product-gates.js

@@ -10,12 +10,8 @@ export const KFD_PRODUCT_GATE_INPUT_CONTRACT =
   "kungfu-buildchain-kfd-product-gate-input";
 export const KFD_PRODUCT_GATE_CONTRACT =
   "kungfu-buildchain-kfd-product-gate";
-export const KFD_SUPPORT_PROJECTION_CONTRACT =
-  "kungfu-buildchain-kfd-support-projection";
 export const KFD_PRODUCT_GATE_INPUT_SCHEMA_ID =
   "https://buildchain.libkungfu.dev/schemas/kfd-product-gate-input-v1.schema.json";
-export const KFD_SUPPORT_PROJECTION_SCHEMA_ID =
-  "https://buildchain.libkungfu.dev/schemas/kfd-support-projection-v1.schema.json";
 
 const SUPPORTED_GATE_STANDARDS = Object.freeze(["kfd-4", "kfd-5", "kfd-7"]);
 const SUPPORTED_GATE_STANDARD_SET = new Set(SUPPORTED_GATE_STANDARDS);
@@ -127,48 +123,6 @@ export const KFD_PRODUCT_GATE_INPUT_SCHEMA = {
   },
 };
 
-export const KFD_SUPPORT_PROJECTION_SCHEMA = {
-  $schema: "https://json-schema.org/draft/2020-12/schema",
-  $id: KFD_SUPPORT_PROJECTION_SCHEMA_ID,
-  title: "Buildchain KFD support projection v1",
-  description:
-    "A release-bound, non-authoritative projection of one product-owned KFD support matrix.",
-  type: "object",
-  additionalProperties: false,
-  required: [
-    "schemaVersion",
-    "contract",
-    "matrix",
-    "standardPackage",
-    "gateResults",
-    "rows",
-    "status",
-    "projectionRoot",
-    "nonClaims",
-  ],
-  properties: {
-    schemaVersion: { const: 1 },
-    contract: { const: KFD_SUPPORT_PROJECTION_CONTRACT },
-    matrix: {
-      type: "object",
-      additionalProperties: false,
-      required: ["contract", "root", "authorityPath"],
-      properties: { contract: STRING, root: SHA256, authorityPath: STRING },
-    },
-    standardPackage: {
-      type: "object",
-      additionalProperties: false,
-      required: ["name", "version", "standardsSha256"],
-      properties: { name: STRING, version: STRING, standardsSha256: SHA256 },
-    },
-    gateResults: { type: "array", minItems: 3, items: { type: "object" } },
-    rows: { type: "array", minItems: 13, maxItems: 13, items: { type: "object" } },
-    status: { enum: ["passed", "failed"] },
-    projectionRoot: SHA256,
-    nonClaims: { type: "array", minItems: 1, items: STRING },
-  },
-};
-
 const require = createRequire(import.meta.url);
 let verifierPromise;
 
@@ -604,262 +558,8 @@ export function validateKfdProductGateResult(result, {
   return { valid: issues.length === 0, issues };
 }
 
-function expectedKfdIds() {
-  return Array.from({ length: 13 }, (_, index) => `KFD-${index + 1}`);
-}
-
-function normalizeMatrixRoot(matrix, matrixRoot) {
-  const normalized = normalizeSha256(matrixRoot);
-  return normalized || kfdProductGateDigest(matrix);
-}
-
-function projectMatrixRow(row) {
-  return {
-    id: row.id,
-    key: row.key,
-    title: row.title,
-    supportStatus: row.supportStatus,
-    normative: row.normative,
-    implementation: row.implementation,
-    verification: row.verification,
-    buildchain: row.buildchain,
-    releaseQualification: row.releaseQualification,
-    claimClass: row.claimClass,
-    knownLimitations: row.knownLimitations,
-    owner: row.owner,
-    nextGate: row.nextGate,
-  };
-}
-
-function validateMatrixRows(matrix, gatesByStandard, issues) {
-  const rows = Array.isArray(matrix?.rows) ? matrix.rows : [];
-  const expectedIds = expectedKfdIds();
-  const ids = rows.map((row) => row?.id);
-  if (rows.length !== expectedIds.length || new Set(ids).size !== expectedIds.length) {
-    issues.push(issue("matrix-row-set", "rows", "support matrix must contain exactly one row for KFD-1 through KFD-13"));
-  }
-  for (const id of expectedIds) {
-    const row = rows.find((entry) => entry?.id === id);
-    if (!row) {
-      issues.push(issue("matrix-row-missing", "rows", `${id} is missing`));
-      continue;
-    }
-    const key = id.toLowerCase();
-    const metadata = standardMetadata(key);
-    if (row.key !== key || row?.normative?.status !== metadata.status || row?.normative?.revision !== metadata.revision) {
-      issues.push(issue("matrix-normative-drift", `rows.${id}.normative`, `${id} must match installed KFD status and revision`, {
-        expected: { key, status: metadata.status, revision: metadata.revision },
-        actual: { key: row.key, status: row?.normative?.status, revision: row?.normative?.revision },
-      }));
-    }
-    const shipped = row?.releaseQualification?.shippedSupport === true;
-    if (
-      shipped &&
-      (
-        row?.implementation?.status !== "implemented" ||
-        row?.verification?.status !== "passed" ||
-        row?.buildchain?.gateStatus !== "passed" ||
-        !String(row.supportStatus || "").includes("supported")
-      )
-    ) {
-      issues.push(issue("matrix-shipped-widening", `rows.${id}`, `${id} cannot be shipped without implemented, verified, and passed Buildchain evidence`));
-    }
-  }
-  for (const id of ["KFD-4", "KFD-5"]) {
-    const row = rows.find((entry) => entry?.id === id);
-    if (row?.supportStatus !== "candidate" || row?.releaseQualification?.shippedSupport !== false) {
-      issues.push(issue("matrix-candidate-widening", `rows.${id}`, `${id} must remain a non-shipped candidate`));
-    }
-  }
-  const kfd6 = rows.find((entry) => entry?.id === "KFD-6");
-  if (
-    kfd6?.supportStatus !== "unsupported" ||
-    kfd6?.releaseQualification?.shippedSupport !== false ||
-    kfd6?.buildchain?.gateStatus === "passed"
-  ) {
-    issues.push(issue("matrix-kfd6-barrier", "rows.KFD-6", "KFD-6 must remain explicitly unsupported and non-shipped"));
-  }
-  for (let number = 8; number <= 13; number += 1) {
-    const id = `KFD-${number}`;
-    const row = rows.find((entry) => entry?.id === id);
-    if (
-      row?.supportStatus !== "draft-adopter-evidence" ||
-      row?.releaseQualification?.shippedSupport !== false ||
-      row?.buildchain?.gateStatus === "passed"
-    ) {
-      issues.push(issue("matrix-draft-barrier", `rows.${id}`, `${id} must remain draft adopter evidence and non-shipped`));
-    }
-  }
-  for (const standard of SUPPORTED_GATE_STANDARDS) {
-    const id = standard.toUpperCase();
-    const row = rows.find((entry) => entry?.id === id);
-    const gate = gatesByStandard.get(standard);
-    if (!gate) {
-      issues.push(issue("matrix-gate-missing", `rows.${id}.buildchain`, `${id} requires a Buildchain product-gate result`));
-      continue;
-    }
-    const rowPassed = row?.buildchain?.gateStatus === "passed";
-    const gatePassed = gate.status === "passed";
-    if (rowPassed !== gatePassed) {
-      issues.push(issue("matrix-gate-disagreement", `rows.${id}.buildchain.gateStatus`, `${id} matrix and Buildchain gate disagree`, {
-        matrix: row?.buildchain?.gateStatus,
-        gate: gate.status,
-      }));
-    }
-    if (row?.buildchain?.protocol !== `${KFD_PRODUCT_GATE_CONTRACT}/v1`) {
-      issues.push(issue("matrix-gate-protocol", `rows.${id}.buildchain.protocol`, `${id} must name the versioned Buildchain product-gate protocol`));
-    }
-  }
-  return rows;
-}
-
-export function createKfdSupportProjection({
-  matrix,
-  matrixRoot = "",
-  gateResults = [],
-  authorityPath = ".buildchain/kfd/support-matrix.json",
-  expectedSourceSha = "",
-  checkedAt = new Date().toISOString(),
-} = {}) {
-  const issues = [];
-  if (!isObject(matrix) || matrix.contract !== "kungfu-kfd-support-matrix" || matrix.schemaVersion !== 1) {
-    issues.push(issue("matrix-contract", "", "support matrix must use kungfu-kfd-support-matrix v1"));
-  }
-  if (
-    matrix?.upstream?.package !== kfdPackageJson.name ||
-    matrix?.upstream?.version !== kfdPackageJson.version ||
-    matrix?.upstream?.standardsSha256 !== standardsFileDigest()
-  ) {
-    issues.push(issue("matrix-standard-package", "upstream", "support matrix must bind the installed KFD package and standards bytes", {
-      expected: {
-        package: kfdPackageJson.name,
-        version: kfdPackageJson.version,
-        standardsSha256: standardsFileDigest(),
-      },
-      actual: matrix?.upstream,
-    }));
-  }
-  const gatesByStandard = new Map();
-  for (const [index, gate] of gateResults.entries()) {
-    const validation = validateKfdProductGateResult(gate, { expectedSourceSha, checkedAt });
-    if (!validation.valid) {
-      issues.push(issue("gate-result-invalid", `gateResults[${index}]`, "gate result is invalid", {
-        gateIssues: validation.issues,
-      }));
-    }
-    if (gatesByStandard.has(gate?.standard)) {
-      issues.push(issue("gate-result-duplicate", `gateResults[${index}].standard`, `${gate.standard} gate result is duplicated`));
-    }
-    gatesByStandard.set(gate?.standard, gate);
-  }
-  const rows = validateMatrixRows(matrix, gatesByStandard, issues);
-  const projection = {
-    schemaVersion: 1,
-    contract: KFD_SUPPORT_PROJECTION_CONTRACT,
-    matrix: {
-      contract: matrix?.contract || "",
-      root: normalizeMatrixRoot(matrix, matrixRoot),
-      authorityPath: optionalString(matrix?.authority?.path || authorityPath),
-    },
-    standardPackage: {
-      name: kfdPackageJson.name,
-      version: kfdPackageJson.version,
-      standardsSha256: standardsFileDigest(),
-    },
-    gateResults: SUPPORTED_GATE_STANDARDS.map((standard) => {
-      const gate = gatesByStandard.get(standard);
-      return gate
-        ? {
-            standard,
-            standardRevision: gate.standardRevision,
-            sourceSha: gate?.source?.sha || "",
-            evidenceCut: gate.evidenceCut,
-            status: gate.status,
-            gateRoot: gate.gateRoot,
-            issueCount: Array.isArray(gate.issues) ? gate.issues.length : 0,
-          }
-        : { standard, status: "missing", gateRoot: "", issueCount: 1 };
-    }),
-    rows: rows.map(projectMatrixRow),
-    status: issues.length === 0 ? "passed" : "failed",
-    nonClaims: [
-      "This projection does not replace the product-owned support matrix.",
-      "A passed Buildchain gate does not by itself activate, ship, or certify a KFD adoption.",
-      "Candidate, unsupported, draft, and non-qualifying matrix states cannot be widened by this projection.",
-    ],
-    issues,
-  };
-  projection.projectionRoot = kfdProductGateDigest(projection);
-  return projection;
-}
-
-export function validateKfdSupportProjection(projection, {
-  expectedSourceSha = "",
-  checkedAt = new Date().toISOString(),
-} = {}) {
-  const issues = [];
-  if (!isObject(projection) || projection.schemaVersion !== 1 || projection.contract !== KFD_SUPPORT_PROJECTION_CONTRACT) {
-    issues.push(issue("projection-contract", "", `projection must use ${KFD_SUPPORT_PROJECTION_CONTRACT} v1`));
-    return { valid: false, issues };
-  }
-  const copy = structuredClone(projection);
-  const root = copy.projectionRoot;
-  delete copy.projectionRoot;
-  if (root !== kfdProductGateDigest(copy)) {
-    issues.push(issue("projection-root", "projectionRoot", "support projection root does not match its content"));
-  }
-  if (projection.status !== "passed" || (projection.issues || []).length !== 0) {
-    issues.push(issue("projection-status", "status", "release passport requires a passed support projection"));
-  }
-  if (
-    projection?.standardPackage?.name !== kfdPackageJson.name ||
-    projection?.standardPackage?.version !== kfdPackageJson.version ||
-    projection?.standardPackage?.standardsSha256 !== standardsFileDigest()
-  ) {
-    issues.push(issue("projection-standard-package", "standardPackage", "support projection uses stale KFD package metadata"));
-  }
-  if (!new RegExp(SHA256_PATTERN).test(optionalString(projection?.matrix?.root))) {
-    issues.push(issue("projection-matrix-root", "matrix.root", "support projection must bind the exact support matrix bytes"));
-  }
-  if (!optionalString(projection?.matrix?.authorityPath)) {
-    issues.push(issue("projection-matrix-authority", "matrix.authorityPath", "support projection must retain the product-owned matrix authority path"));
-  }
-  const gatesByStandard = new Map();
-  for (const [index, gate] of (projection.gateResults || []).entries()) {
-    if (!SUPPORTED_GATE_STANDARD_SET.has(gate?.standard)) {
-      issues.push(issue("projection-gate-standard", `gateResults[${index}].standard`, "projected gate must be kfd-4, kfd-5, or kfd-7"));
-      continue;
-    }
-    if (gatesByStandard.has(gate.standard)) {
-      issues.push(issue("projection-gate-duplicate", `gateResults[${index}].standard`, `${gate.standard} is duplicated`));
-    }
-    gatesByStandard.set(gate.standard, gate);
-    if (gate.standardRevision !== standardMetadata(gate.standard).revision) {
-      issues.push(issue("projection-gate-revision", `gateResults[${index}].standardRevision`, "projected gate revision is stale"));
-    }
-    if (!new RegExp(SHA256_PATTERN).test(optionalString(gate.gateRoot))) {
-      issues.push(issue("projection-gate-root", `gateResults[${index}].gateRoot`, "projected gate must retain its gate root"));
-    }
-    if (expectedSourceSha && gate.sourceSha !== expectedSourceSha) {
-      issues.push(issue("projection-source", `gateResults[${index}].sourceSha`, "gate source must match the release source"));
-    }
-    const checked = parseDate(checkedAt);
-    const expires = parseDate(gate?.evidenceCut?.expiresAt);
-    if (!Number.isFinite(expires) || (Number.isFinite(checked) && expires <= checked)) {
-      issues.push(issue("projection-stale-gate", `gateResults[${index}].evidenceCut.expiresAt`, "projected gate evidence is stale"));
-    }
-  }
-  validateMatrixRows({ rows: projection.rows }, gatesByStandard, issues);
-  if (!Array.isArray(projection.nonClaims) || projection.nonClaims.length === 0) {
-    issues.push(issue("projection-non-claims", "nonClaims", "support projection must preserve non-claims"));
-  }
-  return { valid: issues.length === 0, issues };
-}
-
 export const kfdProductGates = Object.freeze({
   evaluate: evaluateKfdProductGate,
-  projectSupport: createKfdSupportProjection,
   validateGateResult: validateKfdProductGateResult,
-  validateSupportProjection: validateKfdSupportProjection,
   verifyRecord: verifyKfdRecord,
 });

package/packages/core/release-passport-contract.js

@@ -1,8 +1,18 @@
+import path from "node:path";
 import kfdStandards from "@kungfu-tech/kfd/standards.json" with { type: "json" };
 import {
-  RELEASE_CHECK_REPORT_CONTRACT,
-  RELEASE_PASSPORT_CONTRACT,
-} from "./release-passport.js";
+  createKfdAdopterManifestGate,
+  createKfdLegacySupportMatrixProjection,
+  validateKfdLegacySupportMatrixProjection,
+} from "./kfd-adopter-manifest.js";
+import {
+  createKfdAdopterReleaseBinding,
+  installedKfdPackageArtifactRoot,
+  validateKfdAdopterReleaseBinding,
+} from "./artifact-verification-envelope.js";
+
+export const RELEASE_PASSPORT_CONTRACT = "kungfu-buildchain-release-passport";
+export const RELEASE_CHECK_REPORT_CONTRACT = "kungfu-buildchain-release-check-report";
 
 export const RELEASE_PASSPORT_SCHEMA_ID =
   "https://buildchain.libkungfu.dev/schemas/release-passport-v1.schema.json";
@@ -100,6 +110,7 @@ export const RELEASE_PASSPORT_SCHEMA = {
     "kfd-1": OBJECT,
     "kfd-2": OBJECT,
     "kfd-3": OBJECT,
+    kfdAdopter: OBJECT,
     kfdSupport: OBJECT,
   },
   additionalProperties: true,
@@ -123,6 +134,7 @@ const BUILDCHAIN_AGGREGATION_FIELDS = [
   "platformArtifactManifests",
   "distTagPromotion",
   "controllerReceipts",
+  "kfdAdopter",
   "kfdSupport",
   "githubArtifactAttestations",
   "artifacts",
@@ -163,11 +175,12 @@ export function createReleasePassportCheckManifest({ standards = kfdStandards }
         result: "check-report.json",
       },
       kfdSupportProjection: {
-        inputSchema: "schemas/kfd-product-gate-input-v1.schema.json",
-        projectionSchema: "schemas/kfd-support-projection-v1.schema.json",
+        authorityContract: "kfd.adopter-conformance-manifest/v1",
+        gateContract: "kungfu-buildchain-kfd-adopter-manifest-gate",
+        bindingContract: "kungfu-buildchain-kfd-adopter-release-binding",
         evidence: "kfd-support.json",
         rule:
-          "The passport mirrors one product-owned support matrix and validated product-gate results without widening any claim state.",
+          "The standard adopter manifest is the sole declaration authority; the legacy support matrix is an exact derived projection only.",
       },
     },
     ownership: {
@@ -199,6 +212,14 @@ export function createReleasePassportCheckManifest({ standards = kfdStandards }
           when: "kfdSupport is present",
           pointer: "evidence.kfdSupport",
         },
+        {
+          when: "kfdAdopter is present",
+          pointer: "evidence.kfdAdopterManifest",
+        },
+        {
+          when: "kfdAdopter is present",
+          pointer: "evidence.kfdAdopterGate",
+        },
       ],
       rule:
         "The normative checker resolves every declared sibling relative to the passport and fails closed on missing required evidence, digest drift, or semantic mismatch.",
@@ -264,3 +285,195 @@ export function validateReleasePassportSchema(passport) {
     issues,
   };
 }
+
+function passportStableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(passportStableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${passportStableJson(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function passportOptional(value) {
+  return value === undefined || value === null ? "" : String(value);
+}
+
+export function defaultReleaseProductMechanism({ repository = "", productName = "Buildchain" } = {}) {
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-product-mechanism",
+    product: { name: productName, repository, northStar: "GitHub-native release passport protocol for binary and multi-artifact products." },
+    trustModel: {
+      executionSubstrate: "github-actions",
+      releaseAuthority: "protected Buildchain channel refs, exact tags, and release passport evidence",
+      runnerRequirement: "runner facts are recorded, but the protocol is runner-agnostic",
+    },
+    compatibility: {
+      promise: "release passport schemas are welded surfaces; additive fields are allowed, breaking semantic changes require a new major line",
+      kfd: "KFD-1",
+    },
+  };
+}
+
+export function defaultReleaseImpact({ tag = "", line = "", decision = "unknown" } = {}) {
+  const normalized = String(decision).toLowerCase();
+  const final = ["unknown", "patch", "minor", "major"].includes(normalized) ? normalized : String(decision);
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-impact",
+    release: { tag, line },
+    versionImpact: { final, source: "default", rationale: "No surface impact classification was supplied." },
+    surfaceImpacts: [],
+    classification: final,
+    breaking: final === "major",
+    security: false,
+    migrationRequired: final === "major",
+    summary: "No release impact summary was supplied.",
+    recovery: { rollback: "Use the previous exact release tag or previous floating channel ref.", block: "Fail closed if release passport verification fails." },
+  };
+}
+
+export function defaultReleaseAgentIndex({ tag = "", passportPath = "buildchain.release.json" } = {}) {
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-agent-index",
+    release: { tag },
+    entrypoints: [
+      { id: "release-passport", kind: "json", path: passportPath, description: "Read this first to verify release completeness, artifacts, impact, and recovery pointers." },
+      { id: "llms", kind: "text", path: "llms.txt", description: "Short agent-readable release instructions." },
+    ],
+  };
+}
+
+export function defaultReleaseLlmsText({ tag = "", passportPath = "buildchain.release.json" } = {}) {
+  return [
+    "# Buildchain Release Passport",
+    "",
+    `Release: ${tag || "unknown"}`,
+    "",
+    `Start with ${passportPath}. Verify artifact-evidence.json before installing binaries.`,
+    "If verification fails, do not install or promote this release.",
+  ].join("\n");
+}
+
+export function buildReleaseArtifactEvidence({ normalizedAssets = [], repository = "", tag = "", sourceSha = "", workflow = {}, kfdAdopter } = {}) {
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-artifact-evidence",
+    repository: passportOptional(repository),
+    release: { tag: passportOptional(tag), sourceSha: passportOptional(sourceSha) },
+    generatedAt: new Date().toISOString(),
+    runner: {
+      kind: passportOptional(workflow.runnerKind || workflow.runner?.kind || ""),
+      os: passportOptional(workflow.runnerOs || workflow.runner?.os || ""),
+      arch: passportOptional(workflow.runnerArch || workflow.runner?.arch || ""),
+      labels: Array.isArray(workflow.runnerLabels) ? workflow.runnerLabels : [],
+      image: passportOptional(workflow.runnerImage || workflow.runner?.image || ""),
+    },
+    workflow: {
+      name: passportOptional(workflow.name),
+      runId: passportOptional(workflow.runId),
+      runAttempt: passportOptional(workflow.runAttempt),
+      url: passportOptional(workflow.url),
+    },
+    artifacts: normalizedAssets.map((asset) => ({
+      name: asset.name, kind: asset.kind, platform: asset.platform, size: asset.size,
+      sha256: asset.sha256, url: asset.url, githubAssetId: asset.githubAssetId,
+      attestation: passportOptional(asset.attestation || ""),
+    })),
+    ...(kfdAdopter ? { kfdAdopter: structuredClone(kfdAdopter) } : {}),
+  };
+}
+
+export function prepareReleasePassportKfdSections({ kfd1, kfd2Claims, kfd3, kfdAdopter, kfdSupport, kfd1DefaultKey, createKfd2, evidencePaths = {} } = {}) {
+  const one = kfd1?.passportSection ? kfd1 : undefined;
+  const three = kfd3?.passportSection ? kfd3 : undefined;
+  const adopter = kfdAdopter ? structuredClone(kfdAdopter) : undefined;
+  const support = kfdSupport ? structuredClone(kfdSupport) : undefined;
+  const two = createKfd2({ explicitClaims: kfd2Claims, kfd1Section: one?.passportSection, kfd3Section: three?.passportSection });
+  return {
+    sectionEntries: [
+      [one?.key || kfd1DefaultKey, one?.passportSection], ["kfd-2", two],
+      [three?.key || "kfd-3", three?.passportSection], ["kfdAdopter", adopter], ["kfdSupport", support],
+    ],
+    evidence: {
+      kfd1: one ? `${one.key || kfd1DefaultKey}` : "", kfd2: two ? "kfd-2" : "", kfd3: three ? `${three.key || "kfd-3"}` : "",
+      kfdAdopterManifest: adopter ? evidencePaths.manifest || "kfd-adopter-manifest.json" : "",
+      kfdAdopterGate: adopter ? evidencePaths.gate || "kfd-adopter-manifest-gate.json" : "",
+      kfdSupport: support ? evidencePaths.support || "kfd-support.json" : "",
+    },
+  };
+}
+
+export function collectKfdAdopterReleaseEvidence({ manifest, gateResults = [], comparisonMatrix, sourceSha = "", checkedAt } = {}) {
+  if (!manifest) {
+    if (comparisonMatrix || gateResults.length > 0) {
+      throw new Error("KFD support and product-gate inputs require --kfd-adopter-manifest-json; --kfd-support-matrix-json is comparison-only");
+    }
+    return {};
+  }
+  const manifestGate = createKfdAdopterManifestGate({
+    manifest, packageArtifactRoot: installedKfdPackageArtifactRoot(), gateResults,
+    expectedSourceSha: sourceSha, checkedAt,
+  });
+  const legacyProjection = createKfdLegacySupportMatrixProjection({ manifest, manifestGate });
+  if (comparisonMatrix) {
+    const comparison = validateKfdLegacySupportMatrixProjection(comparisonMatrix, { manifest, manifestGate });
+    if (!comparison.valid) {
+      throw new Error(`legacy KFD support matrix drifted from the standard adopter manifest: ${JSON.stringify(comparison.issues)}`);
+    }
+  }
+  return {
+    manifest, manifestGate, legacyProjection,
+    binding: createKfdAdopterReleaseBinding({ manifest, manifestGate, legacyProjection, expectedSourceSha: sourceSha }),
+  };
+}
+
+export function validateKfdAdopterReleaseEvidence({ binding, artifactBinding, manifest, manifestGate, legacyProjection, passportLegacyProjection, expectedSourceSha = "" } = {}) {
+  if (!binding) {
+    return passportLegacyProjection
+      ? [{ code: "kfdSupport.authority", message: "legacy KFD support projection requires the standard adopter manifest binding" }]
+      : [];
+  }
+  const issues = validateKfdAdopterReleaseBinding(binding, {
+    manifest, manifestGate, legacyProjection, expectedSourceSha,
+  }).issues.map((entry) => ({ code: `kfdAdopter.${entry.path || entry.code}`, message: entry.message, details: entry }));
+  if (!artifactBinding || passportStableJson(artifactBinding) !== passportStableJson(binding)) {
+    issues.push({ code: "kfdAdopter.artifactEvidence", message: "release passport and artifact evidence must bind the same exact KFD adopter closure" });
+  }
+  if (!passportLegacyProjection || !legacyProjection
+    || passportStableJson(legacyProjection) !== passportStableJson(passportLegacyProjection)) {
+    issues.push({ code: "kfdAdopter.legacyProjection", message: "legacy support projection must exactly match the manifest-derived passport sibling" });
+  }
+  return issues;
+}
+
+async function explicitOrSibling({ location, basePath, sibling, readJson, resolveSibling, fallback }) {
+  if (location) return readJson(location);
+  return await resolveSibling(basePath, sibling) || fallback;
+}
+
+export async function resolveReleasePassportVerificationInputs({ passportLocation, locations = {}, readJson, resolveSibling } = {}) {
+  const passport = await readJson(passportLocation);
+  const basePath = /^https?:\/\//.test(passportLocation) ? passportLocation : path.resolve(passportLocation);
+  const resolve = (location, sibling, fallback) => explicitOrSibling({ location, basePath, sibling, readJson, resolveSibling, fallback });
+  const releaseEvidenceDocuments = [];
+  for (const reference of Array.isArray(passport.releaseEvidence) ? passport.releaseEvidence : []) {
+    const id = String(reference?.id || "");
+    const safePath = /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id) && reference?.path === `release-evidence-${id}.json`;
+    releaseEvidenceDocuments.push({ reference, document: safePath ? await resolveSibling(basePath, reference.path) : undefined });
+  }
+  return {
+    passport,
+    artifactEvidence: await resolve(locations.artifactEvidence, passport.evidence?.artifactEvidence, {}),
+    publishEvidence: await resolve(locations.publishEvidence, passport.evidence?.publishEvidence, {}),
+    impact: await resolve(locations.impact, passport.evidence?.impact, {}),
+    agentIndex: await resolve(locations.agentIndex, passport.evidence?.agentIndex, {}),
+    productMechanism: await resolve(locations.productMechanism, passport.product?.mechanism, {}),
+    kfdAgentHubEvidence: await resolve(locations.kfdAgentHubEvidence, passport.evidence?.kfdAgentHub),
+    kfdAdopterManifest: await resolve(locations.kfdAdopterManifest, passport.evidence?.kfdAdopterManifest),
+    kfdAdopterManifestGate: await resolve(locations.kfdAdopterManifestGate, passport.evidence?.kfdAdopterGate),
+    kfdSupportEvidence: await resolve(locations.kfdSupportEvidence, passport.evidence?.kfdSupport),
+    releaseEvidenceDocuments,
+  };
+}