@kungfu-tech/buildchain 2.14.14-alpha.3 → 2.14.14-alpha.5

package/README.md

@@ -25,6 +25,27 @@ its existing CI.
 
 The same mechanism releases Buildchain itself.
 
+## Where Buildchain sits in the Agent Supply Chain
+
+Buildchain binds a product's declarations to the exact source cut, build,
+artifacts, checks, and promotion record that produced a release. In the wider
+Agent Supply Chain it sits between KFD-3 product discovery and KFD-2
+purpose-bound assessment:
+
+```text
+KFD-3 declaration -> Buildchain exact-artifact evidence -> KFD-2 assessment
+```
+
+Buildchain can prove that a declared claim and an exact artifact remain
+consistent, or fail/downgrade when their evidence drifts. It does not invent
+the product fact, decide whether a receiver should trust it for a purpose,
+certify every platform, or prove external adoption. Receivers and downstream
+KFD-2 assessors retain the admission decision and residual risk.
+
+To evaluate the layer, inspect a release's `buildchain.release.json` and
+`artifact-evidence.json`, verify them with the CLI, and report missing product
+or protocol evidence through the repository issue tracker.
+
 ## Install and Verify
 
 For standalone use, install a platform archive from a GitHub Release and verify

package/bin/buildchain.mjs

@@ -33,6 +33,12 @@ import {
   explainReleasePassport,
   verifyReleasePassport,
 } from "../packages/core/release-passport.js";
+import {
+  explainKfdAgentHub,
+  initKfdAgentHub,
+  inspectKfdAgentHub,
+  testKfdAgentHub,
+} from "../packages/core/kfd-agent-hub.js";
 import {
   createPublicationAdmission,
   createRunnerProvenance,
@@ -159,6 +165,7 @@ function usage() {
                                     [--kfd-3-artifact-verify-cmd <command>]
                                     [--invariant-passport-json <json-or-path>]...
                                     [--invariant-passport-cmd <command>]
+                                    [--kfd-agent-hub-evidence-json <json-or-path>]
                                     [--base-passport-json <json-or-path>] [--require-base-kfd]
                                     [--release-extra-json <json-or-path>]
                                     [--publish-json <json-or-path>] [--output-dir <dir>] [--json]
@@ -218,6 +225,9 @@ function usage() {
                              [--output <file>] [--json]
   buildchain facts verify [--cwd <dir>] --fact <file> [--json]
   buildchain kfd ...
+  buildchain kfd hub <init|inspect|test|explain> [--cwd <dir>]
+                     [--declaration <path>] [--output-dir <path>]
+                     [--write] [--force] [--for agent] [--json]
   buildchain kfd status [--cwd <dir>] [--json]
   buildchain kfd migrate-layout [--cwd <dir>] [--write] [--force] [--json]
   buildchain kfd schema list [--standard kfd-1|kfd-2|kfd-3|kfd-4] [--json]
@@ -931,7 +941,40 @@ function runKfd2Cli(args = []) {
 async function runKfdCli(args = []) {
   const [subcommand = "", maybeStandardOrAction = "", ...rest] = args;
   if (!subcommand) {
-    throw new Error("usage: buildchain kfd <status|migrate-layout|schema|upstream|aggregate|1|2|3|4> ...");
+    throw new Error("usage: buildchain kfd <status|migrate-layout|schema|upstream|aggregate|hub|1|2|3|4> ...");
+  }
+
+  if (subcommand === "hub") {
+    const action = maybeStandardOrAction || "inspect";
+    const cwd = path.resolve(readFlag(rest, "cwd", process.cwd()));
+    const declarationPath = readFlag(rest, "declaration", ".buildchain/kfd/agent-hub.json");
+    const common = { cwd, declarationPath };
+    let result;
+    if (action === "init") {
+      result = initKfdAgentHub({
+        ...common,
+        write: readBooleanFlag(rest, "write"),
+        force: readBooleanFlag(rest, "force"),
+      });
+    } else if (action === "inspect") {
+      result = inspectKfdAgentHub(common);
+    } else if (action === "test") {
+      result = testKfdAgentHub({
+        ...common,
+        outputDir: readFlag(rest, "output-dir", ".buildchain/artifacts/kfd-agent-hub"),
+      });
+    } else if (action === "explain") {
+      result = explainKfdAgentHub(common);
+    } else {
+      throw new Error("usage: buildchain kfd hub <init|inspect|test|explain> ...");
+    }
+    if (readBooleanFlag(rest, "json") || readFlag(rest, "for", "") === "agent" || action !== "init") {
+      printJson(result);
+    } else {
+      process.stdout.write(`kfd hub init: ${result.write ? "wrote" : "planned"} ${result.path}\n`);
+    }
+    if (result.valid === false || result.status === "blocked") process.exitCode = 1;
+    return;
   }
 
   if (subcommand === "status") {
@@ -1089,7 +1132,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|upstream|aggregate|1|2|3|4> ...");
+  throw new Error("usage: buildchain kfd <status|migrate-layout|schema|upstream|aggregate|hub|1|2|3|4> ...");
 }
 
 async function runBuildFactsCli(args = []) {
@@ -1781,6 +1824,7 @@ async function main(argv = process.argv.slice(2)) {
       kfd3ArtifactVerifyCommand: readFlag(collectArgs, "kfd-3-artifact-verify-cmd", ""),
       invariantPassportJsons: readRepeatedFlag(collectArgs, "invariant-passport-json"),
       invariantPassportCommand: readFlag(collectArgs, "invariant-passport-cmd", ""),
+      kfdAgentHubEvidenceJson: readFlag(collectArgs, "kfd-agent-hub-evidence-json", ""),
       basePassportJson: readFlag(collectArgs, "base-passport-json", ""),
       requireBaseKfd: readBooleanFlag(collectArgs, "require-base-kfd"),
       releaseJsonExtra: readFlag(collectArgs, "release-extra-json", ""),

package/dist/site/agent-index.json

@@ -17,6 +17,7 @@
     "artifact-schemas.json",
     "release-passport-check-manifest.json",
     "schemas/release-passport-v1.schema.json",
+    "schemas/kfd-agent-hub-adoption.schema.json",
     "buildchain-contract.json",
     "kfd-upstream-aggregate.json",
     "kfd-claims.json",

package/dist/site/artifact-schemas.json

@@ -5,6 +5,7 @@
     "buildchain.release.json",
     "release-passport-check-manifest.json",
     "schemas/release-passport-v1.schema.json",
+    "schemas/kfd-agent-hub-adoption.schema.json",
     "artifact-evidence.json",
     "product-mechanism.json",
     "impact.json",
@@ -32,6 +33,7 @@
     "artifact-schemas.json",
     "release-passport-check-manifest.json",
     "schemas/release-passport-v1.schema.json",
+    "schemas/kfd-agent-hub-adoption.schema.json",
     "buildchain-contract.json",
     "kfd-claims.json",
     "product-mechanism.json",