@kungfu-tech/buildchain 2.8.0 → 2.8.1

package/docs/release-passport.md

@@ -98,6 +98,7 @@ buildchain collect github-release \
   --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 \
+  --kfd-2-claim-json .buildchain/kfd-2/release-claims.json \
   --output-dir .buildchain/release-passport
 ```
 
@@ -120,6 +121,12 @@ the Kungfu SDK. The authority chain is:
 3. Consumers only pass declarative witness JSON plus the artifact payloads their
    build already produced.
 
+This gives agents a concrete answer to "what changed and can I trust it?" A
+release can include both normal release passport evidence and KFD-1 evidence:
+the passport proves the release transaction and artifacts are complete, while
+KFD-1 proves selected contract-world surfaces inside those artifacts are the
+byte-for-byte surfaces the release intended to ship.
+
 The witness JSON names the contract world, the canonical serialization policy,
 and the release surfaces that must be byte-for-byte verified:
 
@@ -156,6 +163,125 @@ 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.
 
+For the KFD repository itself, the KFD-1 witness can be a self-hosted standard
+contract witness. In that mode KFD owns the standard-contract facts and
+Buildchain verifies declared source standard metadata, schemas, package
+exports, and site-consumption entrypoints against the packaged artifact. The
+passport records source and artifact hash summaries, schema ids, the
+self-hosting boundary, result, residual risk, and responsibility state for
+source ownership, artifact verification, and release-passport proof ownership.
+
+Good KFD-1 witnesses should point at release payload surfaces, not at private
+build-machine state. For Buildchain itself, the natural witness set is the
+release passport schema and implementation, KFD-1 gate implementation,
+`dist/site/buildchain-contract.json`, and the npm package payload files that
+expose the public CLI, reusable workflow/action contracts, and site facts.
+The final `buildchain.release.json` file should not be used as an ordinary
+byte-for-byte KFD surface because it contains KFD evidence; instead, the
+passport is audited through release-state SHA, `check-report.json`, and the
+contract files that generate and verify it.
+
+### KFD-2 release trust passport audit
+
+Buildchain can write a KFD-2 release trust passport audit under the top-level
+`kfd-2` section. The section is generated automatically from KFD-1 and KFD-3
+release-gate evidence, and callers may add explicit public release claims with
+`--kfd-2-claim-json`.
+
+Every public claim must bind:
+
+- declared sources;
+- machine-readable evidence;
+- source/evidence/artifact hashes;
+- artifact coordinates;
+- verification results;
+- audit boundary;
+- responsibility state;
+- residual risk, even when the array is empty.
+
+Unbound public claims fail release passport verification. Claims that are
+machine-bound but only supported by prose downgrade the KFD-2 audit and produce
+a warning, so agents can distinguish "verified", "needs review", and "not
+bound to evidence" without reading release notes.
+
+### KFD-3 collaboration-interface release gate
+
+KFD-3 asks a different release question than KFD-1. KFD-1 proves that named
+payload bytes match one contract world. KFD-3 proves that a product's shipped
+participant-facing collaboration/control surface is closed over its declared
+interface.
+
+The product remains the fact source. Before build/publish, the product writes a
+pre-build witness:
+
+```bash
+kungfu sdk collaboration-interface witness --json \
+  > .buildchain/kfd-3/collaboration-interface.prebuild.json
+```
+
+That witness must contain, or point to, the product-owned KFD-3 collaboration
+interface, registry digest, participants, and declared public shipped surfaces.
+KFD repository self-verification can declare the same facts as grouped machine
+surfaces: docs, schemas, standards metadata, package exports, and
+site-consumption contracts.
+After the artifact is built, the product also provides artifact-side evidence,
+either as a JSON file or a command:
+
+```bash
+buildchain collect github-release \
+  --kfd-3-prebuild-witness-json .buildchain/kfd-3/collaboration-interface.prebuild.json \
+  --kfd-3-artifact-verify-cmd "kungfu agent verify --json"
+```
+
+Buildchain imports the KFD-3 metadata from `@kungfu-tech/kfd`, freezes the
+pre-build witness digest, ingests the artifact witness, and compares the two
+sets:
+
+- every declared `shipped` public participant-facing surface must appear in the
+  artifact witness;
+- every artifact-exposed public participant-facing surface must be declared by
+  the pre-build witness;
+- if both witnesses record `collaborationInterface.digest`, the digests must
+  match;
+- contradictory, missing, stale, or schema-incomplete evidence fails closed.
+
+The generated release passport records the result under the KFD-provided
+top-level key currently named `kfd-3`. The section includes the KFD package
+version, schema ids/paths, pre-build witness digest, artifact witness digest,
+declared/exposed surface counts, missing declared shipped surfaces, and
+unclassified artifact public surfaces. It also records the KFD-2 trust proof
+view of that evidence: `releaseStatus`, witness file hashes and canonical
+hashes, declared capability verification, reverse audit boundary, residual
+risk, and responsibility state.
+
+The trust proof makes the strongest claim only when the witnesses justify it:
+`No unclassified reachable surface within the declared audit boundary.` If the
+product declares non-exhaustive surfaces, Buildchain keeps the passport
+verifiable but marks the interface `audited` instead of `enforced` and records
+the residual risk explicitly. Draft or partial KFD-3 declarations are
+downgraded; missing declared capabilities, undeclared public artifact surfaces,
+or stale collaboration-interface digests fail the proof.
+
+This makes KFD-3 support usable by readers and agents immediately: they can
+inspect `buildchain.release.json` and know whether the released package
+actually exposes no more and no less than the declared collaboration interface,
+instead of trusting docs or release notes.
+
+### Floating Buildchain contract lock
+
+KFD-1 protects release payload surfaces. Floating ref contract locks protect the
+consumer's relationship to Buildchain itself. A consumer can keep
+`buildchain.contract-lock.json` with the Buildchain floating ref it accepted,
+the resolved SHA, the contract digest, and the compatibility policy. Each
+Buildchain run reads the actual contract from the checked-out Buildchain ref
+and compares it before heavy build or publish work begins.
+
+Compatible drift, such as optional inputs or extra diagnostics, continues and
+creates a consumer-local issue for review. Breaking drift fails fast. This means
+consumers can use `@v2` without silently accepting incompatible changes, while
+Buildchain maintainers can still ship compatible improvements under the same
+major floating tag.
+
 `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/reusable-build-surface.md

@@ -164,6 +164,56 @@ the outer reusable workflow YAML itself to change, such as new jobs,
 permissions, workflow outputs, or matrix topology. Those changes need a canary
 workflow path or a temporary explicit workflow ref.
 
+## Floating Ref Contract Lock
+
+Stable consumers should use floating major refs such as `@v2`, but a floating
+ref is not blind trust. Each released Buildchain ref carries a package-owned
+runtime contract world in `dist/site/buildchain-contract.json`. Consumers may
+keep a small lock file, `buildchain.contract-lock.json`, recording the
+Buildchain ref, resolved SHA, contract digest, compatibility digest, accepted
+major line, and compatibility policy they reviewed.
+
+The reusable build trust gate checks this lock before any heavy matrix job:
+
+1. resolve the Buildchain runtime ref, for example `v2`, to an immutable SHA;
+2. read `dist/site/buildchain-contract.json` from that checked-out Buildchain
+   ref;
+3. read the consumer's `buildchain.contract-lock.json`;
+4. compare the accepted contract with the current contract.
+
+SHA drift alone is not a failure. `v2` is expected to advance. Buildchain only
+fails fast when the accepted contract is no longer compatible, for example a
+required input is removed, a required output disappears, a protected behavior
+promise changes, or the major line changes. Additive changes such as optional
+inputs, optional outputs, diagnostics, or documentation updates continue under
+the default `major-compatible` policy.
+
+```yaml
+jobs:
+  build:
+    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v2
+    permissions:
+      contents: read
+      issues: write
+      id-token: write
+    with:
+      buildchain-contract-lock-path: buildchain.contract-lock.json
+      buildchain-contract-compatibility-policy: major-compatible
+      buildchain-contract-drift-issue-mode: compatible-and-breaking
+```
+
+When compatible drift is detected, the build continues and Buildchain opens or
+updates a low-priority issue in the consumer repository. The issue records the
+old SHA/digest, new SHA/digest, compatibility result, workflow run, and the next
+action: review the Buildchain release notes and update the lock. When breaking
+drift is detected, the same issue path is used, but the trust gate fails before
+matrix build or publish work starts. If the workflow token cannot write issues,
+Buildchain writes a copyable issue body into the job summary.
+
+The lock is intentionally small. It does not copy the full contract. The full
+contract remains in the Buildchain ref and package; the consumer records only
+what it accepted and the policy used to compare future floating-ref movement.
+
 When a Buildchain maintainer asks for downstream validation, the expected
 request is:
 
@@ -201,6 +251,9 @@ The reusable workflow exposes the resolved contract:
 | `buildchain-runtime-class`        | `stable`, `alpha`, `train`, `exact-sha`, or `development`                       |
 | `buildchain-runtime-override`     | `true` when a non-empty `buildchain-ref` override was accepted                  |
 | `buildchain-runtime-trust-decision` | Runtime override trust decision                                               |
+| `buildchain-contract-lock-status` | `unchanged`, `compatible-drift`, `breaking-drift`, `missing-lock`, `non-floating-runtime`, or first-release `runtime-contract-unavailable` |
+| `buildchain-contract-lock-drift`  | `true` when the floating runtime SHA or contract digest changed                 |
+| `buildchain-contract-digest`      | Current Buildchain runtime contract digest                                      |
 | `publish-channel`                 | Resolved publish channel requested by the caller                                |
 | `publish-allowed`                 | `true` only when this event/ref may publish after verification                  |
 | `publish-reason`                  | Human-readable reason for the publish gate decision                             |
@@ -453,9 +506,13 @@ payload artifacts from the same PR-stage run, validates the payload count,
 compares the built tree with the promotion channel tree, locks
 `publish-gate/{alpha,release,major}` to the promotion channel commit, and then
 calls `actions/promote-buildchain-ref` with
-`promote-only-release-candidate: "true"`. It does not call `.build.yml`, does
-not create a matrix, and must fail before publish if the RC evidence or payload
-set is missing or ambiguous.
+`promote-only-release-candidate: "true"` and
+`require-publish-source-lock: "true"`. The wrapper passes the created
+`publish-gate/*` ref, target SHA, and `locked=true` into the promote action, so
+floating `@v2` consumers receive publish-side source-lock drift protection by
+default. It does not call `.build.yml`, does not create a matrix, and must fail
+before publish if the RC evidence, payload set, or source-lock ref is missing or
+ambiguous.
 
 ```yaml
 jobs:
@@ -476,12 +533,15 @@ jobs:
       publish-target: npm
       runner-preset: github-hosted
       trusted-publishing: true
+      github-release: true
       required-status-check: check
       required-artifact-count: 3
       publish-dist-tag: alpha
       publish-package-set-order: platforms-first-main-last
       publish-package-main: "@kungfu-tech/libnode"
       release-passport-product-name: Libnode
+      buildchain-contract-lock-path: buildchain.contract-lock.json
+      buildchain-contract-drift-issue-mode: compatible-and-breaking
 ```
 
 `buildchain-issue-app-id` and `buildchain-issue-app-private-key` are optional
@@ -505,6 +565,22 @@ main`, marks the rest as `role: platform`, and passes the generated
 `publish-required-artifacts-json` to `promote-buildchain-ref` before any publish
 side effect. Downloaded platform manifests are still passed into the release
 passport unless `release-passport-platform-manifest-paths` is set explicitly.
+The same Buildchain contract lock check runs before release-candidate
+resolution and before publish. A compatible `v2` drift leaves an issue in the
+consumer repository but does not trigger a second heavy build; an incompatible
+drift fails before publish side effects.
+
+Set `github-release: true` when the promoted exact tag should also publish a
+GitHub Release. After `promote-buildchain-ref` reports a complete release
+transaction, the wrapper creates or updates the exact-tag release, marks semver
+prerelease tags such as `v1.2.3-alpha.0`, `v1.2.3-rc.1`, or
+`v22.22.3-kf.3-alpha.7` as `prerelease=true` and `make_latest=false`, marks
+stable semver tags as latest, and uploads the publish evidence file plus every
+file in the generated release passport directory, including
+`buildchain.release.json` and `check-report.json`. Consumers do not need to
+hand-write `gh release` logic to trigger `release.published` propagation.
+If the transaction still needs protected-ref finalization, the wrapper defers
+GitHub Release creation until the later run that reaches `state=complete`.
 
 Custom publish jobs can also repeat the channel-ref preflight:
 

package/docs/site-bundle-contract.md

@@ -17,12 +17,17 @@ dist/site/
   workflow-registry.json
   release-model.json
   artifact-schemas.json
+  buildchain-contract.json
   product-mechanism.json
   release-provenance.json
   agent-index.json
 ```
 
 `buildchain-site.json` is the top-level bundle entrypoint.
+`buildchain-contract.json` is the machine-readable Buildchain runtime contract
+world used by floating-ref contract locks. It records public workflow/action/CLI
+surfaces, compatibility digests, and audit digests for the files that implement
+those surfaces.
 
 ## npm Consumption
 
@@ -61,6 +66,7 @@ The P0 bundle includes:
 - workflow/action registry;
 - release model facts;
 - artifact and evidence schema index;
+- Buildchain runtime contract world for `@v2` floating-ref compatibility checks;
 - product mechanism manifest;
 - release provenance;
 - agent read order.

package/docs/versioning.md

@@ -61,7 +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-06 | open-minor | `v2.8` | kfd-1-contract-world-release-gate, kfd-2-release-trust-passport-audit, kfd-3-collaboration-interface-trust-proof, publish-source-lock-enforcement, required-check-protection | additive | KFD release gates add KFD-1 self contract verification, KFD-2 public release trust claim audit, KFD-3 collaboration-interface trust proofs, publish-side source-lock enforcement for promote-only wrappers, and protected channel required checks 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.8.0",
+  "version": "2.8.1",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -14,6 +14,7 @@
     ".": "./packages/core/index.js",
     "./core": "./packages/core/index.js",
     "./artifact-passport": "./packages/core/artifact-passport.js",
+    "./buildchain-contract": "./packages/core/buildchain-contract.js",
     "./diagnostics": "./packages/core/diagnostics.js",
     "./issue-reporting": "./packages/core/issue-reporting.js",
     "./logging": "./packages/core/logging.js",
@@ -27,6 +28,7 @@
     "./site/workflow-registry.json": "./dist/site/workflow-registry.json",
     "./site/release-model.json": "./dist/site/release-model.json",
     "./site/artifact-schemas.json": "./dist/site/artifact-schemas.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",
     "./site/agent-index.json": "./dist/site/agent-index.json",
@@ -92,7 +94,7 @@
     "vitest": "^4.1.9"
   },
   "dependencies": {
-    "@kungfu-tech/kfd": "1.0.0-alpha.2",
+    "@kungfu-tech/kfd": "1.0.0-alpha.3",
     "smol-toml": "1.7.0"
   }
 }