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

package/packages/core/diagnostics.js

@@ -1,1904 +0,0 @@
-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 "./buildchain-config.js";
-import { detectPackageManager, getWorkspaceInfo } from "./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,
-  };
-}