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

package/scripts/dev-pr-delivery-warrant.mjs

@@ -0,0 +1,209 @@
+import fs from "node:fs";
+
+const ROOT_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const SHA_PATTERN = /^[0-9a-f]{40}$/;
+const ADMISSION_SCHEMA = "kungfu.buildchain.dev-pr-admission/v1";
+
+function mismatch(code) {
+  const error = new Error(code);
+  error.code = code;
+  throw error;
+}
+
+function requireMatch(condition, code) {
+  if (!condition) mismatch(code);
+}
+
+function readWarrantResult(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (cause) {
+    const error = new Error(`delivery Warrant result is unreadable: ${cause.message}`);
+    error.code = "invalid-delivery-warrant-result";
+    throw error;
+  }
+}
+
+function exactActiveReadback(result) {
+  requireMatch(result.schema === "kungfu.buildchain.dev-delivery-command-result/v1", "unsupported-delivery-warrant-result");
+  requireMatch(result.mode === "execute", "delivery-warrant-not-executed");
+  requireMatch(SHA_PATTERN.test(String(result.after?.commitSha || "")), "delivery-warrant-commit-readback-missing");
+  requireMatch(ROOT_PATTERN.test(String(result.after?.stateRoot || "")), "delivery-warrant-state-readback-missing");
+  requireMatch(result.observation?.schema === "kungfu.buildchain.dev-delivery-queue-observation/v1", "delivery-warrant-observation-missing");
+  requireMatch(result.observation.stateRoot === result.after.stateRoot, "delivery-warrant-observation-root-mismatch");
+  const warrant = result.observation.activeWarrant;
+  const candidate = result.observation.activeCandidate;
+  requireMatch(warrant?.schema === "kungfu.buildchain.dev-delivery-warrant/v1", "delivery-warrant-missing");
+  requireMatch(candidate?.candidateId === warrant.candidateId, "delivery-warrant-candidate-readback-missing");
+  requireMatch(!result.warrant || JSON.stringify(result.warrant) === JSON.stringify(warrant), "delivery-warrant-readback-mismatch");
+  return { warrant, candidate };
+}
+
+function exactWarrantBinding({ result, warrant, candidate, options, pullRequest }) {
+  requireMatch(warrant.repository === options.repository.fullName, "delivery-warrant-repository-mismatch");
+  requireMatch(warrant.protectedBase === options.targetBranch, "delivery-warrant-base-mismatch");
+  requireMatch(Number(warrant.pullRequestNumber) === Number(pullRequest.number), "delivery-warrant-pr-mismatch");
+  requireMatch(String(warrant.sourceHead || "").toLowerCase() === options.expectedHeadSha, "delivery-warrant-head-mismatch");
+  requireMatch(Number(candidate.pullRequestNumber) === Number(pullRequest.number), "delivery-warrant-candidate-pr-mismatch");
+  requireMatch(String(candidate.sourceHead || "").toLowerCase() === options.expectedHeadSha, "delivery-warrant-candidate-head-mismatch");
+  requireMatch(ROOT_PATTERN.test(String(warrant.fencingToken || "")), "delivery-warrant-fencing-missing");
+  requireMatch(Number.isInteger(Number(warrant.generation)) && Number(warrant.generation) >= 1, "delivery-warrant-generation-invalid");
+  requireMatch(Number.isFinite(Date.parse(warrant.expiresAt)) && Date.parse(warrant.expiresAt) > Date.now(), "delivery-warrant-expired");
+  requireMatch(ROOT_PATTERN.test(String(result.receiptRoot || "")), "delivery-warrant-receipt-root-missing");
+}
+
+export function createDevPrAdmissionReceipt({ options, pr = {}, state, reason, readiness, decision = {}, queue = null, warrant = null, labels = [], nextAction }) {
+  const observedHeadSha = String(pr.head?.sha || "").toLowerCase();
+  return {
+    schema: ADMISSION_SCHEMA,
+    repository: options.repository.fullName,
+    targetBranch: options.targetBranch,
+    pullRequestNumber: options.targetPullRequestNumber,
+    pullRequestUrl: pr.html_url || `https://github.com/${options.repository.fullName}/pull/${options.targetPullRequestNumber}`,
+    expectedHeadSha: options.expectedHeadSha,
+    observedHeadSha,
+    observedBaseBranch: pr.base?.ref || "",
+    headRepository: pr.head?.repo?.full_name || "",
+    headRef: pr.head?.ref || "",
+    observedLabels: [...labels].sort(),
+    policy: {
+      readyLabel: options.readyLabel,
+      blockLabels: options.blockLabels,
+      allowedHeadPrefixes: options.allowedHeadPrefixes,
+      requiredChecks: options.requiredChecks,
+      requireApproval: options.requireApproval,
+      sameRepositoryOnly: options.sameRepositoryOnly,
+      landingMode: options.landingMode,
+      queueAdmissionContext: options.queueAdmissionContext,
+      diagnosticContext: options.diagnosticContext,
+    },
+    readiness: {
+      label: options.readyLabel,
+      observed: readiness?.observed === true,
+      established: readiness?.established === true,
+      mutationAuthorized: !options.dryRun,
+    },
+    approval: decision.approval || { required: options.requireApproval, passed: false },
+    checks: decision.checks || { required: options.requiredChecks, entries: [], passed: false },
+    projectCut: decision.projectCut || null,
+    queue,
+    deliveryWarrant: warrant,
+    autoMergeEnabled: Boolean(pr.auto_merge || pr.autoMergeRequest),
+    state,
+    reason,
+    decision: state,
+    qualification: ["ready", "queued"].includes(state),
+    nextAction: nextAction({ options, state, reason, observedHeadSha }),
+  };
+}
+
+export function readDeliveryWarrantResult(options, pullRequest) {
+  if (options.warrantMode === "off") return null;
+  if (!options.warrantResultPath) mismatch("missing-delivery-warrant");
+  const result = readWarrantResult(options.warrantResultPath);
+  const { warrant, candidate } = exactActiveReadback(result);
+  exactWarrantBinding({ result, warrant, candidate, options, pullRequest });
+  return {
+    stateRef: result.stateRef || "",
+    stateCommit: result.after.commitSha,
+    stateRoot: result.after.stateRoot,
+    receiptRoot: result.receiptRoot,
+    candidateId: warrant.candidateId,
+    fencingToken: warrant.fencingToken,
+    generation: warrant.generation,
+    issuedAt: warrant.issuedAt,
+    expiresAt: warrant.expiresAt,
+  };
+}
+
+export async function runSourceQualification({ options, pullRequest, readiness, client, evaluate, admissionState, createReceipt, root, publishDiagnostic, reject }) {
+  const decision = await evaluate(pullRequest, { ...options, landingMode: options.landingMode, dryRun: true }, client);
+  if (decision.observedHeadSha && String(decision.observedHeadSha).toLowerCase() !== options.expectedHeadSha) {
+    return reject("stale", "head-sha-drift-during-source-qualification", readiness);
+  }
+  const state = decision.action === "would-merge" ? "ready" : admissionState(decision);
+  const receipt = createReceipt({
+    options,
+    pr: pullRequest,
+    state,
+    reason: state === "ready" ? "source-qualified-exact-head" : decision.reason,
+    readiness,
+    decision,
+    queue: null,
+    warrant: null,
+  });
+  const result = {
+    schema: "kungfu.buildchain.dev-pr-admission-result/v1",
+    ok: state === "ready",
+    mode: options.dryRun ? "plan" : "execute",
+    outcome: state === "ready" ? "source-qualified" : "targeted-admission-failed",
+    receipt,
+    receiptRoot: root(receipt),
+    diagnostic: null,
+  };
+  if (!options.dryRun) result.diagnostic = await publishDiagnostic(client, options, receipt, result.receiptRoot);
+  return result;
+}
+
+export async function admitExistingQueueEntry({ options, pullRequest, readiness, client, entry, warrant, createReceipt, root, publishDiagnostic }) {
+  if (!entry) return null;
+  const receipt = createReceipt({
+    options,
+    pr: pullRequest,
+    state: "queued",
+    reason: "already-enqueued-exact-head",
+    readiness,
+    queue: { enabled: true, entry },
+    warrant,
+  });
+  const result = {
+    schema: "kungfu.buildchain.dev-pr-admission-result/v1",
+    ok: true,
+    mode: options.dryRun ? "plan" : "execute",
+    outcome: "admitted",
+    receipt,
+    receiptRoot: root(receipt),
+    diagnostic: null,
+  };
+  if (!options.dryRun) result.diagnostic = await publishDiagnostic(client, options, receipt, result.receiptRoot);
+  return result;
+}
+
+export async function runTargetedQueueAdmission({ options, pullRequest, readiness, client, warrant, runController, admissionState, createReceipt, root, publishDiagnostic }) {
+  const targetedClient = Object.create(client);
+  targetedClient.listPullRequests = async () => [pullRequest];
+  const controller = await runController({ ...options, targetPullRequestNumber: 0 }, targetedClient);
+  controller.runKind = "targeted-admission-evaluation";
+  controller.outcome = controller.actions.length === 0 ? "target-not-admitted" : "target-action-selected";
+  controller.qualification = false;
+  controller.noOp = controller.actions.length === 0;
+  const entry = controller.evaluated.find((value) => value.number === pullRequest.number) || { action: "skip", reason: "target-not-selected" };
+  const state = admissionState(entry);
+  const receipt = createReceipt({
+    options,
+    pr: pullRequest,
+    state,
+    reason: entry.reason,
+    readiness,
+    decision: entry,
+    queue: {
+      enabled: controller.mergeQueue?.enabled === true,
+      predecessor: entry.admissionReceipt?.predecessor || null,
+      entry: entry.queueEntry || null,
+    },
+    warrant,
+  });
+  const admitted = ["ready", "queued"].includes(state);
+  const result = {
+    schema: "kungfu.buildchain.dev-pr-admission-result/v1",
+    ok: admitted,
+    mode: options.dryRun ? "plan" : "execute",
+    outcome: admitted ? "admitted" : "targeted-admission-failed",
+    receipt,
+    receiptRoot: root(receipt),
+    diagnostic: null,
+    controller,
+  };
+  if (!options.dryRun) result.diagnostic = await publishDiagnostic(client, options, receipt, result.receiptRoot);
+  return result;
+}

package/scripts/gate-profile-core.mjs

@@ -67,6 +67,25 @@ function uniqueStrings(value, label) {
   return normalized;
 }
 
+export function normalizeGateEnvironment(value = {}, label = "environment") {
+  const environment = assertObject(value, label);
+  return Object.fromEntries(
+    Object.entries(environment)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([name, entry]) => {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+          throw new Error(`${label} has invalid environment name: ${name}`);
+        }
+        if (!["string", "number", "boolean"].includes(typeof entry)) {
+          throw new Error(
+            `${label}.${name} must be a string, number, or boolean`,
+          );
+        }
+        return [name, String(entry)];
+      }),
+  );
+}
+
 function inferShifuPlatform(platform) {
   const explicit = String(platform.platform || "")
     .trim()
@@ -121,6 +140,10 @@ export function normalizeGatePlatform(platform, index = 0) {
       platform.capabilities || ["node"],
       `platforms[${index}].capabilities`,
     ).sort(),
+    environment: normalizeGateEnvironment(
+      platform.environment || {},
+      `platforms[${index}].environment`,
+    ),
     required: platform.required !== false,
   };
 }
@@ -259,6 +282,7 @@ export function createGateExecutionMatrix({
       platform: platform.platform,
       runner: platform.runner,
       capabilities: platform.capabilities,
+      environment: platform.environment,
       required: platform.required,
       profile,
       includeAdvisory: Boolean(includeAdvisory),

package/scripts/generate-site-bundle.mjs

@@ -56,7 +56,6 @@ const requireFromHere = createRequire(import.meta.url);
 function readText(rel) {
   return fs.readFileSync(path.join(root, rel), "utf8");
 }
-
 function readJson(rel) {
   return JSON.parse(readText(rel));
 }
@@ -518,7 +517,7 @@ function workflowCapabilityGroup(entry) {
   if (["web-surface", "release-propagation"].includes(entry.id)) return capabilityGroup("site-and-propagation");
   if (["build", "release-candidate-promote", "publication-artifact", "paper-release"].includes(entry.id)) return capabilityGroup("reusable-build");
   if (["buildchain-ref-promotion", "release-line-bootstrap"].includes(entry.id)) return capabilityGroup("release-passport-trust");
-  if (entry.id.includes("patrol") || entry.id.includes("dev-pr-auto-merge")) return capabilityGroup("governance-versioning");
+  if (entry.id.includes("patrol") || entry.id.includes("dev-pr-auto-merge") || entry.id.includes("dev-delivery-warrant") || entry.id.includes("buildchain-dev-delivery")) return capabilityGroup("governance-versioning");
   if (entry.status === "repository-internal" || entry.status === "compatibility-fixture") return capabilityGroup("api-cli-reference");
   return capabilityGroup("api-cli-reference");
 }
@@ -778,6 +777,7 @@ function buildSiteBundle() {
         ["paper-release", "reusable-build"],
         ["release-propagation", "release-propagation"],
         ["dev-pr-auto-merge", "dev-governance"],
+        ["buildchain-dev-delivery", "dev-governance"],
         ["github-governance-audit", "dev-governance"],
         ["binary-distribution", "release-passport"],
         ["github-artifact-attestation", "release-passport"],

package/scripts/git-fetch-process-tree.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+import { execFileSync, spawn } from "node:child_process";
+import fs from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const INTERNAL_COMMAND = "--buildchain-internal-git-fetch";
+const TIMEOUT_EXIT_CODE = 124;
+const scriptPath = fileURLToPath(import.meta.url);
+
+async function terminateProcessTree(child, graceMs) {
+  if (!child?.pid) return;
+  if (process.platform === "win32") {
+    await new Promise((resolve) => {
+      const killer = spawn(
+        "taskkill",
+        ["/pid", String(child.pid), "/t", "/f"],
+        {
+          stdio: "ignore",
+          windowsHide: true,
+        },
+      );
+      const fallback = setTimeout(() => {
+        try {
+          child.kill("SIGKILL");
+        } catch {
+          // The process tree may already be gone.
+        }
+        resolve();
+      }, graceMs);
+      killer.once("error", () => {
+        clearTimeout(fallback);
+        try {
+          child.kill("SIGKILL");
+        } catch {
+          // The process tree may already be gone.
+        }
+        resolve();
+      });
+      killer.once("close", () => {
+        clearTimeout(fallback);
+        resolve();
+      });
+    });
+    return;
+  }
+  try {
+    process.kill(-child.pid, "SIGTERM");
+  } catch {
+    return;
+  }
+  await new Promise((resolve) => setTimeout(resolve, graceMs));
+  try {
+    process.kill(-child.pid, "SIGKILL");
+  } catch {
+    // The process group exited during the grace period.
+  }
+}
+
+async function runInternalGitFetch() {
+  const payload = JSON.parse(fs.readFileSync(0, "utf8"));
+  const timeoutMs = Math.max(1, Number(payload.timeoutMs || 60000));
+  const graceMs = Math.max(
+    50,
+    Number(process.env.BUILDCHAIN_GIT_TIMEOUT_GRACE_MS || 2000),
+  );
+  const child = spawn("git", payload.args, {
+    cwd: payload.cwd,
+    env: process.env,
+    detached: process.platform !== "win32",
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+  });
+  const stdout = [];
+  const stderr = [];
+  child.stdout.on("data", (chunk) => stdout.push(chunk));
+  child.stderr.on("data", (chunk) => stderr.push(chunk));
+  let timedOut = false;
+  let spawnError;
+  const closed = new Promise((resolve) => {
+    child.once("error", (error) => {
+      spawnError = error;
+      resolve({ code: 1, signal: "" });
+    });
+    child.once("close", (code, signal) => resolve({ code, signal }));
+  });
+  const timer = setTimeout(() => {
+    timedOut = true;
+    void terminateProcessTree(child, graceMs);
+  }, timeoutMs);
+  const result = await closed;
+  clearTimeout(timer);
+  if (stdout.length) process.stdout.write(Buffer.concat(stdout));
+  if (stderr.length) process.stderr.write(Buffer.concat(stderr));
+  if (spawnError)
+    console.error(
+      `buildchain: failed to start git fetch: ${spawnError.message}`,
+    );
+  if (timedOut)
+    console.error(
+      `buildchain: git fetch timed out after ${timeoutMs}ms; process tree terminated`,
+    );
+  if (result.signal && !timedOut)
+    console.error(`buildchain: git fetch terminated by ${result.signal}`);
+  process.exitCode = timedOut
+    ? TIMEOUT_EXIT_CODE
+    : spawnError || result.signal
+      ? 1
+      : (result.code ?? 1);
+}
+
+export function runGitFetchSync({ args, cwd, env, timeoutMs, stdio }) {
+  const commandStdio = Array.isArray(stdio)
+    ? ["pipe", stdio[1] || "pipe", stdio[2] || "pipe"]
+    : ["pipe", stdio, stdio];
+  try {
+    const output = execFileSync(
+      process.execPath,
+      [scriptPath, INTERNAL_COMMAND],
+      {
+        cwd,
+        env,
+        encoding: "utf8",
+        stdio: commandStdio,
+        input: JSON.stringify({ args, cwd, timeoutMs }),
+        windowsHide: true,
+      },
+    );
+    return output ? String(output).trim() : "";
+  } catch (error) {
+    if (error?.status === TIMEOUT_EXIT_CODE) error.code = "ETIMEDOUT";
+    throw error;
+  }
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  if (process.argv[2] !== INTERNAL_COMMAND)
+    throw new Error("internal git fetch command required");
+  await runInternalGitFetch();
+}

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);
+  }
+}