@kungfu-tech/buildchain 2.12.4 → 2.12.5-alpha.2

package/docs/MAP.md

@@ -28,7 +28,7 @@ workflow, action, and Node API export also carries a `capabilityGroup`,
 | --- | --- | --- |
 | Getting Started | `capability-registry.json`, `product-mechanism.json` | [`install.md`](install.md), [`product-mechanism.md`](product-mechanism.md), [`cli.md`](cli.md) |
 | Release Passport and Trust | `release-model.json`, `artifact-schemas.json`, `kfd-claims.json` | [`release-passport.md`](release-passport.md), [`release-candidate.md`](release-candidate.md), [`publish-transaction.md`](publish-transaction.md), [`binary-distribution.md`](binary-distribution.md) |
-| Reusable Build and Lifecycle | `workflow-registry.json`, `release-model.json` | [`reusable-build-surface.md`](reusable-build-surface.md), [`shifu-gate-profiles.md`](shifu-gate-profiles.md), [`lifecycle-protocol.md`](lifecycle-protocol.md) |
+| Reusable Build and Lifecycle | `workflow-registry.json`, `controller-registry.json`, `release-model.json` | [`reusable-build-surface.md`](reusable-build-surface.md), [`controller-evidence.md`](controller-evidence.md), [`shifu-gate-profiles.md`](shifu-gate-profiles.md), [`lifecycle-protocol.md`](lifecycle-protocol.md) |
 | KFD Trust and Surface Closure | `kfd-claims.json`, `public-surface-audit.json`, `cli-registry.json`, `node-api-registry.json` | [`kfd-support.md`](kfd-support.md), [`release-passport.md`](release-passport.md) |
 | Site Bundle, Web Surfaces, and Propagation | `buildchain-site.json`, `site-manifest.json`, `page-registry.json`, `release-model.json` | [`site-bundle-contract.md`](site-bundle-contract.md), [`web-surface-deployments.md`](web-surface-deployments.md), [`release-propagation.md`](release-propagation.md) |
 | Publication Artifacts | `publication-registry.json`, `workflow-registry.json`, `node-api-registry.json`, `manual-registry.json`, `kungfu-buildchain-publication-artifact-registry` | [`publication-artifacts.md`](publication-artifacts.md), [`reusable-build-surface.md`](reusable-build-surface.md) |
@@ -86,6 +86,7 @@ replace them.
 | How do I gate KFD-3 collaboration-interface releases? | [`release-passport.md`](release-passport.md#kfd-3-collaboration-interface-release-gate) + [`cli.md`](cli.md) | verify/use | stable |
 | How do I detect, register, audit, witness, or query KFD-3 product surfaces? | [`kfd-support.md`](kfd-support.md) + [`cli.md`](cli.md) | verify/use | stable |
 | How do I keep `@v2` floating refs while detecting Buildchain contract drift? | [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock) | verify/use | stable |
+| How do reusable workflows bind controller intent, source/runtime identity, outcomes, and receipt evidence? | [`controller-evidence.md`](controller-evidence.md) | verify/use | draft |
 | How do I propagate finalized upstream releases to downstream package/site PRs? | [`release-propagation.md`](release-propagation.md) | use | preview |
 | How do paper or report repositories publish PDFs, metadata, source bundles, site-consumable manifests, npm packages, and GitHub Releases? | [`publication-artifacts.md`](publication-artifacts.md) | use | stable |
 | How do I generate KFD / Release Passport badge bundles without hand-maintaining Markdown? | [`readme-badges.md`](readme-badges.md) + [`cli.md`](cli.md) | use | stable |

package/docs/controller-evidence.md

@@ -0,0 +1,113 @@
+---
+status: draft
+period: ongoing
+theme: buildchain-controller-evidence
+doc_type: analysis
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-07-14
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-14
+  boundary: Based on repository source and tests; no claim about unobserved downstream runs.
+---
+
+# Controller Evidence
+
+Buildchain controller evidence records what a reusable workflow intended to do
+and what it actually completed. It is a project-independent envelope around
+Buildchain orchestration; it does not replace a consumer project's own policy,
+Gate registry, or domain receipts.
+
+The machine-readable entrypoint is
+`dist/site/controller-registry.json`. The Node API is exported as
+`@kungfu-tech/buildchain/controller-evidence`.
+
+## Public controller inventory
+
+The first versioned inventory contains:
+
+- source check;
+- lifecycle build and channel routing;
+- the Shifu Gate profile envelope;
+- web-surface build/deploy orchestration;
+- publication artifact and paper release;
+- release-candidate promotion;
+- release propagation.
+
+Patrol and repository-maintenance workflows are not controllers. A controller
+descriptor declares its workflow, version, input classifications, expected
+stages, capabilities, evidence kinds, and a deterministic descriptor digest.
+
+## Plan contract
+
+A `buildchain.controller-evidence/v1` plan binds:
+
+- the controller id, version, workflow path, and descriptor digest;
+- the exact consumer repository and 40-character source SHA;
+- the requested Buildchain ref, exact runtime SHA, and runtime contract digest;
+- normalized inputs;
+- expected stages, capabilities, and evidence kinds.
+
+Inputs use one of four policies:
+
+- `included` for safe scalar values;
+- `digest-only` for commands, structured values, runner selection, paths, role
+  identifiers, registries, mirrors, and other environment-shaped values;
+- `redacted` for workflow secrets and token/private-key shaped fields;
+- `unsupported` for a declared input that must fail closed when provided.
+
+Redacted inputs carry no value, digest, or presence bit. Included path-like
+inputs reject absolute runner paths. Undeclared inputs fail plan creation.
+
+## Receipt and aggregation
+
+A receipt binds back to the plan digest and repeats the source and runtime
+identities. Every declared stage is recorded as `passed`, `failed`, `skipped`,
+`cancelled`, or `missing`; the receipt status is `passed`, `failed`, `skipped`,
+or `partial`. Evidence is represented by kind and SHA-256 digest, with an
+optional artifact name.
+
+Reusable workflows expose these outputs:
+
+- `controller-plan-artifact`, `controller-plan-json`, and
+  `controller-plan-digest`;
+- `controller-receipt-artifact`, `controller-receipt-json`,
+  `controller-receipt-digest`, and `controller-receipt-status`.
+
+Final aggregation uses `always()`. A required missing stage, required missing
+evidence, invalid digest, source/runtime mismatch, or missing receipt cannot be
+reported as qualifying green. `aggregateControllerReceipts()` reports an
+explicit `receipt-missing` status when a plan has no receipt.
+
+## Shifu boundary
+
+The Shifu profile controller is an envelope only. Its controller receipt
+references the digest and status of `buildchain.shifu-gate-aggregate/v1`; it
+does not copy project Gate identifiers, Gate semantics, registry contents, or
+per-Gate results into Buildchain's generic controller contract.
+
+## Release Passport references
+
+Release-candidate and final Release Passport documents may carry compact
+`controllerReceipts[]` references. Each reference contains the controller id,
+plan and receipt digests, source and runtime SHAs, status, and artifact name.
+The passport validates those identities; it never invents a controller receipt
+from a successful job conclusion.
+
+The PR-stage lifecycle build creates its qualifying receipt before the
+release-candidate passport. Promotion validates that passport and preserves the
+same references in the final Release Passport, closing the build-to-publish
+evidence chain.
+
+## Train validation
+
+An unreleased contract should be tested through a temporary Buildchain train
+ref and an exact downstream consumer source SHA. The downstream run should
+retain the plan artifact, receipt artifact, workflow outputs, and Release
+Passport or release-candidate reference. Promote to an official alpha or stable
+channel only after those identities and digests agree.

package/docs/release-passport.md

@@ -8,6 +8,12 @@ promotion PRs, exact tags, GitHub Releases, npm Trusted Publishing, and
 machine-readable evidence. A project can keep its existing build system and use
 Buildchain to make the release record auditable.
 
+Release-candidate and final passports may also include compact
+`controllerReceipts[]` references. These bind a real reusable-workflow receipt
+to its plan digest, consumer source SHA, and exact Buildchain runtime SHA; they
+do not infer execution evidence from a green job. See
+[`controller-evidence.md`](controller-evidence.md).
+
 ## Contract
 
 The release passport surface is a welded contract. Additive fields are allowed;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.12.4",
+  "version": "2.12.5-alpha.2",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -17,6 +17,7 @@
     "./core": "./packages/core/index.js",
     "./artifact-passport": "./packages/core/artifact-passport.js",
     "./buildchain-contract": "./packages/core/buildchain-contract.js",
+    "./controller-evidence": "./packages/core/controller-evidence.js",
     "./diagnostics": "./packages/core/diagnostics.js",
     "./homebrew": "./packages/core/homebrew.js",
     "./issue-reporting": "./packages/core/issue-reporting.js",
@@ -45,6 +46,7 @@
     "./site/node-api-registry.json": "./dist/site/node-api-registry.json",
     "./site/kfd-claims.json": "./dist/site/kfd-claims.json",
     "./site/workflow-registry.json": "./dist/site/workflow-registry.json",
+    "./site/controller-registry.json": "./dist/site/controller-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",

package/packages/core/buildchain-contract.js

@@ -1,6 +1,8 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { createControllerRegistry } from "./controller-evidence.js";
+import { enumerateWorkflowInputs } from "./public-surface-audit.js";
 
 export const BUILDCHAIN_RUNTIME_CONTRACT_WORLD = "kungfu-buildchain-runtime-contract-world";
 export const BUILDCHAIN_CONTRACT_LOCK = "kungfu-buildchain-contract-lock";
@@ -70,9 +72,31 @@ function majorLineFromPackageVersion(version = "") {
   return match ? `v${match[1]}` : "v2";
 }
 
-export function createBuildchainContractWorld({ root = process.cwd(), packageJson = undefined } = {}) {
+export function createBuildchainContractWorld({
+  root = process.cwd(),
+  packageJson = undefined,
+  controllerRegistry = undefined,
+} = {}) {
   const pkg = packageJson || readJson(path.join(root, "package.json"), {});
   const majorLine = majorLineFromPackageVersion(pkg.version);
+  const workflowDescriptors = controllerRegistry ? [] : enumerateWorkflowInputs({ root });
+  const controllerWorkflowIds = new Set([
+    "check",
+    ".build",
+    "build",
+    ".gate-profile",
+    ".web-surface",
+    "publication-artifact",
+    "paper-release",
+    "release-candidate-promote",
+    "release-propagation",
+  ]);
+  const hasCompleteControllerSource = [...controllerWorkflowIds]
+    .every((id) => workflowDescriptors.some((workflow) => workflow.id === id));
+  const resolvedControllerRegistry = controllerRegistry
+    || (hasCompleteControllerSource
+      ? createControllerRegistry({ workflows: workflowDescriptors })
+      : readJson(path.join(root, "dist/site/controller-registry.json"), { controllers: [] }));
   const surfaces = [
     surface(root, {
       id: "reusable-build",
@@ -476,6 +500,43 @@ export function createBuildchainContractWorld({ root = process.cwd(), packageJso
       ],
     }),
   ];
+  for (const descriptor of resolvedControllerRegistry.controllers) {
+    surfaces.push(surface(root, {
+      id: `controller:${descriptor.id}`,
+      kind: "controller",
+      path: descriptor.workflow.path,
+      requiredInputs: [],
+      requiredOutputs: [
+        "controller-plan-json",
+        "controller-plan-digest",
+        "controller-receipt-json",
+        "controller-receipt-digest",
+        "controller-receipt-status",
+      ],
+      breakingDefaults: {
+        evidenceContract: "buildchain.controller-evidence/v1",
+        descriptorVersion: descriptor.version,
+        workflowPath: descriptor.workflow.path,
+        requiredStages: descriptor.expected.stages.filter((stage) => stage.required).map((stage) => stage.id),
+        capabilities: descriptor.expected.capabilities,
+        evidenceRequirements: descriptor.expected.evidence,
+        inputClassificationPolicy: "buildchain-controller-input-policy/v1",
+      },
+      optionalInputs: Object.keys(descriptor.inputs),
+      controllerDescriptor: {
+        contract: descriptor.contract,
+        digest: descriptor.digest,
+        registryDigest: resolvedControllerRegistry.digest,
+        inputClassifications: descriptor.inputs,
+      },
+      guarantees: [
+        "plans bind exact consumer source SHA, exact Buildchain runtime SHA, and the runtime contract digest",
+        "receipts bind the plan digest and preserve pass, fail, skip, and partial stage outcomes",
+        "redacted input values are never serialized and digest-only input values are never emitted in plaintext",
+        "missing receipts are non-qualifying and must not be represented as a successful controller run",
+      ],
+    }));
+  }
   const base = {
     schemaVersion: 1,
     contract: BUILDCHAIN_RUNTIME_CONTRACT_WORLD,

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

@@ -15,6 +15,7 @@ export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
   { id: "map", title: "Buildchain documentation map", path: "docs/MAP.md", plane: "use" },
   { id: "install", title: "Install and verify Buildchain", path: "docs/install.md", plane: "use" },
   { id: "release-passport", title: "Release Passport protocol", path: "docs/release-passport.md", plane: "verify" },
+  { id: "controller-evidence", title: "Controller evidence contract", path: "docs/controller-evidence.md", plane: "verify" },
   { id: "release-candidate", title: "Release Candidate Passport", path: "docs/release-candidate.md", plane: "verify" },
   { id: "release-propagation", title: "Release propagation", path: "docs/release-propagation.md", plane: "use" },
   { id: "readme-badges", title: "README badge blocks", path: "docs/readme-badges.md", plane: "use" },
@@ -50,6 +51,7 @@ const SITE_CONTRACT_FILES = Object.freeze([
   "dist/site/manual-registry.json",
   "dist/site/node-api-registry.json",
   "dist/site/workflow-registry.json",
+  "dist/site/controller-registry.json",
   "dist/site/public-surface-audit.json",
   "dist/site/release-model.json",
   "dist/site/artifact-schemas.json",
@@ -65,6 +67,7 @@ const SCHEMA_AND_STANDARD_FILES = Object.freeze([
   "packages/core/kfd-gate.js",
   "packages/core/release-passport.js",
   "packages/core/buildchain-contract.js",
+  "packages/core/controller-evidence.js",
   "packages/core/buildchain-kfd-claims.js",
   "packages/core/kfd3-surface-register.js",
   "packages/core/public-surface-audit.js",