@kungfu-tech/buildchain 4.0.8 → 4.0.9-alpha.1

package/AGENTS.md

@@ -19,26 +19,19 @@ restating them.
 
 ## Using this repo as a Buildchain consumer
 
-Consumers that want Buildchain to select alpha for development/prerelease work
-and stable for production releases use the channel router. The router defaults
-to `auto`; repositories only add channel configuration when they intentionally
-override that policy:
+Ordinary builds read project configuration from `buildchain.toml`. Single-project
+consumers call the public workflow with no inputs:
 
 ```yaml
-uses: kungfu-systems/buildchain/.github/workflows/build.yml@v3
+uses: kungfu-systems/buildchain/.github/workflows/build.yml@v4
 ```
 
-During v3 prerelease evaluation windows, canaries call the same router through
-the matching prerelease ref:
-
-```yaml
-uses: kungfu-systems/buildchain/.github/workflows/build.yml@v3-alpha
-```
-
-The default policy selects `vN-alpha` for pull requests, development, nightly,
-and prerelease intent; it selects stable `vN` for stable release intent. The
-advanced `.build.yml` surface and explicit `buildchain-ref` train/SHA validation
-remain available when a repository needs precise control.
+Use `@v4-alpha` for the alpha runtime. The called workflow ref and SHA determine
+runtime identity and the matching contract lock. A nested project may supply
+only `config-path`; all project settings belong in TOML and infrastructure
+settings belong to a governed Buildchain environment profile. `.build.yml`
+remains the core install/build/verify backbone. Historical build inputs and
+runtime overrides are removed.
 
 For new repositories, prefer the CLI:
 
@@ -65,9 +58,9 @@ See [`docs/cli.md`](docs/cli.md), [`docs/lifecycle-protocol.md`](docs/lifecycle-
 and [`docs/reusable-build-surface.md`](docs/reusable-build-surface.md) for the
 consumer contract.
 
-For temporary validation of an unreleased Buildchain runtime, keep the committed
-workflow ref on `@v3` and use the trusted `workflow_dispatch` `buildchain-ref`
-pass-through. See [`docs/runtime-train-validation.md`](docs/runtime-train-validation.md).
+Ordinary builds do not accept runtime overrides. Specialized release/recovery
+contracts retain their bounded, non-persistent validation mechanisms; see
+[`docs/runtime-train-validation.md`](docs/runtime-train-validation.md).
 
 ## Building this repo
 

package/CONTRIBUTING.md

@@ -161,15 +161,12 @@ release/vX/vX.Y -> publish-gate/major
   wrapper to merge ready, conflict-free dev PRs. The wrapper is policy-gated:
   required checks, ready/block labels, same-repository heads, approvals,
   branch prefixes, max merges, and dry-run are all declared inputs.
-- When a Buildchain change needs downstream validation before stable refs move,
-  publish a temporary runtime train ref such as
-  `train/v3/v3.0/<capability>` and ask consumers to run trusted
-  `workflow_dispatch` with `buildchain-ref` set to that train. Keep the pull
-  request against the `dev/*` branch; the train is only a validation pointer,
-  not a pending merge target. After validation succeeds, merge into the active
-  `dev/*` mainline and run the requested alpha or release promotion. The train
-  may remain for a retention window as a fast-use and rollback channel; old
-  trains are cleaned by a separate periodic cleanup task.
+- Ordinary build callers use `build.yml@v4` or `build.yml@v4-alpha` with
+  project settings in `buildchain.toml`. They have no runtime override input.
+  Validate the implementation and exact contract before merging into protected
+  Dev, publish Alpha, then qualify the public Alpha build before Stable.
+  Specialized release/recovery train admission follows its own bounded
+  contract in `docs/runtime-train-validation.md`.
 - Merging into `alpha/*`, `release/*`, or `publish-gate/major` expresses a
   release intent. Buildchain promotion then creates version-state commits,
   exact tags, floating tags, npm publish evidence, and next-alpha state.

package/README.md

@@ -283,7 +283,7 @@ plus fail-closed product-evidence gates for KFD-4, KFD-5, and KFD-7. These
 gates preserve product-owned qualification and support decisions; they do not
 turn a schema-valid record into certification or shipped support.
 
-Buildchain's action registry currently contains seven active entries. Five are
+Buildchain's action registry contains fourteen active entries. Six are
 direct consumer integration actions:
 
 - `actions/validate-config`
@@ -298,6 +298,16 @@ Two additional release-authority components are also registered and versioned:
 - `actions/github-artifact-attestation`
 - `actions/macos-credential-island`
 
+Six shared build components have explicit ownership in
+`architecture/build-orchestration.json`:
+
+- [`actions/build-lifecycle-stage`](actions/build-lifecycle-stage/action.yml)
+- [`actions/build-signing-request`](actions/build-signing-request/action.yml)
+- [`actions/build-verification-evidence`](actions/build-verification-evidence/action.yml)
+- [`actions/build-attestation-policy`](actions/build-attestation-policy/action.yml)
+- [`actions/build-agent-hub-evidence`](actions/build-agent-hub-evidence/action.yml)
+- [`actions/build-artifact-transfer`](actions/build-artifact-transfer/action.yml)
+
 `dist/site/workflow-registry.json#actions` is the machine-readable inventory;
 this split keeps the older four-action consumer snapshot from being mistaken for
 the complete current registry.

package/architecture/agent-change-map.md

@@ -129,9 +129,6 @@ Safe change route: Reduce one owned responsibility behind the stable facade, run
 - tests: `tests/floating-consumer-policy.test.mjs`
 - tests: `tests/publication-rehearsal.test.mjs`
 - tests: `tests/web-surface.test.mjs`
-- tests: `tests/build-surface-reusable-build.test.mjs`
-- tests: `tests/build-surface-reusable-build-signing.test.mjs`
-- tests: `tests/build-surface-reusable-build-artifacts.test.mjs`
 - tests: `tests/promote-buildchain-ref-durable-recovery.test.mjs`
 - tests: `tests/promote-buildchain-ref-major-promotion.test.mjs`
 - tests: `tests/promote-buildchain-ref-recovery-alpha-finalization.test.mjs`
@@ -142,7 +139,6 @@ Safe change route: Reduce one owned responsibility behind the stable facade, run
 - workflows: `.github/workflows/.release-candidate-promote.yml`
 - workflows: `.github/workflows/.release-verify.yml`
 - workflows: `.github/workflows/.web-surface.yml`
-- workflows: `.github/workflows/build.yml`
 - workflows: `.github/workflows/check.yml`
 - workflows: `.github/workflows/dev-pr-auto-merge.yml`
 - workflows: `.github/workflows/paper-release-sealed.yml`
@@ -607,11 +603,21 @@ Owner: Buildchain workflow maintainers
 - `scripts/resolve-artifact-transfer-mode.mjs`
 - `scripts/resolve-build-summary-names.sh`
 - `scripts/run-lifecycle-core.mjs`
+- `packages/core/build-configuration.js`
+- `scripts/resolve-build-configuration.mjs`
 
 ### Contracts
 
 - `.github/workflows/.build.yml`
 - `.github/workflows/build.yml`
+- `architecture/build-environments.json`
+- `actions/build-lifecycle-stage/action.yml`
+- `actions/build-signing-request/action.yml`
+- `actions/build-verification-evidence/action.yml`
+- `actions/build-attestation-policy/action.yml`
+- `actions/build-agent-hub-evidence/action.yml`
+- `actions/build-artifact-transfer/action.yml`
+- `architecture/build-orchestration.json`
 
 ### Tests
 
@@ -621,6 +627,7 @@ Owner: Buildchain workflow maintainers
 - `tests/build-surface.test.mjs`
 - `tests/build-surface-promotion.test.mjs`
 - `tests/controller-evidence.test.mjs`
+- `tests/build-configuration.test.mjs`
 
 ### Generated outputs
 

package/architecture/build-environments.json

@@ -0,0 +1,71 @@
+{
+  "schema": "buildchain.build-environments/v1",
+  "owner": "Buildchain infrastructure maintainers",
+  "defaults": {
+    "runners": {
+      "preset": "github-hosted",
+      "platforms_json": "",
+      "control_json": "[\"ubuntu-24.04\"]",
+      "codebuild_project": "",
+      "windows_label": "",
+      "macos_label": "",
+      "offline_fallback": false,
+      "container_preset": "",
+      "container_image": ""
+    },
+    "tools": {
+      "rustup_dist_server": "",
+      "rustup_update_root": "",
+      "cargo_registry_index": "",
+      "kfd_agent_hub": "off"
+    },
+    "signing": {
+      "upload_no_proxy": "",
+      "environment": ""
+    },
+    "transfer": {
+      "mode": "github-artifacts",
+      "bucket": "",
+      "region": "",
+      "prefix": "",
+      "upload_role_arn": "",
+      "download_role_arn": "",
+      "oidc_audience": ""
+    },
+    "checkout": {
+      "mode": "off",
+      "mirror_url_template": "",
+      "reference_repository_template": "",
+      "fallback": "github",
+      "timeout_seconds": 60.0,
+      "github_timeout_seconds": 600.0,
+      "fetch_attempts": 3.0,
+      "history_mode": "shallow"
+    },
+    "cache": {
+      "profile_ref": "",
+      "profile_digest": "",
+      "provider": "none",
+      "platforms_json": "[]",
+      "required": false
+    }
+  },
+  "profiles": {
+    "github-hosted": {},
+    "github-hosted-container": {
+      "runners": {
+        "container_preset": "kungfu-verify"
+      }
+    },
+    "kungfu-v4-native": {
+      "runners": {
+        "preset": "kungfu-v4-native"
+      }
+    },
+    "kungfu-v4-self-hosted": {
+      "runners": {
+        "preset": "kungfu-v4-self-hosted"
+      }
+    }
+  }
+}

package/architecture/build-orchestration.json

@@ -0,0 +1,18 @@
+{
+  "schema": "buildchain.build-orchestration/v1",
+  "configurationAuthority": "buildchain.toml",
+  "ordinaryInputs": ["config-path"],
+  "backbone": ".github/workflows/.build.yml",
+  "facade": ".github/workflows/build.yml",
+  "maximumBackboneLines": 2300,
+  "maximumFacadeLines": 200,
+  "lifecycleOrder": ["install", "build", "verify"],
+  "owners": {
+    "actions/build-lifecycle-stage/action.yml": "Buildchain workflow maintainers",
+    "actions/build-signing-request/action.yml": "Buildchain signing maintainers",
+    "actions/build-verification-evidence/action.yml": "Buildchain verification maintainers",
+    "actions/build-attestation-policy/action.yml": "Buildchain signing maintainers",
+    "actions/build-agent-hub-evidence/action.yml": "Buildchain verification maintainers",
+    "actions/build-artifact-transfer/action.yml": "Buildchain artifact transport maintainers"
+  }
+}

package/architecture/ci-lane-change-budget.json

@@ -625,6 +625,57 @@
         "expectedContributionSeconds": 0,
         "rationale": "Runs only after completed exact-source public installation qualification; no merge-critical runner lane is added."
       }
+    },
+    {
+      "laneId": ".github/workflows/.build.yml#configure",
+      "authorityClass": "evidence",
+      "triggerClass": "reusable",
+      "concurrencyPolicy": {
+        "mode": "none",
+        "cancelInProgress": false
+      },
+      "expectedRunnerMinutes": 5,
+      "cancellationBehavior": "finish-started",
+      "sloImpact": {
+        "mergeCritical": false,
+        "metric": "configured build planning and execution latency",
+        "expectedContributionSeconds": 20,
+        "rationale": "Resolve exact source TOML and runtime-owned environment before admission or matrix scheduling."
+      }
+    },
+    {
+      "laneId": ".github/workflows/build.yml#build",
+      "authorityClass": "governed-delegation",
+      "triggerClass": "reusable",
+      "concurrencyPolicy": {
+        "mode": "none",
+        "cancelInProgress": false
+      },
+      "expectedRunnerMinutes": 120,
+      "cancellationBehavior": "finish-started",
+      "sloImpact": {
+        "mergeCritical": false,
+        "metric": "configured build planning and execution latency",
+        "expectedContributionSeconds": 0,
+        "rationale": "The public facade delegates once to the backbone; no additional build or controller runs."
+      }
+    },
+    {
+      "laneId": ".github/workflows/self-build-stable-dogfood.yml#stable-consumer",
+      "authorityClass": "governed-delegation",
+      "triggerClass": "mixed",
+      "concurrencyPolicy": {
+        "mode": "ref-scoped",
+        "cancelInProgress": false
+      },
+      "expectedRunnerMinutes": 20,
+      "cancellationBehavior": "finish-started",
+      "sloImpact": {
+        "mergeCritical": false,
+        "metric": "Published stable TOML build qualification latency",
+        "expectedContributionSeconds": 0,
+        "rationale": "Independent thin public stable fixture caller permits producer-first channel upgrades without duplicating build orchestration."
+      }
     }
   ],
   "declarationFamilies": [
@@ -646,7 +697,6 @@
       "laneIds": [
         ".github/workflows/.auditable-demo.yml#universal-bootstrap",
         ".github/workflows/.binary-release-assets.yml#universal-bootstrap",
-        ".github/workflows/.build.yml#universal-bootstrap",
         ".github/workflows/.bump-minor-version.yml#universal-bootstrap",
         ".github/workflows/.declarative-auditable-demo.yml#universal-bootstrap",
         ".github/workflows/.gate-profile.yml#universal-bootstrap",
@@ -658,7 +708,6 @@
         ".github/workflows/.sync-remote-git.yml#universal-bootstrap",
         ".github/workflows/.web-surface.yml#universal-bootstrap",
         ".github/workflows/.wheel-verify.yml#universal-bootstrap",
-        ".github/workflows/build.yml#universal-bootstrap",
         ".github/workflows/buildchain-patrol.yml#universal-bootstrap",
         ".github/workflows/check.yml#universal-bootstrap",
         ".github/workflows/dev-alpha-candidate-patrol.yml#universal-bootstrap",

package/architecture/internal-capabilities.json

@@ -150,7 +150,9 @@
     "scripts/maintainability-metrics.mjs",
     "scripts/generate-agent-change-map.mjs",
     "scripts/maintainability-domain-metrics.mjs",
-    "scripts/maintainability-governance.mjs"
+    "scripts/maintainability-governance.mjs",
+    "packages/core/build-configuration.js",
+    "scripts/resolve-build-configuration.mjs"
   ],
   "ownershipRules": [
     {
@@ -383,7 +385,9 @@
         "scripts/generate-channel-build-workflow.mjs",
         "scripts/resolve-artifact-transfer-mode.mjs",
         "scripts/resolve-build-summary-names.sh",
-        "scripts/run-lifecycle-core.mjs"
+        "scripts/run-lifecycle-core.mjs",
+        "packages/core/build-configuration.js",
+        "scripts/resolve-build-configuration.mjs"
       ],
       "tests": [
         "tests/artifact-transfer-mode.test.mjs",
@@ -391,11 +395,20 @@
         "tests/build-surface-reusable-build-artifacts.test.mjs",
         "tests/build-surface.test.mjs",
         "tests/build-surface-promotion.test.mjs",
-        "tests/controller-evidence.test.mjs"
+        "tests/controller-evidence.test.mjs",
+        "tests/build-configuration.test.mjs"
       ],
       "contracts": [
         ".github/workflows/.build.yml",
-        ".github/workflows/build.yml"
+        ".github/workflows/build.yml",
+        "architecture/build-environments.json",
+        "actions/build-lifecycle-stage/action.yml",
+        "actions/build-signing-request/action.yml",
+        "actions/build-verification-evidence/action.yml",
+        "actions/build-attestation-policy/action.yml",
+        "actions/build-agent-hub-evidence/action.yml",
+        "actions/build-artifact-transfer/action.yml",
+        "architecture/build-orchestration.json"
       ],
       "generatedOutputs": [
         ".github/workflows/build.yml",