@kungfu-tech/buildchain 2.8.5-alpha.0 → 2.8.5-alpha.2

package/dist/site/buildchain-contract.json

@@ -4,7 +4,7 @@
   "product": {
     "name": "Buildchain",
     "package": "@kungfu-tech/buildchain",
-    "version": "2.8.5-alpha.0",
+    "version": "2.8.5-alpha.2",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "majorLine": "v2",
@@ -193,7 +193,7 @@
         "release-state SHA is recorded as a durable audit entrance"
       ],
       "breakingDigest": "sha256:b627e1b2ece9b6049517a942c5139e342e6077cdd3d8962d61cef8481b1f70ad",
-      "auditDigest": "sha256:f1c2d70510f074102c2e9ff87b638b7b9b33edaa88aad8abc1e73e75e46a6af7"
+      "auditDigest": "sha256:3476a0837292b81a6efeb7c989dc1ee975b2bd8e8882273fd4eb5f865d330bc1"
     },
     {
       "contractVersion": 1,
@@ -218,7 +218,7 @@
         "KFD self contract witnesses record source/artifact hashes, self-hosting boundary, and responsibility state"
       ],
       "breakingDigest": "sha256:f46c1f67b94957ad956cf70db59a73fd5690bd67c91edf9c2d0eb8f3d1e3cf8d",
-      "auditDigest": "sha256:6a99ee108c385837ee9f1dbb75848f6ea434b6474977e6e567ae81f8fc9a555c"
+      "auditDigest": "sha256:534707144fa2c440fe6958073a8a161790f12b8fb4695e3b06e43f43a6c87ffb"
     },
     {
       "contractVersion": 1,
@@ -242,7 +242,7 @@
         "prose-only public claims downgrade the release trust passport audit"
       ],
       "breakingDigest": "sha256:f0b636eb925ddbf45ff1a8872454ab7b4dd98857cac12bb75217830130e62a16",
-      "auditDigest": "sha256:f1c2d70510f074102c2e9ff87b638b7b9b33edaa88aad8abc1e73e75e46a6af7"
+      "auditDigest": "sha256:3476a0837292b81a6efeb7c989dc1ee975b2bd8e8882273fd4eb5f865d330bc1"
     },
     {
       "contractVersion": 1,
@@ -271,7 +271,7 @@
         "KFD-3 passports expose releaseStatus, witness hashes, declared capability verification, reverse audit boundary, residual risk, and responsibility state"
       ],
       "breakingDigest": "sha256:33654f3444c893754aacc42dde3051f0a371bd17c6ef7c657c579a07159cd7c1",
-      "auditDigest": "sha256:6a99ee108c385837ee9f1dbb75848f6ea434b6474977e6e567ae81f8fc9a555c"
+      "auditDigest": "sha256:534707144fa2c440fe6958073a8a161790f12b8fb4695e3b06e43f43a6c87ffb"
     },
     {
       "contractVersion": 1,
@@ -342,9 +342,9 @@
         "agents can discover supported Node APIs without importing internal file paths"
       ],
       "breakingDigest": "sha256:48f925608d3e2131d90936b07dc2a30341204cae3e6e785c0f77d61ad755c945",
-      "auditDigest": "sha256:2d1c150464effb5e8ad5d5a6ef78ee71899b8bd74a46c7b7a7a01fec1e35c86a"
+      "auditDigest": "sha256:0660c503639f5ca6d23ba9c7492b31ee9b05f036ffe76ed5dc8b6cb3bfde367b"
     }
   ],
   "compatibilityDigest": "sha256:36421b592a782decbfe31a7d8d42d70ce1100a56a2c4f4a0ccc21f0617dc72bf",
-  "contractDigest": "sha256:7b6cf45302dbcdf36d469e19095fe84931bf4a4f5cbe03ebeaae543f9a8121fc"
+  "contractDigest": "sha256:5901bfd2f57fc2cb2e6d4da7fb3c2d401111917db86bd404a3a27193d1a522fa"
 }

package/dist/site/node-api-registry.json

@@ -50,7 +50,7 @@
       "specifier": "@kungfu-tech/buildchain/kfd-gate",
       "export": "./kfd-gate",
       "target": "./packages/core/kfd-gate.js",
-      "digest": "sha256:6a99ee108c385837ee9f1dbb75848f6ea434b6474977e6e567ae81f8fc9a555c"
+      "digest": "sha256:534707144fa2c440fe6958073a8a161790f12b8fb4695e3b06e43f43a6c87ffb"
     },
     {
       "specifier": "@kungfu-tech/buildchain/release-candidate",
@@ -62,7 +62,7 @@
       "specifier": "@kungfu-tech/buildchain/release-passport",
       "export": "./release-passport",
       "target": "./packages/core/release-passport.js",
-      "digest": "sha256:f1c2d70510f074102c2e9ff87b638b7b9b33edaa88aad8abc1e73e75e46a6af7"
+      "digest": "sha256:3476a0837292b81a6efeb7c989dc1ee975b2bd8e8882273fd4eb5f865d330bc1"
     },
     {
       "specifier": "@kungfu-tech/buildchain/release-propagation",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.8.5-alpha.0",
+  "version": "2.8.5-alpha.2",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -98,7 +98,7 @@
     "vitest": "^4.1.9"
   },
   "dependencies": {
-    "@kungfu-tech/kfd": "1.0.0-alpha.3",
+    "@kungfu-tech/kfd": "github:kungfu-systems/kfd#1731900b81150ae29095329892b8d7d5670f2314",
     "smol-toml": "1.7.0"
   }
 }

package/packages/core/kfd-gate.js

@@ -58,6 +58,14 @@ function readJsonPackageExport(exportPath) {
   return JSON.parse(fs.readFileSync(require.resolve(exportPath), "utf8"));
 }
 
+function tryReadJsonPackageExport(exportPath) {
+  try {
+    return readJsonPackageExport(exportPath);
+  } catch {
+    return undefined;
+  }
+}
+
 function loadKfdPackageMetadata() {
   const packageJson = readJsonPackageExport("@kungfu-tech/kfd/package.json");
   const standards = readJsonPackageExport("@kungfu-tech/kfd/standards.json");
@@ -148,6 +156,50 @@ export function resolveKfd3Metadata({ requireSchemas = false } = {}) {
   };
 }
 
+export function resolveKfd2Metadata({ requireTrustTaxonomy = false } = {}) {
+  const { packageJson, standards } = loadKfdPackageMetadata();
+  const entries = Object.entries(standards.standards || {});
+  const entry = entries.find(([key, value]) => {
+    const names = [key, value?.key, value?.id, value?.label]
+      .filter(Boolean)
+      .map((name) => String(name).toLowerCase());
+    return names.includes("kfd-2");
+  });
+  if (!entry) {
+    throw new Error("KFD metadata package does not expose KFD-2 metadata");
+  }
+  const [key, standard] = entry;
+  const schemaIds = { ...(standard.schemaIds || {}) };
+  const schemaPaths = { ...(standard.schemaPaths || {}) };
+  const trustTaxonomyPath = schemaPaths.trustTaxonomy || "";
+  const trustTaxonomy = trustTaxonomyPath
+    ? tryReadJsonPackageExport(`@kungfu-tech/kfd/${trustTaxonomyPath}`)
+    : undefined;
+  if (requireTrustTaxonomy && (!schemaIds.trustTaxonomy || !trustTaxonomyPath || !trustTaxonomy)) {
+    throw new Error("KFD metadata package does not expose the KFD-2 trust taxonomy schema");
+  }
+  return {
+    key: standard.key || key,
+    id: standard.id || standard.label || key,
+    label: standard.label || standard.id || key,
+    title: standard.title || "",
+    status: standard.status || "",
+    revision: standard.revision || 0,
+    package: {
+      name: packageJson.name,
+      version: packageJson.version,
+      repository: packageJson.repository?.url || "",
+    },
+    schemaIds,
+    schemaPaths,
+    hasTrustTaxonomySchema: Boolean(schemaIds.trustTaxonomy && trustTaxonomyPath && trustTaxonomy),
+    trustTaxonomy,
+    concepts: { ...(standard.concepts || {}) },
+    metadataSchema: standards.metadataSchema || {},
+    source: standards.source || {},
+  };
+}
+
 function normalizeHash(value, label, { required = false } = {}) {
   const text = optionalString(value).replace(/^sha256:/, "").trim();
   if (!text && !required) {
@@ -391,6 +443,7 @@ function normalizeStringObjectArray(value, label) {
         throw new Error(`${label}[${index}] must be a string or object`);
       }
       return {
+        ...entry,
         id: optionalString(entry.id || entry.name || entry.surface || entry.path || entry.kind || `entry-${index}`),
         kind: optionalString(entry.kind || entry.type),
         reason: optionalString(entry.reason || entry.rationale || entry.note || entry.description),
@@ -400,6 +453,110 @@ function normalizeStringObjectArray(value, label) {
     .filter((entry) => entry.id || entry.reason);
 }
 
+const KFD2_TAXONOMY_FIELDS = ["riskType", "trustImpact", "machineProvability", "agentAction"];
+
+function kfdExtensionGuidance({ taxonomy = undefined, extensionRequests = [] } = {}) {
+  const requestPath = taxonomy?.["x-kfd"]?.extensionPolicy?.requestPath || {};
+  const kfd3Request = Array.isArray(extensionRequests)
+    ? extensionRequests.find((entry) => entry?.requestPath?.kind === "github-issue")
+    : undefined;
+  return {
+    action: taxonomy?.["x-kfd"]?.extensionPolicy?.standardAction || "open-kfd-extension-issue",
+    repository: requestPath.repository || kfd3Request?.requestPath?.target || "https://github.com/kungfu-systems/kfd",
+    issueUrl: requestPath.issueUrl || kfd3Request?.requestPath?.template || "https://github.com/kungfu-systems/kfd/issues/new?title=KFD-2%20trust%20taxonomy%20extension%20request",
+    appliesTo: requestPath.appliesTo || KFD2_TAXONOMY_FIELDS,
+  };
+}
+
+function taxonomyAllowedValues(taxonomy = {}) {
+  const xKfd = taxonomy?.["x-kfd"]?.allowedValues || {};
+  const defs = taxonomy?.$defs || {};
+  return {
+    riskType: new Set(xKfd.riskType || defs.riskType?.enum || []),
+    trustImpact: new Set(xKfd.trustImpact || defs.trustImpact?.enum || []),
+    machineProvability: new Set(xKfd.machineProvability || defs.machineProvability?.enum || []),
+    agentAction: new Set(xKfd.agentAction || defs.agentAction?.enum || []),
+  };
+}
+
+function validateTaxonomyField(entry, field, { allowed, label, guidance }) {
+  const value = optionalString(entry[field]).trim();
+  if (!value) {
+    throw new Error(`${label}.${field} is required by KFD-2 trust taxonomy; do not invent a local private value, ${guidance.action} at ${guidance.issueUrl}`);
+  }
+  if (!allowed[field]?.has(value)) {
+    throw new Error(`${label}.${field}=${value} is not in KFD-2 trust taxonomy; unknown taxonomy values fail validation, ${guidance.action} at ${guidance.issueUrl}`);
+  }
+}
+
+export function validateKfd2TrustTaxonomyEntry(entry, {
+  kind = "residualRisk",
+  label = kind,
+  metadata = resolveKfd2Metadata({ requireTrustTaxonomy: true }),
+  extensionRequests = [],
+} = {}) {
+  const taxonomy = metadata.trustTaxonomy;
+  const taxonomyContract = taxonomy?.contract || taxonomy?.["x-kfd"]?.contract;
+  if (!taxonomy || taxonomyContract !== "kfd-2-trust-taxonomy") {
+    const guidance = kfdExtensionGuidance({ taxonomy, extensionRequests });
+    throw new Error(`${label} requires KFD-2 trust taxonomy from @kungfu-tech/kfd standards.json; ${guidance.action} at ${guidance.issueUrl}`);
+  }
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+    throw new Error(`${label} must be an object validated by KFD-2 trust taxonomy`);
+  }
+  const guidance = kfdExtensionGuidance({ taxonomy, extensionRequests });
+  const defs = taxonomy.$defs || {};
+  const required = defs[kind]?.required || (kind === "residualRisk"
+    ? ["id", "definedBy", "riskType", "trustImpact", "machineProvability", "agentAction", "reason", "owner"]
+    : ["id", "riskType", "trustImpact", "reason"]);
+  for (const field of required) {
+    if (!optionalString(entry[field]).trim()) {
+      throw new Error(`${label}.${field} is required by KFD-2 trust taxonomy; do not add a private local taxonomy value, ${guidance.action} at ${guidance.issueUrl}`);
+    }
+  }
+  const allowed = taxonomyAllowedValues(taxonomy);
+  for (const field of KFD2_TAXONOMY_FIELDS) {
+    if (field in entry || required.includes(field)) {
+      validateTaxonomyField(entry, field, { allowed, label, guidance });
+    }
+  }
+  if (kind === "residualRisk") {
+    const expectedDefinedBy = `${metadata.schemaIds.trustTaxonomy}#/$defs/residualRisk`;
+    if (entry.definedBy !== expectedDefinedBy) {
+      throw new Error(`${label}.definedBy must be ${expectedDefinedBy}; ${guidance.action} at ${guidance.issueUrl}`);
+    }
+  }
+  return {
+    ...entry,
+    taxonomy: {
+      standard: metadata.key,
+      schemaId: metadata.schemaIds.trustTaxonomy,
+      schemaPath: metadata.schemaPaths.trustTaxonomy,
+      contract: taxonomyContract,
+      package: metadata.package,
+    },
+    extensionRequest: entry.extensionRequest || kfdExtensionGuidance({ taxonomy, extensionRequests }),
+  };
+}
+
+function normalizeKfd2TaxonomyEntries(value, {
+  kind = "residualRisk",
+  label = kind,
+  extensionRequests = [],
+} = {}) {
+  const entries = normalizeStringObjectArray(value, label);
+  if (entries.length === 0) {
+    return [];
+  }
+  const metadata = resolveKfd2Metadata({ requireTrustTaxonomy: true });
+  return entries.map((entry, index) => validateKfd2TrustTaxonomyEntry(entry, {
+    kind,
+    label: `${label}[${index}]`,
+    metadata,
+    extensionRequests,
+  }));
+}
+
 function normalizeKfd3AuditBoundary(value = {}, { closure = {}, label = "auditBoundary" } = {}) {
   const boundary = value && typeof value === "object" && !Array.isArray(value) ? value : {};
   const sourceClosure = closure && typeof closure === "object" && !Array.isArray(closure) ? closure : {};
@@ -444,9 +601,10 @@ function normalizeKfd3AuditBoundary(value = {}, { closure = {}, label = "auditBo
   };
 }
 
-function normalizeKfd3ResidualRisk(value = [], { auditBoundary = {} } = {}) {
+function normalizeKfd3ResidualRisk(value = [], { auditBoundary = {}, extensionRequests = [] } = {}) {
   const explicitRisks = normalizeStringObjectArray(value, "residualRisk");
   const boundaryRisks = (auditBoundary.nonExhaustivelyEnumerableSurfaces || []).map((entry) => ({
+    ...entry,
     id: entry.id,
     kind: entry.kind || "non-exhaustive-surface",
     reason: entry.reason || "Surface cannot be exhaustively enumerated by the release passport.",
@@ -456,7 +614,11 @@ function normalizeKfd3ResidualRisk(value = [], { auditBoundary = {} } = {}) {
   for (const entry of [...explicitRisks, ...boundaryRisks]) {
     byId.set(entry.id || entry.reason, entry);
   }
-  return [...byId.values()];
+  return normalizeKfd2TaxonomyEntries([...byId.values()], {
+    kind: "residualRisk",
+    label: "residualRisk",
+    extensionRequests,
+  });
 }
 
 function normalizeKfd3Responsibility(value = {}, { registry = {}, artifactVerifyCommand = "" } = {}) {
@@ -502,6 +664,14 @@ export function normalizeKfd3CollaborationInterfacePrebuildWitness(witness, { me
   }
   const registry = normalizeRegistry(witness.registry || witness.sourceRegistry || witness.source_registry || witness.collaborationInterface?.sourceRegistry || witness.collaboration_interface?.sourceRegistry);
   const closure = witness.collaborationInterface?.closure || witness.collaboration_interface?.closure || {};
+  const extensionRequests = normalizeStringObjectArray(
+    witness.extensionRequests ||
+      witness.extension_requests ||
+      witness.collaborationInterface?.extensionRequests ||
+      witness.collaboration_interface?.extensionRequests ||
+      [],
+    "extensionRequests",
+  );
   const auditBoundary = normalizeKfd3AuditBoundary(witness.auditBoundary || witness.audit_boundary || closure, { closure });
   const expectedArtifactVerification = witness.expectedArtifactVerification && typeof witness.expectedArtifactVerification === "object" && !Array.isArray(witness.expectedArtifactVerification)
     ? { ...witness.expectedArtifactVerification, command: optionalString(witness.expectedArtifactVerification.command) }
@@ -534,8 +704,9 @@ export function normalizeKfd3CollaborationInterfacePrebuildWitness(witness, { me
     auditBoundary,
     residualRisk: normalizeKfd3ResidualRisk(
       witness.residualRisk || witness.residual_risk || witness.auditBoundary?.residualRisk || witness.audit_boundary?.residual_risk || [],
-      { auditBoundary },
+      { auditBoundary, extensionRequests },
     ),
+    extensionRequests,
     responsibility: normalizeKfd3Responsibility(witness.responsibility || witness.owners, {
       registry,
       artifactVerifyCommand: expectedArtifactVerification.command,
@@ -559,6 +730,10 @@ export function normalizeKfd3CollaborationInterfaceArtifactWitness(witness, { me
     throw new Error(`KFD-3 artifact witness standard must match ${metadata.key}`);
   }
   const exposedSurfaces = artifactSurfacesFromWitness(witness).map((surface, index) => normalizeKfd3Surface(surface, index, "exposedSurfaces"));
+  const extensionRequests = normalizeStringObjectArray(
+    witness.extensionRequests || witness.extension_requests || [],
+    "extensionRequests",
+  );
   return {
     schemaVersion: 1,
     contract: KFD3_ARTIFACT_WITNESS_CONTRACT,
@@ -574,6 +749,12 @@ export function normalizeKfd3CollaborationInterfaceArtifactWitness(witness, { me
       witness.collaboration_interface?.digest,
     ),
     exposedSurfaces,
+    residualRisk: normalizeKfd2TaxonomyEntries(witness.residualRisk || witness.residual_risk || [], {
+      kind: "residualRisk",
+      label: "artifactWitness.residualRisk",
+      extensionRequests,
+    }),
+    extensionRequests,
     verifier: witness.verifier && typeof witness.verifier === "object" && !Array.isArray(witness.verifier)
       ? { ...witness.verifier }
       : {},
@@ -1004,7 +1185,11 @@ export function createKfd3CollaborationInterfaceReleaseGateEvidence({
       reasons.push(`support-level-${supportLevel}`);
     }
     const status = reasons.length === 0 ? "passed" : supportLevel === "release" ? "failed" : "downgraded";
-    const residualRisk = prebuildWitness.residualRisk || [];
+    const residualRiskMap = new Map();
+    for (const risk of [...(prebuildWitness.residualRisk || []), ...(artifactWitness?.residualRisk || [])]) {
+      residualRiskMap.set(risk.id || risk.reason, risk);
+    }
+    const residualRisk = [...residualRiskMap.values()];
     const releaseStatus = kfd3ReleaseStatus({ comparisonStatus: status, supportLevel, residualRisk });
     const trustResult = kfd3TrustResult(status);
     const declaredCapabilityVerification = {

package/packages/core/release-passport.js

@@ -10,6 +10,7 @@ import {
   createKfd3CollaborationInterfaceReleaseGateEvidence,
   resolveKfd1Metadata,
   resolveKfd3Metadata,
+  validateKfd2TrustTaxonomyEntry,
   validateKfd1ReleaseGateEvidence,
   validateKfd3CollaborationInterfaceReleaseGateEvidence,
 } from "./kfd-gate.js";
@@ -625,6 +626,13 @@ function arrayOrEmpty(value) {
   return Array.isArray(value) ? value : [];
 }
 
+function arrayOrSingleton(value) {
+  if (Array.isArray(value)) {
+    return value;
+  }
+  return value && typeof value === "object" ? [value] : [];
+}
+
 function normalizeKfd2Claim(raw = {}, index = 0) {
   const claim = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
   const sourceBindings = arrayOrEmpty(claim.sourceBindings || claim.source_bindings || claim.sources || claim.declaredSources);
@@ -638,7 +646,15 @@ function normalizeKfd2Claim(raw = {}, index = 0) {
       ? claim.audit_boundary
       : {};
   const responsibility = claim.responsibility && typeof claim.responsibility === "object" && !Array.isArray(claim.responsibility) ? claim.responsibility : {};
-  const residualRisk = arrayOrEmpty(claim.residualRisk || claim.residual_risk);
+  const residualRisk = arrayOrSingleton(claim.residualRisk || claim.residual_risk).map((entry, riskIndex) => validateKfd2TrustTaxonomyEntry(entry, {
+    kind: "residualRisk",
+    label: `kfd-2.claims[${index}].residualRisk[${riskIndex}]`,
+  }));
+  const downgradeReasons = arrayOrSingleton(claim.downgradeReasons || claim.downgrade_reasons || claim.downgradeReason || claim.downgrade_reason)
+    .map((entry, reasonIndex) => validateKfd2TrustTaxonomyEntry(entry, {
+      kind: "downgradeReason",
+      label: `kfd-2.claims[${index}].downgradeReasons[${reasonIndex}]`,
+    }));
   const trustProof = claim.trustProof && typeof claim.trustProof === "object" && !Array.isArray(claim.trustProof)
     ? claim.trustProof
     : undefined;
@@ -668,6 +684,7 @@ function normalizeKfd2Claim(raw = {}, index = 0) {
     auditBoundary,
     responsibility,
     residualRisk,
+    downgradeReasons,
     ...(trustProof ? { trustProof } : {}),
     proseOnly,
     missingBindings,
@@ -789,6 +806,7 @@ function createKfd2ReleaseTrustPassportAudit({ explicitClaims = [], kfd1Section
   }
   const failed = claims.filter((claim) => claim.public && claim.status === "failed");
   const downgraded = claims.filter((claim) => claim.public && (claim.status === "downgraded" || claim.proseOnly));
+  const downgradeReasons = claims.flatMap((claim) => arrayOrEmpty(claim.downgradeReasons));
   return {
     schemaVersion: 1,
     contract: KFD2_RELEASE_TRUST_PASSPORT_CONTRACT,
@@ -798,6 +816,7 @@ function createKfd2ReleaseTrustPassportAudit({ explicitClaims = [], kfd1Section
       scope: "public release claims visible to humans or agents",
       policy: "public claims must bind declared sources, machine-readable evidence, hashes, artifact coordinates, verification results, audit boundaries, responsibility state, and residual risk",
     },
+    downgradeReasons,
     claims,
     summary: {
       claimCount: claims.length,
@@ -1307,6 +1326,18 @@ function validateKfd2ReleaseTrustPassportAudit(section, issues) {
   if (claims.length === 0) {
     issues.push(issue("error", "kfd-2.claims.empty", "kfd-2 audit must enumerate at least one public release claim"));
   }
+  for (const [reasonIndex, reason] of arrayOrEmpty(section.downgradeReasons).entries()) {
+    try {
+      validateKfd2TrustTaxonomyEntry(reason, {
+        kind: "downgradeReason",
+        label: `kfd-2.downgradeReasons[${reasonIndex}]`,
+      });
+    } catch (error) {
+      issues.push(issue("error", `kfd-2.downgradeReasons[${reasonIndex}]`, error.message, {
+        id: reason?.id || "",
+      }));
+    }
+  }
   for (const [index, claim] of claims.entries()) {
     if (!claim.id || !claim.claim) {
       issues.push(issue("error", `kfd-2.claims[${index}].identity`, "public release claim must include id and statement"));
@@ -1326,6 +1357,30 @@ function validateKfd2ReleaseTrustPassportAudit(section, issues) {
         proseOnly: Boolean(claim.proseOnly),
       }));
     }
+    for (const [riskIndex, risk] of arrayOrSingleton(claim.residualRisk || claim.residual_risk).entries()) {
+      try {
+        validateKfd2TrustTaxonomyEntry(risk, {
+          kind: "residualRisk",
+          label: `kfd-2.claims[${index}].residualRisk[${riskIndex}]`,
+        });
+      } catch (error) {
+        issues.push(issue("error", `kfd-2.claims[${index}].residualRisk[${riskIndex}]`, error.message, {
+          id: risk?.id || claim.id || "",
+        }));
+      }
+    }
+    for (const [reasonIndex, reason] of arrayOrSingleton(claim.downgradeReasons || claim.downgrade_reasons || claim.downgradeReason || claim.downgrade_reason).entries()) {
+      try {
+        validateKfd2TrustTaxonomyEntry(reason, {
+          kind: "downgradeReason",
+          label: `kfd-2.claims[${index}].downgradeReasons[${reasonIndex}]`,
+        });
+      } catch (error) {
+        issues.push(issue("error", `kfd-2.claims[${index}].downgradeReasons[${reasonIndex}]`, error.message, {
+          id: reason?.id || claim.id || "",
+        }));
+      }
+    }
     if (String(claim.id || "").startsWith("kfd-3:")) {
       const trustProof = claim.trustProof && typeof claim.trustProof === "object" && !Array.isArray(claim.trustProof)
         ? claim.trustProof
@@ -1360,6 +1415,19 @@ function validateKfd2ReleaseTrustPassportAudit(section, issues) {
           issues.push(issue("error", `kfd-2.claims[${index}].trustProof.residualRisk`, "KFD-2 trust proof must preserve residual risk as an array", {
             id: claim.id || "",
           }));
+        } else {
+          for (const [riskIndex, risk] of trustProof.residualRisk.entries()) {
+            try {
+              validateKfd2TrustTaxonomyEntry(risk, {
+                kind: "residualRisk",
+                label: `kfd-2.claims[${index}].trustProof.residualRisk[${riskIndex}]`,
+              });
+            } catch (error) {
+              issues.push(issue("error", `kfd-2.claims[${index}].trustProof.residualRisk[${riskIndex}]`, error.message, {
+                id: risk?.id || claim.id || "",
+              }));
+            }
+          }
         }
         if (!trustProof.responsibility?.registryFactsOwner || !trustProof.responsibility?.artifactVerificationOwner || !trustProof.responsibility?.releasePassportProofOwner) {
           issues.push(issue("error", `kfd-2.claims[${index}].trustProof.responsibility`, "KFD-2 trust proof must preserve KFD-3 responsibility state", {