@kungfu-tech/buildchain 2.7.1-alpha.0 → 2.8.0-alpha.0

package/actions/promote-buildchain-ref/README.md

@@ -209,6 +209,11 @@ After a publish transaction reaches `complete`, the action generates the unified
 persists those files under `release-passport/` in the durable release-state ref.
 Set `release-passport-product-name` to record the consumer product name, for
 example `Libnode`, instead of the default `Buildchain`.
+Set `release-passport-kfd-1-witness-jsons` to newline-separated KFD-1
+contract-world witness JSON paths when released artifacts must prove
+byte-for-byte KFD contract surfaces. Buildchain imports the KFD metadata from
+`@kungfu-tech/kfd`, freezes the witness, verifies artifact bytes, and writes the
+result under the KFD-provided `kfd-1` passport section.
 When present, the passport includes the aggregate build summary, platform
 artifact manifests, npm publish evidence, dist-tag promotion evidence, the
 release-state ref, trusted publishing metadata, and the Buildchain transaction

package/bin/buildchain.mjs

@@ -76,6 +76,7 @@ function usage() {
                                     [--build-summary-json <json-or-path>]
                                     [--platform-manifest-json <json-or-path>]...
                                     [--dist-tag-evidence-json <json-or-path>]
+                                    [--kfd-1-witness-json <json-or-path>]...
                                     [--release-extra-json <json-or-path>]
                                     [--publish-json <json-or-path>] [--output-dir <dir>] [--json]
   buildchain verify release-passport <file-or-url> [--json]
@@ -734,6 +735,7 @@ async function main(argv = process.argv.slice(2)) {
       buildSummaryJson: readFlag(collectArgs, "build-summary-json", ""),
       platformManifestJsons: readRepeatedFlag(collectArgs, "platform-manifest-json"),
       distTagEvidenceJson: readFlag(collectArgs, "dist-tag-evidence-json", ""),
+      kfd1WitnessJsons: readRepeatedFlag(collectArgs, "kfd-1-witness-json"),
       releaseJsonExtra: readFlag(collectArgs, "release-extra-json", ""),
       publishJson: readFlag(collectArgs, "publish-json", ""),
       workflow,

package/dist/site/release-provenance.json

@@ -14,6 +14,7 @@
       "./diagnostics": "./packages/core/diagnostics.js",
       "./issue-reporting": "./packages/core/issue-reporting.js",
       "./logging": "./packages/core/logging.js",
+      "./kfd-gate": "./packages/core/kfd-gate.js",
       "./release-candidate": "./packages/core/release-candidate.js",
       "./release-passport": "./packages/core/release-passport.js",
       "./release-propagation": "./packages/core/release-propagation.js",

package/docs/MAP.md

@@ -33,6 +33,7 @@ running artifact), *use* (consume / extend) - and a **status**:
 | How do I declare version files and custom lifecycle commands? | [`lifecycle-protocol.md`](lifecycle-protocol.md) | use | stable |
 | How does publish evidence, recovery, and finalization work? | [`publish-transaction.md`](publish-transaction.md) | verify | stable |
 | How do I publish or verify release passport artifacts? | [`release-passport.md`](release-passport.md) | use | stable |
+| How do I gate release artifacts with KFD-1 contract-world witnesses? | [`release-passport.md`](release-passport.md#kfd-1-contract-world-release-gate) | verify/use | stable |
 | How do I propagate finalized upstream releases to downstream package/site PRs? | [`release-propagation.md`](release-propagation.md) | use | preview |
 | How do I prove a PR-stage reusable build is the artifact source promoted later? | [`release-candidate.md`](release-candidate.md) + [`reusable-build-surface.md`](reusable-build-surface.md) | verify | stable |
 | Why are binary release assets archived by platform, and where is the single bundle? | [`binary-distribution.md`](binary-distribution.md) | verify | stable |
@@ -90,6 +91,8 @@ running artifact), *use* (consume / extend) - and a **status**:
   [`cli.md`](cli.md) and [`publish-transaction.md`](publish-transaction.md).
 - **release chains / upstream package as source of truth / site synchronization** ->
   [`release-propagation.md`](release-propagation.md).
+- **KFD-1 contract worlds / byte-for-byte release gates** ->
+  [`release-passport.md`](release-passport.md#kfd-1-contract-world-release-gate).
 - **GitHub Release passport / binary assets / artifact evidence / agent release checks** ->
   [`release-passport.md`](release-passport.md),
   [`binary-distribution.md`](binary-distribution.md), and [`cli.md`](cli.md).

package/docs/cli.md

@@ -260,6 +260,7 @@ buildchain collect github-release \
   --platform-manifest-json .buildchain/artifacts/darwin-arm64/manifest.json \
   --platform-manifest-json .buildchain/artifacts/win32-x64/manifest.json \
   --dist-tag-evidence-json .buildchain/release-evidence/v2.3.2/dist-tag-evidence.json \
+  --kfd-1-witness-json .buildchain/kfd-1/contract-world.witness.json \
   --release-extra-json '{"channel":"release","targetRef":"release/v2/v2.3"}' \
   --output-dir .buildchain/release-passport
 ```
@@ -276,6 +277,15 @@ platform packages with version, dist-tag, and digest evidence. Verification
 fails closed if supplied sections are internally incomplete or point to
 artifacts without matching evidence.
 
+`--kfd-1-witness-json` attaches a KFD-1 contract-world release gate. The witness
+is structured JSON: consumers declare the contract world, canonical JSON policy,
+artifact paths, and expected SHA-256 digests. Buildchain imports KFD-owned
+metadata from `@kungfu-tech/kfd`, freezes the witness before build publication,
+then verifies the resulting artifact bytes itself and writes the evidence under
+the KFD-provided top-level key currently named `kfd-1`. Consumers should not
+duplicate this by running repository-specific scripts or invoking the Kungfu
+SDK from their release workflow.
+
 `--impact-json` supplies the surface-aware impact ledger. Production release
 passports (`release/*`) and major publish-gate passports require
 `surfaceImpacts[]`; alpha, local, and legacy passport contexts keep it

package/docs/release-passport.md

@@ -97,6 +97,7 @@ buildchain collect github-release \
   --platform-manifest-json .buildchain/artifacts/darwin-arm64/manifest.json \
   --platform-manifest-json .buildchain/artifacts/win32-x64/manifest.json \
   --dist-tag-evidence-json .buildchain/release-evidence/v2.2.0/dist-tag-evidence.json \
+  --kfd-1-witness-json .buildchain/kfd-1/contract-world.witness.json \
   --output-dir .buildchain/release-passport
 ```
 
@@ -106,6 +107,55 @@ dist-tag, registry, role, platform, and digest, so agents do not need to stitch
 npm facts back together from the lower-level evidence files.
 `buildSummary`, `platformArtifactManifests`, and `distTagPromotion` preserve the
 build and npm dist-tag evidence chain in the same passport.
+
+### KFD-1 contract-world release gate
+
+Buildchain can gate release artifacts with KFD-1 contract-world witnesses. This
+is a structured evidence protocol, not a request for consumers to shell out to
+the Kungfu SDK. The authority chain is:
+
+1. KFD owns the standard metadata and schema ids in `@kungfu-tech/kfd`.
+2. Buildchain imports that metadata, owns the JSON formatting policy, freezes
+   the pre-build witness, and independently verifies post-build artifact bytes.
+3. Consumers only pass declarative witness JSON plus the artifact payloads their
+   build already produced.
+
+The witness JSON names the contract world, the canonical serialization policy,
+and the release surfaces that must be byte-for-byte verified:
+
+```json
+{
+  "id": "kungfu-config",
+  "standard": "kfd-1",
+  "source": "kfd",
+  "contractWorld": {
+    "id": "kungfu-config",
+    "kind": "schema",
+    "name": "Kungfu config schema"
+  },
+  "canonicalPolicy": {
+    "format": "json",
+    "encoding": "utf-8",
+    "indent": 2,
+    "trailingNewline": true
+  },
+  "surfaces": [
+    {
+      "id": "kungfu-config-schema",
+      "artifactPath": "Contents/Resources/core/config.schema.json",
+      "expectedSha256": "..."
+    }
+  ]
+}
+```
+
+`collect github-release` writes the result under the KFD-provided top-level key
+currently named `kfd-1`. Each contract world records the frozen witness digest,
+the KFD package version, KFD schema ids, the Buildchain formatting policy, and
+the actual artifact digest observed after the build. Verification fails closed
+when the witness is missing required facts, an artifact cannot be found, or a
+post-build digest does not match the frozen witness.
+
 `impact.json` can be supplied with `--impact-json`. Production release
 passports (`release/*`) and major publish-gate passports require
 `surfaceImpacts[]`; alpha, local, and legacy passport contexts keep the field

package/docs/versioning.md

@@ -61,6 +61,7 @@ repository changes are patch".
 
 | Date | Action | Line | Faces | Class | Rationale | PR |
 | --- | --- | --- | --- | --- | --- | --- |
+| 2026-07-06 | open-minor | `v2.8` | kfd-1-contract-world-release-gate, required-check-protection | additive | KFD-1 contract-world release gates add a public witness API, Buildchain-owned passport evidence, and fail-closed byte verification, while protected channel required checks are repaired to bind GitHub Actions check runs instead of legacy commit status contexts. | |
 | 2026-07-04 | open-minor | `v2.5` | scheduled-integration-governance | additive | Scheduled integration governance adds scheduled feature-branch discovery, conflict-free integration, reporting, and agent-visible governance automation for dev-line maintenance. | |
 | 2026-07-03 | open-minor | `v2.4` | infra-contract-lifecycle | additive | Infra contract lifecycle adds the provider-neutral `infra-contract` CLI command family, project type, adapter capability contract, lifecycle evidence bundle, propagation evidence, CI evidence mode, and consumer-facing contract artifacts. | |
 | 2026-07-02 | open-minor | `v2.3` | web-surface-host-mapping | additive | Web surface host mapping adds first-class multi-host surface bindings, reusable workflow URL outputs, per-surface deployment overrides, and an agent-readable fixture contract. | |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.7.1-alpha.0",
+  "version": "2.8.0-alpha.0",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -17,6 +17,7 @@
     "./diagnostics": "./packages/core/diagnostics.js",
     "./issue-reporting": "./packages/core/issue-reporting.js",
     "./logging": "./packages/core/logging.js",
+    "./kfd-gate": "./packages/core/kfd-gate.js",
     "./release-candidate": "./packages/core/release-candidate.js",
     "./release-passport": "./packages/core/release-passport.js",
     "./release-propagation": "./packages/core/release-propagation.js",
@@ -91,6 +92,7 @@
     "vitest": "^4.1.9"
   },
   "dependencies": {
+    "@kungfu-tech/kfd": "1.0.0-alpha.2",
     "smol-toml": "1.7.0"
   }
 }

package/packages/core/index.js

@@ -104,6 +104,17 @@ export {
   verifyArtifactPassport,
 } from "./artifact-passport.js";
 
+export {
+  BUILDCHAIN_JSON_FORMATTING_POLICY,
+  KFD1_RELEASE_GATE_CONTRACT,
+  KFD1_WITNESS_SET_CONTRACT,
+  createKfd1ReleaseGateEvidence,
+  normalizeKfd1ContractWorldWitness,
+  resolveKfd1Metadata,
+  sha256Json as sha256KfdJson,
+  validateKfd1ReleaseGateEvidence,
+} from "./kfd-gate.js";
+
 export {
   AGENT_INDEX_CONTRACT,
   ARTIFACT_EVIDENCE_CONTRACT,

package/packages/core/kfd-gate.js

@@ -0,0 +1,413 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+
+export const KFD1_RELEASE_GATE_CONTRACT = "kungfu-buildchain-kfd-1-release-gate";
+export const KFD1_WITNESS_SET_CONTRACT = "kungfu-buildchain-kfd-1-witness-set";
+export const BUILDCHAIN_JSON_FORMATTING_POLICY = Object.freeze({
+  name: "buildchain-release-evidence-json-v1",
+  indentation: 2,
+  trailingNewline: true,
+  canonicalDigest: "stable-json-sha256-v1",
+});
+
+function optionalString(value) {
+  return value === undefined || value === null ? "" : String(value);
+}
+
+function nonEmptyString(value, label) {
+  const normalized = optionalString(value).trim();
+  if (!normalized) {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+  return normalized;
+}
+
+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);
+}
+
+function sha256Bytes(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+export function sha256Json(value) {
+  return sha256Bytes(stableJson(value));
+}
+
+export function sha256File(filePath) {
+  return crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+}
+
+function readJsonPackageExport(exportPath) {
+  return JSON.parse(fs.readFileSync(require.resolve(exportPath), "utf8"));
+}
+
+function loadKfdPackageMetadata() {
+  const packageJson = readJsonPackageExport("@kungfu-tech/kfd/package.json");
+  const standards = readJsonPackageExport("@kungfu-tech/kfd/standards.json");
+  return { packageJson, standards };
+}
+
+export function resolveKfd1Metadata() {
+  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-1") &&
+      value?.schemaIds?.contractWorld &&
+      value?.schemaIds?.witness &&
+      value?.schemaPaths?.contractWorld &&
+      value?.schemaPaths?.witness
+    );
+  });
+  if (!entry) {
+    throw new Error("KFD metadata package does not expose the KFD-1 contract-world witness standard");
+  }
+  const [key, standard] = entry;
+  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: { ...standard.schemaIds },
+    schemaPaths: { ...standard.schemaPaths },
+    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) {
+    return "";
+  }
+  if (!/^[0-9a-f]{64}$/i.test(text)) {
+    throw new Error(`${label} must be a sha256 hex digest`);
+  }
+  return text.toLowerCase();
+}
+
+function normalizePath(value, label) {
+  const text = nonEmptyString(value, label).replace(/\\/g, "/");
+  if (path.isAbsolute(text)) {
+    throw new Error(`${label} must be repository-relative`);
+  }
+  if (text.split("/").some((part) => part === "..")) {
+    throw new Error(`${label} must not contain ..`);
+  }
+  return text;
+}
+
+function normalizeEvidenceFile(value, label) {
+  if (!value) {
+    return undefined;
+  }
+  if (typeof value === "string") {
+    return { path: normalizePath(value, `${label}.path`) };
+  }
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return {
+    ...value,
+    path: value.path ? normalizePath(value.path, `${label}.path`) : "",
+    sha256: value.sha256 ? normalizeHash(value.sha256, `${label}.sha256`) : "",
+  };
+}
+
+function normalizeSurface(surface, index) {
+  if (!surface || typeof surface !== "object" || Array.isArray(surface)) {
+    throw new Error(`surfaces[${index}] must be an object`);
+  }
+  const artifactPath = normalizePath(surface.artifactPath || surface.artifact_path, `surfaces[${index}].artifactPath`);
+  return {
+    name: nonEmptyString(surface.name || surface.id, `surfaces[${index}].name`),
+    sourcePath: surface.sourcePath || surface.source_path
+      ? normalizePath(surface.sourcePath || surface.source_path, `surfaces[${index}].sourcePath`)
+      : "",
+    sourceSha256: normalizeHash(surface.sourceSha256 || surface.source_sha256, `surfaces[${index}].sourceSha256`),
+    artifactPath,
+    expectedSha256: normalizeHash(surface.expectedSha256 || surface.expected_sha256, `surfaces[${index}].expectedSha256`, { required: true }),
+    byteForByte: surface.byteForByte === undefined && surface.byte_for_byte === undefined
+      ? true
+      : Boolean(surface.byteForByte ?? surface.byte_for_byte),
+  };
+}
+
+export function normalizeKfd1ContractWorldWitness(witness, { metadata = resolveKfd1Metadata() } = {}) {
+  if (!witness || typeof witness !== "object" || Array.isArray(witness)) {
+    throw new Error("KFD-1 witness must be a JSON object");
+  }
+  const surfaces = Array.isArray(witness.surfaces)
+    ? witness.surfaces.map((surface, index) => normalizeSurface(surface, index))
+    : [];
+  if (surfaces.length === 0) {
+    throw new Error("KFD-1 witness surfaces[] must include at least one artifact surface");
+  }
+  const standard = optionalString(witness.standard || metadata.key);
+  if (standard && standard !== metadata.key && standard !== metadata.id && standard !== metadata.label) {
+    throw new Error(`KFD-1 witness standard must match ${metadata.key}`);
+  }
+  return {
+    schemaVersion: 1,
+    contract: KFD1_WITNESS_SET_CONTRACT,
+    id: nonEmptyString(witness.id, "KFD-1 witness id"),
+    standard: metadata.key,
+    standardLabel: metadata.label,
+    source: witness.source && typeof witness.source === "object" && !Array.isArray(witness.source)
+      ? { ...witness.source }
+      : {},
+    contractWorld: witness.contractWorld && typeof witness.contractWorld === "object" && !Array.isArray(witness.contractWorld)
+      ? {
+          ...witness.contractWorld,
+          schemaId: witness.contractWorld.schemaId || metadata.schemaIds.contractWorld,
+          digest: optionalString(witness.contractWorld.digest || witness.contractWorld.sha256),
+        }
+      : {
+          schemaId: metadata.schemaIds.contractWorld,
+          digest: "",
+        },
+    canonicalPolicy: normalizeEvidenceFile(witness.canonicalPolicy || witness.canonical_policy, "canonicalPolicy"),
+    registry: normalizeEvidenceFile(witness.registry, "registry"),
+    surfaces,
+    metadata: {
+      kfdPackage: metadata.package,
+      schemaIds: metadata.schemaIds,
+      schemaPaths: metadata.schemaPaths,
+    },
+  };
+}
+
+function resolveArtifactFile({ cwd, artifactRoot, artifacts = [], artifactPath }) {
+  const candidates = [
+    path.resolve(cwd, artifactPath),
+    artifactRoot ? path.resolve(artifactRoot, artifactPath) : "",
+  ].filter(Boolean);
+  for (const artifact of artifacts) {
+    const sourcePath = artifact.sourcePath || artifact.path || "";
+    if (!sourcePath) {
+      continue;
+    }
+    const normalizedSource = sourcePath.replace(/\\/g, "/");
+    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));
+    }
+  }
+  return candidates.find((candidate) => candidate && fs.existsSync(candidate) && fs.statSync(candidate).isFile()) || "";
+}
+
+export function createKfd1ReleaseGateEvidence({
+  cwd = process.cwd(),
+  artifactRoot = "",
+  artifacts = [],
+  witnesses = [],
+  verifiedAt = new Date().toISOString(),
+  metadata = resolveKfd1Metadata(),
+} = {}) {
+  const normalizedWitnesses = witnesses.map((witness) => normalizeKfd1ContractWorldWitness(witness, { metadata }));
+  if (normalizedWitnesses.length === 0) {
+    return undefined;
+  }
+  const worlds = normalizedWitnesses.map((witness) => {
+    const preBuildWitnessSha256 = sha256Json(witness);
+    const surfaceResults = witness.surfaces.map((surface) => {
+      const filePath = resolveArtifactFile({
+        cwd,
+        artifactRoot,
+        artifacts,
+        artifactPath: surface.artifactPath,
+      });
+      if (!filePath) {
+        return {
+          name: surface.name,
+          artifactPath: surface.artifactPath,
+          expectedSha256: surface.expectedSha256,
+          actualSha256: "",
+          byteForByte: surface.byteForByte,
+          status: "failed",
+          reason: "artifact-missing",
+        };
+      }
+      const actualSha256 = sha256File(filePath);
+      const passed = actualSha256 === surface.expectedSha256;
+      return {
+        name: surface.name,
+        artifactPath: surface.artifactPath,
+        expectedSha256: surface.expectedSha256,
+        actualSha256,
+        byteForByte: surface.byteForByte,
+        status: passed ? "passed" : "failed",
+        reason: passed ? "" : "digest-mismatch",
+      };
+    });
+    const status = surfaceResults.every((surface) => surface.status === "passed") ? "passed" : "failed";
+    return {
+      id: witness.id,
+      standard: metadata.label,
+      standardKey: metadata.key,
+      preBuildWitnessSha256,
+      witness,
+      artifactVerification: {
+        status,
+        verifiedAt,
+        surfaces: surfaceResults,
+      },
+    };
+  });
+  const status = worlds.every((world) => world.artifactVerification.status === "passed") ? "passed" : "failed";
+  return {
+    key: metadata.key,
+    passportSection: {
+      schemaVersion: 1,
+      contract: KFD1_RELEASE_GATE_CONTRACT,
+      status,
+      metadata: {
+        standard: {
+          key: metadata.key,
+          id: metadata.id,
+          label: metadata.label,
+          title: metadata.title,
+          revision: metadata.revision,
+          status: metadata.status,
+        },
+        schemas: {
+          ids: metadata.schemaIds,
+          paths: metadata.schemaPaths,
+          metadata: metadata.metadataSchema,
+        },
+        package: metadata.package,
+      },
+      formatting: BUILDCHAIN_JSON_FORMATTING_POLICY,
+      contractWorlds: worlds,
+    },
+  };
+}
+
+export function validateKfd1ReleaseGateEvidence(section, { metadata = resolveKfd1Metadata() } = {}) {
+  const issues = [];
+  if (!section) {
+    return issues;
+  }
+  if (typeof section !== "object" || Array.isArray(section)) {
+    issues.push({
+      level: "error",
+      code: `${metadata.key}.object`,
+      message: `${metadata.key} release gate evidence must be an object`,
+      details: {},
+    });
+    return issues;
+  }
+  if (section.contract !== KFD1_RELEASE_GATE_CONTRACT) {
+    issues.push({
+      level: "error",
+      code: `${metadata.key}.contract`,
+      message: `${metadata.key}.contract must be ${KFD1_RELEASE_GATE_CONTRACT}`,
+      details: {},
+    });
+  }
+  if (section.metadata?.standard?.key !== metadata.key) {
+    issues.push({
+      level: "error",
+      code: `${metadata.key}.metadata.standard.key`,
+      message: `${metadata.key} metadata key must come from the KFD metadata package`,
+      details: { expected: metadata.key, actual: section.metadata?.standard?.key || "" },
+    });
+  }
+  const worlds = Array.isArray(section.contractWorlds) ? section.contractWorlds : [];
+  if (worlds.length === 0) {
+    issues.push({
+      level: "error",
+      code: `${metadata.key}.contractWorlds.empty`,
+      message: `${metadata.key}.contractWorlds must include at least one witness`,
+      details: {},
+    });
+  }
+  for (const [worldIndex, world] of worlds.entries()) {
+    if (!world.preBuildWitnessSha256) {
+      issues.push({
+        level: "error",
+        code: `${metadata.key}.contractWorlds[${worldIndex}].preBuildWitnessSha256`,
+        message: "KFD-1 contract world must record the frozen pre-build witness digest",
+        details: {},
+      });
+    }
+    if (world.standardKey !== metadata.key) {
+      issues.push({
+        level: "error",
+        code: `${metadata.key}.contractWorlds[${worldIndex}].standardKey`,
+        message: "KFD-1 contract world standardKey must match KFD metadata",
+        details: { expected: metadata.key, actual: world.standardKey || "" },
+      });
+    }
+    if (world.artifactVerification?.status !== "passed") {
+      issues.push({
+        level: "error",
+        code: `${metadata.key}.contractWorlds[${worldIndex}].artifactVerification`,
+        message: "KFD-1 artifact verification must pass before release passport finalization",
+        details: { id: world.id || "", status: world.artifactVerification?.status || "" },
+      });
+    }
+    const surfaces = Array.isArray(world.artifactVerification?.surfaces) ? world.artifactVerification.surfaces : [];
+    if (surfaces.length === 0) {
+      issues.push({
+        level: "error",
+        code: `${metadata.key}.contractWorlds[${worldIndex}].surfaces.empty`,
+        message: "KFD-1 artifact verification must list checked surfaces",
+        details: { id: world.id || "" },
+      });
+    }
+    for (const [surfaceIndex, surface] of surfaces.entries()) {
+      if (surface.status !== "passed" || !surface.expectedSha256 || !surface.actualSha256 || surface.expectedSha256 !== surface.actualSha256) {
+        issues.push({
+          level: "error",
+          code: `${metadata.key}.contractWorlds[${worldIndex}].surfaces[${surfaceIndex}]`,
+          message: "KFD-1 verified surface digest mismatch",
+          details: {
+            id: world.id || "",
+            name: surface.name || "",
+            artifactPath: surface.artifactPath || "",
+            status: surface.status || "",
+            reason: surface.reason || "",
+          },
+        });
+      }
+    }
+  }
+  if (section.status !== "passed") {
+    issues.push({
+      level: "error",
+      code: `${metadata.key}.status`,
+      message: "KFD-1 release gate status must be passed",
+      details: { status: section.status || "" },
+    });
+  }
+  return issues;
+}

package/packages/core/release-passport.js

@@ -4,6 +4,11 @@ import http from "node:http";
 import https from "node:https";
 import os from "node:os";
 import path from "node:path";
+import {
+  createKfd1ReleaseGateEvidence,
+  resolveKfd1Metadata,
+  validateKfd1ReleaseGateEvidence,
+} from "./kfd-gate.js";
 
 export const RELEASE_PASSPORT_CONTRACT = "kungfu-buildchain-release-passport";
 export const ARTIFACT_EVIDENCE_CONTRACT = "kungfu-buildchain-artifact-evidence";
@@ -621,6 +626,7 @@ export function createReleasePassport({
   publish = {},
   impact = undefined,
   workflow = {},
+  kfd1 = undefined,
 } = {}) {
   const normalizedTag = nonEmptyString(tag, "tag");
   const artifactEvidence = createArtifactEvidence({ assets, repository, tag: normalizedTag, sourceSha, workflow });
@@ -636,6 +642,8 @@ export function createReleasePassport({
     ? normalizeEvidenceDocument(distTagPromotionEvidence, "distTagPromotionEvidence")
     : undefined;
   const normalizedImpact = normalizeImpactLedger(impact, { tag: normalizedTag, line });
+  const kfd1Metadata = resolveKfd1Metadata();
+  const normalizedKfd1 = kfd1?.passportSection ? kfd1 : undefined;
   const publishArtifacts = normalizedPublishEvidence?.artifacts || [];
   const normalizedPublishSummary = normalizePublishSummary({
     packageSet: normalizedPackageSet,
@@ -736,6 +744,7 @@ export function createReleasePassport({
     ...(normalizedBuildSummary ? { buildSummary: normalizedBuildSummary } : {}),
     ...(normalizedPlatformArtifactManifests.length > 0 ? { platformArtifactManifests: normalizedPlatformArtifactManifests } : {}),
     ...(normalizedDistTagPromotionEvidence ? { distTagPromotion: normalizedDistTagPromotionEvidence } : {}),
+    ...(normalizedKfd1 ? { [normalizedKfd1.key || kfd1Metadata.key]: normalizedKfd1.passportSection } : {}),
     versionImpact: normalizedImpact.versionImpact,
     surfaceImpacts: normalizedImpact.surfaceImpacts,
     artifacts: [
@@ -771,6 +780,7 @@ export function createReleasePassport({
         artifactName: manifest.artifactName,
       })),
       distTagPromotionEvidence: normalizedDistTagPromotionEvidence?.path || "",
+      kfd1: normalizedKfd1 ? `${normalizedKfd1.key || kfd1Metadata.key}` : "",
       impact: impactPath,
       checkReport: checkReportPath,
       agentIndex: agentIndexPath,
@@ -804,6 +814,7 @@ export function collectGitHubReleasePassport({
   buildSummaryJson = "",
   platformManifestJsons = [],
   distTagEvidenceJson = "",
+  kfd1WitnessJsons = [],
   releaseJsonExtra = "",
   publishJson = "",
   workflow = {},
@@ -822,11 +833,15 @@ export function collectGitHubReleasePassport({
     .filter(Boolean)
     .map((manifestJson) => parseJsonInputWithMeta(manifestJson, undefined));
   const distTagEvidenceMeta = parseJsonInputWithMeta(distTagEvidenceJson, undefined);
+  const kfd1WitnessMetas = (kfd1WitnessJsons || [])
+    .filter(Boolean)
+    .map((witnessJson) => parseJsonInputWithMeta(witnessJson, undefined))
+    .filter((meta) => meta.value);
   const publish = parseJsonInput(publishJson, {});
   const assets = [
     ...(Array.isArray(release.assets) ? release.assets : []),
     ...(Array.isArray(assetsFromJson) ? assetsFromJson : []),
-    ...discoverAssetsFromDir(assetsDir),
+    ...discoverAssetsFromDir(assetsDir ? path.resolve(cwd, assetsDir) : ""),
   ];
   const resolvedTag = tag || release.tag_name || release.name || "";
   const resolvedOutputDir = path.resolve(cwd, outputDir);
@@ -834,6 +849,12 @@ export function collectGitHubReleasePassport({
   const artifactEvidence = createArtifactEvidence({ assets, repository, tag: resolvedTag, sourceSha, workflow });
   const impact = normalizeImpactLedger(impactMeta.value, { tag: resolvedTag, line, decision: "unknown" });
   const agentIndex = defaultAgentIndex({ tag: resolvedTag });
+  const kfd1 = createKfd1ReleaseGateEvidence({
+    cwd,
+    artifactRoot: assetsDir ? path.resolve(cwd, assetsDir) : "",
+    artifacts: assets,
+    witnesses: kfd1WitnessMetas.map((meta) => meta.value),
+  });
   const passport = createReleasePassport({
     cwd,
     repository,
@@ -870,6 +891,7 @@ export function collectGitHubReleasePassport({
     release: releaseExtra,
     publish,
     impact,
+    kfd1,
     publishEvidencePath: publishEvidenceMeta.path ? path.relative(resolvedOutputDir, publishEvidenceMeta.path).split(path.sep).join("/") : "",
     transactionStatePath: transactionMeta.path ? path.relative(resolvedOutputDir, transactionMeta.path).split(path.sep).join("/") : "",
     workflow,
@@ -1170,6 +1192,8 @@ export function createReleaseCheckReport({
   const declaredFinalImpact = normalizeImpactLevel(impact?.versionImpact?.final || impact?.classification);
   const computedFinalImpact = highestImpactLevel(surfaceImpacts.map((entry) => entry.impact));
   const requiredSurfaceImpacts = surfaceImpactRequirement({ passport, impact });
+  const kfd1Metadata = resolveKfd1Metadata();
+  issues.push(...validateKfd1ReleaseGateEvidence(passport?.[kfd1Metadata.key], { metadata: kfd1Metadata }));
   if (requiredSurfaceImpacts.required && surfaceImpacts.length === 0) {
     issues.push(issue("error", "impact.surfaceImpacts.required", "surfaceImpacts[] is required for this release passport type", requiredSurfaceImpacts));
   }

package/scripts/check-inventory.mjs

@@ -93,6 +93,9 @@ if (rootPackage.exports?.["./issue-reporting"] !== "./packages/core/issue-report
 if (rootPackage.exports?.["./logging"] !== "./packages/core/logging.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/logging");
 }
+if (rootPackage.exports?.["./kfd-gate"] !== "./packages/core/kfd-gate.js") {
+  throw new Error("root package must export @kungfu-tech/buildchain/kfd-gate");
+}
 if (rootPackage.exports?.["./release-passport"] !== "./packages/core/release-passport.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/release-passport");
 }
@@ -138,10 +141,22 @@ if (!coreIndexSource.includes("collectBuildchainDiagnostics")) {
 if (!coreIndexSource.includes("reportBuildchainIssue")) {
   throw new Error("packages/core/index.js must export reportBuildchainIssue");
 }
+for (const requiredSnippet of [
+  "createKfd1ReleaseGateEvidence",
+  "resolveKfd1Metadata",
+  "validateKfd1ReleaseGateEvidence",
+]) {
+  if (!coreIndexSource.includes(requiredSnippet)) {
+    throw new Error(`packages/core/index.js must export KFD-1 gate API: ${requiredSnippet}`);
+  }
+}
 for (const requiredSnippet of [
   "surfaceImpacts[]",
   "versionImpact.final",
   "kfd-registry-schema",
+  "`v2.8`",
+  "kfd-1-contract-world-release-gate",
+  "required-check-protection",
   "`v2.2`",
   "GitHub-hosted runners for production",
   "Self-hosted runners remain compatibility fixtures",
@@ -150,6 +165,18 @@ for (const requiredSnippet of [
     throw new Error(`versioning doc missing required snippet: ${requiredSnippet}`);
   }
 }
+const releasePassportDoc = fs.readFileSync(path.join(root, "docs/release-passport.md"), "utf8");
+for (const requiredSnippet of [
+  "--kfd-1-witness-json",
+  "@kungfu-tech/kfd",
+  "currently named `kfd-1`",
+  "Buildchain formatting policy",
+  "Verification fails closed",
+]) {
+  if (!releasePassportDoc.includes(requiredSnippet)) {
+    throw new Error(`release passport doc missing KFD-1 gate snippet: ${requiredSnippet}`);
+  }
+}
 for (const [docName, docSource] of Object.entries({ "docs/cli.md": cliDoc, "docs/install.md": installDoc })) {
   for (const requiredSnippet of [
     "minimumReleaseAgeExclude",
@@ -227,12 +254,24 @@ for (const requiredSnippet of [
   "target-sha: ${{ github.event.workflow_run.head_sha || inputs.sha || github.sha }}",
   "publish-required-artifacts-json: \"[]\"",
   "release-passport-impact-json: >-",
+  "Buildchain v2.8 promotes KFD-1 contract-world release gates",
+  "kfd-1-contract-world-release-gate",
+  "required-check-protection",
   "\"surfaceImpacts\":[",
 ]) {
   if (!buildchainRefPromotionWorkflow.includes(requiredSnippet)) {
     throw new Error(`buildchain ref promotion workflow missing npm transaction snippet: ${requiredSnippet}`);
   }
 }
+const releaseCandidatePromoteWorkflow = fs.readFileSync(path.join(root, ".github/workflows/release-candidate-promote.yml"), "utf8");
+for (const requiredSnippet of [
+  "release-passport-kfd-1-witness-jsons:",
+  "release-passport-kfd-1-witness-jsons: ${{ inputs.release-passport-kfd-1-witness-jsons }}",
+]) {
+  if (!releaseCandidatePromoteWorkflow.includes(requiredSnippet)) {
+    throw new Error(`release candidate promote workflow missing KFD-1 gate pass-through: ${requiredSnippet}`);
+  }
+}
 for (const forbiddenSnippet of [
   "run: node scripts/release-candidate-resolver.mjs",
   "uses: ./actions/promote-buildchain-ref",