@kungfu-tech/buildchain 2.10.8 → 2.10.9

package/bin/buildchain.mjs

@@ -65,10 +65,14 @@ import {
   writeKungfuBuildInfoProjection,
 } from "../packages/core/build-facts.js";
 import {
+  checkKfdUpstreamFacts,
+  collectKfdAggregate,
   collectKfdStatus,
+  collectKfdUpstreamFacts,
   kfd1,
   kfd2,
   layout as buildchainLayout,
+  listKfdUpstreamRoles,
   listKfdSchemas,
   normalizeKfdStandardId,
   readKfdSchema,
@@ -161,6 +165,10 @@ function usage() {
   buildchain kfd migrate-layout [--cwd <dir>] [--write] [--force] [--json]
   buildchain kfd schema list [--standard kfd-1|kfd-2|kfd-3|kfd-4] [--json]
   buildchain kfd schema show <kfd-1|kfd-2|kfd-3|kfd-4> [--schema <name>] [--json]
+  buildchain kfd upstream roles [--json]
+  buildchain kfd upstream collect [--cwd <dir>] [--output <file>] [--json]
+  buildchain kfd upstream check [--cwd <dir>] [--aggregate-json <file-or-json>] [--json]
+  buildchain kfd aggregate [--cwd <dir>] [--json]
   buildchain kfd 1 schema [--schema <name>] [--json]
   buildchain kfd 1 witness [--cwd <dir>] [--source-sha <sha>] [--output <file>] [--json]
   buildchain kfd 1 gate --witness-json <file-or-json>... [--cwd <dir>] [--artifact-root <dir>]
@@ -226,6 +234,8 @@ Examples:
   buildchain kfd 1 witness --json
   buildchain kfd 2 claims --json
   buildchain kfd 2 trust-assessment --json
+  buildchain kfd upstream collect --json
+  buildchain kfd aggregate --json
   buildchain kfd 3 query buildchain --json
 `;
 }
@@ -810,7 +820,7 @@ function runKfd2Cli(args = []) {
 async function runKfdCli(args = []) {
   const [subcommand = "", maybeStandardOrAction = "", ...rest] = args;
   if (!subcommand) {
-    throw new Error("usage: buildchain kfd <status|migrate-layout|schema|1|2|3|4> ...");
+    throw new Error("usage: buildchain kfd <status|migrate-layout|schema|upstream|aggregate|1|2|3|4> ...");
   }
 
   if (subcommand === "status") {
@@ -880,6 +890,71 @@ async function runKfdCli(args = []) {
     throw new Error("usage: buildchain kfd schema <list|show> ...");
   }
 
+  if (subcommand === "upstream") {
+    const [action = "", ...upstreamArgs] = [maybeStandardOrAction, ...rest];
+    const effectiveAction = action || "collect";
+    const cwd = path.resolve(readFlag(upstreamArgs, "cwd", process.cwd()));
+    const json = readBooleanFlag(upstreamArgs, "json");
+    if (effectiveAction === "roles") {
+      const result = listKfdUpstreamRoles();
+      if (json) {
+        printJson(result);
+      } else {
+        process.stdout.write("KFD upstream roles:\n");
+        for (const entry of result.roles) {
+          process.stdout.write(`- ${entry.role}: ${entry.description}\n`);
+        }
+      }
+      return;
+    }
+    if (effectiveAction === "collect") {
+      const result = collectKfdUpstreamFacts({ cwd });
+      const output = readFlag(upstreamArgs, "output", "");
+      if (output) {
+        fs.mkdirSync(path.dirname(path.resolve(cwd, output)), { recursive: true });
+        fs.writeFileSync(path.resolve(cwd, output), `${JSON.stringify(result, null, 2)}\n`);
+      }
+      if (json || !output) {
+        printJson(result);
+      } else {
+        process.stdout.write(`kfd upstream collect: wrote ${output}\n`);
+      }
+      return;
+    }
+    if (effectiveAction === "check") {
+      const aggregateInput = readFlag(upstreamArgs, "aggregate-json", "");
+      const aggregate = aggregateInput
+        ? readJsonInput(aggregateInput, { cwd, label: "kfd upstream aggregate" })
+        : collectKfdUpstreamFacts({ cwd });
+      const result = checkKfdUpstreamFacts(aggregate);
+      if (json) {
+        printJson(result);
+      } else {
+        process.stdout.write(`kfd upstream check: ${result.status} (${result.upstreamCount} upstreams)\n`);
+        for (const entry of result.issues) {
+          process.stdout.write(`- ${entry.level}: ${entry.code}: ${entry.message}\n`);
+        }
+      }
+      if (!result.ok) {
+        process.exitCode = 1;
+      }
+      return;
+    }
+    throw new Error("usage: buildchain kfd upstream <roles|collect|check> ...");
+  }
+
+  if (subcommand === "aggregate") {
+    const effectiveArgs = maybeStandardOrAction && maybeStandardOrAction.startsWith("--") ? [maybeStandardOrAction, ...rest] : rest;
+    const cwd = path.resolve(readFlag(effectiveArgs, "cwd", process.cwd()));
+    const result = collectKfdAggregate({ cwd });
+    if (readBooleanFlag(effectiveArgs, "json")) {
+      printJson(result);
+    } else {
+      process.stdout.write(`kfd aggregate: upstream=${result.upstream.summary.upstreamCount}, status=${result.upstreamCheck.status}\n`);
+    }
+    return;
+  }
+
   const standard = normalizeKfdStandardId(subcommand);
   if (standard === "kfd-1") {
     runKfd1Cli([maybeStandardOrAction, ...rest]);
@@ -903,7 +978,7 @@ async function runKfdCli(args = []) {
     }
     throw new Error("KFD-4 is currently schema-only in Buildchain; use: buildchain kfd 4 schema");
   }
-  throw new Error("usage: buildchain kfd <status|migrate-layout|schema|1|2|3|4> ...");
+  throw new Error("usage: buildchain kfd <status|migrate-layout|schema|upstream|aggregate|1|2|3|4> ...");
 }
 
 async function runBuildFactsCli(args = []) {

package/dist/site/agent-index.json

@@ -14,6 +14,7 @@
     "public-surface-audit.json",
     "artifact-schemas.json",
     "buildchain-contract.json",
+    "kfd-upstream-aggregate.json",
     "kfd-claims.json",
     "badge-endpoint-registry.json"
   ],

package/dist/site/buildchain-contract.json

@@ -4,7 +4,7 @@
   "product": {
     "name": "Buildchain",
     "package": "@kungfu-tech/buildchain",
-    "version": "2.10.8",
+    "version": "2.10.9",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "majorLine": "v2",
@@ -344,7 +344,7 @@
         "README badge block checks and writes are generated from machine-readable repository facts"
       ],
       "breakingDigest": "sha256:90a73892b2d6c214048448d5f45df75639bdf7b7e8fefd9c596e04b087407bcc",
-      "auditDigest": "sha256:7116471b0795a716a651d8b594fcfe8457bd544a2523faf9d7deafd84d2bf0a3"
+      "auditDigest": "sha256:34b5fa8a801e82667bdf2578ad64274623a4635daa5e080f51cee422a4ed0ba4"
     },
     {
       "contractVersion": 1,
@@ -434,7 +434,7 @@
         "manual entries carry source file digests so downstream sites and agents can detect stale hand-written documentation"
       ],
       "breakingDigest": "sha256:7d0d2819e3a3e72989d9c57b5efe9d0bc0a79bc0f2c82a0c7b9d6c5a211a91f2",
-      "auditDigest": "sha256:c921dfad0945f943f24f566f4a53c6156f3057cf94336cbc840f062b26288864"
+      "auditDigest": "sha256:044cc7ec44c343b450be076db2d1604cb5f52afda6fca3eef67bc3a0960a2a06"
     },
     {
       "contractVersion": 1,
@@ -456,9 +456,9 @@
         "agents can discover supported Node APIs without importing internal file paths"
       ],
       "breakingDigest": "sha256:48f925608d3e2131d90936b07dc2a30341204cae3e6e785c0f77d61ad755c945",
-      "auditDigest": "sha256:46c5938144888f76be429af2c10a16ead94c046c8c6f35965e4d8db647e3c08c"
+      "auditDigest": "sha256:896ddcc6c808d92fd757e087632bcfb069378046008d70132d7de74138f03b76"
     }
   ],
   "compatibilityDigest": "sha256:967df7e854fdf582294ddfb6403eff25c00db9518a24051e7d47cbd75527c785",
-  "contractDigest": "sha256:5a30e9e625f2643c30c0cda4a7825f336f616a39e356166aa32233fd2328c343"
+  "contractDigest": "sha256:511d42f392bdf81805b067079c2c436d7c13f013833215ebe93e6c5b512c10b0"
 }

package/dist/site/buildchain-site.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-bundle",
-  "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"
   },
   "source": {
@@ -69,6 +69,7 @@
     "badge-endpoint-registry.json",
     "product-mechanism.json",
     "release-provenance.json",
+    "kfd-upstream-aggregate.json",
     "kfd-claims.json",
     "agent-index.json",
     "site-manifest.json"
@@ -594,7 +595,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/kfd-support.md",
-      "digest": "sha256:d1fdec0890884340e4e8108c17b62866c08dc95771075e3e285532b5a7b0ee5a",
+      "digest": "sha256:4bcf5d1ce63555072130eae90c739555b11658d1d796a3fcea770b90841c4afd",
       "headings": [
         {
           "level": 1,
@@ -616,6 +617,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",
@@ -652,7 +663,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",
@@ -2238,7 +2249,7 @@
       "path": "docs/kfd-support.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:d1fdec0890884340e4e8108c17b62866c08dc95771075e3e285532b5a7b0ee5a"
+      "digest": "sha256:4bcf5d1ce63555072130eae90c739555b11658d1d796a3fcea770b90841c4afd"
     },
     {
       "id": "lifecycle-protocol",
@@ -2373,6 +2384,7 @@
       "public surface reverse audit",
       "manual and Node API registries",
       "KFD claim registry",
+      "KFD upstream aggregate registry",
       "release-passport evidence vocabulary"
     ],
     "ownedBySite": [

package/dist/site/capability-registry.json

@@ -32,6 +32,7 @@
         "cli-registry.json",
         "node-api-registry.json",
         "workflow-registry.json",
+        "kfd-upstream-aggregate.json",
         "kfd-claims.json"
       ]
     },
@@ -63,6 +64,7 @@
         "cli-registry.json",
         "node-api-registry.json",
         "workflow-registry.json",
+        "kfd-upstream-aggregate.json",
         "kfd-claims.json"
       ]
     },
@@ -94,6 +96,7 @@
         "cli-registry.json",
         "node-api-registry.json",
         "workflow-registry.json",
+        "kfd-upstream-aggregate.json",
         "kfd-claims.json"
       ]
     },
@@ -109,7 +112,7 @@
       "counts": {
         "manualCount": 1,
         "pageCount": 1,
-        "cliCommandCount": 21,
+        "cliCommandCount": 25,
         "nodeApiCount": 5,
         "workflowCount": 0,
         "actionCount": 0
@@ -123,6 +126,7 @@
         "cli-registry.json",
         "node-api-registry.json",
         "workflow-registry.json",
+        "kfd-upstream-aggregate.json",
         "kfd-claims.json"
       ]
     },
@@ -155,6 +159,7 @@
         "cli-registry.json",
         "node-api-registry.json",
         "workflow-registry.json",
+        "kfd-upstream-aggregate.json",
         "kfd-claims.json"
       ]
     },
@@ -186,6 +191,7 @@
         "cli-registry.json",
         "node-api-registry.json",
         "workflow-registry.json",
+        "kfd-upstream-aggregate.json",
         "kfd-claims.json"
       ]
     },
@@ -217,6 +223,7 @@
         "cli-registry.json",
         "node-api-registry.json",
         "workflow-registry.json",
+        "kfd-upstream-aggregate.json",
         "kfd-claims.json"
       ]
     },
@@ -252,6 +259,7 @@
         "cli-registry.json",
         "node-api-registry.json",
         "workflow-registry.json",
+        "kfd-upstream-aggregate.json",
         "kfd-claims.json"
       ]
     },
@@ -281,6 +289,7 @@
         "cli-registry.json",
         "node-api-registry.json",
         "workflow-registry.json",
+        "kfd-upstream-aggregate.json",
         "kfd-claims.json"
       ]
     }

package/dist/site/cli-registry.json

@@ -485,6 +485,18 @@
       ],
       "maturity": "stable"
     },
+    {
+      "id": "kfd-aggregate",
+      "source": "bin/buildchain.mjs",
+      "usage": "buildchain kfd aggregate [--cwd <dir>] [--json]",
+      "purpose": "Return a product KFD view that combines own KFD status with upstream KFD aggregate facts.",
+      "capabilityGroup": "kfd-trust",
+      "audience": [
+        "agent",
+        "operator"
+      ],
+      "maturity": "stable"
+    },
     {
       "id": "kfd-migrate-layout",
       "source": "bin/buildchain.mjs",
@@ -533,6 +545,42 @@
       ],
       "maturity": "stable"
     },
+    {
+      "id": "kfd-upstream-check",
+      "source": "bin/buildchain.mjs",
+      "usage": "buildchain kfd upstream check [--cwd <dir>] [--aggregate-json <file-or-json>] [--json]",
+      "purpose": "Validate a KFD upstream aggregate document and fail closed on missing evidence.",
+      "capabilityGroup": "kfd-trust",
+      "audience": [
+        "agent",
+        "operator"
+      ],
+      "maturity": "stable"
+    },
+    {
+      "id": "kfd-upstream-collect",
+      "source": "bin/buildchain.mjs",
+      "usage": "buildchain kfd upstream collect [--cwd <dir>] [--output <file>] [--json]",
+      "purpose": "Collect declared KFD-aware upstream package evidence and hashes from Buildchain config.",
+      "capabilityGroup": "kfd-trust",
+      "audience": [
+        "agent",
+        "operator"
+      ],
+      "maturity": "stable"
+    },
+    {
+      "id": "kfd-upstream-roles",
+      "source": "bin/buildchain.mjs",
+      "usage": "buildchain kfd upstream roles [--json]",
+      "purpose": "List Buildchain-managed KFD upstream role values and inference policy.",
+      "capabilityGroup": "kfd-trust",
+      "audience": [
+        "agent",
+        "operator"
+      ],
+      "maturity": "stable"
+    },
     {
       "id": "lifecycle",
       "source": "bin/buildchain.mjs",

package/dist/site/kfd-claims.json

@@ -21,13 +21,13 @@
     "contract": "kungfu-buildchain-public-surface-reverse-audit",
     "path": "dist/site/public-surface-audit.json",
     "status": "passed",
-    "sha256": "6431d84ece43e64ec51f31f4a563501181253bd02fcc1789164102158e50c119",
+    "sha256": "9a3e5bce8fd3bdf9a48d76db89b7d464358db7c31d4753ac78cbbda664463565",
     "summary": {
-      "cliCommandCount": 67,
+      "cliCommandCount": 71,
       "workflowCount": 35,
       "actionCount": 4,
       "sitePageCount": 43,
-      "docCommandRefCount": 214,
+      "docCommandRefCount": 224,
       "failureCount": 0
     },
     "auditBoundary": {
@@ -207,13 +207,13 @@
       "contract": "kungfu-buildchain-public-surface-reverse-audit",
       "path": "dist/site/public-surface-audit.json",
       "status": "passed",
-      "sha256": "6431d84ece43e64ec51f31f4a563501181253bd02fcc1789164102158e50c119",
+      "sha256": "9a3e5bce8fd3bdf9a48d76db89b7d464358db7c31d4753ac78cbbda664463565",
       "summary": {
-        "cliCommandCount": 67,
+        "cliCommandCount": 71,
         "workflowCount": 35,
         "actionCount": 4,
         "sitePageCount": 43,
-        "docCommandRefCount": 214,
+        "docCommandRefCount": 224,
         "failureCount": 0
       },
       "auditBoundary": {
@@ -1310,6 +1310,17 @@
           "visibility": "public",
           "participantFacing": true,
           "public": true
+        },
+        {
+          "id": "site:dist/site/kfd-upstream-aggregate.json",
+          "name": "site:dist/site/kfd-upstream-aggregate.json",
+          "kind": "site-consumption-contract",
+          "sourcePath": "dist/site/kfd-upstream-aggregate.json",
+          "evidencePath": "dist/site/kfd-upstream-aggregate.json",
+          "availability": "shipped",
+          "visibility": "public",
+          "participantFacing": true,
+          "public": true
         }
       ],
       "reverseEnumeratedSurfaces": [
@@ -1793,6 +1804,18 @@
           "public": true,
           "reverseAuditSource": "bin/buildchain.mjs"
         },
+        {
+          "id": "cli:kfd-aggregate",
+          "name": "buildchain kfd aggregate [--cwd <dir>] [--json]",
+          "kind": "cli-command",
+          "sourcePath": "bin/buildchain.mjs",
+          "evidencePath": "bin/buildchain.mjs",
+          "availability": "shipped",
+          "visibility": "public",
+          "participantFacing": true,
+          "public": true,
+          "reverseAuditSource": "bin/buildchain.mjs"
+        },
         {
           "id": "cli:kfd-migrate-layout",
           "name": "buildchain kfd migrate-layout [--cwd <dir>] [--write] [--force] [--json]",
@@ -1841,6 +1864,42 @@
           "public": true,
           "reverseAuditSource": "bin/buildchain.mjs"
         },
+        {
+          "id": "cli:kfd-upstream-check",
+          "name": "buildchain kfd upstream check [--cwd <dir>] [--aggregate-json <file-or-json>] [--json]",
+          "kind": "cli-command",
+          "sourcePath": "bin/buildchain.mjs",
+          "evidencePath": "bin/buildchain.mjs",
+          "availability": "shipped",
+          "visibility": "public",
+          "participantFacing": true,
+          "public": true,
+          "reverseAuditSource": "bin/buildchain.mjs"
+        },
+        {
+          "id": "cli:kfd-upstream-collect",
+          "name": "buildchain kfd upstream collect [--cwd <dir>] [--output <file>] [--json]",
+          "kind": "cli-command",
+          "sourcePath": "bin/buildchain.mjs",
+          "evidencePath": "bin/buildchain.mjs",
+          "availability": "shipped",
+          "visibility": "public",
+          "participantFacing": true,
+          "public": true,
+          "reverseAuditSource": "bin/buildchain.mjs"
+        },
+        {
+          "id": "cli:kfd-upstream-roles",
+          "name": "buildchain kfd upstream roles [--json]",
+          "kind": "cli-command",
+          "sourcePath": "bin/buildchain.mjs",
+          "evidencePath": "bin/buildchain.mjs",
+          "availability": "shipped",
+          "visibility": "public",
+          "participantFacing": true,
+          "public": true,
+          "reverseAuditSource": "bin/buildchain.mjs"
+        },
         {
           "id": "cli:lifecycle",
           "name": "buildchain lifecycle run <stage> [--cwd <dir>] [--required]",
@@ -3722,6 +3781,6 @@
         "public": true
       }
     ],
-    "publicSurfaceCount": 247
+    "publicSurfaceCount": 252
   }
 }