@kungfu-tech/buildchain 2.14.2 → 2.14.3-alpha.0

package/dist/site/schemas/release-passport-v1.schema.json

@@ -0,0 +1,198 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://buildchain.libkungfu.dev/schemas/release-passport-v1.schema.json",
+  "title": "Buildchain Release Passport v1",
+  "description": "Standalone structural schema for the Buildchain-owned release-passport envelope. KFD subsection semantics remain owned by their canonical KFD schemas.",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "contract",
+    "product",
+    "release",
+    "artifacts",
+    "evidence",
+    "recovery"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "contract": {
+      "const": "kungfu-buildchain-release-passport"
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "product": {
+      "type": "object",
+      "required": [
+        "name",
+        "repository",
+        "mechanism"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "repository": {
+          "type": "string",
+          "minLength": 1
+        },
+        "mechanism": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": true
+    },
+    "release": {
+      "type": "object",
+      "required": [
+        "tag"
+      ],
+      "properties": {
+        "tag": {
+          "type": "string",
+          "minLength": 1
+        },
+        "sourceSha": {
+          "type": "string"
+        },
+        "releaseSha": {
+          "type": "string"
+        },
+        "releaseMaterialSha": {
+          "type": "string"
+        },
+        "targetRef": {
+          "type": "string"
+        },
+        "channel": {
+          "type": "string"
+        },
+        "line": {
+          "type": "string"
+        },
+        "package": {
+          "type": "object"
+        }
+      },
+      "additionalProperties": true
+    },
+    "artifacts": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "name"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "additionalProperties": true
+      }
+    },
+    "evidence": {
+      "type": "object",
+      "required": [
+        "artifactEvidence",
+        "impact",
+        "agentIndex"
+      ],
+      "properties": {
+        "artifactEvidence": {
+          "type": "string",
+          "minLength": 1
+        },
+        "impact": {
+          "type": "string",
+          "minLength": 1
+        },
+        "agentIndex": {
+          "type": "string",
+          "minLength": 1
+        },
+        "publishEvidence": {
+          "type": "string"
+        },
+        "transactionState": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": true
+    },
+    "recovery": {
+      "type": "object"
+    },
+    "workflow": {
+      "type": "object"
+    },
+    "runnerPolicy": {
+      "type": "object"
+    },
+    "versionImpact": {
+      "type": "object"
+    },
+    "surfaceImpacts": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    },
+    "packageSet": {
+      "type": "object"
+    },
+    "anchorManifest": {
+      "type": "object"
+    },
+    "trustedPublishing": {
+      "type": "object"
+    },
+    "transaction": {
+      "type": "object"
+    },
+    "surfaceTimestampPolicy": {
+      "type": "object"
+    },
+    "buildFacts": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    },
+    "buildSummary": {
+      "type": "object"
+    },
+    "platformArtifactManifests": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    },
+    "distTagPromotion": {
+      "type": "object"
+    },
+    "controllerReceipts": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    },
+    "kfd-1": {
+      "type": "object"
+    },
+    "kfd-2": {
+      "type": "object"
+    },
+    "kfd-3": {
+      "type": "object"
+    }
+  },
+  "additionalProperties": true
+}

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-18T01:00:00.995Z",
-  "publishedAt": "2026-07-18T01:00:00.995Z",
+  "generatedAt": "2026-07-18T22:57:23.219Z",
+  "publishedAt": "2026-07-18T22:57:23.219Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "ae16e640bf2f21c8f981ffa8b3523c8aae9200b2",
+  "sourceRevision": "8b0423396f09f29e2ea05c38896228751767ab21",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.14.2",
+    "version": "2.14.3-alpha.0",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -69,7 +69,7 @@
       "path": "docs/release-passport.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:2421e3e9f2dd892971bea5deb605492dfec38f3a83e539229442b55380bebe25"
+      "digest": "sha256:0029014ffab7d7228a12d8b92326b78cf6757a41f481b661c5997e2cef06d3cc"
     },
     {
       "id": "controller-evidence",
@@ -101,7 +101,7 @@
       "path": "docs/release-propagation.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:d5877075eb41a3d41e531549da113756d29d6f34c91e3b68b8ce650753d5ca1d"
+      "digest": "sha256:fc2b743e3d76c4f90cdd8c6560cf9d619ad25d74c15c074be96db7bcb6cc2a29"
     },
     {
       "id": "readme-badges",

package/dist/site/workflow-registry.json

@@ -1444,17 +1444,20 @@
         "buildchain-repository",
         "downstream-base-ref",
         "downstream-branch",
+        "downstream-prepare-command",
         "downstream-repository",
         "downstream-target",
+        "downstream-verify-command",
         "dry-run",
         "graph-json",
         "lock-path",
         "pr-body",
         "pr-title",
+        "refresh-managed-readme-badges",
         "source-node",
         "upstream-release-json"
       ],
-      "inputCount": 13,
+      "inputCount": 16,
       "secrets": [
         "propagation-token"
       ],

package/docs/release-passport.md

@@ -19,6 +19,25 @@ do not infer execution evidence from a green job. See
 The release passport surface is a welded contract. Additive fields are allowed;
 breaking semantic changes require a new major line.
 
+Independent verifiers can pin two package-owned, standalone files without
+scraping this implementation:
+
+- `dist/site/schemas/release-passport-v1.schema.json` is the self-contained
+  JSON Schema for the Buildchain-owned envelope;
+- `dist/site/release-passport-check-manifest.json` names the normative checker,
+  required and conditional sibling evidence, local-resolution rules,
+  Buildchain aggregation fields, canonical KFD subsection schema authorities,
+  and forward-compatibility policy.
+
+The same files are exported as
+`@kungfu-tech/buildchain/site/schemas/release-passport-v1.schema.json` and
+`@kungfu-tech/buildchain/site/release-passport-check-manifest.json`. The schema
+checks the envelope shape. `buildchain verify release-passport` remains the
+normative semantic checker: it resolves sibling evidence relative to the
+passport and fails closed on missing evidence, digest drift, or inconsistent
+release facts. Buildchain owns envelope aggregation; KFD retains schema and
+compatibility authority for the `kfd-1`, `kfd-2`, and `kfd-3` subsections.
+
 P0 protocol artifacts:
 
 - `product-mechanism.json`

package/docs/release-propagation.md

@@ -182,6 +182,8 @@ jobs:
       downstream-target: site-libkungfu-dev
       downstream-repository: kungfu-systems/site-libkungfu-dev
       downstream-base-ref: dev/v2/v2.7
+      downstream-prepare-command: pnpm install --frozen-lockfile --ignore-scripts
+      downstream-verify-command: pnpm run check
       dry-run: false
     secrets:
       propagation-token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}
@@ -199,13 +201,23 @@ open PR.
 The workflow checks out the Buildchain runtime selected by
 `buildchain-repository` and `buildchain-ref` into `.buildchain/runtime`, invokes
 that runtime for the propagation plan and lock write, then checks out the
-downstream repository, writes the exact lock, and opens or updates a PR. It does
-not publish the downstream release directly. The downstream repository keeps its
-normal Buildchain governance: the PR updates source-of-truth facts, then
-downstream alpha or release publication runs through its own protected channel.
-The workflow stages the declared lock path before checking the index, so the
-first propagation creates a PR even when the lock did not previously exist; a
-byte-identical rerun is an explicit successful no-op.
+downstream repository and writes the exact lock. A consumer that must pin the
+exact upstream package or regenerate deterministic files declares
+`downstream-prepare-command`. The command receives
+`BUILDCHAIN_UPSTREAM_PACKAGE_NAME`, `BUILDCHAIN_UPSTREAM_PACKAGE_VERSION`, and
+`BUILDCHAIN_UPSTREAM_RELEASE_LOCK`. After preparation, Buildchain refreshes an
+existing `<!-- buildchain:badges:start -->` README block by default. Consumers
+can disable that step with `refresh-managed-readme-badges: false`.
+
+`downstream-verify-command` runs against the final tree before any commit or
+push, so consumers can use the same check as their PR workflow. Preparation,
+badge refresh, and verification failures all fail closed. The workflow stages
+the complete deterministic result, signs the propagation commit with DCO, and
+then opens or updates the PR. It does not publish the downstream release
+directly. The downstream repository keeps its normal Buildchain governance: the
+PR updates source-of-truth facts, then downstream alpha or release publication
+runs through its own protected channel. A byte-identical rerun is an explicit
+successful no-op.
 For unreleased runtime validation, keep the caller's reusable workflow reference
 on `@v2` and pass a temporary train ref through `buildchain-ref`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.14.2",
+  "version": "2.14.3-alpha.0",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -38,6 +38,7 @@
     "./release-candidate": "./packages/core/release-candidate.js",
     "./stable-candidate-ledger": "./packages/core/stable-candidate-ledger.js",
     "./release-passport": "./packages/core/release-passport.js",
+    "./release-passport-contract": "./packages/core/release-passport-contract.js",
     "./release-propagation": "./packages/core/release-propagation.js",
     "./surface-manifest": "./packages/core/surface-manifest.js",
     "./buildchain-kfd-claims": "./packages/core/buildchain-kfd-claims.js",
@@ -57,6 +58,8 @@
     "./site/kfd-upstream-aggregate.json": "./dist/site/kfd-upstream-aggregate.json",
     "./site/release-model.json": "./dist/site/release-model.json",
     "./site/artifact-schemas.json": "./dist/site/artifact-schemas.json",
+    "./site/release-passport-check-manifest.json": "./dist/site/release-passport-check-manifest.json",
+    "./site/schemas/release-passport-v1.schema.json": "./dist/site/schemas/release-passport-v1.schema.json",
     "./site/buildchain-contract.json": "./dist/site/buildchain-contract.json",
     "./site/product-mechanism.json": "./dist/site/product-mechanism.json",
     "./site/release-provenance.json": "./dist/site/release-provenance.json",
@@ -104,7 +107,7 @@
     "vitest": "^4.1.9"
   },
   "dependencies": {
-    "@kungfu-tech/kfd": "1.0.0-alpha.21",
+    "@kungfu-tech/kfd": "1.0.0-alpha.29",
     "smol-toml": "1.7.0"
   }
 }

package/packages/core/index.js

@@ -37,6 +37,7 @@ export {
   detectPackageManager,
   getWorkspaceInfo,
   shellJoin,
+  validatePackageManagerContract,
 } from "./package-manager.js";
 
 export {
@@ -320,6 +321,14 @@ export {
   verifyReleasePassport,
 } from "./release-passport.js";
 
+export {
+  RELEASE_PASSPORT_CHECK_MANIFEST_CONTRACT,
+  RELEASE_PASSPORT_SCHEMA,
+  RELEASE_PASSPORT_SCHEMA_ID,
+  createReleasePassportCheckManifest,
+  validateReleasePassportSchema,
+} from "./release-passport-contract.js";
+
 export {
   BUILDCHAIN_CONSUMER_ISSUE_CONTRACT,
   BUILDCHAIN_WORKFLOW_FRICTION_ISSUE_CONTRACT,

package/packages/core/package-manager.js

@@ -15,6 +15,37 @@ function parsePackageManager(value) {
   return match ? match[1] : null;
 }
 
+export function validatePackageManagerContract({ cwd = process.cwd(), expectedManager = "" } = {}) {
+  const resolvedCwd = path.resolve(cwd);
+  const pkg = readJsonIfExists(path.join(resolvedCwd, "package.json"));
+  const declaredSpec = String(pkg?.packageManager || "").trim();
+  const declaredMatch = declaredSpec.match(/^([A-Za-z0-9._-]+)@([^\s]+)$/);
+
+  if (declaredSpec && !declaredMatch) {
+    throw new Error(
+      `Invalid packageManager declaration: ${declaredSpec}. Expected <manager>@<version>.`,
+    );
+  }
+
+  const declaredName = declaredMatch?.[1] || "";
+  const detected = declaredName && !KNOWN_MANAGERS.has(declaredName)
+    ? { name: "custom", reason: "packageManager" }
+    : detectPackageManager(resolvedCwd);
+  const expected = String(expectedManager || "").trim();
+  if (expected && expected !== "custom" && detected.name !== expected) {
+    throw new Error(
+      `Package manager mismatch: workflow requested ${expected}, but the consumer declares ${detected.name}.`,
+    );
+  }
+
+  return {
+    name: detected.name,
+    reason: detected.reason,
+    declaredSpec,
+    declaredVersion: declaredMatch?.[2] || "",
+  };
+}
+
 export function assertPackageManager(manager) {
   if (!KNOWN_MANAGERS.has(manager)) {
     throw new Error(`Unsupported package manager: ${manager}`);
@@ -288,4 +319,5 @@ export default {
   getWorkspaceInfo,
   getYarnLockInfo,
   shellJoin,
+  validatePackageManagerContract,
 };

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

@@ -0,0 +1,249 @@
+import kfdStandards from "@kungfu-tech/kfd/standards.json" with { type: "json" };
+import {
+  RELEASE_CHECK_REPORT_CONTRACT,
+  RELEASE_PASSPORT_CONTRACT,
+} from "./release-passport.js";
+
+export const RELEASE_PASSPORT_SCHEMA_ID =
+  "https://buildchain.libkungfu.dev/schemas/release-passport-v1.schema.json";
+export const RELEASE_PASSPORT_CHECK_MANIFEST_CONTRACT =
+  "kungfu-buildchain-release-passport-check-manifest";
+
+const OBJECT = { type: "object" };
+const STRING = { type: "string", minLength: 1 };
+const OPTIONAL_STRING = { type: "string" };
+
+export const RELEASE_PASSPORT_SCHEMA = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: RELEASE_PASSPORT_SCHEMA_ID,
+  title: "Buildchain Release Passport v1",
+  description:
+    "Standalone structural schema for the Buildchain-owned release-passport envelope. KFD subsection semantics remain owned by their canonical KFD schemas.",
+  type: "object",
+  required: [
+    "schemaVersion",
+    "contract",
+    "product",
+    "release",
+    "artifacts",
+    "evidence",
+    "recovery",
+  ],
+  properties: {
+    schemaVersion: { const: 1 },
+    contract: { const: RELEASE_PASSPORT_CONTRACT },
+    generatedAt: { type: "string", format: "date-time" },
+    product: {
+      type: "object",
+      required: ["name", "repository", "mechanism"],
+      properties: {
+        name: STRING,
+        repository: STRING,
+        mechanism: STRING,
+      },
+      additionalProperties: true,
+    },
+    release: {
+      type: "object",
+      required: ["tag"],
+      properties: {
+        tag: STRING,
+        sourceSha: OPTIONAL_STRING,
+        releaseSha: OPTIONAL_STRING,
+        releaseMaterialSha: OPTIONAL_STRING,
+        targetRef: OPTIONAL_STRING,
+        channel: OPTIONAL_STRING,
+        line: OPTIONAL_STRING,
+        package: OBJECT,
+      },
+      additionalProperties: true,
+    },
+    artifacts: {
+      type: "array",
+      minItems: 1,
+      items: {
+        type: "object",
+        required: ["name"],
+        properties: { name: STRING },
+        additionalProperties: true,
+      },
+    },
+    evidence: {
+      type: "object",
+      required: ["artifactEvidence", "impact", "agentIndex"],
+      properties: {
+        artifactEvidence: STRING,
+        impact: STRING,
+        agentIndex: STRING,
+        publishEvidence: OPTIONAL_STRING,
+        transactionState: OPTIONAL_STRING,
+      },
+      additionalProperties: true,
+    },
+    recovery: OBJECT,
+    workflow: OBJECT,
+    runnerPolicy: OBJECT,
+    versionImpact: OBJECT,
+    surfaceImpacts: { type: "array", items: OBJECT },
+    packageSet: OBJECT,
+    anchorManifest: OBJECT,
+    trustedPublishing: OBJECT,
+    transaction: OBJECT,
+    surfaceTimestampPolicy: OBJECT,
+    buildFacts: { type: "array", items: OBJECT },
+    buildSummary: OBJECT,
+    platformArtifactManifests: { type: "array", items: OBJECT },
+    distTagPromotion: OBJECT,
+    controllerReceipts: { type: "array", items: OBJECT },
+    "kfd-1": OBJECT,
+    "kfd-2": OBJECT,
+    "kfd-3": OBJECT,
+  },
+  additionalProperties: true,
+};
+
+const BUILDCHAIN_AGGREGATION_FIELDS = [
+  "product",
+  "release",
+  "workflow",
+  "runnerPolicy",
+  "versionImpact",
+  "surfaceImpacts",
+  "packageSet",
+  "anchorManifest",
+  "trustedPublishing",
+  "transaction",
+  "surfaceTimestampPolicy",
+  "buildFacts",
+  "buildSummary",
+  "platformArtifactManifests",
+  "distTagPromotion",
+  "controllerReceipts",
+  "artifacts",
+  "evidence",
+  "recovery",
+];
+
+function kfdSectionAuthority(id, standards = kfdStandards) {
+  const standard = standards?.standards?.[id] || {};
+  return {
+    section: id,
+    owner: "KFD",
+    package: standards?.source?.package || "@kungfu-tech/kfd",
+    metadataSchema: standards?.metadataSchema || {},
+    schemaIds: standard.schemaIds || {},
+    schemaPaths: standard.schemaPaths || {},
+    compatibility: standard.compatibility || {},
+    rule: `Buildchain aggregates and checks ${id} evidence but does not redefine its schema semantics.`,
+  };
+}
+
+export function createReleasePassportCheckManifest({ standards = kfdStandards } = {}) {
+  return {
+    schemaVersion: 1,
+    contract: RELEASE_PASSPORT_CHECK_MANIFEST_CONTRACT,
+    passport: {
+      contract: RELEASE_PASSPORT_CONTRACT,
+      schemaVersion: 1,
+      schema: {
+        id: RELEASE_PASSPORT_SCHEMA_ID,
+        path: "schemas/release-passport-v1.schema.json",
+        npmExport: "@kungfu-tech/buildchain/site/schemas/release-passport-v1.schema.json",
+      },
+      checker: {
+        contract: RELEASE_CHECK_REPORT_CONTRACT,
+        command: "buildchain verify release-passport <buildchain.release.json>",
+        nodeApi: "@kungfu-tech/buildchain/release-passport#verifyReleasePassport",
+        result: "check-report.json",
+      },
+    },
+    ownership: {
+      envelopeOwner: "Buildchain",
+      aggregationFields: BUILDCHAIN_AGGREGATION_FIELDS,
+      kfdSections: ["kfd-1", "kfd-2", "kfd-3"].map((id) =>
+        kfdSectionAuthority(id, standards),
+      ),
+    },
+    localClosure: {
+      entrypoint: "buildchain.release.json",
+      resolutionBase: "directory containing the passport",
+      requiredSiblings: [
+        "product.mechanism",
+        "evidence.artifactEvidence",
+        "evidence.impact",
+        "evidence.agentIndex",
+      ],
+      conditionalSiblings: [
+        {
+          when: "evidence.publishEvidence is present or packageSet is present",
+          pointer: "evidence.publishEvidence",
+        },
+        {
+          when: "evidence.transactionState is present",
+          pointer: "evidence.transactionState",
+        },
+      ],
+      rule:
+        "The normative checker resolves every declared sibling relative to the passport and fails closed on missing required evidence, digest drift, or semantic mismatch.",
+    },
+    compatibility: {
+      envelope:
+        "Compatible optional fields may be added while schemaVersion remains 1; removing or changing required-field semantics requires a new schema id or contract version.",
+      siblings:
+        "New optional siblings may be added in v1; making a sibling required requires a new schema id or contract version.",
+      kfdSections:
+        "Each KFD subsection follows the compatibility metadata published by @kungfu-tech/kfd; Buildchain must not silently reinterpret a KFD schema version.",
+      unknownFields: "Independent readers must preserve or ignore unknown additive fields.",
+    },
+  };
+}
+
+function matchesType(value, type) {
+  if (type === "object") return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+  if (type === "array") return Array.isArray(value);
+  if (type === "integer") return Number.isInteger(value);
+  return typeof value === type;
+}
+
+function validateSchemaNode(schema, value, pointer, issues) {
+  if (schema.type && !matchesType(value, schema.type)) {
+    issues.push({ pointer, code: "type", message: `${pointer} must be ${schema.type}` });
+    return;
+  }
+  if (Object.hasOwn(schema, "const") && value !== schema.const) {
+    issues.push({ pointer, code: "const", message: `${pointer} must equal ${JSON.stringify(schema.const)}` });
+  }
+  if (schema.minLength && typeof value === "string" && value.length < schema.minLength) {
+    issues.push({ pointer, code: "minLength", message: `${pointer} must not be empty` });
+  }
+  if (schema.minItems && Array.isArray(value) && value.length < schema.minItems) {
+    issues.push({ pointer, code: "minItems", message: `${pointer} must contain at least ${schema.minItems} item(s)` });
+  }
+  if (Array.isArray(value) && schema.items) {
+    value.forEach((entry, index) => validateSchemaNode(schema.items, entry, `${pointer}/${index}`, issues));
+  }
+  if (matchesType(value, "object")) {
+    for (const key of schema.required || []) {
+      if (!Object.hasOwn(value, key)) {
+        issues.push({ pointer: `${pointer}/${key}`, code: "required", message: `${pointer}/${key} is required` });
+      }
+    }
+    for (const [key, childSchema] of Object.entries(schema.properties || {})) {
+      if (Object.hasOwn(value, key)) {
+        validateSchemaNode(childSchema, value[key], `${pointer}/${key}`, issues);
+      }
+    }
+  }
+}
+
+export function validateReleasePassportSchema(passport) {
+  const issues = [];
+  validateSchemaNode(RELEASE_PASSPORT_SCHEMA, passport, "#", issues);
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-release-passport-schema-validation",
+    schemaId: RELEASE_PASSPORT_SCHEMA_ID,
+    ok: issues.length === 0,
+    issues,
+  };
+}