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

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,40 @@
         "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."
+      }
     }
   ],
   "declarationFamilies": [
@@ -646,7 +680,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 +691,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",

package/architecture/maintainability-debt.json

@@ -7,8 +7,8 @@
   },
   "totalExcessLedger": {
     "metric": "calibrated-full-dimensional-excess-v1",
-    "measuredExcess": 64542,
-    "current": 56481
+    "measuredExcess": 62271,
+    "current": 54210
   },
   "defaults": {
     "owner": "Buildchain architecture maintainers",
@@ -315,10 +315,10 @@
       },
       "packages/core/buildchain-config.js": {
         "baseline": {
-          "lines": 1885
+          "lines": 1887
         },
         "current": {
-          "lines": 1885
+          "lines": 1887
         },
         "target": {
           "lines": 600
@@ -334,10 +334,10 @@
           }
         },
         "current": {
-          "lines": 1078,
+          "lines": 1048,
           "functions": {
             "createBuildchainContractWorld@199": {
-              "lines": 681
+              "lines": 651
             }
           }
         },
@@ -1214,7 +1214,7 @@
           "lines": 1515
         },
         "current": {
-          "lines": 1475
+          "lines": 1502
         },
         "target": {
           "lines": 600
@@ -1457,7 +1457,7 @@
       },
       "scripts/generate-site-bundle.mjs": {
         "baseline": {
-          "lines": 1410,
+          "lines": 1411,
           "functions": {
             "buildSiteBundle@720": {
               "lines": 637
@@ -1465,10 +1465,10 @@
           }
         },
         "current": {
-          "lines": 1410,
+          "lines": 1411,
           "functions": {
             "buildSiteBundle@720": {
-              "lines": 636
+              "lines": 637
             }
           }
         },
@@ -2191,7 +2191,7 @@
     "tests": {
       "tests/auditable-demo-platform.test.mjs": {
         "baseline": {
-          "lines": 712
+          "lines": 714
         },
         "current": {
           "lines": 712
@@ -2241,15 +2241,15 @@
         "baseline": {
           "lines": 3181,
           "functions": {
-            "<anonymous@1559>@1559": {
+            "<anonymous@1537>@1537": {
               "lines": 206
             }
           }
         },
         "current": {
-          "lines": 2738,
+          "lines": 2711,
           "functions": {
-            "<anonymous@1559>@1559": {
+            "<anonymous@1537>@1537": {
               "lines": 206
             }
           }
@@ -2257,7 +2257,7 @@
         "target": {
           "lines": 600,
           "functions": {
-            "<anonymous@1559>@1559": {
+            "<anonymous@1537>@1537": {
               "lines": 180
             }
           }
@@ -2267,33 +2267,27 @@
         "baseline": {
           "lines": 4639,
           "functions": {
-            "<anonymous@170>@170": {
-              "lines": 195
-            },
-            "<anonymous@544>@544": {
+            "<anonymous@445>@445": {
               "lines": 183
             },
-            "<anonymous@1678>@1678": {
+            "<anonymous@1579>@1579": {
               "lines": 249
             },
-            "<anonymous@2684>@2684": {
+            "<anonymous@2585>@2585": {
               "lines": 188
             }
           }
         },
         "current": {
-          "lines": 3027,
+          "lines": 2909,
           "functions": {
-            "<anonymous@170>@170": {
-              "lines": 186
-            },
-            "<anonymous@544>@544": {
+            "<anonymous@445>@445": {
               "lines": 183
             },
-            "<anonymous@1678>@1678": {
+            "<anonymous@1579>@1579": {
               "lines": 249
             },
-            "<anonymous@2684>@2684": {
+            "<anonymous@2585>@2585": {
               "lines": 188
             }
           }
@@ -2301,16 +2295,13 @@
         "target": {
           "lines": 600,
           "functions": {
-            "<anonymous@170>@170": {
-              "lines": 180
-            },
-            "<anonymous@544>@544": {
+            "<anonymous@445>@445": {
               "lines": 180
             },
-            "<anonymous@1678>@1678": {
+            "<anonymous@1579>@1579": {
               "lines": 180
             },
-            "<anonymous@2684>@2684": {
+            "<anonymous@2585>@2585": {
               "lines": 180
             }
           }
@@ -2329,7 +2320,7 @@
       },
       "tests/cli.test.mjs": {
         "baseline": {
-          "lines": 2840,
+          "lines": 2842,
           "functions": {
             "<anonymous@2363>@2363": {
               "lines": 253
@@ -2485,7 +2476,7 @@
           "lines": 916
         },
         "current": {
-          "lines": 916
+          "lines": 899
         },
         "target": {
           "lines": 600
@@ -2756,75 +2747,6 @@
           "lines": 600
         }
       },
-      "tests/build-surface-reusable-build.test.mjs": {
-        "baseline": {
-          "functions": {
-            "<anonymous@3>@3": {
-              "lines": 342
-            }
-          }
-        },
-        "current": {
-          "functions": {
-            "<anonymous@3>@3": {
-              "lines": 342
-            }
-          }
-        },
-        "target": {
-          "functions": {
-            "<anonymous@3>@3": {
-              "lines": 180
-            }
-          }
-        }
-      },
-      "tests/build-surface-reusable-build-signing.test.mjs": {
-        "baseline": {
-          "functions": {
-            "<anonymous@3>@3": {
-              "lines": 266
-            }
-          }
-        },
-        "current": {
-          "functions": {
-            "<anonymous@3>@3": {
-              "lines": 266
-            }
-          }
-        },
-        "target": {
-          "functions": {
-            "<anonymous@3>@3": {
-              "lines": 180
-            }
-          }
-        }
-      },
-      "tests/build-surface-reusable-build-artifacts.test.mjs": {
-        "baseline": {
-          "functions": {
-            "<anonymous@3>@3": {
-              "lines": 232
-            }
-          }
-        },
-        "current": {
-          "functions": {
-            "<anonymous@3>@3": {
-              "lines": 230
-            }
-          }
-        },
-        "target": {
-          "functions": {
-            "<anonymous@3>@3": {
-              "lines": 180
-            }
-          }
-        }
-      },
       "tests/promote-buildchain-ref-durable-recovery.test.mjs": {
         "baseline": {
           "functions": {
@@ -2922,17 +2844,17 @@
       ".github/workflows/.build.yml": {
         "baseline": {
           "lines": 3370,
-          "jobs": 14,
+          "jobs": 15,
           "steps": 194,
           "maxStepsPerJob": 44,
           "decisions": 113
         },
         "current": {
-          "lines": 3341,
-          "jobs": 14,
-          "steps": 194,
-          "maxStepsPerJob": 44,
-          "decisions": 113
+          "lines": 2244,
+          "jobs": 15,
+          "steps": 170,
+          "maxStepsPerJob": 32,
+          "decisions": 87
         },
         "target": {
           "lines": 600,
@@ -3021,17 +2943,6 @@
           "decisions": 25
         }
       },
-      ".github/workflows/build.yml": {
-        "baseline": {
-          "lines": 1218
-        },
-        "current": {
-          "lines": 1218
-        },
-        "target": {
-          "lines": 600
-        }
-      },
       ".github/workflows/check.yml": {
         "baseline": {
           "maxStepsPerJob": 22
@@ -3191,7 +3102,7 @@
       "path": "tests/build-surface.test.mjs",
       "metric": "lines",
       "baseline": 4639,
-      "current": 3027
+      "current": 2909
     },
     {
       "domain": "workflows",