@kungfu-tech/buildchain 2.12.9-alpha.1 → 2.13.0-alpha.1

package/packages/core/index.js

@@ -138,19 +138,25 @@ export {
   PUBLICATION_AUTHORITY_CLASSES,
   PUBLICATION_AUTHORITY_REGISTRY_CONTRACT,
   PUBLICATION_CAPABILITY_CONTRACT,
+  CONSUMER_PUBLICATION_DECISION_CONTRACT,
   PUBLICATION_CONTROL_PLANE_AUDIT_CONTRACT,
   PUBLICATION_GATE_DECISION_CONTRACT,
+  PUBLICATION_QUALIFICATION_RECEIPT_CONTRACT,
   RUNNER_PROVENANCE_CLASSES,
   RUNNER_PROVENANCE_CONTRACT,
   createPublicationAuthorityRegistry,
   createPublicationAdmission,
   createPublicationArtifactManifestSet,
+  createConsumerPublicationDecision,
   createPublicationControlPlaneAudit,
   createPublicationGateDecision,
+  createPublicationQualificationReceipt,
   createRunnerProvenance,
   detectPublicationAuthoritySignals,
   publicationAuthorityDigest,
+  publicationGateAggregateBindings,
   verifyPublicationAdmission,
+  verifyPublicationQualificationReceipt,
 } from "./publication-authority.js";
 
 export {
@@ -179,6 +185,16 @@ export {
   verifyArtifactPassport,
 } from "./artifact-passport.js";
 
+export {
+  ARTIFACT_VERIFICATION_ENVELOPE_CHECK_CONTRACT,
+  ARTIFACT_VERIFICATION_ENVELOPE_CONTRACT,
+  KFX_ADMISSION_INPUTS_CONTRACT,
+  artifactVerificationEnvelopeDigest,
+  projectArtifactVerificationEnvelopeToKfx,
+  sealArtifactVerificationReport,
+  verifyArtifactVerificationEnvelope,
+} from "./artifact-verification-envelope.js";
+
 export {
   BUILDCHAIN_CONTRACT_LOCK,
   BUILDCHAIN_RUNTIME_CONTRACT_WORLD,

package/packages/core/publication-authority.js

@@ -16,6 +16,10 @@ export const PUBLICATION_CONTROL_PLANE_AUDIT_CONTRACT =
   "kungfu-buildchain-publication-control-plane-audit";
 export const PUBLICATION_GATE_DECISION_CONTRACT =
   "kungfu-buildchain-publication-gate-decision";
+export const CONSUMER_PUBLICATION_DECISION_CONTRACT =
+  "kungfu-buildchain-consumer-publication-decision";
+export const PUBLICATION_QUALIFICATION_RECEIPT_CONTRACT =
+  "kungfu-buildchain-publication-qualification-receipt";
 export const PUBLICATION_ARTIFACT_MANIFEST_SET_CONTRACT =
   "kungfu-buildchain-publication-artifact-manifest-set";
 
@@ -225,6 +229,16 @@ export function createPublicationControlPlaneAudit({
 }
 
 export function createPublicationAdmission(input = {}) {
+  const qualificationRequired = input.qualification?.required === true;
+  const qualification = {
+    required: qualificationRequired,
+    predicateId: qualificationRequired
+      ? requiredString(input.qualification?.predicateId, "qualification.predicateId")
+      : "",
+    predicateDigest: qualificationRequired
+      ? normalizeDigest(input.qualification?.predicateDigest, "qualification.predicateDigest")
+      : "",
+  };
   const payload = {
     schemaVersion: 1,
     contract: PUBLICATION_ADMISSION_CONTRACT,
@@ -236,6 +250,10 @@ export function createPublicationAdmission(input = {}) {
     runtimeSha: normalizeGitSha(input.runtimeSha, "runtimeSha"),
     contractDigest: normalizeDigest(input.contractDigest, "contractDigest"),
     policyDigest: normalizeDigest(input.policyDigest, "policyDigest"),
+    gateRegistryDigest: normalizeDigest(
+      input.gateRegistryDigest || input.policyDigest,
+      "gateRegistryDigest",
+    ),
     controllerReceiptDigest: normalizeDigest(input.controllerReceiptDigest, "controllerReceiptDigest"),
     runnerProvenanceDigest: normalizeDigest(input.runnerProvenanceDigest, "runnerProvenanceDigest"),
     controlPlaneAuditDigest: normalizeDigest(input.controlPlaneAuditDigest, "controlPlaneAuditDigest"),
@@ -249,6 +267,7 @@ export function createPublicationAdmission(input = {}) {
     nonce: requiredString(input.nonce, "nonce"),
     issuedAt: new Date(parseTime(input.issuedAt, "issuedAt")).toISOString(),
     expiresAt: new Date(parseTime(input.expiresAt, "expiresAt")).toISOString(),
+    qualification,
   };
   return { ...payload, admissionDigest: publicationAuthorityDigest(payload) };
 }
@@ -381,8 +400,7 @@ export function createPublicationArtifactManifestSet({
   return { ...payload, manifestSetDigest: publicationAuthorityDigest(payload) };
 }
 
-function validateGateAggregate(gateAggregate, { admission, passport }) {
-  const passportSourceSha = passport.source?.headSha || passport.source?.sha;
+export function publicationGateAggregateBindings(gateAggregate) {
   if (gateAggregate?.contract === "buildchain.shifu-gate-aggregate/v1") {
     const { digest, ...payload } = gateAggregate;
     const actualDigest = sha256Json(payload);
@@ -392,12 +410,17 @@ function validateGateAggregate(gateAggregate, { admission, passport }) {
     if (gateAggregate.status !== "pass" || gateAggregate.qualifying !== true) {
       throw new Error("gate aggregate is not qualifying");
     }
-    if (![admission.sourceSha, passportSourceSha].includes(gateAggregate.sourceSha)) {
-      throw new Error("gate aggregate source SHA mismatch");
-    }
-    normalizeDigest(gateAggregate.registry?.digest, "gateAggregate.registry.digest");
+    const registryDigest = normalizeDigest(
+      gateAggregate.registry?.digest,
+      "gateAggregate.registry.digest",
+    );
     const policyDigest = normalizeDigest(gateAggregate.matrixDigest, "gateAggregate.matrixDigest");
-    return { gateAggregateDigest: actualDigest, policyDigest };
+    return {
+      gateAggregateDigest: actualDigest,
+      policyDigest,
+      registryDigest,
+      sourceSha: normalizeGitSha(gateAggregate.sourceSha, "gateAggregate.sourceSha"),
+    };
   }
   if (gateAggregate?.contract !== PUBLICATION_GATE_DECISION_CONTRACT) {
     throw new Error("gate evidence must be a Shifu Gate aggregate or explicit publication Gate decision");
@@ -410,9 +433,6 @@ function validateGateAggregate(gateAggregate, { admission, passport }) {
   if (gateAggregate.required !== false) {
     throw new Error("a required Gate policy must supply a qualifying Shifu Gate aggregate");
   }
-  if (![admission.sourceSha, passportSourceSha].includes(gateAggregate.sourceSha)) {
-    throw new Error("publication Gate decision source SHA mismatch");
-  }
   const normalizedPolicy = {
     profile: requiredString(gateAggregate.profile, "gateDecision.profile"),
     required: false,
@@ -423,7 +443,21 @@ function validateGateAggregate(gateAggregate, { admission, passport }) {
   if (normalizeDigest(gateAggregate.policyDigest, "gateDecision.policyDigest") !== policyDigest) {
     throw new Error("publication Gate policy digest mismatch");
   }
-  return { gateAggregateDigest: actualDigest, policyDigest };
+  return {
+    gateAggregateDigest: actualDigest,
+    policyDigest,
+    registryDigest: policyDigest,
+    sourceSha: normalizeGitSha(gateAggregate.sourceSha, "gateDecision.sourceSha"),
+  };
+}
+
+function validateGateAggregate(gateAggregate, { admission, passport }) {
+  const bindings = publicationGateAggregateBindings(gateAggregate);
+  const passportSourceSha = passport.source?.headSha || passport.source?.sha;
+  if (![admission.sourceSha, passportSourceSha].includes(bindings.sourceSha)) {
+    throw new Error("gate aggregate source SHA mismatch");
+  }
+  return bindings;
 }
 
 function validatePublicationEvidence(publicationEvidence, admission) {
@@ -458,6 +492,7 @@ function validatePublicationEvidence(publicationEvidence, admission) {
       contractDigest,
       gateAggregateDigest: gate.gateAggregateDigest,
       policyDigest: gate.policyDigest,
+      gateRegistryDigest: gate.registryDigest,
       artifactDigest: candidate.candidateDigest,
       evidenceDigest: publicationAuthorityDigest({
         sourceTreeSha: candidate.sourceTreeSha,
@@ -551,6 +586,7 @@ function validatePublicationEvidence(publicationEvidence, admission) {
     contractDigest,
     gateAggregateDigest: gate.gateAggregateDigest,
     policyDigest: gate.policyDigest,
+    gateRegistryDigest: gate.registryDigest,
     artifactDigest: manifestSet.manifestSetDigest,
     evidenceDigest: publicationAuthorityDigest({
       passportCandidateHash: passport.candidateHash,
@@ -712,7 +748,7 @@ export function verifyPublicationAdmission({
   for (const key of ["sourceSha", "runtimeSha"]) {
     normalizeGitSha(admission[key], `admission.${key}`);
   }
-  for (const key of ["contractDigest", "policyDigest", "controllerReceiptDigest", "gateAggregateDigest", "artifactDigest"]) {
+  for (const key of ["contractDigest", "policyDigest", "controllerReceiptDigest", "gateAggregateDigest", "artifactDigest", ...(admission.gateRegistryDigest ? ["gateRegistryDigest"] : [])]) {
     normalizeDigest(admission[key], `admission.${key}`);
   }
 
@@ -726,6 +762,13 @@ export function verifyPublicationAdmission({
     expectedDigest: admission.controlPlaneAuditDigest,
   });
   const evidence = validatePublicationEvidence(publicationEvidence, admission);
+  if (
+    admission.gateRegistryDigest &&
+    normalizeDigest(admission.gateRegistryDigest, "admission.gateRegistryDigest") !==
+      evidence.gateRegistryDigest
+  ) {
+    throw new Error("Gate registry evidence binding mismatch");
+  }
   const { admissionDigest: suppliedAdmissionDigest, producerDecision: _ignored, ...admissionPayload } = admission;
   const actualAdmissionDigest = publicationAuthorityDigest(admissionPayload);
   if (normalizeDigest(suppliedAdmissionDigest, "admission.admissionDigest") !== actualAdmissionDigest) {
@@ -744,6 +787,8 @@ export function verifyPublicationAdmission({
     runtimeSha: normalizeGitSha(admission.runtimeSha, "admission.runtimeSha"),
     contractDigest: normalizeDigest(admission.contractDigest, "admission.contractDigest"),
     policyDigest: normalizeDigest(admission.policyDigest, "admission.policyDigest"),
+    authorityRegistryDigest: actualRegistryDigest,
+    gateRegistryDigest: evidence.gateRegistryDigest,
     controllerReceiptDigest: normalizeDigest(admission.controllerReceiptDigest, "admission.controllerReceiptDigest"),
     product: admission.product,
     target: admission.target,
@@ -758,7 +803,231 @@ export function verifyPublicationAdmission({
     gateAggregateDigest: normalizeDigest(admission.gateAggregateDigest, "admission.gateAggregateDigest"),
     environment,
     nonce,
+    issuedAt: admission.issuedAt,
     expiresAt: admission.expiresAt,
+    qualification: admission.qualification?.required === true
+      ? {
+          required: true,
+          predicateId: requiredString(
+            admission.qualification.predicateId,
+            "admission.qualification.predicateId",
+          ),
+          predicateDigest: normalizeDigest(
+            admission.qualification.predicateDigest,
+            "admission.qualification.predicateDigest",
+          ),
+        }
+      : { required: false, predicateId: "", predicateDigest: "" },
   };
   return { ...capability, capabilityDigest: publicationAuthorityDigest(capability) };
 }
+
+function validatePublicationCapability(capability, now = new Date()) {
+  if (capability?.contract !== PUBLICATION_CAPABILITY_CONTRACT) {
+    throw new Error("publication capability contract mismatch");
+  }
+  const { capabilityDigest: supplied, ...payload } = capability;
+  const actual = publicationAuthorityDigest(payload);
+  if (normalizeDigest(supplied, "capability.capabilityDigest") !== actual) {
+    throw new Error("publication capability digest mismatch");
+  }
+  if (capability.decision !== "allow") {
+    throw new Error("publication capability did not allow provider mutation");
+  }
+  const nowMs = now instanceof Date ? now.getTime() : parseTime(now, "now");
+  if (parseTime(capability.expiresAt, "capability.expiresAt") <= nowMs) {
+    throw new Error("publication capability is stale");
+  }
+  return actual;
+}
+
+function validateCapabilityGateAggregate(capability, gateAggregate) {
+  const gate = publicationGateAggregateBindings(gateAggregate);
+  if (gate.gateAggregateDigest !== normalizeDigest(capability.gateAggregateDigest, "capability.gateAggregateDigest")) {
+    throw new Error("publication qualification Gate aggregate binding mismatch");
+  }
+  if (gate.policyDigest !== normalizeDigest(capability.policyDigest, "capability.policyDigest")) {
+    throw new Error("publication qualification Gate policy binding mismatch");
+  }
+  if (gate.registryDigest !== normalizeDigest(capability.gateRegistryDigest, "capability.gateRegistryDigest")) {
+    throw new Error("publication qualification Gate registry binding mismatch");
+  }
+  if (gate.sourceSha !== normalizeGitSha(capability.sourceSha, "capability.sourceSha")) {
+    throw new Error("publication qualification Gate source binding mismatch");
+  }
+  return gate;
+}
+
+export function createConsumerPublicationDecision({
+  capability,
+  gateAggregate,
+  decision,
+  predicateId,
+  predicateDigest,
+  evidence = {},
+  now = new Date(),
+} = {}) {
+  const capabilityDigest = validatePublicationCapability(capability, now);
+  const gate = validateCapabilityGateAggregate(capability, gateAggregate);
+  if (capability.qualification?.required !== true) {
+    throw new Error("publication capability did not require consumer qualification");
+  }
+  const normalizedPredicateId = requiredString(predicateId, "predicateId");
+  const normalizedPredicateDigest = normalizeDigest(predicateDigest, "predicateDigest");
+  if (normalizedPredicateId !== capability.qualification.predicateId) {
+    throw new Error("consumer publication predicate id mismatch");
+  }
+  if (normalizedPredicateDigest !== capability.qualification.predicateDigest) {
+    throw new Error("consumer publication predicate digest mismatch");
+  }
+  const normalizedDecision = requiredString(decision, "decision");
+  if (!["allow", "deny"].includes(normalizedDecision)) {
+    throw new Error("consumer publication decision must be allow or deny");
+  }
+  const payload = {
+    schemaVersion: 1,
+    contract: CONSUMER_PUBLICATION_DECISION_CONTRACT,
+    decision: normalizedDecision,
+    predicateId: normalizedPredicateId,
+    predicateDigest: normalizedPredicateDigest,
+    capabilityDigest,
+    gateAggregateDigest: gate.gateAggregateDigest,
+    sourceSha: capability.sourceSha,
+    artifactDigest: capability.artifactDigest,
+    version: capability.version,
+    channel: capability.channel,
+    nonce: capability.nonce,
+    evidence,
+  };
+  return { ...payload, decisionDigest: publicationAuthorityDigest(payload) };
+}
+
+export function createPublicationQualificationReceipt({
+  capability,
+  gateAggregate,
+  consumerDecision,
+  now = new Date(),
+} = {}) {
+  const capabilityDigest = validatePublicationCapability(capability, now);
+  const gate = validateCapabilityGateAggregate(capability, gateAggregate);
+  if (capability.qualification?.required !== true) {
+    throw new Error("publication capability did not require consumer qualification");
+  }
+  if (consumerDecision?.contract !== CONSUMER_PUBLICATION_DECISION_CONTRACT) {
+    throw new Error("consumer publication decision contract mismatch");
+  }
+  const { decisionDigest: suppliedDecisionDigest, ...decisionPayload } = consumerDecision;
+  const decisionDigest = publicationAuthorityDigest(decisionPayload);
+  if (normalizeDigest(suppliedDecisionDigest, "consumerDecision.decisionDigest") !== decisionDigest) {
+    throw new Error("consumer publication decision digest mismatch");
+  }
+  if (consumerDecision.decision !== "allow") {
+    throw new Error("consumer publication predicate did not qualify");
+  }
+  const exactBindings = {
+    predicateId: capability.qualification.predicateId,
+    predicateDigest: capability.qualification.predicateDigest,
+    capabilityDigest,
+    gateAggregateDigest: gate.gateAggregateDigest,
+    sourceSha: capability.sourceSha,
+    artifactDigest: capability.artifactDigest,
+    version: capability.version,
+    channel: capability.channel,
+    nonce: capability.nonce,
+  };
+  for (const [key, expected] of Object.entries(exactBindings)) {
+    if (String(consumerDecision[key] || "") !== String(expected)) {
+      throw new Error(`consumer publication decision ${key} binding mismatch`);
+    }
+  }
+  const payload = {
+    schemaVersion: 1,
+    contract: PUBLICATION_QUALIFICATION_RECEIPT_CONTRACT,
+    decision: "allow",
+    ...exactBindings,
+    authorityRegistryDigest: capability.authorityRegistryDigest,
+    gateRegistryDigest: gate.registryDigest,
+    policyDigest: gate.policyDigest,
+    runtimeSha: capability.runtimeSha,
+    contractDigest: capability.contractDigest,
+    controllerReceiptDigest: capability.controllerReceiptDigest,
+    runnerProvenanceDigest: capability.runnerProvenanceDigest,
+    controlPlaneAuditDigest: capability.controlPlaneAuditDigest,
+    publicationEvidenceDigest: capability.publicationEvidenceDigest,
+    product: capability.product,
+    target: capability.target,
+    issuedAt: capability.issuedAt,
+    expiresAt: capability.expiresAt,
+    consumerDecisionDigest: decisionDigest,
+  };
+  return { ...payload, receiptDigest: publicationAuthorityDigest(payload) };
+}
+
+export function verifyPublicationQualificationReceipt({
+  receipt,
+  capability,
+  gateAggregate,
+  expected = {},
+  usedNonces = [],
+  now = new Date(),
+} = {}) {
+  const capabilityDigest = validatePublicationCapability(capability, now);
+  const gate = validateCapabilityGateAggregate(capability, gateAggregate);
+  if (capability.qualification?.required !== true) {
+    throw new Error("publication capability did not require consumer qualification");
+  }
+  if (receipt?.contract !== PUBLICATION_QUALIFICATION_RECEIPT_CONTRACT) {
+    throw new Error("publication qualification receipt contract mismatch");
+  }
+  if (receipt.decision !== "allow") {
+    throw new Error("publication qualification receipt did not allow provider mutation");
+  }
+  const exactBindings = {
+    predicateId: capability.qualification.predicateId,
+    predicateDigest: capability.qualification.predicateDigest,
+    capabilityDigest,
+    gateAggregateDigest: gate.gateAggregateDigest,
+    authorityRegistryDigest: capability.authorityRegistryDigest,
+    gateRegistryDigest: gate.registryDigest,
+    policyDigest: gate.policyDigest,
+    sourceSha: capability.sourceSha,
+    runtimeSha: capability.runtimeSha,
+    contractDigest: capability.contractDigest,
+    controllerReceiptDigest: capability.controllerReceiptDigest,
+    runnerProvenanceDigest: capability.runnerProvenanceDigest,
+    controlPlaneAuditDigest: capability.controlPlaneAuditDigest,
+    publicationEvidenceDigest: capability.publicationEvidenceDigest,
+    artifactDigest: capability.artifactDigest,
+    product: capability.product,
+    target: capability.target,
+    version: capability.version,
+    channel: capability.channel,
+    nonce: capability.nonce,
+    issuedAt: capability.issuedAt,
+    expiresAt: capability.expiresAt,
+  };
+  for (const [key, value] of Object.entries(exactBindings)) {
+    if (String(receipt[key] || "") !== String(value)) {
+      throw new Error(`publication qualification receipt ${key} binding mismatch`);
+    }
+  }
+  normalizeDigest(
+    receipt.consumerDecisionDigest,
+    "receipt.consumerDecisionDigest",
+  );
+  const { receiptDigest: suppliedReceiptDigest, ...receiptPayload } = receipt;
+  const receiptDigest = publicationAuthorityDigest(receiptPayload);
+  if (normalizeDigest(suppliedReceiptDigest, "receipt.receiptDigest") !== receiptDigest) {
+    throw new Error("publication qualification receipt digest mismatch");
+  }
+  const nonce = requiredString(receipt.nonce, "receipt.nonce");
+  if (new Set(usedNonces.map(String)).has(nonce)) {
+    throw new Error("publication qualification receipt nonce was replayed");
+  }
+  for (const [key, value] of Object.entries(expected)) {
+    if (value !== undefined && String(receipt[key] || "") !== String(value)) {
+      throw new Error(`publication qualification receipt ${key} binding mismatch`);
+    }
+  }
+  return { ok: true, receiptDigest, nonce };
+}

package/packages/core/release-line-bootstrap.js

@@ -65,6 +65,29 @@ function writeJson(value) {
   return `${JSON.stringify(value, null, 2)}\n`;
 }
 
+function updateReleaseImpactVersionState(cwd, plan) {
+  const filePath = path.join(cwd, ".buildchain", "release-impact.json");
+  if (!fs.existsSync(filePath)) {
+    return;
+  }
+  const current = readJsonIfExists(filePath);
+  if (!current || typeof current !== "object" || Array.isArray(current)) {
+    throw new Error(".buildchain/release-impact.json must be a JSON object");
+  }
+  const next = {
+    ...current,
+    release: {
+      ...(current.release && typeof current.release === "object" ? current.release : {}),
+      version: plan.initialVersion,
+      line: plan.line,
+    },
+  };
+  const content = writeJson(next);
+  if (content !== writeJson(current)) {
+    fs.writeFileSync(filePath, content);
+  }
+}
+
 function discoverVersionStateFiles(cwd, loadedConfig) {
   if (loadedConfig?.config?.version?.files?.length) {
     return discoverConfiguredVersionStateFiles(cwd, loadedConfig);
@@ -212,6 +235,7 @@ export function writeReleaseLineBootstrapVersionState({
   for (const file of changed) {
     fs.writeFileSync(path.join(cwd, file.path), file.content);
   }
+  updateReleaseImpactVersionState(cwd, plan);
   const lifecycleVersionState =
     getLifecycleStage(loadedConfig, "version-state") ||
     getLifecycleStage(loadedConfig, "version_state");

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

@@ -8,6 +8,7 @@ import {
   createPublicationAdmission,
   createPublicationGateDecision,
   createRunnerProvenance,
+  publicationGateAggregateBindings,
 } from "../packages/core/publication-authority.js";
 import { buildPublicationArtifactCandidate } from "./publication-artifact-candidate.mjs";
 
@@ -126,6 +127,8 @@ async function main() {
     isolation: "github-hosted-single-job",
   });
   const issuedAt = new Date();
+  const gateBindings = publicationGateAggregateBindings(gateAggregate);
+  const qualificationRequired = process.env.BUILDCHAIN_CONSUMER_QUALIFICATION_REQUIRED === "true";
   const admission = createPublicationAdmission({
     registryDigest: registry.registryDigest,
     workflowPath:
@@ -137,6 +140,7 @@ async function main() {
     runtimeSha,
     contractDigest: controllerReceipt.runtime?.contractDigest,
     policyDigest: gateAggregate.policyDigest,
+    gateRegistryDigest: gateBindings.registryDigest,
     controllerReceiptDigest: controllerReceipt.digest,
     runnerProvenanceDigest: runnerProvenance.receiptDigest,
     controlPlaneAuditDigest: controlPlaneAudit.receiptDigest,
@@ -150,6 +154,11 @@ async function main() {
     nonce: `${required("GITHUB_RUN_ID")}:${required("GITHUB_RUN_ATTEMPT")}:${sourceSha}:paper`,
     issuedAt: issuedAt.toISOString(),
     expiresAt: new Date(issuedAt.getTime() + 10 * 60 * 1000).toISOString(),
+    qualification: {
+      required: qualificationRequired,
+      predicateId: process.env.BUILDCHAIN_CONSUMER_PREDICATE_ID || "",
+      predicateDigest: process.env.BUILDCHAIN_CONSUMER_PREDICATE_DIGEST || "",
+    },
   });
   const bindingNames = [
     "repository",
@@ -158,6 +167,7 @@ async function main() {
     "runtimeSha",
     "contractDigest",
     "policyDigest",
+    "gateRegistryDigest",
     "controllerReceiptDigest",
     "gateAggregateDigest",
     "environment",

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

@@ -9,6 +9,7 @@ import {
   createPublicationArtifactManifestSet,
   createPublicationGateDecision,
   createRunnerProvenance,
+  publicationGateAggregateBindings,
 } from "../packages/core/publication-authority.js";
 
 function required(name) {
@@ -148,6 +149,8 @@ async function main() {
   const packageJson = JSON.parse(fs.readFileSync(path.join(runtimeRoot, "package.json"), "utf8"));
   const publicationVersion = required("BUILDCHAIN_PUBLICATION_VERSION");
   const issuedAt = new Date();
+  const gateBindings = publicationGateAggregateBindings(gateAggregate);
+  const qualificationRequired = process.env.BUILDCHAIN_CONSUMER_QUALIFICATION_REQUIRED === "true";
   const admission = createPublicationAdmission({
     registryDigest: registry.registryDigest,
     workflowPath: required("BUILDCHAIN_AUTHORITY_WORKFLOW_PATH"),
@@ -157,6 +160,7 @@ async function main() {
     runtimeSha,
     contractDigest: controllerReceipt.runtime?.contractDigest,
     policyDigest: gateAggregate.policyDigest,
+    gateRegistryDigest: gateBindings.registryDigest,
     controllerReceiptDigest: controllerReceipt.digest,
     runnerProvenanceDigest: runnerProvenance.receiptDigest,
     controlPlaneAuditDigest: controlPlaneAudit.receiptDigest,
@@ -170,9 +174,14 @@ async function main() {
     nonce: `${required("GITHUB_RUN_ID")}:${required("GITHUB_RUN_ATTEMPT")}:${sourceSha}`,
     issuedAt: issuedAt.toISOString(),
     expiresAt: new Date(issuedAt.getTime() + 10 * 60 * 1000).toISOString(),
+    qualification: {
+      required: qualificationRequired,
+      predicateId: process.env.BUILDCHAIN_CONSUMER_PREDICATE_ID || "",
+      predicateDigest: process.env.BUILDCHAIN_CONSUMER_PREDICATE_DIGEST || "",
+    },
   });
   const bindingNames = [
-    "repository", "publisherWorkflowPath", "sourceSha", "runtimeSha", "contractDigest", "policyDigest",
+    "repository", "publisherWorkflowPath", "sourceSha", "runtimeSha", "contractDigest", "policyDigest", "gateRegistryDigest",
     "controllerReceiptDigest", "gateAggregateDigest", "environment", "product", "target", "version", "channel",
     "artifactDigest",
   ];

package/scripts/check-inventory.mjs

@@ -21,6 +21,7 @@ const requiredPaths = [
   ".github/pull_request_template.md",
   "bin/buildchain.mjs",
   "packages/core/homebrew.js",
+  "packages/core/artifact-verification-envelope.js",
   "packages/core/build-facts.js",
   "packages/core/publication-package.js",
   "packages/core/release-line-bootstrap.js",
@@ -239,6 +240,9 @@ if (rootPackage.exports?.["./buildchain-contract"] !== "./packages/core/buildcha
 if (rootPackage.exports?.["./controller-evidence"] !== "./packages/core/controller-evidence.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/controller-evidence");
 }
+if (rootPackage.exports?.["./artifact-verification-envelope"] !== "./packages/core/artifact-verification-envelope.js") {
+  throw new Error("root package must export @kungfu-tech/buildchain/artifact-verification-envelope");
+}
 if (rootPackage.exports?.["./issue-reporting"] !== "./packages/core/issue-reporting.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/issue-reporting");
 }
@@ -843,6 +847,7 @@ for (const requiredSnippet of [
   "expected-publication-version: ${{ needs.publication-plan.outputs.version }}",
   "publication-version: ${{ needs.publication-plan.outputs.version }}",
   "name: Plan exact publication version",
+  "name: Install exact publication planning dependencies",
   "DRY_RUN: ${{ inputs.dry-run }}",
   "if (dryRun) {",
   "Enforce Buildchain stable release canary gate",

package/scripts/generate-site-bundle.mjs

@@ -444,6 +444,8 @@ function cliCommandMeta(id) {
     "publication-artifact": { group: "reusable-build", purpose: "Generate publication artifact manifests, passports, and source bundles for paper/report repositories." },
     "publication-artifact-manifest": { group: "reusable-build", purpose: "Write a site-consumable publication artifact manifest, publication passport, and source bundle." },
     "publication-artifact-npm-package": { group: "reusable-build", purpose: "Synthesize the declared npm paper package from a publication artifact manifest, passport, registry, source bundle, and primary artifact." },
+    project: { group: "release-passport-trust", purpose: "Inspect read-only consumer projection command families." },
+    "project-kfx-admission": { group: "release-passport-trust", purpose: "Project one verified sealed envelope into direct KFX admission inputs without reconstructing evidence." },
     "release-dry-run": { group: "governance-versioning", purpose: "Explain what a channel merge would publish before the PR is merged." },
     "release-line-open": { group: "governance-versioning", purpose: "Plan or write the initial version-state commit for a new minor release line." },
     "release-propagation": { group: "site-and-propagation", purpose: "Plan channel-preserving downstream release PRs and write exact upstream release locks." },
@@ -455,6 +457,7 @@ function cliCommandMeta(id) {
     validate: { group: "getting-started", purpose: "Validate .buildchain/buildchain.toml and declared lifecycle surfaces." },
     verify: { group: "release-passport-trust", purpose: "Inspect release and artifact verification command families." },
     "verify-artifact": { group: "release-passport-trust", purpose: "Verify artifact subjects against release passport evidence." },
+    "verify-artifact-envelope": { group: "release-passport-trust", purpose: "Verify exact roots, identity, lifecycle, revocation, and an existing KFD assessment in a sealed artifact envelope." },
     "verify-infra-contract-evidence-bundle": { group: "governance-versioning", purpose: "Fail closed unless an infra-contract lifecycle evidence bundle is complete, hash-bound, and validation-consistent." },
     "verify-observability-log": { group: "observability-diagnostics", purpose: "Verify Buildchain observability log events." },
     "verify-publication-admission": { group: "release-passport-trust", purpose: "Independently verify sealed publication admission, runner provenance, control-plane audit, nonce freshness, and exact artifact bindings." },
@@ -485,6 +488,7 @@ function nodeApiMeta(exportName) {
     "./publication-control-plane-audit": { group: "release-passport-trust", summary: "Read-only publication control-plane snapshot evaluation APIs." },
     "./buildchain-publication-authority": { group: "release-passport-trust", summary: "Buildchain-owned closed-world publication authority descriptor registry." },
     "./artifact-passport": { group: "release-passport-trust", summary: "Artifact passport digest and evidence helper APIs." },
+    "./artifact-verification-envelope": { group: "release-passport-trust", summary: "Sealed exact-root, lifecycle, identity, and existing KFD assessment inputs for KFX admission." },
     "./release-passport": { group: "release-passport-trust", summary: "Release passport collection, verification, explanation, and evidence APIs." },
     "./release-candidate": { group: "reusable-build", summary: "PR-stage release-candidate artifact, passport, and promote-only resolver APIs." },
     "./stable-candidate-ledger": { group: "governance-versioning", summary: "Immutable alpha candidate ledger, qualification, revocation, selection, and exact stable source-lock APIs." },