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

package/bin/buildchain.mjs

@@ -104,6 +104,10 @@ import {
 } from "../packages/core/kfd3-surface-register.js";
 import { createBuildchainLayoutDiscovery } from "../packages/core/buildchain-layout.js";
 import { createPortableDevCachePlan, createPortableDevCacheReceipt } from "../packages/core/portable-dev-cache.js";
+import {
+  createCandidateTimeline,
+  formatCandidateTimelineReport,
+} from "../packages/core/candidate-timeline.js";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const embeddedPackageVersion = process.env.BUILDCHAIN_EMBEDDED_PACKAGE_VERSION || "";
@@ -121,6 +125,7 @@ function usage() {
                                     [--validation-reason <text>]
                                     [--cold-fallback-status not-run|passed|failed]
                                     [--output <file>] [--json]
+  buildchain candidate timeline --input <file-or-json> [--output <file>] [--json]
   buildchain init [--cwd <dir>] [--type package|native|web-surface|infra-contract|publication-artifact|anchored-package] [--force]
                   [--package-manager pnpm|npm|yarn] [--runner-preset <preset>]
                   [--artifact-name <template>]
@@ -1451,6 +1456,28 @@ async function main(argv = process.argv.slice(2)) {
     throw new Error("usage: buildchain portable-cache <plan|receipt> ...");
   }
 
+  if (command === "candidate") {
+    const [subcommand = "", ...candidateArgs] = args;
+    if (subcommand !== "timeline") {
+      throw new Error("usage: buildchain candidate timeline --input <file-or-json>");
+    }
+    const inputValue = readFlag(candidateArgs, "input", "");
+    if (!inputValue) {
+      throw new Error("buildchain candidate timeline requires --input <file-or-json>");
+    }
+    const input = readJsonInput(inputValue, { label: "candidate timeline input" });
+    const timeline = createCandidateTimeline(input);
+    const output = readFlag(candidateArgs, "output", "");
+    if (output) writeJsonFile(path.resolve(output), timeline);
+    if (readBooleanFlag(candidateArgs, "json") || !output) {
+      printJson(timeline);
+    } else {
+      process.stdout.write(`${formatCandidateTimelineReport(timeline)}\n`);
+      process.stdout.write(`wrote: ${output}\n`);
+    }
+    return;
+  }
+
   if (command === "init") {
     const result = initBuildchainRepo({
       cwd: readFlag(args, "cwd", process.cwd()),

package/dist/site/buildchain-contract.json

@@ -4,7 +4,7 @@
   "product": {
     "name": "Buildchain",
     "package": "@kungfu-tech/buildchain",
-    "version": "2.14.17-alpha.0",
+    "version": "2.14.17-alpha.2",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "majorLine": "v2",
@@ -256,7 +256,7 @@
         "channel-aware artifact host facts are checked against the deploy plan before adapter side effects"
       ],
       "breakingDigest": "sha256:da569f90374e878948e3d5160ed9929338ce0572473ca8ee54867b0fe1aaeace",
-      "auditDigest": "sha256:cd620b10103c27137ae17f23583753adfe2f3ef501e511f7380431aa95f08b18"
+      "auditDigest": "sha256:4a7c696ec399c14aa3170fdd24adac0d624bd33db6a2639c489e2b58726c190b"
     },
     {
       "contractVersion": 1,
@@ -323,6 +323,9 @@
         "publish transactions can require a resolved publish-gate source lock to prevent floating-ref drift",
         "semver GitHub Releases are created or updated only after transaction completion, with prerelease/latest metadata bound to the authoritative publication channel and tag syntax retained as the fallback for ordinary callers"
       ],
+      "compatibleBreakingDigests": [
+        "sha256:a59f0910e6df842e7699139472e5dd69ac2fdd7f7213bf2cb346d1d622556874"
+      ],
       "breakingDigest": "sha256:6147c0a8d5c36bfaa6021871574e1fc28192a3f1b8cfdae4d24ef3059ac1ebda",
       "auditDigest": "sha256:ff220542fd1cb21fc4780d0bb31eb9f78d44d70746b6c4364483e104b48ae083"
     },
@@ -492,7 +495,7 @@
         "README badge block checks and writes are generated from machine-readable repository facts"
       ],
       "breakingDigest": "sha256:90a73892b2d6c214048448d5f45df75639bdf7b7e8fefd9c596e04b087407bcc",
-      "auditDigest": "sha256:0d6ab717fa934bb7d50a166e8cf6e3cea5c57b3be460864d083a91edb013f868"
+      "auditDigest": "sha256:0e33a9c24a2a23e5657d06ee7013454ada97b141a3dbae0c10490554bb74bf1f"
     },
     {
       "contractVersion": 1,
@@ -582,7 +585,7 @@
         "manual entries carry source file digests so downstream sites and agents can detect stale hand-written documentation"
       ],
       "breakingDigest": "sha256:7d0d2819e3a3e72989d9c57b5efe9d0bc0a79bc0f2c82a0c7b9d6c5a211a91f2",
-      "auditDigest": "sha256:b012b8c27fda3a7b5816b14fbd30c7761b899ba65c83079014d8d1f891b60608"
+      "auditDigest": "sha256:a877a3ac90cabaa5f30a735a4ebd7b5be6254492572723a940f7df0fecd43ee7"
     },
     {
       "contractVersion": 1,
@@ -604,7 +607,7 @@
         "agents can discover supported Node APIs without importing internal file paths"
       ],
       "breakingDigest": "sha256:48f925608d3e2131d90936b07dc2a30341204cae3e6e785c0f77d61ad755c945",
-      "auditDigest": "sha256:8005d01fa6c771f466c77629f0589b361fc43a3a4f04b7d88bc1645d33895a51"
+      "auditDigest": "sha256:99097e8474a8dcdccb1a3ab62c19e1b960a010fbc8f00f21df3aac1f04ba2c09"
     },
     {
       "contractVersion": 1,
@@ -1850,7 +1853,7 @@
         "missing receipts are non-qualifying and must not be represented as a successful controller run"
       ],
       "breakingDigest": "sha256:f14825324a16b51c2e9ed708ebe64e1932e05b6d5e0866f83aea8439decb4a27",
-      "auditDigest": "sha256:cd620b10103c27137ae17f23583753adfe2f3ef501e511f7380431aa95f08b18"
+      "auditDigest": "sha256:4a7c696ec399c14aa3170fdd24adac0d624bd33db6a2639c489e2b58726c190b"
     },
     {
       "contractVersion": 1,
@@ -2913,5 +2916,5 @@
     }
   ],
   "compatibilityDigest": "sha256:cdf588422ec6b460bd6f631400efa6e361a045e052c8967d6c50fadd7aa4dd90",
-  "contractDigest": "sha256:fe7adf9ed1c1a0b14b29fef1eb72205ae29c9558806c9b35bfcc258f07d422a8"
+  "contractDigest": "sha256:95680b4596a6e848d6b8cff4b7216b3c560e085298d99587baa4419d4fdc6aef"
 }

package/dist/site/buildchain-site.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-bundle",
-  "generatedAt": "2026-07-22T15:29:55.552Z",
-  "publishedAt": "2026-07-22T15:29:55.552Z",
+  "generatedAt": "2026-07-23T00:58:45.650Z",
+  "publishedAt": "2026-07-23T00:58:45.650Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "a013078fdf88b5b850e48e93faf58de582130440",
+  "sourceRevision": "d67ebd6fcb075c00ef286cee9f2bc1f03633af13",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.14.17-alpha.0",
+    "version": "2.14.17-alpha.2",
     "versionSource": "package.json#version"
   },
   "source": {
@@ -1996,7 +1996,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/toolkit-observability.md",
-      "digest": "sha256:239949a75ca81b6002a2e148f7028402dbd98c00e246acd8d0955855781206a1",
+      "digest": "sha256:ed6c2d0a7e76a5e4fc3fbee635966e462947f748a52d88e515fe4f95a630ac91",
       "headings": [
         {
           "level": 1,
@@ -2013,6 +2013,11 @@
           "title": "Library API",
           "anchor": "library-api"
         },
+        {
+          "level": 2,
+          "title": "Candidate timelines and critical-path-safe timing",
+          "anchor": "candidate-timelines-and-critical-path-safe-timing"
+        },
         {
           "level": 2,
           "title": "Diagnostics API",
@@ -2029,7 +2034,7 @@
           "anchor": "release-gate"
         }
       ],
-      "markdown": "# Toolkit Observability\n\nBuildchain ships a small logging toolkit for repository workflows and project\nscripts. The goal is to separate time spent in Buildchain's framework from time\nspent in the consumer's own build, test, packaging, and publish steps.\n\n## Choose API or CLI\n\n`@kungfu-tech/buildchain` is not only a CLI package. It exports ESM toolkit APIs\nthat project scripts can import directly:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n```\n\nUse the API inside JavaScript or TypeScript build code. Do not spawn\n`buildchain`, download the standalone binary, or shell out through `npx` from\ncode that can import the package. The CLI is for GitHub Actions steps, shell\nscripts, and non-JavaScript tools.\n\nWhen a script runs inside `buildchain lifecycle run`, the lifecycle runner sets\n`BUILDCHAIN_LOG_PATH` and `BUILDCHAIN_LOG_RUN_ID`. Imported loggers pick up those\nenvironment variables automatically, so events emitted deep inside the build are\ngrouped into the same lifecycle summary.\n\nOutside a Buildchain lifecycle or GitHub Actions run, the logger defaults to\nconsole output unless a path is provided. Pass `path` when local scripts should\nwrite a reusable JSONL log:\n\n```js\nconst logger = createBuildchainLogger({\n  path: \".buildchain/logs/native-build.jsonl\",\n  source: \"user\",\n  component: \"native-build\",\n});\n```\n\n## Library API\n\n```js\nimport {\n  createBuildchainLogger,\n  verifyBuildchainLogEvents,\n} from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({\n  source: \"user\",\n  component: \"native-build\",\n});\n\nlogger.mark(\"configure.ready\", {\n  phase: \"configure\",\n  attributes: { preset: \"release\" },\n});\n\nawait logger.span(\"native.compile\", {\n  phase: \"build\",\n  attributes: { target: \"release\" },\n}, async () => {\n  await compile();\n});\n\nlogger.spanSync(\"native.archive\", {\n  phase: \"build\",\n  attributes: { tool: \"libtool\" },\n}, () => {\n  archiveStaticLibraries();\n});\n\nlogger.spawnSync(\"native.build\", \"make\", [\"-j20\"], {\n  stdio: \"inherit\",\n}, {\n  phase: \"build\",\n  attributes: { requestedJobs: 20 },\n});\n\nconst report = verifyBuildchainLogEvents({\n  path: logger.path,\n  minEvents: 3,\n  requirePhases: [\"configure\", \"build\"],\n  requireEvents: [\n    \"configure.ready\",\n    \"native.compile.start\",\n    \"native.compile.end\",\n  ],\n});\n\nif (!report.ok) {\n  throw new Error(\"Buildchain observability verification failed\");\n}\n```\n\nUse the API when a build script has internal stages that are invisible to the\nouter workflow. Keep secret values out of attributes; known sensitive keys are\nredacted, but callers should still avoid logging private material.\n\nCommonJS scripts should import Buildchain's ESM surfaces dynamically:\n\n```js\nconst { createBuildchainLogger } = await import(\"@kungfu-tech/buildchain/logging\");\nconst { collectRunnerDiagnostics } = await import(\"@kungfu-tech/buildchain/diagnostics\");\n```\n\n## Diagnostics API\n\nThe diagnostics surface collects local, non-telemetry build facts that are\nuseful when a native build is slow or flaky:\n\n```js\nimport {\n  collectBuildchainDiagnostics,\n  collectCacheDiagnostics,\n  collectCompilerCacheDiagnostics,\n  collectRunnerDiagnostics,\n  collectToolDiagnostics,\n  detectRequestedParallelism,\n  startProcessSampler,\n  summarizeDiagnosticsArtifacts,\n  summarizeLifecycleObservability,\n  summarizeProcessSamples,\n  validateAnchoredPackageRelease,\n  writeDiagnosticsArtifact,\n} from \"@kungfu-tech/buildchain/diagnostics\";\n\nconst lifecycleObservability = summarizeLifecycleObservability({\n  logPath: \".buildchain/logs/events.jsonl\",\n});\nconst buildCommand = \"make\";\nconst buildArgs = [\"-j20\"];\nconst requestedParallelism = detectRequestedParallelism({\n  command: buildCommand,\n  args: buildArgs,\n});\nconst processSampler = startProcessSampler({\n  intervalMs: 15000,\n  label: \"native-build\",\n  command: buildCommand,\n  args: buildArgs,\n});\n// Run the long native build while the sampler is active.\nconst processSummary = summarizeProcessSamples({\n  requestedParallelism: requestedParallelism.value,\n  samples: processSampler.stop(),\n});\nconst cacheDiagnostics = collectCacheDiagnostics({ cwd: process.cwd() });\n\nwriteDiagnosticsArtifact(\".buildchain/artifacts/diagnostics.json\", {\n  contract: \"consumer-build-diagnostics\",\n  buildchain: collectBuildchainDiagnostics({ cwd: process.cwd() }),\n  runner: collectRunnerDiagnostics(),\n  tools: collectToolDiagnostics({ cwd: process.cwd() }),\n  cache: cacheDiagnostics,\n  lifecycleObservability,\n  process: processSummary,\n});\n```\n\n`collectCacheDiagnostics()` includes package-manager/workspace context, selected\ncache directory stats, and compiler-cache stats from `ccache --show-stats\n--json` plus `sccache --show-stats --stats-format json` when those tools are\npresent. If a ccache build does not support JSON stats, Buildchain falls back to\nplain `ccache --show-stats` and parses the text counters. Missing cache tools\nare recorded as unavailable instead of failing the diagnostics artifact. Call\n`collectCompilerCacheDiagnostics()` directly when a consumer script only needs\ncompiler cache data. Native diagnostics also expose `compilerCaches` and\n`nativeCacheDirs` as top-level fields in each diagnostics artifact and aggregate\nsummary, so reviewers do not have to dig through nested cache sections first.\n\nProcess samples are intentionally summarized before they become long-lived\nartifacts. The summary records requested parallelism, the source of that value\n(`command`, `process-tree`, `env:MAKEFLAGS`,\n`env:CMAKE_BUILD_PARALLEL_LEVEL`, or `explicit`), observed active process\nconcurrency, elapsed sample time, total sampled CPU, and conservative command\ncategories such as `compiler`, `archive`, `linker`, `build-tool`, and `cache`.\nThe sampler detects common `make -j N`, `ninja -j N`, CMake/MSBuild/Xcode job\nflags, and MAKEFLAGS. This lets native projects distinguish \"we asked for\n`make -j20`\" from \"the build graph only kept two active compiler or archive\nchildren busy during the sampled window\" without storing environment dumps.\n\nNative repositories can opt into a reusable diagnostics profile in\n`buildchain.toml`:\n\n```toml\n[diagnostics.native]\nenabled = true\nsample_process_tree = true\ncompiler_cache = \"auto\"\nexpected_tools = [\"ccache\", \"sccache\", \"clang\", \"cl\", \"cmake\", \"ninja\"]\nartifact_dirs = [\"build\", \"dist\", \"build/Release\"]\ncache_dirs = [\".ccache\", \".sccache\"]\n```\n\nWhen enabled, diagnostics artifacts include the normalized profile, selected\ntool versions, compiler-cache stats, and configured artifact/cache directory\nstats. The profile is data-driven: Buildchain does not assume a specific\nproject such as libnode. The reusable build workflow also exposes\n`sample-process-tree`, which wraps the build lifecycle with the process sampler\nand carries the generated summary into the final diagnostics artifact. Custom\nworkflows can call `buildchain sample process-tree` directly when they need a\ndifferent command boundary.\n\nAnchored/manual package projects can also run one higher-level release-shape\ncheck instead of assembling lower-level config calls:\n\n```js\nconst anchoredReport = validateAnchoredPackageRelease({\n  cwd: process.cwd(),\n  requireManifest: true,\n  requirePackageSetOrder: \"platforms-first-main-last\",\n  requireTrustedPublishing: true,\n});\n\nif (!anchoredReport.ok) {\n  throw new Error(\"Anchored package release contract failed\");\n}\n```\n\nIn an actual publish job, make that check source-lock aware:\n\n```js\nconst publishReady = validateAnchoredPackageRelease({\n  cwd: process.cwd(),\n  requirePublishGateSourceLock: true,\n});\n```\n\nThe source-lock inputs are read from `BUILDCHAIN_PUBLISH_SOURCE_REF`,\n`BUILDCHAIN_PUBLISH_SOURCE_SHA`, and `BUILDCHAIN_PUBLISH_SOURCE_LOCKED`, which\nthe reusable build workflow emits after resolving `publish-source-ref`. That\nturns direct channel-branch publication from `alpha/*` or `release/*` into a\nhard failure, while `publish-gate/alpha/<line>/<version>` and\n`publish-gate/release/<line>/<version>` also validate the requested consumer\nversion against configured version files and the anchor manifest.\n\n`buildchain lifecycle run` writes this small diagnostics artifact next to the\nplatform manifest by default. The per-platform diagnostics upload includes the\ncompact `diagnostics.json`, `diagnostics-manifest.json`, lifecycle\n`events.jsonl`, and, when process sampling is enabled, copied\n`process-summary.json` and `process-samples.jsonl` sidecars. The sidecar\nmanifest records each uploaded diagnostics file with its relative path, byte\ncount, and sha256 hash. It is intended to stay small enough to download without\nfetching large binary packages, and it should not include full environment dumps\nor secret-looking values.\n\nUse `summarizeDiagnosticsArtifacts()` when a matrix build uploads one\ndiagnostics artifact per platform. The summary keeps each platform's lifecycle\nstage table, adds a lifecycle total duration, carries the top slow spans, and\naggregates warning/error counts plus the slowest platforms. Per-platform rows\nalso include compact runner facts, checked tool versions/missing tools, package\nmanager/cache directory details, compiler cache availability, and a compact\nprocess sampler view with requested parallelism, observed max active processes,\nthe ratio between them, sample count, process categories, and top sampled\ncommand basenames. That gives release reviewers a small cross-platform timing,\nrunner, tool, cache, and concurrency view without downloading full build outputs\nor process sidecars.\n\nThe reusable build workflow writes that rollup as `diagnostics-summary.json` and\nuploads it in a separate aggregate diagnostics summary artifact. Consumers can\nread the `build-diagnostics-summary-artifact` output when they need only timing,\nwarning/error, runner, cache, and process-sampler context instead of the build\nsummary or binary artifacts. Per-platform rows keep the diagnostics `links`\nobject, including the binary artifact name, manifest artifact name, diagnostics\nartifact name, platform id, diagnostics sidecar manifest path, manifest path,\nsummary path, and process sidecar paths when present. They also keep compact\nrunner/tool/cache summaries so reviewers can tell whether a slow row ran on the\nexpected runner, missed an expected tool, or lacked useful compiler-cache stats.\nWhen the downloaded platform diagnostics include a sibling\n`diagnostics-manifest.json`, `summarizeDiagnosticsArtifacts()` carries a compact\n`diagnosticsManifest` section for that platform and verifies the manifest's\n`diagnostics.json` byte count and sha256. Missing or mismatched sidecar manifests\nincrement `diagnosticsManifestWarningCount`, so reviewers can distinguish\ndiagnostics sidecar drift from lifecycle warnings or build failures.\nThe same summary carries `diagnosticsContract` per platform and aggregates\n`diagnosticsContractWarningCount` when a downloaded `diagnostics.json` does not\nmatch `BUILDCHAIN_DIAGNOSTICS_CONTRACT`.\n\nThe diagnostics SDK also exports stable contract constants such as\n`BUILDCHAIN_DIAGNOSTICS_SUMMARY_CONTRACT`,\n`BUILDCHAIN_DIAGNOSTICS_MANIFEST_CONTRACT`,\n`BUILDCHAIN_PROCESS_SAMPLE_REPORT_CONTRACT`,\n`BUILDCHAIN_PROCESS_SAMPLE_SUMMARY_CONTRACT`, and\n`BUILDCHAIN_ANCHORED_PACKAGE_RELEASE_VALIDATION_CONTRACT` from\n`@kungfu-tech/buildchain/diagnostics`; consumers should compare against those\nconstants instead of hardcoding contract strings.\n\nThe CLI exposes the same aggregation for shell and workflow steps:\n\n```bash\nbuildchain diagnostics summary \\\n  .buildchain/artifacts/linux-x64/diagnostics.json \\\n  .buildchain/artifacts/macos-arm64/diagnostics.json \\\n  --output .buildchain/artifacts/diagnostics-summary.json \\\n  --json\n```\n\nOmit `--json` when the workflow log should show a compact platform table with\nlifecycle stages, artifact scan/upload time, total time, requested jobs,\nobserved active processes, warnings, and errors.\n\nFor long native build commands, the CLI can also sample the child process tree\nwhile preserving the wrapped command's exit code:\n\n```bash\nbuildchain sample process-tree \\\n  --label native-build \\\n  --interval-ms 15000 \\\n  --output .buildchain/diagnostics/process-samples.jsonl \\\n  --summary-output .buildchain/diagnostics/process-summary.json \\\n  -- \\\n  make -j20\n```\n\nThe JSONL sample file stores timestamped process-tree snapshots with full\nredacted command lines, command basenames, CPU percentages when available,\nelapsed time, and requested parallelism context. Unix and macOS snapshots read\nthe full `ps args` field instead of truncated `comm` names. Windows snapshots\nread `Win32_Process` command lines through PowerShell so the sampler no longer\nreturns an empty process set on Windows runners. The summary file records\nobserved concurrency, total sampled CPU, command categories, and top command\nbasenames. This is intended for diagnosing low-utilization tails such as\narchive/link phases without logging full environment dumps.\n\nThe lifecycle observability summary is stage-wide, not just final-step timing:\nwhen install and build write to the same Buildchain log, the final platform\nmanifest can show both stages and the slowest spans.\n\n## CLI Logging\n\n```bash\nbuildchain mark \\\n  --event native.configure \\\n  --phase configure \\\n  --component cmake \\\n  --attribute preset=release\n\nbuildchain span \\\n  --event native.build \\\n  --phase build \\\n  --component cmake \\\n  -- cmake --build build --config Release\n\nbuildchain log summary --json\nbuildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4\n```\n\nEvery event records a timestamp. `span` records duration and preserves the\nwrapped command's exit code.\n\n## Release Gate\n\nBuildchain's own binary distribution lane verifies required log events before\nuploading release assets. Consumers can apply the same pattern:\n\n```bash\nbuildchain verify observability-log .buildchain/logs/events.jsonl \\\n  --require-phase build \\\n  --require-phase package \\\n  --require-component workflow \\\n  --require-event native.build.start \\\n  --require-event native.build.end\n```\n\nThis makes missing instrumentation a release failure instead of a dashboard\nafterthought."
+      "markdown": "# Toolkit Observability\n\nBuildchain ships a small logging toolkit for repository workflows and project\nscripts. The goal is to separate time spent in Buildchain's framework from time\nspent in the consumer's own build, test, packaging, and publish steps.\n\n## Choose API or CLI\n\n`@kungfu-tech/buildchain` is not only a CLI package. It exports ESM toolkit APIs\nthat project scripts can import directly:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n```\n\nUse the API inside JavaScript or TypeScript build code. Do not spawn\n`buildchain`, download the standalone binary, or shell out through `npx` from\ncode that can import the package. The CLI is for GitHub Actions steps, shell\nscripts, and non-JavaScript tools.\n\nWhen a script runs inside `buildchain lifecycle run`, the lifecycle runner sets\n`BUILDCHAIN_LOG_PATH` and `BUILDCHAIN_LOG_RUN_ID`. Imported loggers pick up those\nenvironment variables automatically, so events emitted deep inside the build are\ngrouped into the same lifecycle summary.\n\nOutside a Buildchain lifecycle or GitHub Actions run, the logger defaults to\nconsole output unless a path is provided. Pass `path` when local scripts should\nwrite a reusable JSONL log:\n\n```js\nconst logger = createBuildchainLogger({\n  path: \".buildchain/logs/native-build.jsonl\",\n  source: \"user\",\n  component: \"native-build\",\n});\n```\n\n## Library API\n\n```js\nimport {\n  createBuildchainLogger,\n  verifyBuildchainLogEvents,\n} from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({\n  source: \"user\",\n  component: \"native-build\",\n});\n\nlogger.mark(\"configure.ready\", {\n  phase: \"configure\",\n  attributes: { preset: \"release\" },\n});\n\nawait logger.span(\"native.compile\", {\n  phase: \"build\",\n  attributes: { target: \"release\" },\n}, async () => {\n  await compile();\n});\n\nlogger.spanSync(\"native.archive\", {\n  phase: \"build\",\n  attributes: { tool: \"libtool\" },\n}, () => {\n  archiveStaticLibraries();\n});\n\nlogger.spawnSync(\"native.build\", \"make\", [\"-j20\"], {\n  stdio: \"inherit\",\n}, {\n  phase: \"build\",\n  attributes: { requestedJobs: 20 },\n});\n\nconst report = verifyBuildchainLogEvents({\n  path: logger.path,\n  minEvents: 3,\n  requirePhases: [\"configure\", \"build\"],\n  requireEvents: [\n    \"configure.ready\",\n    \"native.compile.start\",\n    \"native.compile.end\",\n  ],\n});\n\nif (!report.ok) {\n  throw new Error(\"Buildchain observability verification failed\");\n}\n```\n\nUse the API when a build script has internal stages that are invisible to the\nouter workflow. Keep secret values out of attributes; known sensitive keys are\nredacted, but callers should still avoid logging private material.\n\n## Candidate timelines and critical-path-safe timing\n\nLifecycle diagnostics retain their existing summed-duration tables for\ncompatibility. Do not interpret those tables as elapsed time when spans are\nnested or jobs run in parallel. Use the candidate timeline contract when a\nchange must be followed from pull-request admission through Merge Queue attempts\nto its final merge:\n\n```js\nimport {\n  createCandidateTimeline,\n  formatCandidateTimelineReport,\n} from \"@kungfu-tech/buildchain/candidate-timeline\";\n\nconst timeline = createCandidateTimeline({\n  candidate: {\n    repository: \"owner/repository\",\n    baseBranch: \"dev/v4/v4.0\",\n    sourceSha,\n    pullRequest: 123,\n  },\n  events,\n});\n\nconsole.log(formatCandidateTimelineReport(timeline));\n```\n\nEach event binds a stable event id to one attempt id and may also bind a Gate\nid, merge-group SHA, workflow run, platform, partition, cache outcome, execution\nboundary, and parent span. Terminal execution states (`success`, `failure`, and\n`cancelled`) require start and completion timestamps. Non-executed states use\n`skipped`, `dependency-blocked`, or `not-required` without invented timings.\nRecord the clock and timestamp precision explicitly: GitHub Actions timestamps\nare normally provider wall-clock observations with one-second precision, while\nan in-process span may also carry a monotonic duration with millisecond or\nbetter precision.\n\nThe `buildchain.candidate-timeline/v1` artifact reports an independent critical\npath for every attempt. Its critical-path duration is the attempt's observed\nwall-clock envelope; its active duration and per-phase durations are interval\nunions. This prevents nested or parallel spans from being added twice, and it\ndoes not combine a failed or dequeued attempt with a later retry. Missing\nrequired measurements make that attempt `incomplete` instead of producing fake\nprecision.\n\nShell and workflow consumers can generate the same machine artifact plus a\ncompact report:\n\n```sh\nbuildchain candidate timeline \\\n  --input .buildchain/candidate-timeline-input.json \\\n  --output .buildchain/candidate-timeline.json\n```\n\nThe input and output should contain only bounded correlation facts and timing\nreceipts. Do not include tokens, environment dumps, full commands, raw process\ndumps, or private absolute paths.\n\nCommonJS scripts should import Buildchain's ESM surfaces dynamically:\n\n```js\nconst { createBuildchainLogger } = await import(\"@kungfu-tech/buildchain/logging\");\nconst { collectRunnerDiagnostics } = await import(\"@kungfu-tech/buildchain/diagnostics\");\n```\n\n## Diagnostics API\n\nThe diagnostics surface collects local, non-telemetry build facts that are\nuseful when a native build is slow or flaky:\n\n```js\nimport {\n  collectBuildchainDiagnostics,\n  collectCacheDiagnostics,\n  collectCompilerCacheDiagnostics,\n  collectRunnerDiagnostics,\n  collectToolDiagnostics,\n  detectRequestedParallelism,\n  startProcessSampler,\n  summarizeDiagnosticsArtifacts,\n  summarizeLifecycleObservability,\n  summarizeProcessSamples,\n  validateAnchoredPackageRelease,\n  writeDiagnosticsArtifact,\n} from \"@kungfu-tech/buildchain/diagnostics\";\n\nconst lifecycleObservability = summarizeLifecycleObservability({\n  logPath: \".buildchain/logs/events.jsonl\",\n});\nconst buildCommand = \"make\";\nconst buildArgs = [\"-j20\"];\nconst requestedParallelism = detectRequestedParallelism({\n  command: buildCommand,\n  args: buildArgs,\n});\nconst processSampler = startProcessSampler({\n  intervalMs: 15000,\n  label: \"native-build\",\n  command: buildCommand,\n  args: buildArgs,\n});\n// Run the long native build while the sampler is active.\nconst processSummary = summarizeProcessSamples({\n  requestedParallelism: requestedParallelism.value,\n  samples: processSampler.stop(),\n});\nconst cacheDiagnostics = collectCacheDiagnostics({ cwd: process.cwd() });\n\nwriteDiagnosticsArtifact(\".buildchain/artifacts/diagnostics.json\", {\n  contract: \"consumer-build-diagnostics\",\n  buildchain: collectBuildchainDiagnostics({ cwd: process.cwd() }),\n  runner: collectRunnerDiagnostics(),\n  tools: collectToolDiagnostics({ cwd: process.cwd() }),\n  cache: cacheDiagnostics,\n  lifecycleObservability,\n  process: processSummary,\n});\n```\n\n`collectCacheDiagnostics()` includes package-manager/workspace context, selected\ncache directory stats, and compiler-cache stats from `ccache --show-stats\n--json` plus `sccache --show-stats --stats-format json` when those tools are\npresent. If a ccache build does not support JSON stats, Buildchain falls back to\nplain `ccache --show-stats` and parses the text counters. Missing cache tools\nare recorded as unavailable instead of failing the diagnostics artifact. Call\n`collectCompilerCacheDiagnostics()` directly when a consumer script only needs\ncompiler cache data. Native diagnostics also expose `compilerCaches` and\n`nativeCacheDirs` as top-level fields in each diagnostics artifact and aggregate\nsummary, so reviewers do not have to dig through nested cache sections first.\n\nProcess samples are intentionally summarized before they become long-lived\nartifacts. The summary records requested parallelism, the source of that value\n(`command`, `process-tree`, `env:MAKEFLAGS`,\n`env:CMAKE_BUILD_PARALLEL_LEVEL`, or `explicit`), observed active process\nconcurrency, elapsed sample time, total sampled CPU, and conservative command\ncategories such as `compiler`, `archive`, `linker`, `build-tool`, and `cache`.\nThe sampler detects common `make -j N`, `ninja -j N`, CMake/MSBuild/Xcode job\nflags, and MAKEFLAGS. This lets native projects distinguish \"we asked for\n`make -j20`\" from \"the build graph only kept two active compiler or archive\nchildren busy during the sampled window\" without storing environment dumps.\n\nNative repositories can opt into a reusable diagnostics profile in\n`buildchain.toml`:\n\n```toml\n[diagnostics.native]\nenabled = true\nsample_process_tree = true\ncompiler_cache = \"auto\"\nexpected_tools = [\"ccache\", \"sccache\", \"clang\", \"cl\", \"cmake\", \"ninja\"]\nartifact_dirs = [\"build\", \"dist\", \"build/Release\"]\ncache_dirs = [\".ccache\", \".sccache\"]\n```\n\nWhen enabled, diagnostics artifacts include the normalized profile, selected\ntool versions, compiler-cache stats, and configured artifact/cache directory\nstats. The profile is data-driven: Buildchain does not assume a specific\nproject such as libnode. The reusable build workflow also exposes\n`sample-process-tree`, which wraps the build lifecycle with the process sampler\nand carries the generated summary into the final diagnostics artifact. Custom\nworkflows can call `buildchain sample process-tree` directly when they need a\ndifferent command boundary.\n\nAnchored/manual package projects can also run one higher-level release-shape\ncheck instead of assembling lower-level config calls:\n\n```js\nconst anchoredReport = validateAnchoredPackageRelease({\n  cwd: process.cwd(),\n  requireManifest: true,\n  requirePackageSetOrder: \"platforms-first-main-last\",\n  requireTrustedPublishing: true,\n});\n\nif (!anchoredReport.ok) {\n  throw new Error(\"Anchored package release contract failed\");\n}\n```\n\nIn an actual publish job, make that check source-lock aware:\n\n```js\nconst publishReady = validateAnchoredPackageRelease({\n  cwd: process.cwd(),\n  requirePublishGateSourceLock: true,\n});\n```\n\nThe source-lock inputs are read from `BUILDCHAIN_PUBLISH_SOURCE_REF`,\n`BUILDCHAIN_PUBLISH_SOURCE_SHA`, and `BUILDCHAIN_PUBLISH_SOURCE_LOCKED`, which\nthe reusable build workflow emits after resolving `publish-source-ref`. That\nturns direct channel-branch publication from `alpha/*` or `release/*` into a\nhard failure, while `publish-gate/alpha/<line>/<version>` and\n`publish-gate/release/<line>/<version>` also validate the requested consumer\nversion against configured version files and the anchor manifest.\n\n`buildchain lifecycle run` writes this small diagnostics artifact next to the\nplatform manifest by default. The per-platform diagnostics upload includes the\ncompact `diagnostics.json`, `diagnostics-manifest.json`, lifecycle\n`events.jsonl`, and, when process sampling is enabled, copied\n`process-summary.json` and `process-samples.jsonl` sidecars. The sidecar\nmanifest records each uploaded diagnostics file with its relative path, byte\ncount, and sha256 hash. It is intended to stay small enough to download without\nfetching large binary packages, and it should not include full environment dumps\nor secret-looking values.\n\nUse `summarizeDiagnosticsArtifacts()` when a matrix build uploads one\ndiagnostics artifact per platform. The summary keeps each platform's lifecycle\nstage table, adds a lifecycle total duration, carries the top slow spans, and\naggregates warning/error counts plus the slowest platforms. Per-platform rows\nalso include compact runner facts, checked tool versions/missing tools, package\nmanager/cache directory details, compiler cache availability, and a compact\nprocess sampler view with requested parallelism, observed max active processes,\nthe ratio between them, sample count, process categories, and top sampled\ncommand basenames. That gives release reviewers a small cross-platform timing,\nrunner, tool, cache, and concurrency view without downloading full build outputs\nor process sidecars.\n\nThe reusable build workflow writes that rollup as `diagnostics-summary.json` and\nuploads it in a separate aggregate diagnostics summary artifact. Consumers can\nread the `build-diagnostics-summary-artifact` output when they need only timing,\nwarning/error, runner, cache, and process-sampler context instead of the build\nsummary or binary artifacts. Per-platform rows keep the diagnostics `links`\nobject, including the binary artifact name, manifest artifact name, diagnostics\nartifact name, platform id, diagnostics sidecar manifest path, manifest path,\nsummary path, and process sidecar paths when present. They also keep compact\nrunner/tool/cache summaries so reviewers can tell whether a slow row ran on the\nexpected runner, missed an expected tool, or lacked useful compiler-cache stats.\nWhen the downloaded platform diagnostics include a sibling\n`diagnostics-manifest.json`, `summarizeDiagnosticsArtifacts()` carries a compact\n`diagnosticsManifest` section for that platform and verifies the manifest's\n`diagnostics.json` byte count and sha256. Missing or mismatched sidecar manifests\nincrement `diagnosticsManifestWarningCount`, so reviewers can distinguish\ndiagnostics sidecar drift from lifecycle warnings or build failures.\nThe same summary carries `diagnosticsContract` per platform and aggregates\n`diagnosticsContractWarningCount` when a downloaded `diagnostics.json` does not\nmatch `BUILDCHAIN_DIAGNOSTICS_CONTRACT`.\n\nThe diagnostics SDK also exports stable contract constants such as\n`BUILDCHAIN_DIAGNOSTICS_SUMMARY_CONTRACT`,\n`BUILDCHAIN_DIAGNOSTICS_MANIFEST_CONTRACT`,\n`BUILDCHAIN_PROCESS_SAMPLE_REPORT_CONTRACT`,\n`BUILDCHAIN_PROCESS_SAMPLE_SUMMARY_CONTRACT`, and\n`BUILDCHAIN_ANCHORED_PACKAGE_RELEASE_VALIDATION_CONTRACT` from\n`@kungfu-tech/buildchain/diagnostics`; consumers should compare against those\nconstants instead of hardcoding contract strings.\n\nThe CLI exposes the same aggregation for shell and workflow steps:\n\n```bash\nbuildchain diagnostics summary \\\n  .buildchain/artifacts/linux-x64/diagnostics.json \\\n  .buildchain/artifacts/macos-arm64/diagnostics.json \\\n  --output .buildchain/artifacts/diagnostics-summary.json \\\n  --json\n```\n\nOmit `--json` when the workflow log should show a compact platform table with\nlifecycle stages, artifact scan/upload time, total time, requested jobs,\nobserved active processes, warnings, and errors.\n\nFor long native build commands, the CLI can also sample the child process tree\nwhile preserving the wrapped command's exit code:\n\n```bash\nbuildchain sample process-tree \\\n  --label native-build \\\n  --interval-ms 15000 \\\n  --output .buildchain/diagnostics/process-samples.jsonl \\\n  --summary-output .buildchain/diagnostics/process-summary.json \\\n  -- \\\n  make -j20\n```\n\nThe JSONL sample file stores timestamped process-tree snapshots with full\nredacted command lines, command basenames, CPU percentages when available,\nelapsed time, and requested parallelism context. Unix and macOS snapshots read\nthe full `ps args` field instead of truncated `comm` names. Windows snapshots\nread `Win32_Process` command lines through PowerShell so the sampler no longer\nreturns an empty process set on Windows runners. The summary file records\nobserved concurrency, total sampled CPU, command categories, and top command\nbasenames. This is intended for diagnosing low-utilization tails such as\narchive/link phases without logging full environment dumps.\n\nThe lifecycle observability summary is stage-wide, not just final-step timing:\nwhen install and build write to the same Buildchain log, the final platform\nmanifest can show both stages and the slowest spans.\n\n## CLI Logging\n\n```bash\nbuildchain mark \\\n  --event native.configure \\\n  --phase configure \\\n  --component cmake \\\n  --attribute preset=release\n\nbuildchain span \\\n  --event native.build \\\n  --phase build \\\n  --component cmake \\\n  -- cmake --build build --config Release\n\nbuildchain log summary --json\nbuildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4\n```\n\nEvery event records a timestamp. `span` records duration and preserves the\nwrapped command's exit code.\n\n## Release Gate\n\nBuildchain's own binary distribution lane verifies required log events before\nuploading release assets. Consumers can apply the same pattern:\n\n```bash\nbuildchain verify observability-log .buildchain/logs/events.jsonl \\\n  --require-phase build \\\n  --require-phase package \\\n  --require-component workflow \\\n  --require-event native.build.start \\\n  --require-event native.build.end\n```\n\nThis makes missing instrumentation a release failure instead of a dashboard\nafterthought."
     },
     {
       "id": "manual:versioning",
@@ -2677,7 +2682,7 @@
       "path": "docs/toolkit-observability.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:239949a75ca81b6002a2e148f7028402dbd98c00e246acd8d0955855781206a1"
+      "digest": "sha256:ed6c2d0a7e76a5e4fc3fbee635966e462947f748a52d88e515fe4f95a630ac91"
     },
     {
       "id": "site-bundle-contract",

package/dist/site/capability-registry.json

@@ -216,8 +216,8 @@
       "counts": {
         "manualCount": 3,
         "pageCount": 3,
-        "cliCommandCount": 12,
-        "nodeApiCount": 5,
+        "cliCommandCount": 13,
+        "nodeApiCount": 6,
         "workflowCount": 0,
         "actionCount": 1
       },

package/dist/site/cli-registry.json

@@ -77,6 +77,18 @@
       ],
       "maturity": "stable"
     },
+    {
+      "id": "candidate",
+      "source": "bin/buildchain.mjs",
+      "usage": "buildchain candidate timeline --input <file-or-json> [--output <file>] [--json]",
+      "purpose": "Inspect source-bound candidate evidence command families.",
+      "capabilityGroup": "observability-diagnostics",
+      "audience": [
+        "agent",
+        "operator"
+      ],
+      "maturity": "stable"
+    },
     {
       "id": "collect",
       "source": "bin/buildchain.mjs",

package/dist/site/kfd-claims.json

@@ -21,13 +21,13 @@
     "contract": "kungfu-buildchain-public-surface-reverse-audit",
     "path": "dist/site/public-surface-audit.json",
     "status": "passed",
-    "sha256": "85d9b19de156773aab9a45cc7f8c201c0cebfc07a3f8d4ae902ca2d0e9fbfd86",
+    "sha256": "82b7e4e4827b8ab01397192a969e427bceaa344026b758719f8e1f59aa9b97fe",
     "summary": {
-      "cliCommandCount": 85,
+      "cliCommandCount": 86,
       "workflowCount": 51,
       "actionCount": 4,
       "sitePageCount": 52,
-      "docCommandRefCount": 264,
+      "docCommandRefCount": 265,
       "failureCount": 0
     },
     "auditBoundary": {
@@ -228,13 +228,13 @@
       "contract": "kungfu-buildchain-public-surface-reverse-audit",
       "path": "dist/site/public-surface-audit.json",
       "status": "passed",
-      "sha256": "85d9b19de156773aab9a45cc7f8c201c0cebfc07a3f8d4ae902ca2d0e9fbfd86",
+      "sha256": "82b7e4e4827b8ab01397192a969e427bceaa344026b758719f8e1f59aa9b97fe",
       "summary": {
-        "cliCommandCount": 85,
+        "cliCommandCount": 86,
         "workflowCount": 51,
         "actionCount": 4,
         "sitePageCount": 52,
-        "docCommandRefCount": 264,
+        "docCommandRefCount": 265,
         "failureCount": 0
       },
       "auditBoundary": {
@@ -1090,6 +1090,18 @@
           "public": true,
           "packageExport": "./buildchain-contract"
         },
+        {
+          "id": "export:./candidate-timeline",
+          "name": "@kungfu-tech/buildchain/candidate-timeline",
+          "kind": "package-export",
+          "sourcePath": "packages/core/candidate-timeline.js",
+          "evidencePath": "packages/core/candidate-timeline.js",
+          "availability": "shipped",
+          "visibility": "public",
+          "participantFacing": true,
+          "public": true,
+          "packageExport": "./candidate-timeline"
+        },
         {
           "id": "export:./controller-evidence",
           "name": "@kungfu-tech/buildchain/controller-evidence",
@@ -1686,6 +1698,18 @@
           "public": true,
           "reverseAuditSource": "bin/buildchain.mjs"
         },
+        {
+          "id": "cli:candidate",
+          "name": "buildchain candidate timeline --input <file-or-json> [--output <file>] [--json]",
+          "kind": "cli-command",
+          "sourcePath": "bin/buildchain.mjs",
+          "evidencePath": "bin/buildchain.mjs",
+          "availability": "shipped",
+          "visibility": "public",
+          "participantFacing": true,
+          "public": true,
+          "reverseAuditSource": "bin/buildchain.mjs"
+        },
         {
           "id": "cli:collect",
           "name": "buildchain collect",
@@ -4965,6 +4989,6 @@
         }
       }
     ],
-    "publicSurfaceCount": 316
+    "publicSurfaceCount": 318
   }
 }

package/dist/site/kfd-upstream-aggregate.json

@@ -4,7 +4,7 @@
   "product": {
     "id": "kungfu-tech-buildchain",
     "name": "@kungfu-tech/buildchain",
-    "version": "2.14.17-alpha.0",
+    "version": "2.14.17-alpha.2",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "source": {

package/dist/site/manual-registry.json

@@ -177,7 +177,7 @@
       "title": "Toolkit observability",
       "path": "docs/toolkit-observability.md",
       "plane": "use",
-      "digest": "sha256:239949a75ca81b6002a2e148f7028402dbd98c00e246acd8d0955855781206a1",
+      "digest": "sha256:ed6c2d0a7e76a5e4fc3fbee635966e462947f748a52d88e515fe4f95a630ac91",
       "capabilityGroup": "observability-diagnostics",
       "audience": [
         "developer",

package/dist/site/node-api-registry.json

@@ -8,7 +8,7 @@
       "specifier": "@kungfu-tech/buildchain",
       "export": ".",
       "target": "./packages/core/index.js",
-      "digest": "sha256:78c4f1885d1f619242f31e27b6cd4d1e21e0fd9c67fbe92f8b613abe9acdd3c1",
+      "digest": "sha256:1e02f99f2424f2850c0f264ad6a0bb75973144bc1099dba82d06ba0434c2b406",
       "summary": "Root toolkit export for Buildchain's public Node API.",
       "capabilityGroup": "api-cli-reference",
       "audience": [
@@ -47,7 +47,7 @@
       "specifier": "@kungfu-tech/buildchain/core",
       "export": "./core",
       "target": "./packages/core/index.js",
-      "digest": "sha256:78c4f1885d1f619242f31e27b6cd4d1e21e0fd9c67fbe92f8b613abe9acdd3c1",
+      "digest": "sha256:1e02f99f2424f2850c0f264ad6a0bb75973144bc1099dba82d06ba0434c2b406",
       "summary": "Alias for the root public toolkit export.",
       "capabilityGroup": "api-cli-reference",
       "audience": [
@@ -99,7 +99,7 @@
       "specifier": "@kungfu-tech/buildchain/buildchain-contract",
       "export": "./buildchain-contract",
       "target": "./packages/core/buildchain-contract.js",
-      "digest": "sha256:da92e920f6cc00dd5e21405f06580c2fa943eead3b755dc36b6c3a2381e68423",
+      "digest": "sha256:1e5f8a1741a0a98116e754ef0874337db4c1821bb7a153ab398009145509681c",
       "summary": "Runtime contract world and compatibility digest APIs for floating-ref drift checks.",
       "capabilityGroup": "governance-versioning",
       "audience": [
@@ -108,6 +108,19 @@
       ],
       "maturity": "stable"
     },
+    {
+      "specifier": "@kungfu-tech/buildchain/candidate-timeline",
+      "export": "./candidate-timeline",
+      "target": "./packages/core/candidate-timeline.js",
+      "digest": "sha256:d394d97d2165d2294ade84921e81e272c7d9e2a0a0673124531760f0fe428a1a",
+      "summary": "Source-bound candidate event normalization, per-attempt critical-path-safe aggregation, and compact reporting APIs.",
+      "capabilityGroup": "observability-diagnostics",
+      "audience": [
+        "developer",
+        "agent"
+      ],
+      "maturity": "stable"
+    },
     {
       "specifier": "@kungfu-tech/buildchain/controller-evidence",
       "export": "./controller-evidence",

package/dist/site/page-registry.json

@@ -1930,7 +1930,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/toolkit-observability.md",
-      "digest": "sha256:239949a75ca81b6002a2e148f7028402dbd98c00e246acd8d0955855781206a1",
+      "digest": "sha256:ed6c2d0a7e76a5e4fc3fbee635966e462947f748a52d88e515fe4f95a630ac91",
       "headings": [
         {
           "level": 1,
@@ -1947,6 +1947,11 @@
           "title": "Library API",
           "anchor": "library-api"
         },
+        {
+          "level": 2,
+          "title": "Candidate timelines and critical-path-safe timing",
+          "anchor": "candidate-timelines-and-critical-path-safe-timing"
+        },
         {
           "level": 2,
           "title": "Diagnostics API",
@@ -1963,7 +1968,7 @@
           "anchor": "release-gate"
         }
       ],
-      "markdown": "# Toolkit Observability\n\nBuildchain ships a small logging toolkit for repository workflows and project\nscripts. The goal is to separate time spent in Buildchain's framework from time\nspent in the consumer's own build, test, packaging, and publish steps.\n\n## Choose API or CLI\n\n`@kungfu-tech/buildchain` is not only a CLI package. It exports ESM toolkit APIs\nthat project scripts can import directly:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n```\n\nUse the API inside JavaScript or TypeScript build code. Do not spawn\n`buildchain`, download the standalone binary, or shell out through `npx` from\ncode that can import the package. The CLI is for GitHub Actions steps, shell\nscripts, and non-JavaScript tools.\n\nWhen a script runs inside `buildchain lifecycle run`, the lifecycle runner sets\n`BUILDCHAIN_LOG_PATH` and `BUILDCHAIN_LOG_RUN_ID`. Imported loggers pick up those\nenvironment variables automatically, so events emitted deep inside the build are\ngrouped into the same lifecycle summary.\n\nOutside a Buildchain lifecycle or GitHub Actions run, the logger defaults to\nconsole output unless a path is provided. Pass `path` when local scripts should\nwrite a reusable JSONL log:\n\n```js\nconst logger = createBuildchainLogger({\n  path: \".buildchain/logs/native-build.jsonl\",\n  source: \"user\",\n  component: \"native-build\",\n});\n```\n\n## Library API\n\n```js\nimport {\n  createBuildchainLogger,\n  verifyBuildchainLogEvents,\n} from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({\n  source: \"user\",\n  component: \"native-build\",\n});\n\nlogger.mark(\"configure.ready\", {\n  phase: \"configure\",\n  attributes: { preset: \"release\" },\n});\n\nawait logger.span(\"native.compile\", {\n  phase: \"build\",\n  attributes: { target: \"release\" },\n}, async () => {\n  await compile();\n});\n\nlogger.spanSync(\"native.archive\", {\n  phase: \"build\",\n  attributes: { tool: \"libtool\" },\n}, () => {\n  archiveStaticLibraries();\n});\n\nlogger.spawnSync(\"native.build\", \"make\", [\"-j20\"], {\n  stdio: \"inherit\",\n}, {\n  phase: \"build\",\n  attributes: { requestedJobs: 20 },\n});\n\nconst report = verifyBuildchainLogEvents({\n  path: logger.path,\n  minEvents: 3,\n  requirePhases: [\"configure\", \"build\"],\n  requireEvents: [\n    \"configure.ready\",\n    \"native.compile.start\",\n    \"native.compile.end\",\n  ],\n});\n\nif (!report.ok) {\n  throw new Error(\"Buildchain observability verification failed\");\n}\n```\n\nUse the API when a build script has internal stages that are invisible to the\nouter workflow. Keep secret values out of attributes; known sensitive keys are\nredacted, but callers should still avoid logging private material.\n\nCommonJS scripts should import Buildchain's ESM surfaces dynamically:\n\n```js\nconst { createBuildchainLogger } = await import(\"@kungfu-tech/buildchain/logging\");\nconst { collectRunnerDiagnostics } = await import(\"@kungfu-tech/buildchain/diagnostics\");\n```\n\n## Diagnostics API\n\nThe diagnostics surface collects local, non-telemetry build facts that are\nuseful when a native build is slow or flaky:\n\n```js\nimport {\n  collectBuildchainDiagnostics,\n  collectCacheDiagnostics,\n  collectCompilerCacheDiagnostics,\n  collectRunnerDiagnostics,\n  collectToolDiagnostics,\n  detectRequestedParallelism,\n  startProcessSampler,\n  summarizeDiagnosticsArtifacts,\n  summarizeLifecycleObservability,\n  summarizeProcessSamples,\n  validateAnchoredPackageRelease,\n  writeDiagnosticsArtifact,\n} from \"@kungfu-tech/buildchain/diagnostics\";\n\nconst lifecycleObservability = summarizeLifecycleObservability({\n  logPath: \".buildchain/logs/events.jsonl\",\n});\nconst buildCommand = \"make\";\nconst buildArgs = [\"-j20\"];\nconst requestedParallelism = detectRequestedParallelism({\n  command: buildCommand,\n  args: buildArgs,\n});\nconst processSampler = startProcessSampler({\n  intervalMs: 15000,\n  label: \"native-build\",\n  command: buildCommand,\n  args: buildArgs,\n});\n// Run the long native build while the sampler is active.\nconst processSummary = summarizeProcessSamples({\n  requestedParallelism: requestedParallelism.value,\n  samples: processSampler.stop(),\n});\nconst cacheDiagnostics = collectCacheDiagnostics({ cwd: process.cwd() });\n\nwriteDiagnosticsArtifact(\".buildchain/artifacts/diagnostics.json\", {\n  contract: \"consumer-build-diagnostics\",\n  buildchain: collectBuildchainDiagnostics({ cwd: process.cwd() }),\n  runner: collectRunnerDiagnostics(),\n  tools: collectToolDiagnostics({ cwd: process.cwd() }),\n  cache: cacheDiagnostics,\n  lifecycleObservability,\n  process: processSummary,\n});\n```\n\n`collectCacheDiagnostics()` includes package-manager/workspace context, selected\ncache directory stats, and compiler-cache stats from `ccache --show-stats\n--json` plus `sccache --show-stats --stats-format json` when those tools are\npresent. If a ccache build does not support JSON stats, Buildchain falls back to\nplain `ccache --show-stats` and parses the text counters. Missing cache tools\nare recorded as unavailable instead of failing the diagnostics artifact. Call\n`collectCompilerCacheDiagnostics()` directly when a consumer script only needs\ncompiler cache data. Native diagnostics also expose `compilerCaches` and\n`nativeCacheDirs` as top-level fields in each diagnostics artifact and aggregate\nsummary, so reviewers do not have to dig through nested cache sections first.\n\nProcess samples are intentionally summarized before they become long-lived\nartifacts. The summary records requested parallelism, the source of that value\n(`command`, `process-tree`, `env:MAKEFLAGS`,\n`env:CMAKE_BUILD_PARALLEL_LEVEL`, or `explicit`), observed active process\nconcurrency, elapsed sample time, total sampled CPU, and conservative command\ncategories such as `compiler`, `archive`, `linker`, `build-tool`, and `cache`.\nThe sampler detects common `make -j N`, `ninja -j N`, CMake/MSBuild/Xcode job\nflags, and MAKEFLAGS. This lets native projects distinguish \"we asked for\n`make -j20`\" from \"the build graph only kept two active compiler or archive\nchildren busy during the sampled window\" without storing environment dumps.\n\nNative repositories can opt into a reusable diagnostics profile in\n`buildchain.toml`:\n\n```toml\n[diagnostics.native]\nenabled = true\nsample_process_tree = true\ncompiler_cache = \"auto\"\nexpected_tools = [\"ccache\", \"sccache\", \"clang\", \"cl\", \"cmake\", \"ninja\"]\nartifact_dirs = [\"build\", \"dist\", \"build/Release\"]\ncache_dirs = [\".ccache\", \".sccache\"]\n```\n\nWhen enabled, diagnostics artifacts include the normalized profile, selected\ntool versions, compiler-cache stats, and configured artifact/cache directory\nstats. The profile is data-driven: Buildchain does not assume a specific\nproject such as libnode. The reusable build workflow also exposes\n`sample-process-tree`, which wraps the build lifecycle with the process sampler\nand carries the generated summary into the final diagnostics artifact. Custom\nworkflows can call `buildchain sample process-tree` directly when they need a\ndifferent command boundary.\n\nAnchored/manual package projects can also run one higher-level release-shape\ncheck instead of assembling lower-level config calls:\n\n```js\nconst anchoredReport = validateAnchoredPackageRelease({\n  cwd: process.cwd(),\n  requireManifest: true,\n  requirePackageSetOrder: \"platforms-first-main-last\",\n  requireTrustedPublishing: true,\n});\n\nif (!anchoredReport.ok) {\n  throw new Error(\"Anchored package release contract failed\");\n}\n```\n\nIn an actual publish job, make that check source-lock aware:\n\n```js\nconst publishReady = validateAnchoredPackageRelease({\n  cwd: process.cwd(),\n  requirePublishGateSourceLock: true,\n});\n```\n\nThe source-lock inputs are read from `BUILDCHAIN_PUBLISH_SOURCE_REF`,\n`BUILDCHAIN_PUBLISH_SOURCE_SHA`, and `BUILDCHAIN_PUBLISH_SOURCE_LOCKED`, which\nthe reusable build workflow emits after resolving `publish-source-ref`. That\nturns direct channel-branch publication from `alpha/*` or `release/*` into a\nhard failure, while `publish-gate/alpha/<line>/<version>` and\n`publish-gate/release/<line>/<version>` also validate the requested consumer\nversion against configured version files and the anchor manifest.\n\n`buildchain lifecycle run` writes this small diagnostics artifact next to the\nplatform manifest by default. The per-platform diagnostics upload includes the\ncompact `diagnostics.json`, `diagnostics-manifest.json`, lifecycle\n`events.jsonl`, and, when process sampling is enabled, copied\n`process-summary.json` and `process-samples.jsonl` sidecars. The sidecar\nmanifest records each uploaded diagnostics file with its relative path, byte\ncount, and sha256 hash. It is intended to stay small enough to download without\nfetching large binary packages, and it should not include full environment dumps\nor secret-looking values.\n\nUse `summarizeDiagnosticsArtifacts()` when a matrix build uploads one\ndiagnostics artifact per platform. The summary keeps each platform's lifecycle\nstage table, adds a lifecycle total duration, carries the top slow spans, and\naggregates warning/error counts plus the slowest platforms. Per-platform rows\nalso include compact runner facts, checked tool versions/missing tools, package\nmanager/cache directory details, compiler cache availability, and a compact\nprocess sampler view with requested parallelism, observed max active processes,\nthe ratio between them, sample count, process categories, and top sampled\ncommand basenames. That gives release reviewers a small cross-platform timing,\nrunner, tool, cache, and concurrency view without downloading full build outputs\nor process sidecars.\n\nThe reusable build workflow writes that rollup as `diagnostics-summary.json` and\nuploads it in a separate aggregate diagnostics summary artifact. Consumers can\nread the `build-diagnostics-summary-artifact` output when they need only timing,\nwarning/error, runner, cache, and process-sampler context instead of the build\nsummary or binary artifacts. Per-platform rows keep the diagnostics `links`\nobject, including the binary artifact name, manifest artifact name, diagnostics\nartifact name, platform id, diagnostics sidecar manifest path, manifest path,\nsummary path, and process sidecar paths when present. They also keep compact\nrunner/tool/cache summaries so reviewers can tell whether a slow row ran on the\nexpected runner, missed an expected tool, or lacked useful compiler-cache stats.\nWhen the downloaded platform diagnostics include a sibling\n`diagnostics-manifest.json`, `summarizeDiagnosticsArtifacts()` carries a compact\n`diagnosticsManifest` section for that platform and verifies the manifest's\n`diagnostics.json` byte count and sha256. Missing or mismatched sidecar manifests\nincrement `diagnosticsManifestWarningCount`, so reviewers can distinguish\ndiagnostics sidecar drift from lifecycle warnings or build failures.\nThe same summary carries `diagnosticsContract` per platform and aggregates\n`diagnosticsContractWarningCount` when a downloaded `diagnostics.json` does not\nmatch `BUILDCHAIN_DIAGNOSTICS_CONTRACT`.\n\nThe diagnostics SDK also exports stable contract constants such as\n`BUILDCHAIN_DIAGNOSTICS_SUMMARY_CONTRACT`,\n`BUILDCHAIN_DIAGNOSTICS_MANIFEST_CONTRACT`,\n`BUILDCHAIN_PROCESS_SAMPLE_REPORT_CONTRACT`,\n`BUILDCHAIN_PROCESS_SAMPLE_SUMMARY_CONTRACT`, and\n`BUILDCHAIN_ANCHORED_PACKAGE_RELEASE_VALIDATION_CONTRACT` from\n`@kungfu-tech/buildchain/diagnostics`; consumers should compare against those\nconstants instead of hardcoding contract strings.\n\nThe CLI exposes the same aggregation for shell and workflow steps:\n\n```bash\nbuildchain diagnostics summary \\\n  .buildchain/artifacts/linux-x64/diagnostics.json \\\n  .buildchain/artifacts/macos-arm64/diagnostics.json \\\n  --output .buildchain/artifacts/diagnostics-summary.json \\\n  --json\n```\n\nOmit `--json` when the workflow log should show a compact platform table with\nlifecycle stages, artifact scan/upload time, total time, requested jobs,\nobserved active processes, warnings, and errors.\n\nFor long native build commands, the CLI can also sample the child process tree\nwhile preserving the wrapped command's exit code:\n\n```bash\nbuildchain sample process-tree \\\n  --label native-build \\\n  --interval-ms 15000 \\\n  --output .buildchain/diagnostics/process-samples.jsonl \\\n  --summary-output .buildchain/diagnostics/process-summary.json \\\n  -- \\\n  make -j20\n```\n\nThe JSONL sample file stores timestamped process-tree snapshots with full\nredacted command lines, command basenames, CPU percentages when available,\nelapsed time, and requested parallelism context. Unix and macOS snapshots read\nthe full `ps args` field instead of truncated `comm` names. Windows snapshots\nread `Win32_Process` command lines through PowerShell so the sampler no longer\nreturns an empty process set on Windows runners. The summary file records\nobserved concurrency, total sampled CPU, command categories, and top command\nbasenames. This is intended for diagnosing low-utilization tails such as\narchive/link phases without logging full environment dumps.\n\nThe lifecycle observability summary is stage-wide, not just final-step timing:\nwhen install and build write to the same Buildchain log, the final platform\nmanifest can show both stages and the slowest spans.\n\n## CLI Logging\n\n```bash\nbuildchain mark \\\n  --event native.configure \\\n  --phase configure \\\n  --component cmake \\\n  --attribute preset=release\n\nbuildchain span \\\n  --event native.build \\\n  --phase build \\\n  --component cmake \\\n  -- cmake --build build --config Release\n\nbuildchain log summary --json\nbuildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4\n```\n\nEvery event records a timestamp. `span` records duration and preserves the\nwrapped command's exit code.\n\n## Release Gate\n\nBuildchain's own binary distribution lane verifies required log events before\nuploading release assets. Consumers can apply the same pattern:\n\n```bash\nbuildchain verify observability-log .buildchain/logs/events.jsonl \\\n  --require-phase build \\\n  --require-phase package \\\n  --require-component workflow \\\n  --require-event native.build.start \\\n  --require-event native.build.end\n```\n\nThis makes missing instrumentation a release failure instead of a dashboard\nafterthought."
+      "markdown": "# Toolkit Observability\n\nBuildchain ships a small logging toolkit for repository workflows and project\nscripts. The goal is to separate time spent in Buildchain's framework from time\nspent in the consumer's own build, test, packaging, and publish steps.\n\n## Choose API or CLI\n\n`@kungfu-tech/buildchain` is not only a CLI package. It exports ESM toolkit APIs\nthat project scripts can import directly:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n```\n\nUse the API inside JavaScript or TypeScript build code. Do not spawn\n`buildchain`, download the standalone binary, or shell out through `npx` from\ncode that can import the package. The CLI is for GitHub Actions steps, shell\nscripts, and non-JavaScript tools.\n\nWhen a script runs inside `buildchain lifecycle run`, the lifecycle runner sets\n`BUILDCHAIN_LOG_PATH` and `BUILDCHAIN_LOG_RUN_ID`. Imported loggers pick up those\nenvironment variables automatically, so events emitted deep inside the build are\ngrouped into the same lifecycle summary.\n\nOutside a Buildchain lifecycle or GitHub Actions run, the logger defaults to\nconsole output unless a path is provided. Pass `path` when local scripts should\nwrite a reusable JSONL log:\n\n```js\nconst logger = createBuildchainLogger({\n  path: \".buildchain/logs/native-build.jsonl\",\n  source: \"user\",\n  component: \"native-build\",\n});\n```\n\n## Library API\n\n```js\nimport {\n  createBuildchainLogger,\n  verifyBuildchainLogEvents,\n} from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({\n  source: \"user\",\n  component: \"native-build\",\n});\n\nlogger.mark(\"configure.ready\", {\n  phase: \"configure\",\n  attributes: { preset: \"release\" },\n});\n\nawait logger.span(\"native.compile\", {\n  phase: \"build\",\n  attributes: { target: \"release\" },\n}, async () => {\n  await compile();\n});\n\nlogger.spanSync(\"native.archive\", {\n  phase: \"build\",\n  attributes: { tool: \"libtool\" },\n}, () => {\n  archiveStaticLibraries();\n});\n\nlogger.spawnSync(\"native.build\", \"make\", [\"-j20\"], {\n  stdio: \"inherit\",\n}, {\n  phase: \"build\",\n  attributes: { requestedJobs: 20 },\n});\n\nconst report = verifyBuildchainLogEvents({\n  path: logger.path,\n  minEvents: 3,\n  requirePhases: [\"configure\", \"build\"],\n  requireEvents: [\n    \"configure.ready\",\n    \"native.compile.start\",\n    \"native.compile.end\",\n  ],\n});\n\nif (!report.ok) {\n  throw new Error(\"Buildchain observability verification failed\");\n}\n```\n\nUse the API when a build script has internal stages that are invisible to the\nouter workflow. Keep secret values out of attributes; known sensitive keys are\nredacted, but callers should still avoid logging private material.\n\n## Candidate timelines and critical-path-safe timing\n\nLifecycle diagnostics retain their existing summed-duration tables for\ncompatibility. Do not interpret those tables as elapsed time when spans are\nnested or jobs run in parallel. Use the candidate timeline contract when a\nchange must be followed from pull-request admission through Merge Queue attempts\nto its final merge:\n\n```js\nimport {\n  createCandidateTimeline,\n  formatCandidateTimelineReport,\n} from \"@kungfu-tech/buildchain/candidate-timeline\";\n\nconst timeline = createCandidateTimeline({\n  candidate: {\n    repository: \"owner/repository\",\n    baseBranch: \"dev/v4/v4.0\",\n    sourceSha,\n    pullRequest: 123,\n  },\n  events,\n});\n\nconsole.log(formatCandidateTimelineReport(timeline));\n```\n\nEach event binds a stable event id to one attempt id and may also bind a Gate\nid, merge-group SHA, workflow run, platform, partition, cache outcome, execution\nboundary, and parent span. Terminal execution states (`success`, `failure`, and\n`cancelled`) require start and completion timestamps. Non-executed states use\n`skipped`, `dependency-blocked`, or `not-required` without invented timings.\nRecord the clock and timestamp precision explicitly: GitHub Actions timestamps\nare normally provider wall-clock observations with one-second precision, while\nan in-process span may also carry a monotonic duration with millisecond or\nbetter precision.\n\nThe `buildchain.candidate-timeline/v1` artifact reports an independent critical\npath for every attempt. Its critical-path duration is the attempt's observed\nwall-clock envelope; its active duration and per-phase durations are interval\nunions. This prevents nested or parallel spans from being added twice, and it\ndoes not combine a failed or dequeued attempt with a later retry. Missing\nrequired measurements make that attempt `incomplete` instead of producing fake\nprecision.\n\nShell and workflow consumers can generate the same machine artifact plus a\ncompact report:\n\n```sh\nbuildchain candidate timeline \\\n  --input .buildchain/candidate-timeline-input.json \\\n  --output .buildchain/candidate-timeline.json\n```\n\nThe input and output should contain only bounded correlation facts and timing\nreceipts. Do not include tokens, environment dumps, full commands, raw process\ndumps, or private absolute paths.\n\nCommonJS scripts should import Buildchain's ESM surfaces dynamically:\n\n```js\nconst { createBuildchainLogger } = await import(\"@kungfu-tech/buildchain/logging\");\nconst { collectRunnerDiagnostics } = await import(\"@kungfu-tech/buildchain/diagnostics\");\n```\n\n## Diagnostics API\n\nThe diagnostics surface collects local, non-telemetry build facts that are\nuseful when a native build is slow or flaky:\n\n```js\nimport {\n  collectBuildchainDiagnostics,\n  collectCacheDiagnostics,\n  collectCompilerCacheDiagnostics,\n  collectRunnerDiagnostics,\n  collectToolDiagnostics,\n  detectRequestedParallelism,\n  startProcessSampler,\n  summarizeDiagnosticsArtifacts,\n  summarizeLifecycleObservability,\n  summarizeProcessSamples,\n  validateAnchoredPackageRelease,\n  writeDiagnosticsArtifact,\n} from \"@kungfu-tech/buildchain/diagnostics\";\n\nconst lifecycleObservability = summarizeLifecycleObservability({\n  logPath: \".buildchain/logs/events.jsonl\",\n});\nconst buildCommand = \"make\";\nconst buildArgs = [\"-j20\"];\nconst requestedParallelism = detectRequestedParallelism({\n  command: buildCommand,\n  args: buildArgs,\n});\nconst processSampler = startProcessSampler({\n  intervalMs: 15000,\n  label: \"native-build\",\n  command: buildCommand,\n  args: buildArgs,\n});\n// Run the long native build while the sampler is active.\nconst processSummary = summarizeProcessSamples({\n  requestedParallelism: requestedParallelism.value,\n  samples: processSampler.stop(),\n});\nconst cacheDiagnostics = collectCacheDiagnostics({ cwd: process.cwd() });\n\nwriteDiagnosticsArtifact(\".buildchain/artifacts/diagnostics.json\", {\n  contract: \"consumer-build-diagnostics\",\n  buildchain: collectBuildchainDiagnostics({ cwd: process.cwd() }),\n  runner: collectRunnerDiagnostics(),\n  tools: collectToolDiagnostics({ cwd: process.cwd() }),\n  cache: cacheDiagnostics,\n  lifecycleObservability,\n  process: processSummary,\n});\n```\n\n`collectCacheDiagnostics()` includes package-manager/workspace context, selected\ncache directory stats, and compiler-cache stats from `ccache --show-stats\n--json` plus `sccache --show-stats --stats-format json` when those tools are\npresent. If a ccache build does not support JSON stats, Buildchain falls back to\nplain `ccache --show-stats` and parses the text counters. Missing cache tools\nare recorded as unavailable instead of failing the diagnostics artifact. Call\n`collectCompilerCacheDiagnostics()` directly when a consumer script only needs\ncompiler cache data. Native diagnostics also expose `compilerCaches` and\n`nativeCacheDirs` as top-level fields in each diagnostics artifact and aggregate\nsummary, so reviewers do not have to dig through nested cache sections first.\n\nProcess samples are intentionally summarized before they become long-lived\nartifacts. The summary records requested parallelism, the source of that value\n(`command`, `process-tree`, `env:MAKEFLAGS`,\n`env:CMAKE_BUILD_PARALLEL_LEVEL`, or `explicit`), observed active process\nconcurrency, elapsed sample time, total sampled CPU, and conservative command\ncategories such as `compiler`, `archive`, `linker`, `build-tool`, and `cache`.\nThe sampler detects common `make -j N`, `ninja -j N`, CMake/MSBuild/Xcode job\nflags, and MAKEFLAGS. This lets native projects distinguish \"we asked for\n`make -j20`\" from \"the build graph only kept two active compiler or archive\nchildren busy during the sampled window\" without storing environment dumps.\n\nNative repositories can opt into a reusable diagnostics profile in\n`buildchain.toml`:\n\n```toml\n[diagnostics.native]\nenabled = true\nsample_process_tree = true\ncompiler_cache = \"auto\"\nexpected_tools = [\"ccache\", \"sccache\", \"clang\", \"cl\", \"cmake\", \"ninja\"]\nartifact_dirs = [\"build\", \"dist\", \"build/Release\"]\ncache_dirs = [\".ccache\", \".sccache\"]\n```\n\nWhen enabled, diagnostics artifacts include the normalized profile, selected\ntool versions, compiler-cache stats, and configured artifact/cache directory\nstats. The profile is data-driven: Buildchain does not assume a specific\nproject such as libnode. The reusable build workflow also exposes\n`sample-process-tree`, which wraps the build lifecycle with the process sampler\nand carries the generated summary into the final diagnostics artifact. Custom\nworkflows can call `buildchain sample process-tree` directly when they need a\ndifferent command boundary.\n\nAnchored/manual package projects can also run one higher-level release-shape\ncheck instead of assembling lower-level config calls:\n\n```js\nconst anchoredReport = validateAnchoredPackageRelease({\n  cwd: process.cwd(),\n  requireManifest: true,\n  requirePackageSetOrder: \"platforms-first-main-last\",\n  requireTrustedPublishing: true,\n});\n\nif (!anchoredReport.ok) {\n  throw new Error(\"Anchored package release contract failed\");\n}\n```\n\nIn an actual publish job, make that check source-lock aware:\n\n```js\nconst publishReady = validateAnchoredPackageRelease({\n  cwd: process.cwd(),\n  requirePublishGateSourceLock: true,\n});\n```\n\nThe source-lock inputs are read from `BUILDCHAIN_PUBLISH_SOURCE_REF`,\n`BUILDCHAIN_PUBLISH_SOURCE_SHA`, and `BUILDCHAIN_PUBLISH_SOURCE_LOCKED`, which\nthe reusable build workflow emits after resolving `publish-source-ref`. That\nturns direct channel-branch publication from `alpha/*` or `release/*` into a\nhard failure, while `publish-gate/alpha/<line>/<version>` and\n`publish-gate/release/<line>/<version>` also validate the requested consumer\nversion against configured version files and the anchor manifest.\n\n`buildchain lifecycle run` writes this small diagnostics artifact next to the\nplatform manifest by default. The per-platform diagnostics upload includes the\ncompact `diagnostics.json`, `diagnostics-manifest.json`, lifecycle\n`events.jsonl`, and, when process sampling is enabled, copied\n`process-summary.json` and `process-samples.jsonl` sidecars. The sidecar\nmanifest records each uploaded diagnostics file with its relative path, byte\ncount, and sha256 hash. It is intended to stay small enough to download without\nfetching large binary packages, and it should not include full environment dumps\nor secret-looking values.\n\nUse `summarizeDiagnosticsArtifacts()` when a matrix build uploads one\ndiagnostics artifact per platform. The summary keeps each platform's lifecycle\nstage table, adds a lifecycle total duration, carries the top slow spans, and\naggregates warning/error counts plus the slowest platforms. Per-platform rows\nalso include compact runner facts, checked tool versions/missing tools, package\nmanager/cache directory details, compiler cache availability, and a compact\nprocess sampler view with requested parallelism, observed max active processes,\nthe ratio between them, sample count, process categories, and top sampled\ncommand basenames. That gives release reviewers a small cross-platform timing,\nrunner, tool, cache, and concurrency view without downloading full build outputs\nor process sidecars.\n\nThe reusable build workflow writes that rollup as `diagnostics-summary.json` and\nuploads it in a separate aggregate diagnostics summary artifact. Consumers can\nread the `build-diagnostics-summary-artifact` output when they need only timing,\nwarning/error, runner, cache, and process-sampler context instead of the build\nsummary or binary artifacts. Per-platform rows keep the diagnostics `links`\nobject, including the binary artifact name, manifest artifact name, diagnostics\nartifact name, platform id, diagnostics sidecar manifest path, manifest path,\nsummary path, and process sidecar paths when present. They also keep compact\nrunner/tool/cache summaries so reviewers can tell whether a slow row ran on the\nexpected runner, missed an expected tool, or lacked useful compiler-cache stats.\nWhen the downloaded platform diagnostics include a sibling\n`diagnostics-manifest.json`, `summarizeDiagnosticsArtifacts()` carries a compact\n`diagnosticsManifest` section for that platform and verifies the manifest's\n`diagnostics.json` byte count and sha256. Missing or mismatched sidecar manifests\nincrement `diagnosticsManifestWarningCount`, so reviewers can distinguish\ndiagnostics sidecar drift from lifecycle warnings or build failures.\nThe same summary carries `diagnosticsContract` per platform and aggregates\n`diagnosticsContractWarningCount` when a downloaded `diagnostics.json` does not\nmatch `BUILDCHAIN_DIAGNOSTICS_CONTRACT`.\n\nThe diagnostics SDK also exports stable contract constants such as\n`BUILDCHAIN_DIAGNOSTICS_SUMMARY_CONTRACT`,\n`BUILDCHAIN_DIAGNOSTICS_MANIFEST_CONTRACT`,\n`BUILDCHAIN_PROCESS_SAMPLE_REPORT_CONTRACT`,\n`BUILDCHAIN_PROCESS_SAMPLE_SUMMARY_CONTRACT`, and\n`BUILDCHAIN_ANCHORED_PACKAGE_RELEASE_VALIDATION_CONTRACT` from\n`@kungfu-tech/buildchain/diagnostics`; consumers should compare against those\nconstants instead of hardcoding contract strings.\n\nThe CLI exposes the same aggregation for shell and workflow steps:\n\n```bash\nbuildchain diagnostics summary \\\n  .buildchain/artifacts/linux-x64/diagnostics.json \\\n  .buildchain/artifacts/macos-arm64/diagnostics.json \\\n  --output .buildchain/artifacts/diagnostics-summary.json \\\n  --json\n```\n\nOmit `--json` when the workflow log should show a compact platform table with\nlifecycle stages, artifact scan/upload time, total time, requested jobs,\nobserved active processes, warnings, and errors.\n\nFor long native build commands, the CLI can also sample the child process tree\nwhile preserving the wrapped command's exit code:\n\n```bash\nbuildchain sample process-tree \\\n  --label native-build \\\n  --interval-ms 15000 \\\n  --output .buildchain/diagnostics/process-samples.jsonl \\\n  --summary-output .buildchain/diagnostics/process-summary.json \\\n  -- \\\n  make -j20\n```\n\nThe JSONL sample file stores timestamped process-tree snapshots with full\nredacted command lines, command basenames, CPU percentages when available,\nelapsed time, and requested parallelism context. Unix and macOS snapshots read\nthe full `ps args` field instead of truncated `comm` names. Windows snapshots\nread `Win32_Process` command lines through PowerShell so the sampler no longer\nreturns an empty process set on Windows runners. The summary file records\nobserved concurrency, total sampled CPU, command categories, and top command\nbasenames. This is intended for diagnosing low-utilization tails such as\narchive/link phases without logging full environment dumps.\n\nThe lifecycle observability summary is stage-wide, not just final-step timing:\nwhen install and build write to the same Buildchain log, the final platform\nmanifest can show both stages and the slowest spans.\n\n## CLI Logging\n\n```bash\nbuildchain mark \\\n  --event native.configure \\\n  --phase configure \\\n  --component cmake \\\n  --attribute preset=release\n\nbuildchain span \\\n  --event native.build \\\n  --phase build \\\n  --component cmake \\\n  -- cmake --build build --config Release\n\nbuildchain log summary --json\nbuildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4\n```\n\nEvery event records a timestamp. `span` records duration and preserves the\nwrapped command's exit code.\n\n## Release Gate\n\nBuildchain's own binary distribution lane verifies required log events before\nuploading release assets. Consumers can apply the same pattern:\n\n```bash\nbuildchain verify observability-log .buildchain/logs/events.jsonl \\\n  --require-phase build \\\n  --require-phase package \\\n  --require-component workflow \\\n  --require-event native.build.start \\\n  --require-event native.build.end\n```\n\nThis makes missing instrumentation a release failure instead of a dashboard\nafterthought."
     },
     {
       "id": "manual:versioning",

package/dist/site/public-surface-audit.json

@@ -3,11 +3,11 @@
   "contract": "kungfu-buildchain-public-surface-reverse-audit",
   "status": "passed",
   "summary": {
-    "cliCommandCount": 85,
+    "cliCommandCount": 86,
     "workflowCount": 51,
     "actionCount": 4,
     "sitePageCount": 52,
-    "docCommandRefCount": 264,
+    "docCommandRefCount": 265,
     "failureCount": 0
   },
   "enumerated": {
@@ -42,6 +42,11 @@
         "source": "bin/buildchain.mjs",
         "usage": "buildchain facts module [--cwd <dir>] [--module <id>] [--module-root <path>]"
       },
+      {
+        "id": "candidate",
+        "source": "bin/buildchain.mjs",
+        "usage": "buildchain candidate timeline --input <file-or-json> [--output <file>] [--json]"
+      },
       {
         "id": "collect",
         "source": "bin/buildchain.mjs",
@@ -2595,6 +2600,11 @@
         "path": "docs/cli.md",
         "command": "buildchain facts verify --fact"
       },
+      {
+        "id": "candidate",
+        "path": "docs/toolkit-observability.md",
+        "command": "buildchain candidate timeline"
+      },
       {
         "id": "collect-github-release",
         "path": "docs/binary-distribution.md",
@@ -3736,9 +3746,9 @@
     "cliRegistryPath": "dist/site/cli-registry.json",
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
-    "cliRegistryDigest": "07802d410c2111838c8c5f3d93392d7e8205ba64ab4c76ce594f09864ab5baaf",
+    "cliRegistryDigest": "cc76cd0f061103d8ab78ee97dd0b7f0d28d64489f79b7ed06c94d8fef28bc200",
     "workflowRegistryDigest": "a954f67672292e16be1f4f663a98d0c69285f7359a43d5d6333b3ffcf6463c35",
-    "pageRegistryDigest": "75384a857698af54b7a739b40b6eefe0bb641e90bae584c47dd1e2c0b7aa8b2b"
+    "pageRegistryDigest": "273a1baa5db4ae0b719c76b7f42dc055941f616b20947a38eb5eb48f5af1c431"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-07-22T15:29:55.552Z",
-  "publishedAt": "2026-07-22T15:29:55.552Z",
+  "generatedAt": "2026-07-23T00:58:45.650Z",
+  "publishedAt": "2026-07-23T00:58:45.650Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "a013078fdf88b5b850e48e93faf58de582130440",
+  "sourceRevision": "d67ebd6fcb075c00ef286cee9f2bc1f03633af13",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.14.17-alpha.0",
+    "version": "2.14.17-alpha.2",
     "versionSource": "package.json#version"
   },
   "sourceKind": "package-site-bundle",

package/dist/site/release-provenance.json

@@ -16,6 +16,7 @@
       "./artifact-verification-envelope": "./packages/core/artifact-verification-envelope.js",
       "./anchored-version-material": "./packages/core/anchored-version-material.js",
       "./buildchain-contract": "./packages/core/buildchain-contract.js",
+      "./candidate-timeline": "./packages/core/candidate-timeline.js",
       "./controller-evidence": "./packages/core/controller-evidence.js",
       "./diagnostics": "./packages/core/diagnostics.js",
       "./homebrew": "./packages/core/homebrew.js",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-22T15:29:55.552Z",
-  "publishedAt": "2026-07-22T15:29:55.552Z",
+  "generatedAt": "2026-07-23T00:58:45.650Z",
+  "publishedAt": "2026-07-23T00:58:45.650Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "a013078fdf88b5b850e48e93faf58de582130440",
+  "sourceRevision": "d67ebd6fcb075c00ef286cee9f2bc1f03633af13",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.14.17-alpha.0",
+    "version": "2.14.17-alpha.2",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -149,7 +149,7 @@
       "path": "docs/toolkit-observability.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:239949a75ca81b6002a2e148f7028402dbd98c00e246acd8d0955855781206a1"
+      "digest": "sha256:ed6c2d0a7e76a5e4fc3fbee635966e462947f748a52d88e515fe4f95a630ac91"
     },
     {
       "id": "site-bundle-contract",

package/docs/toolkit-observability.md

@@ -94,6 +94,64 @@ Use the API when a build script has internal stages that are invisible to the
 outer workflow. Keep secret values out of attributes; known sensitive keys are
 redacted, but callers should still avoid logging private material.
 
+## Candidate timelines and critical-path-safe timing
+
+Lifecycle diagnostics retain their existing summed-duration tables for
+compatibility. Do not interpret those tables as elapsed time when spans are
+nested or jobs run in parallel. Use the candidate timeline contract when a
+change must be followed from pull-request admission through Merge Queue attempts
+to its final merge:
+
+```js
+import {
+  createCandidateTimeline,
+  formatCandidateTimelineReport,
+} from "@kungfu-tech/buildchain/candidate-timeline";
+
+const timeline = createCandidateTimeline({
+  candidate: {
+    repository: "owner/repository",
+    baseBranch: "dev/v4/v4.0",
+    sourceSha,
+    pullRequest: 123,
+  },
+  events,
+});
+
+console.log(formatCandidateTimelineReport(timeline));
+```
+
+Each event binds a stable event id to one attempt id and may also bind a Gate
+id, merge-group SHA, workflow run, platform, partition, cache outcome, execution
+boundary, and parent span. Terminal execution states (`success`, `failure`, and
+`cancelled`) require start and completion timestamps. Non-executed states use
+`skipped`, `dependency-blocked`, or `not-required` without invented timings.
+Record the clock and timestamp precision explicitly: GitHub Actions timestamps
+are normally provider wall-clock observations with one-second precision, while
+an in-process span may also carry a monotonic duration with millisecond or
+better precision.
+
+The `buildchain.candidate-timeline/v1` artifact reports an independent critical
+path for every attempt. Its critical-path duration is the attempt's observed
+wall-clock envelope; its active duration and per-phase durations are interval
+unions. This prevents nested or parallel spans from being added twice, and it
+does not combine a failed or dequeued attempt with a later retry. Missing
+required measurements make that attempt `incomplete` instead of producing fake
+precision.
+
+Shell and workflow consumers can generate the same machine artifact plus a
+compact report:
+
+```sh
+buildchain candidate timeline \
+  --input .buildchain/candidate-timeline-input.json \
+  --output .buildchain/candidate-timeline.json
+```
+
+The input and output should contain only bounded correlation facts and timing
+receipts. Do not include tokens, environment dumps, full commands, raw process
+dumps, or private absolute paths.
+
 CommonJS scripts should import Buildchain's ESM surfaces dynamically:
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.14.17-alpha.0",
+  "version": "2.14.17-alpha.2",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -19,6 +19,7 @@
     "./artifact-verification-envelope": "./packages/core/artifact-verification-envelope.js",
     "./anchored-version-material": "./packages/core/anchored-version-material.js",
     "./buildchain-contract": "./packages/core/buildchain-contract.js",
+    "./candidate-timeline": "./packages/core/candidate-timeline.js",
     "./controller-evidence": "./packages/core/controller-evidence.js",
     "./diagnostics": "./packages/core/diagnostics.js",
     "./homebrew": "./packages/core/homebrew.js",

package/packages/core/buildchain-contract.js

@@ -351,6 +351,9 @@ export function createBuildchainContractWorld({
         "publish transactions can require a resolved publish-gate source lock to prevent floating-ref drift",
         "semver GitHub Releases are created or updated only after transaction completion, with prerelease/latest metadata bound to the authoritative publication channel and tag syntax retained as the fallback for ordinary callers",
       ],
+      compatibleBreakingDigests: [
+        "sha256:a59f0910e6df842e7699139472e5dd69ac2fdd7f7213bf2cb346d1d622556874",
+      ],
     }),
     surface(root, {
       id: "report-buildchain-issue-action",
@@ -758,7 +761,11 @@ export function evaluateBuildchainContractLock({
       reasons.push(`surface removed: ${oldSurface.id}`);
       continue;
     }
-    if (nextSurface.breakingDigest !== oldSurface.breakingDigest) {
+    const compatibleBreakingDigests = new Set(nextSurface.compatibleBreakingDigests || []);
+    if (
+      nextSurface.breakingDigest !== oldSurface.breakingDigest
+      && !compatibleBreakingDigests.has(oldSurface.breakingDigest)
+    ) {
       reasons.push(`surface breaking digest changed: ${oldSurface.id}`);
     }
   }

package/packages/core/candidate-timeline.js

@@ -0,0 +1,349 @@
+export const BUILDCHAIN_CANDIDATE_TIMELINE_CONTRACT =
+  "buildchain.candidate-timeline/v1";
+export const BUILDCHAIN_CANDIDATE_TIMELINE_EVENT_CONTRACT =
+  "buildchain.candidate-timeline-event/v1";
+
+const EVENT_STATUSES = new Set([
+  "success",
+  "failure",
+  "cancelled",
+  "skipped",
+  "dependency-blocked",
+  "not-required",
+  "unknown",
+]);
+
+function compactObject(value) {
+  return Object.fromEntries(
+    Object.entries(value).filter(
+      ([, entry]) => entry !== undefined && entry !== "",
+    ),
+  );
+}
+
+function finiteNumber(value, fallback = undefined) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+function timestampMs(value) {
+  const parsed = Date.parse(value || "");
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function normalizeTiming(input = {}) {
+  const startedAtMs = timestampMs(input.startedAt);
+  const completedAtMs = timestampMs(input.completedAt);
+  const durationMs = finiteNumber(input.durationMs);
+  const measured =
+    startedAtMs !== null &&
+    completedAtMs !== null &&
+    completedAtMs >= startedAtMs;
+  return compactObject({
+    startedAt: measured ? new Date(startedAtMs).toISOString() : undefined,
+    completedAt: measured ? new Date(completedAtMs).toISOString() : undefined,
+    durationMs:
+      durationMs !== undefined && durationMs >= 0
+        ? Math.round(durationMs * 1000) / 1000
+        : measured
+          ? completedAtMs - startedAtMs
+          : undefined,
+    clock: input.clock || (measured ? "wall" : "unknown"),
+    precisionMs: finiteNumber(input.precisionMs, measured ? 1000 : undefined),
+    authority: input.authority,
+    measured,
+  });
+}
+
+function normalizeAttempt(input = {}) {
+  if (!input.id) {
+    throw new Error("candidate timeline event attempt.id is required");
+  }
+  return compactObject({
+    id: String(input.id),
+    index: Number.isInteger(input.index) ? input.index : undefined,
+    kind: input.kind || "unknown",
+    mergeGroupSha: input.mergeGroupSha,
+    workflowRunId:
+      input.workflowRunId === undefined
+        ? undefined
+        : String(input.workflowRunId),
+  });
+}
+
+export function normalizeCandidateTimelineEvent(input = {}) {
+  if (!input.id) {
+    throw new Error("candidate timeline event id is required");
+  }
+  if (!input.phase) {
+    throw new Error(`candidate timeline event ${input.id} phase is required`);
+  }
+  const status = input.status || "unknown";
+  if (!EVENT_STATUSES.has(status)) {
+    throw new Error(
+      `candidate timeline event ${input.id} has invalid status: ${status}`,
+    );
+  }
+  const timing = normalizeTiming(input.timing);
+  if (
+    ["success", "failure", "cancelled"].includes(status) &&
+    !timing.measured
+  ) {
+    throw new Error(
+      `candidate timeline event ${input.id} status ${status} requires a measured interval`,
+    );
+  }
+  return compactObject({
+    contract: BUILDCHAIN_CANDIDATE_TIMELINE_EVENT_CONTRACT,
+    id: String(input.id),
+    attempt: normalizeAttempt(input.attempt),
+    phase: String(input.phase),
+    category: input.category || "gate",
+    status,
+    gate: input.gate
+      ? compactObject({
+          id: input.gate.id,
+          platform: input.gate.platform,
+          partition:
+            input.gate.partition === undefined
+              ? undefined
+              : String(input.gate.partition),
+        })
+      : undefined,
+    span: input.span
+      ? compactObject({
+          id: input.span.id,
+          parentId: input.span.parentId,
+        })
+      : undefined,
+    execution: input.execution
+      ? compactObject({
+          boundary: input.execution.boundary,
+          runner: input.execution.runner,
+        })
+      : undefined,
+    cache: input.cache
+      ? compactObject({
+          layer: input.cache.layer,
+          outcome: input.cache.outcome,
+        })
+      : undefined,
+    timing,
+    criticalPathEligible: input.criticalPathEligible !== false,
+    attributes: input.attributes || {},
+  });
+}
+
+function interval(event) {
+  if (!event.timing.measured || !event.criticalPathEligible) return null;
+  return [
+    Date.parse(event.timing.startedAt),
+    Date.parse(event.timing.completedAt),
+  ];
+}
+
+function intervalUnionMs(intervals) {
+  const ordered = intervals
+    .filter(Boolean)
+    .map(([start, end]) => [start, end])
+    .sort((left, right) => left[0] - right[0] || left[1] - right[1]);
+  if (!ordered.length) return 0;
+  let total = 0;
+  let [currentStart, currentEnd] = ordered[0];
+  for (const [start, end] of ordered.slice(1)) {
+    if (start <= currentEnd) {
+      currentEnd = Math.max(currentEnd, end);
+    } else {
+      total += currentEnd - currentStart;
+      currentStart = start;
+      currentEnd = end;
+    }
+  }
+  return total + currentEnd - currentStart;
+}
+
+function groupIntervalSummary(events, field) {
+  const values = [
+    ...new Set(events.map((event) => event[field] || "unknown")),
+  ].sort();
+  return Object.fromEntries(
+    values.map((value) => {
+      const selected = events.filter(
+        (event) => (event[field] || "unknown") === value,
+      );
+      return [
+        value,
+        {
+          eventCount: selected.length,
+          measuredEventCount: selected.filter((event) => event.timing.measured)
+            .length,
+          intervalUnionMs: intervalUnionMs(selected.map(interval)),
+        },
+      ];
+    }),
+  );
+}
+
+function attemptOrder(left, right) {
+  const leftIndex = left.attempt.index;
+  const rightIndex = right.attempt.index;
+  if (Number.isInteger(leftIndex) && Number.isInteger(rightIndex)) {
+    return leftIndex - rightIndex;
+  }
+  return left.attempt.id.localeCompare(right.attempt.id);
+}
+
+function summarizeAttempt(events) {
+  const ordered = [...events].sort(attemptOrder);
+  const measured = ordered.filter(
+    (event) => event.timing.measured && event.criticalPathEligible,
+  );
+  const intervals = measured.map(interval);
+  const starts = intervals.map(([start]) => start);
+  const ends = intervals.map(([, end]) => end);
+  const startedAtMs = starts.length ? Math.min(...starts) : null;
+  const completedAtMs = ends.length ? Math.max(...ends) : null;
+  const activeUnionMs = intervalUnionMs(intervals);
+  const elapsedMs =
+    startedAtMs === null || completedAtMs === null
+      ? null
+      : completedAtMs - startedAtMs;
+  const unmeasured = ordered.filter(
+    (event) =>
+      event.criticalPathEligible &&
+      !event.timing.measured &&
+      !["skipped", "dependency-blocked", "not-required"].includes(event.status),
+  );
+  return {
+    attempt: ordered[0].attempt,
+    status: ordered.some((event) => event.status === "failure")
+      ? "failure"
+      : ordered.some((event) => event.status === "cancelled")
+        ? "cancelled"
+        : unmeasured.length
+          ? "incomplete"
+          : "observed",
+    eventCount: ordered.length,
+    measuredEventCount: ordered.filter((event) => event.timing.measured).length,
+    phases: groupIntervalSummary(ordered, "phase"),
+    categories: groupIntervalSummary(ordered, "category"),
+    criticalPath: {
+      method: "attempt-wall-clock-envelope",
+      status: unmeasured.length
+        ? "incomplete"
+        : measured.length
+          ? "observed"
+          : "not-observed",
+      startedAt:
+        startedAtMs === null ? null : new Date(startedAtMs).toISOString(),
+      completedAt:
+        completedAtMs === null ? null : new Date(completedAtMs).toISOString(),
+      durationMs: elapsedMs,
+      activeIntervalUnionMs: activeUnionMs,
+      idleOrUnobservedMs:
+        elapsedMs === null ? null : Math.max(0, elapsedMs - activeUnionMs),
+      unmeasuredEventIds: unmeasured.map((event) => event.id),
+      note: "The attempt envelope is wall-clock elapsed time. Interval unions avoid summing nested or parallel spans; attempts are never combined into one critical path.",
+    },
+  };
+}
+
+function normalizeCandidate(input = {}) {
+  if (!input.sourceSha) {
+    throw new Error("candidate timeline candidate.sourceSha is required");
+  }
+  return compactObject({
+    repository: input.repository,
+    baseBranch: input.baseBranch,
+    sourceSha: String(input.sourceSha),
+    pullRequest:
+      input.pullRequest === undefined ? undefined : Number(input.pullRequest),
+    mergedAt:
+      timestampMs(input.mergedAt) === null
+        ? undefined
+        : new Date(timestampMs(input.mergedAt)).toISOString(),
+  });
+}
+
+export function createCandidateTimeline({
+  candidate = {},
+  events = [],
+  generatedAt,
+} = {}) {
+  const normalizedCandidate = normalizeCandidate(candidate);
+  const normalizedEvents = events.map(normalizeCandidateTimelineEvent);
+  const sourceDrift = normalizedEvents.filter(
+    (event) =>
+      event.attributes?.sourceSha &&
+      event.attributes.sourceSha !== normalizedCandidate.sourceSha,
+  );
+  if (sourceDrift.length) {
+    throw new Error(
+      `candidate timeline source drift in events: ${sourceDrift.map((event) => event.id).join(", ")}`,
+    );
+  }
+  const attemptIds = [
+    ...new Set(normalizedEvents.map((event) => event.attempt.id)),
+  ];
+  const attempts = attemptIds
+    .map((attemptId) =>
+      summarizeAttempt(
+        normalizedEvents.filter((event) => event.attempt.id === attemptId),
+      ),
+    )
+    .sort((left, right) => {
+      const leftIndex = left.attempt.index;
+      const rightIndex = right.attempt.index;
+      if (Number.isInteger(leftIndex) && Number.isInteger(rightIndex)) {
+        return leftIndex - rightIndex;
+      }
+      return left.attempt.id.localeCompare(right.attempt.id);
+    });
+  return {
+    schemaVersion: 1,
+    contract: BUILDCHAIN_CANDIDATE_TIMELINE_CONTRACT,
+    generatedAt: generatedAt || new Date().toISOString(),
+    candidate: normalizedCandidate,
+    summary: {
+      attemptCount: attempts.length,
+      eventCount: normalizedEvents.length,
+      measuredEventCount: normalizedEvents.filter(
+        (event) => event.timing.measured,
+      ).length,
+      status: attempts.some((attempt) => attempt.status === "failure")
+        ? "failure"
+        : attempts.some((attempt) => attempt.status === "incomplete")
+          ? "incomplete"
+          : "observed",
+      criticalPathScope: "per-attempt-only",
+    },
+    attempts,
+    events: normalizedEvents,
+  };
+}
+
+export function formatCandidateTimelineReport(timeline) {
+  const lines = [
+    `Candidate ${timeline.candidate.repository || "repository"}#${timeline.candidate.pullRequest || "?"} ${timeline.candidate.sourceSha}`,
+    `status=${timeline.summary.status} attempts=${timeline.summary.attemptCount} events=${timeline.summary.eventCount} measured=${timeline.summary.measuredEventCount}`,
+  ];
+  for (const attempt of timeline.attempts) {
+    const duration = attempt.criticalPath.durationMs;
+    lines.push(
+      [
+        `attempt=${attempt.attempt.id}`,
+        `kind=${attempt.attempt.kind}`,
+        `status=${attempt.status}`,
+        `elapsed=${duration === null ? "unknown" : `${duration}ms`}`,
+        `active=${attempt.criticalPath.activeIntervalUnionMs}ms`,
+        `unmeasured=${attempt.criticalPath.unmeasuredEventIds.length}`,
+      ].join(" "),
+    );
+    for (const [phase, summary] of Object.entries(attempt.phases)) {
+      lines.push(
+        `  phase=${phase} union=${summary.intervalUnionMs}ms measured=${summary.measuredEventCount}/${summary.eventCount}`,
+      );
+    }
+  }
+  return lines.join("\n");
+}

package/packages/core/index.js

@@ -82,6 +82,14 @@ export {
   verifyBuildchainLogEvents,
 } from "./logging.js";
 
+export {
+  BUILDCHAIN_CANDIDATE_TIMELINE_CONTRACT,
+  BUILDCHAIN_CANDIDATE_TIMELINE_EVENT_CONTRACT,
+  createCandidateTimeline,
+  formatCandidateTimelineReport,
+  normalizeCandidateTimelineEvent,
+} from "./candidate-timeline.js";
+
 export {
   BUILDCHAIN_ANCHORED_PACKAGE_RELEASE_VALIDATION_CONTRACT,
   BUILDCHAIN_DIAGNOSTICS_CONTRACT,

package/scripts/generate-site-bundle.mjs

@@ -390,6 +390,8 @@ function cliCommandMeta(id) {
     "badges-readme": { group: "distribution-indexes", purpose: "Generate or verify managed README badge blocks." },
     "build-contract": { group: "governance-versioning", purpose: "Resolve Buildchain runtime contract metadata for floating-ref drift checks." },
     "build-facts": { group: "observability-diagnostics", purpose: "Collect and verify Git source, version, module output, product artifact, and legacy Kungfu buildinfo facts." },
+    candidate: { group: "observability-diagnostics", purpose: "Inspect source-bound candidate evidence command families." },
+    "candidate-timeline": { group: "observability-diagnostics", purpose: "Create a critical-path-safe timeline across pull-request and Merge Queue attempts." },
     collect: { group: "release-passport-trust", purpose: "Inspect release evidence collection command families." },
     "collect-github-release": { group: "release-passport-trust", purpose: "Collect GitHub Release assets into a release passport." },
     create: { group: "release-passport-trust", purpose: "Create canonical sealed publication evidence documents." },
@@ -495,6 +497,7 @@ function nodeApiMeta(exportName) {
     "./readme-badges": { group: "distribution-indexes", summary: "Managed README badge block facts, rendering, drift checks, and updates." },
     "./homebrew": { group: "distribution-indexes", summary: "Homebrew tap fact collection, Formula rendering, update, and check APIs." },
     "./build-facts": { group: "observability-diagnostics", summary: "Git source, version, module output, product artifact, and legacy Kungfu build fact APIs." },
+    "./candidate-timeline": { group: "observability-diagnostics", summary: "Source-bound candidate event normalization, per-attempt critical-path-safe aggregation, and compact reporting APIs." },
     "./diagnostics": { group: "observability-diagnostics", summary: "Native diagnostics collection, summarization, cache, compiler, and process-sampler APIs." },
     "./logging": { group: "observability-diagnostics", summary: "Buildchain JSONL logging, span, summary, and verification APIs." },
     "./portable-dev-cache": { group: "observability-diagnostics", summary: "Portable dependency/compiler cache plan, exact-root verification, and provider receipt APIs." },

package/scripts/web-surface-production-decision.mjs

@@ -8,6 +8,7 @@ const TRUSTED_PERMISSIONS = new Set(["write", "maintain", "admin"]);
 
 export function resolveWebSurfaceProductionDecision({
   eventName,
+  eventAction = "",
   refName,
   repository,
   sourceSha,
@@ -36,9 +37,11 @@ export function resolveWebSurfaceProductionDecision({
       reason: trusted ? "trusted-manual-dispatch" : "manual-actor-permission-insufficient",
     });
   }
+  const reviewedReleaseEvent =
+    (eventName === "push" && refName === "main") ||
+    (eventName === "pull_request" && eventAction === "closed");
   if (
-    eventName === "push" &&
-    refName === "main" &&
+    reviewedReleaseEvent &&
     productionApply === true &&
     productionReleaseOnMain === true &&
     releaseApproved === true
@@ -103,9 +106,10 @@ async function main() {
   }
   const decision = resolveWebSurfaceProductionDecision({
     eventName,
+    eventAction: process.env.GITHUB_EVENT_ACTION,
     refName: process.env.GITHUB_REF_NAME,
     repository,
-    sourceSha: process.env.GITHUB_SHA,
+    sourceSha: process.env.BUILDCHAIN_PRODUCTION_SOURCE_SHA || process.env.GITHUB_SHA,
     actor,
     productionApply: bool("BUILDCHAIN_PRODUCTION_APPLY"),
     productionApproved: bool("BUILDCHAIN_PRODUCTION_APPROVED"),