@kungfu-tech/buildchain 3.0.6-alpha.0 → 3.0.6-alpha.2

package/scripts/lifecycle-substage-evidence.mjs

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT_PATTERN = /^sha256:[0-9a-f]{64}$/u;
+const SHA_PATTERN = /^[0-9a-f]{40}$/u;
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, item]) => [key, canonical(item)]),
+    );
+  }
+  return value;
+}
+
+function digest(value) {
+  return `sha256:${crypto
+    .createHash("sha256")
+    .update(JSON.stringify(canonical(value)))
+    .digest("hex")}`;
+}
+
+function withoutRoot(value, field = "evidenceRoot") {
+  const body = structuredClone(value);
+  Reflect.deleteProperty(body, field);
+  return body;
+}
+
+function requireIso(value, label) {
+  if (typeof value !== "string" || !Number.isFinite(Date.parse(value))) {
+    throw new Error(`${label} must be an ISO timestamp`);
+  }
+}
+
+function verifyEvidenceHeader(
+  evidence,
+  { lifecycleStage, sourceSha, sourceTree, platformId },
+) {
+  if (evidence?.schema !== "kungfu.lifecycle-substage-evidence/v1") {
+    throw new Error(
+      `unsupported lifecycle substage evidence schema: ${evidence?.schema || "missing"}`,
+    );
+  }
+  if (!ROOT_PATTERN.test(evidence.evidenceRoot || "")) {
+    throw new Error("lifecycle substage evidence root is invalid");
+  }
+  if (evidence.evidenceRoot !== digest(withoutRoot(evidence))) {
+    throw new Error("lifecycle substage evidence root mismatch");
+  }
+  if (lifecycleStage && evidence.lifecycleStage !== lifecycleStage) {
+    throw new Error(
+      `lifecycle stage mismatch: expected ${lifecycleStage}, got ${evidence.lifecycleStage}`,
+    );
+  }
+  if (
+    !SHA_PATTERN.test(evidence.source?.sha || "") ||
+    !SHA_PATTERN.test(evidence.source?.tree || "")
+  ) {
+    throw new Error("lifecycle substage source identity is invalid");
+  }
+  if (sourceSha && evidence.source.sha !== sourceSha) {
+    throw new Error(
+      `lifecycle substage source SHA mismatch: expected ${sourceSha}, got ${evidence.source.sha}`,
+    );
+  }
+  if (sourceTree && evidence.source.tree !== sourceTree) {
+    throw new Error(
+      `lifecycle substage source tree mismatch: expected ${sourceTree}, got ${evidence.source.tree}`,
+    );
+  }
+  if (platformId && evidence.platform?.id !== platformId) {
+    throw new Error(
+      `lifecycle substage platform mismatch: expected ${platformId}, got ${evidence.platform?.id}`,
+    );
+  }
+  if (!["passed", "failed"].includes(evidence.conclusion)) {
+    throw new Error("lifecycle substage conclusion must be passed or failed");
+  }
+  requireIso(evidence.startedAt, "lifecycle substage startedAt");
+  requireIso(evidence.completedAt, "lifecycle substage completedAt");
+  if (!Array.isArray(evidence.substages) || evidence.substages.length === 0) {
+    throw new Error("lifecycle substage evidence has no substages");
+  }
+}
+
+function verifySubstage(substage, index, names) {
+  if (typeof substage.stage !== "string" || !substage.stage) {
+    throw new Error(`substage ${index} has no name`);
+  }
+  if (names.has(substage.stage)) {
+    throw new Error(`duplicate lifecycle substage: ${substage.stage}`);
+  }
+  names.add(substage.stage);
+  requireIso(substage.startedAt, `${substage.stage}.startedAt`);
+  requireIso(substage.completedAt, `${substage.stage}.completedAt`);
+  if (
+    !Number.isFinite(substage.durationSeconds) ||
+    substage.durationSeconds < 0
+  ) {
+    throw new Error(`${substage.stage}.durationSeconds is invalid`);
+  }
+  if (
+    !Number.isInteger(substage.status) ||
+    !["passed", "failed"].includes(substage.conclusion)
+  ) {
+    throw new Error(`${substage.stage} result is invalid`);
+  }
+  if ((substage.status === 0) !== (substage.conclusion === "passed")) {
+    throw new Error(`${substage.stage} status and conclusion disagree`);
+  }
+  if (
+    !["platform-native", "exact-source-reuse"].includes(substage.executionMode)
+  ) {
+    throw new Error(`${substage.stage}.executionMode is invalid`);
+  }
+  if (
+    !ROOT_PATTERN.test(substage.evidenceRoot || "") ||
+    substage.evidenceRoot !== digest(withoutRoot(substage))
+  ) {
+    throw new Error(`${substage.stage} evidence root mismatch`);
+  }
+}
+
+function verifyAggregate(evidence) {
+  const failed = evidence.substages.some((substage) => substage.status !== 0);
+  const expectedFailureReason = failed
+    ? "substage-failed"
+    : evidence.conclusion === "failed"
+      ? "budget-exceeded"
+      : undefined;
+  if (
+    (failed && evidence.conclusion !== "failed") ||
+    (!failed && evidence.conclusion === "passed" && evidence.failureReason) ||
+    evidence.failureReason !== expectedFailureReason
+  ) {
+    throw new Error("lifecycle substage aggregate conclusion is inconsistent");
+  }
+}
+
+export function verifyLifecycleSubstageEvidence(
+  value,
+  {
+    lifecycleStage = "",
+    sourceSha = "",
+    sourceTree = "",
+    platformId = "",
+  } = {},
+) {
+  const evidence = value?.substageEvidence || value;
+  verifyEvidenceHeader(evidence, {
+    lifecycleStage,
+    sourceSha,
+    sourceTree,
+    platformId,
+  });
+  const names = new Set();
+  for (const [index, substage] of evidence.substages.entries()) {
+    verifySubstage(substage, index, names);
+  }
+  verifyAggregate(evidence);
+  return structuredClone(evidence);
+}
+
+export function lifecycleSubstageEvidenceContext({
+  substageEvidencePath = "",
+  cwd,
+  workspace,
+  diagnosticsDir,
+  lifecycleStage,
+  sourceSha = process.env.BUILDCHAIN_SOURCE_SHA || "",
+  sourceTree = process.env.BUILDCHAIN_SOURCE_TREE_SHA || "",
+  platformId,
+}) {
+  if (!substageEvidencePath) {
+    return {
+      evidence: undefined,
+      observability: {},
+      lifecycle: {},
+      links: {},
+      sourcePath: "",
+      targetPath: "",
+      sidecar: {},
+    };
+  }
+  const sourcePath = path.resolve(cwd, substageEvidencePath);
+  const targetPath = path.join(diagnosticsDir, "verify-substages.json");
+  const relativePath = path
+    .relative(workspace, targetPath)
+    .split(path.sep)
+    .join("/");
+  const evidence = readLifecycleSubstageEvidence(sourcePath, {
+    lifecycleStage,
+    sourceSha,
+    sourceTree,
+    platformId,
+  });
+  return {
+    evidence,
+    observability: {
+      substages: {
+        contract: evidence.schema,
+        evidenceRoot: evidence.evidenceRoot,
+        conclusion: evidence.conclusion,
+        path: relativePath,
+      },
+    },
+    lifecycle: { substageEvidence: evidence },
+    links: { lifecycleSubstages: relativePath },
+    sourcePath,
+    targetPath,
+    sidecar: {
+      kind: "lifecycle-substages",
+      filePath: targetPath,
+      required: true,
+    },
+  };
+}
+
+export function readLifecycleSubstageEvidence(file, options = {}) {
+  if (!file) return undefined;
+  const absolute = path.resolve(file);
+  if (!fs.existsSync(absolute))
+    throw new Error(`lifecycle substage evidence file not found: ${file}`);
+  return verifyLifecycleSubstageEvidence(
+    JSON.parse(fs.readFileSync(absolute, "utf8")),
+    options,
+  );
+}
+
+function parse(argv) {
+  const options = {};
+  for (let index = 0; index < argv.length; index += 2) {
+    const flag = argv[index];
+    if (!flag?.startsWith("--") || index + 1 >= argv.length)
+      throw new Error(`invalid option: ${flag || "missing"}`);
+    options[flag.slice(2)] = argv[index + 1];
+  }
+  return options;
+}
+
+function main(argv = process.argv.slice(2)) {
+  const options = parse(argv);
+  const evidence = readLifecycleSubstageEvidence(options.file, {
+    lifecycleStage: options.stage || "",
+    sourceSha: options["source-sha"] || "",
+    sourceTree: options["source-tree"] || "",
+    platformId: options["platform-id"] || "",
+  });
+  process.stdout.write(
+    `${JSON.stringify({ ok: true, evidenceRoot: evidence.evidenceRoot, conclusion: evidence.conclusion })}\n`,
+  );
+}
+
+if (
+  process.argv[1] &&
+  path.basename(process.argv[1]) === "lifecycle-substage-evidence.mjs" &&
+  fileURLToPath(import.meta.url) === path.resolve(process.argv[1])
+) {
+  try {
+    main();
+  } catch (error) {
+    console.error(
+      `[lifecycle-substages] ${error instanceof Error ? error.message : String(error)}`,
+    );
+    process.exit(1);
+  }
+}

package/scripts/locked-source-checkout.mjs

@@ -4,6 +4,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { runGitFetchSync } from "./git-fetch-process-tree.mjs";
 
 export const LOCKED_SOURCE_CHECKOUT_CONTRACT = "kungfu-buildchain-locked-source-checkout-cache";
 export const ISOLATED_GIT_GLOBAL_CONFIG = process.platform === "win32" ? "NUL" : "/dev/null";
@@ -111,9 +112,10 @@ function ensureCheckoutTarget(targetPath, workspace) {
 
 function git(args, { cwd, env = {}, timeoutMs = 60000, stdio = ["ignore", "pipe", "pipe"] } = {}) {
   try {
-    const output = execFileSync("git", args, {
+    const commandEnv = { ...process.env, ...env };
+    const output = args[0] === "fetch" ? runGitFetchSync({ args, cwd, env: commandEnv, timeoutMs, stdio }) : execFileSync("git", args, {
       cwd,
-      env: { ...process.env, ...env },
+      env: commandEnv,
       encoding: "utf8",
       stdio,
       timeout: timeoutMs,
@@ -233,7 +235,8 @@ function checkoutFetchedCommit(targetPath, sha, timeoutMs) {
 function retryableGitFetchError(error) {
   const code = String(error?.code || "").toUpperCase();
   if (["ETIMEDOUT", "ECONNRESET", "ECONNREFUSED", "EAI_AGAIN", "ENETUNREACH", "EPIPE"].includes(code)) return true;
-  return /timed?\s*out|timeout|connection (?:reset|refused)|remote end hung up|early eof|rpc failed|http (?:429|5\d\d)|temporary failure|network is unreachable/i.test(String(error?.message || error || ""));
+  const commandOutput = [error?.stderr, error?.stdout].filter(Boolean).map(String).join("\n").trim();
+  return /timed?\s*out|timeout|connection (?:reset|refused)|remote end hung up|early eof|rpc failed|http (?:429|5\d\d)|temporary failure|network is unreachable/i.test(commandOutput || String(error?.message || error || ""));
 }
 
 export function fetchSourceCommit({

package/scripts/resolve-artifact-transfer-mode.mjs

@@ -26,6 +26,15 @@ function resolveArtifactTransferMode(env = process.env) {
       oidcAudience: "",
     };
   }
+  if (env.INPUT_RELAY_REQUIRED === "false") {
+    return {
+      mode: "github-artifacts",
+      s3Bucket: "",
+      s3Region: "",
+      s3Prefix: "",
+      oidcAudience: "",
+    };
+  }
   const s3Bucket = firstValue(env.INPUT_S3_BUCKET, env.VAR_S3_BUCKET);
   const s3Region = firstValue(env.INPUT_S3_REGION, env.VAR_S3_REGION);
   const s3Prefix = firstValue(

package/scripts/resolve-build-contract.mjs

@@ -41,6 +41,13 @@ export function resolveBuildContractCli() {
       "native-platform-count": String(resolved.nativePlatformCount),
       "container-platforms-json": resolved.containerPlatformsJson,
       "container-platform-count": String(resolved.containerPlatformCount),
+      "github-hosted-platforms-json": resolved.githubHostedPlatformsJson,
+      "github-hosted-platform-ids-json": resolved.githubHostedPlatformIdsJson,
+      "github-hosted-platform-count": String(
+        resolved.githubHostedPlatformCount,
+      ),
+      "relay-platforms-json": resolved.relayPlatformsJson,
+      "relay-platform-count": String(resolved.relayPlatformCount),
       "linux-container-enabled": String(resolved.linuxContainer.enabled),
       "linux-container-preset": resolved.linuxContainer.preset,
       "linux-container-image": resolved.linuxContainer.image,

package/scripts/route-offline-runners.mjs

@@ -71,6 +71,7 @@ export function routeOfflineRunners({
     return {
       ...platform,
       runner: fallbackRunner,
+      githubHosted: true,
     };
   });
   return {

package/scripts/run-lifecycle-core.mjs

@@ -29,6 +29,7 @@ import {
   validateExpectedArtifacts,
 } from "./build-contract-core.mjs";
 import { verifyCompilerCacheActivity } from "./compiler-cache-evidence.mjs";
+import { lifecycleSubstageEvidenceContext } from "./lifecycle-substage-evidence.mjs";
 
 const moduleDir = path.dirname(fileURLToPath(import.meta.url));
 const buildchainCliCandidates = [
@@ -432,6 +433,7 @@ export function runLifecycle({
   processSampleIntervalMs = 15000,
   requestedParallelism = 0,
   processSummaryRequired = true,
+  substageEvidencePath = "",
 } = {}) {
   if (timeoutMinutes !== undefined && (!Number.isFinite(timeoutMinutes) || timeoutMinutes <= 0)) {
     throw new Error("lifecycle timeoutMinutes must be a positive number");
@@ -652,7 +654,6 @@ export function runLifecycle({
       throw lifecycleError;
     }
   }
-
   if (required && !executed) {
     frameworkLog.error("lifecycle.required-missing", {
       attributes: {
@@ -663,13 +664,8 @@ export function runLifecycle({
     throw new Error(`required lifecycle stage did not run: ${stageName || "command"}`);
   }
 
-  const compilerCacheActivity = verifyBuildLifecycleCompilerCacheActivity({
-    stageName,
-    executed,
-    cwd: resolvedCwd,
-    frameworkLog,
-  });
-
+  const compilerCacheActivity = verifyBuildLifecycleCompilerCacheActivity({ stageName, executed, cwd: resolvedCwd, frameworkLog });
+  const substages = lifecycleSubstageEvidenceContext({ substageEvidencePath, cwd: resolvedCwd, workspace: resolvedWorkspace, diagnosticsDir, lifecycleStage: stageName, platformId });
   const shouldReadProcessSummary = Boolean(
     resolvedProcessSummaryPath
       && (fs.existsSync(resolvedProcessSummaryPath) || processSummaryRequired),
@@ -763,7 +759,7 @@ export function runLifecycle({
     fileCount: summary.fileCount,
   });
   observability.lifecycle = lifecycleObservability;
-  Object.assign(observability, { compilerCacheActivity });
+  Object.assign(observability, { compilerCacheActivity }, substages.observability);
   observability.diagnostics = {
     contract: BUILDCHAIN_DIAGNOSTICS_CONTRACT,
     path: relativeDiagnosticsPath,
@@ -796,6 +792,7 @@ export function runLifecycle({
       stage: stageName,
       commandSource,
       executed,
+      ...substages.lifecycle,
     },
     observability,
     summary: summaryWithObservability,
@@ -829,6 +826,7 @@ export function runLifecycle({
         ...(relativeProcessSummaryPath ? { processSummary: relativeProcessSummaryPath } : {}),
         ...(processSummaryArtifact ? { diagnosticsProcessSummary: relativeDiagnosticsProcessSummaryPath } : {}),
         ...(processSummaryArtifact?.samplesPath ? { diagnosticsProcessSamples: relativeDiagnosticsProcessSamplesPath } : {}),
+        ...substages.links,
         ...(sourceCheckoutArtifact ? { sourceCheckout: relativeDiagnosticsSourceCheckoutPath } : {}),
         ...(compilerCachePreparationArtifact
           ? { compilerCachePreparation: relativeDiagnosticsCompilerCachePreparationPath }
@@ -851,6 +849,7 @@ export function runLifecycle({
     });
     copyIfExists(resolvedSamplesPath, resolvedDiagnosticsProcessSamplesPath);
   }
+  copyIfExists(substages.sourcePath, substages.targetPath);
   if (sourceCheckoutArtifact) {
     copyIfExists(resolvedSourceCheckoutPath, resolvedDiagnosticsSourceCheckoutPath);
   }
@@ -870,6 +869,7 @@ export function runLifecycle({
       { kind: "events", filePath: resolvedDiagnosticsEventsPath, required: true },
       { kind: "process-summary", filePath: resolvedDiagnosticsProcessSummaryPath },
       { kind: "process-samples", filePath: resolvedDiagnosticsProcessSamplesPath },
+      substages.sidecar,
       { kind: "source-checkout", filePath: resolvedDiagnosticsSourceCheckoutPath },
       {
         kind: "compiler-cache-preparation",

package/scripts/shifu-gate-profile.mjs

@@ -10,6 +10,7 @@ import {
 import {
   createGateAggregate,
   createGateExecutionMatrix,
+  normalizeGateEnvironment,
   normalizeGatePlatform,
 } from "./gate-profile-core.mjs";
 
@@ -54,27 +55,20 @@ function commandForPlatform(commandJson, platform) {
   return argv;
 }
 
-function gateEnvironment() {
+export function gateEnvironment(platformEnvironment = {}) {
   const parsed = parseJson(
     process.env.BUILDCHAIN_GATE_ENVIRONMENT_JSON || "{}",
     "gate-environment-json",
   );
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error("gate-environment-json must be a JSON object");
-  }
-  const entries = Object.entries(parsed).map(([name, value]) => {
-    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
-      throw new Error(`invalid Gate environment name: ${name}`);
-    if (!["string", "number", "boolean"].includes(typeof value)) {
-      throw new Error(
-        `Gate environment ${name} must be a string, number, or boolean`,
-      );
-    }
-    return [name, String(value)];
-  });
+  const shared = normalizeGateEnvironment(parsed, "gate-environment-json");
+  const platform = normalizeGateEnvironment(
+    platformEnvironment,
+    "gate matrix entry environment",
+  );
   return {
     ...process.env,
-    ...Object.fromEntries(entries),
+    ...shared,
+    ...platform,
     ...(process.env.BUILDCHAIN_SHIFU_CACHE_PROFILE_REF
       ? {
           SHIFU_CACHE_PROFILE_REF:
@@ -237,7 +231,7 @@ function runMode() {
   const receiptPath = path.join(outputRoot, "receipt.json");
   const validationPath = path.join(outputRoot, "validation.json");
   const executionPath = path.join(outputRoot, "execution.json");
-  const env = gateEnvironment();
+  const env = gateEnvironment(entry.environment || {});
   fs.mkdirSync(outputRoot, { recursive: true });
   prepareGateExecutionFiles([receiptPath, validationPath, executionPath]);
   const argv = commandForPlatform(commandJson, entry.platform);

package/scripts/site-capability-metadata.mjs

@@ -87,7 +87,20 @@ export function cliCommandMeta(id) {
     "kfd-upstream-roles": { group: "kfd-trust", purpose: "List Buildchain-managed KFD upstream role values and inference policy." },
     lifecycle: { group: "reusable-build", purpose: "Run configured lifecycle commands and write deterministic artifact manifests." },
     dev: { group: "governance-versioning", purpose: "Inspect protected development-channel governance command families." },
+    "dev-proof-classify": { group: "governance-versioning", purpose: "Classify source-qualified candidate changes against a current integration base." },
+    "dev-proof-integration": { group: "governance-versioning", purpose: "Seal final exact integration delivery proof for a warranted candidate." },
+    "dev-proof-replay": { group: "governance-versioning", purpose: "Replay source qualification against a Project Cut without rewriting candidate source." },
+    "dev-proof-source": { group: "governance-versioning", purpose: "Seal source qualification proof for an exact candidate head and source tree." },
+    "dev-proof-verify-integration": { group: "governance-versioning", purpose: "Verify exact integration delivery proof and its source qualification binding." },
+    "dev-proof-verify-source": { group: "governance-versioning", purpose: "Verify source qualification proof against exact candidate roots." },
     "dev-merge-queue": { group: "governance-versioning", purpose: "Plan or apply an exact-branch GitHub merge queue after required workflow event compatibility is verified." },
+    "dev-warrant-close": { group: "governance-versioning", purpose: "Close the active fenced Dev Delivery Warrant with terminal proof." },
+    "dev-warrant-cancel-queued": { group: "governance-versioning", purpose: "Cancel one exact non-active queued candidate from immutable terminal event evidence." },
+    "dev-warrant-heartbeat": { group: "governance-versioning", purpose: "Renew the active fenced Dev Delivery Warrant without changing queue order." },
+    "dev-warrant-observe": { group: "governance-versioning", purpose: "Read the durable Dev Delivery Warrant queue without mutating authority state." },
+    "dev-warrant-recover": { group: "governance-versioning", purpose: "Recover an expired fenced Warrant and retain candidate age." },
+    "dev-warrant-select": { group: "governance-versioning", purpose: "Select the next fair candidate and issue one fenced delivery Warrant." },
+    "dev-warrant-submit": { group: "governance-versioning", purpose: "Submit or safely refresh an exact candidate in the durable delivery queue." },
     log: { group: "observability-diagnostics", purpose: "Inspect Buildchain logging command families." },
     logging: { group: "observability-diagnostics", purpose: "Emit timestamped build events, summarize logs, and enforce required phases." },
     mark: { group: "observability-diagnostics", purpose: "Emit a single Buildchain log event." },
@@ -155,6 +168,7 @@ export function nodeApiMeta(exportName) {
     "./build-facts": { group: "observability-diagnostics", summary: "Git source, version, module output, product artifact, and legacy Kungfu build fact APIs." },
     "./candidate-timeline": { group: "observability-diagnostics", summary: "Source-bound candidate event normalization, per-attempt critical-path-safe aggregation, and compact reporting APIs." },
     "./channel-candidate": { group: "governance-versioning", summary: "Exact-source channel candidate decisions, same-SHA workflow evidence validation, and deterministic source-lock reference APIs." },
+    "./dev-delivery-warrant": { group: "governance-versioning", summary: "Durable fair Dev Delivery Warrant queue, fenced lease, and split source and integration proof APIs." },
     "./cache-evidence": { group: "observability-diagnostics", summary: "Content-addressed cache operation receipts and source/platform-bound evidence-set verification APIs." },
     "./diagnostics": { group: "observability-diagnostics", summary: "Native diagnostics collection, summarization, cache, compiler, and process-sampler APIs." },
     "./logging": { group: "observability-diagnostics", summary: "Buildchain JSONL logging, span, summary, and verification APIs." },