@kungfu-tech/buildchain 2.10.9 → 2.10.10

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

@@ -3,11 +3,11 @@
   "contract": "kungfu-buildchain-public-surface-reverse-audit",
   "status": "passed",
   "summary": {
-    "cliCommandCount": 71,
-    "workflowCount": 35,
+    "cliCommandCount": 73,
+    "workflowCount": 36,
     "actionCount": 4,
-    "sitePageCount": 43,
-    "docCommandRefCount": 224,
+    "sitePageCount": 45,
+    "docCommandRefCount": 227,
     "failureCount": 0
   },
   "enumerated": {
@@ -110,7 +110,7 @@
       {
         "id": "init",
         "source": "bin/buildchain.mjs",
-        "usage": "buildchain init [--cwd <dir>] [--type package|native|web-surface|infra-contract|anchored-package] [--force]"
+        "usage": "buildchain init [--cwd <dir>] [--type package|native|web-surface|infra-contract|publication-artifact|anchored-package] [--force]"
       },
       {
         "id": "inspect",
@@ -282,6 +282,16 @@
         "source": "bin/buildchain.mjs",
         "usage": "buildchain npm dry-run [--cwd <dir>] [--expected-tag <tag>] [--registry <url>]"
       },
+      {
+        "id": "publication-artifact",
+        "source": "bin/buildchain.mjs",
+        "usage": "buildchain publication-artifact"
+      },
+      {
+        "id": "publication-artifact-manifest",
+        "source": "bin/buildchain.mjs",
+        "usage": "buildchain publication-artifact manifest [--cwd <dir>] [--source-sha <sha>]"
+      },
       {
         "id": "publish-source",
         "source": "bin/buildchain.mjs",
@@ -606,6 +616,7 @@
           "production-approved",
           "production-aws-role-arn",
           "production-environment",
+          "production-release-app-client-id",
           "production-release-app-id",
           "production-release-branch-channel",
           "production-release-head-prefix",
@@ -620,7 +631,7 @@
           "verify-command",
           "working-directory"
         ],
-        "inputCount": 32
+        "inputCount": 33
       },
       {
         "id": ".wheel-release",
@@ -813,6 +824,26 @@
         ],
         "inputCount": 4
       },
+      {
+        "id": "publication-artifact",
+        "path": ".github/workflows/publication-artifact.yml",
+        "inputs": [
+          "artifact-name",
+          "artifact-paths",
+          "artifact-retention-days",
+          "build-command",
+          "buildchain-contract-compatibility-policy",
+          "buildchain-contract-drift-issue-mode",
+          "buildchain-contract-lock-path",
+          "buildchain-ref",
+          "buildchain-repository",
+          "node-version",
+          "setup-node",
+          "verify-command",
+          "working-directory"
+        ],
+        "inputCount": 13
+      },
       {
         "id": "release-candidate-promote",
         "path": ".github/workflows/release-candidate-promote.yml",
@@ -1132,6 +1163,10 @@
         "id": "fixture:libnode-shaped",
         "category": "fixture"
       },
+      {
+        "id": "fixture:publication-artifact-shaped",
+        "category": "fixture"
+      },
       {
         "id": "fixture:publish-transaction-shaped",
         "category": "fixture"
@@ -1196,6 +1231,10 @@
         "id": "manual:product-mechanism",
         "category": "manual"
       },
+      {
+        "id": "manual:publication-artifacts",
+        "category": "manual"
+      },
       {
         "id": "manual:publish-transaction",
         "category": "manual"
@@ -2084,6 +2123,21 @@
         "path": "docs/cli.md",
         "command": "buildchain npm dry-run"
       },
+      {
+        "id": "publication-artifact-manifest",
+        "path": "docs/cli.md",
+        "command": "buildchain publication-artifact manifest"
+      },
+      {
+        "id": "publication-artifact-manifest",
+        "path": "docs/publication-artifacts.md",
+        "command": "buildchain publication-artifact manifest --source-sha"
+      },
+      {
+        "id": "publication-artifact",
+        "path": "docs/cli.md",
+        "command": "buildchain publication-artifact"
+      },
       {
         "id": "publish-source",
         "path": "docs/cli.md",
@@ -2380,9 +2434,9 @@
     "cliRegistryPath": "dist/site/cli-registry.json",
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
-    "cliRegistryDigest": "239414b93a2165625ea54f124377ad270355ca8c0764f4ff2a8ebc9ad78f2832",
-    "workflowRegistryDigest": "7ec4a7f4f2d81ec294a4b961f6f991c3e90bacb6f516a5138736399d461d9aee",
-    "pageRegistryDigest": "23c900280e3c30ca9886d74a5f744961f2b2c5a202743d264d423f0bb29c9eee"
+    "cliRegistryDigest": "1f7e1f7707a089f067175030fde6712b69ceece3df1b811eb542b0b4c8c1d4a9",
+    "workflowRegistryDigest": "5a74fd4e5b7b071f014b59d590313535da05e7a96d46b82db0bc306182911395",
+    "pageRegistryDigest": "a32dc62d72d1499d3156711aa51c58c0a19be4cace798617815c98c733e43f8e"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/release-provenance.json

@@ -23,6 +23,7 @@
       "./readme-badges": "./packages/core/readme-badges.js",
       "./public-surface-audit": "./packages/core/public-surface-audit.js",
       "./logging": "./packages/core/logging.js",
+      "./publication-artifact": "./packages/core/publication-artifact.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-09T00:25:26.922Z",
-  "publishedAt": "2026-07-09T00:25:26.922Z",
+  "generatedAt": "2026-07-09T01:16:31.067Z",
+  "publishedAt": "2026-07-09T01:16:31.067Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "bdd863e4ac8fa7b502a23f7e9a8faf9d31535c19",
+  "sourceRevision": "227aeefaff9a5bbf881d7fb903d39544ef0624af",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.10.9",
+    "version": "2.10.10",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -53,7 +53,7 @@
       "path": "docs/MAP.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:b12caa887a325820c591d462ae2c0a4521eda001cb71d3def72e9b55924f892f"
+      "digest": "sha256:2295adcb4860c46a6f7fb39a0790d7347d916a0ac999d862437698d194af31de"
     },
     {
       "id": "install",
@@ -173,7 +173,7 @@
       "path": "docs/cli.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:b6bc32831d202d5c542d72f6e63322f632014751e7db00862b28fb9ce5318fd3"
+      "digest": "sha256:35df4de8a3ade449bb577b50ac3000adb2eafe354fd2f885f408ffe6e86d5f19"
     },
     {
       "id": "build-facts",
@@ -253,7 +253,7 @@
       "path": "docs/web-surface-deployments.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:cae39c60ffa0da5eb963a49d8d4ad6294788b1b76a8ba2516de75b263b3b8504"
+      "digest": "sha256:e5792a28aac1b2502a91f0cafd06dd52a4eecbcfb1f8df349c5aed16229777ec"
     }
   ],
   "facts": [

package/dist/site/workflow-registry.json

@@ -270,6 +270,7 @@
         "production-approved",
         "production-aws-role-arn",
         "production-environment",
+        "production-release-app-client-id",
         "production-release-app-id",
         "production-release-branch-channel",
         "production-release-head-prefix",
@@ -284,7 +285,7 @@
         "verify-command",
         "working-directory"
       ],
-      "inputCount": 32,
+      "inputCount": 33,
       "surface": "reusable-workflow",
       "capabilityGroup": "api-cli-reference",
       "status": "active"
@@ -528,6 +529,29 @@
       "capabilityGroup": "governance-versioning",
       "status": "active"
     },
+    {
+      "id": "publication-artifact",
+      "path": ".github/workflows/publication-artifact.yml",
+      "inputs": [
+        "artifact-name",
+        "artifact-paths",
+        "artifact-retention-days",
+        "build-command",
+        "buildchain-contract-compatibility-policy",
+        "buildchain-contract-drift-issue-mode",
+        "buildchain-contract-lock-path",
+        "buildchain-ref",
+        "buildchain-repository",
+        "node-version",
+        "setup-node",
+        "verify-command",
+        "working-directory"
+      ],
+      "inputCount": 13,
+      "surface": "repository-workflow",
+      "capabilityGroup": "reusable-build",
+      "status": "active"
+    },
     {
       "id": "release-candidate-promote",
       "path": ".github/workflows/release-candidate-promote.yml",

package/docs/MAP.md

@@ -31,6 +31,7 @@ workflow, action, and Node API export also carries a `capabilityGroup`,
 | Reusable Build and Lifecycle | `workflow-registry.json`, `release-model.json` | [`reusable-build-surface.md`](reusable-build-surface.md), [`lifecycle-protocol.md`](lifecycle-protocol.md) |
 | KFD Trust and Surface Closure | `kfd-claims.json`, `public-surface-audit.json`, `cli-registry.json`, `node-api-registry.json` | [`kfd-support.md`](kfd-support.md), [`release-passport.md`](release-passport.md) |
 | Site Bundle, Web Surfaces, and Propagation | `buildchain-site.json`, `site-manifest.json`, `page-registry.json`, `release-model.json` | [`site-bundle-contract.md`](site-bundle-contract.md), [`web-surface-deployments.md`](web-surface-deployments.md), [`release-propagation.md`](release-propagation.md) |
+| Publication Artifacts | `workflow-registry.json`, `node-api-registry.json`, `manual-registry.json` | [`publication-artifacts.md`](publication-artifacts.md), [`reusable-build-surface.md`](reusable-build-surface.md) |
 | Distribution Indexes and Badges | `badge-endpoint-registry.json`, `node-api-registry.json`, `manual-registry.json` | [`readme-badges.md`](readme-badges.md), [`homebrew.md`](homebrew.md) |
 | Build Facts, Observability, and Diagnostics | `cli-registry.json`, `node-api-registry.json`, lifecycle artifacts | [`build-facts.md`](build-facts.md), [`toolkit-observability.md`](toolkit-observability.md), [`consumer-issue-reporting.md`](consumer-issue-reporting.md) |
 | Governance, Versioning, and Runtime Drift | `buildchain-contract.json`, `workflow-registry.json`, `release-model.json` | [`release-governance.md`](release-governance.md), [`release-flow.md`](release-flow.md), [`versioning.md`](versioning.md), [`runtime-train-validation.md`](runtime-train-validation.md) |
@@ -47,6 +48,7 @@ workflow, action, and Node API export also carries a `capabilityGroup`,
 | Git/source/version/module/product build facts | `dist/site/node-api-registry.json`, `dist/site/cli-registry.json`, `kungfu-buildchain-module-build-facts`, `kungfu-buildchain-product-build-facts` | [`build-facts.md`](build-facts.md) |
 | GitHub Release passport/evidence publication | `dist/site/release-model.json`, `dist/site/artifact-schemas.json` | [`release-governance.md`](release-governance.md), [`release-candidate.md`](release-candidate.md) |
 | release propagation for package/site chains | `dist/site/release-model.json` | [`release-propagation.md`](release-propagation.md) |
+| publication artifact manifests, source bundles, and paper repository workflows | `dist/site/workflow-registry.json`, `dist/site/node-api-registry.json`, `kungfu-buildchain-publication-artifact-manifest` | [`publication-artifacts.md`](publication-artifacts.md) |
 | Generated badge bundles, README badge blocks, and badge facts | `dist/site/node-api-registry.json`, `dist/site/manual-registry.json`, `kungfu-buildchain-badge-bundle-facts`, `kungfu-buildchain-readme-badge-facts` | [`readme-badges.md`](readme-badges.md) |
 | Homebrew tap distribution indexes | `dist/site/node-api-registry.json`, `dist/site/buildchain-contract.json` | [`homebrew.md`](homebrew.md) |
 | Buildchain CLI manual | `dist/site/cli-registry.json`, `dist/site/manual-registry.json` | [`cli.md`](cli.md) |
@@ -85,6 +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 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 |
@@ -99,7 +102,7 @@ replace them.
 | How do I publish observed infrastructure contracts for downstream consumers? | [`infra-contract.md`](infra-contract.md) | use | preview |
 | How do I use the active actions directly? | [`../actions/validate-config/README.md`](../actions/validate-config/README.md), [`../actions/run-lifecycle/README.md`](../actions/run-lifecycle/README.md), [`../actions/promote-buildchain-ref/README.md`](../actions/promote-buildchain-ref/README.md), [`../actions/report-buildchain-issue/README.md`](../actions/report-buildchain-issue/README.md) | use | stable |
 | How can a consumer workflow report a Buildchain-owned failure back to Buildchain? | [`consumer-issue-reporting.md`](consumer-issue-reporting.md) + [`../actions/report-buildchain-issue/README.md`](../actions/report-buildchain-issue/README.md) | use | stable |
-| What do the fixture repositories demonstrate? | [`../fixtures/libnode-shaped/README.md`](../fixtures/libnode-shaped/README.md), [`../fixtures/publish-transaction-shaped/README.md`](../fixtures/publish-transaction-shaped/README.md), [`../fixtures/web-surface-shaped/README.md`](../fixtures/web-surface-shaped/README.md) | verify | stable |
+| What do the fixture repositories demonstrate? | [`../fixtures/libnode-shaped/README.md`](../fixtures/libnode-shaped/README.md), [`../fixtures/publish-transaction-shaped/README.md`](../fixtures/publish-transaction-shaped/README.md), [`../fixtures/web-surface-shaped/README.md`](../fixtures/web-surface-shaped/README.md), [`../fixtures/publication-artifact-shaped/README.md`](../fixtures/publication-artifact-shaped/README.md) | verify | stable |
 | What license and contribution terms apply? | [`../LICENSE`](../LICENSE) + [`../LICENSE-POLICY.md`](../LICENSE-POLICY.md) | use | stable |
 | What trademark, official-service, and provider-compliance boundaries apply? | [`../TRADEMARK.md`](../TRADEMARK.md) + [`../ACCEPTABLE_USE.md`](../ACCEPTABLE_USE.md) + [`../PROVIDER_COMPLIANCE.md`](../PROVIDER_COMPLIANCE.md) | use | stable |
 | How do I report a vulnerability? | [`../SECURITY.md`](../SECURITY.md) | use | stable |
@@ -148,6 +151,8 @@ replace them.
   Kungfu build info** -> [`build-facts.md`](build-facts.md) and [`cli.md`](cli.md).
 - **release chains / upstream package as source of truth / site synchronization** ->
   [`release-propagation.md`](release-propagation.md).
+- **paper repositories / PDFs / publication manifests / source bundles** ->
+  [`publication-artifacts.md`](publication-artifacts.md).
 - **README status badges / KFD badge bundles / badge facts JSON** ->
   [`readme-badges.md`](readme-badges.md) and [`cli.md`](cli.md).
 - **Homebrew taps / distribution indexes / Formula drift checks** ->

package/docs/cli.md

@@ -102,6 +102,9 @@ Supported presets:
   validation, observation, contract publication, and downstream propagation
   planning without default mutation. Provider adapters expose built-in command
   plans by default, and only configured `[infra.commands]` hooks can execute.
+- `--type publication-artifact` for papers, reports, specifications, and other
+  publication repositories that produce PDFs, metadata, source bundles, and
+  site-consumable manifests without becoming web-surface repositories.
 - `--type distribution-index` for Homebrew taps and other index repositories
   whose files are projections of upstream release passport evidence.
 - `--type anchored-package` for packages whose version is anchored to an
@@ -378,11 +381,25 @@ version against configured version files and the anchor manifest. The JSON
 result is shaped for future `buildchain.libkungfu.dev` fact ingestion.
 
 `buildchain release`, `buildchain web-surface`, `buildchain infra-contract`,
-`buildchain publish-source`, `buildchain badges`, `buildchain homebrew`, and
-`buildchain build-contract` route to the same implementation used by
+`buildchain publication-artifact`, `buildchain publish-source`,
+`buildchain badges`, `buildchain homebrew`, and `buildchain build-contract`
+route to the same implementation used by
 Buildchain's package APIs or GitHub Actions workflows. This keeps local
 inspection and CI behavior on the same implementation path.
 
+Generate publication artifact metadata after building a paper or report:
+
+```bash
+buildchain publication-artifact manifest \
+  --source-sha "$(git rev-parse HEAD)" \
+  --json
+```
+
+The command writes `.buildchain/publication/publication-artifact.json`,
+`.buildchain/publication/publication-artifact-passport.json`, and a source
+bundle by default. See [`publication-artifacts.md`](publication-artifacts.md)
+for the repository contract and reusable workflow.
+
 Generate, check, or update the managed README badge block:
 
 ```bash

package/docs/publication-artifacts.md

@@ -0,0 +1,126 @@
+# Publication Artifact Workflow
+
+Buildchain supports `project.type = "publication-artifact"` for repositories
+that produce auditable papers, reports, specifications, or similar publication
+packages. These repositories are artifact producers. They should not be forced
+to become `web-surface` repositories just because a downstream site later
+renders the paper.
+
+The split is:
+
+```text
+paper repo = source, PDF, metadata, source bundle, publication manifest
+papers site = layout, navigation, public web surface, downstream rendering
+```
+
+## Configuration
+
+The paper repository owns `.buildchain/buildchain.toml`:
+
+```toml
+schema = 1
+
+[project]
+type = "publication-artifact"
+name = "paper-observer-declared-timelines"
+
+[publication]
+kind = "paper"
+title = "Observer-Declared Timelines for Real-World Agent Work"
+primary_artifact = "_build/main.pdf"
+artifact_paths = ["_build/main.pdf"]
+metadata_paths = ["README.md", "docs/MAP.md"]
+source_paths = ["paper", "README.md", "LICENSE", "Makefile"]
+site_consumers = ["papers.libkungfu.dev"]
+manifest_path = ".buildchain/publication/publication-artifact.json"
+source_bundle_path = ".buildchain/publication/source.tar.gz"
+
+[lifecycle.build]
+command = "make pdf"
+
+[lifecycle.verify]
+command = "make check"
+```
+
+`primary_artifact` is the human-facing publication output, usually a PDF.
+`source_paths` are archived into a source bundle. `metadata_paths` are hashed
+and recorded so a site can consume the paper facts without scraping prose.
+
+## Reusable Workflow
+
+Consumer repositories can call the Buildchain wrapper directly:
+
+```yaml
+jobs:
+  publication:
+    uses: kungfu-systems/buildchain/.github/workflows/publication-artifact.yml@v2
+    with:
+      build-command: make pdf
+      verify-command: make check
+      artifact-name: observer-declared-timelines
+      buildchain-contract-lock-path: .buildchain/contract-lock.json
+```
+
+The workflow:
+
+- resolves the Buildchain runtime and checks the floating contract lock before
+  any paper build runs;
+- runs the declared build and verify commands;
+- creates a source bundle from `publication.source_paths`;
+- writes `.buildchain/publication/publication-artifact.json`;
+- writes `.buildchain/publication/publication-artifact-passport.json`;
+- uploads one GitHub artifact containing the PDF, manifest, passport, 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.
+
+## CLI And Node API
+
+Generate the publication manifest locally or in CI:
+
+```sh
+buildchain publication-artifact manifest --source-sha "$(git rev-parse HEAD)" --json
+```
+
+Node API:
+
+```js
+import {
+  collectPublicationArtifact,
+  writePublicationArtifact,
+} from "@kungfu-tech/buildchain/publication-artifact";
+```
+
+`writePublicationArtifact()` is the single implementation used by the CLI and
+the reusable workflow. The generated manifest records:
+
+- publication title, kind, authors, and primary artifact;
+- artifact paths, byte sizes, and SHA-256 digests;
+- metadata paths and SHA-256 digests;
+- source SHA, tree SHA, source files, and source bundle digest;
+- timestamp and reproducibility policy;
+- downstream site-consumption hints.
+
+The companion publication artifact passport records the same source and
+artifact evidence plus an explicit responsibility split. Buildchain proves
+declared files and hashes; it does not peer-review paper claims.
+
+## Site Consumption
+
+A downstream papers site should treat the publication manifest as the single
+fact source for the artifact. The site owns rendering and navigation; it should
+not reinterpret the paper repository as a web deployment source.
+
+For `paper-observer-declared-timelines`, the expected adoption path is:
+
+```text
+paper repo builds PDF + manifest + source bundle
+papers site consumes publication-artifact.json
+site renders paper page and links the PDF/source bundle
+```
+
+This mirrors web-surface governance without mixing producer and renderer
+responsibilities.

package/docs/web-surface-deployments.md

@@ -726,17 +726,23 @@ jobs:
 Automatic release PR creation normally uses the workflow `github.token`.
 Consumers that cannot enable "GitHub Actions can create and approve pull
 requests" globally should prefer the first-class GitHub App path. Pass the App
-id as an input and the private key as a reusable workflow secret; Buildchain
+client id as an input and the private key as a reusable workflow secret; Buildchain
 creates an installation token inside the release PR job and uses it only for the
 release-intent branch, PR, and label operations:
 
 ```yaml
 with:
-  production-release-app-id: ${{ vars.KUNGFU_RELEASE_APP_ID }}
+  production-release-app-client-id: ${{ vars.KUNGFU_RELEASE_APP_CLIENT_ID }}
 secrets:
   production-release-app-private-key: ${{ secrets.KUNGFU_RELEASE_APP_PRIVATE_KEY }}
 ```
 
+`production-release-app-id` remains accepted as a deprecated alias for the input
+name, but the value should be the GitHub App client id. GitHub App numeric App
+IDs and client IDs are distinct, and Buildchain passes the value to
+`actions/create-github-app-token` through its non-deprecated `client-id` input so
+new runs do not emit the deprecated `app-id` warning.
+
 If a repository already generates its own narrow token or PAT, it can still pass
 that through `production-release-pr-token`:
 

package/fixtures/publication-artifact-shaped/README.md

@@ -0,0 +1,11 @@
+# Publication Artifact Fixture
+
+This fixture models a paper repository that produces publication artifacts
+without becoming a web-surface repository.
+
+It declares:
+
+- `project.type = "publication-artifact"`;
+- a primary PDF artifact;
+- source paths that Buildchain archives into a source bundle;
+- metadata paths that a future papers site can consume as a single fact source.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.10.9",
+  "version": "2.10.10",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -26,6 +26,7 @@
     "./readme-badges": "./packages/core/readme-badges.js",
     "./public-surface-audit": "./packages/core/public-surface-audit.js",
     "./logging": "./packages/core/logging.js",
+    "./publication-artifact": "./packages/core/publication-artifact.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/README.md

@@ -18,6 +18,8 @@ Current shared surfaces:
   `@kungfu-tech/buildchain/release-passport`.
 - managed KFD / Release Passport badge bundle facts and README marker blocks
   through `@kungfu-tech/buildchain/badges`.
+- publication artifact manifests, source bundles, and publication artifact
+  passports through `@kungfu-tech/buildchain/publication-artifact`.
 
 ## Toolkit Imports
 
@@ -64,6 +66,15 @@ const fact = collectModuleBuildFacts({ moduleId: "native-core" });
 writeBuildFacts({ fact, output: ".buildchain/facts/native-core.json" });
 ```
 
+Publication repositories can produce site-consumable paper/report facts without
+becoming web-surface repositories:
+
+```js
+import { writePublicationArtifact } from "@kungfu-tech/buildchain/publication-artifact";
+
+writePublicationArtifact({ sourceSha: process.env.GITHUB_SHA });
+```
+
 Web-surface validation stays in core because both local scripts and GitHub
 Actions need the same fail-closed interpretation of project, channel, deploy,
 retention, and staging security declarations.

package/packages/core/buildchain-config.js

@@ -13,7 +13,7 @@ const RESERVED_LIFECYCLE_KEYS = new Set(["env", "shell"]);
 const SUPPORTED_VERSION_FILE_TYPES = new Set(["json", "toml", "regex"]);
 const SUPPORTED_VERSION_STRATEGIES = new Set(["semver", "anchored"]);
 const SUPPORTED_VERSION_NEXT = new Set(["auto", "manual"]);
-const SUPPORTED_PROJECT_TYPES = new Set(["package", "web-surface", "infra-contract", "distribution-index"]);
+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_PACKAGE_SET_ORDER = new Set(["as-provided", "platforms-first-main-last"]);
@@ -147,6 +147,9 @@ export function normalizeBuildchainConfig(config) {
   if (normalized.infra !== undefined) {
     normalized.infra = normalizeInfraSection(normalized.infra);
   }
+  if (normalized.publication !== undefined) {
+    normalized.publication = normalizePublicationSection(normalized.publication);
+  }
   if (normalized.consumers !== undefined) {
     normalized.consumers = normalizeConsumersSection(normalized.consumers);
   }
@@ -357,7 +360,7 @@ function normalizeProjectSection(project) {
   assertPlainObject(project, "project");
   const type = assertString(project.type, "project.type");
   if (!SUPPORTED_PROJECT_TYPES.has(type)) {
-    throw new Error("project.type must be one of package, web-surface, infra-contract, or distribution-index");
+    throw new Error("project.type must be one of package, web-surface, infra-contract, distribution-index, or publication-artifact");
   }
   const normalized = { type };
   for (const key of ["name", "site"]) {
@@ -368,6 +371,33 @@ function normalizeProjectSection(project) {
   return normalized;
 }
 
+function normalizePublicationSection(publication) {
+  assertPlainObject(publication, "publication");
+  const kind = publication.kind === undefined ? "paper" : assertString(publication.kind, "publication.kind");
+  if (!["paper", "report", "specification", "article", "dataset-note"].includes(kind)) {
+    throw new Error("publication.kind must be one of paper, report, specification, article, or dataset-note");
+  }
+  const primaryArtifact = posixPath(assertString(publication.primary_artifact, "publication.primary_artifact"));
+  return {
+    kind,
+    title: assertString(publication.title, "publication.title"),
+    primaryArtifact,
+    version: publication.version === undefined ? "" : assertString(publication.version, "publication.version"),
+    abstract: publication.abstract === undefined ? "" : assertString(publication.abstract, "publication.abstract"),
+    authors: normalizeStringArray(publication.authors, "publication.authors"),
+    artifactPaths: normalizeStringArray(publication.artifact_paths, "publication.artifact_paths").map(posixPath),
+    metadataPaths: normalizeStringArray(publication.metadata_paths, "publication.metadata_paths").map(posixPath),
+    sourcePaths: normalizeStringArray(publication.source_paths, "publication.source_paths").map(posixPath),
+    siteConsumers: normalizeStringArray(publication.site_consumers, "publication.site_consumers"),
+    manifestPath: publication.manifest_path === undefined
+      ? ".buildchain/publication/publication-artifact.json"
+      : posixPath(assertString(publication.manifest_path, "publication.manifest_path")),
+    sourceBundlePath: publication.source_bundle_path === undefined
+      ? ".buildchain/publication/source.tar.gz"
+      : posixPath(assertString(publication.source_bundle_path, "publication.source_bundle_path")),
+  };
+}
+
 function normalizeInfraSection(infra) {
   assertPlainObject(infra, "infra");
   const adapter = assertString(infra.adapter, "infra.adapter");
@@ -1203,6 +1233,7 @@ export function validateBuildchainConfig(
     lifecycleStages,
     publish: loadedConfig.config.publish,
     facts: loadedConfig.config.facts,
+    publication: loadedConfig.config.publication,
   };
 }
 

package/packages/core/index.js

@@ -185,6 +185,14 @@ export {
   enumerateWorkflowInputs,
 } from "./public-surface-audit.js";
 
+export {
+  PUBLICATION_ARTIFACT_MANIFEST_CONTRACT,
+  PUBLICATION_ARTIFACT_PASSPORT_CONTRACT,
+  collectPublicationArtifact,
+  createPublicationSourceBundle,
+  writePublicationArtifact,
+} from "./publication-artifact.js";
+
 export {
   AGENT_INDEX_CONTRACT,
   ARTIFACT_EVIDENCE_CONTRACT,

package/packages/core/public-surface-audit.js

@@ -73,6 +73,10 @@ function commandId(first = "", second = "", third = "") {
   if (head === "homebrew" && sub) return `homebrew-${sub}`;
   if (head === "release-propagation") return "release-propagation";
   if (head === "publish-source") return "publish-source";
+  if (head === "publication-artifact" && sub) return `publication-artifact-${sub}`;
+  if (head === "publication-artifact") return "publication-artifact";
+  if (head === "publication" && sub) return `publication-artifact-${sub}`;
+  if (head === "publication") return "publication-artifact";
   if (head === "build-contract") return "build-contract";
   if (head === "infra-contract") return "infra-contract";
   if (head === "web-surface") return "web-surface";