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

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",
@@ -615,6 +626,9 @@
           "auto-no-gate",
           "buildchain-ref",
           "buildchain-repository",
+          "consumer-predicate-digest",
+          "consumer-predicate-id",
+          "consumer-qualification-required",
           "control-plane-audit-json",
           "dry-run",
           "evidence-controller-artifact",
@@ -638,15 +652,17 @@
           "target-ref",
           "used-nonces-json"
         ],
-        "inputCount": 29,
+        "inputCount": 32,
         "secrets": [],
         "secretCount": 0,
         "outputs": [
           "capability-artifact",
           "capability-digest",
-          "capability-json"
+          "capability-json",
+          "gate-aggregate-digest",
+          "gate-aggregate-json"
         ],
-        "outputCount": 3
+        "outputCount": 5
       },
       {
         "id": ".release-docker",
@@ -1066,6 +1082,7 @@
           "expected-artifacts-json",
           "gate-profile-aggregate-json",
           "install-command",
+          "lifecycle-timeout-minutes",
           "linux-container-image",
           "linux-container-preset",
           "node-version",
@@ -1096,7 +1113,7 @@
           "verify-command",
           "working-directory"
         ],
-        "inputCount": 61,
+        "inputCount": 62,
         "secrets": [
           "BUILDCHAIN_ARTIFACT_RELAY_S3_DOWNLOAD_ROLE_ARN",
           "BUILDCHAIN_ARTIFACT_RELAY_S3_ROLE_ARN",
@@ -1603,6 +1620,8 @@
           "publication-admission-json",
           "publication-auto-admission",
           "publication-auto-no-gate",
+          "publication-consumer-predicate-id",
+          "publication-consumer-qualification-command",
           "publication-control-plane-audit-json",
           "publication-expected-json",
           "publication-gate-aggregate-json",
@@ -1612,6 +1631,7 @@
           "publication-runner-provenance-json",
           "publication-target",
           "publication-used-nonces-json",
+          "publication-used-qualification-nonces-json",
           "publish-artifact-kind",
           "publish-command",
           "publish-dist-tag",
@@ -1640,7 +1660,7 @@
           "target-sha",
           "trusted-publishing"
         ],
-        "inputCount": 56,
+        "inputCount": 59,
         "secrets": [
           "BUILDCHAIN_ISSUE_APP_ID",
           "BUILDCHAIN_ISSUE_APP_PRIVATE_KEY",
@@ -1823,6 +1843,10 @@
           "github-release-notes",
           "github-release-title",
           "promote-only-release-candidate",
+          "publication-capability-json",
+          "publication-gate-aggregate-json",
+          "publication-qualification-receipt-json",
+          "publication-used-qualification-nonces-json",
           "publish-auth",
           "publish-command",
           "publish-dist-tag",
@@ -1855,6 +1879,7 @@
           "release-passport-platform-manifest-paths",
           "release-passport-product-name",
           "require-governance",
+          "require-publication-qualification",
           "require-publish-source-lock",
           "require-version-state",
           "required-status-check",
@@ -1865,7 +1890,7 @@
           "transaction-state-path",
           "verification-command"
         ],
-        "inputCount": 54
+        "inputCount": 59
       },
       {
         "id": "report-buildchain-issue",
@@ -1940,9 +1965,10 @@
           "required",
           "sample-process-tree",
           "stage",
-          "summary-path"
+          "summary-path",
+          "timeout-minutes"
         ],
-        "inputCount": 20
+        "inputCount": 21
       },
       {
         "id": "validate-config",
@@ -2024,6 +2050,10 @@
         "id": "fixture:web-surface-shaped",
         "category": "fixture"
       },
+      {
+        "id": "manual:artifact-verification-envelope",
+        "category": "manual"
+      },
       {
         "id": "manual:binary-distribution",
         "category": "manual"
@@ -3059,6 +3089,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 +3309,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 +3440,9 @@
     "cliRegistryPath": "dist/site/cli-registry.json",
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
-    "cliRegistryDigest": "a6daf4822365bf576425777230246046ebca67b3f8dcfea61fc7a61773776185",
-    "workflowRegistryDigest": "f7906cff65097a4dc0a7e3eb8a13a52415fadae6b6d019646a52867d94903998",
-    "pageRegistryDigest": "9bc28515f1e756237c167e9343eed56f6c21823611bd91ebf411630ff4b7c9f3"
+    "cliRegistryDigest": "ff1772371ec74271c21b6723dad0745a080347be8feef36a37e3948ebd19993d",
+    "workflowRegistryDigest": "f4dc70cba95a30b79eadbffc3a4ba5f8d382aae220a7bc13965365c2bbd5e674",
+    "pageRegistryDigest": "f06ce732622727942f855a2e7e9639fb274722fb4bd2ca8e24fc677ffcdf7d5d"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-07-16T02:23:01.656Z",
-  "publishedAt": "2026-07-16T02:23:01.656Z",
+  "generatedAt": "2026-07-16T00:47:22.222Z",
+  "publishedAt": "2026-07-16T00:47:22.222Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "7ab8004aa2c6f99118710b81525f86d38615035b",
+  "sourceRevision": "b4ee7448f7de3f9dce8f390db06c26569d3ddefe",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.12.9-alpha.1",
+    "version": "2.13.0-alpha.1",
     "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-16T02:23:01.656Z",
-  "publishedAt": "2026-07-16T02:23:01.656Z",
+  "generatedAt": "2026-07-16T00:47:22.222Z",
+  "publishedAt": "2026-07-16T00:47:22.222Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "7ab8004aa2c6f99118710b81525f86d38615035b",
+  "sourceRevision": "b4ee7448f7de3f9dce8f390db06c26569d3ddefe",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.12.9-alpha.1",
+    "version": "2.13.0-alpha.1",
     "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",
@@ -61,7 +61,7 @@
       "path": "docs/install.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:1879849c01f82b8820f2d9aeb09faed0931954cb7fe6939176a5eb69110cee59"
+      "digest": "sha256:2600738a92b5853bc26d4e01211f0c07b8b36a21d4d72ca809bc6032dff5dc5f"
     },
     {
       "id": "release-passport",
@@ -85,7 +85,7 @@
       "path": "docs/publication-authority.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:05bc22c7e5885e591bc121fc43f588e5d49ccf0a8de6a642811c1d0d03dcee1e"
+      "digest": "sha256:920d4f14902ded1999f46d39f6d02db8cb5be6f22e376f6f2d456b3a1cc0c674"
     },
     {
       "id": "release-candidate",
@@ -93,7 +93,7 @@
       "path": "docs/release-candidate.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:6a20c6e3e483327d5ccbe70271f7fb4752731bd0523eeddb96f27b2b6ebf1cf8"
+      "digest": "sha256:1fc581cf1b4e4a202464c8d6671b3bff12d0b349760246a951e88ef524f99e6b"
     },
     {
       "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",
@@ -229,7 +229,7 @@
       "path": "docs/publish-transaction.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:9e77030dbd69e27c2402d855980f7560a465270cac1f3225c0470523ab4a8ddf"
+      "digest": "sha256:8d5d7075cf8b4280a4c5097726f5c51ae40db83e2652eafefe4fa5e487794f57"
     },
     {
       "id": "release-governance",
@@ -237,7 +237,7 @@
       "path": "docs/release-governance.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:d85ac78b7c73b85b0a59a4a39131230522ae65225fa1b52f9dfe6939f1bb839c"
+      "digest": "sha256:82160f0fd9e45f08dbfbaf8037e0895cbeecf251feca8bdaff607dcc030b3e28"
     },
     {
       "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",
@@ -221,6 +222,9 @@
         "auto-no-gate",
         "buildchain-ref",
         "buildchain-repository",
+        "consumer-predicate-digest",
+        "consumer-predicate-id",
+        "consumer-qualification-required",
         "control-plane-audit-json",
         "dry-run",
         "evidence-controller-artifact",
@@ -244,15 +248,17 @@
         "target-ref",
         "used-nonces-json"
       ],
-      "inputCount": 29,
+      "inputCount": 32,
       "secrets": [],
       "secretCount": 0,
       "outputs": [
         "capability-artifact",
         "capability-digest",
-        "capability-json"
+        "capability-json",
+        "gate-aggregate-digest",
+        "gate-aggregate-json"
       ],
-      "outputCount": 3,
+      "outputCount": 5,
       "surface": "reusable-workflow",
       "capabilityGroup": "api-cli-reference",
       "status": "active"
@@ -717,6 +723,7 @@
         "expected-artifacts-json",
         "gate-profile-aggregate-json",
         "install-command",
+        "lifecycle-timeout-minutes",
         "linux-container-image",
         "linux-container-preset",
         "node-version",
@@ -747,7 +754,7 @@
         "verify-command",
         "working-directory"
       ],
-      "inputCount": 61,
+      "inputCount": 62,
       "secrets": [
         "BUILDCHAIN_ARTIFACT_RELAY_S3_DOWNLOAD_ROLE_ARN",
         "BUILDCHAIN_ARTIFACT_RELAY_S3_ROLE_ARN",
@@ -1311,6 +1318,8 @@
         "publication-admission-json",
         "publication-auto-admission",
         "publication-auto-no-gate",
+        "publication-consumer-predicate-id",
+        "publication-consumer-qualification-command",
         "publication-control-plane-audit-json",
         "publication-expected-json",
         "publication-gate-aggregate-json",
@@ -1320,6 +1329,7 @@
         "publication-runner-provenance-json",
         "publication-target",
         "publication-used-nonces-json",
+        "publication-used-qualification-nonces-json",
         "publish-artifact-kind",
         "publish-command",
         "publish-dist-tag",
@@ -1348,7 +1358,7 @@
         "target-sha",
         "trusted-publishing"
       ],
-      "inputCount": 56,
+      "inputCount": 59,
       "secrets": [
         "BUILDCHAIN_ISSUE_APP_ID",
         "BUILDCHAIN_ISSUE_APP_PRIVATE_KEY",
@@ -1559,6 +1569,10 @@
         "github-release-notes",
         "github-release-title",
         "promote-only-release-candidate",
+        "publication-capability-json",
+        "publication-gate-aggregate-json",
+        "publication-qualification-receipt-json",
+        "publication-used-qualification-nonces-json",
         "publish-auth",
         "publish-command",
         "publish-dist-tag",
@@ -1591,6 +1605,7 @@
         "release-passport-platform-manifest-paths",
         "release-passport-product-name",
         "require-governance",
+        "require-publication-qualification",
         "require-publish-source-lock",
         "require-version-state",
         "required-status-check",
@@ -1601,7 +1616,7 @@
         "transaction-state-path",
         "verification-command"
       ],
-      "inputCount": 54,
+      "inputCount": 59,
       "capabilityGroup": "release-passport-trust",
       "status": "active"
     },
@@ -1680,9 +1695,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/install.md

@@ -51,9 +51,7 @@ npx buildchain version
 npx buildchain doctor --json
 ```
 
-The highest alpha minor publishes to the `alpha` npm dist-tag; older maintenance
-minor alphas use `vX.Y-alpha` so they cannot roll the global alpha channel back.
-Stable releases publish to
+Alpha releases publish to the `alpha` npm dist-tag. Stable releases publish to
 `latest`. Both are created by the protected Buildchain promotion transaction.
 
 Stable consumers should pin the exact Buildchain version they have validated,