@kungfu-tech/buildchain 2.6.2 → 2.7.0-alpha.0

package/bin/buildchain.mjs

@@ -8,6 +8,7 @@ import { initBuildchainRepo } from "../scripts/init-repo.mjs";
 import { npmPublishDryRun } from "../scripts/npm-publish-dry-run.mjs";
 import { runLifecycle } from "../scripts/run-lifecycle-core.mjs";
 import { verifyInfraContractEvidenceBundle } from "../scripts/infra-contract-core.mjs";
+import { runReleasePropagationCli } from "../scripts/release-propagation.mjs";
 import { validateBuildchainConfig } from "../packages/core/buildchain-config.js";
 import { detectPackageManager } from "../packages/core/package-manager.js";
 import {
@@ -107,6 +108,7 @@ function usage() {
                   [--path <jsonl>] -- <command> [args...]
   buildchain web-surface ...
   buildchain infra-contract ...
+  buildchain release-propagation <plan|write-lock> ...
   buildchain publish-source <lock|manifest|verify-lock|verify-channel-ref|validate-anchored-release> ...
   buildchain build-contract ...
 
@@ -129,6 +131,7 @@ Examples:
   buildchain infra-contract --mode apply --plan <plan.json> --source-sha <sha> --approval-id <id> --dry-run false --execute-adapter-commands true
   buildchain infra-contract --mode propagation-apply --propagation-plan <plan.json> --dry-run true
   buildchain infra-contract --mode evidence-bundle --artifact <artifact.json> --propagation-result <result.json>
+  buildchain release-propagation plan --graph graph.json --upstream-release release.json --json
 `;
 }
 
@@ -930,6 +933,11 @@ async function main(argv = process.argv.slice(2)) {
     return;
   }
 
+  if (command === "release-propagation") {
+    runReleasePropagationCli(args);
+    return;
+  }
+
   if (command === "build-contract") {
     runScript("resolve-build-contract.mjs", args);
     return;

package/dist/site/buildchain-site.json

@@ -38,6 +38,13 @@
       "plane": "verify",
       "exists": true
     },
+    {
+      "id": "release-propagation",
+      "title": "Release propagation",
+      "path": "docs/release-propagation.md",
+      "plane": "use",
+      "exists": true
+    },
     {
       "id": "binary-distribution",
       "title": "Binary distribution contract",
@@ -149,6 +156,16 @@
       "bundle": "buildchain-release-bundle.tar.gz",
       "contract": "kungfu-buildchain-release-passport"
     },
+    "releasePropagation": {
+      "graphContract": "kungfu-buildchain-release-propagation-graph",
+      "planContract": "kungfu-buildchain-release-propagation-plan",
+      "lockContract": "kungfu-buildchain-release-propagation-lock",
+      "defaultChannelPolicy": "preserve",
+      "defaultChannelMap": {
+        "alpha": "alpha",
+        "release": "release"
+      }
+    },
     "npm": {
       "package": "@kungfu-tech/buildchain",
       "command": "./bin/buildchain.mjs",

package/dist/site/cli-registry.json

@@ -44,6 +44,11 @@
       "usage": "buildchain verify release-passport <file-or-url>",
       "purpose": "Fail closed unless a release passport and its evidence are complete."
     },
+    {
+      "id": "release-propagation",
+      "usage": "buildchain release-propagation <plan|write-lock>",
+      "purpose": "Plan channel-preserving downstream release PRs and write exact upstream release locks."
+    },
     {
       "id": "verify-infra-contract-evidence-bundle",
       "usage": "buildchain verify infra-contract-evidence-bundle <file>",

package/dist/site/release-model.json

@@ -17,6 +17,16 @@
     "bundle": "buildchain-release-bundle.tar.gz",
     "contract": "kungfu-buildchain-release-passport"
   },
+  "releasePropagation": {
+    "graphContract": "kungfu-buildchain-release-propagation-graph",
+    "planContract": "kungfu-buildchain-release-propagation-plan",
+    "lockContract": "kungfu-buildchain-release-propagation-lock",
+    "defaultChannelPolicy": "preserve",
+    "defaultChannelMap": {
+      "alpha": "alpha",
+      "release": "release"
+    }
+  },
   "npm": {
     "package": "@kungfu-tech/buildchain",
     "command": "./bin/buildchain.mjs",

package/dist/site/release-provenance.json

@@ -16,6 +16,7 @@
       "./logging": "./packages/core/logging.js",
       "./release-candidate": "./packages/core/release-candidate.js",
       "./release-passport": "./packages/core/release-passport.js",
+      "./release-propagation": "./packages/core/release-propagation.js",
       "./site/buildchain-site.json": "./dist/site/buildchain-site.json",
       "./site/site-manifest.json": "./dist/site/site-manifest.json",
       "./site/cli-registry.json": "./dist/site/cli-registry.json",

package/dist/site/site-manifest.json

@@ -26,6 +26,13 @@
       "plane": "verify",
       "exists": true
     },
+    {
+      "id": "release-propagation",
+      "title": "Release propagation",
+      "path": "docs/release-propagation.md",
+      "plane": "use",
+      "exists": true
+    },
     {
       "id": "binary-distribution",
       "title": "Binary distribution contract",

package/dist/site/workflow-registry.json

@@ -20,6 +20,12 @@
       "surface": "release-governance",
       "status": "active"
     },
+    {
+      "id": "release-propagation",
+      "path": ".github/workflows/release-propagation.yml",
+      "surface": "release-propagation",
+      "status": "preview"
+    },
     {
       "id": "dev-pr-auto-merge",
       "path": ".github/workflows/dev-pr-auto-merge.yml",

package/docs/MAP.md

@@ -33,6 +33,7 @@ running artifact), *use* (consume / extend) - and a **status**:
 | How do I declare version files and custom lifecycle commands? | [`lifecycle-protocol.md`](lifecycle-protocol.md) | use | stable |
 | How does publish evidence, recovery, and finalization work? | [`publish-transaction.md`](publish-transaction.md) | verify | stable |
 | How do I publish or verify release passport artifacts? | [`release-passport.md`](release-passport.md) | use | stable |
+| How do I propagate finalized upstream releases to downstream package/site PRs? | [`release-propagation.md`](release-propagation.md) | use | preview |
 | How do I prove a PR-stage reusable build is the artifact source promoted later? | [`release-candidate.md`](release-candidate.md) + [`reusable-build-surface.md`](reusable-build-surface.md) | verify | stable |
 | Why are binary release assets archived by platform, and where is the single bundle? | [`binary-distribution.md`](binary-distribution.md) | verify | stable |
 | How do I add timestamped logs inside build scripts? | [`toolkit-observability.md`](toolkit-observability.md) | use | stable |
@@ -87,6 +88,8 @@ running artifact), *use* (consume / extend) - and a **status**:
   and [`release-passport.md`](release-passport.md).
 - **Trusted Publishing / npm / publish evidence / recovery** ->
   [`cli.md`](cli.md) and [`publish-transaction.md`](publish-transaction.md).
+- **release chains / upstream package as source of truth / site synchronization** ->
+  [`release-propagation.md`](release-propagation.md).
 - **GitHub Release passport / binary assets / artifact evidence / agent release checks** ->
   [`release-passport.md`](release-passport.md),
   [`binary-distribution.md`](binary-distribution.md), and [`cli.md`](cli.md).

package/docs/release-propagation.md

@@ -0,0 +1,156 @@
+# Release Propagation
+
+Release propagation lets a finalized upstream release open a downstream update
+PR using the upstream release passport as the audit source. It is for product
+chains such as:
+
+```text
+kfd -> site-libkungfu-dev
+A -> B -> C
+```
+
+The downstream repository receives an exact lock, not a floating dist-tag. A
+site or app can then consume the upstream package, site bundle, or release
+passport as its single source of truth without hand-copying release facts.
+
+## Contract
+
+The propagation graph is declarative JSON:
+
+```json
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-release-propagation-graph",
+  "nodes": [
+    {
+      "id": "kfd",
+      "repository": "kungfu-systems/kfd",
+      "package": "@kungfu-tech/kfd"
+    },
+    {
+      "id": "site-libkungfu-dev",
+      "repository": "kungfu-systems/site-libkungfu-dev",
+      "lockPath": "buildchain.upstreams/kfd.release.json",
+      "baseRef": "dev/v2/v2.7"
+    }
+  ],
+  "edges": [
+    {
+      "id": "kfd-to-site",
+      "from": "kfd",
+      "to": "site-libkungfu-dev",
+      "channelPolicy": "preserve"
+    }
+  ]
+}
+```
+
+`channelPolicy: "preserve"` is the default and maps:
+
+```text
+alpha   -> alpha
+release -> release
+```
+
+Cross-channel mapping is allowed only when an edge declares
+`channelPolicy: "explicit"` and a `channelMap`. Buildchain rejects cycles so a
+chain can fan out or continue as `A -> B -> C`, but cannot loop back into an
+already visited release line.
+
+## Upstream Release Envelope
+
+The upstream release envelope is the post-finalization fact set:
+
+```json
+{
+  "repository": "kungfu-systems/kfd",
+  "channel": "alpha",
+  "tag": "v1.4.0-alpha.3",
+  "sourceSha": "1111111111111111111111111111111111111111",
+  "package": {
+    "name": "@kungfu-tech/kfd",
+    "version": "1.4.0-alpha.3",
+    "integrity": "sha512-..."
+  },
+  "releasePassport": {
+    "url": "https://github.com/kungfu-systems/kfd/releases/download/v1.4.0-alpha.3/buildchain.release.json",
+    "sha256": "2222222222222222222222222222222222222222222222222222222222222222"
+  },
+  "siteBundle": {
+    "manifestSha256": "3333333333333333333333333333333333333333333333333333333333333333"
+  }
+}
+```
+
+The package version and integrity must be exact. Downstream build logic should
+install that version directly, not resolve `alpha` or `latest` again.
+
+## CLI
+
+Generate a propagation plan:
+
+```bash
+buildchain release-propagation plan \
+  --graph buildchain.release-propagation.json \
+  --upstream-release .buildchain/upstream-release.json \
+  --output .buildchain/release-propagation-plan.json \
+  --json
+```
+
+Write the downstream lock:
+
+```bash
+buildchain release-propagation write-lock \
+  --plan .buildchain/release-propagation-plan.json \
+  --target site-libkungfu-dev \
+  --cwd downstream-checkout \
+  --json
+```
+
+The written lock has contract
+`kungfu-buildchain-release-propagation-lock` and records:
+
+- upstream repository, channel, exact tag, source SHA;
+- npm package name, exact version, and sha512 integrity;
+- release passport URL and SHA-256;
+- optional site bundle manifest SHA-256;
+- downstream repository, channel, base ref, lock path;
+- edge id and channel policy.
+
+## Reusable Workflow
+
+Upstream repositories can call
+`.github/workflows/release-propagation.yml@v2` after release finalization:
+
+```yaml
+jobs:
+  propagate-site:
+    uses: kungfu-systems/buildchain/.github/workflows/release-propagation.yml@v2
+    with:
+      graph-json: ${{ needs.release.outputs.propagation-graph-json }}
+      upstream-release-json: ${{ needs.release.outputs.upstream-release-json }}
+      downstream-target: site-libkungfu-dev
+      downstream-repository: kungfu-systems/site-libkungfu-dev
+      downstream-base-ref: dev/v2/v2.7
+      dry-run: false
+    secrets:
+      propagation-token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}
+```
+
+The workflow plans propagation, checks out the downstream repository, writes the
+exact lock, and opens or updates a PR. It does not publish the downstream
+release directly. The downstream repository keeps its normal Buildchain
+governance: the PR updates source-of-truth facts, then downstream alpha or
+release publication runs through its own protected channel.
+
+## kfd to site-libkungfu-dev
+
+For `kfd -> site-libkungfu-dev`, the graph should preserve channels:
+
+- a `kfd` alpha release produces a downstream alpha lock and downstream alpha
+  publication consumes the exact `@kungfu-tech/kfd@...-alpha.N` package;
+- a `kfd` stable release produces a downstream release lock and downstream
+  stable publication consumes the exact stable package.
+
+This keeps the site synchronized to the package truth without allowing the site
+to drift onto a floating npm dist-tag.

package/docs/site-bundle-contract.md

@@ -68,3 +68,7 @@ The P0 bundle includes:
 Future minor lines can add examples, recipes, fixture indexes, and richer
 schema metadata without breaking existing consumers.
 
+`release-propagation.md` describes the package-to-package or package-to-site
+release chain model. The site bundle exposes that document and the
+`release-propagation` CLI entry so downstream sites can render the current
+Buildchain-owned propagation contract instead of hand-writing it.

package/fixtures/release-propagation-shaped/README.md

@@ -0,0 +1,6 @@
+# Release Propagation Fixture
+
+This fixture demonstrates a generic release propagation graph with a
+`kfd -> site-libkungfu-dev` shaped edge. It is safe test data only; tests use it
+to prove that Buildchain preserves alpha/release channels and writes an exact
+upstream release lock.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.6.2",
+  "version": "2.7.0-alpha.0",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -19,6 +19,7 @@
     "./logging": "./packages/core/logging.js",
     "./release-candidate": "./packages/core/release-candidate.js",
     "./release-passport": "./packages/core/release-passport.js",
+    "./release-propagation": "./packages/core/release-propagation.js",
     "./site/buildchain-site.json": "./dist/site/buildchain-site.json",
     "./site/site-manifest.json": "./dist/site/site-manifest.json",
     "./site/cli-registry.json": "./dist/site/cli-registry.json",
@@ -52,6 +53,7 @@
     "docs/product-mechanism.md",
     "docs/publish-transaction.md",
     "docs/release-passport.md",
+    "docs/release-propagation.md",
     "docs/release-candidate.md",
     "docs/release-flow.md",
     "docs/release-governance.md",

package/packages/core/index.js

@@ -143,3 +143,15 @@ export {
   truncateUtf8,
   workflowFrictionMarker,
 } from "./issue-reporting.js";
+
+export {
+  RELEASE_PROPAGATION_GRAPH_CONTRACT,
+  RELEASE_PROPAGATION_LOCK_CONTRACT,
+  RELEASE_PROPAGATION_PLAN_CONTRACT,
+  createReleasePropagationLock,
+  normalizeReleasePropagationGraph,
+  planReleasePropagation,
+  readReleasePropagationJson,
+  resolvePropagationChannel,
+  writeReleasePropagationLock,
+} from "./release-propagation.js";

package/packages/core/release-propagation.js

@@ -0,0 +1,354 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+export const RELEASE_PROPAGATION_GRAPH_CONTRACT = "kungfu-buildchain-release-propagation-graph";
+export const RELEASE_PROPAGATION_PLAN_CONTRACT = "kungfu-buildchain-release-propagation-plan";
+export const RELEASE_PROPAGATION_LOCK_CONTRACT = "kungfu-buildchain-release-propagation-lock";
+
+const SUPPORTED_CHANNELS = new Set(["alpha", "release"]);
+const SUPPORTED_CHANNEL_POLICIES = new Set(["preserve", "explicit"]);
+
+function stableJson(value) {
+  return `${JSON.stringify(sortJson(value), null, 2)}\n`;
+}
+
+function sortJson(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortJson);
+  }
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  return Object.fromEntries(
+    Object.entries(value)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, entry]) => [key, sortJson(entry)]),
+  );
+}
+
+function sha256Json(value) {
+  return crypto.createHash("sha256").update(stableJson(value)).digest("hex");
+}
+
+function assertPlainObject(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value;
+}
+
+function assertString(value, label) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function optionalString(value) {
+  return value === undefined || value === null ? "" : String(value).trim();
+}
+
+function normalizeChannel(value, label) {
+  const channel = assertString(value, label);
+  if (!SUPPORTED_CHANNELS.has(channel)) {
+    throw new Error(`${label} must be alpha or release`);
+  }
+  return channel;
+}
+
+function normalizeChannelMap(edge, label) {
+  const policy = edge.channelPolicy || "preserve";
+  if (!SUPPORTED_CHANNEL_POLICIES.has(policy)) {
+    throw new Error(`${label}.channelPolicy must be preserve or explicit`);
+  }
+  const map = {
+    alpha: "alpha",
+    release: "release",
+    ...(edge.channelMap || {}),
+  };
+  if (policy === "explicit" && !edge.channelMap) {
+    throw new Error(`${label}.channelMap is required when channelPolicy is explicit`);
+  }
+  for (const channel of Object.keys(map)) {
+    normalizeChannel(channel, `${label}.channelMap key`);
+    normalizeChannel(map[channel], `${label}.channelMap.${channel}`);
+  }
+  return { policy, map };
+}
+
+function normalizeNode(node, index) {
+  assertPlainObject(node, `nodes[${index}]`);
+  const normalized = {
+    id: assertString(node.id, `nodes[${index}].id`),
+    repository: assertString(node.repository, `nodes[${index}].repository`),
+    package: optionalString(node.package),
+    lockPath: optionalString(node.lockPath || node.lock_path),
+    baseRef: optionalString(node.baseRef || node.base_ref),
+    workflow: optionalString(node.workflow),
+  };
+  if (!/^[^/\s]+\/[^/\s]+$/.test(normalized.repository)) {
+    throw new Error(`nodes[${index}].repository must be owner/repo`);
+  }
+  return normalized;
+}
+
+function normalizeEdge(edge, index) {
+  assertPlainObject(edge, `edges[${index}]`);
+  const channel = normalizeChannelMap({
+    channelPolicy: edge.channelPolicy || edge.channel_policy,
+    channelMap: edge.channelMap || edge.channel_map,
+  }, `edges[${index}]`);
+  const channels = edge.channels === undefined
+    ? ["alpha", "release"]
+    : edge.channels.map((entry, channelIndex) => normalizeChannel(entry, `edges[${index}].channels[${channelIndex}]`));
+  return {
+    id: optionalString(edge.id) || `edge-${index + 1}`,
+    from: assertString(edge.from, `edges[${index}].from`),
+    to: assertString(edge.to, `edges[${index}].to`),
+    channels,
+    channelPolicy: channel.policy,
+    channelMap: channel.map,
+    lockPath: optionalString(edge.lockPath || edge.lock_path),
+    prBaseRef: optionalString(edge.prBaseRef || edge.pr_base_ref),
+  };
+}
+
+function assertUnique(values, label) {
+  const seen = new Set();
+  for (const value of values) {
+    if (seen.has(value)) {
+      throw new Error(`${label} contains duplicate value: ${value}`);
+    }
+    seen.add(value);
+  }
+}
+
+function assertAcyclic(nodes, edges) {
+  const outgoing = new Map(nodes.map((node) => [node.id, []]));
+  for (const edge of edges) {
+    outgoing.get(edge.from).push(edge.to);
+  }
+  const visiting = new Set();
+  const visited = new Set();
+  const stack = [];
+  function visit(id) {
+    if (visiting.has(id)) {
+      const start = stack.indexOf(id);
+      const cycle = stack.slice(start).concat(id).join(" -> ");
+      throw new Error(`release propagation graph contains a cycle: ${cycle}`);
+    }
+    if (visited.has(id)) {
+      return;
+    }
+    visiting.add(id);
+    stack.push(id);
+    for (const next of outgoing.get(id) || []) {
+      visit(next);
+    }
+    stack.pop();
+    visiting.delete(id);
+    visited.add(id);
+  }
+  for (const node of nodes) {
+    visit(node.id);
+  }
+}
+
+export function normalizeReleasePropagationGraph(input) {
+  const graph = assertPlainObject(input, "release propagation graph");
+  const nodes = (graph.nodes || []).map(normalizeNode);
+  const edges = (graph.edges || []).map(normalizeEdge);
+  if (nodes.length === 0) {
+    throw new Error("release propagation graph requires nodes[]");
+  }
+  assertUnique(nodes.map((node) => node.id), "nodes.id");
+  const nodeIds = new Set(nodes.map((node) => node.id));
+  for (const edge of edges) {
+    if (!nodeIds.has(edge.from)) {
+      throw new Error(`edge ${edge.id} references unknown from node: ${edge.from}`);
+    }
+    if (!nodeIds.has(edge.to)) {
+      throw new Error(`edge ${edge.id} references unknown to node: ${edge.to}`);
+    }
+  }
+  assertAcyclic(nodes, edges);
+  return {
+    schemaVersion: 1,
+    contract: RELEASE_PROPAGATION_GRAPH_CONTRACT,
+    channelPolicy: graph.channelPolicy || graph.channel_policy || "preserve",
+    nodes,
+    edges,
+  };
+}
+
+export function resolvePropagationChannel(edge, upstreamChannel) {
+  const channel = normalizeChannel(upstreamChannel, "upstreamRelease.channel");
+  if (!edge.channels.includes(channel)) {
+    return "";
+  }
+  const downstreamChannel = edge.channelMap[channel] || "";
+  return downstreamChannel ? normalizeChannel(downstreamChannel, `edge ${edge.id} downstream channel`) : "";
+}
+
+function normalizeReleasePassport(passport = {}) {
+  if (!passport || typeof passport !== "object" || Array.isArray(passport)) {
+    throw new Error("upstreamRelease.releasePassport must be an object");
+  }
+  return {
+    url: assertString(passport.url, "upstreamRelease.releasePassport.url"),
+    sha256: assertString(passport.sha256 || passport.digest, "upstreamRelease.releasePassport.sha256"),
+  };
+}
+
+function normalizePackageFact(pkg = {}) {
+  if (!pkg || typeof pkg !== "object" || Array.isArray(pkg)) {
+    throw new Error("upstreamRelease.package must be an object");
+  }
+  return {
+    name: assertString(pkg.name, "upstreamRelease.package.name"),
+    version: assertString(pkg.version, "upstreamRelease.package.version"),
+    integrity: assertString(pkg.integrity, "upstreamRelease.package.integrity"),
+  };
+}
+
+function normalizeUpstreamRelease(input) {
+  const release = assertPlainObject(input, "upstreamRelease");
+  return {
+    repository: assertString(release.repository, "upstreamRelease.repository"),
+    channel: normalizeChannel(release.channel, "upstreamRelease.channel"),
+    tag: assertString(release.tag, "upstreamRelease.tag"),
+    sourceSha: assertString(release.sourceSha || release.source_sha, "upstreamRelease.sourceSha"),
+    package: normalizePackageFact(release.package),
+    releasePassport: normalizeReleasePassport(release.releasePassport || release.release_passport),
+    siteBundle: release.siteBundle || release.site_bundle
+      ? {
+        manifestSha256: assertString(
+          release.siteBundle?.manifestSha256 || release.site_bundle?.manifest_sha256,
+          "upstreamRelease.siteBundle.manifestSha256",
+        ),
+      }
+      : undefined,
+  };
+}
+
+export function createReleasePropagationLock({
+  graph,
+  edge,
+  sourceNode,
+  targetNode,
+  upstreamRelease,
+  downstreamChannel,
+} = {}) {
+  const lock = {
+    schemaVersion: 1,
+    contract: RELEASE_PROPAGATION_LOCK_CONTRACT,
+    upstream: {
+      node: sourceNode.id,
+      repository: upstreamRelease.repository,
+      channel: upstreamRelease.channel,
+      tag: upstreamRelease.tag,
+      sourceSha: upstreamRelease.sourceSha,
+      package: upstreamRelease.package,
+      releasePassport: upstreamRelease.releasePassport,
+      siteBundle: upstreamRelease.siteBundle,
+    },
+    downstream: {
+      node: targetNode.id,
+      repository: targetNode.repository,
+      channel: downstreamChannel,
+      baseRef: edge.prBaseRef || targetNode.baseRef,
+      lockPath: edge.lockPath || targetNode.lockPath || ".buildchain/upstream-release.lock.json",
+    },
+    propagation: {
+      graphContract: graph.contract,
+      edge: edge.id,
+      channelPolicy: edge.channelPolicy,
+      channelMap: edge.channelMap,
+      exact: true,
+      floatingTags: false,
+    },
+  };
+  lock.lockSha256 = sha256Json({ ...lock, lockSha256: undefined });
+  return lock;
+}
+
+export function planReleasePropagation({ graph: graphInput, upstreamRelease: releaseInput, sourceNode = "" } = {}) {
+  const graph = normalizeReleasePropagationGraph(graphInput);
+  const upstreamRelease = normalizeUpstreamRelease(releaseInput);
+  const source = sourceNode
+    ? graph.nodes.find((node) => node.id === sourceNode)
+    : graph.nodes.find((node) => node.repository === upstreamRelease.repository || node.package === upstreamRelease.package.name);
+  if (!source) {
+    throw new Error("could not resolve source node for upstream release");
+  }
+  const targets = [];
+  for (const edge of graph.edges.filter((entry) => entry.from === source.id)) {
+    const downstreamChannel = resolvePropagationChannel(edge, upstreamRelease.channel);
+    if (!downstreamChannel) {
+      continue;
+    }
+    const target = graph.nodes.find((node) => node.id === edge.to);
+    const lock = createReleasePropagationLock({
+      graph,
+      edge,
+      sourceNode: source,
+      targetNode: target,
+      upstreamRelease,
+      downstreamChannel,
+    });
+    targets.push({
+      edge: edge.id,
+      source: source.id,
+      target: target.id,
+      repository: target.repository,
+      channel: downstreamChannel,
+      baseRef: lock.downstream.baseRef,
+      lockPath: lock.downstream.lockPath,
+      lock,
+    });
+  }
+  return {
+    schemaVersion: 1,
+    contract: RELEASE_PROPAGATION_PLAN_CONTRACT,
+    source: source.id,
+    upstreamRelease,
+    targets,
+    summary: {
+      targetCount: targets.length,
+      channels: [...new Set(targets.map((target) => target.channel))],
+      repositories: targets.map((target) => target.repository),
+    },
+  };
+}
+
+export function readReleasePropagationJson(value, { cwd = process.cwd(), label = "json" } = {}) {
+  const source = String(value || "").trim();
+  if (!source) {
+    throw new Error(`${label} is required`);
+  }
+  const candidatePath = path.isAbsolute(source) ? source : path.join(cwd, source);
+  if (fs.existsSync(candidatePath)) {
+    return JSON.parse(fs.readFileSync(candidatePath, "utf8"));
+  }
+  return JSON.parse(source);
+}
+
+export function writeReleasePropagationLock({ plan, target = "", cwd = process.cwd(), output = "" } = {}) {
+  assertPlainObject(plan, "plan");
+  const matches = plan.targets.filter((entry) => !target || entry.target === target || entry.repository === target);
+  if (matches.length !== 1) {
+    throw new Error(`expected exactly one propagation target, found ${matches.length}`);
+  }
+  const selected = matches[0];
+  const outputPath = path.resolve(cwd, output || selected.lockPath);
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, stableJson(selected.lock));
+  return {
+    target: selected.target,
+    repository: selected.repository,
+    channel: selected.channel,
+    path: outputPath,
+    lockSha256: selected.lock.lockSha256,
+  };
+}

package/scripts/check-inventory.mjs

@@ -21,6 +21,7 @@ const requiredPaths = [
   "docs/install.md",
   "docs/product-mechanism.md",
   "docs/release-passport.md",
+  "docs/release-propagation.md",
   "docs/site-bundle-contract.md",
   "docs/toolkit-observability.md",
   "docs/versioning.md",
@@ -53,6 +54,7 @@ const requiredPaths = [
   ".github/workflows/buildchain-patrol-weekly.yml",
   ".github/workflows/buildchain-patrol-monthly.yml",
   ".github/workflows/release-candidate-promote.yml",
+  ".github/workflows/release-propagation.yml",
   ".github/workflows/npm-publish.yml",
   ".github/workflows/binary-distribution.yml",
   ".github/workflows/verify.yml",
@@ -94,6 +96,9 @@ if (rootPackage.exports?.["./logging"] !== "./packages/core/logging.js") {
 if (rootPackage.exports?.["./release-passport"] !== "./packages/core/release-passport.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/release-passport");
 }
+if (rootPackage.exports?.["./release-propagation"] !== "./packages/core/release-propagation.js") {
+  throw new Error("root package must export @kungfu-tech/buildchain/release-propagation");
+}
 if (rootPackage.publishConfig?.access !== "public") {
   throw new Error("root package publishConfig.access must be public");
 }
@@ -110,6 +115,9 @@ for (const expectedFile of ["dist/site/", "docs/install.md", "docs/binary-distri
     throw new Error(`root package files must include ${expectedFile}`);
   }
 }
+if (!rootPackage.files?.includes("docs/release-propagation.md")) {
+  throw new Error("root package files must include docs/release-propagation.md");
+}
 const cliSource = fs.readFileSync(path.join(root, "bin/buildchain.mjs"), "utf8");
 const coreIndexSource = fs.readFileSync(path.join(root, "packages/core/index.js"), "utf8");
 const versioningDoc = fs.readFileSync(path.join(root, "docs/versioning.md"), "utf8");

package/scripts/generate-site-bundle.mjs

@@ -40,6 +40,7 @@ function buildSiteBundle() {
   const docs = [
     docEntry("install", "Install and verify Buildchain", "docs/install.md", "use"),
     docEntry("release-passport", "Release Passport protocol", "docs/release-passport.md", "verify"),
+    docEntry("release-propagation", "Release propagation", "docs/release-propagation.md", "use"),
     docEntry("binary-distribution", "Binary distribution contract", "docs/binary-distribution.md", "verify"),
     docEntry("toolkit-observability", "Toolkit observability", "docs/toolkit-observability.md", "use"),
     docEntry("site-bundle-contract", "Site bundle contract", "docs/site-bundle-contract.md", "use"),
@@ -69,6 +70,7 @@ function buildSiteBundle() {
       { id: "release-dry-run", usage: "buildchain release --dry-run --target-ref <ref>", purpose: "Explain what a channel merge would publish before the PR is merged." },
       { id: "collect-github-release", usage: "buildchain collect github-release --tag <tag>", purpose: "Collect release assets into a release passport." },
       { id: "verify-release-passport", usage: "buildchain verify release-passport <file-or-url>", purpose: "Fail closed unless a release passport and its evidence are complete." },
+      { id: "release-propagation", usage: "buildchain release-propagation <plan|write-lock>", purpose: "Plan channel-preserving downstream release PRs and write exact upstream release locks." },
       { id: "verify-infra-contract-evidence-bundle", usage: "buildchain verify infra-contract-evidence-bundle <file>", purpose: "Fail closed unless an infra-contract lifecycle evidence bundle is complete, hash-bound, and validation-consistent." },
       { id: "logging", 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." },
@@ -84,6 +86,7 @@ function buildSiteBundle() {
       { id: "build", path: ".github/workflows/.build.yml", surface: "reusable-build", status: "active" },
       { id: "web-surface", path: ".github/workflows/.web-surface.yml", surface: "site-app-deployment", status: "active" },
       { id: "buildchain-ref-promotion", path: ".github/workflows/buildchain-ref-promotion.yml", surface: "release-governance", status: "active" },
+      { id: "release-propagation", path: ".github/workflows/release-propagation.yml", surface: "release-propagation", status: "preview" },
       { id: "dev-pr-auto-merge", path: ".github/workflows/dev-pr-auto-merge.yml", surface: "dev-governance", status: "active" },
       { id: "binary-distribution", path: ".github/workflows/binary-distribution.yml", surface: "release-passport", status: "active" },
     ],
@@ -106,6 +109,13 @@ function buildSiteBundle() {
       bundle: "buildchain-release-bundle.tar.gz",
       contract: "kungfu-buildchain-release-passport",
     },
+    releasePropagation: {
+      graphContract: "kungfu-buildchain-release-propagation-graph",
+      planContract: "kungfu-buildchain-release-propagation-plan",
+      lockContract: "kungfu-buildchain-release-propagation-lock",
+      defaultChannelPolicy: "preserve",
+      defaultChannelMap: { alpha: "alpha", release: "release" },
+    },
     npm: {
       package: packageJson.name,
       command: packageJson.bin?.buildchain || "",

package/scripts/release-propagation.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  planReleasePropagation,
+  readReleasePropagationJson,
+  writeReleasePropagationLock,
+} from "../packages/core/release-propagation.js";
+
+function usage() {
+  return `Usage:
+  buildchain release-propagation plan --graph <json-or-path>
+                                      --upstream-release <json-or-path>
+                                      [--source-node <id>] [--output <file>] [--json]
+  buildchain release-propagation write-lock --plan <json-or-path>
+                                            [--target <id-or-repo>] [--cwd <dir>]
+                                            [--output <file>] [--json]
+`;
+}
+
+function readFlag(args, name, fallback = "") {
+  const index = args.indexOf(`--${name}`);
+  return index === -1 ? fallback : args[index + 1] || "";
+}
+
+function hasFlag(args, name) {
+  return args.includes(`--${name}`);
+}
+
+function printJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+function writeOutput(filePath, value) {
+  if (!filePath) {
+    return;
+  }
+  fs.mkdirSync(path.dirname(path.resolve(filePath)), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function runReleasePropagationCli(argv = process.argv.slice(2)) {
+  const [mode = "", ...args] = argv;
+  if (!mode || mode === "--help" || mode === "-h") {
+    process.stdout.write(usage());
+    return;
+  }
+  if (mode === "plan") {
+    const graph = readReleasePropagationJson(readFlag(args, "graph"), {
+      label: "--graph",
+      cwd: process.cwd(),
+    });
+    const upstreamRelease = readReleasePropagationJson(readFlag(args, "upstream-release"), {
+      label: "--upstream-release",
+      cwd: process.cwd(),
+    });
+    const plan = planReleasePropagation({
+      graph,
+      upstreamRelease,
+      sourceNode: readFlag(args, "source-node", ""),
+    });
+    writeOutput(readFlag(args, "output", ""), plan);
+    if (hasFlag(args, "json")) {
+      printJson(plan);
+    } else {
+      process.stdout.write(`release propagation targets: ${plan.summary.targetCount}\n`);
+      for (const target of plan.targets) {
+        process.stdout.write(`- ${target.repository} ${target.channel} lock=${target.lockPath}\n`);
+      }
+    }
+    return;
+  }
+  if (mode === "write-lock") {
+    const plan = readReleasePropagationJson(readFlag(args, "plan"), {
+      label: "--plan",
+      cwd: process.cwd(),
+    });
+    const result = writeReleasePropagationLock({
+      plan,
+      target: readFlag(args, "target", ""),
+      cwd: readFlag(args, "cwd", process.cwd()),
+      output: readFlag(args, "output", ""),
+    });
+    if (hasFlag(args, "json")) {
+      printJson(result);
+    } else {
+      process.stdout.write(`release propagation lock: ${result.path}\n`);
+      process.stdout.write(`lock sha256: ${result.lockSha256}\n`);
+    }
+    return;
+  }
+  throw new Error(`unsupported release-propagation command: ${mode}`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runReleasePropagationCli();
+}