@kungfu-tech/buildchain 4.1.6-alpha.0 → 4.1.7-alpha.0

package/packages/core/runtime/entry/compatibility.js

@@ -0,0 +1,53 @@
+// Retain old selector names at the historical workflow boundary. The selected
+// runtime still goes through the same lock validation and trusted recovery gate.
+export function historicalEntrySelection(value, workflowRef) {
+  if (!value) return {};
+  const inputs = typeof value === "string" ? JSON.parse(value) : value;
+  if (!inputs || typeof inputs !== "object" || Array.isArray(inputs))
+    throw new Error("Historical entry inputs must be an object");
+  const read = (name, fallback = "") => {
+    const result = inputs[name] ?? fallback;
+    if (typeof result !== "string")
+      throw new Error(`Invalid historical selector: ${name}`);
+    return result;
+  };
+  if (
+    read("buildchain-repository", "kungfu-systems/buildchain") !==
+    "kungfu-systems/buildchain"
+  )
+    throw new Error(
+      "Historical entry requires the official Buildchain repository",
+    );
+  const calledChannel = /@(?:refs\/tags\/)?v4-alpha$/u.test(workflowRef)
+    ? "alpha"
+    : "stable";
+  const requested = read("buildchain-channel", "auto");
+  if (!["auto", "alpha", "stable"].includes(requested))
+    throw new Error("Invalid historical Buildchain channel");
+  const channel = requested === "auto" ? calledChannel : requested;
+  let ref = read("buildchain-ref").replace(/^v[23](-alpha)?$/u, "v4$1");
+  if (workflowRef?.split("@")[0] === "kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml") {
+    const recovery = read("resume-buildchain-runtime-sha");
+    if (recovery && !/^[a-f0-9]{40}$/u.test(recovery))
+      throw new Error("Historical recovery selector requires an exact runtime SHA");
+    if (recovery) ref = recovery;
+  }
+  const stableLock = read(
+    "buildchain-stable-contract-lock-path",
+    ".buildchain/contract-lock.json",
+  );
+  const alphaLock = read(
+    "buildchain-alpha-contract-lock-path",
+    ".buildchain/alpha-contract-lock.json",
+  );
+  return {
+    runtimeRef:
+      ref && ref !== (calledChannel === "alpha" ? "v4-alpha" : "v4") ? ref : "",
+    lockPath:
+      read("buildchain-contract-lock-path") ||
+      (channel === "alpha" ? alphaLock : stableLock),
+    channel,
+    stableLock,
+    alphaLock,
+  };
+}

package/packages/core/workflow/engine/conformance.js

@@ -1,6 +1,7 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { compatibilityWorkflowTarget } from "../../consumer/compatibility-workflows.js";
 import { exactObject, exactRuntime, fail, contentRoot } from "./identity.js";
 function rawFileRoot(runtimeRoot, relative) {
   const hash = crypto.createHash("sha256");
@@ -41,14 +42,17 @@ export function executeBootstrapConformance(
       ),
     ),
   );
+  const governed = [...new Set(architecture.bootstrapGovernedWorkflows.map(relative =>
+    compatibilityWorkflowTarget(runtimeRoot, relative, fs.readFileSync(path.join(runtimeRoot, relative), "utf8"))
+  ))];
   if (
-    architecture.bootstrapGovernedWorkflows.length !==
+    governed.length !==
       request.payload.expectedGovernedWorkflowCount ||
     architecture.status !== "active" ||
     policy.allowedCapabilities.includes("workflow-contract")
   )
     fail("candidate Bootstrap conformance does not close execution semantics");
-  for (const relative of architecture.bootstrapGovernedWorkflows) {
+  for (const relative of governed) {
     const source = fs.readFileSync(path.join(runtimeRoot, relative), "utf8");
     if (
       relative !== architecture.bootstrap.publicWorkflow &&
@@ -60,7 +64,7 @@ export function executeBootstrapConformance(
     schema: "kungfu-buildchain-v4-universal-bootstrap-conformance-result/v1",
     status: "candidate-engine-executed",
     runtime: exactRuntime(admission),
-    governedWorkflowCount: architecture.bootstrapGovernedWorkflows.length,
+    governedWorkflowCount: governed.length,
     architectureRoot: rawFileRoot(
       runtimeRoot,
       "architecture/universal-workflow-bootstrap.json",

package/packages/core/workflow/pipeline/controller.js

@@ -37,6 +37,11 @@ async function groupBuild(event, inputs, host) {
   return { operation: "build", context };
 }
 
+async function wakePipeline(host, attempt, reason) {
+  await host.wake(attempt);
+  return { operation: "wait", reason, attempt };
+}
+
 export async function controlPipeline(name, payload, inputs, host) {
   const event = pipelineEvent(name, payload, host.repository);
   host.terminalOnly = event.terminalOnly;
@@ -66,14 +71,12 @@ export async function controlPipeline(name, payload, inputs, host) {
   if (
     current.identity.requestKey.startsWith("recover:") &&
     recordDigest(current.events[0].runtime) !== recordDigest(host.runtime)
-  ) {
-    await host.wake(current.identity.id);
-    return {
-      operation: "wait",
-      reason: "admitted-recovery-runtime-continuation-required",
-      attempt: current.identity.id,
-    };
-  }
+  )
+    return wakePipeline(
+      host,
+      current.identity.id,
+      "admitted-recovery-runtime-continuation-required",
+    );
   if (
     ["failure", "cancelled", "superseded", "complete"].includes(
       session.observed.status,
@@ -90,14 +93,12 @@ export async function controlPipeline(name, payload, inputs, host) {
   if (
     admission.live.source &&
     host.selection.source.sha !== admission.live.source.commit
-  ) {
-    await host.wake(session.observed.attempt);
-    return {
-      operation: "wait",
-      reason: "source-generation-runtime-selection-required",
-      attempt: session.observed.attempt,
-    };
-  }
+  )
+    return wakePipeline(
+      host,
+      session.observed.attempt,
+      "source-generation-runtime-selection-required",
+    );
   if (session.intent.expectedNodes.includes("warrant"))
     host.queueExit ||= githubPipelineQueueExit(
       host.github.graphql,
@@ -118,16 +119,15 @@ export async function controlPipeline(name, payload, inputs, host) {
     return { operation: "build", context };
   }
   await host.project(session);
-  if (operation.operation === "successor") {
-    // Closed or retargeted PRs do not authorize a new attempt on the old route.
-    // A later normal event re-admits a lawful source after the old candidate ends.
-    await host.wake(session.observed.attempt);
-    return {
-      operation: "wait",
-      reason: operation.reason,
-      attempt: session.observed.attempt,
-    };
-  }
+  // PR run.head_sha and signing certificates can name different commits.
+  const dispatchPublication =
+    operation.operation === "publish" && event.kind !== "attempt";
+  if (operation.operation === "successor" || dispatchPublication)
+    return wakePipeline(
+      host,
+      session.observed.attempt,
+      operation.reason || "publication-requires-a-normal-dispatch",
+    );
   if (operation.operation === "settle") {
     const settled = await host.settle(
       session,

package/scripts/check-dev-delivery-actions.mjs

@@ -6,6 +6,7 @@ import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
 import YAML from "yaml";
 import { lowerSelfReferencesForLint } from "./workflow-self-reference.mjs";
+import { compatibilityWorkflowTarget } from "../packages/core/consumer/compatibility-workflows.js";
 const root = process.cwd();
 const contract = JSON.parse(fs.readFileSync(path.join(root, "architecture/dev-delivery-orchestration.json"), "utf8"));
 const temp = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "buildchain-delivery-actionlint-")));
@@ -16,6 +17,17 @@ try {
   fs.mkdirSync(path.join(temp, ".buildchain"));
   fs.symlinkSync(path.join(root, "actions"), path.join(temp, "actions"), "junction");
   const files = fs.readdirSync(workflows).filter(file => /\.ya?ml$/u.test(file)).map(file => path.join(workflows, file));
+  const configPath = path.join(temp, ".github/actionlint.yaml");
+  const config = YAML.parse(fs.readFileSync(configPath, "utf8"));
+  for (const file of files) {
+    const relative = `.github/workflows/${path.basename(file)}`;
+    const canonical = compatibilityWorkflowTarget(root, relative, fs.readFileSync(file, "utf8"));
+    // Verified generated copies inherit only their canonical source's scoped
+    // rules for GitHub contexts newer than the pinned actionlint release.
+    if (canonical !== relative && config.paths?.[canonical])
+      config.paths[relative] = config.paths[canonical];
+  }
+  fs.writeFileSync(configPath, YAML.stringify(config));
   for (const node of contract.nodes) for (const implementation of node.implementations) {
     const action = YAML.parse(fs.readFileSync(path.join(root, implementation.action), "utf8"));
     assert.deepEqual(Object.keys(action.inputs || {}), implementation.inputs, `${implementation.action}: input contract drift`);

package/scripts/check-inventory.mjs

@@ -296,7 +296,7 @@ assertPromotionInventory(root);
 for (const workflow of [channelBuildWorkflow, reusableBuildWorkflow]) {
   const block = workflow.split("    inputs:\n")[1].split("    secrets:\n")[0];
   const names = [...block.matchAll(/^      ([a-z0-9-]+):$/gm)].map((match) => match[1]);
-  if (JSON.stringify(names.sort()) !== JSON.stringify(['config-path','contract-lock','resume-run-id','runtime-ref','runtime-selection'])) throw new Error('build API must expose only the locator and unified runtime entry inputs');
+  if (JSON.stringify(names.sort()) !== JSON.stringify(['compatibility-inputs','config-path','contract-lock','resume-run-id','runtime-ref','runtime-selection'])) throw new Error('build component must expose only its locator, runtime transport and historical argument transport');
 }
 if ((channelBuildWorkflow.match(/uses: \.\/\.github\/workflows\/\.build\.yml/g) || []).length !== 1) {
   throw new Error("public build facade must invoke its exact backbone once");

package/scripts/check-public-dogfood-contract.mjs

@@ -5,6 +5,7 @@ import YAML from "yaml";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { checkSelfConsumerContract } from "./check-self-consumer-contract.mjs";
+import { compatibilityWorkflowTarget } from "../packages/core/consumer/compatibility-workflows.js";
 
 const DEFAULT_ROOT = path.resolve(
   path.dirname(fileURLToPath(import.meta.url)),
@@ -188,6 +189,7 @@ function assertWorkflowInventory(root) {
     if (!entry.isFile() || !/\.ya?ml$/u.test(entry.name)) continue;
     let relative = `.github/workflows/${entry.name}`;
     const text = read(root, relative);
+    relative = compatibilityWorkflowTarget(root, relative, text);
     if (
       relative !== REUSABLE_PATH &&
       (text.includes(

package/scripts/check-release-topology.mjs

@@ -5,6 +5,7 @@ import { assertPipelinePublicationTopology } from "./check-pipeline-publication-
 import { inspectWorkflowJob, readWorkflow } from "./workflow-action-graph.mjs";
 import crypto from "node:crypto";
 import fs from "node:fs";
+import { readConsumerUpgrade, compatibilityWorkflowTarget } from "../packages/core/consumer/compatibility-workflows.js";
 import ts from "typescript";
 
 import path from "node:path";
@@ -406,7 +407,10 @@ export function findUnknownReleaseTopology(
 }
 
 function assertClosedWorld(workflowPaths) {
-  const unknown = findUnknownReleaseTopology(workflowPaths);
+  const retained = (readConsumerUpgrade(root)?.entries || []).filter(entry =>
+    workflowPaths.includes(compatibilityWorkflowTarget(root, entry.path, read(entry.path)))
+  ).map(entry => entry.path);
+  const unknown = findUnknownReleaseTopology([...workflowPaths, ...retained]);
   assert.deepEqual(
     unknown,
     [],

package/scripts/check-self-consumer-contract.mjs

@@ -4,7 +4,8 @@ import { fileURLToPath } from "node:url";
 import { parse as yaml } from "yaml";
 import * as consumerPlan from "../packages/core/consumer/contract/plan.js";
 import { consumerWorkflows } from "../packages/core/consumer/contract/entries.js";
-import { workflowPath } from "../packages/core/workflow/workflow-taxonomy.mjs";
+import { checkWorkflowTaxonomy, workflowPath } from "../packages/core/workflow/workflow-taxonomy.mjs";
+import { readConsumerUpgrade } from "../packages/core/consumer/compatibility-workflows.js";
 
 export const SELF_ENTRY_CHANNEL = "v4";
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -33,6 +34,9 @@ export function checkSelfConsumerContract(root = ROOT) {
     if (read(file) !== bytes) fail(`${file}: generated caller drift`);
   const taxonomy = JSON.parse(read("architecture/workflow-taxonomy.json"));
   const registered = new Set(taxonomy.entries.map(workflowPath));
+  const inventory = checkWorkflowTaxonomy(root, { integration: false, documentation: false });
+  if (!inventory.ok) fail(inventory.errors.join("; "));
+  for (const entry of readConsumerUpgrade(root)?.entries || []) registered.add(entry.path);
   const observed = fs
     .readdirSync(path.join(root, ".github/workflows"))
     .filter((file) => /\.ya?ml$/u.test(file))

package/scripts/generate-bootstrap-admission.mjs

@@ -3,6 +3,7 @@ import { format } from "prettier";
 import path from "node:path";
 import crypto from "node:crypto";
 import { fileURLToPath } from "node:url";
+import { readConsumerUpgrade } from "../packages/core/consumer/compatibility-workflows.js";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const contract = JSON.parse(
@@ -16,6 +17,25 @@ const target = path.join(
   "architecture/universal-workflow-capability-policy.json",
 );
 const policy = JSON.parse(fs.readFileSync(target, "utf8"));
+for (const entry of readConsumerUpgrade(root)?.entries || []) {
+  if (!entry.interface.workflow_call) continue;
+  for (const field of [
+    "inventoryWorkflows",
+    "directCapabilityWorkflows",
+    "bootstrapGovernedWorkflows",
+  ]) {
+    if (
+      contract[field].includes(entry.target) &&
+      !contract[field].includes(entry.path)
+    )
+      contract[field].push(entry.path);
+    contract[field].sort();
+  }
+}
+fs.writeFileSync(
+  path.join(root, "architecture/universal-workflow-bootstrap.json"),
+  await format(JSON.stringify(contract), { parser: "json" }),
+);
 policy.contractRoots = contract.bootstrap.admissionPolicySources
   .map((file) => {
     if (path.isAbsolute(file) || file.split("/").includes(".."))

package/scripts/generate-site-bundle.mjs

@@ -2,6 +2,7 @@
 import { actionSurfaceAudit } from "./site-action-audit.mjs";
 import { actionInventory } from "../packages/core/contracts/action-inventory.js";
 import { readWorkflowTaxonomy, workflowPath } from "../packages/core/workflow/workflow-taxonomy.mjs";
+import { readConsumerUpgrade } from "../packages/core/consumer/compatibility-workflows.js";
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
@@ -830,12 +831,14 @@ function buildSiteBundle() {
   };
   const nodeApiRegistry = createSiteNodeApiRegistry({ root, packageJson, nodeApiMeta, sha256File, publicSurfaceLifecycle });
   const taxonomy = readWorkflowTaxonomy(root);
+  const retainedEntries = readConsumerUpgrade(root)?.entries || [];
   const workflowRegistry = {
     schemaVersion: 1,
     contract: "kungfu-buildchain-workflow-registry",
     workflowSource: ".github/workflows reverse input enumeration",
     workflows: enumerateWorkflowInputs({ root }).map((entry) => {
-      const classification = taxonomy?.entries.find((item) => workflowPath(item) === entry.path || item.compatibility?.path === entry.path);
+      const retained = retainedEntries.find(item => item.path === entry.path);
+      const classification = taxonomy?.entries.find((item) => workflowPath(item) === (retained?.target || entry.path));
       const semanticId = classification?.id || entry.id;
       const surfaceById = new Map([
         ["build", "channel-build-router"],
@@ -877,14 +880,10 @@ function buildSiteBundle() {
         [".auditable-demo", "preview"],
         [".declarative-auditable-demo", "preview"],
         ["release-propagation", "preview"],
-        ["candidate-lab", "repository-internal"],
-        ["build-surface-fixture", "repository-internal"],
-        ["buildchain-stable-candidate-qualification", "repository-internal"],
         ["engineering-housekeeper", "preview"],
         ["engineering-housekeeper-daily", "preview"],
         ["engineering-housekeeper-weekly", "preview"],
         ["engineering-housekeeper-monthly", "preview"],
-        ["self-hosted-runner-smoke", "compatibility-fixture"],
       ]);
       const engineeringHousekeeper = semanticId.startsWith("engineering-housekeeper");
       if (classification?.role === "component") statusById.set(semanticId, "repository-internal");
@@ -905,6 +904,7 @@ function buildSiteBundle() {
             ? "One reusable policy and evidence boundary owns Engineering Housekeeper execution; scheduled callers contain cadence values only."
             : "Canonical workflow owns one declared API or orchestration responsibility.",
         }),
+        ...(retained ? { compatibilityPromise: "retained-consumer-contract", status: "compatibility", apiRole: "compatibility", nonDuplicationRationale: "Generated from the registered canonical implementation; retained published inputs, outputs, defaults, permissions and job contexts are verified before release." } : {}),
       };
     }),
     actionSource: "actions/*/*/*/action.yml reverse input enumeration",

package/scripts/generate-workflow-taxonomy.mjs

@@ -1,6 +1,10 @@
 #!/usr/bin/env node
 import fs from "node:fs";
 import path from "node:path";
+import {
+  compatibilityWorkflowEntries,
+  renderCompatibilityWorkflow,
+} from "../packages/core/consumer/compatibility-workflows.js";
 import {
   readWorkflowTaxonomy,
   renderWorkflowCatalog,
@@ -19,6 +23,19 @@ for (const entry of policy.entries) {
     fs.readFileSync(path.join(root, workflowPath(entry)), "utf8"),
   );
 }
+for (const entry of compatibilityWorkflowEntries(
+  root,
+  undefined,
+  policy.entries.map((entry) => ({ ...entry, path: workflowPath(entry) })),
+)) {
+  fs.writeFileSync(
+    path.join(root, entry.path),
+    renderCompatibilityWorkflow(
+      entry,
+      fs.readFileSync(path.join(root, entry.target), "utf8"),
+    ),
+  );
+}
 fs.writeFileSync(path.join(root, TAXONOMY_DOC), renderWorkflowCatalog(policy));
 process.stdout.write(
   `Generated ${policy.entries.length} canonical workflow declarations.\n`,

package/scripts/maintainability-metrics.mjs

@@ -5,6 +5,10 @@ import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { pathToFileURL } from "node:url";
 import ts from "typescript";
+import {
+  CONSUMER_UPGRADE_PATH,
+  renderCompatibilityWorkflow,
+} from "../packages/core/consumer/compatibility-workflows.js";
 import {
   dependencyCycles,
   relativeImports,
@@ -292,7 +296,29 @@ function collectMaintainabilityMetrics({
     path: file,
     text: readTrackedFile(root, file, revision),
   }));
-  const logicalWorkflows = physicalWorkflows;
+  const retained = files.includes(CONSUMER_UPGRADE_PATH)
+    ? JSON.parse(readTrackedFile(root, CONSUMER_UPGRADE_PATH, revision)).entries
+    : [];
+  const generatedWorkflows = new Set(
+    retained
+      .filter((entry) => {
+        const actual = physicalWorkflows.find(
+          (file) => file.path === entry.path,
+        );
+        const canonical = physicalWorkflows.find(
+          (file) => file.path === entry.target,
+        );
+        return (
+          actual &&
+          canonical &&
+          actual.text === renderCompatibilityWorkflow(entry, canonical.text)
+        );
+      })
+      .map((entry) => entry.path),
+  );
+  const logicalWorkflows = physicalWorkflows.filter(
+    (entry) => !generatedWorkflows.has(entry.path),
+  );
   const workflowMetrics = Object.fromEntries(
     logicalWorkflows.map((entry) => [
       entry.path,
@@ -319,7 +345,7 @@ function collectMaintainabilityMetrics({
     (total, entry) => total + entry.lines,
     0,
   );
-  const workflowLines = sumLines(workflowFiles);
+  const workflowLines = sumLines(logicalWorkflows.map((entry) => entry.path));
   const actionDefinitionLines = sumLines(actionDefinitions);
   const head = revision || gitText(root, ["rev-parse", "HEAD"]).trim();
   return {
@@ -334,6 +360,8 @@ function collectMaintainabilityMetrics({
       testLines: sumLines(testFiles),
       workflowFiles: logicalWorkflows.length,
       workflowLines,
+      generatedCompatibilityWorkflowFiles: generatedWorkflows.size,
+      generatedCompatibilityWorkflowLines: sumLines([...generatedWorkflows]),
       actionDefinitions: actionDefinitions.length,
       actionDefinitionLines,
       automationImplementationLines:

package/scripts/maintainability-public-surface.mjs

@@ -1,14 +1,15 @@
 import fs from "node:fs";
 import path from "node:path";
+import { readConsumerUpgrade } from "../packages/core/consumer/compatibility-workflows.js";
 
 function readJson(root, file) {
   return JSON.parse(fs.readFileSync(path.join(root, file), "utf8"));
 }
 
-// Public API ownership follows the current architecture. Retired release
-// contracts do not require aliases or forwarding implementations in 4.1.
+// Current APIs and explicitly retained published contracts have distinct owners.
 export function evaluatePublicSurface({ root, policy }) {
   const issues = [];
+  const retained = new Set((readConsumerUpgrade(root)?.entries || []).map(entry => entry.path));
   const groups = new Set(readJson(root, "dist/site/capability-registry.json").groups.map(entry => entry.id));
   for (const [file, collection, kind, key] of [
     ["dist/site/cli-registry.json", "commands", "cli", "id"],
@@ -26,7 +27,8 @@ export function evaluatePublicSurface({ root, policy }) {
       }
       if (!groups.has(entry.capabilityGroup)) issues.push(`${label}: capability group ${entry.capabilityGroup || "<empty>"} is not registered`);
       if (!entry.nonDuplicationRationale?.trim()) issues.push(`${label}: public surface requires a non-duplication rationale`);
-      if (entry.compatibilityPromise !== "current-contract-only") issues.push(`${label}: historical compatibility promise is not part of the current architecture`);
+      const promise = kind === "workflow" && retained.has(entry.path) ? "retained-consumer-contract" : "current-contract-only";
+      if (entry.compatibilityPromise !== promise) issues.push(`${label}: compatibility promise does not match the registered contract`);
       if (kind === "action" && !["public", "implementation"].includes(entry.apiRole)) issues.push(`${label}: action API role is missing`);
       const target = kind === "node" ? entry.target : ["workflow", "action"].includes(kind) ? entry.path : null;
       if (target) {