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

package/packages/core/cache-evidence.js

@@ -0,0 +1,288 @@
+import crypto from "node:crypto";
+
+export const BUILDCHAIN_CACHE_OPERATION_RECEIPT_CONTRACT =
+  "buildchain.cache-operation-receipt/v1";
+export const BUILDCHAIN_CACHE_EVIDENCE_SET_CONTRACT =
+  "buildchain.cache-evidence-set/v1";
+
+const DIGEST_RE = /^sha256:[0-9a-f]{64}$/;
+const OUTCOMES = new Set([
+  "hit",
+  "miss",
+  "partial",
+  "bypassed",
+  "poisoned",
+  "unavailable",
+]);
+const METRIC_UNITS = Object.freeze({
+  lookupDuration: "ms",
+  restoreDuration: "ms",
+  saveDuration: "ms",
+  restoredBytes: "bytes",
+  writtenBytes: "bytes",
+  savedTime: "ms",
+});
+const METRIC_STATUSES = new Set(["observed", "unavailable", "not-applicable"]);
+const SAVED_TIME_METHODS = new Set(["producer-measured", "provider-reported"]);
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function ordered(value) {
+  if (Array.isArray(value)) return value.map(ordered);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort()
+        .map((key) => [key, ordered(value[key])]),
+    );
+  }
+  return value;
+}
+
+function stableJson(value) {
+  return JSON.stringify(ordered(value));
+}
+
+export function cacheEvidenceDigest(value) {
+  return `sha256:${crypto
+    .createHash("sha256")
+    .update(typeof value === "string" ? value : stableJson(value))
+    .digest("hex")}`;
+}
+
+function exactKeys(value, allowed, label) {
+  assert(
+    value && typeof value === "object" && !Array.isArray(value),
+    `${label} must be an object`,
+  );
+  for (const key of Object.keys(value)) {
+    assert(allowed.has(key), `${label}.${key} is not allowed`);
+  }
+}
+
+function text(value, label) {
+  assert(
+    typeof value === "string" && value.trim() === value && value.length > 0,
+    `${label} is required`,
+  );
+  assert(!/[\r\n\0]/.test(value), `${label} contains control characters`);
+  return value;
+}
+
+function digest(value, label) {
+  assert(DIGEST_RE.test(value), `${label} must be a sha256 digest`);
+  return value;
+}
+
+function normalizeBindings(bindings = {}) {
+  exactKeys(
+    bindings,
+    new Set([
+      "sourceCommit",
+      "sourceTree",
+      "runtimeCommit",
+      "dependencyLockRoot",
+      "toolchainRoot",
+      "policyRoot",
+      "platformRoot",
+      "cacheProfileRoot",
+    ]),
+    "bindings",
+  );
+  return Object.fromEntries(
+    Object.entries(bindings)
+      .filter(([, value]) => value !== null && value !== undefined && value !== "")
+      .map(([key, value]) => [key, text(value, `bindings.${key}`)]),
+  );
+}
+
+function normalizeMetric(metric, name) {
+  exactKeys(
+    metric,
+    new Set([
+      "status",
+      "unit",
+      "value",
+      "source",
+      "reason",
+      "evidenceRoot",
+      "method",
+    ]),
+    `metrics.${name}`,
+  );
+  const status = text(metric.status, `metrics.${name}.status`);
+  assert(
+    METRIC_STATUSES.has(status),
+    `metrics.${name}.status must be observed, unavailable, or not-applicable`,
+  );
+  assert(
+    metric.unit === METRIC_UNITS[name],
+    `metrics.${name}.unit must be ${METRIC_UNITS[name]}`,
+  );
+  if (status === "observed") {
+    assert(
+      Number.isFinite(metric.value) && metric.value >= 0,
+      `metrics.${name}.value must be a non-negative finite number`,
+    );
+    const normalized = {
+      status,
+      unit: metric.unit,
+      value: metric.value,
+      source: text(metric.source, `metrics.${name}.source`),
+      reason: null,
+      evidenceRoot: digest(
+        metric.evidenceRoot,
+        `metrics.${name}.evidenceRoot`,
+      ),
+    };
+    if (name === "savedTime") {
+      assert(
+        typeof metric.method === "string" &&
+          SAVED_TIME_METHODS.has(metric.method),
+        "observed saved time requires producer-measured or provider-reported evidence",
+      );
+      normalized.method = metric.method;
+    } else if (metric.method) {
+      normalized.method = text(metric.method, `metrics.${name}.method`);
+    }
+    return normalized;
+  }
+  assert(
+    metric.value === null || metric.value === undefined,
+    `metrics.${name}.value must be null when ${status}`,
+  );
+  return {
+    status,
+    unit: metric.unit,
+    value: null,
+    source: metric.source ? text(metric.source, `metrics.${name}.source`) : null,
+    reason: text(metric.reason, `metrics.${name}.reason`),
+    evidenceRoot: metric.evidenceRoot
+      ? digest(metric.evidenceRoot, `metrics.${name}.evidenceRoot`)
+      : null,
+  };
+}
+
+export function createCacheOperationReceipt({
+  operationId,
+  operation,
+  provider,
+  producer,
+  platform,
+  cacheKey,
+  cacheRoot,
+  outcome,
+  bindings = {},
+  metrics,
+  evidence,
+} = {}) {
+  assert(
+    ["restore", "save", "lookup"].includes(operation),
+    "operation must be restore, save, or lookup",
+  );
+  assert(OUTCOMES.has(outcome), "unsupported cache outcome");
+  exactKeys(
+    metrics,
+    new Set(Object.keys(METRIC_UNITS)),
+    "metrics",
+  );
+  for (const name of Object.keys(METRIC_UNITS)) {
+    assert(metrics[name], `metrics.${name} is required`);
+  }
+  exactKeys(
+    evidence,
+    new Set(["kind", "root", "locator"]),
+    "evidence",
+  );
+  const receipt = {
+    schema: BUILDCHAIN_CACHE_OPERATION_RECEIPT_CONTRACT,
+    operationId: text(operationId, "operationId"),
+    operation,
+    provider: text(provider, "provider"),
+    producer: text(producer, "producer"),
+    platform: text(platform, "platform"),
+    cacheKey: cacheKey ? text(cacheKey, "cacheKey") : null,
+    cacheRoot: cacheRoot ? text(cacheRoot, "cacheRoot") : null,
+    outcome,
+    bindings: normalizeBindings(bindings),
+    metrics: Object.fromEntries(
+      Object.keys(METRIC_UNITS).map((name) => [
+        name,
+        normalizeMetric(metrics[name], name),
+      ]),
+    ),
+    evidence: {
+      kind: text(evidence.kind, "evidence.kind"),
+      root: digest(evidence.root, "evidence.root"),
+      locator: text(evidence.locator, "evidence.locator"),
+    },
+  };
+  return { ...receipt, receiptRoot: cacheEvidenceDigest(receipt) };
+}
+
+export function verifyCacheOperationReceipt(receipt) {
+  assert(
+    receipt?.schema === BUILDCHAIN_CACHE_OPERATION_RECEIPT_CONTRACT,
+    "cache operation receipt schema mismatch",
+  );
+  const { receiptRoot, ...body } = receipt;
+  assert(
+    receiptRoot === cacheEvidenceDigest(body),
+    "cache operation receipt root mismatch",
+  );
+  const rebuilt = createCacheOperationReceipt(body);
+  assert(
+    stableJson(rebuilt) === stableJson(receipt),
+    "cache operation receipt normalization drift",
+  );
+  return true;
+}
+
+export function createCacheEvidenceSet({
+  repository,
+  sourceCommit,
+  sourceTree = "",
+  runtimeCommit = "",
+  platform,
+  operations = [],
+} = {}) {
+  assert(Array.isArray(operations), "cache evidence operations must be an array");
+  operations.forEach(verifyCacheOperationReceipt);
+  const operationIds = operations.map(({ operationId }) => operationId);
+  assert(
+    operationIds.length === new Set(operationIds).size,
+    "cache evidence operation ids must be unique",
+  );
+  const value = {
+    schema: BUILDCHAIN_CACHE_EVIDENCE_SET_CONTRACT,
+    repository: text(repository, "repository"),
+    sourceCommit: text(sourceCommit, "sourceCommit"),
+    sourceTree: sourceTree ? text(sourceTree, "sourceTree") : null,
+    runtimeCommit: runtimeCommit ? text(runtimeCommit, "runtimeCommit") : null,
+    platform: text(platform, "platform"),
+    operations: [...operations].sort((left, right) =>
+      left.operationId.localeCompare(right.operationId),
+    ),
+  };
+  return { ...value, evidenceRoot: cacheEvidenceDigest(value) };
+}
+
+export function verifyCacheEvidenceSet(receipt) {
+  assert(
+    receipt?.schema === BUILDCHAIN_CACHE_EVIDENCE_SET_CONTRACT,
+    "cache evidence set schema mismatch",
+  );
+  const { evidenceRoot, ...body } = receipt;
+  assert(
+    evidenceRoot === cacheEvidenceDigest(body),
+    "cache evidence set root mismatch",
+  );
+  const rebuilt = createCacheEvidenceSet(body);
+  assert(
+    stableJson(rebuilt) === stableJson(receipt),
+    "cache evidence set normalization drift",
+  );
+  return true;
+}

package/packages/core/diagnostics.js

@@ -19,6 +19,11 @@ import {
   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 =
@@ -568,18 +573,37 @@ function collectCompilerCacheTool({ command, attempts, cwd, runCommand }) {
 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: collectCompilerCacheTool({
-      command: "ccache",
-      attempts: [
-        { args: ["--show-stats", "--json"], format: "json" },
-        { args: ["--show-stats"], format: "text" },
-      ],
-      cwd: resolvedCwd,
-      runCommand,
-    }),
+    ccache,
     sccache: collectCompilerCacheTool({
       command: "sccache",
       attempts: [
@@ -591,6 +615,238 @@ export function collectCompilerCacheDiagnostics({
   };
 }
 
+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 cacheStatsCount(stats, names) {
+  return names.reduce((sum, name) => sum + Number(stats?.[name] || 0), 0);
+}
+
+function compilerCacheOutcome(compilerCaches) {
+  const logStats = compilerCaches?.ccache?.logStats;
+  if (!logStats?.available || !logStats.stats) return "unavailable";
+  const hits = cacheStatsCount(logStats.stats, [
+    "direct_cache_hit",
+    "preprocessed_cache_hit",
+  ]);
+  const misses = cacheStatsCount(logStats.stats, ["cache_miss"]);
+  if (hits > 0 && misses > 0) return "partial";
+  if (hits > 0) return "hit";
+  if (misses > 0) return "miss";
+  return "bypassed";
+}
+
+function createStructuredCacheEvidence({
+  sourceCheckout,
+  compilerCaches,
+  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 } : {}),
+  };
+  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 compilerEvidenceRoot = cacheEvidenceDigest(compilerCaches || {});
+  operations.push(
+    createCacheOperationReceipt({
+      operationId: `compiler-cache:${platform}`,
+      operation: "restore",
+      provider: compilerCaches?.ccache?.available ? "ccache" : "compiler-cache",
+      producer: compilerCaches?.ccache?.available ? "ccache" : "unavailable",
+      platform,
+      cacheKey: policyRoot || null,
+      cacheRoot: policyRoot || null,
+      outcome: compilerCacheOutcome(compilerCaches),
+      bindings,
+      metrics: {
+        lookupDuration: unavailableMetric(
+          "ms",
+          "ccache stats log exposes outcomes but not lookup duration",
+          "ccache-stats-log",
+          compilerEvidenceRoot,
+        ),
+        restoreDuration: unavailableMetric(
+          "ms",
+          "ccache stats log exposes outcomes but not transfer duration",
+          "ccache-stats-log",
+          compilerEvidenceRoot,
+        ),
+        saveDuration: unavailableMetric(
+          "ms",
+          "ccache stats log exposes writes but not save duration",
+          "ccache-stats-log",
+          compilerEvidenceRoot,
+        ),
+        restoredBytes: unavailableMetric(
+          "bytes",
+          "ccache does not expose per-run restored bytes",
+          "ccache-stats-log",
+          compilerEvidenceRoot,
+        ),
+        writtenBytes: unavailableMetric(
+          "bytes",
+          "ccache does not expose per-run written bytes",
+          "ccache-stats-log",
+          compilerEvidenceRoot,
+        ),
+        savedTime: unavailableMetric(
+          "ms",
+          "ccache does not report evidence-backed compile time saved",
+          "ccache-stats-log",
+          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 {
@@ -1095,6 +1351,11 @@ export function createDiagnosticsArtifact({
   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,
@@ -1105,7 +1366,12 @@ export function createDiagnosticsArtifact({
     tools: collectToolDiagnostics({ cwd: resolvedCwd }),
     cache,
     native,
-    compilerCaches: native.compilerCaches || cache.compilerCaches || {},
+    compilerCaches,
+    cacheEvidence: createStructuredCacheEvidence({
+      sourceCheckout,
+      compilerCaches,
+      platform,
+    }),
     nativeCacheDirs: native.cacheDirs || [],
     git: collectGitDiagnostics({ cwd: resolvedCwd }),
     lifecycleObservability: lifecycleObservability || summarizeLifecycleObservability({ events, logPath }),