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

package/docs/runtime-train-validation.md

@@ -6,183 +6,56 @@ doc_type: technical-reference
 source_level: local-files
 confidence: high
 sensitivity: public
-evidence_grade: A
+evidence_grade: B
 review_state: unreviewed
-last_reviewed: 2026-07-31
+last_reviewed: 2026-09-08
 ai_provenance:
-  model_family: GPT-5
+  model_family: GPT-6
   product: Codex
-  generated_at: 2026-07-31
+  generated_at: 2026-09-08
   invisible_context: not asserted
 ---
 
 # Runtime Train Validation
 
-Buildchain consumers should keep stable workflow refs such as `@v3` in
-committed workflow YAML. Runtime trains provide a temporary validation pointer
-for Buildchain changes that are ready for downstream testing but not yet
-promoted through the normal `dev -> alpha -> release` chain.
-
-Official floating channels are not runtime overrides. A consumer that
-deliberately follows `@v3-alpha` gets the matching runtime on pull requests and
-pushes because the reusable workflow reads the called workflow identity from
-`job.workflow_ref`. Passing `buildchain-ref: v3-alpha` explicitly is also
-accepted when the caller wants the channel binding visible in its input set.
-The caller's `github.workflow_ref` is not used for this inference because it
-identifies the caller workflow during reusable calls.
-
-## Train refs
-
-A train ref is a branch in the Buildchain repository:
-
-```text
-train/v3/v3.0/<capability>
-```
-
-It is a validation pointer, not a release channel:
-
-- it does not move `v3`, `vX.Y`, `vX.Y-alpha`, exact tags, npm dist-tags, or
-  production refs;
-- it must not be pinned as a long-term production dependency;
-- it should point at the Buildchain commit that downstream maintainers are
-  expected to validate;
-- it is not a pending merge target or a delivery state;
-- the final durable path is still a pull request into the active `dev/*`
-  channel, followed by the requested alpha or release promotion.
-- it may remain for a retention window after release so initiating repositories
-  have a stable fast-use and rollback channel while stable refs, caches, or
-  rollout windows settle.
-
-## Buildchain contributor requirement
-
-When a Buildchain change needs downstream validation before stable refs move,
-publish a train ref before asking consumers to test it:
-
-```sh
-git push origin HEAD:refs/heads/train/v3/v3.0/<capability>
-```
-
-Use a capability slug that names the behavior being validated, for example:
-
-```text
-train/v3/v3.0/runtime-loader
-train/v3/v3.0/toolkit-diagnostics
-train/v3/v3.0/site-source-of-truth
-```
-
-The pull request or validation request should include the train ref, the exact
-commit SHA it points to, and the downstream evidence expected from consumers.
-If the train is refreshed, state the new SHA in the validation thread.
-
-After downstream validation succeeds, close out through the normal release
-path. Merge the Buildchain pull request into the active `dev/*` mainline, run
-the requested alpha or release promotion, and record the final mainline commit
-plus release ref or tag in the delivery thread. Do not leave the train as the
-item that still needs to be merged; it is only a temporary fast-use,
-diagnostic, and rollback channel for initiating repositories. Retained trains
-are cleaned up by a separate periodic Buildchain cleanup task.
-
-## Formal artifact-signing authority ref
-
-Artifact signing uses a durable, channel-neutral authority ref after its
-runtime has passed downstream validation:
-
-```text
-authority/v3/v3.0/artifact-signing
-```
-
-Unlike a train, this ref is a protected execution boundary. Alpha and stable
-release intent use the same authority ref and the same
-`buildchain-artifact-signing` environment; channel promotion never selects a
-different certificate environment. Updates to the authority ref require a
-reviewed pull request, the normal `check` and `verify` status contexts, and a
-fast-forward-safe protected branch policy. Deletion and non-fast-forward
-updates are forbidden.
-
-The temporary `train/v3/v3.0/artifact-signing-authority` ref remains a bounded
-rollback and diagnostic pointer during migration. It is not the production
-identity and must not regain credential ownership.
-
-## Consumer workflow requirement
-
-Consumers keep their reusable workflow pinned to the stable shell:
-
-```yaml
-jobs:
-  build:
-    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3
-```
-
-To validate a train without committing temporary workflow refs, expose a
-trusted manual pass-through once:
-
-```yaml
-on:
-  workflow_dispatch:
-    inputs:
-      buildchain-ref:
-        description: "Temporary Buildchain runtime ref for trusted manual validation"
-        required: false
-        default: ""
-
-jobs:
-  build:
-    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3
-    with:
-      buildchain-ref: ${{ inputs.buildchain-ref || '' }}
-```
-
-Buildchain initializes new package workflows with this pass-through. Existing
-consumers that do not have it should add it once before validating a train.
-
-## Validation request
-
-Use this short request when a train is ready:
-
-```text
-Buildchain train ready: buildchain-ref=train/v3/v3.0/<capability>.
-Keep uses: ...@v3; run workflow_dispatch with that buildchain-ref and report the runtime evidence summary.
-```
-
-The consumer should run a trusted `workflow_dispatch`, paste the train ref into
-`buildchain-ref`, and report the workflow summary or aggregate Buildchain
-summary. The evidence should include:
-
-- workflow shell ref;
-- requested runtime ref;
-- resolved runtime ref;
-- resolved runtime SHA;
-- stability class;
-- trust decision;
-- rollback ref.
-
-## Trust and limitation
-
-Official floating channel refs such as `v3` and `v3-alpha` may be selected on
-pull requests and pushes. Train refs and arbitrary exact-SHA overrides still
-fail closed unless the event is `workflow_dispatch` and the actor has write,
-maintain, or admin permission on the caller repository. Pull requests,
-including fork-originated pull requests, cannot use train or exact-SHA
-overrides.
-
-That permission does not create a third channel. A train, authority ref, or
-exact SHA must be bound to an alpha or stable shell lane, and the consumer lock
-must prove that same lane and major. Trusted overrides can replace the runtime
-coordinate for validation; they cannot combine a stable shell or lock with an
-alpha runtime, or the reverse.
-
-Runtime train validation covers Buildchain runtime scripts, CLI code, local
-actions, configuration parsing, and lifecycle behavior. It cannot validate
-changes that require the outer reusable workflow YAML itself to change, such as
-new jobs, permissions, workflow outputs, or matrix topology. Those changes need
-a canary workflow path or a temporary explicit workflow ref.
-
-## v4 persisted-selector boundary
-
-For v4 consumers, never commit a train or exact SHA in a `uses` node. Keep the
-caller on `@v4` or `@v4-alpha`, retain both stable and alpha contract locks, and
-pass a temporary train/SHA only through the trusted `workflow_dispatch`
-`buildchain-ref` input. Consumer admission binds the selected lock to the exact
-workflow-shell commit while recording the separately resolved runtime SHA.
-Therefore a train can exercise candidate runtime code without weakening the
-durable floating-selector policy or masquerading as a channel promotion.
+Ordinary builds use the public `build.yml@v4` or `build.yml@v4-alpha`
+workflow and select all project settings from `buildchain.toml`. The called
+workflow SHA also selects the runtime; there is no second runtime selector.
+See [Reusable Build Surface](reusable-build-surface.md) for configuration,
+zero-input calls and the optional nested-project locator.
+
+## Alpha qualification
+
+Buildchain changes enter the protected development branch after review and
+checks. Publish an alpha through the protected release workflow, then exercise
+that public alpha on the exact consumer source. Record the called workflow SHA,
+source SHA, channel-matching contract lock, configuration root and artifact
+manifests. Promote stable only after the required alpha evidence succeeds.
+
+For a breaking build-interface change, publish the producer before changing
+its own public consumers. Retain the callers and locks for the currently
+published interface while creating the first alpha from a successful PR-stage
+candidate. Then migrate the callers and accept the published alpha contract,
+qualify that public interface, and publish the completed alpha and stable.
+This ordering adds no compatibility inputs to the new build workflow.
+
+Source checks verify each consumer lock against the immutable source contract
+at its accepted SHA. Hosted consumer admission separately verifies the actual
+called floating workflow; unpublished producer code is not that dependency.
+
+A train branch is a temporary diagnostic pointer, never a release channel or a
+persisted consumer dependency. Ordinary builds do not accept train, SHA or
+`buildchain-ref` inputs. Initialization does not create a runtime pass-through.
+
+## Specialized release and recovery
+
+Release and recovery entry points retain their own bounded runtime admission
+contracts. Their runtime override capability does not extend to ordinary builds.
+Follow [Release Flow](release-flow.md) and the particular entry point's contract;
+a diagnostic train does not authorize publication, signing, or floating-ref
+movement. Preserve existing source locks, exact candidate lineage and terminal
+receipts when recovering a release.
+
+The Buildchain self-build callers exercise the public floating channels using
+root or fixture TOML. They do not commit a private runtime selector to qualify
+that channel.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "4.0.8",
+  "version": "4.0.9-alpha.0",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",

package/packages/core/build-configuration.js

@@ -0,0 +1,117 @@
+import fs from "node:fs";
+import path from "node:path";
+
+// Project choices only. Provider endpoints, roles, runner labels and cache
+// transport authority belong to the selected, runtime-owned environment.
+const sections = {
+  tools: { node: "24", rust: "" },
+  artifacts: {
+    name: "buildchain-artifact", paths: ["dist", "build/stage"],
+    required_paths: [], min_files: 0, max_files: Number.MAX_SAFE_INTEGER,
+    min_total_bytes: 0, retention_days: 14, compression_level: 0,
+    release_candidate: false,
+  },
+  diagnostics: {
+    sample_process_tree: true, sample_interval_ms: 15000,
+    requested_parallelism: 0,
+  },
+  verification: { substage_evidence_path: "" },
+  finalization: { command: "", on_platform: false },
+  transport_smoke: { scenario_path: "", artifact_root: "." },
+  attestation: { subject_path: "", platform: "linux-x64" },
+  macos_signing: { app_path: "", platform: "macos-arm64" },
+  contract: {
+    compatibility_policy: "major-compatible",
+    drift_issue_mode: "compatible-and-breaking",
+  },
+  evidence: { gate_profile_path: "", candidate_family_path: "" },
+};
+const choices = {
+  "contract.compatibility_policy": ["major-compatible", "allow-additive", "exact"],
+  "contract.drift_issue_mode": ["off", "breaking-only", "compatible-and-breaking"],
+};
+const ranges = {
+  timeout_minutes: [1, 360],
+  "artifacts.retention_days": [1, 90],
+  "artifacts.compression_level": [0, 9],
+  "artifacts.min_files": [0, Number.MAX_SAFE_INTEGER],
+  "artifacts.max_files": [0, Number.MAX_SAFE_INTEGER],
+  "artifacts.min_total_bytes": [0, Number.MAX_SAFE_INTEGER],
+  "diagnostics.sample_interval_ms": [100, 3600000],
+  "diagnostics.requested_parallelism": [0, 1024],
+};
+
+function table(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be a table`);
+  }
+  return value;
+}
+
+function fields(value, defaults, prefix) {
+  table(value, `build.${prefix}`);
+  for (const key of Object.keys(value)) {
+    if (!Object.hasOwn(defaults, key)) throw new Error(`Unknown build.${prefix}${key}`);
+  }
+  return Object.fromEntries(Object.entries(defaults).map(([key, fallback]) => {
+    const label = `${prefix}${key}`;
+    const selected = value[key] === undefined ? structuredClone(fallback) : value[key];
+    const valid = Array.isArray(fallback)
+      ? Array.isArray(selected) && selected.every((item) => typeof item === "string" && item.trim())
+      : typeof selected === typeof fallback;
+    if (!valid || (typeof selected === "string" && /\0/u.test(selected))) {
+      throw new Error(`Invalid build.${label} type or multiline value`);
+    }
+    if (ranges[label] && (!Number.isInteger(selected) || selected < ranges[label][0] || selected > ranges[label][1])) {
+      throw new Error(`build.${label} must be an integer in ${ranges[label].join("..")}`);
+    }
+    if (choices[label] && !choices[label].includes(selected)) throw new Error(`Invalid build.${label}: ${selected}`);
+    return [key, selected];
+  }));
+}
+
+export function normalizeBuildConfiguration(value = {}) {
+  table(value, "build");
+  const { environment = "github-hosted", fail_fast = false, timeout_minutes = 120, ...groups } = value;
+  const result = fields({ environment, fail_fast, timeout_minutes }, { environment: "github-hosted", fail_fast: false, timeout_minutes: 120 }, "");
+  if (!/^[a-z][a-z0-9-]*$/u.test(result.environment)) throw new Error("Invalid build.environment profile name");
+  for (const name of Object.keys(groups)) {
+    if (!Object.hasOwn(sections, name)) throw new Error(`Unknown build.${name}`);
+  }
+  for (const [name, defaults] of Object.entries(sections)) {
+    result[name] = fields(groups[name] === undefined ? {} : groups[name], defaults, `${name}.`);
+  }
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/u.test(result.artifacts.name)) throw new Error("Invalid build.artifacts.name");
+  if (result.artifacts.min_files > result.artifacts.max_files) throw new Error("build.artifacts.min_files exceeds max_files");
+  return result;
+}
+
+export function containedBuildPath(root, relative) {
+  if (typeof relative !== "string" || !relative || path.isAbsolute(relative) || relative.includes("\\") || /[\r\n\0]/u.test(relative) || relative.split("/").includes("..")) {
+    throw new Error("Build configuration paths must remain repository-relative");
+  }
+  const resolved = path.resolve(root, relative);
+  const realRoot = fs.realpathSync(root);
+  // Reject symlink escape through any existing parent, including a missing leaf.
+  let ancestor = resolved;
+  while (!fs.existsSync(ancestor)) ancestor = path.dirname(ancestor);
+  const realAncestor = fs.realpathSync(ancestor);
+  if (realAncestor !== realRoot && !realAncestor.startsWith(`${realRoot}${path.sep}`)) {
+    throw new Error(`Build configuration path escapes repository: ${relative}`);
+  }
+  return resolved;
+}
+
+export function discoverBuildConfiguration(root, locator = "") {
+  const candidates = locator ? [locator] : [".buildchain/buildchain.toml", "buildchain.toml"];
+  const found = candidates.filter((candidate) => fs.existsSync(containedBuildPath(root, candidate)));
+  if (found.length !== 1) throw new Error(`Expected one buildchain.toml; found ${found.length}. Use config-path for a project outside the repository root.`);
+  const configPath = found[0];
+  if (path.basename(configPath) !== "buildchain.toml") throw new Error("config-path must locate a project's buildchain.toml");
+  const directory = path.posix.dirname(configPath);
+  const cwd = path.posix.basename(directory) === ".buildchain" ? path.posix.dirname(directory) : directory;
+  // Lifecycle and planning must discover the same file, never a second config.
+  const projectConfigs = [".buildchain/buildchain.toml", "buildchain.toml"].filter((candidate) => fs.existsSync(containedBuildPath(root, path.posix.join(cwd, candidate))));
+  if (projectConfigs.length !== 1) throw new Error("Ambiguous project configuration");
+  return { configPath, cwd };
+}

package/packages/core/buildchain-config.js

@@ -8,6 +8,7 @@ import {
   resolveBuildchainConfigPath,
 } from "./buildchain-layout.js";
 import { runShellCommandSync } from "./spawn-command.js";
+import { normalizeBuildConfiguration } from "./build-configuration.js";
 
 const CONFIG_FILE = BUILDCHAIN_CONFIG_PATH;
 const RESERVED_LIFECYCLE_KEYS = new Set(["env", "shell"]);
@@ -206,6 +207,7 @@ export function loadBuildchainConfig(cwd = process.cwd()) {
 export function normalizeBuildchainConfig(config) {
   assertPlainObject(config, CONFIG_FILE);
   const normalized = { ...config };
+  if (normalized.build !== undefined) normalized.build = normalizeBuildConfiguration(normalized.build);
   if (normalized.project !== undefined) {
     normalized.project = normalizeProjectSection(normalized.project);
   }

package/packages/core/buildchain-contract.js

@@ -236,24 +236,11 @@ export function createBuildchainContractWorld({
         "release-candidate-artifact",
       ],
       breakingDefaults: {
-        buildchainRefDefault: "workflow-shell-ref-or-v3",
-        promoteOnlyHeavyBuildPolicy: "pr-stage-only",
+        configurationAuthority: "buildchain.toml",
+        runtimeIdentity: "exact-called-workflow",
+        projectDiscovery: "unambiguous-root-or-config-path",
       },
-      optionalInputs: [
-        "buildchain-ref",
-        "runner-preset",
-        "platforms-json",
-        "release-candidate",
-        "github-artifact-attestation-subject-path",
-        "github-artifact-attestation-platform-id",
-        "artifact-transfer-mode",
-        "checkout-cache-mode",
-        "checkout-cache-fallback",
-        "checkout-cache-timeout-seconds",
-        "checkout-cache-fetch-attempts",
-        "buildchain-contract-lock-path",
-        "buildchain-contract-drift-issue-mode",
-      ],
+      optionalInputs: ["config-path"],
       guarantees: [
         "runtime floating refs are resolved to immutable SHAs before matrix jobs",
         "publish source locks are verified before heavy build jobs",
@@ -270,26 +257,17 @@ export function createBuildchainContractWorld({
       requiredInputs: [],
       requiredOutputs: ["buildchain-channel", "buildchain-runtime-sha", "build-summary-artifact"],
       breakingDefaults: {
-        channelDefault: "auto",
-        developmentDefault: "alpha",
-        prereleaseDefault: "alpha",
-        stableReleaseDefault: "stable",
-        ambiguousReleasePolicy: "fail-closed",
+        configurationAuthority: "buildchain.toml",
+        runtimeIdentity: "exact-called-workflow",
+        projectDiscovery: "unambiguous-root-or-config-path",
       },
-      optionalInputs: [
-        "buildchain-channel",
-        "buildchain-ref",
-        "buildchain-alpha-contract-lock-path",
-        "buildchain-stable-contract-lock-path",
-        "buildchain-contract-lock-path",
-      ],
+      optionalInputs: ["config-path"],
       guarantees: [
-        "consumers declare one build job while Buildchain selects the matching generic major channel",
-        "development and prerelease intent select vN-alpha",
-        "stable release intent selects vN",
-        "ambiguous release-like intent fails before build jobs",
-        "explicit train and exact-SHA overrides retain the reusable build trust gate",
-        "alpha and stable channel selections use separate consumer contract locks by default",
+        "single-project consumers require no workflow inputs",
+        "project settings have one TOML authority and environment profiles own infrastructure",
+        "the called floating ref determines channel and exact runtime SHA",
+        "stable and alpha select their matching repository contract locks",
+        "source, runtime and configuration roots are bound before the build matrix",
       ],
     }),
     surface(root, devDeliveryWorkflowContractSurface(pkg, majorLine)),
@@ -837,7 +815,7 @@ export function createBuildchainContractWorld({
         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",
+        inputClassificationPolicy: descriptor.id === "build-lifecycle" ? "buildchain-configured-controller-input-policy/v1" : "buildchain-controller-input-policy/v1",
       },
       optionalInputs: Object.keys(descriptor.inputs),
       controllerDescriptor: {
@@ -846,14 +824,6 @@ export function createBuildchainContractWorld({
         registryDigest: resolvedControllerRegistry.digest,
         inputClassifications: descriptor.inputs,
       },
-      ...(descriptor.id === "build-lifecycle"
-        ? {
-            compatibleBreakingDigests: [
-              "sha256:e264a79f9f399038c2fcfd21e4168c68c2e1485ee5c651c02242a02b622ac2be",
-              "sha256:30745921541e9b0f70475bb2178c2559f6aef248f6680670ccd44d8c5a69a6b1",
-            ],
-          }
-        : {}),
       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",

package/packages/core/controller-evidence.js

@@ -22,6 +22,7 @@ const CONTROLLER_SPECS = [
     id: "build-lifecycle",
     workflowId: ".build",
     version: 1,
+    derivedInputs: { "configuration-root": { classification: "included", source: "resolved-build-plan" } },
     capabilities: [
       "source-lock",
       "lifecycle-build",
@@ -47,15 +48,6 @@ const CONTROLLER_SPECS = [
       "controller-receipt",
     ],
   },
-  {
-    id: "build-channel-router",
-    workflowId: "build",
-    version: 1,
-    capabilities: ["channel-selection", "runtime-selection", "build-delegation"],
-    stages: ["resolve-channel", "override", "alpha", "stable", "aggregate"],
-    optionalStages: ["override", "alpha", "stable"],
-    evidence: ["nested-controller-receipt", "controller-receipt"],
-  },
   {
     id: "shifu-gate-profile-envelope",
     workflowId: ".gate-profile",
@@ -208,6 +200,7 @@ export function createControllerRegistry({ workflows = [] } = {}) {
       classification: classifyInput(name, secrets),
       source: secrets.has(name) ? "workflow-call-secret" : "workflow-call-input",
     }]));
+    Object.assign(inputs, spec.derivedInputs || {});
     for (const [name, policy] of Object.entries(workflow.inputPolicies || {})) {
       if (!inputs[name]) throw new Error(`controller ${spec.id} input policy references undeclared input ${name}`);
       inputs[name] = { ...inputs[name], ...policy };

package/scripts/buildchain-cli-help.mjs

@@ -24,7 +24,7 @@ export const BUILDCHAIN_USAGE = `Usage:
   buildchain candidate timeline --input <file-or-json> [--output <file>] [--json]
   buildchain init [--cwd <dir>] [--type package|native|web-surface|infra-contract|publication-artifact|anchored-package] [--force]
                   [--package-manager pnpm|npm|yarn] [--runner-preset <preset>]
-                  [--artifact-name <template>]
+                  [--artifact-name <name>]
   buildchain validate [--cwd <dir>] [--require-version-state]
                       [--require-lifecycle-stages <comma-list>]
   buildchain lifecycle run <stage> [--cwd <dir>] [--required]

package/scripts/check-floating-consumer-policy-contract.mjs

@@ -123,15 +123,12 @@ export function checkFloatingConsumerPolicyContract() {
   ]);
   const buildWorkflow = read(".github/workflows/.build.yml");
   if (
-    !buildWorkflow.includes("Normalize v3 expected identity aliases") ||
+    buildWorkflow.includes("Normalize v3 expected identity aliases") ||
+    buildWorkflow.includes("buildchain-expected-channel:") ||
     !buildWorkflow.includes(
-      "buildchain-contract-expected-channel conflicts with buildchain-expected-channel",
+      "BUILDCHAIN_EXPECTED_INVOCATION_CHANNEL: ${{ fromJSON(needs.configure.outputs.plan-json).identity.channel }}",
     ) ||
-    !buildWorkflow.includes(
-      "BUILDCHAIN_EXPECTED_INVOCATION_CHANNEL: ${{ steps.expected-identity.outputs.expected-channel }}",
-    ) ||
-    buildWorkflow.indexOf("Normalize v3 expected identity aliases") >
-      buildWorkflow.indexOf("Enforce v4 floating consumer policy")
+    !buildWorkflow.includes("BUILDCHAIN_WORKFLOW_SHA: ${{ job.workflow_sha }}")
   )
     fail("channel builds must disambiguate dual-channel caller invocations");
   assertTrustGatedJobs(read(".github/workflows/.build.yml"), [