@kungfu-tech/buildchain 2.11.2-alpha.1 → 2.11.2

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

@@ -3,11 +3,11 @@
   "contract": "kungfu-buildchain-public-surface-reverse-audit",
   "status": "passed",
   "summary": {
-    "cliCommandCount": 73,
-    "workflowCount": 36,
+    "cliCommandCount": 74,
+    "workflowCount": 37,
     "actionCount": 4,
     "sitePageCount": 45,
-    "docCommandRefCount": 229,
+    "docCommandRefCount": 231,
     "failureCount": 0
   },
   "enumerated": {
@@ -292,6 +292,11 @@
         "source": "bin/buildchain.mjs",
         "usage": "buildchain publication-artifact manifest [--cwd <dir>] [--source-sha <sha>]"
       },
+      {
+        "id": "publication-artifact-npm-package",
+        "source": "bin/buildchain.mjs",
+        "usage": "buildchain publication-artifact npm-package [--cwd <dir>] [--output-dir <dir>] [--package-name <name>] [--json]"
+      },
       {
         "id": "publish-source",
         "source": "bin/buildchain.mjs",
@@ -783,6 +788,45 @@
         ],
         "inputCount": 2
       },
+      {
+        "id": "paper-release",
+        "path": ".github/workflows/paper-release.yml",
+        "inputs": [
+          "artifact-name",
+          "artifact-retention-days",
+          "branch-protection-bypass-apps",
+          "branch-protection-bypass-teams",
+          "branch-protection-bypass-users",
+          "build-command",
+          "buildchain-contract-compatibility-policy",
+          "buildchain-contract-drift-issue-mode",
+          "buildchain-contract-lock-path",
+          "buildchain-ref",
+          "buildchain-repository",
+          "dry-run",
+          "github-release",
+          "github-release-notes",
+          "github-release-title",
+          "node-version",
+          "package-name",
+          "publish-dist-tag",
+          "publish-package-set-order",
+          "release-passport-impact-json",
+          "release-passport-output-dir",
+          "release-passport-product-name",
+          "required-status-check",
+          "setup-node",
+          "target-ref",
+          "target-sha",
+          "toolchain-command",
+          "toolchain-digest",
+          "toolchain-image",
+          "toolchain-type",
+          "verify-command",
+          "working-directory"
+        ],
+        "inputCount": 32
+      },
       {
         "id": "patrol-daily",
         "path": ".github/workflows/patrol-daily.yml",
@@ -2142,6 +2186,16 @@
         "path": "docs/publication-artifacts.md",
         "command": "buildchain publication-artifact manifest --source-sha"
       },
+      {
+        "id": "publication-artifact-npm-package",
+        "path": "docs/cli.md",
+        "command": "buildchain publication-artifact npm-package --json"
+      },
+      {
+        "id": "publication-artifact-npm-package",
+        "path": "docs/publication-artifacts.md",
+        "command": "buildchain publication-artifact npm-package --json"
+      },
       {
         "id": "publication-artifact",
         "path": "docs/cli.md",
@@ -2448,9 +2502,9 @@
     "cliRegistryPath": "dist/site/cli-registry.json",
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
-    "cliRegistryDigest": "53833f92021caa7cc5feaff5d21f38b0a77317ace11a43795be180d1dec3699f",
-    "workflowRegistryDigest": "67572429a83124370b9ffd46f56923aa2b252873c9624ded39a26675fb0ee815",
-    "pageRegistryDigest": "3a041b5802183d5a9559a415645b03f582a1e4808b4ba5713484e6941956d35e"
+    "cliRegistryDigest": "fb33fe38423f56ebf95919e2b58e13dc2f544aee10169bc87d7afe980bc1b142",
+    "workflowRegistryDigest": "4041321df08640a802a87ff0fbe8584d95dc416945b43778727adb820cab9097",
+    "pageRegistryDigest": "f9da4a3693844653a4b18db81be75676ecd70c5e15ebbc9371dcf007e5e4e858"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-07-09T15:39:27.573Z",
-  "publishedAt": "2026-07-09T15:39:27.573Z",
+  "generatedAt": "2026-07-09T16:13:10.700Z",
+  "publishedAt": "2026-07-09T16:13:10.700Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "2e87aaee5e94ac19ac676c3999349c55b8253730",
+  "sourceRevision": "f03d2e06255056626b7c0509274ada03b91c5a30",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.11.2-alpha.1",
+    "version": "2.11.2",
     "versionSource": "package.json#version"
   },
   "sourceKind": "package-site-bundle",

package/dist/site/release-provenance.json

@@ -24,6 +24,7 @@
       "./public-surface-audit": "./packages/core/public-surface-audit.js",
       "./logging": "./packages/core/logging.js",
       "./publication-artifact": "./packages/core/publication-artifact.js",
+      "./publication-package": "./packages/core/publication-package.js",
       "./kfd-gate": "./packages/core/kfd-gate.js",
       "./release-candidate": "./packages/core/release-candidate.js",
       "./release-passport": "./packages/core/release-passport.js",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-09T15:39:27.573Z",
-  "publishedAt": "2026-07-09T15:39:27.573Z",
+  "generatedAt": "2026-07-09T16:13:10.700Z",
+  "publishedAt": "2026-07-09T16:13:10.700Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "2e87aaee5e94ac19ac676c3999349c55b8253730",
+  "sourceRevision": "f03d2e06255056626b7c0509274ada03b91c5a30",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.11.2-alpha.1",
+    "version": "2.11.2",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -53,7 +53,7 @@
       "path": "docs/MAP.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:7e1b72dfc0ad91323156295617e320fee94a644efee54667b017e690fcebf64e"
+      "digest": "sha256:886d073bd37ac655e1ad9659baf161c72ef796b6032c5c3332218ac8198c2aeb"
     },
     {
       "id": "install",
@@ -173,7 +173,7 @@
       "path": "docs/cli.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:4b31f7ff5330cde8ab32b237f533c7af76463cce570d67dd14669c3a14c83c84"
+      "digest": "sha256:81624885888c9e357db128f644f93dcab2286910df426b532730b0141d7cb00d"
     },
     {
       "id": "build-facts",

package/dist/site/workflow-registry.json

@@ -479,6 +479,48 @@
       "capabilityGroup": "api-cli-reference",
       "status": "active"
     },
+    {
+      "id": "paper-release",
+      "path": ".github/workflows/paper-release.yml",
+      "inputs": [
+        "artifact-name",
+        "artifact-retention-days",
+        "branch-protection-bypass-apps",
+        "branch-protection-bypass-teams",
+        "branch-protection-bypass-users",
+        "build-command",
+        "buildchain-contract-compatibility-policy",
+        "buildchain-contract-drift-issue-mode",
+        "buildchain-contract-lock-path",
+        "buildchain-ref",
+        "buildchain-repository",
+        "dry-run",
+        "github-release",
+        "github-release-notes",
+        "github-release-title",
+        "node-version",
+        "package-name",
+        "publish-dist-tag",
+        "publish-package-set-order",
+        "release-passport-impact-json",
+        "release-passport-output-dir",
+        "release-passport-product-name",
+        "required-status-check",
+        "setup-node",
+        "target-ref",
+        "target-sha",
+        "toolchain-command",
+        "toolchain-digest",
+        "toolchain-image",
+        "toolchain-type",
+        "verify-command",
+        "working-directory"
+      ],
+      "inputCount": 32,
+      "surface": "reusable-build",
+      "capabilityGroup": "reusable-build",
+      "status": "active"
+    },
     {
       "id": "patrol-daily",
       "path": ".github/workflows/patrol-daily.yml",

package/docs/MAP.md

@@ -87,7 +87,7 @@ replace them.
 | How do I detect, register, audit, witness, or query KFD-3 product surfaces? | [`kfd-support.md`](kfd-support.md) + [`cli.md`](cli.md) | verify/use | stable |
 | How do I keep `@v2` floating refs while detecting Buildchain contract drift? | [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock) | verify/use | stable |
 | How do I propagate finalized upstream releases to downstream package/site PRs? | [`release-propagation.md`](release-propagation.md) | use | preview |
-| How do paper or report repositories publish PDFs, metadata, source bundles, and site-consumable manifests? | [`publication-artifacts.md`](publication-artifacts.md) | use | stable |
+| How do paper or report repositories publish PDFs, metadata, source bundles, site-consumable manifests, npm packages, and GitHub Releases? | [`publication-artifacts.md`](publication-artifacts.md) | use | stable |
 | How do I generate KFD / Release Passport badge bundles without hand-maintaining Markdown? | [`readme-badges.md`](readme-badges.md) + [`cli.md`](cli.md) | use | stable |
 | How do I generate and verify a Homebrew tap from release passport evidence? | [`homebrew.md`](homebrew.md) + [`cli.md`](cli.md) | use/verify | stable |
 | How do I prove a PR-stage reusable build is the artifact source promoted later? | [`release-candidate.md`](release-candidate.md) + [`reusable-build-surface.md`](reusable-build-surface.md) | verify | stable |

package/docs/cli.md

@@ -398,6 +398,19 @@ buildchain publication-artifact manifest \
   --json
 ```
 
+Generate the Buildchain-owned npm paper package contents from declared
+publication facts:
+
+```bash
+buildchain publication-artifact npm-package --json
+```
+
+This command reads `project.type = "publication-artifact"`,
+`publication.version`, and `[publish] kind = "npm-paper-package"` plus
+`publish.package`; it writes `.buildchain/publication/npm-package` by default.
+The `paper-release.yml@v2` reusable workflow uses the same command before
+running the standard npm publish transaction.
+
 The command writes `.buildchain/publication/publication-artifact.json`,
 `.buildchain/publication/publication-artifact-passport.json`, a source bundle,
 and, when `[publication.archive]` is configured,

package/docs/publication-artifacts.md

@@ -50,6 +50,11 @@ image = "ghcr.io/kungfu-systems/build-images/latex-pdf-builder"
 digest = "sha256:c20f3809e96836c1c78e97c76939d12f1de3fed0ea9b7c40c43332ec2ea480f8"
 command = "latexmk -pdf -outdir=_build paper/main.tex"
 
+[publish]
+kind = "npm-paper-package"
+package = "@kungfu-tech/paper-observer-declared-timelines"
+auth = "trusted-publishing"
+
 [lifecycle.build]
 command = "make pdf"
 
@@ -91,9 +96,16 @@ for compatibility, but the passport records it as lower trust because
 Buildchain can record the command boundary without proving the compiler or
 LaTeX distribution digest.
 
+`publish.kind = "npm-paper-package"` declares that Buildchain, not the consumer
+repository, owns the standard paper npm package shape and release transaction
+mechanics. `publish.package` is the public npm package that contains the PDF,
+publication manifest, publication passport, optional archive registry, source
+bundle, and declared metadata files.
+
 ## Reusable Workflow
 
-Consumer repositories can call the Buildchain wrapper directly:
+Consumer repositories that only need to build and upload paper evidence can
+call the build-only wrapper directly:
 
 ```yaml
 jobs:
@@ -106,7 +118,7 @@ jobs:
       buildchain-contract-lock-path: .buildchain/contract-lock.json
 ```
 
-The workflow:
+The build-only workflow:
 
 - resolves the Buildchain runtime and checks the floating contract lock before
   any paper build runs;
@@ -126,10 +138,76 @@ The workflow:
 - uploads one GitHub artifact containing the PDF, manifest, passport, optional
   registry, and source bundle.
 
-The wrapper is build-only. It does not publish npm packages, deploy web pages,
-or create GitHub Releases. Release publication can be layered later by a
-repository-specific governance workflow that attaches the generated manifest
-and passport as release assets.
+It does not publish npm packages, deploy web pages, or create GitHub Releases.
+
+## Paper Release Preset
+
+Paper repositories that publish a versioned npm package should use the
+Buildchain-managed release preset instead of copying npm transaction scripts or
+promotion YAML:
+
+```yaml
+name: Paper Release
+
+on:
+  push:
+    branches:
+      - alpha/v1/v1.0
+      - release/v1/v1.0
+  workflow_dispatch:
+    inputs:
+      buildchain-ref:
+        description: "Temporary Buildchain runtime ref"
+        required: false
+        default: ""
+
+jobs:
+  paper-release:
+    uses: kungfu-systems/buildchain/.github/workflows/paper-release.yml@v2
+    permissions:
+      contents: write
+      id-token: write
+      issues: write
+    with:
+      buildchain-ref: ${{ inputs.buildchain-ref || '' }}
+      toolchain-type: config
+      verify-command: make check
+      buildchain-contract-lock-path: .buildchain/contract-lock.json
+```
+
+The preset:
+
+- resolves the same floating Buildchain runtime and contract lock as the build
+  workflow;
+- builds the PDF through the declared pinned LaTeX Docker toolchain or custom
+  command;
+- verifies the paper repository;
+- writes the publication manifest, publication passport, optional archive
+  registry, and source bundle;
+- synthesizes an npm package from `[publication]` and `[publish]` declarations
+  under `.buildchain/publication/npm-package`;
+- computes npm-style `sha512` integrity from `npm pack --dry-run` and passes
+  it as `publish-required-artifacts-json`;
+- creates a `publish-gate/<alpha|release>/.../<version>` source lock for the
+  channel commit and requires `promote-buildchain-ref` to verify that lock
+  before any publish side effect;
+- publishes the package through npm Trusted Publishing;
+- writes Buildchain release/passport evidence; and
+- creates or updates the exact-version GitHub Release by default.
+
+Consumers can opt out of the GitHub Release with `github-release: false`, but
+the default is on so downstream release propagation can observe
+`release.published` without hand-written `gh release` steps.
+
+For npm Trusted Publishing, register the consumer workflow file that calls this
+preset, for example `.github/workflows/paper-release.yml`, against the declared
+package in npm. The trusted publisher is the consumer repository and workflow
+file; the implementation still runs inside Buildchain's reusable workflow.
+
+Standard paper repositories should not carry local copies of
+`scripts/npm-publish-transaction.mjs`, package-generation scripts, or
+promotion/ref-lock YAML. If the default package shape is insufficient, extend
+Buildchain rather than forking the mechanics into each paper repository.
 
 ## CLI And Node API
 
@@ -139,6 +217,12 @@ Generate the publication manifest locally or in CI:
 buildchain publication-artifact manifest --source-sha "$(git rev-parse HEAD)" --json
 ```
 
+Generate the npm package contents after the manifest exists:
+
+```sh
+buildchain publication-artifact npm-package --json
+```
+
 Node API:
 
 ```js
@@ -146,6 +230,11 @@ import {
   collectPublicationArtifact,
   writePublicationArtifact,
 } from "@kungfu-tech/buildchain/publication-artifact";
+
+import {
+  collectPublicationPackageFacts,
+  preparePublicationNpmPackage,
+} from "@kungfu-tech/buildchain/publication-package";
 ```
 
 `writePublicationArtifact()` is the single implementation used by the CLI and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.11.2-alpha.1",
+  "version": "2.11.2",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -27,6 +27,7 @@
     "./public-surface-audit": "./packages/core/public-surface-audit.js",
     "./logging": "./packages/core/logging.js",
     "./publication-artifact": "./packages/core/publication-artifact.js",
+    "./publication-package": "./packages/core/publication-package.js",
     "./kfd-gate": "./packages/core/kfd-gate.js",
     "./release-candidate": "./packages/core/release-candidate.js",
     "./release-passport": "./packages/core/release-passport.js",

package/packages/core/buildchain-config.js

@@ -16,6 +16,7 @@ const SUPPORTED_VERSION_NEXT = new Set(["auto", "manual"]);
 const SUPPORTED_PROJECT_TYPES = new Set(["package", "web-surface", "infra-contract", "distribution-index", "publication-artifact"]);
 const SUPPORTED_PUBLISH_MODES = new Set(["publish-final-version", "promote-existing-version"]);
 const SUPPORTED_PUBLISH_AUTH = new Set(["trusted-publishing", "npm-token"]);
+const SUPPORTED_PUBLISH_KINDS = new Set(["npm-package", "npm-paper-package"]);
 const SUPPORTED_PACKAGE_SET_ORDER = new Set(["as-provided", "platforms-first-main-last"]);
 const SUPPORTED_NATIVE_COMPILER_CACHE = new Set(["auto", "ccache", "sccache", "none"]);
 const WEB_SURFACE_CHANNELS = ["preview", "staging", "production"];
@@ -338,13 +339,19 @@ function normalizePublishSection(publish) {
   if (mode === "promote-existing-version" && auth !== "npm-token") {
     throw new Error('publish.mode = "promote-existing-version" requires publish.auth = "npm-token"');
   }
+  const kind = publish.kind === undefined
+    ? ""
+    : assertString(publish.kind, "publish.kind");
+  if (kind && !SUPPORTED_PUBLISH_KINDS.has(kind)) {
+    throw new Error("publish.kind must be one of npm-package or npm-paper-package");
+  }
   const packageSetOrder = publish.package_set_order === undefined
     ? "as-provided"
     : assertString(publish.package_set_order, "publish.package_set_order");
   if (!SUPPORTED_PACKAGE_SET_ORDER.has(packageSetOrder)) {
     throw new Error("publish.package_set_order must be one of as-provided or platforms-first-main-last");
   }
-  return {
+  const normalized = {
     mode,
     auth,
     distTag: publish.dist_tag === undefined
@@ -355,6 +362,13 @@ function normalizePublishSection(publish) {
       ? ""
       : assertString(publish.main_package, "publish.main_package"),
   };
+  if (publish.kind !== undefined) {
+    normalized.kind = kind;
+  }
+  if (publish.package !== undefined) {
+    normalized.package = assertString(publish.package, "publish.package");
+  }
+  return normalized;
 }
 
 function normalizeProjectSection(project) {

package/packages/core/index.js

@@ -111,6 +111,12 @@ export {
   validateReleaseCandidatePassport,
 } from "./release-candidate.js";
 
+export {
+  PUBLICATION_NPM_PACKAGE_CONTRACT,
+  collectPublicationPackageFacts,
+  preparePublicationNpmPackage,
+} from "./publication-package.js";
+
 export {
   ARTIFACT_PASSPORT_LOCATOR_CONTRACT,
   ARTIFACT_PASSPORT_POINTER_CONTRACT,