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

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

@@ -3,11 +3,11 @@
   "contract": "kungfu-buildchain-public-surface-reverse-audit",
   "status": "passed",
   "summary": {
-    "cliCommandCount": 79,
+    "cliCommandCount": 81,
     "workflowCount": 47,
     "actionCount": 4,
-    "sitePageCount": 49,
-    "docCommandRefCount": 246,
+    "sitePageCount": 50,
+    "docCommandRefCount": 250,
     "failureCount": 0
   },
   "enumerated": {
@@ -302,6 +302,11 @@
         "source": "bin/buildchain.mjs",
         "usage": "buildchain npm dry-run [--cwd <dir>] [--expected-tag <tag>] [--registry <url>]"
       },
+      {
+        "id": "project",
+        "source": "bin/buildchain.mjs",
+        "usage": "buildchain project kfx-admission <file-or-json> [--assessment-time <epoch>]"
+      },
       {
         "id": "publication-artifact",
         "source": "bin/buildchain.mjs",
@@ -377,6 +382,11 @@
         "source": "bin/buildchain.mjs",
         "usage": "buildchain verify artifact <file|dir|url|npm:...|oci:...|github-release:...>"
       },
+      {
+        "id": "verify-artifact-envelope",
+        "source": "bin/buildchain.mjs",
+        "usage": "buildchain verify artifact-envelope <file-or-json> [--assessment-time <epoch>]"
+      },
       {
         "id": "verify-infra-contract-evidence-bundle",
         "source": "bin/buildchain.mjs",
@@ -464,6 +474,7 @@
           "expected-artifacts-json",
           "gate-profile-aggregate-json",
           "install-command",
+          "lifecycle-timeout-minutes",
           "linux-container-image",
           "linux-container-preset",
           "node-version",
@@ -494,7 +505,7 @@
           "verify-command",
           "working-directory"
         ],
-        "inputCount": 58,
+        "inputCount": 59,
         "secrets": [
           "BUILDCHAIN_ARTIFACT_RELAY_S3_DOWNLOAD_ROLE_ARN",
           "BUILDCHAIN_ARTIFACT_RELAY_S3_ROLE_ARN",
@@ -1066,6 +1077,7 @@
           "expected-artifacts-json",
           "gate-profile-aggregate-json",
           "install-command",
+          "lifecycle-timeout-minutes",
           "linux-container-image",
           "linux-container-preset",
           "node-version",
@@ -1096,7 +1108,7 @@
           "verify-command",
           "working-directory"
         ],
-        "inputCount": 61,
+        "inputCount": 62,
         "secrets": [
           "BUILDCHAIN_ARTIFACT_RELAY_S3_DOWNLOAD_ROLE_ARN",
           "BUILDCHAIN_ARTIFACT_RELAY_S3_ROLE_ARN",
@@ -1940,9 +1952,10 @@
           "required",
           "sample-process-tree",
           "stage",
-          "summary-path"
+          "summary-path",
+          "timeout-minutes"
         ],
-        "inputCount": 20
+        "inputCount": 21
       },
       {
         "id": "validate-config",
@@ -2024,6 +2037,10 @@
         "id": "fixture:web-surface-shaped",
         "category": "fixture"
       },
+      {
+        "id": "manual:artifact-verification-envelope",
+        "category": "manual"
+      },
       {
         "id": "manual:binary-distribution",
         "category": "manual"
@@ -3059,6 +3076,16 @@
         "path": "docs/cli.md",
         "command": "buildchain npm dry-run"
       },
+      {
+        "id": "project",
+        "path": "docs/artifact-verification-envelope.md",
+        "command": "buildchain project kfx-admission envelope"
+      },
+      {
+        "id": "project",
+        "path": "docs/cli.md",
+        "command": "buildchain project kfx-admission envelope"
+      },
       {
         "id": "publication-artifact-manifest",
         "path": "docs/cli.md",
@@ -3269,6 +3296,16 @@
         "path": "README.md",
         "command": "buildchain validate --require-version-state npx"
       },
+      {
+        "id": "verify-artifact-envelope",
+        "path": "docs/artifact-verification-envelope.md",
+        "command": "buildchain verify artifact-envelope envelope"
+      },
+      {
+        "id": "verify-artifact-envelope",
+        "path": "docs/cli.md",
+        "command": "buildchain verify artifact-envelope envelope"
+      },
       {
         "id": "verify-artifact",
         "path": "docs/cli.md",
@@ -3390,9 +3427,9 @@
     "cliRegistryPath": "dist/site/cli-registry.json",
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
-    "cliRegistryDigest": "a6daf4822365bf576425777230246046ebca67b3f8dcfea61fc7a61773776185",
-    "workflowRegistryDigest": "f7906cff65097a4dc0a7e3eb8a13a52415fadae6b6d019646a52867d94903998",
-    "pageRegistryDigest": "18046faf40798c07c6056d61beae2c1eda19d51e1545aa245f3c18692d18b9a0"
+    "cliRegistryDigest": "ff1772371ec74271c21b6723dad0745a080347be8feef36a37e3948ebd19993d",
+    "workflowRegistryDigest": "c496f3c91b98409ecadf252ac087e620bb95c02222690ec4543013d0740190d1",
+    "pageRegistryDigest": "246e694c72df3166277b128d60bf18bf58c15583d0b70f5652dd4f342510fcdc"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-07-16T01:31:41.801Z",
-  "publishedAt": "2026-07-16T01:31:41.801Z",
+  "generatedAt": "2026-07-15T16:38:35.118Z",
+  "publishedAt": "2026-07-15T16:38:35.118Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "6ad6f3a62b05b6713d1345285ee9442bf4faa894",
+  "sourceRevision": "aa454f78402e4e89a05592f8714e2d0f55f10c86",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.12.9-alpha.0",
+    "version": "2.13.0-alpha.0",
     "versionSource": "package.json#version"
   },
   "sourceKind": "package-site-bundle",

package/dist/site/release-provenance.json

@@ -13,6 +13,7 @@
       "./build-facts": "./packages/core/build-facts.js",
       "./core": "./packages/core/index.js",
       "./artifact-passport": "./packages/core/artifact-passport.js",
+      "./artifact-verification-envelope": "./packages/core/artifact-verification-envelope.js",
       "./buildchain-contract": "./packages/core/buildchain-contract.js",
       "./controller-evidence": "./packages/core/controller-evidence.js",
       "./diagnostics": "./packages/core/diagnostics.js",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-16T01:31:41.801Z",
-  "publishedAt": "2026-07-16T01:31:41.801Z",
+  "generatedAt": "2026-07-15T16:38:35.118Z",
+  "publishedAt": "2026-07-15T16:38:35.118Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "6ad6f3a62b05b6713d1345285ee9442bf4faa894",
+  "sourceRevision": "aa454f78402e4e89a05592f8714e2d0f55f10c86",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.12.9-alpha.0",
+    "version": "2.13.0-alpha.0",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -53,7 +53,7 @@
       "path": "docs/MAP.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:91dc800bafc31bc149680c86272827936c94e0f025d547bbabc10d58fe5f128e"
+      "digest": "sha256:ce439062d4ed9d8213499e607825afdcf8a65f825343a657d0438f3e229a0af0"
     },
     {
       "id": "install",
@@ -93,7 +93,7 @@
       "path": "docs/release-candidate.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:6a20c6e3e483327d5ccbe70271f7fb4752731bd0523eeddb96f27b2b6ebf1cf8"
+      "digest": "sha256:554613c963f57cc391acbd072bf73e1a2543d9bd1371087d4411577cccbf817c"
     },
     {
       "id": "release-propagation",
@@ -101,7 +101,7 @@
       "path": "docs/release-propagation.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:c8085445fcd0ffd6a55197ac2db1e34fa4aaa94df9107e8e7b216b925fc3bddc"
+      "digest": "sha256:55895694a32b76dfaf5ed0eb9e32f1e10bd859fb590d6f4504d36692ebe61ea9"
     },
     {
       "id": "readme-badges",
@@ -189,7 +189,7 @@
       "path": "docs/cli.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:3b3ac97c353f7549229f1102cca38236e734ec8d08c219d4a6e5ef2a48fc0e16"
+      "digest": "sha256:ef5be4484da8628b9e027f00fe0fdb5b295665ed23eeceefac48e63581f12c0c"
     },
     {
       "id": "build-facts",
@@ -221,7 +221,7 @@
       "path": "docs/reusable-build-surface.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:6916d88ae0f25fa129308354b04d339552b72796d4d7d7938015e0e2f4dcaa6a"
+      "digest": "sha256:a2092c8064332cec9a4be852b24d94f90625cb45f885c4c3208f7068a643a3f0"
     },
     {
       "id": "publish-transaction",
@@ -237,7 +237,7 @@
       "path": "docs/release-governance.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:cce9f80add3c746fe28d8ebf5afb809348694741cb75d19154ed3057a9374c0d"
+      "digest": "sha256:03108f05a608cb0849e7a668fe23671b62863907ce02a70bc6522eb8074f3e63"
     },
     {
       "id": "release-flow",
@@ -261,7 +261,7 @@
       "path": "docs/versioning.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:400027d5e34d5c22752f7664bb9ca9ce99c04e7be298183d0303f3fb04fa7747"
+      "digest": "sha256:280d30e15552ab6a362cb121a7a1cafc3b907913cdc7d4d8a9e8e1930d856f7e"
     },
     {
       "id": "web-surface-deployments",

package/dist/site/workflow-registry.json

@@ -61,6 +61,7 @@
         "expected-artifacts-json",
         "gate-profile-aggregate-json",
         "install-command",
+        "lifecycle-timeout-minutes",
         "linux-container-image",
         "linux-container-preset",
         "node-version",
@@ -91,7 +92,7 @@
         "verify-command",
         "working-directory"
       ],
-      "inputCount": 58,
+      "inputCount": 59,
       "secrets": [
         "BUILDCHAIN_ARTIFACT_RELAY_S3_DOWNLOAD_ROLE_ARN",
         "BUILDCHAIN_ARTIFACT_RELAY_S3_ROLE_ARN",
@@ -717,6 +718,7 @@
         "expected-artifacts-json",
         "gate-profile-aggregate-json",
         "install-command",
+        "lifecycle-timeout-minutes",
         "linux-container-image",
         "linux-container-preset",
         "node-version",
@@ -747,7 +749,7 @@
         "verify-command",
         "working-directory"
       ],
-      "inputCount": 61,
+      "inputCount": 62,
       "secrets": [
         "BUILDCHAIN_ARTIFACT_RELAY_S3_DOWNLOAD_ROLE_ARN",
         "BUILDCHAIN_ARTIFACT_RELAY_S3_ROLE_ARN",
@@ -1680,9 +1682,10 @@
         "required",
         "sample-process-tree",
         "stage",
-        "summary-path"
+        "summary-path",
+        "timeout-minutes"
       ],
-      "inputCount": 20,
+      "inputCount": 21,
       "capabilityGroup": "reusable-build",
       "status": "active"
     },

package/docs/MAP.md

@@ -81,6 +81,7 @@ replace them.
 | How does publish evidence, recovery, and finalization work? | [`publish-transaction.md`](publish-transaction.md) | verify | stable |
 | How do I collect and verify module/product build facts from Git source, version files, and outputs? | [`build-facts.md`](build-facts.md) + [`cli.md`](cli.md) | use/verify | stable |
 | How do I publish or verify release passport artifacts? | [`release-passport.md`](release-passport.md) | use | stable |
+| How do I seal exact artifact, identity, lifecycle, and KFD assessment roots for KFX admission? | [`artifact-verification-envelope.md`](artifact-verification-envelope.md) | verify/use | preview |
 | How is product publication authority sealed to an exact workflow, runner, control plane, nonce, and artifact? | [`publication-authority.md`](publication-authority.md) | verify | preview |
 | 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 declare, render, and audit product KFD-2 release trust claims? | [`kfd-support.md`](kfd-support.md#kfd-2) + [`release-passport.md`](release-passport.md#kfd-2-release-trust-passport-audit) + [`cli.md`](cli.md) | verify/use | stable |

package/docs/artifact-verification-envelope.md

@@ -0,0 +1,113 @@
+# Artifact Verification Envelope
+
+Buildchain can turn a passing exact-artifact passport verification into one
+sealed, versioned input for Kungfu KFX admission. The envelope carries the
+public verification result together with exact package, source, dependency,
+build-plan, toolchain, artifact, qualification, and verifier roots; issuer and
+publisher identity; lifecycle and revocation facts; and an existing ADR-0052
+KFD assessment.
+
+The envelope does not create a second KFD evaluator. It validates and binds an
+assessment produced by the Kungfu KFD lifecycle. It also does not claim that an
+artifact is malware-free, universally safe, fit for every workspace, or
+authorized as a Product System component.
+
+## Public API
+
+Import the dedicated package subpath:
+
+```js
+import {
+  projectArtifactVerificationEnvelopeToKfx,
+  sealArtifactVerificationReport,
+  verifyArtifactVerificationEnvelope,
+} from "@kungfu-tech/buildchain/artifact-verification-envelope";
+```
+
+`verifyArtifactPassport` also accepts an optional `verificationEnvelope`
+object. Existing callers that omit it receive the unchanged
+`kungfu-buildchain-artifact-verification` v1 result.
+
+```js
+const attestation = await verifyArtifactPassport({
+  subject: "dist/example.kfx",
+  passportLocation: "dist/buildchain.release.json",
+  verificationEnvelope: {
+    bindings,
+    kfdAssessment,
+    issuedAt,
+    expiresAt,
+    revocation,
+  },
+});
+```
+
+The result keeps the artifact-verification v1 fields that existing consumers
+understand and adds:
+
+- `bindings`: the schema-closed `kungfu.kfx-trust-inputs/v1` exact roots and
+  identities;
+- `issuedAt`, `expiresAt`, `revoked`, and a root-bound `revocation` fact;
+- `kfdAssessment`: the pinned fresh `kungfu.trust.assessment/v1` lifecycle
+  result;
+- `envelope`: the envelope contract, canonicalization version, and exact
+  content root.
+
+`projectArtifactVerificationEnvelopeToKfx` returns the same sealed report as
+`attestation`, its exact `bindings` as `trustInputs`, and its existing
+`kfdAssessment`. A consumer does not reconstruct fields, recompute the KFD
+decision, or inspect private Buildchain structures.
+
+The read-only CLI uses those same functions for portable verification and
+projection:
+
+```bash
+buildchain verify artifact-envelope envelope.json \
+  --assessment-time 150 \
+  --expected-root sha256:... \
+  --expected-issuer buildchain.libkungfu.dev \
+  --expected-publisher kungfu-systems \
+  --expected-contract buildchain.release/v1 \
+  --json
+
+buildchain project kfx-admission envelope.json \
+  --assessment-time 150 \
+  --json
+```
+
+The projection's `envelopeRoot` is the same root returned by the Node verifier.
+The CLI never adds consumer-side bindings or KFD conclusions.
+
+## Canonicalization and roots
+
+The v1 envelope uses `buildchain-stable-json/v1`: object keys are sorted
+recursively, array order is retained, and the root is lowercase SHA-256 with a
+`sha256:` prefix. `envelope.root` is excluded from its own root basis.
+
+The KFD report hash is independently recomputed over the report with
+`report_hash` removed. The envelope is accepted only when:
+
+- the base artifact passport verification passes;
+- `bindings.artifactRoot` equals both the exact subject digest and the matched
+  passport artifact digest;
+- every binding root is canonical lowercase SHA-256;
+- `bindings.qualificationRoot` equals the recomputed KFD `report_hash`;
+- the assessment key matches the report and its lifecycle state is `fresh`;
+- the report binds purpose, query proof, contract world, policy, and at least
+  one fact-surface root;
+- lifecycle bounds are active and revocation facts are internally consistent;
+- any caller-pinned envelope root, issuer, publisher, or contract version
+  matches exactly.
+
+## Fail-closed behavior
+
+`verifyArtifactVerificationEnvelope` returns a machine-readable check report.
+It rejects sibling artifacts, root tampering, identity drift, invalid contract
+versions, expired or revoked envelopes, stale assessments, altered KFD report
+content, and missing fact-surface bindings. Callers may pin expected authority
+fields without changing the envelope.
+
+The canonical root detects changed serialized content; authenticity still
+depends on the pinned Buildchain verifier and release passport authority. The
+envelope is supply-chain and evidence input. Kungfu Product and Workspace
+policy retain operation, capability, and System-role authority.

package/docs/cli.md

@@ -674,6 +674,28 @@ files, directories, and URLs are digestable directly; remote package, OCI,
 object storage, and deployment subjects should provide a digest or resolve to a
 locator that records one.
 
+Seal an exact artifact verification with the Node API, then verify or project
+the resulting KFX admission envelope without reconstructing its roots:
+
+```bash
+buildchain verify artifact-envelope envelope.json \
+  --assessment-time 150 \
+  --expected-root sha256:... \
+  --expected-issuer buildchain.libkungfu.dev \
+  --expected-publisher kungfu-systems \
+  --expected-contract buildchain.release/v1 \
+  --json
+
+buildchain project kfx-admission envelope.json \
+  --assessment-time 150 \
+  --json
+```
+
+Both commands call the public artifact-verification-envelope verifier. The
+projected `attestation`, `trustInputs`, and `kfdAssessment` are direct copies of
+the sealed envelope, and `envelopeRoot` stays identical across Node and CLI.
+See [`artifact-verification-envelope.md`](artifact-verification-envelope.md).
+
 Verify infra-contract lifecycle evidence bundles:
 
 ```bash

package/docs/release-candidate.md

@@ -82,6 +82,11 @@ other package as `role: platform`. Consumer workflows therefore stay
 declarative and do not need their own artifact download or publish-evidence
 generation scripts.
 
+Because a channel merge can trigger promotion before its PR-stage matrix has
+finished uploading evidence, the resolver waits up to ten minutes for the exact
+merged PR's successful workflow run and paired artifacts. Polling remains bound
+to the PR/head identity; timeout or a sibling run still fails closed.
+
 By default, the wrapper forwards GitHub Release publication to the underlying
 `promote-buildchain-ref` semver model. Once the release transaction is complete,
 the action creates or updates the public GitHub Release, applies

package/docs/release-governance.md

@@ -94,6 +94,13 @@ The implementation is intentionally stricter than a local release script:
   release source tree against that tested alpha tree;
 - generated version-state commits are verified before refs move.
 
+Exact publication planning installs the checked-out promotion source's declared
+dependencies before version-state verification. This keeps the pre-authority
+version plan on the same package-manager boundary as the later promotion job,
+including repositories whose verification commands import production packages.
+The planning pass may materialize and verify declared derived files locally,
+but dry-run never creates Git blobs, trees, commits, refs, or tags.
+
 Promotion intents are serialized globally per caller repository with
 `cancel-in-progress: false`. A queued intent re-reads its protected target ref
 before checkout, dependency installation, release-candidate resolution, or any

package/docs/release-propagation.md

@@ -194,6 +194,9 @@ 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.
 For unreleased runtime validation, keep the caller's reusable workflow reference
 on `@v2` and pass a temporary train ref through `buildchain-ref`.
 

package/docs/reusable-build-surface.md

@@ -903,6 +903,18 @@ with:
   verify-command: ctest --test-dir build --output-on-failure
 ```
 
+Every native and container matrix job is bounded by
+`lifecycle-timeout-minutes`, which defaults to 120 minutes. The same input is
+the fallback deadline for each install, build, and verify action, so a hung
+command fails with the lifecycle name and matrix platform before it can occupy
+a self-hosted runner indefinitely. A stage-level `timeout_minutes` in
+`buildchain.toml` remains the more specific override for that stage.
+
+```yaml
+with:
+  lifecycle-timeout-minutes: 90
+```
+
 The reusable build workflow samples the build lifecycle by default and carries
 the generated summary into the final verify diagnostics. Callers can override
 the sidecar path or disable sampling:
@@ -932,6 +944,7 @@ For custom workflows, use the action directly:
   with:
     stage: build
     required: "true"
+    timeout-minutes: "90"
     artifact-name: libnode-linux-x64-${{ github.sha }}
     artifact-paths: |
       dist

package/docs/versioning.md

@@ -61,6 +61,7 @@ repository changes are patch".
 
 | Date | Action | Line | Faces | Class | Rationale | PR |
 | --- | --- | --- | --- | --- | --- | --- |
+| 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. | |
 | 2026-07-11 | open-minor | `v2.12` | channel-build-router, channel-selection-protocol | additive | The public `build.yml` reusable workflow lets consumers declare one build job while Buildchain selects generic major alpha for development/prerelease intent and stable major for production release intent, with explicit overrides, separate locks, and fail-closed ambiguity handling. | |
 | 2026-07-08 | open-minor | `v2.9` | build-facts-contract | additive | Build Facts add a public CLI command family, Node API export, config protocol, module/product fact contracts, release-passport evidence section, and Kungfu legacy buildinfo projection from the same source facts. | |
 | 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. | |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.12.9-alpha.0",
+  "version": "2.13.0-alpha.0",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -16,6 +16,7 @@
     "./build-facts": "./packages/core/build-facts.js",
     "./core": "./packages/core/index.js",
     "./artifact-passport": "./packages/core/artifact-passport.js",
+    "./artifact-verification-envelope": "./packages/core/artifact-verification-envelope.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`.
+- 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
   through `@kungfu-tech/buildchain/badges`.
 - publication artifact manifests, source bundles, and publication artifact
@@ -66,6 +68,17 @@ const fact = collectModuleBuildFacts({ moduleId: "native-core" });
 writeBuildFacts({ fact, output: ".buildchain/facts/native-core.json" });
 ```
 
+KFX producers can seal one passing artifact verification with exact roots,
+identity, lifecycle, revocation, and an existing ADR-0052 assessment. Consumers
+verify or project the same envelope instead of reconstructing bindings:
+
+```js
+import {
+  projectArtifactVerificationEnvelopeToKfx,
+  verifyArtifactVerificationEnvelope,
+} from "@kungfu-tech/buildchain/artifact-verification-envelope";
+```
+
 Publication repositories can produce site-consumable paper/report facts without
 becoming web-surface repositories. When `[publication.archive]` is configured,
 the same API also maintains the append-only publication registry used by site

package/packages/core/artifact-passport.js

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import http from "node:http";
 import https from "node:https";
 import path from "node:path";
+import { sealArtifactVerificationReport } from "./artifact-verification-envelope.js";
 import { readJsonFromLocation, sha256File, verifyReleasePassport } from "./release-passport.js";
 
 export const ARTIFACT_VERIFICATION_CONTRACT = "kungfu-buildchain-artifact-verification";
@@ -708,6 +709,7 @@ export async function verifyArtifactPassport({
   subjectDigest = "",
   subjectKind = "",
   npmRegistryBaseUrl = "",
+  verificationEnvelope = undefined,
 } = {}) {
   const resolvedSubject = await resolveArtifactSubject(subject, { cwd, subjectDigest, subjectKind, npmRegistryBaseUrl });
   const issues = [];
@@ -789,7 +791,7 @@ export async function verifyArtifactPassport({
   }
   const ok = passportReport.ok && Boolean(match);
   const outcome = ok ? "pass" : "fail";
-  return {
+  const report = {
     schemaVersion: 1,
     contract: ARTIFACT_VERIFICATION_CONTRACT,
     outcome,
@@ -817,6 +819,9 @@ export async function verifyArtifactPassport({
       : undefined,
     issues,
   };
+  return verificationEnvelope
+    ? sealArtifactVerificationReport({ report, ...verificationEnvelope })
+    : report;
 }
 
 export async function explainArtifactPassport(options = {}) {