@kungfu-tech/buildchain 2.3.1-alpha.0 → 2.3.1-alpha.1

package/AGENTS.md

@@ -36,6 +36,10 @@ See [`docs/cli.md`](docs/cli.md), [`docs/lifecycle-protocol.md`](docs/lifecycle-
 and [`docs/reusable-build-surface.md`](docs/reusable-build-surface.md) for the
 consumer contract.
 
+For temporary validation of an unreleased Buildchain runtime, keep the committed
+workflow ref on `@v2` and use the trusted `workflow_dispatch` `buildchain-ref`
+pass-through. See [`docs/runtime-train-validation.md`](docs/runtime-train-validation.md).
+
 ## Building this repo
 
 Buildchain is a pnpm workspace running on Node 24:
@@ -52,6 +56,13 @@ and rebuilds every action bundle.
 ## Proposing changes
 
 - Open pull requests against the relevant `dev/*` channel branch.
+- If a Buildchain change needs downstream validation before stable refs move,
+  publish a `train/v2/v2.3/<capability>` ref and include the validation request
+  described in [`docs/runtime-train-validation.md`](docs/runtime-train-validation.md).
+  After validation succeeds, do not leave the train as a pending merge item:
+  merge the pull request into the active `dev/*` mainline and run the requested
+  alpha or release promotion. The train may remain for a retention window as a
+  fast-use and rollback channel; periodic cleanup handles old trains.
 - Write commit messages and PR descriptions in English, using lightweight
   [Conventional Commits](https://www.conventionalcommits.org/)
   (`type(scope): summary`).

package/CONTRIBUTING.md

@@ -103,14 +103,24 @@ release/vX/vX.Y -> publish-gate/major
 ```
 
 - Open normal changes against the relevant `dev/*` branch.
+- When a Buildchain change needs downstream validation before stable refs move,
+  publish a temporary runtime train ref such as
+  `train/v2/v2.3/<capability>` and ask consumers to run trusted
+  `workflow_dispatch` with `buildchain-ref` set to that train. Keep the pull
+  request against the `dev/*` branch; the train is only a validation pointer,
+  not a pending merge target. After validation succeeds, merge into the active
+  `dev/*` mainline and run the requested alpha or release promotion. The train
+  may remain for a retention window as a fast-use and rollback channel; old
+  trains are cleaned by a separate periodic cleanup task.
 - Merging into `alpha/*`, `release/*`, or `publish-gate/major` expresses a
   release intent. Buildchain promotion then creates version-state commits,
   exact tags, floating tags, npm publish evidence, and next-alpha state.
 - Manual promotion dispatch is dry-run only; non-dry-run promotion follows a
   successful protected workflow path.
 
-See [`docs/release-governance.md`](docs/release-governance.md) and
-[`docs/release-flow.md`](docs/release-flow.md).
+See [`docs/release-governance.md`](docs/release-governance.md),
+[`docs/release-flow.md`](docs/release-flow.md), and
+[`docs/runtime-train-validation.md`](docs/runtime-train-validation.md).
 
 ## License
 

package/README.md

@@ -85,6 +85,27 @@ const report = verifyBuildchainLogEvents({
 The package also ships `dist/site/` as the Buildchain-owned fact source for
 `buildchain.libkungfu.dev`.
 
+Native build consumers can import the diagnostics toolkit instead of copying
+repository-local probes:
+
+```js
+import {
+  collectBuildchainDiagnostics,
+  collectRunnerDiagnostics,
+  writeDiagnosticsArtifact,
+} from "@kungfu-tech/buildchain/diagnostics";
+
+writeDiagnosticsArtifact(".buildchain/artifacts/diagnostics.json", {
+  contract: "consumer-build-diagnostics",
+  buildchain: collectBuildchainDiagnostics({ cwd: process.cwd() }),
+  runner: collectRunnerDiagnostics(),
+});
+```
+
+`buildchain lifecycle run` writes a small `diagnostics.json` next to the
+platform manifest. It includes lifecycle-wide observability, runner/tool/cache
+snapshots, Git state, and links to the larger manifest and artifact outputs.
+
 ## Use Buildchain
 
 Bootstrap a repository:

package/actions/promote-buildchain-ref/README.md

@@ -101,6 +101,31 @@ trusted channel workflow:
       ]
 ```
 
+For anchored/manual package repositories that build through the reusable
+workflow, keep the publish entrypoint on the `publish-gate/*` source-lock
+contract:
+
+```yaml
+- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v2
+  with:
+    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}
+    sha: ${{ needs.build.outputs.publish-source-sha }}
+    target-ref: release/v22/v22.22
+    require-publish-source-lock: "true"
+    publish-source-ref: ${{ needs.build.outputs.publish-source-ref }}
+    publish-source-sha: ${{ needs.build.outputs.publish-source-sha }}
+    publish-source-locked: ${{ needs.build.outputs.publish-source-locked }}
+    publish-transaction: "true"
+    publish-mode: publish-final-version
+    publish-auth: trusted-publishing
+```
+
+`target-ref` remains the channel promotion target that must point at `sha`.
+`publish-source-ref` is the reviewed source-lock branch that authorized this
+specific package publication. Direct `alpha/*` or `release/*` channel refs are
+not valid publish source locks when `require-publish-source-lock` is enabled,
+and a mismatched `publish-source-sha` fails before any promotion or publish side effects begin.
+
 When enabled, the action creates or resumes a release transaction keyed by
 repository, version, source SHA, and target ref. It persists that transaction to
 a machine-managed branch under `buildchain/release-state/<version>`, with
@@ -144,10 +169,23 @@ BUILDCHAIN_PUBLISH_EVIDENCE
 The action outputs `transaction-id`, `transaction-state`,
 `transaction-exact-tag`, `transaction-release-sha`, `transaction-state-ref`,
 `transaction-state-sha`, `transaction-state-path`, `publish-evidence-path`, and
-`finalization-needed`. `transaction-state-ref` is the durable recovery location.
+`release-passport-path`, `release-passport-output-dir`,
+`release-passport-state-sha`, and `finalization-needed`.
+`transaction-state-ref` is the durable recovery location.
+`release-passport-state-sha` is the durable ref commit after the generated
+`release-passport/*` files have been uploaded into that recovery ref.
 `finalization-needed=true` means publish evidence is valid, but protected branch
 or ref finalization needs a later promotion run.
 
+After a publish transaction reaches `complete`, the action generates the unified
+`buildchain-release-passport` in `.buildchain/release-passport` by default and
+persists those files under `release-passport/` in the durable release-state ref.
+When present, the passport includes the aggregate build summary, platform
+artifact manifests, npm publish evidence, dist-tag promotion evidence, the
+release-state ref, trusted publishing metadata, and the Buildchain transaction
+result. Set `release-passport: "false"` only for a controlled recovery run that
+must skip passport generation.
+
 Finalization recovery is anchored to the durable transaction, not to a single
 workflow run SHA. After a generated version-state PR is merged, the current
 channel head can be a merge commit that contains or corresponds to the recorded

package/actions/run-lifecycle/README.md

@@ -39,3 +39,23 @@ with:
   expected-artifacts-json: >-
     {"minFiles":2,"requiredPaths":["dist/app.tar.gz","dist/checksums.txt"]}
 ```
+
+For long native builds, set `sample-process-tree: "true"` and pass
+`process-summary-path`. The action wraps either the explicit `command` or the
+configured lifecycle stage with `buildchain sample process-tree`, then embeds
+the produced summary in the lifecycle diagnostics artifact:
+
+```yaml
+with:
+  stage: build
+  sample-process-tree: "true"
+  process-summary-path: .buildchain/diagnostics/process-summary.json
+```
+
+Custom wrappers can still pass an existing sampler report or summary with
+`process-summary-path`; the action reads it after the lifecycle command
+finishes, so commands may generate the file during the same invocation.
+Set `process-summary-required: "false"` when the summary is an optional sidecar,
+for example when a reusable workflow may skip an optional build stage.
+The diagnostics directory also includes `diagnostics-manifest.json`, a compact
+inventory of the diagnostics sidecars with byte counts and sha256 hashes.

package/bin/buildchain.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
@@ -24,6 +24,14 @@ import {
   explainReleasePassport,
   verifyReleasePassport,
 } from "../packages/core/release-passport.js";
+import {
+  BUILDCHAIN_PROCESS_SAMPLE_REPORT_CONTRACT,
+  formatDiagnosticsSummaryTable,
+  startProcessSampler,
+  summarizeDiagnosticsArtifacts,
+  summarizeProcessSamples,
+  validateAnchoredPackageRelease,
+} from "../packages/core/diagnostics.js";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const embeddedPackageVersion = process.env.BUILDCHAIN_EMBEDDED_PACKAGE_VERSION || "";
@@ -39,6 +47,7 @@ function usage() {
                       [--require-lifecycle-stages <comma-list>]
   buildchain lifecycle run <stage> [--cwd <dir>] [--required]
                              [--artifact-name <name>] [--artifact-path <path>]...
+                             [--process-summary <json>]
   buildchain npm dry-run [--cwd <dir>] [--expected-tag <tag>] [--registry <url>]
                          [--dist-tag <tag>] [--skip-npm-publish-dry-run] [--json]
   buildchain release --dry-run --target-ref <ref> [--sha <sha>] [--source-ref <ref>]
@@ -51,7 +60,17 @@ function usage() {
   buildchain transaction inspect ...
   buildchain collect github-release --tag <tag> [--repository <owner/repo>]
                                     [--assets-dir <dir>] [--assets-json <json-or-path>]
-                                    [--release-json <json-or-path>] [--output-dir <dir>] [--json]
+                                    [--release-json <json-or-path>] [--package-set-json <json-or-path>]
+                                    [--product-name <name>]
+                                    [--publish-evidence-json <json-or-path>]
+                                    [--trusted-publishing-json <json-or-path>]
+                                    [--transaction-json <json-or-path>]
+                                    [--anchor-manifest-json <json-or-path>]
+                                    [--build-summary-json <json-or-path>]
+                                    [--platform-manifest-json <json-or-path>]...
+                                    [--dist-tag-evidence-json <json-or-path>]
+                                    [--release-extra-json <json-or-path>]
+                                    [--publish-json <json-or-path>] [--output-dir <dir>] [--json]
   buildchain verify release-passport <file-or-url> [--json]
   buildchain verify observability-log <jsonl> [--min-events <n>]
                                              [--require-phase <csv>]
@@ -59,17 +78,23 @@ function usage() {
                                              [--require-event <csv>] [--allow-errors] [--json]
   buildchain explain release --passport <file-or-url> [--for human|agent] [--json]
   buildchain inspect release --passport <file-or-url> [--json]
-  buildchain doctor [--cwd <dir>] [--json]
+  buildchain doctor [--cwd <dir>] [--require-publish-source-lock] [--json]
   buildchain log <info|warn|error> --event <name> [--phase <phase>]
                  [--component <name>] [--source <name>] [--attribute key=value]...
                  [--path <jsonl>] [--json]
   buildchain log summary [--path <jsonl>] [--json]
+  buildchain diagnostics summary <diagnostics.json>... [--artifact <file>]...
+                                      [--output <file>] [--json]
+  buildchain sample process-tree [--interval-ms <n>] [--label <name>]
+                                 [--output <jsonl>] [--summary-output <json>]
+                                 [--requested-parallelism <n>] [--json]
+                                 -- <command> [args...]
   buildchain mark --event <name> [--phase <phase>] [--component <name>]
                   [--attribute key=value]... [--path <jsonl>] [--json]
   buildchain span --event <name> [--phase <phase>] [--component <name>]
                   [--path <jsonl>] -- <command> [args...]
   buildchain web-surface ...
-  buildchain publish-source <lock|manifest|verify-lock> ...
+  buildchain publish-source <lock|manifest|verify-lock|validate-anchored-release> ...
   buildchain build-contract ...
 
 Examples:
@@ -140,14 +165,15 @@ function checkStatus(ok, id, message, details = {}) {
   return { id, status: ok ? "pass" : "fail", message, details };
 }
 
-function runDoctor({ cwd = process.cwd() } = {}) {
+function runDoctor({ cwd = process.cwd(), requirePublishSourceLock = false } = {}) {
   const resolvedCwd = path.resolve(cwd);
   const checks = [];
   checks.push(checkStatus(fs.existsSync(resolvedCwd), "cwd.exists", "working directory exists", { cwd: resolvedCwd }));
+  let validation;
   try {
-    const validation = validateBuildchainConfig(resolvedCwd);
+    validation = validateBuildchainConfig(resolvedCwd);
     checks.push(checkStatus(true, "config.valid", "buildchain.toml is valid", {
-      projectType: validation.project.type,
+      projectType: validation.project?.type || "",
       lifecycleStages: validation.lifecycleStages.map((stage) => stage.name),
     }));
   } catch (error) {
@@ -168,6 +194,22 @@ function runDoctor({ cwd = process.cwd() } = {}) {
   checks.push(checkStatus(fs.existsSync(workflowPath), "workflow.build", "reusable workflow caller exists", {
     path: ".github/workflows/build.yml",
   }));
+  if (validation?.version?.strategy === "anchored" && validation.version.next === "manual") {
+    const anchored = validateAnchoredPackageRelease({
+      cwd: resolvedCwd,
+      requirePublishGateSourceLock: requirePublishSourceLock,
+    });
+    checks.push(checkStatus(
+      anchored.ok,
+      "anchored-package-release.valid",
+      "anchored package release contract is valid",
+      {
+        contract: anchored.contract,
+        summary: anchored.summary,
+        checks: anchored.checks,
+      },
+    ));
+  }
   return {
     schemaVersion: 1,
     contract: "kungfu-buildchain-doctor",
@@ -195,6 +237,61 @@ function printJson(value) {
   process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
 
+function writeJsonFile(filePath, value) {
+  if (!filePath) {
+    return "";
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+  return filePath;
+}
+
+function appendJsonLine(filePath, value) {
+  if (!filePath) {
+    return "";
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.appendFileSync(filePath, `${JSON.stringify(value)}\n`);
+  return filePath;
+}
+
+function readIntegerFlag(args, name, fallback = 0) {
+  const value = readFlag(args, name, "");
+  if (!value) {
+    return fallback;
+  }
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new Error(`--${name} must be a non-negative integer`);
+  }
+  return parsed;
+}
+
+function readDiagnosticsArtifactInputs(args) {
+  const values = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const entry = args[index];
+    if (entry === "--artifact") {
+      const value = args[index + 1];
+      if (!value || value.startsWith("--")) {
+        throw new Error("buildchain diagnostics summary --artifact requires a file path");
+      }
+      values.push(value);
+      index += 1;
+      continue;
+    }
+    if (entry === "--output") {
+      index += 1;
+      continue;
+    }
+    if (entry === "--json") {
+      continue;
+    }
+    values.push(entry);
+  }
+  return values;
+}
+
 function packageVersion() {
   if (embeddedPackageVersion) {
     return embeddedPackageVersion;
@@ -203,6 +300,81 @@ function packageVersion() {
   return packageJson.version;
 }
 
+async function runProcessTreeSample(sampleArgs = []) {
+  const separator = sampleArgs.indexOf("--");
+  const optionArgs = separator === -1 ? sampleArgs : sampleArgs.slice(0, separator);
+  const commandArgs = separator === -1 ? [] : sampleArgs.slice(separator + 1);
+  if (commandArgs.length === 0) {
+    throw new Error("usage: buildchain sample process-tree -- <command> [args...]");
+  }
+  const command = commandArgs[0];
+  const args = commandArgs.slice(1);
+  const label = readFlag(optionArgs, "label", "process-tree");
+  const intervalMs = readIntegerFlag(optionArgs, "interval-ms", 15000);
+  const requestedParallelism = readIntegerFlag(optionArgs, "requested-parallelism", 0);
+  const outputPath = readFlag(optionArgs, "output", ".buildchain/diagnostics/process-samples.jsonl");
+  const summaryOutputPath = readFlag(optionArgs, "summary-output", ".buildchain/diagnostics/process-summary.json");
+  const startedAt = Date.now();
+  const child = spawn(command, args, {
+    cwd: process.cwd(),
+    env: process.env,
+    stdio: "inherit",
+  });
+  const sampler = startProcessSampler({
+    rootPid: child.pid || process.pid,
+    intervalMs,
+    label,
+    command,
+    args,
+    env: process.env,
+    requestedParallelism,
+    onSample(sample) {
+      appendJsonLine(outputPath, sample);
+    },
+  });
+  const result = await new Promise((resolve) => {
+    child.on("error", (error) => resolve({ error, status: 1, signal: "" }));
+    child.on("close", (status, signal) => resolve({ status, signal: signal || "" }));
+  });
+  const samples = sampler.stop();
+  const summary = summarizeProcessSamples({
+    samples,
+    command,
+    args,
+    env: process.env,
+    requestedParallelism,
+  });
+  const report = {
+    schemaVersion: 1,
+    contract: BUILDCHAIN_PROCESS_SAMPLE_REPORT_CONTRACT,
+    label,
+    command: path.basename(command),
+    argsCount: args.length,
+    exit: {
+      status: result.status ?? 0,
+      signal: result.signal || "",
+      error: result.error?.message || "",
+    },
+    durationMs: Date.now() - startedAt,
+    samplesPath: outputPath,
+    summaryPath: summaryOutputPath,
+    summary,
+  };
+  writeJsonFile(summaryOutputPath, report);
+  if (readBooleanFlag(optionArgs, "json")) {
+    printJson(report);
+  } else {
+    process.stdout.write(`buildchain process sample: ${summary.sampleCount} samples\n`);
+    process.stdout.write(`observed concurrency max: ${summary.observedConcurrency.max}\n`);
+    process.stdout.write(`wrote: ${outputPath}\n`);
+    process.stdout.write(`wrote: ${summaryOutputPath}\n`);
+  }
+  if (result.error || result.status !== 0) {
+    process.exitCode = result.status || 1;
+  }
+  return report;
+}
+
 async function main(argv = process.argv.slice(2)) {
   const [command, ...args] = argv;
   if (!command || command === "-h" || command === "--help" || command === "help") {
@@ -241,7 +413,10 @@ async function main(argv = process.argv.slice(2)) {
   }
 
   if (command === "doctor") {
-    const result = runDoctor({ cwd: readFlag(args, "cwd", process.cwd()) });
+    const result = runDoctor({
+      cwd: readFlag(args, "cwd", process.cwd()),
+      requirePublishSourceLock: readBooleanFlag(args, "require-publish-source-lock"),
+    });
     if (readBooleanFlag(args, "json")) {
       printJson(result);
     } else {
@@ -285,6 +460,46 @@ async function main(argv = process.argv.slice(2)) {
     return;
   }
 
+  if (command === "diagnostics") {
+    const [subcommand = "", ...diagnosticsArgs] = args;
+    if (subcommand !== "summary") {
+      throw new Error("usage: buildchain diagnostics summary <diagnostics.json>...");
+    }
+    const inputs = readDiagnosticsArtifactInputs(diagnosticsArgs);
+    if (inputs.length === 0) {
+      throw new Error("buildchain diagnostics summary requires at least one artifact");
+    }
+    const summary = summarizeDiagnosticsArtifacts(inputs);
+    if (summary.count !== inputs.length) {
+      throw new Error(`buildchain diagnostics summary read ${summary.count}/${inputs.length} artifacts`);
+    }
+    const outputPath = readFlag(diagnosticsArgs, "output", "");
+    writeJsonFile(outputPath, summary);
+    if (readBooleanFlag(diagnosticsArgs, "json")) {
+      printJson(summary);
+    } else {
+      process.stdout.write(`buildchain diagnostics summary: ${summary.count} platforms\n`);
+      process.stdout.write(`warnings: ${summary.totalWarningCount} errors: ${summary.totalErrorCount}\n`);
+      if (summary.diagnosticsManifestWarningCount) {
+        process.stdout.write(`diagnostics manifest warnings: ${summary.diagnosticsManifestWarningCount}\n`);
+      }
+      process.stdout.write(`${formatDiagnosticsSummaryTable(summary)}\n`);
+      if (outputPath) {
+        process.stdout.write(`wrote: ${outputPath}\n`);
+      }
+    }
+    return;
+  }
+
+  if (command === "sample") {
+    const [subcommand = "", ...sampleArgs] = args;
+    if (subcommand !== "process-tree") {
+      throw new Error("usage: buildchain sample process-tree -- <command> [args...]");
+    }
+    await runProcessTreeSample(sampleArgs);
+    return;
+  }
+
   if (command === "mark") {
     const eventName = readFlag(args, "event", "");
     if (!eventName) {
@@ -359,6 +574,7 @@ async function main(argv = process.argv.slice(2)) {
       artifactPaths,
       expectedArtifactsJson: readFlag(lifecycleArgs, "expected-artifacts-json", ""),
       logPath: readFlag(lifecycleArgs, "log-path", process.env.BUILDCHAIN_LOG_PATH || ".buildchain/logs/events.jsonl"),
+      processSummaryPath: readFlag(lifecycleArgs, "process-summary", ""),
       workspace: process.cwd(),
     });
     printJson(manifest);
@@ -446,8 +662,19 @@ async function main(argv = process.argv.slice(2)) {
       assetsDir: readFlag(collectArgs, "assets-dir", ""),
       assetsJson: readFlag(collectArgs, "assets-json", ""),
       releaseJson: readFlag(collectArgs, "release-json", ""),
+      productName: readFlag(collectArgs, "product-name", "Buildchain"),
       packageName: readFlag(collectArgs, "package-name", "@kungfu-tech/buildchain"),
       packageVersion: readFlag(collectArgs, "package-version", packageVersion()),
+      packageSetJson: readFlag(collectArgs, "package-set-json", ""),
+      publishEvidenceJson: readFlag(collectArgs, "publish-evidence-json", ""),
+      trustedPublishingJson: readFlag(collectArgs, "trusted-publishing-json", ""),
+      transactionJson: readFlag(collectArgs, "transaction-json", ""),
+      anchorManifestJson: readFlag(collectArgs, "anchor-manifest-json", ""),
+      buildSummaryJson: readFlag(collectArgs, "build-summary-json", ""),
+      platformManifestJsons: readRepeatedFlag(collectArgs, "platform-manifest-json"),
+      distTagEvidenceJson: readFlag(collectArgs, "dist-tag-evidence-json", ""),
+      releaseJsonExtra: readFlag(collectArgs, "release-extra-json", ""),
+      publishJson: readFlag(collectArgs, "publish-json", ""),
       workflow,
     });
     if (readBooleanFlag(collectArgs, "json")) {
@@ -562,6 +789,24 @@ async function main(argv = process.argv.slice(2)) {
       runScript("verify-publish-source-lock.mjs", publishArgs);
       return;
     }
+    if (mode === "validate-anchored-release") {
+      const report = validateAnchoredPackageRelease({
+        cwd: readFlag(publishArgs, "cwd", process.cwd()),
+        requirePublishGateSourceLock: true,
+      });
+      if (readBooleanFlag(publishArgs, "json")) {
+        printJson(report);
+      } else {
+        process.stdout.write(`anchored release source lock: ${report.ok ? "ok" : "failed"}\n`);
+        for (const entry of report.checks) {
+          process.stdout.write(`- ${entry.status}: ${entry.id}: ${entry.message}\n`);
+        }
+      }
+      if (!report.ok) {
+        process.exitCode = 1;
+      }
+      return;
+    }
     throw new Error(`unsupported publish-source command: ${mode}`);
   }
 

package/dist/site/cli-registry.json

@@ -49,6 +49,11 @@
       "usage": "buildchain log|mark|span|verify observability-log",
       "purpose": "Emit timestamped build events, summarize logs, and enforce required phases."
     },
+    {
+      "id": "diagnostics-summary",
+      "usage": "buildchain diagnostics summary <diagnostics.json>...",
+      "purpose": "Summarize small diagnostics artifacts into JSON and a cross-platform lifecycle timing table."
+    },
     {
       "id": "npm-dry-run",
       "usage": "buildchain npm dry-run --json",

package/dist/site/release-provenance.json

@@ -10,6 +10,7 @@
     "exports": {
       ".": "./packages/core/index.js",
       "./core": "./packages/core/index.js",
+      "./diagnostics": "./packages/core/diagnostics.js",
       "./logging": "./packages/core/logging.js",
       "./release-passport": "./packages/core/release-passport.js",
       "./site/buildchain-site.json": "./dist/site/buildchain-site.json",

package/docs/MAP.md

@@ -35,6 +35,7 @@ running artifact), *use* (consume / extend) - and a **status**:
 | How do I add timestamped logs inside build scripts? | [`toolkit-observability.md`](toolkit-observability.md) | use | stable |
 | What package-owned facts should buildchain.libkungfu.dev render? | [`site-bundle-contract.md`](site-bundle-contract.md) | use | stable |
 | How do I call the reusable build workflow? | [`reusable-build-surface.md`](reusable-build-surface.md) | use | stable |
+| How do I validate an unreleased Buildchain runtime train while keeping `@v2`? | [`runtime-train-validation.md`](runtime-train-validation.md) | use | stable |
 | How do I deploy a site/app preview, staging, or production surface? | [`web-surface-deployments.md`](web-surface-deployments.md) | use | stable |
 | How do I use the active actions directly? | [`../actions/validate-config/README.md`](../actions/validate-config/README.md), [`../actions/run-lifecycle/README.md`](../actions/run-lifecycle/README.md), [`../actions/promote-buildchain-ref/README.md`](../actions/promote-buildchain-ref/README.md) | use | stable |
 | What do the fixture repositories demonstrate? | [`../fixtures/libnode-shaped/README.md`](../fixtures/libnode-shaped/README.md), [`../fixtures/publish-transaction-shaped/README.md`](../fixtures/publish-transaction-shaped/README.md), [`../fixtures/web-surface-shaped/README.md`](../fixtures/web-surface-shaped/README.md) | verify | stable |
@@ -59,6 +60,9 @@ running artifact), *use* (consume / extend) - and a **status**:
 - **libnode / native artifacts / self-hosted runner matrix** ->
   [`reusable-build-surface.md`](reusable-build-surface.md) and
   [`../fixtures/libnode-shaped/README.md`](../fixtures/libnode-shaped/README.md).
+- **runtime train validation / temporary `buildchain-ref` override** ->
+  [`runtime-train-validation.md`](runtime-train-validation.md) and
+  [`reusable-build-surface.md`](reusable-build-surface.md).
 - **standalone binary install / platform archives / GitHub Release bundle** ->
   [`install.md`](install.md), [`binary-distribution.md`](binary-distribution.md),
   and [`release-passport.md`](release-passport.md).