@kungfu-tech/buildchain 2.14.3-alpha.0 → 2.14.3-alpha.10

package/scripts/generate-channel-promotion-workflow.mjs

@@ -0,0 +1,413 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const sourcePath = path.join(root, ".github/workflows/.release-candidate-promote.yml");
+const targetPath = path.join(root, ".github/workflows/release-candidate-promote.yml");
+const routingPath = path.join(root, ".buildchain/promotion-shell-routing.json");
+const internalInputs = new Set([
+  "promotion-router-ref",
+  "promotion-router-sha",
+  "promotion-shell-ref",
+  "promotion-shell-sha",
+  "promotion-runtime-ref",
+  "promotion-runtime-sha",
+  "promotion-contract-lock-path",
+  "promotion-contract-lock-digest",
+  "promotion-publication-channel",
+  "promotion-target-ref",
+  "promotion-override-used",
+]);
+
+function blockBetween(source, start, end) {
+  const startIndex = source.indexOf(start);
+  const endIndex = source.indexOf(end, startIndex + start.length);
+  if (startIndex < 0 || endIndex < 0) throw new Error(`unable to locate workflow block: ${start.trim()}`);
+  return source.slice(startIndex + start.length, endIndex);
+}
+
+function entries(block, indent = 6) {
+  const pattern = new RegExp(`^ {${indent}}([a-z0-9-]+):$`, "gm");
+  const matches = [...block.matchAll(pattern)];
+  return matches.map((match, index) => ({
+    name: match[1],
+    source: block.slice(match.index, matches[index + 1]?.index ?? block.length).trimEnd(),
+  }));
+}
+
+function publicInputs(inputBlock) {
+  const retained = entries(inputBlock)
+    .filter((entry) => !internalInputs.has(entry.name))
+    .map((entry) => entry.name === "buildchain-contract-lock-path"
+      ? entry.source.replace('        default: ".buildchain/contract-lock.json"', '        default: ""')
+      : entry.source);
+  return [
+    "      buildchain-channel:",
+    '        description: "Promotion workflow-shell/runtime channel: auto, alpha, or stable"',
+    '        default: "auto"',
+    "        type: string",
+    "        required: false",
+    "      buildchain-alpha-contract-lock-path:",
+    '        description: "Consumer-owned contract lock selected for alpha promotion"',
+    '        default: ".buildchain/alpha-contract-lock.json"',
+    "        type: string",
+    "        required: false",
+    "      buildchain-stable-contract-lock-path:",
+    '        description: "Consumer-owned contract lock selected for stable promotion"',
+    '        default: ".buildchain/contract-lock.json"',
+    "        type: string",
+    "        required: false",
+    ...retained,
+  ].join("\n");
+}
+
+function publicOutputs(outputBlock) {
+  const forwarded = entries(outputBlock).map((entry) => entry.source.replace(
+    /^        value:.*$/m,
+    `        value: \${{ jobs.alpha.outputs.${entry.name} || jobs.stable.outputs.${entry.name} }}`,
+  ));
+  const routed = [
+    ["buildchain-channel", "Selected promotion workflow-shell channel", "channel"],
+    ["promotion-router-ref", "Router workflow ref", "router-ref"],
+    ["promotion-router-sha", "Resolved router workflow SHA", "router-sha"],
+    ["promotion-shell-ref", "Selected advanced promotion workflow-shell ref", "shell-ref"],
+    ["promotion-shell-sha", "Resolved advanced promotion workflow-shell SHA", "shell-sha"],
+    ["promotion-runtime-ref", "Selected Buildchain runtime ref", "runtime-ref"],
+    ["promotion-runtime-sha", "Resolved Buildchain runtime SHA", "runtime-sha"],
+    ["promotion-contract-lock-path", "Selected consumer contract-lock path", "contract-lock-path"],
+    ["promotion-contract-lock-digest", "Selected consumer contract-lock sha256 digest", "contract-lock-digest"],
+    ["promotion-publication-channel", "Derived publication channel", "publication-channel"],
+    ["promotion-target-ref", "Derived promotion target ref", "target-ref"],
+    ["promotion-override-used", "Whether a trusted runtime override was used", "override-used"],
+  ].map(([name, description, output]) => [
+    `      ${name}:`,
+    `        description: "${description}"`,
+    `        value: \${{ jobs.resolve-promotion.outputs.${output} }}`,
+  ].join("\n"));
+  return [...routed, ...forwarded].join("\n");
+}
+
+function forwardedInputs(inputNames, { includeInternal = true } = {}) {
+  return inputNames
+    .filter((name) => includeInternal || !internalInputs.has(name))
+    .map((name) => {
+      const routed = {
+        "buildchain-ref": "runtime-ref",
+        "buildchain-contract-lock-path": "contract-lock-path",
+        channel: "publication-channel",
+        "target-ref": "target-ref",
+        "promotion-router-ref": "router-ref",
+        "promotion-router-sha": "router-sha",
+        "promotion-shell-ref": "shell-ref",
+        "promotion-shell-sha": "shell-sha",
+        "promotion-runtime-ref": "runtime-ref",
+        "promotion-runtime-sha": "runtime-sha",
+        "promotion-contract-lock-path": "contract-lock-path",
+        "promotion-contract-lock-digest": "contract-lock-digest",
+        "promotion-publication-channel": "publication-channel",
+        "promotion-target-ref": "target-ref",
+        "promotion-override-used": "override-used",
+      }[name];
+      if (name === "promotion-override-used") {
+        return `      ${name}: \${{ needs.resolve-promotion.outputs.override-used == 'true' }}`;
+      }
+      return routed
+        ? `      ${name}: \${{ needs.resolve-promotion.outputs.${routed} }}`
+        : `      ${name}: \${{ inputs.${name} }}`;
+    }).join("\n");
+}
+
+function validateWorkflowRoute(name, route, expectedLogicalRef) {
+  if (!route || typeof route !== "object") throw new Error(`promotion shell routing missing ${name} route`);
+  if (route.logicalRef !== expectedLogicalRef) {
+    throw new Error(`promotion shell ${name} logicalRef must be ${expectedLogicalRef}`);
+  }
+  if (!/^\.github\/workflows\/[.a-z0-9-]+\.ya?ml$/.test(route.workflowPath || "")) {
+    throw new Error(`promotion shell ${name} workflowPath must name a reusable workflow`);
+  }
+  if (!/^(?:v[0-9]+(?:-alpha)?|[0-9a-f]{40})$/.test(route.callRef || "")) {
+    throw new Error(`promotion shell ${name} callRef must be an official channel ref or exact SHA`);
+  }
+  if (typeof route.forwardInternalInputs !== "boolean") {
+    throw new Error(`promotion shell ${name} forwardInternalInputs must be boolean`);
+  }
+  return { ...route };
+}
+
+export function parsePromotionShellRouting(source, { major = 2 } = {}) {
+  const parsed = JSON.parse(source);
+  if (parsed.schemaVersion !== 1) throw new Error("promotion shell routing schemaVersion must be 1");
+  if (parsed.major !== major) throw new Error(`promotion shell routing major must be ${major}`);
+  return {
+    alpha: validateWorkflowRoute("alpha", parsed.alpha, `v${major}-alpha`),
+    stable: validateWorkflowRoute("stable", parsed.stable, `v${major}`),
+  };
+}
+
+export function generateChannelPromotionWorkflow(source, { major = 2, shellRouting } = {}) {
+  const routes = shellRouting || {
+    alpha: {
+      logicalRef: `v${major}-alpha`,
+      callRef: `v${major}-alpha`,
+      workflowPath: ".github/workflows/.release-candidate-promote.yml",
+      forwardInternalInputs: true,
+    },
+    stable: {
+      logicalRef: `v${major}`,
+      callRef: `v${major}`,
+      workflowPath: ".github/workflows/.release-candidate-promote.yml",
+      forwardInternalInputs: true,
+    },
+  };
+  const alphaRoute = validateWorkflowRoute("alpha", routes.alpha, `v${major}-alpha`);
+  const stableRoute = validateWorkflowRoute("stable", routes.stable, `v${major}`);
+  const inputs = blockBetween(source, "    inputs:\n", "    secrets:\n");
+  const secrets = blockBetween(source, "    secrets:\n", "    outputs:\n");
+  const outputs = blockBetween(source, "    outputs:\n", "\nconcurrency:\n");
+  const inputNames = entries(inputs).map((entry) => entry.name);
+  for (const required of ["buildchain-ref", "buildchain-contract-lock-path", "channel", "target-ref", ...internalInputs]) {
+    if (!inputNames.includes(required)) throw new Error(`advanced promotion workflow missing input: ${required}`);
+  }
+  const alphaForwarded = forwardedInputs(inputNames, {
+    includeInternal: alphaRoute.forwardInternalInputs,
+  });
+  const stableForwarded = forwardedInputs(inputNames, {
+    includeInternal: stableRoute.forwardInternalInputs,
+  });
+  return `# Generated by scripts/generate-channel-promotion-workflow.mjs. Do not edit directly.
+name: Release Candidate Promote
+
+on:
+  workflow_call:
+    inputs:
+${publicInputs(inputs)}
+    secrets:
+${secrets.trimEnd()}
+    outputs:
+${publicOutputs(outputs)}
+
+permissions:
+  actions: read
+  checks: write
+  contents: write
+  id-token: write
+  issues: write
+
+jobs:
+  resolve-promotion:
+    name: Resolve promotion workflow shell and runtime
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    outputs:
+      channel: \${{ steps.route.outputs.channel }}
+      publication-channel: \${{ steps.route.outputs.publication-channel }}
+      target-ref: \${{ steps.route.outputs.target-ref }}
+      router-ref: \${{ steps.router.outputs.ref }}
+      router-sha: \${{ steps.identities.outputs.router-sha }}
+      shell-ref: \${{ steps.route.outputs.shell-ref }}
+      shell-sha: \${{ steps.identities.outputs.shell-sha }}
+      runtime-ref: \${{ steps.route.outputs.runtime-ref }}
+      runtime-sha: \${{ steps.identities.outputs.runtime-sha }}
+      contract-lock-path: \${{ steps.lock.outputs.path }}
+      contract-lock-digest: \${{ steps.lock.outputs.digest }}
+      override-used: \${{ steps.route.outputs.override-used }}
+      selection-source: \${{ steps.route.outputs.selection-source }}
+      reason: \${{ steps.route.outputs.reason }}
+    steps:
+      - name: Resolve promotion router source
+        id: router
+        shell: bash
+        env:
+          BUILDCHAIN_ROUTER_WORKFLOW_REF: \${{ job.workflow_ref }}
+        run: |
+          set -euo pipefail
+          workflow_ref="\${BUILDCHAIN_ROUTER_WORKFLOW_REF}"
+          repository="\${workflow_ref%%/.github/workflows/*}"
+          ref="\${workflow_ref##*@}"
+          ref="\${ref#refs/heads/}"
+          ref="\${ref#refs/tags/}"
+          if [[ -z "\${repository}" || "\${repository}" = "\${workflow_ref}" || -z "\${ref}" ]]; then
+            echo "::error::Unable to resolve promotion router source from job.workflow_ref=\${workflow_ref}"
+            exit 1
+          fi
+          echo "repository=\${repository}" >> "\${GITHUB_OUTPUT}"
+          echo "ref=\${ref}" >> "\${GITHUB_OUTPUT}"
+
+      - name: Checkout promotion router
+        uses: actions/checkout@v7.0.0
+        with:
+          repository: \${{ steps.router.outputs.repository }}
+          ref: \${{ steps.router.outputs.ref }}
+          path: .buildchain/router
+          persist-credentials: false
+
+      - name: Resolve promotion channel
+        id: route
+        shell: bash
+        run: >-
+          node .buildchain/router/scripts/promotion-channel-router.mjs
+          --cwd .buildchain/router
+          --channel "\${{ inputs.buildchain-channel }}"
+          --buildchain-ref "\${{ inputs.buildchain-ref }}"
+          --publication-channel "\${{ inputs.channel }}"
+          --target-ref "\${{ inputs.target-ref || github.ref_name }}"
+          --router-ref "\${{ steps.router.outputs.ref }}"
+
+      - name: Authorize trusted runtime override
+        if: \${{ steps.route.outputs.override-used == 'true' }}
+        uses: actions/github-script@v8
+        with:
+          script: |
+            if (context.eventName !== "workflow_dispatch") {
+              throw new Error("promotion runtime override is only allowed for trusted workflow_dispatch runs");
+            }
+            const permission = await github.rest.repos.getCollaboratorPermissionLevel({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              username: context.actor,
+            });
+            const level = permission.data.user?.permissions || permission.data.permission || "none";
+            if (!["write", "maintain", "admin"].includes(level)) {
+              throw new Error(\`promotion runtime override requires write, maintain, or admin permission; actor has \${level}\`);
+            }
+
+      - name: Checkout selected promotion workflow shell
+        uses: actions/checkout@v7.0.0
+        with:
+          repository: \${{ steps.router.outputs.repository }}
+          ref: \${{ steps.route.outputs.shell-ref }}
+          path: .buildchain/shell
+          persist-credentials: false
+
+      - name: Checkout selected Buildchain runtime
+        uses: actions/checkout@v7.0.0
+        with:
+          repository: \${{ steps.router.outputs.repository }}
+          ref: \${{ steps.route.outputs.runtime-ref }}
+          path: .buildchain/runtime
+          persist-credentials: false
+
+      - name: Checkout promotion source
+        uses: actions/checkout@v7.0.0
+        with:
+          ref: \${{ inputs.target-sha || github.sha }}
+          path: .buildchain/source
+          persist-credentials: false
+
+      - name: Select and verify consumer contract lock
+        id: lock
+        shell: bash
+        env:
+          EXPLICIT_PATH: \${{ inputs.buildchain-contract-lock-path }}
+          ALPHA_PATH: \${{ inputs.buildchain-alpha-contract-lock-path }}
+          STABLE_PATH: \${{ inputs.buildchain-stable-contract-lock-path }}
+          CHANNEL: \${{ steps.route.outputs.channel }}
+        run: |
+          set -euo pipefail
+          path="\${EXPLICIT_PATH}"
+          if [[ -z "\${path}" ]]; then
+            if [[ "\${CHANNEL}" = "alpha" ]]; then path="\${ALPHA_PATH}"; else path="\${STABLE_PATH}"; fi
+          fi
+          if [[ -z "\${path}" || ! -f ".buildchain/source/\${path}" ]]; then
+            echo "::error::Selected promotion contract lock is missing: \${path:-<empty>}"
+            exit 1
+          fi
+          digest="sha256:$(shasum -a 256 ".buildchain/source/\${path}" | awk '{print $1}')"
+          echo "path=\${path}" >> "\${GITHUB_OUTPUT}"
+          echo "digest=\${digest}" >> "\${GITHUB_OUTPUT}"
+
+      - name: Resolve immutable promotion identities
+        id: identities
+        shell: bash
+        env:
+          CHANNEL: \${{ steps.route.outputs.channel }}
+          SELECTED_SHELL_REF: \${{ steps.route.outputs.shell-ref }}
+          ALPHA_SHELL_REF: ${alphaRoute.logicalRef}
+          ALPHA_SHELL_CALL_REF: ${alphaRoute.callRef}
+          ALPHA_SHELL_WORKFLOW_PATH: ${alphaRoute.workflowPath}
+          STABLE_SHELL_REF: ${stableRoute.logicalRef}
+          STABLE_SHELL_CALL_REF: ${stableRoute.callRef}
+          STABLE_SHELL_WORKFLOW_PATH: ${stableRoute.workflowPath}
+        run: |
+          set -euo pipefail
+          if [[ "\${CHANNEL}" = "alpha" ]]; then
+            expected_ref="\${ALPHA_SHELL_REF}"
+            call_ref="\${ALPHA_SHELL_CALL_REF}"
+            workflow_path="\${ALPHA_SHELL_WORKFLOW_PATH}"
+          else
+            expected_ref="\${STABLE_SHELL_REF}"
+            call_ref="\${STABLE_SHELL_CALL_REF}"
+            workflow_path="\${STABLE_SHELL_WORKFLOW_PATH}"
+          fi
+          if [[ "\${SELECTED_SHELL_REF}" != "\${expected_ref}" ]]; then
+            echo "::error::Selected promotion shell ref \${SELECTED_SHELL_REF} does not match configured \${expected_ref}"
+            exit 1
+          fi
+          test -f ".buildchain/shell/\${workflow_path}"
+          shell_sha="$(git -C .buildchain/shell rev-parse HEAD)"
+          if [[ "\${call_ref}" =~ ^[0-9a-f]{40}$ && "\${shell_sha}" != "\${call_ref}" ]]; then
+            echo "::error::Pinned promotion shell \${call_ref} does not match selected \${shell_sha}"
+            exit 1
+          fi
+          {
+            echo "router-sha=$(git -C .buildchain/router rev-parse HEAD)"
+            echo "shell-sha=\${shell_sha}"
+            echo "runtime-sha=$(git -C .buildchain/runtime rev-parse HEAD)"
+          } >> "\${GITHUB_OUTPUT}"
+
+  alpha:
+    name: Promote with alpha workflow shell
+    needs: resolve-promotion
+    if: \${{ needs.resolve-promotion.outputs.channel == 'alpha' }}
+    uses: kungfu-systems/buildchain/${alphaRoute.workflowPath}@${alphaRoute.callRef}
+    permissions:
+      actions: read
+      checks: write
+      contents: write
+      id-token: write
+      issues: write
+    with:
+${alphaForwarded}
+    secrets: inherit
+
+  stable:
+    name: Promote with stable workflow shell
+    needs: resolve-promotion
+    if: \${{ needs.resolve-promotion.outputs.channel == 'stable' }}
+    uses: kungfu-systems/buildchain/${stableRoute.workflowPath}@${stableRoute.callRef}
+    permissions:
+      actions: read
+      checks: write
+      contents: write
+      id-token: write
+      issues: write
+    with:
+${stableForwarded}
+    secrets: inherit
+`;
+}
+
+function main() {
+  const source = fs.readFileSync(sourcePath, "utf8");
+  const version = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).version;
+  const major = Number(String(version).match(/^(\d+)\./)?.[1]);
+  if (!Number.isInteger(major)) throw new Error("package version must expose a numeric major");
+  const shellRouting = parsePromotionShellRouting(fs.readFileSync(routingPath, "utf8"), { major });
+  const generated = generateChannelPromotionWorkflow(source, { major, shellRouting });
+  if (process.argv.includes("--check")) {
+    const current = fs.existsSync(targetPath) ? fs.readFileSync(targetPath, "utf8") : "";
+    if (current !== generated) {
+      console.error(".github/workflows/release-candidate-promote.yml is stale; run node scripts/generate-channel-promotion-workflow.mjs");
+      process.exitCode = 1;
+    }
+    return;
+  }
+  fs.writeFileSync(targetPath, generated);
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) main();

package/scripts/promotion-channel-router.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveBuildchainChannel } from "./buildchain-channel-router.mjs";
+
+const TARGETS = [
+  { pattern: /^alpha\/v(\d+)\/v\d+\.\d+$/, publicationChannel: "alpha", shellChannel: "alpha" },
+  { pattern: /^release\/v(\d+)\/v\d+\.\d+$/, publicationChannel: "release", shellChannel: "stable" },
+  { pattern: /^(?:publish-gate\/major|major-gate)$/, publicationChannel: "major", shellChannel: "stable" },
+];
+
+function normalized(value) {
+  return String(value ?? "").trim();
+}
+
+function targetIntent(targetRef, requestedPublicationChannel = "") {
+  const ref = normalized(targetRef).replace(/^refs\/heads\//, "");
+  const target = TARGETS.find((entry) => entry.pattern.test(ref));
+  if (!target) throw new Error(`unsupported promotion target ref: ${ref || "<empty>"}`);
+  const requested = normalized(requestedPublicationChannel).toLowerCase();
+  if (requested && requested !== target.publicationChannel) {
+    throw new Error(`promotion channel ${requested} does not match target ref ${ref} (${target.publicationChannel})`);
+  }
+  return {
+    targetRef: ref,
+    publicationChannel: target.publicationChannel,
+    shellChannel: target.shellChannel,
+  };
+}
+
+export function resolvePromotionChannel({
+  requestedChannel = "auto",
+  requestedRef = "",
+  publicationChannel = "",
+  targetRef = "",
+  routerRef = "",
+  packageVersion = "",
+} = {}) {
+  const intent = targetIntent(targetRef, publicationChannel);
+  const selected = resolveBuildchainChannel({
+    requestedChannel,
+    requestedRef,
+    publishChannel: intent.publicationChannel,
+    eventName: "workflow_call",
+    routerRef,
+    packageVersion,
+  });
+  const overrideUsed = selected.channel === "override";
+  if (!overrideUsed && selected.channel !== intent.shellChannel) {
+    throw new Error(
+      `promotion target ${intent.targetRef} requires ${intent.shellChannel} shell/runtime, got ${selected.channel}`,
+    );
+  }
+  const shellRef = intent.shellChannel === "alpha" ? `v${selected.major}-alpha` : `v${selected.major}`;
+  return {
+    targetRef: intent.targetRef,
+    publicationChannel: intent.publicationChannel,
+    channel: intent.shellChannel,
+    major: selected.major,
+    shellRef,
+    runtimeRef: selected.buildchainRef,
+    overrideUsed,
+    selectionSource: selected.selectionSource,
+    reason: selected.reason,
+  };
+}
+
+function parseArgs(argv) {
+  const values = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) throw new Error(`unexpected argument: ${token}`);
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith("--")) throw new Error(`missing value for ${token}`);
+    values[token.slice(2)] = value;
+    index += 1;
+  }
+  return values;
+}
+
+function readPackageVersion(cwd) {
+  return JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8")).version;
+}
+
+function writeOutputs(file, result) {
+  const outputs = {
+    "target-ref": result.targetRef,
+    "publication-channel": result.publicationChannel,
+    channel: result.channel,
+    major: String(result.major),
+    "shell-ref": result.shellRef,
+    "runtime-ref": result.runtimeRef,
+    "override-used": String(result.overrideUsed),
+    "selection-source": result.selectionSource,
+    reason: result.reason,
+  };
+  fs.appendFileSync(file, Object.entries(outputs).map(([key, value]) => `${key}=${value}\n`).join(""));
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const cwd = path.resolve(args.cwd || process.cwd());
+  const result = resolvePromotionChannel({
+    requestedChannel: args.channel,
+    requestedRef: args["buildchain-ref"],
+    publicationChannel: args["publication-channel"],
+    targetRef: args["target-ref"],
+    routerRef: args["router-ref"],
+    packageVersion: readPackageVersion(cwd),
+  });
+  if (process.env.GITHUB_OUTPUT) writeOutputs(process.env.GITHUB_OUTPUT, result);
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`promotion-channel-router: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/stable-candidate-patrol.mjs

@@ -223,7 +223,7 @@ export async function runStableCandidatePatrol(optionsInput = {}, clientInput) {
           `Buildchain Stable Candidate Patrol human release-now for ${selection.candidate.version}`,
         );
       }
-      await client.ensureBranch(refs.sourceRef, selection.candidate.sha);
+      await client.ensureBranch(refs.sourceRef, selection.candidate.sha, refs.targetRef);
       const pullRequest = await client.ensurePromotionPullRequest({
         head: refs.sourceRef,
         base: refs.targetRef,
@@ -371,15 +371,64 @@ export function createGitHubStableCandidateClient({ repository: repositoryInput,
         },
       });
     },
-    async ensureBranch(ref, candidateSha) {
+    async ensureBranch(ref, candidateSha, targetRef) {
       const current = await api(`/repos/${owner}/${repo}/git/ref/heads/${encodeRef(ref)}`, { allow404: true });
-      if (!current) {
+      if (!targetRef) {
+        if (!current) {
+          return api(`/repos/${owner}/${repo}/git/refs`, { method: "POST", body: { ref: `refs/heads/${ref}`, sha: candidateSha } });
+        }
+        if (current.object.sha !== candidateSha) {
+          throw new Error(`source-lock branch ${ref} already points to ${current.object.sha}, not ${candidateSha}`);
+        }
+        return current;
+      }
+
+      const candidateCommit = await api(`/repos/${owner}/${repo}/git/commits/${candidateSha}`);
+      let sourceSha = current?.object?.sha || candidateSha;
+      if (sourceSha !== candidateSha) {
+        const sourceCommit = await api(`/repos/${owner}/${repo}/git/commits/${sourceSha}`);
+        if (sourceCommit.tree?.sha !== candidateCommit.tree?.sha) {
+          throw new Error(`source-lock branch ${ref} no longer preserves candidate ${candidateSha} tree`);
+        }
+        const candidateLineage = await api(`/repos/${owner}/${repo}/compare/${candidateSha}...${sourceSha}`);
+        if (!["ahead", "identical"].includes(candidateLineage.status)) {
+          throw new Error(`source-lock branch ${ref} no longer descends from candidate ${candidateSha}`);
+        }
+      }
+
+      const target = await api(`/repos/${owner}/${repo}/git/ref/heads/${encodeRef(targetRef)}`);
+      const targetSha = target.object?.sha || "";
+      const targetLineage = await api(`/repos/${owner}/${repo}/compare/${targetSha}...${sourceSha}`);
+      if (["ahead", "identical"].includes(targetLineage.status)) {
+        if (current) return current;
         return api(`/repos/${owner}/${repo}/git/refs`, { method: "POST", body: { ref: `refs/heads/${ref}`, sha: candidateSha } });
       }
-      if (current.object.sha !== candidateSha) {
-        throw new Error(`source-lock branch ${ref} already points to ${current.object.sha}, not ${candidateSha}`);
+
+      const identity = { name: "Buildchain Patrol", email: "buildchain-patrol@kungfu.link" };
+      const reconciliation = await api(`/repos/${owner}/${repo}/git/commits`, {
+        method: "POST",
+        body: {
+          message: [
+            "chore(buildchain): reconcile stable source-lock ancestry",
+            "",
+            `Preserve the exact candidate tree from ${candidateSha} while admitting ${targetRef} at ${targetSha}.`,
+            "",
+            "Signed-off-by: Buildchain Patrol <buildchain-patrol@kungfu.link>",
+          ].join("\n"),
+          tree: candidateCommit.tree.sha,
+          parents: [sourceSha, targetSha],
+          author: identity,
+          committer: identity,
+        },
+      });
+      sourceSha = reconciliation.sha;
+      if (!current) {
+        return api(`/repos/${owner}/${repo}/git/refs`, { method: "POST", body: { ref: `refs/heads/${ref}`, sha: sourceSha } });
       }
-      return current;
+      return api(`/repos/${owner}/${repo}/git/refs/heads/${encodeRef(ref)}`, {
+        method: "PATCH",
+        body: { sha: sourceSha, force: false },
+      });
     },
     async ensurePromotionPullRequest({ head, base, title, body }) {
       const open = await api(`/repos/${owner}/${repo}/pulls?state=open&head=${encodeURIComponent(`${owner}:${head}`)}&base=${encodeURIComponent(base)}&per_page=20`);