@kungfu-tech/buildchain 3.0.7-alpha.0 → 3.0.7

package/packages/core/engineering-housekeeper.js

@@ -0,0 +1,259 @@
+import crypto from "node:crypto";
+
+export const ENGINEERING_HOUSEKEEPER_CONTRACT =
+  "kungfu-buildchain-engineering-housekeeper/v1";
+export const ENGINEERING_HOUSEKEEPER_SCHEMA_VERSION = 1;
+
+export const HOUSEKEEPER_REASON_CODES = Object.freeze({
+  ELIGIBLE_MERGED_BRANCH: "eligible.merged-branch",
+  PROTECTED_BRANCH: "branch.protected",
+  RETAINED_BRANCH: "branch.retained",
+  DEFAULT_BRANCH: "branch.default",
+  TARGET_BRANCH: "branch.target",
+  OPEN_PR_HEAD: "branch.open-pr-head",
+  CROSS_REPOSITORY: "branch.cross-repository",
+  NOT_MERGED: "branch.not-merged",
+  HEAD_ADVANCED: "branch.head-advanced",
+  RENAMED: "branch.renamed",
+  TARGET_ADVANCED: "branch.target-advanced",
+  PERMISSION_DENIED: "branch.permission-denied",
+  PR_ACTIVE: "pull-request.active",
+  PR_STALE_REPORT: "pull-request.stale-report",
+  PR_LABEL_ELIGIBLE: "pull-request.label-eligible",
+  PR_AUTO_CLOSE_DISABLED: "pull-request.auto-close-disabled",
+  PR_FORKED: "pull-request.forked",
+  REPEATED_NO_OP: "replay.already-applied",
+});
+
+export const DEFAULT_HOUSEKEEPER_POLICY = Object.freeze({
+  protectedPatterns: ["dev/**", "alpha/**", "release/**", "publish-gate/**"],
+  retainedPatterns: ["train/**", "authority/**"],
+  pullRequests: Object.freeze({
+    reportStale: true,
+    label: "",
+    autoClose: false,
+  }),
+});
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export function engineeringHousekeeperRoot(value) {
+  return `sha256:${crypto.createHash("sha256").update(stableJson(value)).digest("hex")}`;
+}
+
+function globMatches(pattern, value) {
+  const expression = String(pattern)
+    .split("**")
+    .map((chunk) =>
+      chunk
+        .split("*")
+        .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+        .join("[^/]*"),
+    )
+    .join(".*");
+  return new RegExp(`^${expression}$`).test(value);
+}
+
+function matchesAny(patterns, value) {
+  return [...(patterns || [])].some((pattern) => globMatches(pattern, value));
+}
+
+function normalizePolicy(policy = {}) {
+  return {
+    protectedPatterns: [
+      ...(policy.protectedPatterns ||
+        DEFAULT_HOUSEKEEPER_POLICY.protectedPatterns),
+    ].sort(),
+    retainedPatterns: [
+      ...(policy.retainedPatterns ||
+        DEFAULT_HOUSEKEEPER_POLICY.retainedPatterns),
+    ].sort(),
+    pullRequests: {
+      reportStale: policy.pullRequests?.reportStale !== false,
+      label: String(policy.pullRequests?.label || ""),
+      autoClose: false,
+    },
+  };
+}
+
+function sortedUnique(values) {
+  return [...new Set(values)].sort();
+}
+
+export function classifyHousekeeperBranch(branch, policyInput = {}) {
+  const policy = normalizePolicy(policyInput);
+  const reasons = [];
+  if (branch.isDefault) reasons.push(HOUSEKEEPER_REASON_CODES.DEFAULT_BRANCH);
+  if (branch.name === branch.target?.name)
+    reasons.push(HOUSEKEEPER_REASON_CODES.TARGET_BRANCH);
+  if (
+    branch.isProtected === true ||
+    matchesAny(policy.protectedPatterns, branch.name)
+  )
+    reasons.push(HOUSEKEEPER_REASON_CODES.PROTECTED_BRANCH);
+  if (matchesAny(policy.retainedPatterns, branch.name))
+    reasons.push(HOUSEKEEPER_REASON_CODES.RETAINED_BRANCH);
+  if (branch.sourceRepository && branch.sourceRepository !== branch.repository)
+    reasons.push(HOUSEKEEPER_REASON_CODES.CROSS_REPOSITORY);
+  if ((branch.openPullRequestNumbers || []).length > 0)
+    reasons.push(HOUSEKEEPER_REASON_CODES.OPEN_PR_HEAD);
+  if (branch.ancestry !== "ancestor")
+    reasons.push(HOUSEKEEPER_REASON_CODES.NOT_MERGED);
+  const eligible =
+    reasons.length === 0 &&
+    Boolean(branch.headOid) &&
+    Boolean(branch.target?.headOid);
+  return {
+    kind: "branch",
+    repository: branch.repository,
+    name: branch.name,
+    headOid: branch.headOid,
+    target: { name: branch.target?.name, headOid: branch.target?.headOid },
+    eligible,
+    decision: eligible ? "delete" : "retain",
+    reasonCodes: eligible
+      ? [HOUSEKEEPER_REASON_CODES.ELIGIBLE_MERGED_BRANCH]
+      : sortedUnique(reasons),
+  };
+}
+
+export function classifyHousekeeperPullRequest(pullRequest, policyInput = {}) {
+  const policy = normalizePolicy(policyInput);
+  const active = ["open", "draft"].includes(pullRequest.state);
+  const forked = pullRequest.headRepository !== pullRequest.repository;
+  const stale = active && pullRequest.stale === true;
+  const actions = stale && policy.pullRequests.reportStale ? ["report"] : [];
+  if (stale && policy.pullRequests.label) actions.push("label");
+  const reasons = [HOUSEKEEPER_REASON_CODES.PR_AUTO_CLOSE_DISABLED];
+  if (active) reasons.push(HOUSEKEEPER_REASON_CODES.PR_ACTIVE);
+  if (stale) reasons.push(HOUSEKEEPER_REASON_CODES.PR_STALE_REPORT);
+  if (stale && policy.pullRequests.label)
+    reasons.push(HOUSEKEEPER_REASON_CODES.PR_LABEL_ELIGIBLE);
+  if (forked) reasons.push(HOUSEKEEPER_REASON_CODES.PR_FORKED);
+  return {
+    kind: "pull-request",
+    repository: pullRequest.repository,
+    number: pullRequest.number,
+    headRepository: pullRequest.headRepository,
+    headRef: pullRequest.headRef,
+    headOid: pullRequest.headOid,
+    state: pullRequest.state,
+    actions: actions.sort(),
+    reasonCodes: sortedUnique(reasons),
+  };
+}
+
+export function createEngineeringHousekeeperPlan({
+  repository,
+  target,
+  branches = [],
+  pullRequests = [],
+  policy = {},
+  observedAt,
+}) {
+  const normalizedPolicy = normalizePolicy(policy);
+  const inventory = [
+    ...branches.map((branch) =>
+      classifyHousekeeperBranch(branch, normalizedPolicy),
+    ),
+    ...pullRequests.map((pullRequest) =>
+      classifyHousekeeperPullRequest(pullRequest, normalizedPolicy),
+    ),
+  ].sort((left, right) =>
+    `${left.kind}:${left.name || String(left.number).padStart(12, "0")}`.localeCompare(
+      `${right.kind}:${right.name || String(right.number).padStart(12, "0")}`,
+    ),
+  );
+  const body = {
+    contract: ENGINEERING_HOUSEKEEPER_CONTRACT,
+    schemaVersion: ENGINEERING_HOUSEKEEPER_SCHEMA_VERSION,
+    mode: "plan",
+    repository,
+    target,
+    observedAt,
+    policy: normalizedPolicy,
+    inventory,
+    actions: inventory.flatMap((entry) =>
+      entry.kind === "branch" && entry.eligible
+        ? [
+            {
+              kind: "delete-branch",
+              name: entry.name,
+              expectedHeadOid: entry.headOid,
+              targetName: entry.target.name,
+              expectedTargetHeadOid: entry.target.headOid,
+            },
+          ]
+        : entry.kind === "pull-request"
+          ? entry.actions.map((action) => ({
+              kind: `${action}-pull-request`,
+              number: entry.number,
+              expectedHeadOid: entry.headOid,
+            }))
+          : [],
+    ),
+  };
+  return { ...body, planRoot: engineeringHousekeeperRoot(body) };
+}
+
+export function revalidateHousekeeperBranchAction(
+  action,
+  current,
+  policy = {},
+) {
+  const reasons = [];
+  if (current.name !== action.name)
+    reasons.push(HOUSEKEEPER_REASON_CODES.RENAMED);
+  if (current.headOid !== action.expectedHeadOid)
+    reasons.push(HOUSEKEEPER_REASON_CODES.HEAD_ADVANCED);
+  if (current.target?.headOid !== action.expectedTargetHeadOid)
+    reasons.push(HOUSEKEEPER_REASON_CODES.TARGET_ADVANCED);
+  const classification = classifyHousekeeperBranch(current, policy);
+  if (!classification.eligible) reasons.push(...classification.reasonCodes);
+  return {
+    ok: reasons.length === 0,
+    action,
+    currentHeadOid: current.headOid,
+    currentTargetHeadOid: current.target?.headOid,
+    reasonCodes: sortedUnique(reasons),
+  };
+}
+
+export function createEngineeringHousekeeperReceipt({
+  plan,
+  outcomes,
+  appliedAt,
+}) {
+  const orderedOutcomes = [...outcomes].sort((a, b) =>
+    stableJson(a).localeCompare(stableJson(b)),
+  );
+  const body = {
+    contract: ENGINEERING_HOUSEKEEPER_CONTRACT,
+    schemaVersion: ENGINEERING_HOUSEKEEPER_SCHEMA_VERSION,
+    mode: "receipt",
+    planRoot: plan.planRoot,
+    appliedAt,
+    outcomes: orderedOutcomes,
+  };
+  return { ...body, receiptRoot: engineeringHousekeeperRoot(body) };
+}
+
+export function classifyHousekeeperReplay(plan, priorReceipt) {
+  const alreadyApplied = priorReceipt?.planRoot === plan.planRoot;
+  return {
+    alreadyApplied,
+    action: alreadyApplied ? "no-op" : "apply",
+    reasonCodes: alreadyApplied
+      ? [HOUSEKEEPER_REASON_CODES.REPEATED_NO_OP]
+      : [],
+  };
+}

package/packages/core/index.js

@@ -287,6 +287,9 @@ export {
   verifyGithubGovernanceReceipt,
 } from "./github-governance-authority.js";
 
+export * from "./engineering-housekeeper.js";
+export * from "./engineering-housekeeper-github.js";
+
 export {
   ARTIFACT_PASSPORT_LOCATOR_CONTRACT,
   ARTIFACT_PASSPORT_POINTER_CONTRACT,

package/packages/core/kfd-gate.js

@@ -944,26 +944,49 @@ export function normalizeKfd1ContractWorldWitness(witness, { metadata = resolveK
   };
 }
 
-function resolveArtifactFile({ cwd, artifactRoot, artifacts = [], artifactPath }) {
-  const candidates = [
-    path.resolve(cwd, artifactPath),
-    artifactRoot ? path.resolve(artifactRoot, artifactPath) : "",
-  ].filter(Boolean);
+function indexArtifactSearchRoots({ roots = [], artifactPaths = [] } = {}) {
+  const wanted = [...new Set(artifactPaths.filter(Boolean))];
+  const indexed = new Map();
+  const stack = roots.filter((root) => root && fs.existsSync(root) && fs.statSync(root).isDirectory());
+  while (stack.length > 0) {
+    const current = stack.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const candidate = path.join(current, entry.name);
+      if (entry.isDirectory()) { stack.push(candidate); continue; }
+      if (!entry.isFile()) continue;
+      const normalized = candidate.replace(/\\/g, "/");
+      for (const artifactPath of wanted) {
+        if (normalized === artifactPath || normalized.endsWith(`/${artifactPath}`)) {
+          const candidates = indexed.get(artifactPath) || [];
+          candidates.push(candidate);
+          indexed.set(artifactPath, candidates);
+        }
+      }
+    }
+  }
+  return indexed;
+}
+
+function resolveArtifactFile({ cwd, artifactRoot, artifactIndex = new Map(), artifacts = [], artifactPath, expectedSha256 = "" }) {
+  const candidates = artifactIndex.size > 0
+    ? [...(artifactIndex.get(artifactPath) || []), artifactRoot ? path.resolve(artifactRoot, artifactPath) : "", path.resolve(cwd, artifactPath)]
+    : [path.resolve(cwd, artifactPath), artifactRoot ? path.resolve(artifactRoot, artifactPath) : ""];
   for (const artifact of artifacts) {
     const sourcePath = artifact.sourcePath || artifact.path || "";
-    if (!sourcePath) {
-      continue;
-    }
+    if (!sourcePath) continue;
     const normalizedSource = sourcePath.replace(/\\/g, "/");
-    if (normalizedSource === artifactPath || normalizedSource.endsWith(`/${artifactPath}`)) {
-      candidates.push(path.resolve(sourcePath));
-    }
+    if (normalizedSource === artifactPath || normalizedSource.endsWith(`/${artifactPath}`)) candidates.push(path.resolve(sourcePath));
     const name = artifact.name || artifact.filename || "";
-    if (name && name === artifactPath) {
-      candidates.push(path.resolve(sourcePath));
-    }
+    if (name && name === artifactPath) candidates.push(path.resolve(sourcePath));
   }
-  return candidates.find((candidate) => candidate && fs.existsSync(candidate) && fs.statSync(candidate).isFile()) || "";
+  const existing = [...new Set(candidates)].filter(
+    (candidate) => candidate && fs.existsSync(candidate) && fs.statSync(candidate).isFile(),
+  );
+  if (expectedSha256) {
+    const exact = existing.find((candidate) => sha256File(candidate) === expectedSha256);
+    if (exact) return exact;
+  }
+  return existing[0] || "";
 }
 
 function resolveSourceFile({ cwd, sourcePath }) {
@@ -977,6 +1000,7 @@ function resolveSourceFile({ cwd, sourcePath }) {
 export function createKfd1ReleaseGateEvidence({
   cwd = process.cwd(),
   artifactRoot = "",
+  artifactSearchRoots = [],
   artifacts = [],
   witnesses = [],
   verifiedAt = new Date().toISOString(),
@@ -986,6 +1010,10 @@ export function createKfd1ReleaseGateEvidence({
   if (normalizedWitnesses.length === 0) {
     return undefined;
   }
+  const artifactIndex = indexArtifactSearchRoots({
+    roots: artifactSearchRoots,
+    artifactPaths: normalizedWitnesses.flatMap((witness) => witness.surfaces.map((surface) => surface.artifactPath)),
+  });
   const worlds = normalizedWitnesses.map((witness) => {
     const preBuildWitnessSha256 = sha256Json(witness);
     const sourceResults = witness.surfaces.map((surface) => {
@@ -1025,8 +1053,10 @@ export function createKfd1ReleaseGateEvidence({
       const filePath = resolveArtifactFile({
         cwd,
         artifactRoot,
+        artifactIndex,
         artifacts,
         artifactPath: surface.artifactPath,
+        expectedSha256: surface.expectedSha256,
       });
       if (!filePath) {
         return {

package/packages/core/publication-rehearsal-runtime.js

@@ -102,7 +102,19 @@ function safeRelativePath(value, label) {
 }
 
 function fileDigest(filePath) {
-  return `sha256:${crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex")}`;
+  const hash = crypto.createHash("sha256");
+  const descriptor = fs.openSync(filePath, "r");
+  const buffer = Buffer.allocUnsafe(8 * 1024 * 1024);
+  try {
+    for (;;) {
+      const count = fs.readSync(descriptor, buffer, 0, buffer.length, null);
+      if (count === 0) break;
+      hash.update(buffer.subarray(0, count));
+    }
+  } finally {
+    fs.closeSync(descriptor);
+  }
+  return `sha256:${hash.digest("hex")}`;
 }
 
 function rootedPayload(value) {

package/packages/core/release-passport.js

@@ -146,6 +146,15 @@ function invariantSemanticPreimage(passport) {
   return value;
 }
 
+function hasCompleteInvariantCoverage(value) {
+  const coverage = value?.coverage;
+  return Number.isInteger(coverage?.required)
+    && coverage.required > 0
+    && coverage.verified === coverage.required
+    && [coverage.missing, coverage.falsified, coverage.unqualified]
+      .every((items) => Array.isArray(items) && items.length === 0);
+}
+
 function normalizeInvariantPassport(meta, index = 0) {
   const value = meta?.value;
   const label = `invariantPassportJsons[${index}]`;
@@ -165,11 +174,18 @@ function normalizeInvariantPassport(meta, index = 0) {
   if (value.passportRoot !== expectedRoot) {
     throw new Error(`${label}.passportRoot mismatch: expected ${expectedRoot}, got ${value.passportRoot}`);
   }
-  if (value.verdict !== "verified") {
-    throw new Error(`${label}.verdict must be verified, got ${value.verdict}`);
-  }
-  if (value.coverage?.complete !== true) {
-    throw new Error(`${label}.coverage.complete must be true`);
+  const verifiedPassport = value.verdict === "verified" && value.coverage?.complete === true;
+  const scopedUnqualifiedClaim = value.verdict === "unqualified"
+    && value.coverage?.complete === false
+    && hasCompleteInvariantCoverage(value)
+    && value.releaseClaims?.verdict === "unqualified"
+    && /^sha256:[0-9a-f]{64}$/.test(optionalString(value.releaseClaims?.claimRoot))
+    && Array.isArray(value.releaseClaims?.diagnostics)
+    && value.releaseClaims.diagnostics.length > 0
+    && Array.isArray(value.diagnostics)
+    && value.diagnostics.length === 0;
+  if (!verifiedPassport && !scopedUnqualifiedClaim) {
+    throw new Error(`${label}.verdict must be verified, or unqualified only for complete invariant coverage with one explicit unqualified releaseClaims section`);
   }
   if (value.source?.dirty !== false) {
     throw new Error(`${label}.source.dirty must be false`);
@@ -182,6 +198,9 @@ function normalizeInvariantPassport(meta, index = 0) {
     : [];
   if (platforms.length === 0) throw new Error(`${label}.coverage.platforms must be non-empty`);
   if (!Array.isArray(value.residualRisk)) throw new Error(`${label}.residualRisk must be an array`);
+  const releaseClaimRisks = scopedUnqualifiedClaim
+    ? value.releaseClaims.diagnostics.map((entry) => `Exit/provider claim ${optionalString(entry?.code) || "unqualified"}: ${optionalString(entry?.message) || "consumer claim remains unqualified"}`)
+    : [];
   return {
     path: optionalString(meta.path),
     sha256: optionalString(meta.sha256),
@@ -194,7 +213,15 @@ function normalizeInvariantPassport(meta, index = 0) {
     source: structuredClone(value.source),
     coverage: structuredClone(value.coverage),
     platforms,
-    residualRisk: structuredClone(value.residualRisk),
+    admission: {
+      scope: "consumer-invariant-coverage",
+      result: "passed",
+      consumerVerdict: value.verdict,
+      releaseClaimsVerdict: optionalString(value.releaseClaims?.verdict),
+    },
+    releaseClaims: value.releaseClaims ? structuredClone(value.releaseClaims) : undefined,
+    diagnostics: Array.isArray(value.diagnostics) ? structuredClone(value.diagnostics) : [],
+    residualRisk: [...new Set([...value.residualRisk, ...releaseClaimRisks])].sort(),
   };
 }
 
@@ -533,7 +560,12 @@ function mergeAuthoritativeImpactBase(impact, basePassport = undefined) {
   return merged;
 }
 
-function parseJsonCommandOutput({ command = "", cwd = process.cwd(), label = "command" } = {}) {
+function parseJsonCommandOutput({
+  command = "",
+  cwd = process.cwd(),
+  label = "command",
+  acceptNonzeroJson = undefined,
+} = {}) {
   const normalized = String(command || "").trim();
   if (!normalized) {
     return { value: undefined, path: "", sha256: "" };
@@ -547,7 +579,7 @@ function parseJsonCommandOutput({ command = "", cwd = process.cwd(), label = "co
   if (result.error) {
     throw new Error(`${label} failed to start: ${result.error.message}`);
   }
-  if (result.status !== 0) {
+  if (result.status !== 0 && typeof acceptNonzeroJson !== "function") {
     const stderr = String(result.stderr || "").trim();
     throw new Error(`${label} exited with ${result.status}${stderr ? `: ${stderr.slice(-1000)}` : ""}`);
   }
@@ -561,10 +593,15 @@ function parseJsonCommandOutput({ command = "", cwd = process.cwd(), label = "co
   } catch (error) {
     throw new Error(`${label} output must be valid JSON: ${error.message}`, { cause: error });
   }
+  if (result.status !== 0 && !acceptNonzeroJson({ status: result.status, value: parsed })) {
+    const stderr = String(result.stderr || "").trim();
+    throw new Error(`${label} exited with ${result.status}${stderr ? `: ${stderr.slice(-1000)}` : ""}`);
+  }
   return {
     value: parsed,
     path: "",
     sha256: sha256Text(stableJson(parsed)),
+    status: result.status,
   };
 }
 
@@ -879,6 +916,41 @@ function arrayOrSingleton(value) {
   return value && typeof value === "object" ? [value] : [];
 }
 
+const KFD2_RESIDUAL_RISK_SCHEMA = "https://kfd.libkungfu.dev/schemas/kfd-2/trust-taxonomy.schema.json#/$defs/residualRisk";
+
+function normalizeKfd2ResidualRisk(entry, { claim = {}, claimIndex = 0, riskIndex = 0 } = {}) {
+  if (entry && typeof entry === "object" && !Array.isArray(entry)) {
+    return entry;
+  }
+  const reason = optionalString(entry).trim();
+  if (!reason) {
+    return entry;
+  }
+  const claimId = optionalString(claim.id || `claim-${claimIndex + 1}`)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "") || `claim-${claimIndex + 1}`;
+  const responsibility = claim.responsibility && typeof claim.responsibility === "object" && !Array.isArray(claim.responsibility)
+    ? claim.responsibility
+    : {};
+  return {
+    id: `${claimId}-residual-risk-${riskIndex + 1}`,
+    definedBy: KFD2_RESIDUAL_RISK_SCHEMA,
+    riskType: "manual-review-risk",
+    trustImpact: "downgrade-warning",
+    machineProvability: "not-machine-verifiable",
+    agentAction: "request-maintainer-review",
+    reason,
+    owner: optionalString(
+      responsibility.releaseDecisionOwner
+      || responsibility.owner
+      || responsibility.sourceOwner
+      || responsibility.sourceContractOwner
+      || "release maintainer",
+    ),
+  };
+}
+
 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);
@@ -892,10 +964,13 @@ function normalizeKfd2Claim(raw = {}, index = 0) {
       ? claim.audit_boundary
       : {};
   const responsibility = claim.responsibility && typeof claim.responsibility === "object" && !Array.isArray(claim.responsibility) ? claim.responsibility : {};
-  const residualRisk = arrayOrSingleton(claim.residualRisk || claim.residual_risk).map((entry, riskIndex) => validateKfd2TrustTaxonomyEntry(entry, {
-    kind: "residualRisk",
-    label: `kfd-2.claims[${index}].residualRisk[${riskIndex}]`,
-  }));
+  const residualRisk = arrayOrSingleton(claim.residualRisk || claim.residual_risk).map((entry, riskIndex) => validateKfd2TrustTaxonomyEntry(
+    normalizeKfd2ResidualRisk(entry, { claim, claimIndex: index, riskIndex }),
+    {
+      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",
@@ -1494,6 +1569,7 @@ export function collectGitHubReleasePassport({
   outputDir = ".buildchain/release-passport",
   assetsJson = "",
   assetsDir = "",
+  kfdArtifactSearchRoots = [],
   releaseJson = "",
   productName = "Buildchain",
   packageName = "@kungfu-tech/buildchain",
@@ -1568,6 +1644,11 @@ export function collectGitHubReleasePassport({
     .filter(Boolean)
     .map((witnessJson) => parseJsonInputWithMeta(witnessJson, undefined, { cwd, label: "kfd3ArtifactWitnessJsons entry" }))
     .filter((meta) => meta.value);
+  const kfd3ArtifactCommandMeta = parseJsonCommandOutput({
+    command: kfd3ArtifactVerifyCommand,
+    cwd,
+    label: "KFD-3 artifact verify command",
+  });
   const kfdSupportMatrixMeta = parseJsonInputWithMeta(
     kfdSupportMatrixJson,
     undefined,
@@ -1578,11 +1659,6 @@ export function collectGitHubReleasePassport({
     .map((gateJson) => parseJsonInputWithMeta(gateJson, undefined, { cwd, label: "kfdProductGateJsons entry" }))
     .filter((meta) => meta.value);
   const basePassportMeta = parseJsonInputWithMeta(basePassportJson, undefined, { cwd, label: "basePassportJson" });
-  const kfd3ArtifactCommandMeta = parseJsonCommandOutput({
-    command: kfd3ArtifactVerifyCommand,
-    cwd,
-    label: "KFD-3 artifact verify command",
-  });
   const invariantPassportMetas = (invariantPassportJsons || [])
     .filter(Boolean)
     .map((passportJson) => parseJsonInputWithMeta(passportJson, undefined, { cwd, label: "invariantPassportJsons entry" }))
@@ -1591,6 +1667,22 @@ export function collectGitHubReleasePassport({
     command: invariantPassportCommand,
     cwd,
     label: "invariant passport command",
+    acceptNonzeroJson: ({ status, value }) => {
+      if (status !== 2) return false;
+      try {
+        const normalized = normalizeInvariantPassport(
+          { value, path: "", sha256: sha256Text(stableJson(value)) },
+          invariantPassportMetas.length,
+        );
+        return normalized.verdict === "unqualified"
+          && normalized.coverage?.complete === false
+          && normalized.releaseClaims?.verdict === "unqualified"
+          && normalized.admission?.scope === "consumer-invariant-coverage"
+          && normalized.admission?.result === "passed";
+      } catch {
+        return false;
+      }
+    },
   });
   if (invariantPassportCommandMeta.value) invariantPassportMetas.push(invariantPassportCommandMeta);
   const invariantPassports = createInvariantPassportGate(invariantPassportMetas);
@@ -1664,6 +1756,7 @@ export function collectGitHubReleasePassport({
   const kfd1 = createKfd1ReleaseGateEvidence({
     cwd,
     artifactRoot: assetsDir ? path.resolve(cwd, assetsDir) : "",
+    artifactSearchRoots: kfdArtifactSearchRoots.map((root) => path.resolve(cwd, root)),
     artifacts: assets,
     witnesses: kfd1WitnessMetas.map((meta) => meta.value),
   });
@@ -2092,7 +2185,17 @@ function validateReleaseEvidenceContracts({
   for (const [index, value] of (passport?.githubArtifactAttestations || []).entries()) {
     try {
       const policy = normalizeGitHubArtifactAttestationPolicy(value);
-      if (policy.caller.sourceSha !== String(passport?.release?.sourceSha || "").toLowerCase()) {
+      const release = passport?.release || {};
+      const acceptedSourceShas = new Set([String(release.sourceSha || "").toLowerCase()]);
+      if (
+        release.treeEquivalent === true
+        && release.builtSourceTreeSha
+        && release.builtSourceTreeSha === release.promotionChannelTreeSha
+        && release.builtSourceSha
+      ) {
+        acceptedSourceShas.add(String(release.builtSourceSha).toLowerCase());
+      }
+      if (!acceptedSourceShas.has(policy.caller.sourceSha)) {
         issues.push(issue(
           "error",
           `githubArtifactAttestations[${index}].caller.sourceSha`,
@@ -2490,8 +2593,15 @@ function validatePassportTrustSections({ passport, issues }) {
   ].filter(Boolean));
   for (const [index, entry] of (section.passports || []).entries()) {
     const prefix = `invariantPassports.passports[${index}]`;
-    if (entry.verdict !== "verified") issues.push(issue("error", `${prefix}.verdict`, `${prefix}.verdict must be verified`));
-    if (entry.coverage?.complete !== true) issues.push(issue("error", `${prefix}.coverage`, `${prefix}.coverage.complete must be true`));
+    if (entry.admission?.scope !== "consumer-invariant-coverage" || entry.admission?.result !== "passed") {
+      issues.push(issue("error", `${prefix}.admission`, `${prefix}.admission must record passed consumer invariant coverage`));
+    }
+    if (entry.verdict !== "verified" && !(entry.verdict === "unqualified" && entry.releaseClaims?.verdict === "unqualified")) {
+      issues.push(issue("error", `${prefix}.verdict`, `${prefix}.verdict must be verified or preserve one explicit unqualified releaseClaims verdict`));
+    }
+    if (entry.coverage?.complete !== true && !hasCompleteInvariantCoverage(entry)) {
+      issues.push(issue("error", `${prefix}.coverage`, `${prefix}.coverage must be complete or prove every required invariant coordinate verified`));
+    }
     if (entry.source?.dirty !== false) issues.push(issue("error", `${prefix}.source.dirty`, `${prefix}.source.dirty must be false`));
     if (acceptedSourceShas.size > 0 && !acceptedSourceShas.has(entry.source?.revision)) {
       issues.push(issue("error", `${prefix}.source.revision`, `${prefix}.source.revision must match a release source identity`));

package/scripts/assemble-self-publication-admission.mjs

@@ -173,7 +173,7 @@ async function main() {
     artifactDigest: artifactSet.manifestSetDigest,
     nonce: `${required("GITHUB_RUN_ID")}:${required("GITHUB_RUN_ATTEMPT")}:${sourceSha}`,
     issuedAt: issuedAt.toISOString(),
-    expiresAt: new Date(issuedAt.getTime() + 10 * 60 * 1000).toISOString(),
+    expiresAt: new Date(issuedAt.getTime() + 15 * 60 * 1000).toISOString(),
     qualification: {
       required: qualificationRequired,
       predicateId: process.env.BUILDCHAIN_CONSUMER_PREDICATE_ID || "",

package/scripts/audit-publication-control-plane.mjs

@@ -453,7 +453,7 @@ function main() {
   const reviewRules = (environmentState.protection_rules || []).filter((rule) => rule.type === "required_reviewers");
   const runsOn = (block.match(/^\s{4}runs-on:\s*([^\n#]+)/m)?.[1] || "").trim().replace(/["']/g, "");
   const observedAt = new Date();
-  const expiresAt = new Date(observedAt.getTime() + 10 * 60 * 1000);
+  const expiresAt = new Date(observedAt.getTime() + 15 * 60 * 1000);
   const receipt = evaluatePublicationControlPlaneSnapshot({
     repository,
     workflowPath,