@kungfu-tech/buildchain 2.10.10 → 2.10.11

package/dist/site/buildchain-contract.json

@@ -4,7 +4,7 @@
   "product": {
     "name": "Buildchain",
     "package": "@kungfu-tech/buildchain",
-    "version": "2.10.10",
+    "version": "2.10.11",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "majorLine": "v2",
@@ -92,7 +92,7 @@
         "GitHub Release passport and evidence publication is delegated to promote-buildchain-ref after the semver release transaction completes"
       ],
       "breakingDigest": "sha256:403d2fcdb0c5eabe749e89102defad69745f70a1556707bec7831fcc2e9fa8f8",
-      "auditDigest": "sha256:b3e96fe1d01793481dcf507373b7856a9b29451d168b18cd0f149517cb61ffde"
+      "auditDigest": "sha256:db6fe83e886a04221cc2457d3bdf091cd8607083d5c5e4dc87f40220c2436581"
     },
     {
       "contractVersion": 1,
@@ -134,7 +134,7 @@
         "breaking contract drift fails closed before rendering, deployment, or release publication"
       ],
       "breakingDigest": "sha256:82ee63cb336e40d832dfff4a1c5e6cbfa221a4fc8b2359990033bc931bffc43a",
-      "auditDigest": "sha256:fdb586f033b0bcbe2455b1f9e1ced419d22b715fcdcb5d096265b741471cac9a"
+      "auditDigest": "sha256:623e5222b8e649b40a05817fabf4c7fd8052a3e64636e74eb7a7bbcfd9de4998"
     },
     {
       "contractVersion": 1,
@@ -456,9 +456,9 @@
         "agents can discover supported Node APIs without importing internal file paths"
       ],
       "breakingDigest": "sha256:48f925608d3e2131d90936b07dc2a30341204cae3e6e785c0f77d61ad755c945",
-      "auditDigest": "sha256:44685053beb1571e543d5912009acea8eb29e13ca9bb96baffb10e87805dfcbf"
+      "auditDigest": "sha256:983094d1f0d421294e6c542232a5483c408aa72352883b851e1e2ecff1f9e8b5"
     }
   ],
   "compatibilityDigest": "sha256:967df7e854fdf582294ddfb6403eff25c00db9518a24051e7d47cbd75527c785",
-  "contractDigest": "sha256:3ed710d73ac54819396ec372044ec633230fac360b8cad972b4318044d782538"
+  "contractDigest": "sha256:b420ce7d38f966d3a2d72b31ef43490f9720bf0733d1848b1cc497c4a6ac5643"
 }

package/dist/site/buildchain-site.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-bundle",
-  "generatedAt": "2026-07-09T01:16:31.067Z",
-  "publishedAt": "2026-07-09T01:16:31.067Z",
+  "generatedAt": "2026-07-09T03:20:50.735Z",
+  "publishedAt": "2026-07-09T03:20:50.735Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "227aeefaff9a5bbf881d7fb903d39544ef0624af",
+  "sourceRevision": "c7e618f57355231a8f27fd628ee9499bd5b8e9fd",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.10.10",
+    "version": "2.10.11",
     "versionSource": "package.json#version"
   },
   "source": {
@@ -965,7 +965,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/publication-artifacts.md",
-      "digest": "sha256:ef8f4cc214b5fb5f6214796e7688ea897eddb5bc9dd9135638500ce9a1e18c92",
+      "digest": "sha256:06ba810c9eb13d47e408c74d58442635727396da66ed90fd4d505f2ff031cc18",
       "headings": [
         {
           "level": 1,
@@ -993,7 +993,7 @@
           "anchor": "site-consumption"
         }
       ],
-      "markdown": "# Publication Artifact Workflow\n\nBuildchain supports `project.type = \"publication-artifact\"` for repositories\nthat produce auditable papers, reports, specifications, or similar publication\npackages. These repositories are artifact producers. They should not be forced\nto become `web-surface` repositories just because a downstream site later\nrenders the paper.\n\nThe split is:\n\n```text\npaper repo = source, PDF, metadata, source bundle, publication manifest\npapers site = layout, navigation, public web surface, downstream rendering\n```\n\n## Configuration\n\nThe paper repository owns `.buildchain/buildchain.toml`:\n\n```toml\nschema = 1\n\n[project]\ntype = \"publication-artifact\"\nname = \"paper-observer-declared-timelines\"\n\n[publication]\nkind = \"paper\"\ntitle = \"Observer-Declared Timelines for Real-World Agent Work\"\nprimary_artifact = \"_build/main.pdf\"\nartifact_paths = [\"_build/main.pdf\"]\nmetadata_paths = [\"README.md\", \"docs/MAP.md\"]\nsource_paths = [\"paper\", \"README.md\", \"LICENSE\", \"Makefile\"]\nsite_consumers = [\"papers.libkungfu.dev\"]\nmanifest_path = \".buildchain/publication/publication-artifact.json\"\nsource_bundle_path = \".buildchain/publication/source.tar.gz\"\n\n[lifecycle.build]\ncommand = \"make pdf\"\n\n[lifecycle.verify]\ncommand = \"make check\"\n```\n\n`primary_artifact` is the human-facing publication output, usually a PDF.\n`source_paths` are archived into a source bundle. `metadata_paths` are hashed\nand recorded so a site can consume the paper facts without scraping prose.\n\n## Reusable Workflow\n\nConsumer repositories can call the Buildchain wrapper directly:\n\n```yaml\njobs:\n  publication:\n    uses: kungfu-systems/buildchain/.github/workflows/publication-artifact.yml@v2\n    with:\n      build-command: make pdf\n      verify-command: make check\n      artifact-name: observer-declared-timelines\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n```\n\nThe workflow:\n\n- resolves the Buildchain runtime and checks the floating contract lock before\n  any paper build runs;\n- runs the declared build and verify commands;\n- creates a source bundle from `publication.source_paths`;\n- writes `.buildchain/publication/publication-artifact.json`;\n- writes `.buildchain/publication/publication-artifact-passport.json`;\n- uploads one GitHub artifact containing the PDF, manifest, passport, and\n  source bundle.\n\nThe wrapper is build-only. It does not publish npm packages, deploy web pages,\nor create GitHub Releases. Release publication can be layered later by a\nrepository-specific governance workflow that attaches the generated manifest\nand passport as release assets.\n\n## CLI And Node API\n\nGenerate the publication manifest locally or in CI:\n\n```sh\nbuildchain publication-artifact manifest --source-sha \"$(git rev-parse HEAD)\" --json\n```\n\nNode API:\n\n```js\nimport {\n  collectPublicationArtifact,\n  writePublicationArtifact,\n} from \"@kungfu-tech/buildchain/publication-artifact\";\n```\n\n`writePublicationArtifact()` is the single implementation used by the CLI and\nthe reusable workflow. The generated manifest records:\n\n- publication title, kind, authors, and primary artifact;\n- artifact paths, byte sizes, and SHA-256 digests;\n- metadata paths and SHA-256 digests;\n- source SHA, tree SHA, source files, and source bundle digest;\n- timestamp and reproducibility policy;\n- downstream site-consumption hints.\n\nThe companion publication artifact passport records the same source and\nartifact evidence plus an explicit responsibility split. Buildchain proves\ndeclared files and hashes; it does not peer-review paper claims.\n\n## Site Consumption\n\nA downstream papers site should treat the publication manifest as the single\nfact source for the artifact. The site owns rendering and navigation; it should\nnot reinterpret the paper repository as a web deployment source.\n\nFor `paper-observer-declared-timelines`, the expected adoption path is:\n\n```text\npaper repo builds PDF + manifest + source bundle\npapers site consumes publication-artifact.json\nsite renders paper page and links the PDF/source bundle\n```\n\nThis mirrors web-surface governance without mixing producer and renderer\nresponsibilities."
+      "markdown": "# Publication Artifact Workflow\n\nBuildchain supports `project.type = \"publication-artifact\"` for repositories\nthat produce auditable papers, reports, specifications, or similar publication\npackages. These repositories are artifact producers. They should not be forced\nto become `web-surface` repositories just because a downstream site later\nrenders the paper.\n\nThe split is:\n\n```text\npaper repo = source, PDF, metadata, source bundle, publication manifest\npapers site = layout, navigation, public web surface, downstream rendering\n```\n\n## Configuration\n\nThe paper repository owns `.buildchain/buildchain.toml`:\n\n```toml\nschema = 1\n\n[project]\ntype = \"publication-artifact\"\nname = \"paper-observer-declared-timelines\"\n\n[publication]\nkind = \"paper\"\ntitle = \"Observer-Declared Timelines for Real-World Agent Work\"\nprimary_artifact = \"_build/main.pdf\"\nartifact_paths = [\"_build/main.pdf\"]\nmetadata_paths = [\"README.md\", \"docs/MAP.md\"]\nsource_paths = [\"paper\", \"README.md\", \"LICENSE\", \"Makefile\"]\nsite_consumers = [\"papers.libkungfu.dev\"]\nmanifest_path = \".buildchain/publication/publication-artifact.json\"\nsource_bundle_path = \".buildchain/publication/source.tar.gz\"\n\n[publication.toolchain]\ntype = \"latex-docker\"\nimage = \"ghcr.io/kungfu-systems/latex\"\ndigest = \"sha256:0000000000000000000000000000000000000000000000000000000000000000\"\ncommand = \"latexmk -pdf -outdir=_build paper/main.tex\"\n\n[lifecycle.build]\ncommand = \"make pdf\"\n\n[lifecycle.verify]\ncommand = \"make check\"\n```\n\n`primary_artifact` is the human-facing publication output, usually a PDF.\n`source_paths` are archived into a source bundle. `metadata_paths` are hashed\nand recorded so a site can consume the paper facts without scraping prose.\n\n`publication.toolchain` makes the source-to-PDF transformation part of the\nmachine-readable contract. `latex-docker` is the preferred LaTeX profile: the\nworkflow pulls the declared image by digest and runs the declared command in\nthat pinned container. `custom-command` remains available for compatibility,\nbut the passport records it as lower trust because Buildchain can record the\ncommand boundary without proving the compiler or LaTeX distribution digest.\n\n## Reusable Workflow\n\nConsumer repositories can call the Buildchain wrapper directly:\n\n```yaml\njobs:\n  publication:\n    uses: kungfu-systems/buildchain/.github/workflows/publication-artifact.yml@v2\n    with:\n      toolchain-type: config\n      verify-command: make check\n      artifact-name: observer-declared-timelines\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n```\n\nThe workflow:\n\n- resolves the Buildchain runtime and checks the floating contract lock before\n  any paper build runs;\n- resolves the declared publication toolchain from `[publication.toolchain]` or\n  workflow inputs;\n- for `latex-docker`, pulls the pinned image digest and runs the declared\n  command in the container;\n- for `custom-command`, runs the declared command and records the lower-trust\n  boundary in the passport;\n- runs the verify command;\n- creates a source bundle from `publication.source_paths`;\n- writes `.buildchain/publication/publication-artifact.json`;\n- writes `.buildchain/publication/publication-artifact-passport.json`;\n- uploads one GitHub artifact containing the PDF, manifest, passport, and\n  source bundle.\n\nThe wrapper is build-only. It does not publish npm packages, deploy web pages,\nor create GitHub Releases. Release publication can be layered later by a\nrepository-specific governance workflow that attaches the generated manifest\nand passport as release assets.\n\n## CLI And Node API\n\nGenerate the publication manifest locally or in CI:\n\n```sh\nbuildchain publication-artifact manifest --source-sha \"$(git rev-parse HEAD)\" --json\n```\n\nNode API:\n\n```js\nimport {\n  collectPublicationArtifact,\n  writePublicationArtifact,\n} from \"@kungfu-tech/buildchain/publication-artifact\";\n```\n\n`writePublicationArtifact()` is the single implementation used by the CLI and\nthe reusable workflow. The generated manifest records:\n\n- publication title, kind, authors, and primary artifact;\n- artifact paths, byte sizes, and SHA-256 digests;\n- metadata paths and SHA-256 digests;\n- source SHA, tree SHA, source files, and source bundle digest;\n- publication toolchain type, image, digest, command, invocation mode, and trust\n  classification;\n- timestamp and reproducibility policy;\n- downstream site-consumption hints.\n\nThe companion publication artifact passport records the same source and\nartifact evidence plus an explicit responsibility split. Buildchain proves\ndeclared files and hashes; it does not peer-review paper claims.\n\n## Site Consumption\n\nA downstream papers site should treat the publication manifest as the single\nfact source for the artifact. The site owns rendering and navigation; it should\nnot reinterpret the paper repository as a web deployment source.\n\nFor `paper-observer-declared-timelines`, the expected adoption path is:\n\n```text\npaper repo builds PDF + manifest + source bundle\npapers site consumes publication-artifact.json\nsite renders paper page and links the PDF/source bundle\n```\n\nThis mirrors web-surface governance without mixing producer and renderer\nresponsibilities."
     },
     {
       "id": "manual:publish-transaction",

package/dist/site/kfd-claims.json

@@ -21,7 +21,7 @@
     "contract": "kungfu-buildchain-public-surface-reverse-audit",
     "path": "dist/site/public-surface-audit.json",
     "status": "passed",
-    "sha256": "7d22fa037b5c1c14ac2ca1853dd414bb83b2c561221034a49a97401f28672471",
+    "sha256": "a978e2407063ed5d118024da92e28916a90d7704d9948fea52b62e933f7387b4",
     "summary": {
       "cliCommandCount": 73,
       "workflowCount": 36,
@@ -207,7 +207,7 @@
       "contract": "kungfu-buildchain-public-surface-reverse-audit",
       "path": "dist/site/public-surface-audit.json",
       "status": "passed",
-      "sha256": "7d22fa037b5c1c14ac2ca1853dd414bb83b2c561221034a49a97401f28672471",
+      "sha256": "a978e2407063ed5d118024da92e28916a90d7704d9948fea52b62e933f7387b4",
       "summary": {
         "cliCommandCount": 73,
         "workflowCount": 36,
@@ -2895,7 +2895,7 @@
           "visibility": "public",
           "participantFacing": true,
           "public": true,
-          "inputCount": 13,
+          "inputCount": 17,
           "inputs": [
             "artifact-name",
             "artifact-paths",
@@ -2908,6 +2908,10 @@
             "buildchain-repository",
             "node-version",
             "setup-node",
+            "toolchain-command",
+            "toolchain-digest",
+            "toolchain-image",
+            "toolchain-type",
             "verify-command",
             "working-directory"
           ],

package/dist/site/kfd-upstream-aggregate.json

@@ -4,7 +4,7 @@
   "product": {
     "id": "kungfu-tech-buildchain",
     "name": "@kungfu-tech/buildchain",
-    "version": "2.10.10",
+    "version": "2.10.11",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "source": {

package/dist/site/node-api-registry.json

@@ -203,7 +203,7 @@
       "specifier": "@kungfu-tech/buildchain/publication-artifact",
       "export": "./publication-artifact",
       "target": "./packages/core/publication-artifact.js",
-      "digest": "sha256:4d00985aa43a98ca0feee872f889251d7b7b2c8f1a6703316ffc27ad4405e423",
+      "digest": "sha256:03cf19323cf8d4bd7726e07ab615ed74b4ff7ca0b58becd25963ff080993c6ea",
       "summary": "Publication artifact manifest, source bundle, and publication passport APIs.",
       "capabilityGroup": "reusable-build",
       "audience": [

package/dist/site/page-registry.json

@@ -902,7 +902,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/publication-artifacts.md",
-      "digest": "sha256:ef8f4cc214b5fb5f6214796e7688ea897eddb5bc9dd9135638500ce9a1e18c92",
+      "digest": "sha256:06ba810c9eb13d47e408c74d58442635727396da66ed90fd4d505f2ff031cc18",
       "headings": [
         {
           "level": 1,
@@ -930,7 +930,7 @@
           "anchor": "site-consumption"
         }
       ],
-      "markdown": "# Publication Artifact Workflow\n\nBuildchain supports `project.type = \"publication-artifact\"` for repositories\nthat produce auditable papers, reports, specifications, or similar publication\npackages. These repositories are artifact producers. They should not be forced\nto become `web-surface` repositories just because a downstream site later\nrenders the paper.\n\nThe split is:\n\n```text\npaper repo = source, PDF, metadata, source bundle, publication manifest\npapers site = layout, navigation, public web surface, downstream rendering\n```\n\n## Configuration\n\nThe paper repository owns `.buildchain/buildchain.toml`:\n\n```toml\nschema = 1\n\n[project]\ntype = \"publication-artifact\"\nname = \"paper-observer-declared-timelines\"\n\n[publication]\nkind = \"paper\"\ntitle = \"Observer-Declared Timelines for Real-World Agent Work\"\nprimary_artifact = \"_build/main.pdf\"\nartifact_paths = [\"_build/main.pdf\"]\nmetadata_paths = [\"README.md\", \"docs/MAP.md\"]\nsource_paths = [\"paper\", \"README.md\", \"LICENSE\", \"Makefile\"]\nsite_consumers = [\"papers.libkungfu.dev\"]\nmanifest_path = \".buildchain/publication/publication-artifact.json\"\nsource_bundle_path = \".buildchain/publication/source.tar.gz\"\n\n[lifecycle.build]\ncommand = \"make pdf\"\n\n[lifecycle.verify]\ncommand = \"make check\"\n```\n\n`primary_artifact` is the human-facing publication output, usually a PDF.\n`source_paths` are archived into a source bundle. `metadata_paths` are hashed\nand recorded so a site can consume the paper facts without scraping prose.\n\n## Reusable Workflow\n\nConsumer repositories can call the Buildchain wrapper directly:\n\n```yaml\njobs:\n  publication:\n    uses: kungfu-systems/buildchain/.github/workflows/publication-artifact.yml@v2\n    with:\n      build-command: make pdf\n      verify-command: make check\n      artifact-name: observer-declared-timelines\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n```\n\nThe workflow:\n\n- resolves the Buildchain runtime and checks the floating contract lock before\n  any paper build runs;\n- runs the declared build and verify commands;\n- creates a source bundle from `publication.source_paths`;\n- writes `.buildchain/publication/publication-artifact.json`;\n- writes `.buildchain/publication/publication-artifact-passport.json`;\n- uploads one GitHub artifact containing the PDF, manifest, passport, and\n  source bundle.\n\nThe wrapper is build-only. It does not publish npm packages, deploy web pages,\nor create GitHub Releases. Release publication can be layered later by a\nrepository-specific governance workflow that attaches the generated manifest\nand passport as release assets.\n\n## CLI And Node API\n\nGenerate the publication manifest locally or in CI:\n\n```sh\nbuildchain publication-artifact manifest --source-sha \"$(git rev-parse HEAD)\" --json\n```\n\nNode API:\n\n```js\nimport {\n  collectPublicationArtifact,\n  writePublicationArtifact,\n} from \"@kungfu-tech/buildchain/publication-artifact\";\n```\n\n`writePublicationArtifact()` is the single implementation used by the CLI and\nthe reusable workflow. The generated manifest records:\n\n- publication title, kind, authors, and primary artifact;\n- artifact paths, byte sizes, and SHA-256 digests;\n- metadata paths and SHA-256 digests;\n- source SHA, tree SHA, source files, and source bundle digest;\n- timestamp and reproducibility policy;\n- downstream site-consumption hints.\n\nThe companion publication artifact passport records the same source and\nartifact evidence plus an explicit responsibility split. Buildchain proves\ndeclared files and hashes; it does not peer-review paper claims.\n\n## Site Consumption\n\nA downstream papers site should treat the publication manifest as the single\nfact source for the artifact. The site owns rendering and navigation; it should\nnot reinterpret the paper repository as a web deployment source.\n\nFor `paper-observer-declared-timelines`, the expected adoption path is:\n\n```text\npaper repo builds PDF + manifest + source bundle\npapers site consumes publication-artifact.json\nsite renders paper page and links the PDF/source bundle\n```\n\nThis mirrors web-surface governance without mixing producer and renderer\nresponsibilities."
+      "markdown": "# Publication Artifact Workflow\n\nBuildchain supports `project.type = \"publication-artifact\"` for repositories\nthat produce auditable papers, reports, specifications, or similar publication\npackages. These repositories are artifact producers. They should not be forced\nto become `web-surface` repositories just because a downstream site later\nrenders the paper.\n\nThe split is:\n\n```text\npaper repo = source, PDF, metadata, source bundle, publication manifest\npapers site = layout, navigation, public web surface, downstream rendering\n```\n\n## Configuration\n\nThe paper repository owns `.buildchain/buildchain.toml`:\n\n```toml\nschema = 1\n\n[project]\ntype = \"publication-artifact\"\nname = \"paper-observer-declared-timelines\"\n\n[publication]\nkind = \"paper\"\ntitle = \"Observer-Declared Timelines for Real-World Agent Work\"\nprimary_artifact = \"_build/main.pdf\"\nartifact_paths = [\"_build/main.pdf\"]\nmetadata_paths = [\"README.md\", \"docs/MAP.md\"]\nsource_paths = [\"paper\", \"README.md\", \"LICENSE\", \"Makefile\"]\nsite_consumers = [\"papers.libkungfu.dev\"]\nmanifest_path = \".buildchain/publication/publication-artifact.json\"\nsource_bundle_path = \".buildchain/publication/source.tar.gz\"\n\n[publication.toolchain]\ntype = \"latex-docker\"\nimage = \"ghcr.io/kungfu-systems/latex\"\ndigest = \"sha256:0000000000000000000000000000000000000000000000000000000000000000\"\ncommand = \"latexmk -pdf -outdir=_build paper/main.tex\"\n\n[lifecycle.build]\ncommand = \"make pdf\"\n\n[lifecycle.verify]\ncommand = \"make check\"\n```\n\n`primary_artifact` is the human-facing publication output, usually a PDF.\n`source_paths` are archived into a source bundle. `metadata_paths` are hashed\nand recorded so a site can consume the paper facts without scraping prose.\n\n`publication.toolchain` makes the source-to-PDF transformation part of the\nmachine-readable contract. `latex-docker` is the preferred LaTeX profile: the\nworkflow pulls the declared image by digest and runs the declared command in\nthat pinned container. `custom-command` remains available for compatibility,\nbut the passport records it as lower trust because Buildchain can record the\ncommand boundary without proving the compiler or LaTeX distribution digest.\n\n## Reusable Workflow\n\nConsumer repositories can call the Buildchain wrapper directly:\n\n```yaml\njobs:\n  publication:\n    uses: kungfu-systems/buildchain/.github/workflows/publication-artifact.yml@v2\n    with:\n      toolchain-type: config\n      verify-command: make check\n      artifact-name: observer-declared-timelines\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n```\n\nThe workflow:\n\n- resolves the Buildchain runtime and checks the floating contract lock before\n  any paper build runs;\n- resolves the declared publication toolchain from `[publication.toolchain]` or\n  workflow inputs;\n- for `latex-docker`, pulls the pinned image digest and runs the declared\n  command in the container;\n- for `custom-command`, runs the declared command and records the lower-trust\n  boundary in the passport;\n- runs the verify command;\n- creates a source bundle from `publication.source_paths`;\n- writes `.buildchain/publication/publication-artifact.json`;\n- writes `.buildchain/publication/publication-artifact-passport.json`;\n- uploads one GitHub artifact containing the PDF, manifest, passport, and\n  source bundle.\n\nThe wrapper is build-only. It does not publish npm packages, deploy web pages,\nor create GitHub Releases. Release publication can be layered later by a\nrepository-specific governance workflow that attaches the generated manifest\nand passport as release assets.\n\n## CLI And Node API\n\nGenerate the publication manifest locally or in CI:\n\n```sh\nbuildchain publication-artifact manifest --source-sha \"$(git rev-parse HEAD)\" --json\n```\n\nNode API:\n\n```js\nimport {\n  collectPublicationArtifact,\n  writePublicationArtifact,\n} from \"@kungfu-tech/buildchain/publication-artifact\";\n```\n\n`writePublicationArtifact()` is the single implementation used by the CLI and\nthe reusable workflow. The generated manifest records:\n\n- publication title, kind, authors, and primary artifact;\n- artifact paths, byte sizes, and SHA-256 digests;\n- metadata paths and SHA-256 digests;\n- source SHA, tree SHA, source files, and source bundle digest;\n- publication toolchain type, image, digest, command, invocation mode, and trust\n  classification;\n- timestamp and reproducibility policy;\n- downstream site-consumption hints.\n\nThe companion publication artifact passport records the same source and\nartifact evidence plus an explicit responsibility split. Buildchain proves\ndeclared files and hashes; it does not peer-review paper claims.\n\n## Site Consumption\n\nA downstream papers site should treat the publication manifest as the single\nfact source for the artifact. The site owns rendering and navigation; it should\nnot reinterpret the paper repository as a web deployment source.\n\nFor `paper-observer-declared-timelines`, the expected adoption path is:\n\n```text\npaper repo builds PDF + manifest + source bundle\npapers site consumes publication-artifact.json\nsite renders paper page and links the PDF/source bundle\n```\n\nThis mirrors web-surface governance without mixing producer and renderer\nresponsibilities."
     },
     {
       "id": "manual:publish-transaction",

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

@@ -839,10 +839,14 @@
           "buildchain-repository",
           "node-version",
           "setup-node",
+          "toolchain-command",
+          "toolchain-digest",
+          "toolchain-image",
+          "toolchain-type",
           "verify-command",
           "working-directory"
         ],
-        "inputCount": 13
+        "inputCount": 17
       },
       {
         "id": "release-candidate-promote",
@@ -2435,8 +2439,8 @@
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "1f7e1f7707a089f067175030fde6712b69ceece3df1b811eb542b0b4c8c1d4a9",
-    "workflowRegistryDigest": "5a74fd4e5b7b071f014b59d590313535da05e7a96d46b82db0bc306182911395",
-    "pageRegistryDigest": "a32dc62d72d1499d3156711aa51c58c0a19be4cace798617815c98c733e43f8e"
+    "workflowRegistryDigest": "67572429a83124370b9ffd46f56923aa2b252873c9624ded39a26675fb0ee815",
+    "pageRegistryDigest": "c1ec998aced6612b9cf444b886d126a89b344954a1ecebf6908d11610dba3cf8"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-09T01:16:31.067Z",
-  "publishedAt": "2026-07-09T01:16:31.067Z",
+  "generatedAt": "2026-07-09T03:20:50.735Z",
+  "publishedAt": "2026-07-09T03:20:50.735Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "227aeefaff9a5bbf881d7fb903d39544ef0624af",
+  "sourceRevision": "c7e618f57355231a8f27fd628ee9499bd5b8e9fd",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.10.10",
+    "version": "2.10.11",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",

package/dist/site/workflow-registry.json

@@ -544,10 +544,14 @@
         "buildchain-repository",
         "node-version",
         "setup-node",
+        "toolchain-command",
+        "toolchain-digest",
+        "toolchain-image",
+        "toolchain-type",
         "verify-command",
         "working-directory"
       ],
-      "inputCount": 13,
+      "inputCount": 17,
       "surface": "repository-workflow",
       "capabilityGroup": "reusable-build",
       "status": "active"

package/docs/publication-artifacts.md

@@ -35,6 +35,12 @@ site_consumers = ["papers.libkungfu.dev"]
 manifest_path = ".buildchain/publication/publication-artifact.json"
 source_bundle_path = ".buildchain/publication/source.tar.gz"
 
+[publication.toolchain]
+type = "latex-docker"
+image = "ghcr.io/kungfu-systems/latex"
+digest = "sha256:0000000000000000000000000000000000000000000000000000000000000000"
+command = "latexmk -pdf -outdir=_build paper/main.tex"
+
 [lifecycle.build]
 command = "make pdf"
 
@@ -46,6 +52,13 @@ command = "make check"
 `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.
 
+`publication.toolchain` makes the source-to-PDF transformation part of the
+machine-readable contract. `latex-docker` is the preferred LaTeX profile: the
+workflow pulls the declared image by digest and runs the declared command in
+that pinned container. `custom-command` remains available 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.
+
 ## Reusable Workflow
 
 Consumer repositories can call the Buildchain wrapper directly:
@@ -55,7 +68,7 @@ jobs:
   publication:
     uses: kungfu-systems/buildchain/.github/workflows/publication-artifact.yml@v2
     with:
-      build-command: make pdf
+      toolchain-type: config
       verify-command: make check
       artifact-name: observer-declared-timelines
       buildchain-contract-lock-path: .buildchain/contract-lock.json
@@ -65,7 +78,13 @@ The workflow:
 
 - resolves the Buildchain runtime and checks the floating contract lock before
   any paper build runs;
-- runs the declared build and verify commands;
+- resolves the declared publication toolchain from `[publication.toolchain]` or
+  workflow inputs;
+- for `latex-docker`, pulls the pinned image digest and runs the declared
+  command in the container;
+- for `custom-command`, runs the declared command and records the lower-trust
+  boundary in the passport;
+- runs the verify command;
 - creates a source bundle from `publication.source_paths`;
 - writes `.buildchain/publication/publication-artifact.json`;
 - writes `.buildchain/publication/publication-artifact-passport.json`;
@@ -101,6 +120,8 @@ the reusable workflow. The generated manifest records:
 - artifact paths, byte sizes, and SHA-256 digests;
 - metadata paths and SHA-256 digests;
 - source SHA, tree SHA, source files, and source bundle digest;
+- publication toolchain type, image, digest, command, invocation mode, and trust
+  classification;
 - timestamp and reproducibility policy;
 - downstream site-consumption hints.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.10.10",
+  "version": "2.10.11",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",

package/packages/core/buildchain-config.js

@@ -49,6 +49,7 @@ const SUPPORTED_INFRA_ADOPTION_MODES = new Set([
 const SUPPORTED_INFRA_APPLY_MODES = new Set(["disabled", "manual-approval", "environment-approval"]);
 const SUPPORTED_FACT_VERSION_SOURCE_TYPES = new Set(["static", "json", "toml", "regex", "command"]);
 const SUPPORTED_FACT_LEGACY_PROJECTIONS = new Set(["kungfu-buildinfo"]);
+const SUPPORTED_PUBLICATION_TOOLCHAINS = new Set(["custom-command", "latex-docker"]);
 
 function posixPath(value) {
   return String(value || "").split(path.sep).join("/");
@@ -389,6 +390,7 @@ function normalizePublicationSection(publication) {
     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"),
+    toolchain: normalizePublicationToolchain(publication.toolchain),
     manifestPath: publication.manifest_path === undefined
       ? ".buildchain/publication/publication-artifact.json"
       : posixPath(assertString(publication.manifest_path, "publication.manifest_path")),
@@ -398,6 +400,49 @@ function normalizePublicationSection(publication) {
   };
 }
 
+function normalizePublicationToolchain(toolchain = undefined) {
+  if (toolchain === undefined) {
+    return {
+      type: "custom-command",
+      image: "",
+      digest: "",
+      command: "",
+      trustClassification: "custom-command",
+    };
+  }
+  assertPlainObject(toolchain, "publication.toolchain");
+  const type = toolchain.type === undefined
+    ? "custom-command"
+    : assertString(toolchain.type, "publication.toolchain.type");
+  if (!SUPPORTED_PUBLICATION_TOOLCHAINS.has(type)) {
+    throw new Error("publication.toolchain.type must be one of custom-command or latex-docker");
+  }
+  const command = toolchain.command === undefined
+    ? ""
+    : assertString(toolchain.command, "publication.toolchain.command");
+  const image = toolchain.image === undefined
+    ? ""
+    : assertString(toolchain.image, "publication.toolchain.image");
+  const digest = toolchain.digest === undefined
+    ? ""
+    : assertString(toolchain.digest, "publication.toolchain.digest");
+  if (type === "latex-docker") {
+    if (!image) throw new Error("publication.toolchain.image is required for latex-docker");
+    if (!digest) throw new Error("publication.toolchain.digest is required for latex-docker");
+    if (!/^sha256:[0-9a-f]{64}$/i.test(digest)) {
+      throw new Error("publication.toolchain.digest must be a sha256:<64 hex> image digest");
+    }
+    if (!command) throw new Error("publication.toolchain.command is required for latex-docker");
+  }
+  return {
+    type,
+    image,
+    digest,
+    command,
+    trustClassification: type === "latex-docker" ? "pinned-docker-toolchain" : "custom-command",
+  };
+}
+
 function normalizeInfraSection(infra) {
   assertPlainObject(infra, "infra");
   const adapter = assertString(infra.adapter, "infra.adapter");

package/packages/core/publication-artifact.js

@@ -6,6 +6,7 @@ import { loadBuildchainConfig } from "./buildchain-config.js";
 
 export const PUBLICATION_ARTIFACT_MANIFEST_CONTRACT = "kungfu-buildchain-publication-artifact-manifest";
 export const PUBLICATION_ARTIFACT_PASSPORT_CONTRACT = "kungfu-buildchain-publication-artifact-passport";
+const KFD2_RESIDUAL_RISK_SCHEMA = "https://kfd.libkungfu.dev/schemas/kfd-2/trust-taxonomy.schema.json#/$defs/residualRisk";
 
 function toPosix(value) {
   return String(value || "").split(path.sep).join("/");
@@ -74,6 +75,69 @@ function createdAt(now = new Date()) {
   return now.toISOString();
 }
 
+function publicationToolchainFacts(publication) {
+  const envType = String(process.env.BUILDCHAIN_PUBLICATION_TOOLCHAIN_TYPE || "").trim();
+  const envToolchain = envType
+    ? {
+        type: envType,
+        image: process.env.BUILDCHAIN_PUBLICATION_TOOLCHAIN_IMAGE || "",
+        digest: process.env.BUILDCHAIN_PUBLICATION_TOOLCHAIN_DIGEST || "",
+        command: process.env.BUILDCHAIN_PUBLICATION_TOOLCHAIN_COMMAND || "",
+        trustClassification: envType === "latex-docker" ? "pinned-docker-toolchain" : "custom-command",
+      }
+    : undefined;
+  const toolchain = publication.toolchain || {
+    type: "custom-command",
+    image: "",
+    digest: "",
+    command: "",
+    trustClassification: "custom-command",
+  };
+  const resolved = envToolchain || toolchain;
+  const facts = {
+    type: resolved.type,
+    trustClassification: resolved.trustClassification || (resolved.type === "latex-docker" ? "pinned-docker-toolchain" : "custom-command"),
+    command: resolved.command || "",
+    image: resolved.image || "",
+    digest: resolved.digest || "",
+    machineVerifiable: resolved.type === "latex-docker" && Boolean(resolved.image && resolved.digest && resolved.command),
+  };
+  facts.invocation = facts.type === "latex-docker"
+    ? "docker-image-digest"
+    : "caller-provided-command";
+  return facts;
+}
+
+function publicationResidualRisk(toolchainFacts) {
+  const risks = [
+    {
+      id: "publication-semantic-review",
+      definedBy: KFD2_RESIDUAL_RISK_SCHEMA,
+      riskType: "natural-language-semantic-risk",
+      trustImpact: "downgrade-warning",
+      machineProvability: "not-machine-verifiable",
+      agentAction: "semantic-review-required",
+      owner: "publication maintainers",
+      reason: "Buildchain verifies declared files and hashes; it does not peer-review paper claims.",
+      note: "Buildchain verifies declared files and hashes; it does not peer-review paper claims.",
+    },
+  ];
+  if (toolchainFacts.type === "custom-command") {
+    risks.push({
+      id: "publication-custom-build-toolchain",
+      definedBy: KFD2_RESIDUAL_RISK_SCHEMA,
+      riskType: "natural-language-semantic-risk",
+      trustImpact: "downgrade-warning",
+      machineProvability: "not-machine-verifiable",
+      agentAction: "semantic-review-required",
+      owner: "publication maintainers",
+      reason: "The source-to-publication build is a caller-provided command, so Buildchain records the command boundary but cannot prove a pinned compiler or LaTeX image digest.",
+      note: "Use publication.toolchain.type = \"latex-docker\" with an image digest to make the PDF build toolchain machine-auditable.",
+    });
+  }
+  return risks;
+}
+
 export function createPublicationSourceBundle({
   cwd = process.cwd(),
   sourcePaths = [],
@@ -130,6 +194,7 @@ export function collectPublicationArtifact({
   const resolvedSourceSha = sourceSha || gitValue(cwd, ["rev-parse", "HEAD"]);
   const sourceTreeSha = gitValue(cwd, ["rev-parse", `${resolvedSourceSha}^{tree}`]);
   const timestamp = generatedAt || createdAt();
+  const toolchain = publicationToolchainFacts(publication);
   const manifest = {
     schemaVersion: 1,
     contract: PUBLICATION_ARTIFACT_MANIFEST_CONTRACT,
@@ -146,6 +211,7 @@ export function collectPublicationArtifact({
       primaryArtifact: publication.primaryArtifact,
       siteConsumers: publication.siteConsumers,
     },
+    toolchain,
     source: {
       repository: gitValue(cwd, ["config", "--get", "remote.origin.url"]),
       sha: resolvedSourceSha,
@@ -183,6 +249,7 @@ export function collectPublicationArtifact({
       status: "passed",
       manifestDigest: `sha256:${sha256Buffer(Buffer.from(JSON.stringify(manifest, null, 2)))}`,
       source: manifest.source,
+      toolchain,
       artifacts: manifest.artifacts,
       responsibility: {
         producer: "publication repository",
@@ -195,6 +262,9 @@ export function collectPublicationArtifact({
           "declared publication metadata files exist",
           "declared publication source files are hashed",
           "source bundle digest is recorded",
+          toolchain.machineVerifiable
+            ? "publication PDF build toolchain image digest is declared"
+            : "publication build command boundary is recorded",
         ],
         outsideBoundary: [
           "paper scientific claims",
@@ -202,15 +272,7 @@ export function collectPublicationArtifact({
           "human review of publication content",
         ],
       },
-      residualRisk: [
-        {
-          riskType: "natural-language-semantic-risk",
-          trustImpact: "downgrade-warning",
-          machineProvability: "not-machine-verifiable",
-          agentAction: "semantic-review-required",
-          note: "Buildchain verifies declared files and hashes; it does not peer-review paper claims.",
-        },
-      ],
+      residualRisk: publicationResidualRisk(toolchain),
     },
   };
 }

package/scripts/init-repo.mjs

@@ -258,6 +258,10 @@ site_consumers = ["papers-site"]
 manifest_path = ".buildchain/publication/publication-artifact.json"
 source_bundle_path = ".buildchain/publication/source.tar.gz"
 
+[publication.toolchain]
+type = "custom-command"
+command = "make pdf"
+
 [lifecycle.build]
 command = "make pdf"
 
@@ -343,7 +347,7 @@ jobs:
     uses: kungfu-systems/buildchain/.github/workflows/publication-artifact.yml@v2
     with:
       buildchain-ref: \${{ inputs.buildchain-ref || '' }}
-      build-command: make pdf
+      toolchain-type: config
       verify-command: make check
       artifact-name: publication-artifact
 `;