@kungfu-tech/buildchain 2.3.1-alpha.0 → 2.3.1-alpha.1

package/scripts/run-lifecycle-core.mjs

@@ -1,8 +1,9 @@
 import crypto from "node:crypto";
-import { execSync } from "node:child_process";
+import { execFileSync, execSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import {
   loadBuildchainConfig,
   normalizeLifecycleStage,
@@ -13,12 +14,32 @@ import {
   readBuildchainLogEvents,
   summarizeBuildchainLogEvents,
 } from "../packages/core/logging.js";
+import {
+  BUILDCHAIN_DIAGNOSTICS_CONTRACT,
+  BUILDCHAIN_DIAGNOSTICS_MANIFEST_CONTRACT,
+  BUILDCHAIN_PROCESS_SAMPLE_REPORT_CONTRACT,
+  BUILDCHAIN_PROCESS_SAMPLE_SUMMARY_CONTRACT,
+  createDiagnosticsArtifact,
+  summarizeLifecycleObservability,
+  writeDiagnosticsArtifact,
+} from "../packages/core/diagnostics.js";
 import {
   createArtifactSummary,
   parseExpectedArtifactsJson,
   validateExpectedArtifacts,
 } from "./build-contract-core.mjs";
 
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+const buildchainCliCandidates = [
+  path.resolve(moduleDir, "..", "bin", "buildchain.mjs"),
+  path.resolve(moduleDir, "..", "..", "..", "bin", "buildchain.mjs"),
+  path.resolve(process.cwd(), ".buildchain", "runtime", "bin", "buildchain.mjs"),
+];
+
+function resolveBuildchainCliPath() {
+  return buildchainCliCandidates.find((candidate) => fs.existsSync(candidate)) || buildchainCliCandidates[0];
+}
+
 function sha256File(filePath) {
   const hash = crypto.createHash("sha256");
   hash.update(fs.readFileSync(filePath));
@@ -71,6 +92,224 @@ function collectArtifactFiles(root, patterns) {
   return [...files].sort();
 }
 
+function readProcessSummaryArtifact(filePath) {
+  if (!filePath) {
+    return undefined;
+  }
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`process summary file not found: ${filePath}`);
+  }
+  let artifact;
+  try {
+    artifact = JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch (error) {
+    throw new Error(`failed to read process summary file ${filePath}: ${error.message}`);
+  }
+  if (artifact?.contract === BUILDCHAIN_PROCESS_SAMPLE_REPORT_CONTRACT && artifact.summary) {
+    return {
+      artifact,
+      summary: artifact.summary,
+      samplesPath: artifact.samplesPath || "",
+    };
+  }
+  if (artifact?.contract === BUILDCHAIN_PROCESS_SAMPLE_SUMMARY_CONTRACT) {
+    return {
+      artifact,
+      summary: artifact,
+      samplesPath: "",
+    };
+  }
+  throw new Error(`process summary file has unsupported contract: ${artifact?.contract || "unknown"}`);
+}
+
+function shellCommandArgs(command, shell) {
+  if (typeof shell === "string" && shell.trim()) {
+    return [shell, "-c", command];
+  }
+  if (process.platform === "win32") {
+    return [process.env.ComSpec || "cmd.exe", "/d", "/s", "/c", command];
+  }
+  return [process.env.SHELL || "/bin/sh", "-c", command];
+}
+
+function samplerPathForCwd(filePath, cwd) {
+  const relative = path.relative(cwd, filePath);
+  return relative && !relative.startsWith("..") && !path.isAbsolute(relative)
+    ? toPosix(relative)
+    : filePath;
+}
+
+function executeSampledShellCommand({
+  command,
+  cwd,
+  env,
+  shell,
+  timeout,
+  label,
+  processSummaryPath,
+  processSamplesPath,
+  processSampleIntervalMs,
+  requestedParallelism,
+}) {
+  fs.mkdirSync(path.dirname(processSummaryPath), { recursive: true });
+  fs.mkdirSync(path.dirname(processSamplesPath), { recursive: true });
+  const args = [
+    resolveBuildchainCliPath(),
+    "sample",
+    "process-tree",
+    "--label",
+    label || "lifecycle",
+    "--interval-ms",
+    String(processSampleIntervalMs || 15000),
+    "--output",
+    samplerPathForCwd(processSamplesPath, cwd),
+    "--summary-output",
+    samplerPathForCwd(processSummaryPath, cwd),
+  ];
+  if (Number(requestedParallelism || 0) > 0) {
+    args.push("--requested-parallelism", String(Number(requestedParallelism)));
+  }
+  args.push("--", ...shellCommandArgs(command, shell));
+  execFileSync(process.execPath, args, {
+    cwd,
+    env,
+    stdio: "inherit",
+    timeout,
+  });
+}
+
+function stageCommandText(stage) {
+  if (stage.mode === "script") {
+    return stage.script;
+  }
+  if (process.platform === "win32") {
+    return stage.commands.join(" && ");
+  }
+  return ["set -e", ...stage.commands].join("\n");
+}
+
+function runLifecycleStageWithSampler({
+  cwd,
+  loadedConfig,
+  name,
+  env,
+  sampleProcessTree,
+  processSummaryPath,
+  processSamplesPath,
+  processSampleIntervalMs,
+  requestedParallelism,
+}) {
+  if (!sampleProcessTree) {
+    return runLifecycleStage({ cwd, loadedConfig, name, env });
+  }
+  const lifecycle = loadedConfig?.config?.lifecycle || {};
+  const stage = lifecycle[name];
+  if (!stage) {
+    return false;
+  }
+  const stageEnv = {
+    ...process.env,
+    ...(lifecycle.env || {}),
+    ...(stage.env || {}),
+    ...(env || {}),
+  };
+  const timeout = stage.timeoutMinutes ? stage.timeoutMinutes * 60_000 : undefined;
+  let lastError;
+  for (let attempt = 1; attempt <= stage.retries; attempt += 1) {
+    try {
+      executeSampledShellCommand({
+        command: stageCommandText(stage),
+        cwd,
+        env: stageEnv,
+        shell: stage.shell || true,
+        timeout,
+        label: `lifecycle-${name}`,
+        processSummaryPath,
+        processSamplesPath,
+        processSampleIntervalMs,
+        requestedParallelism,
+      });
+      return true;
+    } catch (error) {
+      lastError = error;
+      if (attempt < stage.retries) {
+        console.log(`> lifecycle ${name || "stage"} failed, retry ${attempt + 1}/${stage.retries}`);
+      }
+    }
+  }
+  throw lastError;
+}
+
+function writeJsonlEvents(filePath, events = []) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, events.map((event) => JSON.stringify(event)).join("\n") + (events.length ? "\n" : ""));
+}
+
+function copyIfExists(sourcePath, targetPath) {
+  if (!sourcePath || !fs.existsSync(sourcePath)) {
+    return false;
+  }
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.copyFileSync(sourcePath, targetPath);
+  return true;
+}
+
+function resolveLinkedFilePath({ linkedPath = "", workspace, cwd, fallbackDir }) {
+  if (!linkedPath) {
+    return "";
+  }
+  const candidates = path.isAbsolute(linkedPath)
+    ? [linkedPath]
+    : [
+        path.resolve(workspace, linkedPath),
+        path.resolve(cwd, linkedPath),
+        path.resolve(fallbackDir, linkedPath),
+      ];
+  return candidates.find((candidate) => fs.existsSync(candidate)) || candidates[0] || "";
+}
+
+function diagnosticsSidecarEntry({ kind, filePath, workspace, required = false }) {
+  if (!filePath || !fs.existsSync(filePath)) {
+    return null;
+  }
+  const stat = fs.statSync(filePath);
+  if (!stat.isFile()) {
+    return null;
+  }
+  return {
+    kind,
+    path: toPosix(path.relative(workspace, filePath)),
+    bytes: stat.size,
+    sha256: sha256File(filePath),
+    required: Boolean(required),
+  };
+}
+
+function writeDiagnosticsSidecarManifest(filePath, {
+  workspace,
+  artifactName,
+  platformId,
+  diagnosticsArtifactName = "",
+  files = [],
+}) {
+  const entries = files
+    .map((entry) => diagnosticsSidecarEntry({ ...entry, workspace }))
+    .filter(Boolean);
+  const manifest = {
+    schemaVersion: 1,
+    contract: BUILDCHAIN_DIAGNOSTICS_MANIFEST_CONTRACT,
+    generatedAt: new Date().toISOString(),
+    artifactName,
+    platformId,
+    ...(diagnosticsArtifactName ? { diagnosticsArtifactName } : {}),
+    fileCount: entries.length,
+    totalBytes: entries.reduce((sum, entry) => sum + entry.bytes, 0),
+    files: entries,
+  };
+  fs.writeFileSync(filePath, `${JSON.stringify(manifest, null, 2)}\n`);
+  return manifest;
+}
+
 export function runLifecycle({
   cwd = process.cwd(),
   stageName = "",
@@ -78,20 +317,52 @@ export function runLifecycle({
   required = false,
   manifestPath = ".buildchain/artifacts/manifest.json",
   summaryPath = ".buildchain/artifacts/summary.json",
+  diagnosticsPath = "",
   artifactName = "buildchain-artifact",
+  manifestArtifactName = "",
+  diagnosticsArtifactName = "",
   platformId = os.platform(),
   platformName = platformId,
   artifactPaths = [],
   expectedArtifactsJson = "",
   workspace = process.cwd(),
   logPath = process.env.BUILDCHAIN_LOG_PATH || ".buildchain/logs/events.jsonl",
+  processSummaryPath = "",
+  processSamplesPath = ".buildchain/diagnostics/process-samples.jsonl",
+  sampleProcessTree = false,
+  processSampleIntervalMs = 15000,
+  requestedParallelism = 0,
+  processSummaryRequired = true,
 } = {}) {
   const resolvedCwd = path.resolve(cwd);
   const resolvedWorkspace = path.resolve(workspace);
   const resolvedManifestPath = path.resolve(resolvedWorkspace, manifestPath);
   const resolvedSummaryPath = path.resolve(resolvedWorkspace, summaryPath);
+  const resolvedDiagnosticsPath = path.resolve(
+    resolvedWorkspace,
+    diagnosticsPath || path.join(path.dirname(manifestPath), "diagnostics.json"),
+  );
   const resolvedLogPath = logPath ? path.resolve(resolvedWorkspace, logPath) : "";
+  const resolvedProcessSummaryPath = processSummaryPath || sampleProcessTree
+    ? path.resolve(resolvedWorkspace, processSummaryPath || ".buildchain/diagnostics/process-summary.json")
+    : "";
+  const resolvedProcessSamplesPath = processSamplesPath
+    ? path.resolve(resolvedWorkspace, processSamplesPath)
+    : path.resolve(resolvedWorkspace, ".buildchain/diagnostics/process-samples.jsonl");
   const relativeLogPath = resolvedLogPath ? toPosix(path.relative(resolvedWorkspace, resolvedLogPath)) : "";
+  const relativeProcessSummaryPath = resolvedProcessSummaryPath
+    ? toPosix(path.relative(resolvedWorkspace, resolvedProcessSummaryPath))
+    : "";
+  const relativeDiagnosticsPath = toPosix(path.relative(resolvedWorkspace, resolvedDiagnosticsPath));
+  const diagnosticsDir = path.dirname(resolvedDiagnosticsPath);
+  const resolvedDiagnosticsEventsPath = path.join(diagnosticsDir, "events.jsonl");
+  const resolvedDiagnosticsProcessSummaryPath = path.join(diagnosticsDir, "process-summary.json");
+  const resolvedDiagnosticsProcessSamplesPath = path.join(diagnosticsDir, "process-samples.jsonl");
+  const resolvedDiagnosticsManifestPath = path.join(diagnosticsDir, "diagnostics-manifest.json");
+  const relativeDiagnosticsEventsPath = toPosix(path.relative(resolvedWorkspace, resolvedDiagnosticsEventsPath));
+  const relativeDiagnosticsProcessSummaryPath = toPosix(path.relative(resolvedWorkspace, resolvedDiagnosticsProcessSummaryPath));
+  const relativeDiagnosticsProcessSamplesPath = toPosix(path.relative(resolvedWorkspace, resolvedDiagnosticsProcessSamplesPath));
+  const relativeDiagnosticsManifestPath = toPosix(path.relative(resolvedWorkspace, resolvedDiagnosticsManifestPath));
   const logRunId = crypto.randomUUID();
   const frameworkLog = createBuildchainLogger({
     cwd: resolvedWorkspace,
@@ -130,23 +401,39 @@ export function runLifecycle({
       attributes: {
         commandSource,
         stage: stageName || "command",
+        sampleProcessTree,
       },
     });
     try {
-      execSync(command, {
-        cwd: resolvedCwd,
-        env: {
-          ...process.env,
-          ...(resolvedLogPath
-            ? {
-                BUILDCHAIN_LOG_PATH: resolvedLogPath,
-                BUILDCHAIN_LOG_RUN_ID: logRunId,
-              }
-            : {}),
-        },
-        shell: true,
-        stdio: "inherit",
-      });
+      const commandEnv = {
+        ...process.env,
+        ...(resolvedLogPath
+          ? {
+              BUILDCHAIN_LOG_PATH: resolvedLogPath,
+              BUILDCHAIN_LOG_RUN_ID: logRunId,
+            }
+          : {}),
+      };
+      if (sampleProcessTree) {
+        executeSampledShellCommand({
+          command,
+          cwd: resolvedCwd,
+          env: commandEnv,
+          shell: true,
+          label: `lifecycle-${stageName || "command"}`,
+          processSummaryPath: resolvedProcessSummaryPath,
+          processSamplesPath: resolvedProcessSamplesPath,
+          processSampleIntervalMs,
+          requestedParallelism,
+        });
+      } else {
+        execSync(command, {
+          cwd: resolvedCwd,
+          env: commandEnv,
+          shell: true,
+          stdio: "inherit",
+        });
+      }
       executed = true;
       userLog.info("lifecycle.command.end", {
         durationMs: Date.now() - startedAt,
@@ -162,6 +449,7 @@ export function runLifecycle({
         attributes: lifecycleErrorAttributes(error, {
           commandSource,
           stage: stageName || "command",
+          sampleProcessTree,
         }),
       });
       throw error;
@@ -173,10 +461,11 @@ export function runLifecycle({
       attributes: {
         commandSource,
         stage: stageName,
+        sampleProcessTree,
       },
     });
     try {
-      executed = runLifecycleStage({
+      executed = runLifecycleStageWithSampler({
         cwd: resolvedCwd,
         loadedConfig,
         name: stageName,
@@ -186,6 +475,11 @@ export function runLifecycle({
               BUILDCHAIN_LOG_RUN_ID: logRunId,
             }
           : {},
+        sampleProcessTree,
+        processSummaryPath: resolvedProcessSummaryPath,
+        processSamplesPath: resolvedProcessSamplesPath,
+        processSampleIntervalMs,
+        requestedParallelism,
       });
       userLog.info("lifecycle.stage.end", {
         durationMs: Date.now() - startedAt,
@@ -202,6 +496,7 @@ export function runLifecycle({
         attributes: lifecycleErrorAttributes(error, {
           commandSource,
           stage: stageName,
+          sampleProcessTree,
         }),
       });
       throw error;
@@ -218,6 +513,13 @@ export function runLifecycle({
     throw new Error(`required lifecycle stage did not run: ${stageName || "command"}`);
   }
 
+  const shouldReadProcessSummary = Boolean(
+    resolvedProcessSummaryPath
+      && (fs.existsSync(resolvedProcessSummaryPath) || processSummaryRequired),
+  );
+  const processSummaryArtifact = shouldReadProcessSummary
+    ? readProcessSummaryArtifact(resolvedProcessSummaryPath)
+    : undefined;
   fs.mkdirSync(path.dirname(resolvedManifestPath), { recursive: true });
   const scanStartedAt = Date.now();
   const files = collectArtifactFiles(resolvedWorkspace, artifactPaths);
@@ -229,8 +531,9 @@ export function runLifecycle({
       sha256: sha256File(file),
     };
   });
+  const artifactScanDurationMs = Date.now() - scanStartedAt;
   frameworkLog.info("artifact.scan", {
-    durationMs: Date.now() - scanStartedAt,
+    durationMs: artifactScanDurationMs,
     attributes: {
       fileCount: manifestFiles.length,
     },
@@ -279,6 +582,26 @@ export function runLifecycle({
         : summarizeBuildchainLogEvents([...frameworkLog.events, ...userLog.events]),
     },
   };
+  const lifecycleObservability = summarizeLifecycleObservability({
+    events: resolvedLogPath ? readBuildchainLogEvents(resolvedLogPath) : [...frameworkLog.events, ...userLog.events],
+    logPath: relativeLogPath,
+    artifactScanDurationMs,
+    totalBytes: summary.totalBytes,
+    fileCount: summary.fileCount,
+  });
+  observability.lifecycle = lifecycleObservability;
+  observability.diagnostics = {
+    contract: BUILDCHAIN_DIAGNOSTICS_CONTRACT,
+    path: relativeDiagnosticsPath,
+    manifestPath: relativeDiagnosticsManifestPath,
+    eventsPath: relativeDiagnosticsEventsPath,
+  };
+  if (relativeProcessSummaryPath) {
+    observability.process = {
+      contract: BUILDCHAIN_PROCESS_SAMPLE_SUMMARY_CONTRACT,
+      path: relativeProcessSummaryPath,
+    };
+  }
   const summaryWithObservability = {
     ...summary,
     observability,
@@ -309,6 +632,57 @@ export function runLifecycle({
   fs.writeFileSync(resolvedManifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
   fs.mkdirSync(path.dirname(resolvedSummaryPath), { recursive: true });
   fs.writeFileSync(resolvedSummaryPath, `${JSON.stringify(summaryWithObservability, null, 2)}\n`);
+  writeDiagnosticsArtifact(
+    resolvedDiagnosticsPath,
+    createDiagnosticsArtifact({
+      cwd: resolvedCwd,
+      logPath: resolvedLogPath,
+      artifactPaths,
+      lifecycleObservability,
+      processSummary: processSummaryArtifact?.summary,
+      links: {
+        artifactName,
+        platformId,
+        ...(manifestArtifactName ? { manifestArtifactName } : {}),
+        ...(diagnosticsArtifactName ? { diagnosticsArtifactName } : {}),
+        manifest: toPosix(path.relative(resolvedWorkspace, resolvedManifestPath)),
+        summary: toPosix(path.relative(resolvedWorkspace, resolvedSummaryPath)),
+        log: relativeLogPath,
+        diagnosticsManifest: relativeDiagnosticsManifestPath,
+        diagnosticsEvents: relativeDiagnosticsEventsPath,
+        ...(relativeProcessSummaryPath ? { processSummary: relativeProcessSummaryPath } : {}),
+        ...(processSummaryArtifact ? { diagnosticsProcessSummary: relativeDiagnosticsProcessSummaryPath } : {}),
+        ...(processSummaryArtifact?.samplesPath ? { diagnosticsProcessSamples: relativeDiagnosticsProcessSamplesPath } : {}),
+      },
+    }),
+  );
+  if (resolvedLogPath && fs.existsSync(resolvedLogPath)) {
+    copyIfExists(resolvedLogPath, resolvedDiagnosticsEventsPath);
+  } else {
+    writeJsonlEvents(resolvedDiagnosticsEventsPath, [...frameworkLog.events, ...userLog.events]);
+  }
+  if (processSummaryArtifact) {
+    copyIfExists(resolvedProcessSummaryPath, resolvedDiagnosticsProcessSummaryPath);
+    const resolvedSamplesPath = resolveLinkedFilePath({
+      linkedPath: processSummaryArtifact.samplesPath,
+      workspace: resolvedWorkspace,
+      cwd: resolvedCwd,
+      fallbackDir: path.dirname(resolvedProcessSummaryPath),
+    });
+    copyIfExists(resolvedSamplesPath, resolvedDiagnosticsProcessSamplesPath);
+  }
+  writeDiagnosticsSidecarManifest(resolvedDiagnosticsManifestPath, {
+    workspace: resolvedWorkspace,
+    artifactName,
+    platformId,
+    diagnosticsArtifactName,
+    files: [
+      { kind: "diagnostics", filePath: resolvedDiagnosticsPath, required: true },
+      { kind: "events", filePath: resolvedDiagnosticsEventsPath, required: true },
+      { kind: "process-summary", filePath: resolvedDiagnosticsProcessSummaryPath },
+      { kind: "process-samples", filePath: resolvedDiagnosticsProcessSamplesPath },
+    ],
+  });
   console.log(`buildchain_manifest=${path.relative(resolvedWorkspace, resolvedManifestPath)}`);
   return manifest;
 }

package/scripts/run-lifecycle.mjs

@@ -18,6 +18,14 @@ function parseList(value) {
     .filter(Boolean);
 }
 
+function readBooleanArg(name, fallback = "false") {
+  return readArg(name, fallback) === "true";
+}
+
+function readNumberArg(name, fallback) {
+  return Number(readArg(name, String(fallback)) || fallback);
+}
+
 export function runLifecycleCli() {
   return runLifecycle({
     cwd: readArg("cwd", process.cwd()),
@@ -27,10 +35,18 @@ export function runLifecycleCli() {
     manifestPath: readArg("manifest-path", ".buildchain/artifacts/manifest.json"),
     summaryPath: readArg("summary-path", ".buildchain/artifacts/summary.json"),
     artifactName: readArg("artifact-name", "buildchain-artifact"),
+    manifestArtifactName: readArg("manifest-artifact-name", ""),
+    diagnosticsArtifactName: readArg("diagnostics-artifact-name", ""),
     platformId: readArg("platform-id", os.platform()),
     platformName: readArg("platform-name", readArg("platform-id", os.platform())),
     artifactPaths: parseList(process.env.BUILDCHAIN_ARTIFACT_PATHS || ""),
     expectedArtifactsJson: process.env.BUILDCHAIN_EXPECTED_ARTIFACTS_JSON || "",
+    processSummaryPath: readArg("process-summary", process.env.BUILDCHAIN_PROCESS_SUMMARY_PATH || ""),
+    processSamplesPath: readArg("process-samples", process.env.BUILDCHAIN_PROCESS_SAMPLES_PATH || ".buildchain/diagnostics/process-samples.jsonl"),
+    sampleProcessTree: readBooleanArg("sample-process-tree", process.env.BUILDCHAIN_SAMPLE_PROCESS_TREE || "false"),
+    processSampleIntervalMs: readNumberArg("process-sample-interval-ms", process.env.BUILDCHAIN_PROCESS_SAMPLE_INTERVAL_MS || 15000),
+    requestedParallelism: readNumberArg("requested-parallelism", process.env.BUILDCHAIN_REQUESTED_PARALLELISM || 0),
+    processSummaryRequired: readBooleanArg("process-summary-required", process.env.BUILDCHAIN_PROCESS_SUMMARY_REQUIRED || "true"),
     workspace: process.cwd(),
   });
 }

package/scripts/runtime-ref-core.mjs

@@ -0,0 +1,109 @@
+const EXACT_SHA_RE = /^[0-9a-f]{40}$/i;
+const TRAIN_REF_RE = /^train\/v\d+\/v\d+\.\d+\/[A-Za-z0-9._/-]+$/;
+
+export function parseWorkflowShellRef(workflowRef = "", fallback = "v2", buildchainRepository = "kungfu-systems/buildchain") {
+  const value = String(workflowRef || "");
+  const expectedPrefix = `${buildchainRepository}/.github/workflows/`;
+  if (!value.startsWith(expectedPrefix)) {
+    return fallback;
+  }
+  const ref = value.split("@").pop()?.trim();
+  return ref || fallback;
+}
+
+export function classifyBuildchainRuntimeRef(ref = "") {
+  const value = String(ref || "").trim().replace(/^refs\/heads\//, "").replace(/^refs\/tags\//, "");
+  if (EXACT_SHA_RE.test(value)) {
+    return "exact-sha";
+  }
+  if (TRAIN_REF_RE.test(value)) {
+    return "train";
+  }
+  if (/^v\d+(?:\.\d+)?$/.test(value) || /^v\d+\.\d+\.\d+$/.test(value)) {
+    return "stable";
+  }
+  if (/^v\d+(?:\.\d+)?-alpha$/.test(value) || /^v\d+\.\d+\.\d+-alpha\.\d+$/.test(value)) {
+    return "alpha";
+  }
+  return "development";
+}
+
+export function normalizeRequestedRuntimeRef(requestedRef = "") {
+  const requested = String(requestedRef || "").trim();
+  if (!requested) {
+    return { ref: "", fullRef: "", class: "", exactSha: false };
+  }
+  if (EXACT_SHA_RE.test(requested)) {
+    return { ref: requested, fullRef: requested, class: "exact-sha", exactSha: true };
+  }
+  const trainRef = requested.replace(/^refs\/heads\//, "");
+  if (!TRAIN_REF_RE.test(trainRef)) {
+    throw new Error(
+      "buildchain-ref override must be train/vN/vN.M/<capability>, refs/heads/train/vN/vN.M/<capability>, or an exact 40-character SHA",
+    );
+  }
+  return {
+    ref: trainRef,
+    fullRef: `refs/heads/${trainRef}`,
+    class: "train",
+    exactSha: false,
+  };
+}
+
+export function resolveRuntimeSelection({
+  requestedRef = "",
+  workflowRef = "",
+  defaultStableRef = "v2",
+  buildchainRepository = "kungfu-systems/buildchain",
+} = {}) {
+  const requested = String(requestedRef || "").trim();
+  const workflowShellRef = parseWorkflowShellRef(workflowRef, defaultStableRef, buildchainRepository);
+  if (!requested) {
+    return {
+      requestedRef: "",
+      runtimeRef: workflowShellRef || defaultStableRef,
+      runtimeFullRef: workflowShellRef || defaultStableRef,
+      runtimeClass: classifyBuildchainRuntimeRef(workflowShellRef || defaultStableRef),
+      runtimeOverride: false,
+      workflowShellRef: workflowShellRef || defaultStableRef,
+      rollbackRef: workflowShellRef || defaultStableRef,
+      trustDecision: "stable-default",
+    };
+  }
+  const normalized = normalizeRequestedRuntimeRef(requested);
+  return {
+    requestedRef: requested,
+    runtimeRef: normalized.ref,
+    runtimeFullRef: normalized.fullRef,
+    runtimeClass: normalized.class,
+    runtimeOverride: true,
+    workflowShellRef: workflowShellRef || defaultStableRef,
+    rollbackRef: workflowShellRef || defaultStableRef,
+    trustDecision: "override-requested",
+  };
+}
+
+export function validateRuntimeOverrideTrust({
+  requestedRef = "",
+  eventName = "",
+  actorPermission = "",
+} = {}) {
+  if (!String(requestedRef || "").trim()) {
+    return { ok: true, decision: "stable-default" };
+  }
+  if (eventName !== "workflow_dispatch") {
+    return {
+      ok: false,
+      decision: "rejected-untrusted-event",
+      reason: "buildchain-ref override is only allowed for trusted workflow_dispatch runs",
+    };
+  }
+  if (!new Set(["admin", "maintain", "write"]).has(String(actorPermission || ""))) {
+    return {
+      ok: false,
+      decision: "rejected-insufficient-permission",
+      reason: "buildchain-ref override requires actor write, maintain, or admin permission",
+    };
+  }
+  return { ok: true, decision: "override-accepted" };
+}

package/scripts/web-surface-core.mjs

@@ -584,6 +584,10 @@ export function planWebSurfaceDeploy({
   sourceSha = "",
   artifactHash = "",
   artifactPath = "",
+  runtimeId = "",
+  configFingerprint = "",
+  rollbackPointer = "",
+  rollbackLimitations = "",
   dryRun = true,
   deployedAt = new Date().toISOString(),
 } = {}) {
@@ -608,6 +612,10 @@ export function planWebSurfaceDeploy({
     alias,
     sourceSha,
     artifactHash: resolvedArtifact.artifactHash,
+    runtimeId,
+    configFingerprint,
+    rollbackPointer,
+    rollbackLimitations,
     deployedAt,
   });
   return {

package/scripts/web-surface.mjs

@@ -82,6 +82,10 @@ export function webSurfaceCli() {
       sourceSha,
       artifactHash: readArg("artifact-hash", process.env.BUILDCHAIN_WEB_SURFACE_ARTIFACT_HASH || ""),
       artifactPath: readArg("artifact-path", process.env.BUILDCHAIN_WEB_SURFACE_ARTIFACT_PATH || ""),
+      runtimeId: readArg("runtime-id", process.env.BUILDCHAIN_RUNTIME_ID || ""),
+      configFingerprint: readArg("config-fingerprint", process.env.BUILDCHAIN_CONFIG_FINGERPRINT || ""),
+      rollbackPointer: readArg("rollback-pointer", process.env.BUILDCHAIN_ROLLBACK_REF || ""),
+      rollbackLimitations: readArg("rollback-limitations", process.env.BUILDCHAIN_ROLLBACK_LIMITATIONS || ""),
       dryRun: readBooleanArg("dry-run", true),
     });
     const outputResult = mode === "manifest" ? result.manifest : result;