@kungfu-tech/buildchain 2.14.3 → 2.14.4-alpha.1

package/dist/site/public-surface-audit.json

@@ -735,6 +735,8 @@
           "release-passport",
           "release-passport-buildchain-self-kfd",
           "release-passport-impact-json",
+          "release-passport-invariant-passport-command",
+          "release-passport-invariant-passport-jsons",
           "release-passport-kfd-1-witness-jsons",
           "release-passport-kfd-2-claim-jsons",
           "release-passport-kfd-3-artifact-verify-command",
@@ -750,7 +752,7 @@
           "target-sha",
           "trusted-publishing"
         ],
-        "inputCount": 70,
+        "inputCount": 72,
         "secrets": [
           "BUILDCHAIN_ISSUE_APP_ID",
           "BUILDCHAIN_ISSUE_APP_PRIVATE_KEY",
@@ -1777,6 +1779,8 @@
           "release-passport",
           "release-passport-buildchain-self-kfd",
           "release-passport-impact-json",
+          "release-passport-invariant-passport-command",
+          "release-passport-invariant-passport-jsons",
           "release-passport-kfd-1-witness-jsons",
           "release-passport-kfd-2-claim-jsons",
           "release-passport-kfd-3-artifact-verify-command",
@@ -1792,7 +1796,7 @@
           "target-sha",
           "trusted-publishing"
         ],
-        "inputCount": 62,
+        "inputCount": 64,
         "secrets": [
           "BUILDCHAIN_ISSUE_APP_ID",
           "BUILDCHAIN_ISSUE_APP_PRIVATE_KEY",
@@ -2017,6 +2021,8 @@
           "release-passport-build-summary-path",
           "release-passport-buildchain-self-kfd",
           "release-passport-impact-json",
+          "release-passport-invariant-passport-command",
+          "release-passport-invariant-passport-jsons",
           "release-passport-kfd-1-witness-jsons",
           "release-passport-kfd-2-claim-jsons",
           "release-passport-kfd-3-artifact-verify-command",
@@ -2038,7 +2044,7 @@
           "transaction-state-path",
           "verification-command"
         ],
-        "inputCount": 60
+        "inputCount": 62
       },
       {
         "id": "report-buildchain-issue",
@@ -3629,8 +3635,8 @@
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "b469949f77ed7777f23fe68c54daf6d2c20d3afc97f3bbd5a178a91202a068d0",
-    "workflowRegistryDigest": "4812aea118585c3f527834090569f02cf66c142d2f9a0f8b3d3882e9a614a361",
-    "pageRegistryDigest": "a0cb6986c2f52468405374106606adfdd6a9a70cbb6b4dc2fc100aeb413901e6"
+    "workflowRegistryDigest": "ea8ba62e4fa1e3399df992e75e907ba14c42b1fc9b936e6d93cee04bb1a1c257",
+    "pageRegistryDigest": "8cad634cb5fe3fac32df1724024df69478bbf5aaf47b5d7f791f1d6ce1e369f8"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-07-19T14:35:41.954Z",
-  "publishedAt": "2026-07-19T14:35:41.954Z",
+  "generatedAt": "2026-07-20T14:30:08.216Z",
+  "publishedAt": "2026-07-20T14:30:08.216Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "e8b620431679d89985e47f429db8c21f4424cc52",
+  "sourceRevision": "24d614a941bc9b9c452bf50ab8c1efd08770c2a5",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.14.3",
+    "version": "2.14.4-alpha.1",
     "versionSource": "package.json#version"
   },
   "sourceKind": "package-site-bundle",

package/dist/site/release-passport-check-manifest.json

@@ -27,6 +27,7 @@
       "surfaceImpacts",
       "packageSet",
       "anchorManifest",
+      "versionMaterial",
       "trustedPublishing",
       "transaction",
       "surfaceTimestampPolicy",

package/dist/site/release-provenance.json

@@ -14,6 +14,7 @@
       "./core": "./packages/core/index.js",
       "./artifact-passport": "./packages/core/artifact-passport.js",
       "./artifact-verification-envelope": "./packages/core/artifact-verification-envelope.js",
+      "./anchored-version-material": "./packages/core/anchored-version-material.js",
       "./buildchain-contract": "./packages/core/buildchain-contract.js",
       "./controller-evidence": "./packages/core/controller-evidence.js",
       "./diagnostics": "./packages/core/diagnostics.js",

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

@@ -151,6 +151,9 @@
     "anchorManifest": {
       "type": "object"
     },
+    "versionMaterial": {
+      "type": "object"
+    },
     "trustedPublishing": {
       "type": "object"
     },

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-19T14:35:41.954Z",
-  "publishedAt": "2026-07-19T14:35:41.954Z",
+  "generatedAt": "2026-07-20T14:30:08.216Z",
+  "publishedAt": "2026-07-20T14:30:08.216Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "e8b620431679d89985e47f429db8c21f4424cc52",
+  "sourceRevision": "24d614a941bc9b9c452bf50ab8c1efd08770c2a5",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.14.3",
+    "version": "2.14.4-alpha.1",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -53,7 +53,7 @@
       "path": "docs/MAP.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:308bc83b7403f407ac1be13d7c19000fa249f4bedf0c9c90b2f701e5163471a3"
+      "digest": "sha256:fa818a541ee2d70a0cc08caec85bf4c1eb20ff5118be0cc2149062fed50f4620"
     },
     {
       "id": "install",
@@ -69,7 +69,7 @@
       "path": "docs/release-passport.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:0029014ffab7d7228a12d8b92326b78cf6757a41f481b661c5997e2cef06d3cc"
+      "digest": "sha256:2dec5e7cd0050815d17c30dbbfd2f5c3c987f55a4558514118538d81a9c562b0"
     },
     {
       "id": "controller-evidence",
@@ -189,7 +189,7 @@
       "path": "docs/cli.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:1733f9377938a16e6de77511546be7de67c5ab8816220d693fd46f55450a5148"
+      "digest": "sha256:733a43df58e6fa643ef529d8736fbdbea053b5b58e5fbe445b595ea1e25861f6"
     },
     {
       "id": "build-facts",
@@ -213,7 +213,7 @@
       "path": "docs/lifecycle-protocol.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:3a03359ec58db04f334303256b02020f6039616e8802c19dfc00e76bbb05bf18"
+      "digest": "sha256:71552baae51146fa790d40af02d5d5b3a1a4aa0d9764af09907bb05d3360b0cc"
     },
     {
       "id": "reusable-build-surface",
@@ -237,7 +237,7 @@
       "path": "docs/release-governance.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:d25a2ceb6cdc1a1db321e7d2a6aa8a454fb4d7a10560177604f8ecb5801a6e66"
+      "digest": "sha256:cea8921c430b208ec127af1800b58be21812ea07066998eb940ea1ac53738f2f"
     },
     {
       "id": "release-flow",
@@ -261,7 +261,7 @@
       "path": "docs/versioning.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:e856ec8aee11ff4bd2760425a8950538a91245cd5624c22c8768af50d6b1a8ce"
+      "digest": "sha256:10ec868fcb3fd58ae35b54ecd8ccd9a4556516f460c262f0c1ee41c81bdbc264"
     },
     {
       "id": "web-surface-deployments",

package/dist/site/workflow-registry.json

@@ -324,6 +324,8 @@
         "release-passport",
         "release-passport-buildchain-self-kfd",
         "release-passport-impact-json",
+        "release-passport-invariant-passport-command",
+        "release-passport-invariant-passport-jsons",
         "release-passport-kfd-1-witness-jsons",
         "release-passport-kfd-2-claim-jsons",
         "release-passport-kfd-3-artifact-verify-command",
@@ -339,7 +341,7 @@
         "target-sha",
         "trusted-publishing"
       ],
-      "inputCount": 70,
+      "inputCount": 72,
       "secrets": [
         "BUILDCHAIN_ISSUE_APP_ID",
         "BUILDCHAIN_ISSUE_APP_PRIVATE_KEY",
@@ -1471,6 +1473,8 @@
         "release-passport",
         "release-passport-buildchain-self-kfd",
         "release-passport-impact-json",
+        "release-passport-invariant-passport-command",
+        "release-passport-invariant-passport-jsons",
         "release-passport-kfd-1-witness-jsons",
         "release-passport-kfd-2-claim-jsons",
         "release-passport-kfd-3-artifact-verify-command",
@@ -1486,7 +1490,7 @@
         "target-sha",
         "trusted-publishing"
       ],
-      "inputCount": 62,
+      "inputCount": 64,
       "secrets": [
         "BUILDCHAIN_ISSUE_APP_ID",
         "BUILDCHAIN_ISSUE_APP_PRIVATE_KEY",
@@ -1739,6 +1743,8 @@
         "release-passport-build-summary-path",
         "release-passport-buildchain-self-kfd",
         "release-passport-impact-json",
+        "release-passport-invariant-passport-command",
+        "release-passport-invariant-passport-jsons",
         "release-passport-kfd-1-witness-jsons",
         "release-passport-kfd-2-claim-jsons",
         "release-passport-kfd-3-artifact-verify-command",
@@ -1760,7 +1766,7 @@
         "transaction-state-path",
         "verification-command"
       ],
-      "inputCount": 60,
+      "inputCount": 62,
       "capabilityGroup": "release-passport-trust",
       "status": "active"
     },

package/docs/MAP.md

@@ -41,6 +41,7 @@ workflow, action, and Node API export also carries a `capabilityGroup`,
 | --- | --- | --- |
 | Capability-grouped KFD navigation | `dist/site/capability-registry.json`, `dist/site/page-registry.json`, `dist/site/manual-registry.json`, `dist/site/cli-registry.json`, `dist/site/node-api-registry.json` | this map, [`site-bundle-contract.md`](site-bundle-contract.md), [`kfd-support.md`](kfd-support.md) |
 | KFD-1 / KFD-2 / KFD-3 release-passport gates | `dist/site/kfd-claims.json`, `dist/site/buildchain-contract.json`, `dist/site/artifact-schemas.json` | [`release-passport.md`](release-passport.md) |
+| Product invariant Passport release gate | `buildchain.release.json#invariantPassports`, `dist/site/buildchain-contract.json` | [`release-passport.md`](release-passport.md) |
 | KFD-3 public surface reverse audit | `dist/site/public-surface-audit.json`, `dist/site/cli-registry.json`, `dist/site/workflow-registry.json`, `dist/site/page-registry.json` | [`cli.md`](cli.md), [`site-bundle-contract.md`](site-bundle-contract.md) |
 | KFD-1 / KFD-2 / KFD-3 first-class CLI and Node API | `.buildchain/kfd/kfd-3/surfaces.json`, `dist/site/kfd-claims.json`, `buildchain.release.json`, KFD schemas from `@kungfu-tech/kfd` | [`kfd-support.md`](kfd-support.md), [`cli.md`](cli.md#commands) |
 | Floating `@v2` drift detection and compatibility issues | `dist/site/buildchain-contract.json` | [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock) |

package/docs/cli.md

@@ -663,6 +663,13 @@ into release evidence. A package cannot claim KFD-3 collaboration-interface
 support merely because the docs mention it; the release passport must show the
 frozen declaration, the artifact-side witness digest, and a passing closure
 comparison.
+
+`--invariant-passport-json` attaches a product-owned invariant Passport to the
+release gate and may be repeated. `--invariant-passport-cmd` runs a product
+command that emits one Passport JSON document. Buildchain verifies the
+Passport root, exact clean source identity, `verified` verdict, complete
+platform coverage, and residual-risk shape; it does not redefine the product's
+invariant semantics. Declared invariant Passport input is fail-closed.
 For the KFD repository itself, the witness can declare docs, schemas, standards
 metadata, package exports, and site-consumption contracts as grouped public
 surfaces; the artifact witness must expose the same enumerable package/site

package/docs/lifecycle-protocol.md

@@ -96,6 +96,9 @@ required = true
 strategy = "anchored"
 next = "manual"
 manifest = "libnode.release.json"
+derived_files = [
+  "dist/version-witness.json",
+]
 
 [[version.files]]
 type = "json"
@@ -109,6 +112,17 @@ With `strategy = "anchored"` and `next = "manual"`:
   does not rewrite those files to the Buildchain release tag.
 - `lifecycle.verify` is the project-owned truth gate. It should compare the
   package version, anchor manifest, and upstream source/submodule state.
+- `version.derived_files` can declare committed witnesses or generated metadata
+  whose bytes are derived by `lifecycle.version-state`. The field is valid only
+  for anchored/manual projects that declare both `lifecycle.version-state` and
+  `lifecycle.verify`.
+- release-candidate builds rerun derivation and verification before heavy
+  platform builds, require the committed tree to remain unchanged, and bind the
+  alpha/release tree identities plus declared file digests into controller and
+  release-passport evidence.
+- release promotion permits differences from the tested alpha tree only in
+  `version.files`, the anchor manifest, and declared `version.derived_files`;
+  any other changed path fails closed before publication.
 - release promotion still creates the exact/floating production refs for the
   current line;
 - release promotion does not auto-create the next alpha branch or tag;

package/docs/release-governance.md

@@ -631,11 +631,20 @@ declare version-state files and lifecycle commands without pretending every
 project is a Node workspace. Supported version files include JSON, TOML, and
 regex-based files such as `CMakeLists.txt` or `conanfile.py`.
 
-The promotion action currently consumes `version.files` and `lifecycle.verify`.
+The promotion action consumes `version.files`, optional anchored/manual
+`version.derived_files`, and `lifecycle.verify`.
 The verify stage runs after generated version-state changes are applied locally
 and before any release refs move. If `verification-command` is passed directly
 to the action, that explicit command overrides `lifecycle.verify`.
 
+Anchored/manual repositories may use `version.derived_files` for committed
+version witnesses that are regenerated by `lifecycle.version-state`. The
+release-candidate build verifies those witnesses before heavy builds and records
+their digests with the exact alpha and release tree identities. Promotion then
+accepts only declared version files, the anchor manifest, and those derived
+files as differences from the tested alpha tree; release passports preserve the
+same material binding.
+
 Protected release-line branches keep their normal human review gate. Managed
 `dev/vN/vN.M`, `alpha/vN/vN.M`, and `release/vN/vN.M` branches are configured
 with one required approving review, required GitHub Actions checks, administrator

package/docs/release-passport.md

@@ -86,6 +86,11 @@ Additive passport sections:
   back to the evidence file that proves its digest. Registry artifacts retain
   optional built/reused action, content and current-release coordinates,
   platform/contract/parent metadata, and fail-closed verification evidence.
+- `invariantPassports`: product-owned invariant verification results admitted
+  by Buildchain. Each entry binds the product contract and registry roots,
+  semantic Passport root, exact clean source revision, complete platform
+  coverage, verdict, and residual risk. Buildchain owns release admission, not
+  the meaning of the product invariants.
 
 Buildchain's own binary lane also publishes observability artifacts generated by
 the Buildchain logging API and CLI:
@@ -138,9 +143,25 @@ buildchain collect github-release \
   --dist-tag-evidence-json .buildchain/release-evidence/v2.2.0/dist-tag-evidence.json \
   --kfd-1-witness-json .buildchain/kfd/kfd-1/contract-world.witness.json \
   --kfd-2-claim-json .buildchain/kfd/kfd-2/release-claims.json \
+  --invariant-passport-json product/release/qualification/invariant-passport.json \
   --output-dir .buildchain/release-passport
 ```
 
+For a promotion workflow, consumers can instead use
+`release-passport-invariant-passport-command`. The command must emit exactly one
+canonical JSON object on stdout; for example:
+
+```yaml
+release-passport-invariant-passport-command: >-
+  node scripts/kungfu-invariant.mjs --collect-evidence .
+  --passport product/release/qualification/invariant-passport.json --json
+```
+
+Supplying the input makes the invariant gate mandatory. Command failure,
+missing output, semantic-root drift, a non-`verified` verdict, incomplete
+coverage, dirty source state, or a source revision unrelated to the release
+fails closed before release publication.
+
 `packageSet` records the ordered main-plus-platform package set.
 `publish.packages[]` summarizes each published npm package with its version,
 dist-tag, registry, role, platform, and digest, so agents do not need to stitch

package/docs/versioning.md

@@ -61,6 +61,7 @@ repository changes are patch".
 
 | Date | Action | Line | Faces | Class | Rationale | PR |
 | --- | --- | --- | --- | --- | --- | --- |
+| 2026-07-20 | extend-minor | `v2.14` | anchored-derived-version-material, build-controller-evidence, release-passport, package-subpaths, release-propagation-controller | additive | Anchored/manual consumers can declare derived version witnesses that Buildchain regenerates and verifies before heavy builds, binds to exact alpha/release trees and passports, and admits during protected promotion; propagation receipts now model their existing optional consumer stages. | |
 | 2026-07-17 | extend-minor | `v2.14` | merge-queue-config, release-line-governance-inheritance | additive | Buildchain config can explicitly enable, inherit, or disable exact dev-channel merge queues, and release-line bootstrap reconciles the declared or inherited policy before moving the repository default branch. | |
 | 2026-07-16 | open-minor | `v2.14` | dev-merge-queue-governance | additive | The public CLI adds a dry-run-first, idempotent merge-queue governance command that verifies required workflow event compatibility before applying an exact dev-channel ruleset and removing the strict up-to-date race. | |
 | 2026-07-15 | open-minor | `v2.13` | artifact-verification-envelope, package-subpaths | additive | The public envelope seals exact artifact, provenance, identity, lifecycle, revocation, and existing KFD assessment roots into one consumer-ready KFX admission input, with a dedicated Node API export and fail-closed verifier. | |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.14.3",
+  "version": "2.14.4-alpha.1",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -17,6 +17,7 @@
     "./core": "./packages/core/index.js",
     "./artifact-passport": "./packages/core/artifact-passport.js",
     "./artifact-verification-envelope": "./packages/core/artifact-verification-envelope.js",
+    "./anchored-version-material": "./packages/core/anchored-version-material.js",
     "./buildchain-contract": "./packages/core/buildchain-contract.js",
     "./controller-evidence": "./packages/core/controller-evidence.js",
     "./diagnostics": "./packages/core/diagnostics.js",

package/packages/core/README.md

@@ -16,6 +16,8 @@ Current shared surfaces:
   `@kungfu-tech/buildchain/build-facts`;
 - release passport creation and verification through
   `@kungfu-tech/buildchain/release-passport`.
+- anchored/manual derived witness preflight and exact-tree evidence through
+  `@kungfu-tech/buildchain/anchored-version-material`.
 - sealed exact-root and KFD assessment inputs for KFX admission through
   `@kungfu-tech/buildchain/artifact-verification-envelope`.
 - managed KFD / Release Passport badge bundle facts and README marker blocks