@kungfu-tech/buildchain 2.12.1-alpha.2 → 2.12.1-alpha.4

package/docs/cli.md

@@ -77,6 +77,7 @@ import { verifyReleasePassport } from "@kungfu-tech/buildchain/release-passport"
 import { createReleasePropagationPlan } from "@kungfu-tech/buildchain/release-propagation";
 import { planReleaseLineBootstrap } from "@kungfu-tech/buildchain/release-line-bootstrap";
 import { collectPublicSurfaceReverseAudit } from "@kungfu-tech/buildchain/public-surface-audit";
+import { createBuildchainLayoutDiscovery } from "@kungfu-tech/buildchain/buildchain-layout";
 import contractWorld from "@kungfu-tech/buildchain/site/buildchain-contract.json" with { type: "json" };
 import capabilityRegistry from "@kungfu-tech/buildchain/site/capability-registry.json" with { type: "json" };
 import manualRegistry from "@kungfu-tech/buildchain/site/manual-registry.json" with { type: "json" };
@@ -90,6 +91,22 @@ floating-ref contract world for a runtime such as `@v2`.
 
 ## Commands
 
+`buildchain layout` is the stable machine question for repository layout. Tools
+such as Shifu should call it instead of copying `.buildchain/` path constants:
+
+```bash
+buildchain layout --cwd /path/to/repository --json
+```
+
+The result identifies the Buildchain version pin, repository root and config,
+the canonical and currently resolved KFD-3 registry paths, and the KFD field
+used to declare Shifu jurisdiction. A repository is in Shifu's distribution
+jurisdiction only when a KFD-3 surface explicitly declares
+`distribution.registrar="shifu"`; the presence of Buildchain configuration is
+not sufficient. The same contract is available through
+`createBuildchainLayoutDiscovery()` from
+`@kungfu-tech/buildchain/buildchain-layout`.
+
 `buildchain init` writes a starter `.buildchain/buildchain.toml` and a reusable workflow
 caller at `.github/workflows/build.yml`.
 

package/docs/kfd-support.md

@@ -279,6 +279,49 @@ detect standard public surfaces, write a small product-owned registry, audit the
 registry against the current artifact/source tree, generate a release-passport
 compatible witness, and query the resulting capability map.
 
+## Shifu Discovery and Distribution Declarations
+
+Buildchain owns the repository-layout question; product tools must not copy its
+internal paths. Shifu and other consumers use this sequence:
+
+1. read the welded `.buildchain-version` pin to select Buildchain;
+2. run `buildchain layout --cwd <repository> --json`;
+3. read the returned `kfd.registries["kfd-3"].path`;
+4. treat a surface as Shifu-managed only when its declaration contains
+   `distribution.registrar="shifu"`.
+
+The layout response uses the
+`kungfu-buildchain-layout-discovery` contract with an explicit schema version.
+Changing or removing its fields is a public contract change. Consumers must not
+fall back to a hard-coded registry location when the command is unavailable or
+returns an unsupported contract.
+
+A Shifu distribution declaration must contain at least one task and one
+artifact. Every artifact declares `kind`, `platform`, and `pathGlob`; an
+optional `sha256` is a lowercase 64-character hexadecimal digest. This makes
+artifact form and platform machine-readable without asking Shifu to infer them
+from filenames:
+
+```json
+{
+  "distribution": {
+    "registrar": "shifu",
+    "tasks": ["binary:build"],
+    "artifacts": [
+      {
+        "kind": "binary",
+        "platform": "linux",
+        "pathGlob": "dist/binary/example-x86_64-unknown-linux-gnu.tar.gz"
+      }
+    ]
+  }
+}
+```
+
+Buildchain validates this shape whenever a KFD-3 registry is read or written.
+Repositories that do not declare the registrar remain outside Shifu's
+distribution jurisdiction.
+
 ## Detected, Declared, Enforced
 
 KFD-3 surface registration uses three states.
@@ -402,7 +445,7 @@ Buildchain dogfoods this model in two ways:
   `buildchain kfd 2 trust-assessment --json` expose and validate the KFD
   package's foundation KFD-2 trust facts against the latest KFD taxonomy;
 - `dist/site/kfd-claims.json` declares Buildchain's own KFD-3 collaboration
-  interface;
+  interface, including a Shifu-owned standalone binary distribution surface;
 - `buildchain kfd 3 query buildchain --json` resolves the packaged
   Buildchain capability map from that site fact source.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.12.1-alpha.2",
+  "version": "2.12.1-alpha.4",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -84,6 +84,7 @@
     "check:site": "node scripts/generate-site-bundle.mjs --check",
     "test:unit": "node --test tests/*.test.mjs",
     "build": "pnpm -r --filter \"./actions/**\" build",
+    "binary:build": "node scripts/build-standalone-binary.mjs",
     "package": "npm pack --dry-run --json --registry=https://registry.npmjs.org/",
     "pack:check": "npm pack --dry-run --json --registry=https://registry.npmjs.org/"
   },

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

@@ -6,6 +6,7 @@ import {
   BUILDCHAIN_PUBLIC_SURFACE_AUDIT_CONTRACT,
   collectPublicSurfaceReverseAudit,
 } from "./public-surface-audit.js";
+import { normalizeKfd3DistributionDeclaration } from "./kfd3-surface-register.js";
 
 export const BUILDCHAIN_KFD_CLAIM_REGISTRY_CONTRACT = "kungfu-buildchain-kfd-claim-registry";
 export const BUILDCHAIN_KFD_COLLABORATION_INTERFACE_CONTRACT = "kungfu-buildchain-kfd-collaboration-interface";
@@ -307,6 +308,23 @@ export function createBuildchainPublicClaimDefinitions() {
         "dist/site/public-surface-audit.json",
       ],
     },
+    {
+      id: "claim:buildchain-shifu-kfd-discovery",
+      claim: "Buildchain exposes a versioned repository-layout discovery contract and KFD-3 distribution declarations so Shifu can locate the registry and determine jurisdiction without copying Buildchain layout paths.",
+      sourcePaths: [
+        "packages/core/buildchain-layout.js",
+        "packages/core/buildchain-kfd-claims.js",
+        "packages/core/kfd3-surface-register.js",
+        "bin/buildchain.mjs",
+        "scripts/build-standalone-binary.mjs",
+        "docs/kfd-support.md",
+      ],
+      artifactPaths: [
+        "dist/site/kfd-claims.json",
+        "dist/site/cli-registry.json",
+        "dist/site/node-api-registry.json",
+      ],
+    },
     {
       id: "claim:buildchain-readme-badge-facts",
       claim: "Buildchain README status badges are generated from repository-owned facts and verified release-passport evidence, not hand-maintained README prose.",
@@ -431,6 +449,37 @@ export function createBuildchainKfdSurfaceRegistry({ root = process.cwd() } = {}
   ];
   const siteConsumptionContracts = SITE_CONTRACT_FILES.map((relPath) => surface(`site:${relPath}`, "site-consumption-contract", relPath));
   const controlSurfaces = WORKFLOW_AND_ACTION_FILES.map((relPath) => surface(`control:${relPath}`, relPath.includes("actions/") ? "action" : "workflow", relPath));
+  const standaloneDistribution = surface(
+    "distribution:buildchain-standalone",
+    "binary-distribution",
+    "scripts/build-standalone-binary.mjs",
+    {
+      name: "Buildchain standalone binary distribution",
+      artifactPath: "dist/binary",
+      evidencePath: ".github/workflows/binary-distribution.yml",
+      distribution: normalizeKfd3DistributionDeclaration({
+        registrar: "shifu",
+        tasks: ["binary:build"],
+        artifacts: [
+          {
+            kind: "binary",
+            platform: "linux",
+            pathGlob: "dist/binary/buildchain-x86_64-unknown-linux-gnu.tar.gz",
+          },
+          {
+            kind: "binary",
+            platform: "macos",
+            pathGlob: "dist/binary/buildchain-aarch64-apple-darwin.tar.gz",
+          },
+          {
+            kind: "binary",
+            platform: "windows",
+            pathGlob: "dist/binary/buildchain-x86_64-pc-windows-msvc.zip",
+          },
+        ],
+      }, { surfaceId: "distribution:buildchain-standalone" }),
+    },
+  );
   const reverseEnumeratedSurfaces = uniqueById([
     ...reverseAudit.enumerated.cliCommands.map((entry) => surface(`cli:${entry.id}`, "cli-command", "bin/buildchain.mjs", {
       name: entry.usage,
@@ -463,8 +512,8 @@ export function createBuildchainKfdSurfaceRegistry({ root = process.cwd() } = {}
       siteConsumptionContracts,
       reverseEnumeratedSurfaces,
     },
-    additionalSurfaces: controlSurfaces,
-    publicSurfaceCount: docs.length + schemas.length + standardsMetadata.length + exports.length + siteConsumptionContracts.length + reverseEnumeratedSurfaces.length + controlSurfaces.length,
+    additionalSurfaces: [...controlSurfaces, standaloneDistribution],
+    publicSurfaceCount: docs.length + schemas.length + standardsMetadata.length + exports.length + siteConsumptionContracts.length + reverseEnumeratedSurfaces.length + controlSurfaces.length + 1,
   };
 }
 

package/packages/core/buildchain-layout.js

@@ -2,6 +2,8 @@ import fs from "node:fs";
 import path from "node:path";
 
 export const BUILDCHAIN_DIR = ".buildchain";
+export const BUILDCHAIN_VERSION_PIN_PATH = ".buildchain-version";
+export const BUILDCHAIN_LAYOUT_DISCOVERY_CONTRACT = "kungfu-buildchain-layout-discovery";
 export const BUILDCHAIN_CONFIG_PATH = ".buildchain/buildchain.toml";
 export const LEGACY_BUILDCHAIN_CONFIG_PATH = "buildchain.toml";
 export const BUILDCHAIN_CONTRACT_LOCK_PATH = ".buildchain/contract-lock.json";
@@ -94,6 +96,50 @@ export function resolveReleasePassportPath(cwd = process.cwd()) {
   ]);
 }
 
+export function createBuildchainLayoutDiscovery({
+  cwd = process.cwd(),
+  buildchainVersion = "",
+} = {}) {
+  const resolvedCwd = path.resolve(cwd);
+  const configPath = resolveBuildchainConfigPath(resolvedCwd);
+  const kfd3RegistryPath = resolveKfd3SurfaceRegistryPath(resolvedCwd);
+  return {
+    schemaVersion: 1,
+    contract: BUILDCHAIN_LAYOUT_DISCOVERY_CONTRACT,
+    buildchain: {
+      version: String(buildchainVersion || ""),
+      versionPinPath: BUILDCHAIN_VERSION_PIN_PATH,
+    },
+    repository: {
+      root: resolvedCwd,
+      managed: fs.existsSync(repoPath(resolvedCwd, configPath))
+        || fs.existsSync(repoPath(resolvedCwd, BUILDCHAIN_VERSION_PIN_PATH))
+        || fs.existsSync(repoPath(resolvedCwd, kfd3RegistryPath)),
+      configPath,
+    },
+    kfd: {
+      root: BUILDCHAIN_KFD_ROOT,
+      registries: {
+        "kfd-3": {
+          standard: "kfd-3",
+          schemaVersion: 1,
+          path: kfd3RegistryPath,
+          canonicalPath: BUILDCHAIN_KFD3_SURFACE_REGISTRY_PATH,
+          exists: fs.existsSync(repoPath(resolvedCwd, kfd3RegistryPath)),
+        },
+      },
+    },
+    shifu: {
+      jurisdiction: {
+        source: "kfd-3-distribution-declaration",
+        registryStandard: "kfd-3",
+        field: "surfaces[].distribution.registrar",
+        value: "shifu",
+      },
+    },
+  };
+}
+
 export function discoverBuildchainRepoFiles(cwd = process.cwd()) {
   const files = [
     {

package/packages/core/index.js

@@ -292,6 +292,8 @@ export {
   BUILDCHAIN_CONFIG_PATH,
   BUILDCHAIN_CONTRACT_LOCK_PATH,
   BUILDCHAIN_DIR,
+  BUILDCHAIN_LAYOUT_DISCOVERY_CONTRACT,
+  BUILDCHAIN_VERSION_PIN_PATH,
   BUILDCHAIN_GENERATED_DIRS,
   BUILDCHAIN_KFD_ROOT,
   BUILDCHAIN_KFD1_CONTRACT_WORLD_WITNESS_PATH,
@@ -317,6 +319,7 @@ export {
   LEGACY_BUILDCHAIN_KFD3_SURFACE_REGISTRY_PATHS,
   LEGACY_BUILDCHAIN_RELEASE_PASSPORT_PATH,
   discoverBuildchainRepoFiles,
+  createBuildchainLayoutDiscovery,
   migrateBuildchainLayout,
   planBuildchainLayoutMigration,
   resolveBuildchainConfigPath,
@@ -359,6 +362,7 @@ export {
   auditKfd3Surfaces,
   createKfd3SurfaceWitness,
   detectKfd3Surfaces,
+  normalizeKfd3DistributionDeclaration,
   queryKfd3Capabilities,
   readKfd3SurfaceRegistry,
   registerKfd3Surfaces,

package/packages/core/kfd3-surface-register.js

@@ -67,6 +67,63 @@ function normalizeKinds(kinds = []) {
   return [...new Set(selected.map(normalizeKind))].sort();
 }
 
+export function normalizeKfd3DistributionDeclaration(distribution, { surfaceId = "surface" } = {}) {
+  if (!distribution || typeof distribution !== "object" || Array.isArray(distribution)) {
+    throw new Error(`KFD-3 surface ${surfaceId} distribution must be an object`);
+  }
+  const registrar = String(distribution.registrar || "").trim();
+  if (!registrar) {
+    throw new Error(`KFD-3 surface ${surfaceId} distribution.registrar is required`);
+  }
+  const tasks = Array.isArray(distribution.tasks)
+    ? [...new Set(distribution.tasks.map((entry) => String(entry || "").trim()).filter(Boolean))]
+    : [];
+  if (tasks.length === 0) {
+    throw new Error(`KFD-3 surface ${surfaceId} distribution.tasks must contain at least one task`);
+  }
+  const sourceArtifacts = Array.isArray(distribution.artifacts) ? distribution.artifacts : [];
+  if (sourceArtifacts.length === 0) {
+    throw new Error(`KFD-3 surface ${surfaceId} distribution.artifacts must contain at least one artifact`);
+  }
+  const artifacts = sourceArtifacts.map((artifact, index) => {
+    if (!artifact || typeof artifact !== "object" || Array.isArray(artifact)) {
+      throw new Error(`KFD-3 surface ${surfaceId} distribution.artifacts[${index}] must be an object`);
+    }
+    const normalized = {
+      ...artifact,
+      kind: String(artifact.kind || "").trim(),
+      platform: String(artifact.platform || "").trim(),
+      pathGlob: String(artifact.pathGlob || "").trim(),
+    };
+    for (const field of ["kind", "platform", "pathGlob"]) {
+      if (!normalized[field]) {
+        throw new Error(`KFD-3 surface ${surfaceId} distribution.artifacts[${index}].${field} is required`);
+      }
+    }
+    if (artifact.sha256 !== undefined) {
+      normalized.sha256 = String(artifact.sha256 || "").trim().toLowerCase();
+      if (!/^[a-f0-9]{64}$/.test(normalized.sha256)) {
+        throw new Error(`KFD-3 surface ${surfaceId} distribution.artifacts[${index}].sha256 must be 64 lowercase hex characters`);
+      }
+    }
+    return normalized;
+  });
+  return {
+    ...distribution,
+    registrar,
+    tasks,
+    artifacts,
+  };
+}
+
+function normalizeRegistrySurface(entry) {
+  if (!entry?.distribution) return entry;
+  return {
+    ...entry,
+    distribution: normalizeKfd3DistributionDeclaration(entry.distribution, { surfaceId: entry.id || "surface" }),
+  };
+}
+
 function stableId(value) {
   return String(value || "")
     .toLowerCase()
@@ -366,7 +423,7 @@ export function readKfd3SurfaceRegistry({ cwd = process.cwd(), registryPath = ""
     contract: registry.contract || KFD3_SURFACE_REGISTRY_CONTRACT,
     product: registry.product || {},
     registryPath: registry.registryPath || effectiveRegistryPath,
-    surfaces: Array.isArray(registry.surfaces) ? registry.surfaces : [],
+    surfaces: Array.isArray(registry.surfaces) ? registry.surfaces.map(normalizeRegistrySurface) : [],
     policy: registry.policy || {},
   };
 }
@@ -379,7 +436,7 @@ export function writeKfd3SurfaceRegistry({ cwd = process.cwd(), registryPath = "
     product: registry.product || {},
     registryPath: effectiveRegistryPath,
     surfaces: uniqueSurfaces(registry.surfaces || []).map((entry) => ({
-      ...entry,
+      ...normalizeRegistrySurface(entry),
       state: entry.state || "declared",
       declaration: entry.declaration || {
         owner: "product",

package/scripts/build-standalone-binary.mjs

@@ -176,9 +176,10 @@ function bundleCli({ cwd, tempDir, version, logger }) {
   sourcemap: false,
   dts: false,
   shims: true,
-  noExternal: ["smol-toml"],
+  noExternal: ["smol-toml", /^@kungfu-tech\\/kfd(?:\\/|$)/],
   define: {
     "process.env.BUILDCHAIN_EMBEDDED_PACKAGE_VERSION": ${JSON.stringify(JSON.stringify(version || packageVersion(cwd)))},
+    "process.env.BUILDCHAIN_EMBEDDED_ENTRYPOINT": ${JSON.stringify(JSON.stringify("1"))},
   },
 };
 `);

package/scripts/check-inventory.mjs

@@ -732,7 +732,8 @@ for (const requiredSnippet of [
   "../packages/core/logging.js",
   "standalone.cli-bundle.create",
   "BUILDCHAIN_EMBEDDED_PACKAGE_VERSION",
-  "noExternal: [\"smol-toml\"]",
+  "BUILDCHAIN_EMBEDDED_ENTRYPOINT",
+  "noExternal: [\"smol-toml\",",
   "--macho-segment-name",
   "mainFormat: \"commonjs\"",
   "standalone.sea-blob.create",

package/scripts/generate-site-bundle.mjs

@@ -395,6 +395,7 @@ function cliCommandMeta(id) {
     "inspect-artifact": { group: "release-passport-trust", purpose: "Inspect artifact evidence." },
     "inspect-release": { group: "release-passport-trust", purpose: "Inspect release passport evidence." },
     kfd: { group: "kfd-trust", purpose: "Inspect KFD standards, schemas, and versioned KFD command families." },
+    layout: { group: "kfd-trust", purpose: "Return the versioned repository-layout and KFD registry discovery contract for tools such as Shifu." },
     "kfd-schema": { group: "kfd-trust", purpose: "Inspect KFD schema command families." },
     "kfd-schema-list": { group: "kfd-trust", purpose: "List machine-readable schemas exposed by the KFD package standards metadata." },
     "kfd-schema-show": { group: "kfd-trust", purpose: "Print a machine-readable KFD schema from the KFD package standards metadata." },
@@ -479,7 +480,7 @@ function nodeApiMeta(exportName) {
     "./buildchain-contract": { group: "governance-versioning", summary: "Runtime contract world and compatibility digest APIs for floating-ref drift checks." },
     "./surface-manifest": { group: "site-and-propagation", summary: "Surface manifest timestamp and reproducibility policy APIs." },
     "./issue-reporting": { group: "observability-diagnostics", summary: "Buildchain-owned issue reporting API for workflow friction feedback." },
-    "./buildchain-layout": { group: "kfd-trust", summary: "Canonical .buildchain repository layout constants, path resolution, and migration APIs." },
+    "./buildchain-layout": { group: "kfd-trust", summary: "Versioned Buildchain repository-layout discovery contract plus canonical .buildchain path resolution and migration APIs." },
     "./kfd": { group: "kfd-trust", 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." },
     "./public-surface-audit": { group: "kfd-trust", summary: "Reverse audit APIs for CLI, workflow, action, site page, and documentation command surfaces." },
     "./kfd-gate": { group: "kfd-trust", summary: "KFD-1/KFD-2/KFD-3 release gate evidence and validation APIs." },

package/scripts/init-repo.mjs

@@ -477,7 +477,7 @@ function readArg(name, fallback = "") {
   return process.argv[index + 1] || "";
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (!process.env.BUILDCHAIN_EMBEDDED_ENTRYPOINT && process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   try {
     const result = initBuildchainRepo({
       cwd: readArg("cwd", process.cwd()),

package/scripts/npm-publish-dry-run.mjs

@@ -155,7 +155,7 @@ function usage() {
 `;
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (!process.env.BUILDCHAIN_EMBEDDED_ENTRYPOINT && process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   try {
     const argv = process.argv.slice(2);
     if (hasFlag(argv, "help") || hasFlag(argv, "h")) {

package/scripts/publication-artifact.mjs

@@ -57,7 +57,7 @@ export function runPublicationArtifactCli(args = process.argv.slice(2)) {
   return result;
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (!process.env.BUILDCHAIN_EMBEDDED_ENTRYPOINT && process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   try {
     runPublicationArtifactCli();
   } catch (error) {

package/scripts/publication-package.mjs

@@ -28,7 +28,7 @@ export function runPublicationPackageCli(args = process.argv.slice(2)) {
   return result;
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (!process.env.BUILDCHAIN_EMBEDDED_ENTRYPOINT && process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   try {
     runPublicationPackageCli();
   } catch (error) {

package/scripts/release-propagation.mjs

@@ -93,6 +93,6 @@ export function runReleasePropagationCli(argv = process.argv.slice(2)) {
   throw new Error(`unsupported release-propagation command: ${mode}`);
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (!process.env.BUILDCHAIN_EMBEDDED_ENTRYPOINT && process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   runReleasePropagationCli();
 }