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

package/packages/core/observability/diagnostics.js

@@ -0,0 +1,1904 @@
+import { execFileSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  discoverConfiguredVersionStateFiles,
+  getNativeDiagnosticsProfile,
+  getLifecycleStage,
+  getPublishContract,
+  getVersionStrategy,
+  loadBuildchainConfig,
+  loadConfiguredAnchorManifest,
+  validateBuildchainConfig,
+} from "../consumer/buildchain-config.js";
+import { detectPackageManager, getWorkspaceInfo } from "../build/package-manager.js";
+import {
+  BUILDCHAIN_LOG_EVENT_CONTRACT,
+  readBuildchainLogEvents,
+  summarizeBuildchainLogEvents,
+} from "./logging.js";
+import {
+  cacheEvidenceDigest,
+  createCacheEvidenceSet,
+  createCacheOperationReceipt,
+} from "./cache-evidence.js";
+
+export const BUILDCHAIN_DIAGNOSTICS_CONTRACT = "kungfu-buildchain-diagnostics";
+export const BUILDCHAIN_LIFECYCLE_OBSERVABILITY_CONTRACT =
+  "kungfu-buildchain-lifecycle-observability";
+export const BUILDCHAIN_ANCHORED_PACKAGE_RELEASE_VALIDATION_CONTRACT =
+  "kungfu-buildchain-anchored-package-release-validation";
+export const BUILDCHAIN_DIAGNOSTICS_MANIFEST_CONTRACT =
+  "kungfu-buildchain-diagnostics-manifest";
+export const BUILDCHAIN_DIAGNOSTICS_SUMMARY_CONTRACT =
+  "kungfu-buildchain-diagnostics-summary";
+export const BUILDCHAIN_PROCESS_SAMPLE_REPORT_CONTRACT =
+  "kungfu-buildchain-process-sample-report";
+export const BUILDCHAIN_PROCESS_SAMPLE_SUMMARY_CONTRACT =
+  "kungfu-buildchain-process-sample-summary";
+export const BUILDCHAIN_LOCKED_SOURCE_CHECKOUT_CONTRACT =
+  "kungfu-buildchain-locked-source-checkout-cache";
+
+const DEFAULT_SECRET_KEY_PATTERN =
+  /(authorization|cookie|credential|password|passwd|private[_-]?key|secret|token|api[_-]?key)/i;
+
+function posixPath(value) {
+  return String(value || "").split(path.sep).join("/");
+}
+
+function safeReadJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+function readJsonResult(filePath) {
+  try {
+    return { value: JSON.parse(fs.readFileSync(filePath, "utf8")) };
+  } catch (error) {
+    return { error };
+  }
+}
+
+function sha256File(filePath) {
+  return crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+}
+
+function fileStats(cwd, entries = []) {
+  return entries.map((entry) => {
+    const filePath = path.resolve(cwd, entry);
+    if (!fs.existsSync(filePath)) {
+      return { path: posixPath(entry), exists: false };
+    }
+    const stat = fs.statSync(filePath);
+    return {
+      path: posixPath(entry),
+      exists: true,
+      type: stat.isDirectory() ? "directory" : stat.isFile() ? "file" : "other",
+      bytes: stat.size,
+    };
+  });
+}
+
+function commandVersion(command, args = ["--version"], cwd = process.cwd()) {
+  try {
+    return execFileSync(command, args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5000,
+    }).trim().split(/\r?\n/)[0] || "";
+  } catch {
+    return "";
+  }
+}
+
+function defaultDiagnosticCommandRunner(command, args = [], { cwd = process.cwd(), timeoutMs = 5000 } = {}) {
+  return execFileSync(command, args, {
+    cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    timeout: timeoutMs,
+  });
+}
+
+function gitField(cwd, args) {
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5000,
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+function safeAnchorManifest(cwd, loadedConfig) {
+  try {
+    return loadConfiguredAnchorManifest(cwd, loadedConfig);
+  } catch (error) {
+    return { error: error.message };
+  }
+}
+
+function check(ok, id, message, details = {}) {
+  return { id, status: ok ? "pass" : "fail", message, details };
+}
+
+function normalizePublishSourceRef(value = "") {
+  return String(value || "")
+    .trim()
+    .replace(/^refs\/heads\//, "")
+    .replace(/^refs\/tags\//, "");
+}
+
+function parsePublishGateSourceRef(value = "") {
+  const sourceRef = normalizePublishSourceRef(value);
+  if (sourceRef === "publish-gate/major") {
+    return { sourceRef, channel: "major", line: "", consumerVersion: "" };
+  }
+  if (sourceRef === "publish-gate/anchor") {
+    return { sourceRef, channel: "anchor", line: "", consumerVersion: "" };
+  }
+  const match = sourceRef.match(/^publish-gate\/(alpha|release)\/(.+)\/([^/]+)$/);
+  if (!match) {
+    return { sourceRef, channel: "", line: "", consumerVersion: "" };
+  }
+  return {
+    sourceRef,
+    channel: match[1],
+    line: match[2],
+    consumerVersion: match[3],
+  };
+}
+
+function versionFileValue(file) {
+  if (file.type === "json" || file.type === "toml") {
+    return String(file.key || "")
+      .split(".")
+      .reduce((current, segment) => current?.[segment], file.content);
+  }
+  return file.source.match(file.pattern)?.groups?.version;
+}
+
+function defaultPublishSourceFromEnv(env = process.env) {
+  return {
+    sourceRef: env.BUILDCHAIN_PUBLISH_SOURCE_REF || "",
+    sourceSha: env.BUILDCHAIN_PUBLISH_SOURCE_SHA || "",
+    sourceLocked: env.BUILDCHAIN_PUBLISH_SOURCE_LOCKED || "",
+    channel: env.BUILDCHAIN_PUBLISH_SOURCE_CHANNEL || "",
+    consumerVersion: env.BUILDCHAIN_PUBLISH_SOURCE_CONSUMER_VERSION || "",
+  };
+}
+
+function lifecycleTimingFromEvents(events = []) {
+  const stages = {};
+  const spans = [];
+  let warningCount = 0;
+  let errorCount = 0;
+  for (const event of events) {
+    if (event.level === "warn") {
+      warningCount += 1;
+    }
+    if (event.level === "error") {
+      errorCount += 1;
+    }
+    const stage = event.attributes?.stage || event.phase || "unknown";
+    const durationMs = Number(event.durationMs || 0);
+    if (durationMs > 0) {
+      stages[stage] = stages[stage] || { durationMs: 0, eventCount: 0 };
+      stages[stage].durationMs += durationMs;
+      spans.push({
+        event: event.event,
+        source: event.source || "",
+        component: event.component || "",
+        stage,
+        phase: event.phase || "",
+        durationMs,
+      });
+    }
+    if (stage) {
+      stages[stage] = stages[stage] || { durationMs: 0, eventCount: 0 };
+      stages[stage].eventCount += 1;
+    }
+  }
+  return {
+    stages: Object.fromEntries(Object.entries(stages).sort(([left], [right]) => left.localeCompare(right))),
+    topSlowSpans: spans.sort((left, right) => right.durationMs - left.durationMs).slice(0, 10),
+    warningCount,
+    errorCount,
+  };
+}
+
+export function summarizeLifecycleObservability({
+  events = [],
+  logPath = "",
+  artifactScanDurationMs = 0,
+  artifactUploadDurationMs = 0,
+  totalBytes = 0,
+  fileCount = 0,
+} = {}) {
+  const resolvedEvents = events.length ? events : readBuildchainLogEvents(logPath);
+  const timing = lifecycleTimingFromEvents(resolvedEvents);
+  return {
+    schemaVersion: 1,
+    contract: BUILDCHAIN_LIFECYCLE_OBSERVABILITY_CONTRACT,
+    log: {
+      contract: BUILDCHAIN_LOG_EVENT_CONTRACT,
+      path: logPath ? posixPath(logPath) : "",
+      summary: summarizeBuildchainLogEvents(resolvedEvents),
+    },
+    stages: timing.stages,
+    artifactScan: { durationMs: Math.round(Number(artifactScanDurationMs || 0)) },
+    artifactUpload: { durationMs: Math.round(Number(artifactUploadDurationMs || 0)) },
+    totalBytes: Number(totalBytes || 0),
+    fileCount: Number(fileCount || 0),
+    topSlowSpans: timing.topSlowSpans,
+    warningCount: timing.warningCount,
+    errorCount: timing.errorCount,
+  };
+}
+
+export function collectBuildchainDiagnostics({ cwd = process.cwd(), artifactPaths = [] } = {}) {
+  const resolvedCwd = path.resolve(cwd);
+  const loadedConfig = loadBuildchainConfig(resolvedCwd);
+  let configSummary = {};
+  try {
+    configSummary = validateBuildchainConfig(resolvedCwd);
+  } catch (error) {
+    configSummary = { ok: false, error: error.message };
+  }
+  return {
+    config: loadedConfig
+      ? {
+          path: loadedConfig.path,
+          project: loadedConfig.config.project || {},
+          versionStrategy: getVersionStrategy(loadedConfig),
+          publishContract: getPublishContract(loadedConfig),
+          lifecycleStages: Object.keys(loadedConfig.config.lifecycle || {}),
+          diagnostics: {
+            native: getNativeDiagnosticsProfile(loadedConfig),
+          },
+          anchorManifest: safeAnchorManifest(resolvedCwd, loadedConfig),
+          validation: configSummary,
+        }
+      : { path: "", validation: configSummary },
+    lifecycle: Object.fromEntries(
+      ["install", "build", "verify", "publish"]
+        .map((stage) => [stage, getLifecycleStage(loadedConfig, stage)])
+        .filter(([, value]) => Boolean(value)),
+    ),
+    artifactPaths: fileStats(resolvedCwd, artifactPaths),
+  };
+}
+
+function selectedCompilerCacheDiagnostics({ cwd, compilerCache, runCommand }) {
+  if (compilerCache === "none") {
+    return {};
+  }
+  const diagnostics = collectCompilerCacheDiagnostics({ cwd, runCommand });
+  if (compilerCache === "ccache") {
+    return { ccache: diagnostics.ccache };
+  }
+  if (compilerCache === "sccache") {
+    return { sccache: diagnostics.sccache };
+  }
+  return diagnostics;
+}
+
+export function collectNativeDiagnostics({
+  cwd = process.cwd(),
+  profile = undefined,
+  runCommand = defaultDiagnosticCommandRunner,
+} = {}) {
+  const resolvedCwd = path.resolve(cwd);
+  const nativeProfile = profile || getNativeDiagnosticsProfile(loadBuildchainConfig(resolvedCwd));
+  if (!nativeProfile.enabled) {
+    return {
+      enabled: false,
+      profile: nativeProfile,
+    };
+  }
+  const expectedTools = nativeProfile.expectedTools.length
+    ? nativeProfile.expectedTools
+    : ["node", "pnpm", "npm", "git", "cmake", "ninja", "ccache", "sccache"];
+  return {
+    enabled: true,
+    profile: nativeProfile,
+    tools: collectToolDiagnostics({ cwd: resolvedCwd, tools: expectedTools }),
+    compilerCaches: selectedCompilerCacheDiagnostics({
+      cwd: resolvedCwd,
+      compilerCache: nativeProfile.compilerCache,
+      runCommand,
+    }),
+    artifactDirs: fileStats(resolvedCwd, nativeProfile.artifactDirs),
+    cacheDirs: fileStats(resolvedCwd, nativeProfile.cacheDirs),
+  };
+}
+
+export function validateAnchoredPackageRelease({
+  cwd = process.cwd(),
+  requireManifest = true,
+  requirePackageSetOrder = "platforms-first-main-last",
+  requireTrustedPublishing = true,
+  requireLifecycleStages = ["install", "build", "verify", "publish"],
+  requirePublishGateSourceLock = false,
+  publishSource = undefined,
+  env = process.env,
+} = {}) {
+  const resolvedCwd = path.resolve(cwd);
+  const checks = [];
+  let versionFiles = [];
+  let loadedConfig;
+  try {
+    loadedConfig = loadBuildchainConfig(resolvedCwd);
+    checks.push(check(Boolean(loadedConfig), "config.load", "buildchain.toml is readable"));
+  } catch (error) {
+    checks.push(check(false, "config.load", error.message));
+  }
+  const versionStrategy = getVersionStrategy(loadedConfig);
+  checks.push(check(
+    versionStrategy.strategy === "anchored",
+    "version.strategy",
+    "version strategy is anchored",
+    versionStrategy,
+  ));
+  checks.push(check(
+    versionStrategy.next === "manual",
+    "version.next",
+    "next version strategy is manual",
+    versionStrategy,
+  ));
+  const anchorManifest = safeAnchorManifest(resolvedCwd, loadedConfig);
+  checks.push(check(
+    !requireManifest || (anchorManifest && !anchorManifest.error),
+    "version.manifest",
+    anchorManifest?.error || "anchor manifest is readable",
+    { path: anchorManifest?.path || versionStrategy.manifest || "" },
+  ));
+  try {
+    versionFiles = discoverConfiguredVersionStateFiles(resolvedCwd, loadedConfig);
+    checks.push(check(versionFiles.length > 0, "version.files", "configured version files are readable", {
+      files: versionFiles.map((file) => file.path),
+    }));
+  } catch (error) {
+    checks.push(check(false, "version.files", error.message));
+  }
+  const publish = getPublishContract(loadedConfig) || {};
+  checks.push(check(
+    publish.mode === "publish-final-version",
+    "publish.mode",
+    "publish mode is compatible with anchored final-version release",
+    { mode: publish.mode || "" },
+  ));
+  if (requireTrustedPublishing) {
+    checks.push(check(
+      publish.auth === "trusted-publishing",
+      "publish.auth",
+      "trusted publishing is enabled",
+      { auth: publish.auth || "" },
+    ));
+  }
+  if (requirePackageSetOrder) {
+    checks.push(check(
+      publish.packageSetOrder === requirePackageSetOrder,
+      "publish.package_set_order",
+      `package set order is ${requirePackageSetOrder}`,
+      { packageSetOrder: publish.packageSetOrder || "" },
+    ));
+  }
+  for (const stage of requireLifecycleStages || []) {
+    checks.push(check(
+      Boolean(getLifecycleStage(loadedConfig, stage)),
+      `lifecycle.${stage}`,
+      `lifecycle stage is configured: ${stage}`,
+    ));
+  }
+  const source = publishSource || defaultPublishSourceFromEnv(env);
+  const parsedSource = parsePublishGateSourceRef(source.sourceRef);
+  if (requirePublishGateSourceLock) {
+    const normalizedLocked = String(source.sourceLocked || "").toLowerCase();
+    const lockEnabled = normalizedLocked === "true" || normalizedLocked === "1" || source.sourceLocked === true;
+    checks.push(check(
+      lockEnabled,
+      "publish.source_locked",
+      "publish source lock is required before package publication",
+      { sourceLocked: source.sourceLocked || "" },
+    ));
+    checks.push(check(
+      Boolean(parsedSource.channel) && parsedSource.channel !== "anchor",
+      "publish.source_ref",
+      "publish source ref uses publish-gate/{alpha,release,major}",
+      { sourceRef: parsedSource.sourceRef || source.sourceRef || "", channel: parsedSource.channel || "" },
+    ));
+    checks.push(check(
+      /^[0-9a-f]{40}$/i.test(String(source.sourceSha || "")),
+      "publish.source_sha",
+      "publish source SHA is a 40-character Git SHA",
+      { sourceSha: source.sourceSha || "" },
+    ));
+    const consumerVersion = parsedSource.consumerVersion || source.consumerVersion || "";
+    if (consumerVersion) {
+      const mismatches = versionFiles
+        .map((file) => ({ path: file.path, version: versionFileValue(file) || "" }))
+        .filter((file) => file.version !== consumerVersion);
+      checks.push(check(
+        mismatches.length === 0,
+        "publish.source_version",
+        `publish source consumer version matches configured version files: ${consumerVersion}`,
+        { consumerVersion, mismatches },
+      ));
+      checks.push(check(
+        !anchorManifest?.fields?.npmVersion || anchorManifest.fields.npmVersion === consumerVersion,
+        "publish.anchor_version",
+        `anchor manifest npmVersion matches publish source version: ${consumerVersion}`,
+        { consumerVersion, npmVersion: anchorManifest?.fields?.npmVersion || "" },
+      ));
+    }
+  }
+  return {
+    schemaVersion: 1,
+    contract: BUILDCHAIN_ANCHORED_PACKAGE_RELEASE_VALIDATION_CONTRACT,
+    cwd: resolvedCwd,
+    ok: checks.every((entry) => entry.status === "pass"),
+    checks,
+    summary: {
+      versionStrategy,
+      anchorManifest: anchorManifest?.path || "",
+      publish,
+      publishSource: {
+        sourceRef: parsedSource.sourceRef || source.sourceRef || "",
+        sourceSha: source.sourceSha || "",
+        sourceLocked: source.sourceLocked || "",
+        channel: parsedSource.channel || source.channel || "",
+        line: parsedSource.line || "",
+        consumerVersion: parsedSource.consumerVersion || source.consumerVersion || "",
+      },
+      requiredLifecycleStages: requireLifecycleStages,
+    },
+  };
+}
+
+export function collectRunnerDiagnostics() {
+  return {
+    os: {
+      platform: os.platform(),
+      release: os.release(),
+      arch: os.arch(),
+      type: os.type(),
+    },
+    cpu: {
+      logicalCount: os.cpus().length,
+      model: os.cpus()[0]?.model || "",
+      loadAverage: os.loadavg(),
+    },
+    memory: {
+      totalBytes: os.totalmem(),
+      freeBytes: os.freemem(),
+    },
+    uptimeSeconds: Math.round(os.uptime()),
+    github: {
+      actions: process.env.GITHUB_ACTIONS === "true",
+      runnerOs: process.env.RUNNER_OS || "",
+      runnerArch: process.env.RUNNER_ARCH || "",
+      runnerName: process.env.RUNNER_NAME || "",
+    },
+  };
+}
+
+export function collectToolDiagnostics({ cwd = process.cwd(), tools = ["node", "pnpm", "npm", "git", "cmake", "ninja", "ccache", "sccache"] } = {}) {
+  return Object.fromEntries(tools.map((tool) => [tool, { version: commandVersion(tool, ["--version"], cwd) }]));
+}
+
+function parseJsonDiagnostics(value = "") {
+  try {
+    return JSON.parse(String(value || "").trim());
+  } catch {
+    return undefined;
+  }
+}
+
+function parseTextStats(value = "") {
+  const stats = {};
+  for (const line of String(value || "").split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+    const match = trimmed.match(/^(.+?)(?:\s{2,}|\t+|:\s+)([-+]?\d+(?:\.\d+)?)(?:\s|$)/);
+    if (!match) {
+      continue;
+    }
+    const key = match[1]
+      .trim()
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "_")
+      .replace(/^_+|_+$/g, "");
+    if (!key) {
+      continue;
+    }
+    const number = Number(match[2]);
+    stats[key] = Number.isFinite(number) ? number : match[2];
+  }
+  return stats;
+}
+
+function collectCompilerCacheTool({ command, attempts, cwd, runCommand }) {
+  let lastError;
+  for (const attempt of attempts) {
+    const args = attempt.args || [];
+    const expectedFormat = attempt.format || "";
+    try {
+      const output = runCommand(command, args, { cwd, timeoutMs: 5000 });
+      const text = String(output || "").trim();
+      const jsonStats = parseJsonDiagnostics(text);
+      if (jsonStats) {
+        return {
+          available: true,
+          command,
+          args,
+          format: "json",
+          stats: jsonStats,
+          rawBytes: Buffer.byteLength(text, "utf8"),
+          parseError: "",
+        };
+      }
+      const textStats = parseTextStats(text);
+      return {
+        available: true,
+        command,
+        args,
+        format: "text",
+        stats: textStats,
+        rawBytes: Buffer.byteLength(text, "utf8"),
+        parseError: Object.keys(textStats).length ? "" : `${expectedFormat || "stats"} output was not parseable`,
+      };
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  return {
+    available: false,
+    command,
+    error: lastError?.code || lastError?.message || "stats command failed",
+  };
+}
+
+export function collectCompilerCacheDiagnostics({
+  cwd = process.cwd(),
+  runCommand = defaultDiagnosticCommandRunner,
+  env = process.env,
+} = {}) {
+  const resolvedCwd = path.resolve(cwd);
+  const ccache = collectCompilerCacheTool({
+    command: "ccache",
+    attempts: [
+      { args: ["--show-stats", "--json"], format: "json" },
+      { args: ["--show-stats"], format: "text" },
+    ],
+    cwd: resolvedCwd,
+    runCommand,
+  });
+  ccache.logStats = env.CCACHE_STATSLOG
+    ? collectCompilerCacheTool({
+        command: "ccache",
+        attempts: [
+          {
+            args: ["--print-log-stats", "--format", "json"],
+            format: "json",
+          },
+        ],
+        cwd: resolvedCwd,
+        runCommand,
+      })
+    : {
+        available: false,
+        command: "ccache",
+        error: "CCACHE_STATSLOG is not configured",
+      };
+  return {
+    ccache,
+    sccache: collectCompilerCacheTool({
+      command: "sccache",
+      attempts: [
+        { args: ["--show-stats", "--stats-format", "json"], format: "json" },
+      ],
+      cwd: resolvedCwd,
+      runCommand,
+    }),
+  };
+}
+
+function unavailableMetric(unit, reason, source = null, evidenceRoot = null) {
+  return {
+    status: "unavailable",
+    unit,
+    value: null,
+    source,
+    reason,
+    evidenceRoot,
+  };
+}
+
+function notApplicableMetric(unit, reason) {
+  return {
+    status: "not-applicable",
+    unit,
+    value: null,
+    reason,
+  };
+}
+
+function observedMetric(unit, value, source, evidenceRoot) {
+  return {
+    status: "observed",
+    unit,
+    value: Number(value),
+    source,
+    evidenceRoot,
+  };
+}
+
+function numericTotal(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (value && typeof value === "object") {
+    return Object.values(value).reduce((sum, entry) => sum + numericTotal(entry), 0);
+  }
+  return 0;
+}
+
+function cacheStatsCount(stats, names) {
+  return names.reduce((sum, name) => sum + numericTotal(stats?.[name]), 0);
+}
+
+function compilerCacheObservation(compilerCaches, compilerCachePreparation) {
+  const preparationValid =
+    compilerCachePreparation?.contract ===
+      "kungfu-buildchain-compiler-cache-preparation" &&
+    compilerCachePreparation?.provider === "sccache" &&
+    compilerCachePreparation?.status === "prepared" &&
+    compilerCachePreparation?.action?.statsReset === true &&
+    /^sha256:[0-9a-f]{64}$/.test(compilerCachePreparation?.root || "");
+  const sccache = compilerCaches?.sccache;
+  if (preparationValid && sccache?.available && sccache.stats) {
+    const stats = sccache.stats.stats || sccache.stats;
+    return {
+      provider: "sccache",
+      producer: "sccache",
+      source: "sccache-current-run-stats",
+      stats,
+      hits: cacheStatsCount(stats, [
+        "cache_hits",
+        "cache_hit",
+        "cache_hits_count",
+        "cache_hit_count",
+      ]),
+      misses: cacheStatsCount(stats, [
+        "cache_misses",
+        "cache_miss",
+        "cache_misses_count",
+        "cache_miss_count",
+      ]),
+    };
+  }
+  const logStats = compilerCaches?.ccache?.logStats;
+  if (logStats?.available && logStats.stats) {
+    return {
+      provider: "ccache",
+      producer: "ccache",
+      source: "ccache-current-run-stats-log",
+      stats: logStats.stats,
+      hits: cacheStatsCount(logStats.stats, [
+        "direct_cache_hit",
+        "preprocessed_cache_hit",
+      ]),
+      misses: cacheStatsCount(logStats.stats, ["cache_miss"]),
+    };
+  }
+  return {
+    provider: sccache?.available ? "sccache" : "compiler-cache",
+    producer: "unavailable",
+    source: sccache?.available ? "sccache-cumulative-stats" : "compiler-cache-diagnostics",
+    stats: undefined,
+    hits: 0,
+    misses: 0,
+  };
+}
+
+function compilerCacheOutcome(observation) {
+  if (!observation?.stats) return "unavailable";
+  if (observation.hits > 0 && observation.misses > 0) return "partial";
+  if (observation.hits > 0) return "hit";
+  if (observation.misses > 0) return "miss";
+  return "bypassed";
+}
+
+export function createStructuredCacheEvidence({
+  sourceCheckout,
+  compilerCaches,
+  compilerCachePreparation,
+  platform,
+  env = process.env,
+}) {
+  const repository = env.GITHUB_REPOSITORY || sourceCheckout?.repository || "unknown/unknown";
+  const sourceCommit =
+    env.BUILDCHAIN_SOURCE_SHA ||
+    sourceCheckout?.source?.sha ||
+    sourceCheckout?.verification?.head ||
+    "unknown";
+  const sourceTree =
+    env.BUILDCHAIN_SOURCE_TREE_SHA ||
+    sourceCheckout?.source?.treeSha ||
+    sourceCheckout?.verification?.tree ||
+    "";
+  const runtimeCommit = env.BUILDCHAIN_RUNTIME_SHA || "";
+  const policyRoot = env.SHIFU_CACHE_PROFILE_DIGEST || "";
+  const bindings = {
+    sourceCommit,
+    ...(sourceTree ? { sourceTree } : {}),
+    ...(runtimeCommit ? { runtimeCommit } : {}),
+    ...(env.BUILDCHAIN_DEPENDENCY_LOCK_ROOT
+      ? { dependencyLockRoot: env.BUILDCHAIN_DEPENDENCY_LOCK_ROOT }
+      : {}),
+    ...(env.BUILDCHAIN_TOOLCHAIN_ROOT
+      ? { toolchainRoot: env.BUILDCHAIN_TOOLCHAIN_ROOT }
+      : {}),
+    ...(env.BUILDCHAIN_CACHE_POLICY_ROOT
+      ? { policyRoot: env.BUILDCHAIN_CACHE_POLICY_ROOT }
+      : {}),
+    ...(policyRoot ? { cacheProfileRoot: policyRoot } : {}),
+    ...(compilerCachePreparation?.root
+      ? { compilerCachePreparationRoot: compilerCachePreparation.root }
+      : {}),
+  };
+  const operations = [];
+  if (sourceCheckout) {
+    const evidenceRoot = cacheEvidenceDigest(sourceCheckout);
+    const cache = sourceCheckout.cache || {};
+    const outcome = cache.hit
+      ? "hit"
+      : cache.attempted === false || sourceCheckout.policy?.mode === "off"
+        ? "bypassed"
+        : cache.fallbackUsed
+          ? "miss"
+          : "unavailable";
+    operations.push(
+      createCacheOperationReceipt({
+        operationId: `source-checkout:${platform}`,
+        operation: "restore",
+        provider: `git-${cache.transport || "unknown"}`,
+        producer: "kungfu-systems/buildchain",
+        platform,
+        cacheKey: sourceCommit,
+        cacheRoot:
+          sourceCheckout.policy?.referenceRepository?.display ||
+          sourceCheckout.policy?.mirror?.display ||
+          `transport:${cache.transport || "unknown"}`,
+        outcome,
+        bindings,
+        metrics: {
+          lookupDuration:
+            cache.attempted === false
+              ? notApplicableMetric("ms", "source checkout cache was disabled")
+              : observedMetric(
+                  "ms",
+                  cache.lookupDurationMs || 0,
+                  "locked-source-checkout",
+                  evidenceRoot,
+                ),
+          restoreDuration: cache.hit
+            ? observedMetric(
+                "ms",
+                cache.restoreDurationMs || 0,
+                "locked-source-checkout",
+                evidenceRoot,
+              )
+            : notApplicableMetric(
+                "ms",
+                "no cache payload was admitted for restore",
+              ),
+          saveDuration: notApplicableMetric(
+            "ms",
+            "locked source checkout does not save cache state",
+          ),
+          restoredBytes:
+            cache.restoredBytesStatus === "observed"
+              ? observedMetric(
+                  "bytes",
+                  cache.restoredBytes || 0,
+                  cache.restoredBytesMethod || "git-object-store-delta",
+                  evidenceRoot,
+                )
+              : unavailableMetric(
+                  "bytes",
+                  "checkout provider did not expose restored byte evidence",
+                  "locked-source-checkout",
+                  evidenceRoot,
+                ),
+          writtenBytes: notApplicableMetric(
+            "bytes",
+            "locked source checkout does not save cache state",
+          ),
+          savedTime: unavailableMetric(
+            "ms",
+            "checkout provider did not report a measured cold-path comparison",
+            "locked-source-checkout",
+            evidenceRoot,
+          ),
+        },
+        evidence: {
+          kind: "locked-source-checkout",
+          root: evidenceRoot,
+          locator: ".buildchain/diagnostics/source-checkout.json",
+        },
+      }),
+    );
+  }
+  const compilerObservation = compilerCacheObservation(
+    compilerCaches,
+    compilerCachePreparation,
+  );
+  const compilerEvidenceRoot = cacheEvidenceDigest({
+    compilerCaches: compilerCaches || {},
+    compilerCachePreparation: compilerCachePreparation || null,
+  });
+  const compilerMetricReason = compilerObservation.stats
+    ? `${compilerObservation.provider} current-run stats do not expose this metric`
+    : compilerObservation.provider === "sccache"
+      ? "sccache stats were not admitted without a current-run reset preparation receipt"
+      : "compiler cache current-run stats were unavailable";
+  operations.push(
+    createCacheOperationReceipt({
+      operationId: `compiler-cache:${platform}`,
+      operation: "restore",
+      provider: compilerObservation.provider,
+      producer: compilerObservation.producer,
+      platform,
+      cacheKey: compilerCachePreparation?.root || policyRoot || null,
+      cacheRoot: policyRoot || null,
+      outcome: compilerCacheOutcome(compilerObservation),
+      bindings,
+      metrics: {
+        lookupDuration: unavailableMetric(
+          "ms",
+          compilerMetricReason,
+          compilerObservation.source,
+          compilerEvidenceRoot,
+        ),
+        restoreDuration: unavailableMetric(
+          "ms",
+          compilerMetricReason,
+          compilerObservation.source,
+          compilerEvidenceRoot,
+        ),
+        saveDuration: unavailableMetric(
+          "ms",
+          compilerMetricReason,
+          compilerObservation.source,
+          compilerEvidenceRoot,
+        ),
+        restoredBytes: unavailableMetric(
+          "bytes",
+          compilerMetricReason,
+          compilerObservation.source,
+          compilerEvidenceRoot,
+        ),
+        writtenBytes: unavailableMetric(
+          "bytes",
+          compilerMetricReason,
+          compilerObservation.source,
+          compilerEvidenceRoot,
+        ),
+        savedTime: unavailableMetric(
+          "ms",
+          compilerMetricReason,
+          compilerObservation.source,
+          compilerEvidenceRoot,
+        ),
+      },
+      evidence: {
+        kind: "compiler-cache-diagnostics",
+        root: compilerEvidenceRoot,
+        locator: ".buildchain/artifacts/<platform>/diagnostics.json#compilerCaches",
+      },
+    }),
+  );
+  return createCacheEvidenceSet({
+    repository,
+    sourceCommit,
+    sourceTree,
+    runtimeCommit,
+    platform,
+    operations,
+  });
+}
+
+export function collectCacheDiagnostics({ cwd = process.cwd(), cacheDirs = [], runCommand = defaultDiagnosticCommandRunner } = {}) {
+  const resolvedCwd = path.resolve(cwd);
+  return {
+    packageManager: (() => {
+      try {
+        return detectPackageManager(resolvedCwd);
+      } catch (error) {
+        return { name: "unknown", error: error.message };
+      }
+    })(),
+    workspace: (() => {
+      try {
+        return getWorkspaceInfo(resolvedCwd);
+      } catch (error) {
+        return { error: error.message };
+      }
+    })(),
+    dirs: fileStats(resolvedCwd, cacheDirs),
+    compilerCaches: collectCompilerCacheDiagnostics({ cwd: resolvedCwd, runCommand }),
+  };
+}
+
+export function collectGitDiagnostics({ cwd = process.cwd() } = {}) {
+  return {
+    repository: gitField(cwd, ["config", "--get", "remote.origin.url"]),
+    head: gitField(cwd, ["rev-parse", "HEAD"]),
+    ref: gitField(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]),
+    dirty: gitField(cwd, ["status", "--short"]) !== "",
+  };
+}
+
+export function redactDiagnosticsValue(key, value, pattern = DEFAULT_SECRET_KEY_PATTERN) {
+  if (pattern.test(String(key || ""))) {
+    return "[REDACTED]";
+  }
+  return value;
+}
+
+function processCommandFromLine(commandLine = "", fallback = "") {
+  const firstToken = shellishTokens(commandLine)[0] || fallback;
+  return String(firstToken || "")
+    .replace(/[()]/g, "")
+    .split(/[\\/]/)
+    .pop();
+}
+
+function normalizeProcessRows({ rootPid, platform, rows = [] }) {
+  const byParent = new Map();
+  const byPid = new Map();
+  for (const row of rows) {
+    byPid.set(row.pid, row);
+    byParent.set(row.ppid, [...(byParent.get(row.ppid) || []), row]);
+  }
+  const seen = new Set();
+  const stack = [String(rootPid)];
+  const processes = [];
+  while (stack.length) {
+    const current = stack.pop();
+    for (const child of byParent.get(current) || []) {
+      if (seen.has(child.pid)) {
+        continue;
+      }
+      seen.add(child.pid);
+      processes.push(child);
+      stack.push(child.pid);
+    }
+  }
+  return { rootPid: String(rootPid), platform, rootProcess: byPid.get(String(rootPid)) || undefined, processes };
+}
+
+function collectWindowsProcessRows({ cwd, runCommand }) {
+  const script = [
+    "$ErrorActionPreference = 'Stop';",
+    "Get-CimInstance Win32_Process |",
+    "Select-Object ProcessId,ParentProcessId,Name,CommandLine |",
+    "ConvertTo-Json -Compress",
+  ].join(" ");
+  const errors = [];
+  let output = "";
+  for (const command of ["powershell.exe", "powershell", "pwsh"]) {
+    try {
+      output = runCommand(command, ["-NoProfile", "-NonInteractive", "-Command", script], {
+        cwd,
+        timeoutMs: 5000,
+      });
+      break;
+    } catch (error) {
+      errors.push(`${command}: ${error.message}`);
+    }
+  }
+  if (!output) {
+    throw new Error(`Windows process sampler unavailable: ${errors.join("; ") || "no process query output"}`);
+  }
+  const parsed = JSON.parse(String(output || "[]"));
+  const entries = Array.isArray(parsed) ? parsed : [parsed];
+  return entries.map((entry) => {
+    const commandLine = redactCommandLine(entry.CommandLine || entry.Name || "");
+    return {
+      pid: String(entry.ProcessId || ""),
+      ppid: String(entry.ParentProcessId || ""),
+      cpu: 0,
+      command: processCommandFromLine(commandLine, entry.Name || ""),
+      commandLine,
+    };
+  }).filter((entry) => entry.pid && entry.ppid);
+}
+
+export function collectProcessTreeSnapshot({
+  rootPid = process.pid,
+  cwd = process.cwd(),
+  platform = process.platform,
+  runCommand = defaultDiagnosticCommandRunner,
+} = {}) {
+  const pid = String(rootPid || process.pid);
+  if (platform === "win32") {
+    try {
+      return normalizeProcessRows({
+        rootPid: pid,
+        platform,
+        rows: collectWindowsProcessRows({ cwd, runCommand }),
+      });
+    } catch (error) {
+      return {
+        rootPid: pid,
+        platform,
+        processes: [],
+        samplerUnavailable: true,
+        samplerUnavailableReason: error.message,
+      };
+    }
+  }
+  let lines = [];
+  try {
+    lines = runCommand("ps", ["-axo", "pid=,ppid=,pcpu=,args="], {
+      cwd,
+      timeoutMs: 5000,
+    }).split(/\r?\n/).filter(Boolean);
+  } catch (error) {
+    return {
+      rootPid: pid,
+      platform,
+      processes: [],
+      samplerUnavailable: true,
+      samplerUnavailableReason: error.message,
+    };
+  }
+  const rows = lines.map((line) => {
+    const match = line.trim().match(/^(\d+)\s+(\d+)\s+([0-9.]+)\s+(.*)$/);
+    const args = match?.[4] || "";
+    const commandLine = redactCommandLine(args);
+    return match
+      ? {
+          pid: match[1],
+          ppid: match[2],
+          cpu: Number(match[3]),
+          command: processCommandFromLine(commandLine),
+          commandLine,
+        }
+      : undefined;
+  }).filter(Boolean);
+  return normalizeProcessRows({ rootPid: pid, platform, rows });
+}
+
+export function classifyProcessCommand(command = "") {
+  const name = String(command || "").split(/[\\/]/).pop().toLowerCase();
+  if (/^(ccache|sccache)$/.test(name)) {
+    return "cache";
+  }
+  if (/^(clang|clang\+\+|gcc|g\+\+|cc|c\+\+|cl)(\.exe)?$/.test(name)) {
+    return "compiler";
+  }
+  if (/^(ld|lld|lld-link|link)(\.exe)?$/.test(name)) {
+    return "linker";
+  }
+  if (/^(ar|llvm-ar|libtool|ranlib)(\.exe)?$/.test(name)) {
+    return "archive";
+  }
+  if (/^(make|ninja|cmake|msbuild|vcbuild|gyp-mac-tool)(\.exe)?$/.test(name)) {
+    return "build-tool";
+  }
+  if (/^(node|python|python3|bash|sh|pwsh|powershell)(\.exe)?$/.test(name)) {
+    return "script";
+  }
+  return "other";
+}
+
+function firstPositiveInteger(value) {
+  const number = Number(value);
+  return Number.isInteger(number) && number > 0 ? number : 0;
+}
+
+function commandName(value = "") {
+  return String(value || "")
+    .replace(/[()]/g, "")
+    .replace(/\.exe$/i, "")
+    .split(/[\\/]/)
+    .pop()
+    .toLowerCase();
+}
+
+function detectParallelismFromTokens(tokens = []) {
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = String(tokens[index] || "");
+    const inlineMatch = token.match(/^(?:-j|--jobs=|--parallel=|-jobs|\/m:|\/maxcpucount:|-m:)(\d+)$/i);
+    if (inlineMatch) {
+      return { value: Number(inlineMatch[1]), source: "command", token };
+    }
+    if (/^(?:-j|--jobs|--parallel|-jobs)$/i.test(token)) {
+      const value = firstPositiveInteger(tokens[index + 1]);
+      if (value) {
+        return { value, source: "command", token: `${token} ${tokens[index + 1]}` };
+      }
+    }
+  }
+  return { value: 0, source: "", token: "" };
+}
+
+function shellishTokens(command = "") {
+  return String(command || "").match(/"[^"]+"|'[^']+'|\S+/g)?.map((token) => token.replace(/^['"]|['"]$/g, "")) || [];
+}
+
+function redactCommandLine(commandLine = "", pattern = DEFAULT_SECRET_KEY_PATTERN) {
+  const tokens = shellishTokens(commandLine);
+  let redactNext = false;
+  return tokens.map((token) => {
+    const withUrlUserInfo = token.replace(/:\/\/[^/\s:@]+:[^/\s@]+@/g, "://[REDACTED]@");
+    if (redactNext) {
+      redactNext = false;
+      return "[REDACTED]";
+    }
+    const assignment = withUrlUserInfo.match(/^([^=\s]+)=(.*)$/);
+    if (assignment && pattern.test(assignment[1])) {
+      return `${assignment[1]}=[REDACTED]`;
+    }
+    const inlineOption = withUrlUserInfo.match(/^(--?[^=\s]+)=(.*)$/);
+    if (inlineOption && pattern.test(inlineOption[1])) {
+      return `${inlineOption[1]}=[REDACTED]`;
+    }
+    if (/^--?/.test(withUrlUserInfo) && pattern.test(withUrlUserInfo)) {
+      redactNext = true;
+    }
+    return withUrlUserInfo;
+  }).join(" ");
+}
+
+function commandLineFromProcess(entry = {}) {
+  return [
+    entry.commandLine,
+    Array.isArray(entry.args) ? entry.args.join(" ") : entry.args,
+    Array.isArray(entry.argv) ? entry.argv.join(" ") : "",
+    entry.command,
+  ].find((value) => String(value || "").trim()) || "";
+}
+
+function parallelismCandidate({ value, source, token, entry, sample }) {
+  return {
+    value,
+    source,
+    token,
+    pid: entry?.pid ? String(entry.pid) : "",
+    command: commandName(entry?.command || shellishTokens(commandLineFromProcess(entry))[0] || ""),
+    commandLine: commandLineFromProcess(entry),
+    timestamp: sample?.timestamp || "",
+  };
+}
+
+export function detectRequestedParallelism({
+  command = "",
+  args = [],
+  env = process.env,
+} = {}) {
+  const commandTokens = [
+    ...shellishTokens(command),
+    ...(Array.isArray(args) ? args.map((entry) => String(entry)) : shellishTokens(args)),
+  ];
+  const commandParallelism = detectParallelismFromTokens(commandTokens);
+  if (commandParallelism.value) {
+    return commandParallelism;
+  }
+
+  const explicitEnvKeys = [
+    "BUILDCHAIN_REQUESTED_PARALLELISM",
+    "CMAKE_BUILD_PARALLEL_LEVEL",
+    "NINJA_STATUS_JOBS",
+    "npm_config_jobs",
+  ];
+  for (const key of explicitEnvKeys) {
+    const value = firstPositiveInteger(env?.[key]);
+    if (value) {
+      return { value, source: `env:${key}`, token: key };
+    }
+  }
+
+  const makeflags = detectParallelismFromTokens(shellishTokens(env?.MAKEFLAGS || ""));
+  if (makeflags.value) {
+    return { ...makeflags, source: "env:MAKEFLAGS" };
+  }
+
+  return { value: 0, source: "", token: "" };
+}
+
+export function detectRequestedParallelismFromProcessSamples(samples = []) {
+  const candidates = [];
+  const buildToolNames = new Set(["make", "ninja", "cmake", "msbuild", "xcodebuild"]);
+  for (const sample of Array.isArray(samples) ? samples : []) {
+    for (const entry of Array.isArray(sample?.processes) ? sample.processes : []) {
+      const command = commandName(entry.command || shellishTokens(commandLineFromProcess(entry))[0] || "");
+      if (!buildToolNames.has(command)) {
+        continue;
+      }
+      const tokens = shellishTokens(commandLineFromProcess(entry));
+      const detected = detectParallelismFromTokens(tokens);
+      if (detected.value) {
+        candidates.push(parallelismCandidate({
+          ...detected,
+          source: "process-tree",
+          entry,
+          sample,
+        }));
+      }
+    }
+  }
+  candidates.sort((left, right) => right.value - left.value || left.command.localeCompare(right.command));
+  return {
+    value: candidates[0]?.value || 0,
+    source: candidates[0] ? "process-tree" : "",
+    token: candidates[0]?.token || "",
+    evidence: candidates[0] || undefined,
+    candidates,
+  };
+}
+
+export function summarizeProcessSamples({
+  samples = [],
+  requestedParallelism = 0,
+  command = "",
+  args = [],
+  env = process.env,
+  activeCpuThreshold = 0.1,
+} = {}) {
+  const normalizedSamples = Array.isArray(samples) ? samples : [];
+  const unavailableSamples = normalizedSamples.filter((sample) => sample?.samplerUnavailable);
+  const activeCounts = [];
+  const cpuTotals = [];
+  const categoryMax = {};
+  const commandStats = new Map();
+  const threshold = Number(activeCpuThreshold || 0);
+
+  for (const sample of normalizedSamples) {
+    const processes = Array.isArray(sample?.processes) ? sample.processes : [];
+    const active = processes.filter((entry) => Number(entry.cpu || 0) >= threshold);
+    activeCounts.push(active.length);
+    cpuTotals.push(processes.reduce((sum, entry) => sum + Number(entry.cpu || 0), 0));
+
+    const categoryCounts = {};
+    for (const entry of active) {
+      const command = path.basename(String(entry.command || "unknown"));
+      const category = classifyProcessCommand(command);
+      categoryCounts[category] = (categoryCounts[category] || 0) + 1;
+      const stats = commandStats.get(command) || {
+        command,
+        category,
+        samples: 0,
+        maxConcurrent: 0,
+        maxCpu: 0,
+      };
+      stats.samples += 1;
+      stats.maxCpu = Math.max(stats.maxCpu, Number(entry.cpu || 0));
+      commandStats.set(command, stats);
+    }
+
+    const commandCounts = {};
+    for (const entry of active) {
+      const command = path.basename(String(entry.command || "unknown"));
+      commandCounts[command] = (commandCounts[command] || 0) + 1;
+    }
+    for (const [command, count] of Object.entries(commandCounts)) {
+      const stats = commandStats.get(command);
+      if (stats) {
+        stats.maxConcurrent = Math.max(stats.maxConcurrent, count);
+      }
+    }
+    for (const [category, count] of Object.entries(categoryCounts)) {
+      categoryMax[category] = Math.max(categoryMax[category] || 0, count);
+    }
+  }
+
+  const observedMax = activeCounts.length ? Math.max(...activeCounts) : 0;
+  const observedAverage = activeCounts.length
+    ? activeCounts.reduce((sum, value) => sum + value, 0) / activeCounts.length
+    : 0;
+  const totalCpuMax = cpuTotals.length ? Math.max(...cpuTotals) : 0;
+  const totalCpuAverage = cpuTotals.length
+    ? cpuTotals.reduce((sum, value) => sum + value, 0) / cpuTotals.length
+    : 0;
+  const explicitRequested = firstPositiveInteger(requestedParallelism);
+  const commandParallelism = detectRequestedParallelism({ command, args, env });
+  const sampledParallelism = detectRequestedParallelismFromProcessSamples(normalizedSamples);
+  const requested = explicitRequested || sampledParallelism.value || commandParallelism.value;
+  const requestedSource = explicitRequested
+    ? "explicit"
+    : sampledParallelism.source || commandParallelism.source;
+  const requestedEvidence = explicitRequested
+    ? { value: explicitRequested, source: "explicit" }
+    : sampledParallelism.evidence || (commandParallelism.value ? commandParallelism : undefined);
+
+  return {
+    schemaVersion: 1,
+    contract: BUILDCHAIN_PROCESS_SAMPLE_SUMMARY_CONTRACT,
+    sampleCount: normalizedSamples.length,
+    sampler: {
+      unavailable: unavailableSamples.length > 0,
+      unavailableSamples: unavailableSamples.length,
+      unavailableReasons: [...new Set(
+        unavailableSamples
+          .map((sample) => String(sample.samplerUnavailableReason || "").trim())
+          .filter(Boolean),
+      )].slice(0, 5),
+    },
+    activeCpuThreshold: threshold,
+    requestedParallelism: requested,
+    requestedParallelismSource: requestedSource,
+    requestedParallelismEvidence: requestedEvidence || {},
+    requestedParallelismCandidates: sampledParallelism.candidates.slice(0, 10),
+    observedConcurrency: {
+      max: observedMax,
+      average: Number(observedAverage.toFixed(2)),
+      ratioToRequestedMax: requested > 0 ? Number((observedMax / requested).toFixed(3)) : 0,
+    },
+    cpu: {
+      totalMax: Number(totalCpuMax.toFixed(2)),
+      totalAverage: Number(totalCpuAverage.toFixed(2)),
+    },
+    categories: Object.fromEntries(Object.entries(categoryMax).sort(([left], [right]) => left.localeCompare(right))),
+    topCommands: [...commandStats.values()]
+      .sort((left, right) => right.maxConcurrent - left.maxConcurrent || right.maxCpu - left.maxCpu)
+      .slice(0, 10),
+  };
+}
+
+export function startProcessSampler({
+  rootPid = process.pid,
+  intervalMs = 15000,
+  label = "",
+  command = "",
+  args = [],
+  env = process.env,
+  requestedParallelism = 0,
+  onSample = () => undefined,
+  cwd = process.cwd(),
+} = {}) {
+  const samples = [];
+  const startedAt = Date.now();
+  const explicitRequested = firstPositiveInteger(requestedParallelism);
+  const detectedParallelism = detectRequestedParallelism({ command, args, env });
+  const requested = explicitRequested || detectedParallelism.value;
+  const sample = () => {
+    const snapshot = {
+      timestamp: new Date().toISOString(),
+      label,
+      elapsedMs: Date.now() - startedAt,
+      requestedParallelism: requested,
+      requestedParallelismSource: explicitRequested ? "explicit" : detectedParallelism.source,
+      ...collectProcessTreeSnapshot({ rootPid, cwd }),
+    };
+    samples.push(snapshot);
+    onSample(snapshot);
+    return snapshot;
+  };
+  sample();
+  const interval = Math.max(1000, Number(intervalMs || 15000));
+  const earlyDelay = Math.min(1000, interval);
+  const earlyTimer = interval > earlyDelay ? setTimeout(sample, earlyDelay) : undefined;
+  const timer = setInterval(sample, interval);
+  return {
+    samples,
+    stop() {
+      if (earlyTimer) {
+        clearTimeout(earlyTimer);
+      }
+      clearInterval(timer);
+      return samples;
+    },
+  };
+}
+
+export function createDiagnosticsArtifact({
+  cwd = process.cwd(),
+  logPath = "",
+  artifactPaths = [],
+  cacheDirs = [],
+  lifecycleObservability = undefined,
+  processSamples = [],
+  processSummary = undefined,
+  requestedParallelism = 0,
+  sourceCheckout = undefined,
+  compilerCachePreparation = undefined,
+  links = {},
+} = {}) {
+  const resolvedCwd = path.resolve(cwd);
+  const events = logPath ? readBuildchainLogEvents(logPath) : [];
+  const loadedConfig = loadBuildchainConfig(resolvedCwd);
+  const nativeProfile = getNativeDiagnosticsProfile(loadedConfig);
+  const native = collectNativeDiagnostics({ cwd: resolvedCwd, profile: nativeProfile });
+  const cache = collectCacheDiagnostics({ cwd: resolvedCwd, cacheDirs });
+  const compilerCaches = native.compilerCaches || cache.compilerCaches || {};
+  const platform =
+    links.platformId ||
+    process.env.BUILDCHAIN_PLATFORM_ID ||
+    `${process.env.RUNNER_OS || os.platform()}-${process.env.RUNNER_ARCH || os.arch()}`;
+  return {
+    schemaVersion: 1,
+    contract: BUILDCHAIN_DIAGNOSTICS_CONTRACT,
+    generatedAt: new Date().toISOString(),
+    cwd: resolvedCwd,
+    buildchain: collectBuildchainDiagnostics({ cwd: resolvedCwd, artifactPaths }),
+    runner: collectRunnerDiagnostics(),
+    tools: collectToolDiagnostics({ cwd: resolvedCwd }),
+    cache,
+    native,
+    compilerCaches,
+    cacheEvidence: createStructuredCacheEvidence({
+      sourceCheckout,
+      compilerCaches,
+      compilerCachePreparation,
+      platform,
+    }),
+    nativeCacheDirs: native.cacheDirs || [],
+    git: collectGitDiagnostics({ cwd: resolvedCwd }),
+    lifecycleObservability: lifecycleObservability || summarizeLifecycleObservability({ events, logPath }),
+    process: processSummary || summarizeProcessSamples({ samples: processSamples, requestedParallelism }),
+    ...(sourceCheckout ? { sourceCheckout } : {}),
+    ...(compilerCachePreparation ? { compilerCachePreparation } : {}),
+    links,
+  };
+}
+
+export function writeDiagnosticsArtifact(filePath, diagnostics) {
+  if (!filePath) {
+    return "";
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(diagnostics, null, 2)}\n`);
+  return filePath;
+}
+
+export function readDiagnosticsArtifact(filePath) {
+  return safeReadJson(filePath);
+}
+
+function sumLifecycleDurationMs(stages = {}) {
+  return Object.values(stages).reduce((sum, entry) => sum + Number(entry?.durationMs || 0), 0);
+}
+
+function stageDurationMs(stages = {}, stage) {
+  return Math.round(Number(stages?.[stage]?.durationMs || 0));
+}
+
+function formatDiagnosticsDurationMs(value) {
+  const durationMs = Math.round(Number(value || 0));
+  if (!Number.isFinite(durationMs) || durationMs <= 0) {
+    return "-";
+  }
+  if (durationMs < 1000) {
+    return `${durationMs}ms`;
+  }
+  if (durationMs < 60000) {
+    const seconds = durationMs / 1000;
+    return `${seconds < 10 ? seconds.toFixed(1).replace(/\.0$/, "") : Math.round(seconds)}s`;
+  }
+  const minutes = Math.floor(durationMs / 60000);
+  const seconds = Math.round((durationMs % 60000) / 1000);
+  return seconds ? `${minutes}m${seconds}s` : `${minutes}m`;
+}
+
+function compactProcessSummary(process = {}) {
+  const observedConcurrency = process?.observedConcurrency || {};
+  const topCommands = Array.isArray(process?.topCommands)
+    ? process.topCommands.slice(0, 3).map((entry) => ({
+        command: entry.command || "",
+        category: entry.category || "",
+        maxConcurrent: Number(entry.maxConcurrent || 0),
+        maxCpu: Number(entry.maxCpu || 0),
+      }))
+    : [];
+  return {
+    requestedParallelism: Number(process?.requestedParallelism || 0),
+    requestedParallelismSource: process?.requestedParallelismSource || "",
+    observedConcurrencyMax: Number(observedConcurrency.max || 0),
+    ratioToRequestedMax: Number(observedConcurrency.ratioToRequestedMax || 0),
+    sampleCount: Number(process?.sampleCount || 0),
+    categories: process?.categories || {},
+    topCommands,
+  };
+}
+
+function formatDiagnosticsProcessValue(value) {
+  const number = Number(value || 0);
+  return number > 0 ? String(number) : "-";
+}
+
+function compactRunnerDetails(runner = {}) {
+  return {
+    os: {
+      platform: runner.os?.platform || "",
+      release: runner.os?.release || "",
+      arch: runner.os?.arch || "",
+      type: runner.os?.type || "",
+    },
+    github: {
+      actions: Boolean(runner.github?.actions),
+      runnerOs: runner.github?.runnerOs || "",
+      runnerArch: runner.github?.runnerArch || "",
+      runnerName: runner.github?.runnerName || "",
+    },
+    cpu: {
+      logicalCount: Number(runner.cpu?.logicalCount || 0),
+      model: runner.cpu?.model || "",
+      loadAverage: Array.isArray(runner.cpu?.loadAverage)
+        ? runner.cpu.loadAverage.map((entry) => Number(entry || 0))
+        : [],
+    },
+    memory: {
+      totalBytes: Number(runner.memory?.totalBytes || 0),
+      freeBytes: Number(runner.memory?.freeBytes || 0),
+    },
+    uptimeSeconds: Number(runner.uptimeSeconds || 0),
+  };
+}
+
+function compactToolSummary(...toolSets) {
+  const merged = {};
+  for (const toolSet of toolSets) {
+    for (const [name, details] of Object.entries(toolSet || {})) {
+      merged[name] = details || {};
+    }
+  }
+  const versions = {};
+  const missing = [];
+  for (const [name, details] of Object.entries(merged).sort(([left], [right]) => left.localeCompare(right))) {
+    const version = String(details?.version || "").trim();
+    if (version) {
+      versions[name] = version;
+    } else {
+      missing.push(name);
+    }
+  }
+  return {
+    checked: Object.keys(merged).length,
+    available: Object.keys(versions).length,
+    missing,
+    versions,
+  };
+}
+
+function compactStatsObject(stats = {}, limit = 12) {
+  const entries = [];
+  const visit = (prefix, value) => {
+    if (entries.length >= limit || value === undefined || value === null) {
+      return;
+    }
+    if (typeof value === "number" || typeof value === "string" || typeof value === "boolean") {
+      entries.push([prefix, value]);
+      return;
+    }
+    if (Array.isArray(value) || typeof value !== "object") {
+      return;
+    }
+    for (const [key, nested] of Object.entries(value).sort(([left], [right]) => left.localeCompare(right))) {
+      visit(prefix ? `${prefix}.${key}` : key, nested);
+      if (entries.length >= limit) {
+        break;
+      }
+    }
+  };
+  visit("", stats);
+  return Object.fromEntries(entries);
+}
+
+function compactCompilerCacheSummary(compilerCaches = {}) {
+  return Object.fromEntries(
+    Object.entries(compilerCaches || {})
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([name, details]) => [name, {
+        available: Boolean(details?.available),
+        format: details?.format || "",
+        rawBytes: Number(details?.rawBytes || 0),
+        error: details?.error || "",
+        stats: compactStatsObject(details?.stats || {}),
+      }]),
+  );
+}
+
+function compactCacheSummary(cache = {}, native = {}) {
+  const workspace = cache.workspace || {};
+  const workspacePackages = workspace && !workspace.error && !Array.isArray(workspace) && typeof workspace === "object"
+    ? Object.keys(workspace).length
+    : 0;
+  return {
+    packageManager: cache.packageManager || {},
+    workspacePackages,
+    workspaceError: workspace.error || "",
+    dirs: Array.isArray(cache.dirs)
+      ? cache.dirs.map((entry) => ({
+          path: entry.path || "",
+          exists: Boolean(entry.exists),
+          type: entry.type || "",
+          bytes: Number(entry.bytes || 0),
+        }))
+      : [],
+    compilerCaches: compactCompilerCacheSummary({
+      ...(cache.compilerCaches || {}),
+      ...(native.compilerCaches || {}),
+    }),
+    nativeCacheDirs: Array.isArray(native.cacheDirs)
+      ? native.cacheDirs.map((entry) => ({
+          path: entry.path || "",
+          exists: Boolean(entry.exists),
+          type: entry.type || "",
+          bytes: Number(entry.bytes || 0),
+        }))
+      : [],
+  };
+}
+
+function resolveDiagnosticsInput(entry) {
+  if (typeof entry !== "string") {
+    return { diagnostics: entry, sourcePath: "" };
+  }
+  return {
+    diagnostics: readDiagnosticsArtifact(entry),
+    sourcePath: path.resolve(entry),
+  };
+}
+
+function buildchainRootForPath(filePath) {
+  const parts = path.resolve(filePath).split(path.sep);
+  const index = parts.lastIndexOf(".buildchain");
+  if (index <= 0) {
+    return "";
+  }
+  const rootParts = parts.slice(0, index);
+  return rootParts.length ? rootParts.join(path.sep) || path.sep : path.sep;
+}
+
+function diagnosticsManifestCandidates(diagnostics, sourcePath) {
+  if (!sourcePath) {
+    return [];
+  }
+  const candidates = [path.join(path.dirname(sourcePath), "diagnostics-manifest.json")];
+  const linkedPath = diagnostics?.links?.diagnosticsManifest || "";
+  if (linkedPath) {
+    if (path.isAbsolute(linkedPath)) {
+      candidates.push(linkedPath);
+    } else {
+      const buildchainRoot = buildchainRootForPath(sourcePath);
+      if (buildchainRoot) {
+        candidates.push(path.resolve(buildchainRoot, linkedPath));
+      }
+      candidates.push(path.resolve(process.cwd(), linkedPath));
+      candidates.push(path.resolve(path.dirname(sourcePath), linkedPath));
+    }
+  }
+  return [...new Set(candidates)];
+}
+
+function compactDiagnosticsManifestFile(entry = {}) {
+  return {
+    kind: entry.kind || "",
+    path: entry.path || "",
+    bytes: Number(entry.bytes || 0),
+    sha256: entry.sha256 || "",
+    required: Boolean(entry.required),
+  };
+}
+
+function summarizeDiagnosticsContract(diagnostics = {}) {
+  const actual = diagnostics?.contract || "";
+  const warnings = [];
+  if (actual !== BUILDCHAIN_DIAGNOSTICS_CONTRACT) {
+    warnings.push(`unexpected diagnostics artifact contract: ${actual || "unknown"}`);
+  }
+  return {
+    status: warnings.length ? "warning" : "verified",
+    expected: BUILDCHAIN_DIAGNOSTICS_CONTRACT,
+    actual,
+    warningCount: warnings.length,
+    warnings,
+  };
+}
+
+function summarizeDiagnosticsManifest(diagnostics, sourcePath) {
+  if (!sourcePath) {
+    return undefined;
+  }
+  const candidates = diagnosticsManifestCandidates(diagnostics, sourcePath);
+  const manifestPath = candidates.find((candidate) => fs.existsSync(candidate)) || candidates[0] || "";
+  const relativePath = manifestPath
+    ? posixPath(path.relative(path.dirname(sourcePath), manifestPath))
+    : "";
+  if (!manifestPath || !fs.existsSync(manifestPath)) {
+    return {
+      status: "missing",
+      path: relativePath || "diagnostics-manifest.json",
+      warningCount: 1,
+      warnings: ["diagnostics sidecar manifest is missing"],
+    };
+  }
+
+  const { value: manifest, error } = readJsonResult(manifestPath);
+  if (error) {
+    return {
+      status: "invalid",
+      path: relativePath,
+      warningCount: 1,
+      warnings: [`failed to read diagnostics sidecar manifest: ${error.message}`],
+    };
+  }
+
+  const warnings = [];
+  if (manifest?.contract !== BUILDCHAIN_DIAGNOSTICS_MANIFEST_CONTRACT) {
+    warnings.push(`unexpected diagnostics sidecar manifest contract: ${manifest?.contract || "unknown"}`);
+  }
+  const files = Array.isArray(manifest?.files) ? manifest.files.map(compactDiagnosticsManifestFile) : [];
+  if (!Array.isArray(manifest?.files)) {
+    warnings.push("diagnostics sidecar manifest files must be an array");
+  }
+  const diagnosticsEntry = files.find((entry) => entry.kind === "diagnostics");
+  if (!diagnosticsEntry) {
+    warnings.push("diagnostics sidecar manifest does not list diagnostics.json");
+  } else {
+    const stat = fs.statSync(sourcePath);
+    const digest = sha256File(sourcePath);
+    if (diagnosticsEntry.bytes !== stat.size) {
+      warnings.push("diagnostics sidecar manifest bytes do not match diagnostics.json");
+    }
+    if (diagnosticsEntry.sha256 && diagnosticsEntry.sha256 !== digest) {
+      warnings.push("diagnostics sidecar manifest sha256 does not match diagnostics.json");
+    }
+  }
+
+  return {
+    status: warnings.length ? "warning" : "verified",
+    path: relativePath,
+    artifactName: manifest?.artifactName || "",
+    diagnosticsArtifactName: manifest?.diagnosticsArtifactName || "",
+    platformId: manifest?.platformId || "",
+    fileCount: Number(manifest?.fileCount || files.length),
+    totalBytes: Number(manifest?.totalBytes || files.reduce((sum, entry) => sum + entry.bytes, 0)),
+    files,
+    warningCount: warnings.length,
+    warnings,
+  };
+}
+
+function formatDiagnosticsSummaryRows(rows = []) {
+  const widths = rows[0].map((_, columnIndex) => (
+    Math.max(...rows.map((row) => String(row[columnIndex] ?? "").length))
+  ));
+  return rows
+    .map((row) => row.map((cell, index) => String(cell ?? "").padEnd(widths[index], " ")).join("  ").trimEnd())
+    .join("\n");
+}
+
+export function formatDiagnosticsSummaryTable(summary = {}) {
+  const rows = [[
+    "platform",
+    "head",
+    "install",
+    "build",
+    "verify",
+    "publish",
+    "scan",
+    "upload",
+    "total",
+    "jobs",
+    "active",
+    "warn",
+    "err",
+  ]];
+  for (const platform of summary.platforms || []) {
+    const label = `${platform.runner || "unknown"}/${platform.arch || "unknown"}`;
+    const processSummary = compactProcessSummary(platform.process);
+    rows.push([
+      label,
+      platform.gitHead ? platform.gitHead.slice(0, 12) : "-",
+      formatDiagnosticsDurationMs(stageDurationMs(platform.lifecycle, "install")),
+      formatDiagnosticsDurationMs(stageDurationMs(platform.lifecycle, "build")),
+      formatDiagnosticsDurationMs(stageDurationMs(platform.lifecycle, "verify")),
+      formatDiagnosticsDurationMs(stageDurationMs(platform.lifecycle, "publish")),
+      formatDiagnosticsDurationMs(platform.artifactScanDurationMs),
+      formatDiagnosticsDurationMs(platform.artifactUploadDurationMs),
+      formatDiagnosticsDurationMs(platform.totalDurationMs),
+      formatDiagnosticsProcessValue(processSummary.requestedParallelism),
+      formatDiagnosticsProcessValue(processSummary.observedConcurrencyMax),
+      platform.warningCount || 0,
+      platform.errorCount || 0,
+    ]);
+  }
+  return formatDiagnosticsSummaryRows(rows);
+}
+
+export function summarizeDiagnosticsArtifacts(inputs = []) {
+  const diagnostics = inputs
+    .map(resolveDiagnosticsInput)
+    .filter((entry) => entry.diagnostics);
+  const platforms = diagnostics.map(({ diagnostics: entry, sourcePath }) => {
+    const lifecycle = entry.lifecycleObservability?.stages || {};
+    const lifecycleTotalDurationMs = sumLifecycleDurationMs(lifecycle);
+    const artifactScanDurationMs = Math.round(Number(entry.lifecycleObservability?.artifactScan?.durationMs || 0));
+    const artifactUploadDurationMs = Math.round(Number(entry.lifecycleObservability?.artifactUpload?.durationMs || 0));
+    const diagnosticsContract = summarizeDiagnosticsContract(entry);
+    const diagnosticsManifest = summarizeDiagnosticsManifest(entry, sourcePath);
+    return {
+      runner: entry.runner?.github?.runnerOs || entry.runner?.os?.platform || "unknown",
+      arch: entry.runner?.github?.runnerArch || entry.runner?.os?.arch || "unknown",
+      gitHead: entry.git?.head || "",
+      lifecycle,
+      lifecycleTotalDurationMs,
+      artifactScanDurationMs,
+      artifactUploadDurationMs,
+      totalDurationMs: lifecycleTotalDurationMs + artifactScanDurationMs + artifactUploadDurationMs,
+      totalBytes: Number(entry.lifecycleObservability?.totalBytes || 0),
+      fileCount: Number(entry.lifecycleObservability?.fileCount || 0),
+      topSlowSpans: (entry.lifecycleObservability?.topSlowSpans || []).slice(0, 5),
+      runnerDetails: compactRunnerDetails(entry.runner || {}),
+      tools: compactToolSummary(entry.tools || {}, entry.native?.tools || {}),
+      cache: compactCacheSummary(entry.cache || {}, entry.native || {}),
+      compilerCaches: compactCompilerCacheSummary(entry.compilerCaches || entry.native?.compilerCaches || entry.cache?.compilerCaches || {}),
+      nativeCacheDirs: Array.isArray(entry.nativeCacheDirs)
+        ? entry.nativeCacheDirs
+        : Array.isArray(entry.native?.cacheDirs)
+          ? entry.native.cacheDirs
+          : [],
+      process: entry.process || {},
+      sourceCheckout: entry.sourceCheckout
+        ? {
+            mode: entry.sourceCheckout.policy?.mode || "",
+            transport: entry.sourceCheckout.cache?.transport || "",
+            hit: Boolean(entry.sourceCheckout.cache?.hit),
+            fallbackUsed: Boolean(entry.sourceCheckout.cache?.fallbackUsed),
+            fallbackReason: entry.sourceCheckout.cache?.fallbackReason || "",
+            durationMs: Number(entry.sourceCheckout.durationMs || 0),
+            headOk: Boolean(entry.sourceCheckout.verification?.headOk),
+            treeOk: Boolean(entry.sourceCheckout.verification?.treeOk),
+          }
+        : undefined,
+      diagnosticsContract,
+      ...(diagnosticsManifest ? { diagnosticsManifest } : {}),
+      links: entry.links || {},
+      warningCount: entry.lifecycleObservability?.warningCount || 0,
+      errorCount: entry.lifecycleObservability?.errorCount || 0,
+    };
+  });
+  return {
+    schemaVersion: 1,
+    contract: BUILDCHAIN_DIAGNOSTICS_SUMMARY_CONTRACT,
+    generatedAt: new Date().toISOString(),
+    count: diagnostics.length,
+    totalWarningCount: platforms.reduce((sum, entry) => sum + entry.warningCount, 0),
+    totalErrorCount: platforms.reduce((sum, entry) => sum + entry.errorCount, 0),
+    diagnosticsManifestWarningCount: platforms.reduce(
+      (sum, entry) => sum + Number(entry.diagnosticsManifest?.warningCount || 0),
+      0,
+    ),
+    diagnosticsContractWarningCount: platforms.reduce(
+      (sum, entry) => sum + Number(entry.diagnosticsContract?.warningCount || 0),
+      0,
+    ),
+    slowestPlatforms: platforms
+      .map(({ runner, arch, gitHead, lifecycleTotalDurationMs, totalDurationMs, process }) => ({
+        runner,
+        arch,
+        gitHead,
+        lifecycleTotalDurationMs,
+        totalDurationMs,
+        process: compactProcessSummary(process),
+      }))
+      .sort((left, right) => right.totalDurationMs - left.totalDurationMs)
+      .slice(0, 10),
+    platforms,
+  };
+}