@kungfu-tech/buildchain 2.10.8 → 2.10.9

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

@@ -0,0 +1,120 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-kfd-upstream-aggregate",
+  "product": {
+    "id": "kungfu-tech-buildchain",
+    "name": "@kungfu-tech/buildchain",
+    "version": "2.10.9",
+    "repository": "https://github.com/kungfu-systems/buildchain"
+  },
+  "source": {
+    "generator": "@kungfu-tech/buildchain/kfd.collectKfdUpstreamFacts",
+    "configPath": ".buildchain/buildchain.toml",
+    "autoDiscover": false
+  },
+  "upstreams": [
+    {
+      "id": "kfd",
+      "role": "standard-and-schema-provider",
+      "roleSource": "known-package",
+      "roleReason": "@kungfu-tech/kfd is a Buildchain-known KFD upstream package.",
+      "roleValid": true,
+      "package": {
+        "name": "@kungfu-tech/kfd",
+        "version": "1.0.0-alpha.21"
+      },
+      "repository": "kungfu-systems/kfd",
+      "kfd": {
+        "kfd1": "exported-witness",
+        "kfd2": "exported-claim",
+        "kfd3": "exported-collaboration-interface",
+        "kfd4": "schema-metadata"
+      },
+      "releasePassport": "",
+      "releaseAnchor": {
+        "schemaVersion": 1,
+        "contract": "kfd-release-anchor",
+        "line": "v1.0",
+        "channel": "alpha",
+        "npmPackage": "@kungfu-tech/kfd",
+        "npmVersion": "1.0.0-alpha.21",
+        "source": {
+          "repository": "kungfu-systems/kfd",
+          "branch": "alpha/v1/v1.0"
+        },
+        "rationale": "KFD uses an anchored/manual Buildchain mode: the public package version is an explicit release fact, while the outer KFD line remains v1.0."
+      },
+      "kfd3SurfaceCount": 18,
+      "assets": [
+        {
+          "path": "kfd.release.json",
+          "kind": "package",
+          "sha256": "sha256:bfb302c839b6cb45204d541b5af5b1c211568efb16fb3eebbb04dc65f7de83d2",
+          "contract": "kfd-release-anchor",
+          "role": "",
+          "directory": false
+        },
+        {
+          "path": ".buildchain/kfd-1/contract-world.witness.json",
+          "kind": "package",
+          "sha256": "sha256:542fe5b730f2e4782655d096ec04a5dd82a88d4fc9e8701ee235eb111a06dab6",
+          "contract": "",
+          "role": "",
+          "directory": false
+        },
+        {
+          "path": ".buildchain/kfd-2/public-release-trust.claim.json",
+          "kind": "package",
+          "sha256": "sha256:3780b47472762b5ce9575250da73ee800af71dd194a9b0a3f61a063569311237",
+          "contract": "",
+          "role": "",
+          "directory": false
+        },
+        {
+          "path": ".buildchain/kfd-2/kfd-foundation.trust-claims.json",
+          "kind": "package",
+          "sha256": "sha256:87757bd26c8f64465472aaafda05fe56497939a3ce66274563c142594d9d769b",
+          "contract": "kfd-2-trust-claims",
+          "role": "",
+          "directory": false
+        },
+        {
+          "path": ".buildchain/kfd-2/kfd-foundation.trust-assessment.json",
+          "kind": "package",
+          "sha256": "sha256:c3749585bb4a295bb2f0f510a4b6030f0398d9a09dc50dab0ace31248bf95b0f",
+          "contract": "kfd-2-trust-assessment",
+          "role": "",
+          "directory": false
+        },
+        {
+          "path": ".buildchain/kfd-3/collaboration-interface.json",
+          "kind": "package",
+          "sha256": "sha256:fa41128be4ee57a4a40b76d4d7a063c01d7c2e5c53aec2b9c6db819c7a27b22b",
+          "contract": "kfd-3-collaboration-interface",
+          "role": "",
+          "directory": false
+        },
+        {
+          "path": "standards.json",
+          "kind": "package",
+          "sha256": "sha256:4ee9e5fc732eef1b43c75a146125496e0dbd859ef5a11d0c637c41e9091c677f",
+          "contract": "kfd-standards-metadata",
+          "role": "",
+          "directory": false
+        }
+      ],
+      "residualRisk": [],
+      "status": "collected"
+    }
+  ],
+  "summary": {
+    "upstreamCount": 1,
+    "kfdAwareUpstreams": [
+      "kfd"
+    ],
+    "packageVersions": {
+      "kfd": "1.0.0-alpha.21"
+    },
+    "status": "collected"
+  }
+}

package/dist/site/manual-registry.json

@@ -245,7 +245,7 @@
       "title": "KFD support and KFD-3 surface registration",
       "path": "docs/kfd-support.md",
       "plane": "verify",
-      "digest": "sha256:d1fdec0890884340e4e8108c17b62866c08dc95771075e3e285532b5a7b0ee5a",
+      "digest": "sha256:4bcf5d1ce63555072130eae90c739555b11658d1d796a3fcea770b90841c4afd",
       "capabilityGroup": "kfd-trust",
       "audience": [
         "agent",

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

@@ -125,8 +125,8 @@
       "specifier": "@kungfu-tech/buildchain/kfd",
       "export": "./kfd",
       "target": "./packages/core/kfd.js",
-      "digest": "sha256:e9170c1e56d2729cf530f953df9ade21963faa9a756ba5fbd0cdd03d8b781cb3",
-      "summary": "Unified KFD standards, schema discovery, KFD-1/KFD-2/KFD-3 grouped APIs, KFD-4 schema discovery, and Buildchain KFD claim helpers.",
+      "digest": "sha256:843c68350fe5cefdd94bfe49355ab60d4b52ce63c5e52d1874a3e8ec78244070",
+      "summary": "Unified KFD standards, schema discovery, KFD-1/KFD-2/KFD-3 grouped APIs, KFD-4 schema discovery, upstream KFD aggregate facts, and Buildchain KFD claim helpers.",
       "capabilityGroup": "kfd-trust",
       "audience": [
         "developer",
@@ -177,7 +177,7 @@
       "specifier": "@kungfu-tech/buildchain/public-surface-audit",
       "export": "./public-surface-audit",
       "target": "./packages/core/public-surface-audit.js",
-      "digest": "sha256:22b8354a876962400f47070b5917141faace5589c2b40fe54ed004816d6735d4",
+      "digest": "sha256:21e866a27cf96f6385f1fe2f3f0f73526fb9bba4c409334dbf9b34a886c80450",
       "summary": "Reverse audit APIs for CLI, workflow, action, site page, and documentation command surfaces.",
       "capabilityGroup": "kfd-trust",
       "audience": [
@@ -268,7 +268,7 @@
       "specifier": "@kungfu-tech/buildchain/buildchain-kfd-claims",
       "export": "./buildchain-kfd-claims",
       "target": "./packages/core/buildchain-kfd-claims.js",
-      "digest": "sha256:e800194bd945e6727d2e467d3dc155e0df95c656d58047590d12e5174ca84463",
+      "digest": "sha256:a61fd06fa065808eb6b1205b0748ae8801525dbb22cb902122b62fddde48c355",
       "summary": "Buildchain self KFD claim registry, witnesses, and public claim APIs.",
       "capabilityGroup": "kfd-trust",
       "audience": [
@@ -292,7 +292,7 @@
     {
       "id": "kfd-support",
       "path": "docs/kfd-support.md",
-      "digest": "sha256:d1fdec0890884340e4e8108c17b62866c08dc95771075e3e285532b5a7b0ee5a"
+      "digest": "sha256:4bcf5d1ce63555072130eae90c739555b11658d1d796a3fcea770b90841c4afd"
     },
     {
       "id": "readme-badges",

package/dist/site/page-registry.json

@@ -532,7 +532,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/kfd-support.md",
-      "digest": "sha256:d1fdec0890884340e4e8108c17b62866c08dc95771075e3e285532b5a7b0ee5a",
+      "digest": "sha256:4bcf5d1ce63555072130eae90c739555b11658d1d796a3fcea770b90841c4afd",
       "headings": [
         {
           "level": 1,
@@ -554,6 +554,16 @@
           "title": "KFD-2",
           "anchor": "kfd-2"
         },
+        {
+          "level": 2,
+          "title": "Upstream KFD Aggregation",
+          "anchor": "upstream-kfd-aggregation"
+        },
+        {
+          "level": 3,
+          "title": "Upstream Roles",
+          "anchor": "upstream-roles"
+        },
         {
           "level": 2,
           "title": "KFD-3",
@@ -590,7 +600,7 @@
           "anchor": "known-gaps"
         }
       ],
-      "markdown": "# KFD Support\n\nBuildchain implements KFD support as release evidence and product capability\nfacts, not as README prose. The machine-readable sources are:\n\n- `dist/site/kfd-claims.json` for Buildchain-owned public claims and KFD-3\n  collaboration surfaces;\n- `dist/site/public-surface-audit.json` for reverse enumeration of exposed CLI,\n  workflow, action, site, and documented command surfaces;\n- `buildchain.release.json` for release-specific KFD-1, KFD-2, and KFD-3\n  passport results;\n- `.buildchain/buildchain.toml` for repository-owned Buildchain configuration;\n- `.buildchain/kfd/kfd-3-surfaces.json` for product-owned KFD-3 surface\n  registration;\n- `.buildchain/contract-lock.json` for accepted floating runtime contracts.\n\nBuildchain still reads the legacy root files `buildchain.toml`,\n`buildchain.contract-lock.json`, and `buildchain.kfd3.json` so existing\nconsumers do not break, but new repositories should keep repo-owned Buildchain\nfiles under `.buildchain/`.\n\n## Unified Namespace\n\nKFD support is exposed through one first-class namespace:\n\n```bash\nbuildchain kfd status --json\nbuildchain kfd migrate-layout --write\nbuildchain kfd schema list --json\nbuildchain kfd 1 witness --json\nbuildchain kfd 2 claims --json\nbuildchain kfd 2 trust-claims --json\nbuildchain kfd 2 trust-assessment --json\nbuildchain kfd 3 query buildchain --json\nbuildchain kfd 4 schema --json\n```\n\nKFD-1, KFD-2, and KFD-3 have concrete Buildchain workflows. KFD-4 is currently\nschema-only in Buildchain: agents can discover and read the KFD-4 schema from\n`@kungfu-tech/kfd`, but Buildchain does not claim KFD-4 verification.\n\n## KFD-1\n\nKFD-1 proves that a product release is bound to one contract world. Buildchain\nuses KFD-1 for its runtime contract, release-passport schemas, packaged docs,\nNode exports, workflows, actions, and site-consumption facts.\n\nFor Buildchain itself, the source registry lives in\n`packages/core/buildchain-kfd-claims.js` and is projected to\n`dist/site/kfd-claims.json`. Release promotion binds that registry to exact\nsource and artifact hashes in the release passport.\n\nBuildchain exposes KFD-1 through:\n\n```bash\nbuildchain kfd 1 schema --json\nbuildchain kfd 1 witness --json\nbuildchain kfd 1 gate --witness-json kfd-1-witness.json --json\nbuildchain kfd 1 verify --gate-json kfd-1-gate.json --json\n```\n\n## KFD-2\n\nKFD-2 requires public trust claims to be backed by machine-readable evidence.\nBuildchain release passports fail or downgrade claims that only have prose.\n\nEvery public claim binds:\n\n- declared source files;\n- machine-readable evidence;\n- source, evidence, and artifact hashes;\n- artifact coordinates;\n- verification result;\n- audit boundary;\n- responsibility state;\n- residual risk.\n\nBuildchain exposes KFD-2 through:\n\n```bash\nbuildchain kfd 2 schema --json\nbuildchain kfd 2 taxonomy --entry-json residual-risk.json --kind residualRisk --json\nbuildchain kfd 2 claims --json\nbuildchain kfd 2 trust-claims --json\nbuildchain kfd 2 trust-assessment --json\n```\n\n`claims` generates Buildchain's release-passport public claim inputs. The\n`trust-claims` and `trust-assessment` commands expose the latest KFD package's\nfoundation KFD-2 facts from `@kungfu-tech/kfd` and validate their taxonomy\nvalues against the KFD-owned `trust-taxonomy` schema. Unknown `riskType`,\n`trustImpact`, `machineProvability`, or `agentAction` values fail validation;\nnew values must be requested upstream in `kungfu-systems/kfd`, not invented in\nBuildchain.\n\n## KFD-3\n\nKFD-3 closes participant-facing collaboration surfaces over a declared public\ninterface. Buildchain supports two complementary KFD-3 layers.\n\nThe first layer is Buildchain self-verification. Buildchain reverse-enumerates\nreal CLI commands, reusable workflow inputs, action inputs, site pages, and\ndocumented command references, then compares those facts with the generated\nregistries in `dist/site/`. A missing registry entry fails `pnpm run check`.\n\nThe second layer is product surface registration. Products can ask Buildchain to\ndetect standard public surfaces, write a small product-owned registry, audit the\nregistry against the current artifact/source tree, generate a release-passport\ncompatible witness, and query the resulting capability map.\n\n## Detected, Declared, Enforced\n\nKFD-3 surface registration uses three states.\n\n| State | Meaning |\n| --- | --- |\n| `detected` | Buildchain found a candidate public surface from package metadata, wheel metadata, CLI bins, binary artifacts, docs, or site bundle facts. |\n| `declared` | The product owner accepted that candidate into `.buildchain/kfd/kfd-3-surfaces.json`. |\n| `enforced` | The product has promoted a declared surface to a hard release boundary. Missing enforced surfaces fail release verification. |\n\nDetection does not silently become product intent. `register` is the boundary\ndecision. Existing consumers are unaffected until they opt in.\n\n## CLI\n\nInspect KFD-owned schema facts:\n\n```bash\nbuildchain kfd schema list --json\nbuildchain kfd schema show kfd-1 --json\nbuildchain kfd 4 schema --json\n```\n\nThe KFD schema namespace is discovered from `@kungfu-tech/kfd/standards.json`.\nFor KFD-2 this includes `trustClaims`, `trustAssessment`, `trustTaxonomy`,\n`releaseClaims`, and `releaseTrustPassport`. For KFD-4 Buildchain currently\nexposes the KFD-owned `observerPerspective` schema only.\n\nDetect public surface candidates:\n\n```bash\nbuildchain kfd 3 detect --json\nbuildchain kfd 3 detect --kind node-api --kind cli --json\n```\n\nRegister standard surface classes:\n\n```bash\nbuildchain kfd 3 register node-api --product Buildchain\nbuildchain kfd 3 register cli\nbuildchain kfd 3 register python-api --artifact dist/wheel-unpacked\n```\n\nAudit detected, declared, and enforced surfaces:\n\n```bash\nbuildchain kfd 3 audit --json\n```\n\nGenerate a witness for release passport collection:\n\n```bash\nbuildchain kfd 3 witness \\\n  --kind prebuild \\\n  --output .buildchain/kfd-3/collaboration-interface.prebuild.json\n```\n\nQuery capability facts for agents or downstream sites:\n\n```bash\nbuildchain kfd 3 query buildchain --json\nbuildchain kfd 3 query --passport .buildchain/release-passport/buildchain.release.json --json\n```\n\n## Node API\n\nThe CLI is a thin wrapper over the public Node API:\n\n```js\nimport {\n  kfd1,\n  kfd2,\n  kfd3,\n  kfd4,\n  collectKfdStatus,\n  listKfdSchemas,\n  readKfdSchema,\n} from \"@kungfu-tech/buildchain/kfd\";\n```\n\nAgents should start with `collectKfdStatus()` to learn which standards are\nimplemented and where the repository-owned Buildchain files live. For capability\nuse decisions, prefer `kfd3.queryCapabilities()`. The query result connects each\ncapability to:\n\n- KFD-3 surface identity and state;\n- KFD-1 basis facts such as source and artifact paths or digests;\n- KFD-2 trust evidence when a release passport is attached;\n- residual risk and recommended agent action.\n\n## Standard Detectors\n\nThe initial detector set is intentionally conservative:\n\n- npm packages: `package.json` `exports`, `main`, `types`, and `bin`;\n- Python wheels: unpacked `.dist-info/METADATA`, `RECORD`,\n  `entry_points.txt`, and `top_level.txt`;\n- CLI binaries: `package.json#bin` and files under `bin/`;\n- standalone binaries and archives: common binary/archive outputs under\n  artifact directories such as `dist/`;\n- documentation: `README.md`, `AGENTS.md`, and `docs/*.md`;\n- site bundles: `dist/site/*.json`.\n\nPython importability alone is not considered public API. A product can extend\nthe registry over time, but the first boundary is metadata-based.\n\n## Buildchain Self Dogfood\n\nBuildchain dogfoods this model in two ways:\n\n- `buildchain kfd 1 witness --json` generates Buildchain's own KFD-1 contract\n  world witness;\n- `buildchain kfd 2 claims --json` generates Buildchain's own KFD-2 public\n  claim evidence;\n- `buildchain kfd 2 trust-claims --json` and\n  `buildchain kfd 2 trust-assessment --json` expose and validate the KFD\n  package's foundation KFD-2 trust facts against the latest KFD taxonomy;\n- `dist/site/kfd-claims.json` declares Buildchain's own KFD-3 collaboration\n  interface;\n- `buildchain kfd 3 query buildchain --json` resolves the packaged\n  Buildchain capability map from that site fact source.\n\nThis lets downstream agents discover Buildchain's supported CLI, Node API,\nrelease passport, workflow, and site bundle surfaces from the npm package\ninstead of scraping source files or README examples.\n\n## Known Gaps\n\nArchive unpacking for `.whl`, `.tar.gz`, `.zip`, and platform-native installers\nis intentionally not part of the first detector. Callers can point\n`--artifact` at an unpacked artifact directory. Future Buildchain versions can\nadd archive readers without changing the registry contract."
+      "markdown": "# KFD Support\n\nBuildchain implements KFD support as release evidence and product capability\nfacts, not as README prose. The machine-readable sources are:\n\n- `dist/site/kfd-claims.json` for Buildchain-owned public claims and KFD-3\n  collaboration surfaces;\n- `dist/site/public-surface-audit.json` for reverse enumeration of exposed CLI,\n  workflow, action, site, and documented command surfaces;\n- `buildchain.release.json` for release-specific KFD-1, KFD-2, and KFD-3\n  passport results;\n- `.buildchain/buildchain.toml` for repository-owned Buildchain configuration;\n- `.buildchain/kfd/kfd-3-surfaces.json` for product-owned KFD-3 surface\n  registration;\n- `.buildchain/contract-lock.json` for accepted floating runtime contracts.\n\nBuildchain still reads the legacy root files `buildchain.toml`,\n`buildchain.contract-lock.json`, and `buildchain.kfd3.json` so existing\nconsumers do not break, but new repositories should keep repo-owned Buildchain\nfiles under `.buildchain/`.\n\n## Unified Namespace\n\nKFD support is exposed through one first-class namespace:\n\n```bash\nbuildchain kfd status --json\nbuildchain kfd migrate-layout --write\nbuildchain kfd schema list --json\nbuildchain kfd 1 witness --json\nbuildchain kfd 2 claims --json\nbuildchain kfd 2 trust-claims --json\nbuildchain kfd 2 trust-assessment --json\nbuildchain kfd upstream roles --json\nbuildchain kfd upstream collect --json\nbuildchain kfd upstream check --json\nbuildchain kfd aggregate --json\nbuildchain kfd 3 query buildchain --json\nbuildchain kfd 4 schema --json\n```\n\nKFD-1, KFD-2, and KFD-3 have concrete Buildchain workflows. KFD-4 is currently\nschema-only in Buildchain: agents can discover and read the KFD-4 schema from\n`@kungfu-tech/kfd`, but Buildchain does not claim KFD-4 verification.\n\n## KFD-1\n\nKFD-1 proves that a product release is bound to one contract world. Buildchain\nuses KFD-1 for its runtime contract, release-passport schemas, packaged docs,\nNode exports, workflows, actions, and site-consumption facts.\n\nFor Buildchain itself, the source registry lives in\n`packages/core/buildchain-kfd-claims.js` and is projected to\n`dist/site/kfd-claims.json`. Release promotion binds that registry to exact\nsource and artifact hashes in the release passport.\n\nBuildchain exposes KFD-1 through:\n\n```bash\nbuildchain kfd 1 schema --json\nbuildchain kfd 1 witness --json\nbuildchain kfd 1 gate --witness-json kfd-1-witness.json --json\nbuildchain kfd 1 verify --gate-json kfd-1-gate.json --json\n```\n\n## KFD-2\n\nKFD-2 requires public trust claims to be backed by machine-readable evidence.\nBuildchain release passports fail or downgrade claims that only have prose.\n\nEvery public claim binds:\n\n- declared source files;\n- machine-readable evidence;\n- source, evidence, and artifact hashes;\n- artifact coordinates;\n- verification result;\n- audit boundary;\n- responsibility state;\n- residual risk.\n\nBuildchain exposes KFD-2 through:\n\n```bash\nbuildchain kfd 2 schema --json\nbuildchain kfd 2 taxonomy --entry-json residual-risk.json --kind residualRisk --json\nbuildchain kfd 2 claims --json\nbuildchain kfd 2 trust-claims --json\nbuildchain kfd 2 trust-assessment --json\n```\n\n`claims` generates Buildchain's release-passport public claim inputs. The\n`trust-claims` and `trust-assessment` commands expose the latest KFD package's\nfoundation KFD-2 facts from `@kungfu-tech/kfd` and validate their taxonomy\nvalues against the KFD-owned `trust-taxonomy` schema. Unknown `riskType`,\n`trustImpact`, `machineProvability`, or `agentAction` values fail validation;\nnew values must be requested upstream in `kungfu-systems/kfd`, not invented in\nBuildchain.\n\n`@kungfu-tech/kfd` is a runtime dependency of Buildchain, not a development-only\ndependency. The public `buildchain kfd ...` CLI and `@kungfu-tech/buildchain/kfd`\nNode API read KFD-owned standards metadata, schemas, foundation trust claims,\nfoundation trust assessments, and taxonomy values at runtime. Moving KFD to\n`devDependencies` would make installed Buildchain packages unable to answer KFD\nqueries in consumer repositories.\n\n## Upstream KFD Aggregation\n\nProducts often depend on multiple KFD-aware upstream components. A product's own\nKFD status is not the same thing as the status of those upstreams, but agents\nstill need one machine-readable view of the upstream trust surface.\n\nBuildchain exposes that view through:\n\n```bash\nbuildchain kfd upstream roles --json\nbuildchain kfd upstream collect --json\nbuildchain kfd upstream check --json\nbuildchain kfd aggregate --json\n```\n\n`upstream collect` reads `.buildchain/buildchain.toml`, resolves declared\npackages from the caller repository, hashes declared evidence assets, and emits\na `kungfu-buildchain-kfd-upstream-aggregate` document. `upstream check` validates\nthat aggregate. `aggregate` combines the product's own Buildchain KFD status\nwith the upstream aggregate.\n\nThis works in development before the consuming repository has published an\nalpha or release. In that state Buildchain can collect and check upstream\nfacts, versions, hashes, roles, and residual risk, but the consuming product\nmust not claim its own KFD status as `passed` until a release passport verifies\nthat product release.\n\nThe repository-owned declaration is intentionally small. Consumers normally\ndeclare the upstream package identity, not Buildchain's inferred role or a\nduplicate semver:\n\n```toml\n[kfd.upstream]\nauto_discover = false\n\n[[kfd.upstream.components]]\nid = \"kfd\"\npackage = \"@kungfu-tech/kfd\"\nrepository = \"kungfu-systems/kfd\"\nevidence = [\n  \"package:kfd.release.json\",\n  \"package:.buildchain/kfd-1/contract-world.witness.json\",\n  \"package:.buildchain/kfd-2/public-release-trust.claim.json\",\n  \"package:.buildchain/kfd-3/collaboration-interface.json\",\n  \"package:standards.json\",\n]\n```\n\nThe upstream package version is a single source of truth owned by the package\nmanager. Put the dependency in `package.json` / the lockfile, then let\nBuildchain read the installed package's real `package.json`:\n\n```json\n{\n  \"devDependencies\": {\n    \"@kungfu-tech/kfd\": \"1.0.0-alpha.21\"\n  }\n}\n```\n\nMost consumers should keep `@kungfu-tech/kfd` in `devDependencies`: Buildchain\nuses it during CI, development checks, release evidence collection, and site\ngeneration. Move it to `dependencies` only if the product's own runtime imports\nKFD directly. Buildchain itself keeps KFD in `dependencies` because its public\nCLI and Node API resolve KFD standards, schemas, taxonomy, and foundation trust\nfacts at runtime.\n\nDo not repeat upstream semver values in `.buildchain/buildchain.toml`. Repeating\nversions in both `package.json` and Buildchain config creates stale facts.\n`upstream collect` records the actual installed package version and evidence\nhashes in the aggregate output.\n\n`kfd_1`, `kfd_2`, `kfd_3`, and `kfd_4` are optional capability-state hints. When\nomitted, Buildchain treats the component as `declared`. Use explicit values only\nwhen the upstream package really exposes the corresponding machine evidence,\nfor example:\n\n```toml\nkfd_1 = \"exported-witness\"\nkfd_2 = \"exported-claim\"\nkfd_3 = \"exported-collaboration-interface\"\nkfd_4 = \"schema-metadata\"\n```\n\nAn upstream component may be `declared`, `aligned`, `exported-*`, or another\nexplicit non-passed state when the evidence is package-local. A component may\nclaim `passed` only when the aggregate also binds that component to a release\npassport. Upstream `passed` never upgrades the product's own KFD status; it only\ndescribes the upstream trust surface consumed by the product.\n\n### Upstream Roles\n\nConsumers should normally omit `role`. Buildchain owns the role vocabulary and\ninfers the role from package identity and evidence. The aggregate records:\n\n- `role` - the normalized Buildchain-managed role;\n- `roleSource` - `known-package`, `evidence`, `default`, or `explicit`;\n- `roleReason` - the machine-readable explanation for the chosen role.\n\nThe managed role registry is queryable:\n\n```bash\nbuildchain kfd upstream roles --json\n```\n\nCurrent roles are:\n\n| Role | Meaning |\n| --- | --- |\n| `standard-and-schema-provider` | Provides KFD standards, schemas, taxonomy, or standard-owned witness and claim facts. |\n| `release-passport-and-kfd-gate-provider` | Provides release passport, KFD gate, release claim, or release governance machinery consumed by the product. |\n| `kfd-aware-product-component` | A product component that exposes KFD witness, claim, collaboration-interface, or package evidence without being core KFD infrastructure. |\n| `site-consumption-provider` | Provides site-consumption facts such as site manifests, site bundles, or downstream page-content contracts. |\n| `unknown-kfd-upstream` | Fallback for a declared upstream that has not matched a Buildchain-known package or role-specific evidence. |\n\nIf a consumer explicitly writes `role`, it must be one of that registry. Unknown\nexplicit values fail closed during `upstream check`; Buildchain will not let\nrepositories invent local role spellings that later fragment aggregate reports.\n\nBuildchain dogfoods this model with `@kungfu-tech/kfd` as its upstream\nstandard-and-schema provider. The generated site bundle includes\n`dist/site/kfd-upstream-aggregate.json` so downstream sites and agents can read\nBuildchain's upstream KFD facts from the npm package instead of scraping\nrepository scripts.\n\n## KFD-3\n\nKFD-3 closes participant-facing collaboration surfaces over a declared public\ninterface. Buildchain supports two complementary KFD-3 layers.\n\nThe first layer is Buildchain self-verification. Buildchain reverse-enumerates\nreal CLI commands, reusable workflow inputs, action inputs, site pages, and\ndocumented command references, then compares those facts with the generated\nregistries in `dist/site/`. A missing registry entry fails `pnpm run check`.\n\nThe second layer is product surface registration. Products can ask Buildchain to\ndetect standard public surfaces, write a small product-owned registry, audit the\nregistry against the current artifact/source tree, generate a release-passport\ncompatible witness, and query the resulting capability map.\n\n## Detected, Declared, Enforced\n\nKFD-3 surface registration uses three states.\n\n| State | Meaning |\n| --- | --- |\n| `detected` | Buildchain found a candidate public surface from package metadata, wheel metadata, CLI bins, binary artifacts, docs, or site bundle facts. |\n| `declared` | The product owner accepted that candidate into `.buildchain/kfd/kfd-3-surfaces.json`. |\n| `enforced` | The product has promoted a declared surface to a hard release boundary. Missing enforced surfaces fail release verification. |\n\nDetection does not silently become product intent. `register` is the boundary\ndecision. Existing consumers are unaffected until they opt in.\n\n## CLI\n\nInspect KFD-owned schema facts:\n\n```bash\nbuildchain kfd schema list --json\nbuildchain kfd schema show kfd-1 --json\nbuildchain kfd 4 schema --json\n```\n\nThe KFD schema namespace is discovered from `@kungfu-tech/kfd/standards.json`.\nFor KFD-2 this includes `trustClaims`, `trustAssessment`, `trustTaxonomy`,\n`releaseClaims`, and `releaseTrustPassport`. For KFD-4 Buildchain currently\nexposes the KFD-owned `observerPerspective` schema only.\n\nDetect public surface candidates:\n\n```bash\nbuildchain kfd 3 detect --json\nbuildchain kfd 3 detect --kind node-api --kind cli --json\n```\n\nRegister standard surface classes:\n\n```bash\nbuildchain kfd 3 register node-api --product Buildchain\nbuildchain kfd 3 register cli\nbuildchain kfd 3 register python-api --artifact dist/wheel-unpacked\n```\n\nAudit detected, declared, and enforced surfaces:\n\n```bash\nbuildchain kfd 3 audit --json\n```\n\nGenerate a witness for release passport collection:\n\n```bash\nbuildchain kfd 3 witness \\\n  --kind prebuild \\\n  --output .buildchain/kfd-3/collaboration-interface.prebuild.json\n```\n\nQuery capability facts for agents or downstream sites:\n\n```bash\nbuildchain kfd 3 query buildchain --json\nbuildchain kfd 3 query --passport .buildchain/release-passport/buildchain.release.json --json\n```\n\n## Node API\n\nThe CLI is a thin wrapper over the public Node API:\n\n```js\nimport {\n  kfd1,\n  kfd2,\n  kfd3,\n  kfd4,\n  upstream,\n  collectKfdAggregate,\n  collectKfdStatus,\n  collectKfdUpstreamFacts,\n  checkKfdUpstreamFacts,\n  listKfdUpstreamRoles,\n  listKfdSchemas,\n  readKfdSchema,\n} from \"@kungfu-tech/buildchain/kfd\";\n```\n\nAgents should start with `collectKfdStatus()` to learn which standards are\nimplemented and where the repository-owned Buildchain files live. For capability\nuse decisions, prefer `kfd3.queryCapabilities()`. The query result connects each\ncapability to:\n\n- KFD-3 surface identity and state;\n- KFD-1 basis facts such as source and artifact paths or digests;\n- KFD-2 trust evidence when a release passport is attached;\n- residual risk and recommended agent action.\n\n## Standard Detectors\n\nThe initial detector set is intentionally conservative:\n\n- npm packages: `package.json` `exports`, `main`, `types`, and `bin`;\n- Python wheels: unpacked `.dist-info/METADATA`, `RECORD`,\n  `entry_points.txt`, and `top_level.txt`;\n- CLI binaries: `package.json#bin` and files under `bin/`;\n- standalone binaries and archives: common binary/archive outputs under\n  artifact directories such as `dist/`;\n- documentation: `README.md`, `AGENTS.md`, and `docs/*.md`;\n- site bundles: `dist/site/*.json`.\n\nPython importability alone is not considered public API. A product can extend\nthe registry over time, but the first boundary is metadata-based.\n\n## Buildchain Self Dogfood\n\nBuildchain dogfoods this model in two ways:\n\n- `buildchain kfd 1 witness --json` generates Buildchain's own KFD-1 contract\n  world witness;\n- `buildchain kfd 2 claims --json` generates Buildchain's own KFD-2 public\n  claim evidence;\n- `buildchain kfd 2 trust-claims --json` and\n  `buildchain kfd 2 trust-assessment --json` expose and validate the KFD\n  package's foundation KFD-2 trust facts against the latest KFD taxonomy;\n- `dist/site/kfd-claims.json` declares Buildchain's own KFD-3 collaboration\n  interface;\n- `buildchain kfd 3 query buildchain --json` resolves the packaged\n  Buildchain capability map from that site fact source.\n\nThis lets downstream agents discover Buildchain's supported CLI, Node API,\nrelease passport, workflow, and site bundle surfaces from the npm package\ninstead of scraping source files or README examples.\n\n## Known Gaps\n\nArchive unpacking for `.whl`, `.tar.gz`, `.zip`, and platform-native installers\nis intentionally not part of the first detector. Callers can point\n`--artifact` at an unpacked artifact directory. Future Buildchain versions can\nadd archive readers without changing the registry contract."
     },
     {
       "id": "manual:lifecycle-protocol",

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

@@ -3,11 +3,11 @@
   "contract": "kungfu-buildchain-public-surface-reverse-audit",
   "status": "passed",
   "summary": {
-    "cliCommandCount": 67,
+    "cliCommandCount": 71,
     "workflowCount": 35,
     "actionCount": 4,
     "sitePageCount": 43,
-    "docCommandRefCount": 214,
+    "docCommandRefCount": 224,
     "failureCount": 0
   },
   "enumerated": {
@@ -212,6 +212,11 @@
         "source": "bin/buildchain.mjs",
         "usage": "buildchain kfd 4 schema [--schema <name>] [--json]"
       },
+      {
+        "id": "kfd-aggregate",
+        "source": "bin/buildchain.mjs",
+        "usage": "buildchain kfd aggregate [--cwd <dir>] [--json]"
+      },
       {
         "id": "kfd-migrate-layout",
         "source": "bin/buildchain.mjs",
@@ -232,6 +237,21 @@
         "source": "bin/buildchain.mjs",
         "usage": "buildchain kfd status [--cwd <dir>] [--json]"
       },
+      {
+        "id": "kfd-upstream-check",
+        "source": "bin/buildchain.mjs",
+        "usage": "buildchain kfd upstream check [--cwd <dir>] [--aggregate-json <file-or-json>] [--json]"
+      },
+      {
+        "id": "kfd-upstream-collect",
+        "source": "bin/buildchain.mjs",
+        "usage": "buildchain kfd upstream collect [--cwd <dir>] [--output <file>] [--json]"
+      },
+      {
+        "id": "kfd-upstream-roles",
+        "source": "bin/buildchain.mjs",
+        "usage": "buildchain kfd upstream roles [--json]"
+      },
       {
         "id": "lifecycle",
         "source": "bin/buildchain.mjs",
@@ -1854,6 +1874,16 @@
         "path": "docs/kfd-support.md",
         "command": "buildchain kfd 4 schema"
       },
+      {
+        "id": "kfd-aggregate",
+        "path": "docs/kfd-support.md",
+        "command": "buildchain kfd aggregate --json"
+      },
+      {
+        "id": "kfd-aggregate",
+        "path": "docs/kfd-support.md",
+        "command": "buildchain kfd aggregate --json"
+      },
       {
         "id": "kfd-migrate-layout",
         "path": "docs/cli.md",
@@ -1899,11 +1929,51 @@
         "path": "docs/kfd-support.md",
         "command": "buildchain kfd status --json"
       },
+      {
+        "id": "kfd-upstream-check",
+        "path": "docs/kfd-support.md",
+        "command": "buildchain kfd upstream check"
+      },
+      {
+        "id": "kfd-upstream-check",
+        "path": "docs/kfd-support.md",
+        "command": "buildchain kfd upstream check"
+      },
+      {
+        "id": "kfd-upstream-collect",
+        "path": "docs/kfd-support.md",
+        "command": "buildchain kfd upstream collect"
+      },
+      {
+        "id": "kfd-upstream-collect",
+        "path": "docs/kfd-support.md",
+        "command": "buildchain kfd upstream collect"
+      },
+      {
+        "id": "kfd-upstream-roles",
+        "path": "docs/kfd-support.md",
+        "command": "buildchain kfd upstream roles"
+      },
+      {
+        "id": "kfd-upstream-roles",
+        "path": "docs/kfd-support.md",
+        "command": "buildchain kfd upstream roles"
+      },
+      {
+        "id": "kfd-upstream-roles",
+        "path": "docs/kfd-support.md",
+        "command": "buildchain kfd upstream roles"
+      },
       {
         "id": "kfd",
         "path": "docs/cli.md",
         "command": "buildchain kfd"
       },
+      {
+        "id": "kfd",
+        "path": "docs/kfd-support.md",
+        "command": "buildchain kfd"
+      },
       {
         "id": "kfd",
         "path": "README.md",
@@ -2310,9 +2380,9 @@
     "cliRegistryPath": "dist/site/cli-registry.json",
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
-    "cliRegistryDigest": "a3cec96bbde43078fa328afb51e0c0e9df87f4aab494ea4b9841a05a67261f00",
+    "cliRegistryDigest": "239414b93a2165625ea54f124377ad270355ca8c0764f4ff2a8ebc9ad78f2832",
     "workflowRegistryDigest": "7ec4a7f4f2d81ec294a4b961f6f991c3e90bacb6f516a5138736399d461d9aee",
-    "pageRegistryDigest": "aa643d3ca72fb1bed26ad0f1f5c910ae49eeb6a2a57850ab0bfdc538b221308c"
+    "pageRegistryDigest": "23c900280e3c30ca9886d74a5f744961f2b2c5a202743d264d423f0bb29c9eee"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/release-provenance.json

@@ -39,6 +39,7 @@
       "./site/kfd-claims.json": "./dist/site/kfd-claims.json",
       "./site/workflow-registry.json": "./dist/site/workflow-registry.json",
       "./site/public-surface-audit.json": "./dist/site/public-surface-audit.json",
+      "./site/kfd-upstream-aggregate.json": "./dist/site/kfd-upstream-aggregate.json",
       "./site/release-model.json": "./dist/site/release-model.json",
       "./site/artifact-schemas.json": "./dist/site/artifact-schemas.json",
       "./site/buildchain-contract.json": "./dist/site/buildchain-contract.json",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-08T15:35:10.464Z",
-  "publishedAt": "2026-07-08T15:35:10.464Z",
+  "generatedAt": "2026-07-09T00:25:26.922Z",
+  "publishedAt": "2026-07-09T00:25:26.922Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "09ef484f589c8cb3e0c053c0ab3ec2542e2eb5f1",
+  "sourceRevision": "bdd863e4ac8fa7b502a23f7e9a8faf9d31535c19",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.10.8",
+    "version": "2.10.9",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -189,7 +189,7 @@
       "path": "docs/kfd-support.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:d1fdec0890884340e4e8108c17b62866c08dc95771075e3e285532b5a7b0ee5a"
+      "digest": "sha256:4bcf5d1ce63555072130eae90c739555b11658d1d796a3fcea770b90841c4afd"
     },
     {
       "id": "lifecycle-protocol",
@@ -269,6 +269,7 @@
     "badge-endpoint-registry.json",
     "product-mechanism.json",
     "release-provenance.json",
+    "kfd-upstream-aggregate.json",
     "kfd-claims.json",
     "agent-index.json"
   ]

package/docs/kfd-support.md

@@ -31,6 +31,10 @@ buildchain kfd 1 witness --json
 buildchain kfd 2 claims --json
 buildchain kfd 2 trust-claims --json
 buildchain kfd 2 trust-assessment --json
+buildchain kfd upstream roles --json
+buildchain kfd upstream collect --json
+buildchain kfd upstream check --json
+buildchain kfd aggregate --json
 buildchain kfd 3 query buildchain --json
 buildchain kfd 4 schema --json
 ```
@@ -93,6 +97,138 @@ values against the KFD-owned `trust-taxonomy` schema. Unknown `riskType`,
 new values must be requested upstream in `kungfu-systems/kfd`, not invented in
 Buildchain.
 
+`@kungfu-tech/kfd` is a runtime dependency of Buildchain, not a development-only
+dependency. The public `buildchain kfd ...` CLI and `@kungfu-tech/buildchain/kfd`
+Node API read KFD-owned standards metadata, schemas, foundation trust claims,
+foundation trust assessments, and taxonomy values at runtime. Moving KFD to
+`devDependencies` would make installed Buildchain packages unable to answer KFD
+queries in consumer repositories.
+
+## Upstream KFD Aggregation
+
+Products often depend on multiple KFD-aware upstream components. A product's own
+KFD status is not the same thing as the status of those upstreams, but agents
+still need one machine-readable view of the upstream trust surface.
+
+Buildchain exposes that view through:
+
+```bash
+buildchain kfd upstream roles --json
+buildchain kfd upstream collect --json
+buildchain kfd upstream check --json
+buildchain kfd aggregate --json
+```
+
+`upstream collect` reads `.buildchain/buildchain.toml`, resolves declared
+packages from the caller repository, hashes declared evidence assets, and emits
+a `kungfu-buildchain-kfd-upstream-aggregate` document. `upstream check` validates
+that aggregate. `aggregate` combines the product's own Buildchain KFD status
+with the upstream aggregate.
+
+This works in development before the consuming repository has published an
+alpha or release. In that state Buildchain can collect and check upstream
+facts, versions, hashes, roles, and residual risk, but the consuming product
+must not claim its own KFD status as `passed` until a release passport verifies
+that product release.
+
+The repository-owned declaration is intentionally small. Consumers normally
+declare the upstream package identity, not Buildchain's inferred role or a
+duplicate semver:
+
+```toml
+[kfd.upstream]
+auto_discover = false
+
+[[kfd.upstream.components]]
+id = "kfd"
+package = "@kungfu-tech/kfd"
+repository = "kungfu-systems/kfd"
+evidence = [
+  "package:kfd.release.json",
+  "package:.buildchain/kfd-1/contract-world.witness.json",
+  "package:.buildchain/kfd-2/public-release-trust.claim.json",
+  "package:.buildchain/kfd-3/collaboration-interface.json",
+  "package:standards.json",
+]
+```
+
+The upstream package version is a single source of truth owned by the package
+manager. Put the dependency in `package.json` / the lockfile, then let
+Buildchain read the installed package's real `package.json`:
+
+```json
+{
+  "devDependencies": {
+    "@kungfu-tech/kfd": "1.0.0-alpha.21"
+  }
+}
+```
+
+Most consumers should keep `@kungfu-tech/kfd` in `devDependencies`: Buildchain
+uses it during CI, development checks, release evidence collection, and site
+generation. Move it to `dependencies` only if the product's own runtime imports
+KFD directly. Buildchain itself keeps KFD in `dependencies` because its public
+CLI and Node API resolve KFD standards, schemas, taxonomy, and foundation trust
+facts at runtime.
+
+Do not repeat upstream semver values in `.buildchain/buildchain.toml`. Repeating
+versions in both `package.json` and Buildchain config creates stale facts.
+`upstream collect` records the actual installed package version and evidence
+hashes in the aggregate output.
+
+`kfd_1`, `kfd_2`, `kfd_3`, and `kfd_4` are optional capability-state hints. When
+omitted, Buildchain treats the component as `declared`. Use explicit values only
+when the upstream package really exposes the corresponding machine evidence,
+for example:
+
+```toml
+kfd_1 = "exported-witness"
+kfd_2 = "exported-claim"
+kfd_3 = "exported-collaboration-interface"
+kfd_4 = "schema-metadata"
+```
+
+An upstream component may be `declared`, `aligned`, `exported-*`, or another
+explicit non-passed state when the evidence is package-local. A component may
+claim `passed` only when the aggregate also binds that component to a release
+passport. Upstream `passed` never upgrades the product's own KFD status; it only
+describes the upstream trust surface consumed by the product.
+
+### Upstream Roles
+
+Consumers should normally omit `role`. Buildchain owns the role vocabulary and
+infers the role from package identity and evidence. The aggregate records:
+
+- `role` - the normalized Buildchain-managed role;
+- `roleSource` - `known-package`, `evidence`, `default`, or `explicit`;
+- `roleReason` - the machine-readable explanation for the chosen role.
+
+The managed role registry is queryable:
+
+```bash
+buildchain kfd upstream roles --json
+```
+
+Current roles are:
+
+| Role | Meaning |
+| --- | --- |
+| `standard-and-schema-provider` | Provides KFD standards, schemas, taxonomy, or standard-owned witness and claim facts. |
+| `release-passport-and-kfd-gate-provider` | Provides release passport, KFD gate, release claim, or release governance machinery consumed by the product. |
+| `kfd-aware-product-component` | A product component that exposes KFD witness, claim, collaboration-interface, or package evidence without being core KFD infrastructure. |
+| `site-consumption-provider` | Provides site-consumption facts such as site manifests, site bundles, or downstream page-content contracts. |
+| `unknown-kfd-upstream` | Fallback for a declared upstream that has not matched a Buildchain-known package or role-specific evidence. |
+
+If a consumer explicitly writes `role`, it must be one of that registry. Unknown
+explicit values fail closed during `upstream check`; Buildchain will not let
+repositories invent local role spellings that later fragment aggregate reports.
+
+Buildchain dogfoods this model with `@kungfu-tech/kfd` as its upstream
+standard-and-schema provider. The generated site bundle includes
+`dist/site/kfd-upstream-aggregate.json` so downstream sites and agents can read
+Buildchain's upstream KFD facts from the npm package instead of scraping
+repository scripts.
+
 ## KFD-3
 
 KFD-3 closes participant-facing collaboration surfaces over a declared public
@@ -182,7 +318,12 @@ import {
   kfd2,
   kfd3,
   kfd4,
+  upstream,
+  collectKfdAggregate,
   collectKfdStatus,
+  collectKfdUpstreamFacts,
+  checkKfdUpstreamFacts,
+  listKfdUpstreamRoles,
   listKfdSchemas,
   readKfdSchema,
 } from "@kungfu-tech/buildchain/kfd";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.10.8",
+  "version": "2.10.9",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -42,6 +42,7 @@
     "./site/kfd-claims.json": "./dist/site/kfd-claims.json",
     "./site/workflow-registry.json": "./dist/site/workflow-registry.json",
     "./site/public-surface-audit.json": "./dist/site/public-surface-audit.json",
+    "./site/kfd-upstream-aggregate.json": "./dist/site/kfd-upstream-aggregate.json",
     "./site/release-model.json": "./dist/site/release-model.json",
     "./site/artifact-schemas.json": "./dist/site/artifact-schemas.json",
     "./site/buildchain-contract.json": "./dist/site/buildchain-contract.json",

package/packages/core/buildchain-kfd-claims.js

@@ -56,6 +56,7 @@ const SITE_CONTRACT_FILES = Object.freeze([
   "dist/site/release-provenance.json",
   "dist/site/agent-index.json",
   "dist/site/kfd-claims.json",
+  "dist/site/kfd-upstream-aggregate.json",
 ]);
 
 const SCHEMA_AND_STANDARD_FILES = Object.freeze([