@kungfu-tech/buildchain 2.12.0 → 2.12.1-alpha.10

package/packages/core/kfd3-surface-register.js

@@ -67,6 +67,63 @@ function normalizeKinds(kinds = []) {
   return [...new Set(selected.map(normalizeKind))].sort();
 }
 
+export function normalizeKfd3DistributionDeclaration(distribution, { surfaceId = "surface" } = {}) {
+  if (!distribution || typeof distribution !== "object" || Array.isArray(distribution)) {
+    throw new Error(`KFD-3 surface ${surfaceId} distribution must be an object`);
+  }
+  const registrar = String(distribution.registrar || "").trim();
+  if (!registrar) {
+    throw new Error(`KFD-3 surface ${surfaceId} distribution.registrar is required`);
+  }
+  const tasks = Array.isArray(distribution.tasks)
+    ? [...new Set(distribution.tasks.map((entry) => String(entry || "").trim()).filter(Boolean))]
+    : [];
+  if (tasks.length === 0) {
+    throw new Error(`KFD-3 surface ${surfaceId} distribution.tasks must contain at least one task`);
+  }
+  const sourceArtifacts = Array.isArray(distribution.artifacts) ? distribution.artifacts : [];
+  if (sourceArtifacts.length === 0) {
+    throw new Error(`KFD-3 surface ${surfaceId} distribution.artifacts must contain at least one artifact`);
+  }
+  const artifacts = sourceArtifacts.map((artifact, index) => {
+    if (!artifact || typeof artifact !== "object" || Array.isArray(artifact)) {
+      throw new Error(`KFD-3 surface ${surfaceId} distribution.artifacts[${index}] must be an object`);
+    }
+    const normalized = {
+      ...artifact,
+      kind: String(artifact.kind || "").trim(),
+      platform: String(artifact.platform || "").trim(),
+      pathGlob: String(artifact.pathGlob || "").trim(),
+    };
+    for (const field of ["kind", "platform", "pathGlob"]) {
+      if (!normalized[field]) {
+        throw new Error(`KFD-3 surface ${surfaceId} distribution.artifacts[${index}].${field} is required`);
+      }
+    }
+    if (artifact.sha256 !== undefined) {
+      normalized.sha256 = String(artifact.sha256 || "").trim().toLowerCase();
+      if (!/^[a-f0-9]{64}$/.test(normalized.sha256)) {
+        throw new Error(`KFD-3 surface ${surfaceId} distribution.artifacts[${index}].sha256 must be 64 lowercase hex characters`);
+      }
+    }
+    return normalized;
+  });
+  return {
+    ...distribution,
+    registrar,
+    tasks,
+    artifacts,
+  };
+}
+
+function normalizeRegistrySurface(entry) {
+  if (!entry?.distribution) return entry;
+  return {
+    ...entry,
+    distribution: normalizeKfd3DistributionDeclaration(entry.distribution, { surfaceId: entry.id || "surface" }),
+  };
+}
+
 function stableId(value) {
   return String(value || "")
     .toLowerCase()
@@ -366,7 +423,7 @@ export function readKfd3SurfaceRegistry({ cwd = process.cwd(), registryPath = ""
     contract: registry.contract || KFD3_SURFACE_REGISTRY_CONTRACT,
     product: registry.product || {},
     registryPath: registry.registryPath || effectiveRegistryPath,
-    surfaces: Array.isArray(registry.surfaces) ? registry.surfaces : [],
+    surfaces: Array.isArray(registry.surfaces) ? registry.surfaces.map(normalizeRegistrySurface) : [],
     policy: registry.policy || {},
   };
 }
@@ -379,7 +436,7 @@ export function writeKfd3SurfaceRegistry({ cwd = process.cwd(), registryPath = "
     product: registry.product || {},
     registryPath: effectiveRegistryPath,
     surfaces: uniqueSurfaces(registry.surfaces || []).map((entry) => ({
-      ...entry,
+      ...normalizeRegistrySurface(entry),
       state: entry.state || "declared",
       declaration: entry.declaration || {
         owner: "product",

package/packages/core/stable-candidate-ledger.js

@@ -0,0 +1,276 @@
+export const STABLE_CANDIDATE_LEDGER_CONTRACT = "kungfu-buildchain-stable-candidate-ledger";
+export const STABLE_CANDIDATE_STATES = Object.freeze([
+  "soaking",
+  "qualified",
+  "revoked",
+  "promoted",
+]);
+
+function text(value = "") {
+  return String(value ?? "").trim();
+}
+
+function iso(value, label) {
+  const normalized = text(value);
+  const milliseconds = Date.parse(normalized);
+  if (!normalized || !Number.isFinite(milliseconds)) {
+    throw new Error(`${label} must be an ISO-8601 timestamp`);
+  }
+  return new Date(milliseconds).toISOString();
+}
+
+function exactAlpha(version) {
+  const normalized = text(version).replace(/^v/, "");
+  const match = normalized.match(/^(\d+)\.(\d+)\.(\d+)-alpha\.(\d+)$/);
+  if (!match) {
+    throw new Error(`candidate version must be an exact alpha, got ${version || "<empty>"}`);
+  }
+  return {
+    version: normalized,
+    stableVersion: `${match[1]}.${match[2]}.${match[3]}`,
+    order: match.slice(1).map(Number),
+  };
+}
+
+function sha(value, label = "candidate sha") {
+  const normalized = text(value).toLowerCase();
+  if (!/^[0-9a-f]{40}$/.test(normalized)) {
+    throw new Error(`${label} must be a 40-character commit SHA`);
+  }
+  return normalized;
+}
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function compareCandidates(left, right) {
+  const a = exactAlpha(left.version).order;
+  const b = exactAlpha(right.version).order;
+  for (let index = 0; index < a.length; index += 1) {
+    if (a[index] !== b[index]) return a[index] - b[index];
+  }
+  return left.publishedAt.localeCompare(right.publishedAt);
+}
+
+export function createStableCandidateLedger({ repository, targetBranch, now = new Date().toISOString() } = {}) {
+  const normalizedRepository = text(repository);
+  const normalizedTargetBranch = text(targetBranch).replace(/^refs\/heads\//, "");
+  if (!/^[^/\s]+\/[^/\s]+$/.test(normalizedRepository)) {
+    throw new Error(`repository must be owner/repo, got ${repository || "<empty>"}`);
+  }
+  if (!/^release\/v\d+\/v\d+\.\d+$/.test(normalizedTargetBranch)) {
+    throw new Error(`targetBranch must be release/vN/vN.M, got ${targetBranch || "<empty>"}`);
+  }
+  return {
+    schemaVersion: 1,
+    contract: STABLE_CANDIDATE_LEDGER_CONTRACT,
+    repository: normalizedRepository,
+    targetBranch: normalizedTargetBranch,
+    hold: { enabled: false, reason: "", updatedAt: iso(now, "now") },
+    candidates: [],
+    updatedAt: iso(now, "now"),
+  };
+}
+
+export function normalizeStableCandidateLedger(input, expected = {}) {
+  const ledger = clone(input || {});
+  if (ledger.contract !== STABLE_CANDIDATE_LEDGER_CONTRACT || Number(ledger.schemaVersion) !== 1) {
+    throw new Error(`stable candidate ledger must use ${STABLE_CANDIDATE_LEDGER_CONTRACT} schemaVersion 1`);
+  }
+  if (expected.repository && ledger.repository !== expected.repository) {
+    throw new Error(`stable candidate ledger repository mismatch: ${ledger.repository} != ${expected.repository}`);
+  }
+  if (expected.targetBranch && ledger.targetBranch !== expected.targetBranch) {
+    throw new Error(`stable candidate ledger targetBranch mismatch: ${ledger.targetBranch} != ${expected.targetBranch}`);
+  }
+  ledger.hold ||= { enabled: false, reason: "", updatedAt: ledger.updatedAt };
+  ledger.candidates = (ledger.candidates || []).map((candidate) => {
+    const parsed = exactAlpha(candidate.version);
+    const state = text(candidate.state);
+    if (!STABLE_CANDIDATE_STATES.includes(state)) {
+      throw new Error(`unsupported candidate state ${state || "<empty>"}`);
+    }
+    return {
+      ...candidate,
+      version: parsed.version,
+      stableVersion: parsed.stableVersion,
+      sha: sha(candidate.sha),
+      publishedAt: iso(candidate.publishedAt, `candidate ${parsed.version} publishedAt`),
+      state,
+    };
+  });
+  return ledger;
+}
+
+export function registerStableCandidate(ledgerInput, candidateInput, { now = new Date().toISOString() } = {}) {
+  const ledger = normalizeStableCandidateLedger(ledgerInput);
+  const parsed = exactAlpha(candidateInput.version);
+  const candidateSha = sha(candidateInput.sha);
+  const existing = ledger.candidates.find((candidate) => candidate.version === parsed.version);
+  if (existing) {
+    if (existing.sha !== candidateSha) {
+      throw new Error(`candidate ${parsed.version} is already bound to ${existing.sha}, not ${candidateSha}`);
+    }
+    return ledger;
+  }
+  ledger.candidates.push({
+    version: parsed.version,
+    stableVersion: parsed.stableVersion,
+    sha: candidateSha,
+    tag: `v${parsed.version}`,
+    publishedAt: iso(candidateInput.publishedAt, `candidate ${parsed.version} publishedAt`),
+    state: "soaking",
+    qualification: {
+      ok: false,
+      observedAt: "",
+      soakStartedAt: "",
+      soakElapsedSeconds: 0,
+      requiredSeconds: 0,
+      checks: [],
+    },
+    decision: { reason: "registered", updatedAt: iso(now, "now"), actor: text(candidateInput.actor) },
+  });
+  ledger.candidates.sort(compareCandidates);
+  ledger.updatedAt = iso(now, "now");
+  return ledger;
+}
+
+export function qualifyStableCandidate(
+  ledgerInput,
+  observation,
+  { minimumSoakSeconds = 3600, now = new Date().toISOString() } = {},
+) {
+  const ledger = normalizeStableCandidateLedger(ledgerInput);
+  const version = exactAlpha(observation.version).version;
+  const candidate = ledger.candidates.find((entry) => entry.version === version);
+  if (!candidate) throw new Error(`candidate ${version} is not registered`);
+  if (candidate.sha !== sha(observation.sha)) {
+    throw new Error(`candidate ${version} observation SHA does not match ledger`);
+  }
+  if (["revoked", "promoted"].includes(candidate.state)) return ledger;
+
+  const checks = Array.isArray(observation.checks) ? observation.checks.map((check) => ({
+    id: text(check.id),
+    status: text(check.status),
+    completedAt: check.completedAt ? iso(check.completedAt, `check ${check.id} completedAt`) : "",
+    evidenceUrl: text(check.evidenceUrl),
+  })) : [];
+  const passed = checks.length > 0 && checks.every((check) => check.id && check.status === "pass" && check.completedAt);
+  const latestCheck = passed ? Math.max(...checks.map((check) => Date.parse(check.completedAt))) : NaN;
+  const soakStartedAt = passed
+    ? new Date(Math.max(Date.parse(candidate.publishedAt), latestCheck)).toISOString()
+    : "";
+  const elapsedSeconds = passed
+    ? Math.max(0, Math.floor((Date.parse(iso(now, "now")) - Date.parse(soakStartedAt)) / 1000))
+    : 0;
+  candidate.qualification = {
+    ok: passed && elapsedSeconds >= Number(minimumSoakSeconds),
+    observedAt: iso(now, "now"),
+    soakStartedAt,
+    soakElapsedSeconds: elapsedSeconds,
+    requiredSeconds: Number(minimumSoakSeconds),
+    checks,
+  };
+  candidate.state = candidate.qualification.ok ? "qualified" : "soaking";
+  candidate.decision = {
+    reason: candidate.qualification.ok ? "qualification-satisfied" : passed ? "soaking" : "checks-incomplete",
+    updatedAt: iso(now, "now"),
+    actor: text(observation.actor),
+  };
+  ledger.updatedAt = iso(now, "now");
+  return ledger;
+}
+
+export function revokeStableCandidate(ledgerInput, versionInput, { reason, actor = "", now = new Date().toISOString() } = {}) {
+  const ledger = normalizeStableCandidateLedger(ledgerInput);
+  const version = exactAlpha(versionInput).version;
+  const candidate = ledger.candidates.find((entry) => entry.version === version);
+  if (!candidate) throw new Error(`candidate ${version} is not registered`);
+  if (candidate.state === "promoted") throw new Error(`promoted candidate ${version} cannot be revoked`);
+  if (!text(reason)) throw new Error("candidate revocation requires a reason");
+  candidate.state = "revoked";
+  candidate.decision = { reason: text(reason), actor: text(actor), updatedAt: iso(now, "now") };
+  ledger.updatedAt = iso(now, "now");
+  return ledger;
+}
+
+export function setStableCandidateHold(ledgerInput, enabled, { reason = "", now = new Date().toISOString() } = {}) {
+  const ledger = normalizeStableCandidateLedger(ledgerInput);
+  if (enabled && !text(reason)) throw new Error("enabling stable candidate hold requires a reason");
+  ledger.hold = { enabled: Boolean(enabled), reason: text(reason), updatedAt: iso(now, "now") };
+  ledger.updatedAt = iso(now, "now");
+  return ledger;
+}
+
+export function selectStableCandidate(ledgerInput, { releaseNow = "", now = new Date().toISOString() } = {}) {
+  const ledger = normalizeStableCandidateLedger(ledgerInput);
+  if (ledger.hold.enabled && !releaseNow) {
+    return { selected: false, reason: "repository-held", hold: ledger.hold };
+  }
+  if (releaseNow) {
+    const version = exactAlpha(releaseNow).version;
+    const candidate = ledger.candidates.find((entry) => entry.version === version);
+    if (!candidate) return { selected: false, reason: "release-now-candidate-missing", version };
+    if (["revoked", "promoted"].includes(candidate.state)) {
+      return { selected: false, reason: `release-now-candidate-${candidate.state}`, candidate };
+    }
+    return { selected: true, reason: "human-release-now", authority: "human", candidate };
+  }
+  const candidates = ledger.candidates
+    .filter((candidate) => candidate.state === "qualified")
+    .sort(compareCandidates);
+  const candidate = candidates.at(-1);
+  return candidate
+    ? { selected: true, reason: "latest-qualified", authority: "policy", candidate }
+    : { selected: false, reason: "no-qualified-candidate" };
+}
+
+export function markStableCandidatePromoted(
+  ledgerInput,
+  versionInput,
+  { stableTag = "", stableSha = "", now = new Date().toISOString() } = {},
+) {
+  const ledger = normalizeStableCandidateLedger(ledgerInput);
+  const version = exactAlpha(versionInput).version;
+  const candidate = ledger.candidates.find((entry) => entry.version === version);
+  if (!candidate) throw new Error(`candidate ${version} is not registered`);
+  if (!candidate.qualification?.ok && candidate.decision?.reason !== "human-release-now") {
+    throw new Error(`candidate ${version} is not qualified for promotion`);
+  }
+  candidate.state = "promoted";
+  candidate.promotion = {
+    stableTag: text(stableTag) || `v${candidate.stableVersion}`,
+    stableSha: stableSha ? sha(stableSha, "stable sha") : "",
+    promotedAt: iso(now, "now"),
+  };
+  candidate.decision = { reason: "promoted", actor: "", updatedAt: iso(now, "now") };
+  for (const entry of ledger.candidates) {
+    if (entry.version !== version && entry.stableVersion === candidate.stableVersion && entry.state !== "promoted") {
+      entry.state = "revoked";
+      entry.decision = {
+        reason: `stable-version-promoted-by:${version}`,
+        actor: "buildchain",
+        updatedAt: iso(now, "now"),
+      };
+    }
+  }
+  ledger.updatedAt = iso(now, "now");
+  return ledger;
+}
+
+export function stableCandidatePromotionRefs(candidateInput, targetBranch) {
+  const candidate = { ...candidateInput, ...exactAlpha(candidateInput.version) };
+  const normalizedTarget = text(targetBranch).replace(/^refs\/heads\//, "");
+  const match = normalizedTarget.match(/^release\/(v\d+)\/(v\d+\.\d+)$/);
+  if (!match) throw new Error(`targetBranch must be release/vN/vN.M, got ${targetBranch || "<empty>"}`);
+  if (`v${candidate.stableVersion.split(".").slice(0, 2).join(".")}` !== match[2]) {
+    throw new Error(`candidate ${candidate.version} does not belong to ${normalizedTarget}`);
+  }
+  return {
+    sourceRef: `publish-gate/release/${match[1]}/${match[2]}/${candidate.version}`,
+    targetRef: normalizedTarget,
+    exactAlphaTag: `v${candidate.version}`,
+    stableTag: `v${candidate.stableVersion}`,
+  };
+}

package/scripts/build-standalone-binary.mjs

@@ -176,9 +176,10 @@ function bundleCli({ cwd, tempDir, version, logger }) {
   sourcemap: false,
   dts: false,
   shims: true,
-  noExternal: ["smol-toml"],
+  noExternal: ["smol-toml", /^@kungfu-tech\\/kfd(?:\\/|$)/],
   define: {
     "process.env.BUILDCHAIN_EMBEDDED_PACKAGE_VERSION": ${JSON.stringify(JSON.stringify(version || packageVersion(cwd)))},
+    "process.env.BUILDCHAIN_EMBEDDED_ENTRYPOINT": ${JSON.stringify(JSON.stringify("1"))},
   },
 };
 `);

package/scripts/check-inventory.mjs

@@ -683,6 +683,8 @@ for (const requiredSnippet of [
   "checkout-cache-mode",
   "BUILDCHAIN_CHECKOUT_CACHE_MIRROR_URL_TEMPLATE",
   "sourceCheckout",
+  "Shifu Cache Profile Passthrough",
+  "opaque reference and digest",
 ]) {
   if (!reusableBuildSurfaceDoc.includes(requiredSnippet)) {
     throw new Error(`reusable build surface doc missing contract lock snippet: ${requiredSnippet}`);
@@ -732,7 +734,8 @@ for (const requiredSnippet of [
   "../packages/core/logging.js",
   "standalone.cli-bundle.create",
   "BUILDCHAIN_EMBEDDED_PACKAGE_VERSION",
-  "noExternal: [\"smol-toml\"]",
+  "BUILDCHAIN_EMBEDDED_ENTRYPOINT",
+  "noExternal: [\"smol-toml\",",
   "--macho-segment-name",
   "mainFormat: \"commonjs\"",
   "standalone.sea-blob.create",

package/scripts/generate-site-bundle.mjs

@@ -319,6 +319,7 @@ const manualMetaById = new Map(Object.entries({
   "binary-distribution": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "stable", order: 110 },
   "publish-transaction": { capabilityGroup: "release-passport-trust", audience: ["release-operator"], maturity: "stable", order: 120 },
   "release-candidate": { capabilityGroup: "reusable-build", audience: ["release-operator", "consumer"], maturity: "stable", order: 130 },
+  "stable-candidate-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer"], maturity: "preview", order: 135 },
   "reusable-build-surface": { capabilityGroup: "reusable-build", audience: ["consumer", "release-operator"], maturity: "stable", order: 200 },
   "lifecycle-protocol": { capabilityGroup: "reusable-build", audience: ["consumer", "developer"], maturity: "stable", order: 210 },
   "runtime-train-validation": { capabilityGroup: "governance-versioning", audience: ["maintainer", "consumer"], maturity: "stable", order: 220 },
@@ -394,6 +395,7 @@ function cliCommandMeta(id) {
     "inspect-artifact": { group: "release-passport-trust", purpose: "Inspect artifact evidence." },
     "inspect-release": { group: "release-passport-trust", purpose: "Inspect release passport evidence." },
     kfd: { group: "kfd-trust", purpose: "Inspect KFD standards, schemas, and versioned KFD command families." },
+    layout: { group: "kfd-trust", purpose: "Return the versioned repository-layout and KFD registry discovery contract for tools such as Shifu." },
     "kfd-schema": { group: "kfd-trust", purpose: "Inspect KFD schema command families." },
     "kfd-schema-list": { group: "kfd-trust", purpose: "List machine-readable schemas exposed by the KFD package standards metadata." },
     "kfd-schema-show": { group: "kfd-trust", purpose: "Print a machine-readable KFD schema from the KFD package standards metadata." },
@@ -472,12 +474,13 @@ function nodeApiMeta(exportName) {
     "./artifact-passport": { group: "release-passport-trust", summary: "Artifact passport digest and evidence helper APIs." },
     "./release-passport": { group: "release-passport-trust", summary: "Release passport collection, verification, explanation, and evidence APIs." },
     "./release-candidate": { group: "reusable-build", summary: "PR-stage release-candidate artifact, passport, and promote-only resolver APIs." },
+    "./stable-candidate-ledger": { group: "governance-versioning", summary: "Immutable alpha candidate ledger, qualification, revocation, selection, and exact stable source-lock APIs." },
     "./release-propagation": { group: "site-and-propagation", summary: "Release propagation graph, plan, and exact upstream lock APIs." },
     "./release-line-bootstrap": { group: "governance-versioning", summary: "Semver release-line bootstrap planning and version-state APIs." },
     "./buildchain-contract": { group: "governance-versioning", summary: "Runtime contract world and compatibility digest APIs for floating-ref drift checks." },
     "./surface-manifest": { group: "site-and-propagation", summary: "Surface manifest timestamp and reproducibility policy APIs." },
     "./issue-reporting": { group: "observability-diagnostics", summary: "Buildchain-owned issue reporting API for workflow friction feedback." },
-    "./buildchain-layout": { group: "kfd-trust", summary: "Canonical .buildchain repository layout constants, path resolution, and migration APIs." },
+    "./buildchain-layout": { group: "kfd-trust", summary: "Versioned Buildchain repository-layout discovery contract plus canonical .buildchain path resolution and migration APIs." },
     "./kfd": { group: "kfd-trust", summary: "Unified KFD standards, schema discovery, KFD-1/KFD-2/KFD-3 grouped APIs, KFD-4 schema discovery, upstream KFD aggregate facts, and Buildchain KFD claim helpers." },
     "./public-surface-audit": { group: "kfd-trust", summary: "Reverse audit APIs for CLI, workflow, action, site page, and documentation command surfaces." },
     "./kfd-gate": { group: "kfd-trust", summary: "KFD-1/KFD-2/KFD-3 release gate evidence and validation APIs." },
@@ -747,6 +750,7 @@ function buildSiteBundle() {
       "docs/kfd-support.md",
       "docs/reusable-build-surface.md",
       "docs/release-candidate.md",
+      "docs/stable-candidate-patrol.md",
       "docs/release-governance.md",
       "docs/release-passport.md",
       "docs/publish-transaction.md",
@@ -827,6 +831,9 @@ function buildSiteBundle() {
         ["buildchain-patrol-daily", "repository-patrol"],
         ["buildchain-patrol-weekly", "repository-patrol"],
         ["buildchain-patrol-monthly", "repository-patrol"],
+        ["stable-candidate-patrol", "repository-patrol"],
+        ["buildchain-stable-candidate-patrol", "repository-patrol"],
+        ["buildchain-stable-candidate-qualification", "repository-patrol"],
         ["patrol-daily", "repository-patrol"],
         ["patrol-weekly", "repository-patrol"],
         ["patrol-monthly", "repository-patrol"],
@@ -835,6 +842,7 @@ function buildSiteBundle() {
         ["release-propagation", "preview"],
         ["candidate-lab", "repository-internal"],
         ["build-surface-fixture", "repository-internal"],
+        ["buildchain-stable-candidate-qualification", "repository-internal"],
         ["self-hosted-runner-smoke", "compatibility-fixture"],
       ]);
       return {

package/scripts/init-repo.mjs

@@ -477,7 +477,7 @@ function readArg(name, fallback = "") {
   return process.argv[index + 1] || "";
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (!process.env.BUILDCHAIN_EMBEDDED_ENTRYPOINT && process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   try {
     const result = initBuildchainRepo({
       cwd: readArg("cwd", process.cwd()),

package/scripts/locked-source-checkout.mjs

@@ -179,7 +179,13 @@ function hasCommit(targetPath, sha, timeoutMs) {
 }
 
 function checkoutFetchedCommit(targetPath, sha, timeoutMs) {
-  git(["checkout", "--force", "--detach", sha], { cwd: targetPath, timeoutMs });
+  // The locked Git tree is also the byte-level source of release evidence.
+  // Override runner-global autocrlf only at checkout time so this also works
+  // when a container workspace uses an external Git metadata pointer.
+  git(["-c", "core.autocrlf=false", "-c", "core.eol=lf", "checkout", "--force", "--detach", sha], {
+    cwd: targetPath,
+    timeoutMs,
+  });
 }
 
 function retryableGitFetchError(error) {
@@ -194,6 +200,7 @@ export function fetchSourceCommit({
   remoteUrl,
   sha,
   fetchRef,
+  sourceTreeSha = "",
   timeoutMs,
   env = {},
   runGit = git,
@@ -216,10 +223,22 @@ export function fetchSourceCommit({
         cwd: targetPath,
         timeoutMs,
         env,
-        stdio: "ignore",
       });
       if (containsCommit(targetPath, sha, timeoutMs)) {
-        return { selector: "ref" };
+        return { selector: "ref", checkoutSha: sha };
+      }
+      if (/^refs\/pull\/\d+\/merge$/.test(fetchRef) && sourceTreeSha) {
+        const fetchedSha = runGit(["rev-parse", "refs/buildchain/source-ref^{commit}"], {
+          cwd: targetPath,
+          timeoutMs,
+        });
+        const fetchedTree = runGit(["rev-parse", "refs/buildchain/source-ref^{tree}"], {
+          cwd: targetPath,
+          timeoutMs,
+        });
+        if (fetchedTree === sourceTreeSha) {
+          return { selector: "ref-tree", checkoutSha: fetchedSha };
+        }
       }
     } catch (error) {
       // A retryable transport failure belongs to the bounded outer retry. Do
@@ -234,12 +253,11 @@ export function fetchSourceCommit({
     cwd: targetPath,
     timeoutMs,
     env,
-    stdio: "ignore",
   });
   if (!containsCommit(targetPath, sha, timeoutMs)) {
     throw new Error(`fetched ${fetchRef || sha}, but ${sha} is not available`);
   }
-  return { selector: "sha" };
+  return { selector: "sha", checkoutSha: sha };
 }
 
 export function runBoundedFetch({ attempts = 1, fetch, onAttempt = () => {}, onRetry = () => {}, shouldRetry = () => true }) {
@@ -266,18 +284,30 @@ function githubRemoteUrl({ repository, serverUrl = "https://github.com" }) {
   return `${base}/${repository}.git`;
 }
 
-function verifyCheckout({ targetPath, sourceSha, sourceTreeSha = "" }) {
+function verifyCheckout({ targetPath, sourceSha, sourceTreeSha = "", fetchRef = "" }) {
   const head = git(["rev-parse", "HEAD"], { cwd: targetPath });
   const tree = git(["rev-parse", "HEAD^{tree}"], { cwd: targetPath });
   const headOk = head === sourceSha;
   const treeOk = !sourceTreeSha || tree === sourceTreeSha;
-  if (!headOk) {
+  const pullMergeTreeEquivalent = !headOk
+    && /^refs\/pull\/\d+\/merge$/.test(fetchRef)
+    && Boolean(sourceTreeSha)
+    && treeOk;
+  if (!headOk && !pullMergeTreeEquivalent) {
     throw new Error(`locked source checkout head mismatch: expected ${sourceSha}, got ${head}`);
   }
   if (!treeOk) {
     throw new Error(`locked source checkout tree mismatch: expected ${sourceTreeSha}, got ${tree}`);
   }
-  return { head, tree, headOk, treeOk };
+  return {
+    head,
+    expectedHead: sourceSha,
+    tree,
+    headOk,
+    treeOk,
+    identityOk: headOk || pullMergeTreeEquivalent,
+    identityMode: pullMergeTreeEquivalent ? "tree-equivalent-pull-merge" : "commit",
+  };
 }
 
 function writeEvidence(filePath, evidence) {
@@ -359,6 +389,7 @@ export function lockedSourceCheckout({
     durationMs: 0,
   };
   let checkoutError;
+  let checkoutSha = sha;
   if (normalizedMode !== "off") {
     try {
       if (renderedReferenceRepository) {
@@ -374,15 +405,17 @@ export function lockedSourceCheckout({
         checkoutFetchedCommit(targetPath, sha, timeoutMs);
       } else if (renderedMirrorUrl) {
         evidence.cache.transport = "mirror-url";
-        fetchSourceCommit({
+        const fetchResult = fetchSourceCommit({
           targetPath,
           remoteName: "buildchain-cache",
           remoteUrl: renderedMirrorUrl,
           sha,
           fetchRef,
+          sourceTreeSha: treeSha,
           timeoutMs,
         });
-        checkoutFetchedCommit(targetPath, sha, timeoutMs);
+        checkoutSha = fetchResult.checkoutSha || sha;
+        checkoutFetchedCommit(targetPath, checkoutSha, timeoutMs);
       } else {
         throw new Error("checkout cache is enabled but no mirror URL or reference repository template was provided");
       }
@@ -416,6 +449,7 @@ export function lockedSourceCheckout({
           remoteUrl,
           sha,
           fetchRef,
+          sourceTreeSha: treeSha,
           timeoutMs: githubTimeoutMs,
           env: githubAuthEnv(githubToken),
         }),
@@ -424,14 +458,20 @@ export function lockedSourceCheckout({
         shouldRetry: retryableGitFetchError,
       });
       evidence.cache.githubFetchAttempts = fetchResult.attempts;
+      checkoutSha = fetchResult.value.checkoutSha || sha;
     } catch (error) {
       evidence.durationMs = Date.now() - startedAt;
       writeEvidence(path.resolve(workspace, diagnosticsPath), evidence);
       throw error;
     }
-    checkoutFetchedCommit(targetPath, sha, timeoutMs);
+    checkoutFetchedCommit(targetPath, checkoutSha, timeoutMs);
   }
-  evidence.verification = verifyCheckout({ targetPath, sourceSha: sha, sourceTreeSha: treeSha });
+  evidence.verification = verifyCheckout({
+    targetPath,
+    sourceSha: sha,
+    sourceTreeSha: treeSha,
+    fetchRef,
+  });
   evidence.durationMs = Date.now() - startedAt;
   writeEvidence(path.resolve(workspace, diagnosticsPath), evidence);
   return evidence;

package/scripts/npm-publish-dry-run.mjs

@@ -155,7 +155,7 @@ function usage() {
 `;
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (!process.env.BUILDCHAIN_EMBEDDED_ENTRYPOINT && process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   try {
     const argv = process.argv.slice(2);
     if (hasFlag(argv, "help") || hasFlag(argv, "h")) {

package/scripts/publication-artifact.mjs

@@ -57,7 +57,7 @@ export function runPublicationArtifactCli(args = process.argv.slice(2)) {
   return result;
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (!process.env.BUILDCHAIN_EMBEDDED_ENTRYPOINT && process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   try {
     runPublicationArtifactCli();
   } catch (error) {

package/scripts/publication-package.mjs

@@ -28,7 +28,7 @@ export function runPublicationPackageCli(args = process.argv.slice(2)) {
   return result;
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (!process.env.BUILDCHAIN_EMBEDDED_ENTRYPOINT && process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   try {
     runPublicationPackageCli();
   } catch (error) {

package/scripts/release-propagation.mjs

@@ -93,6 +93,6 @@ export function runReleasePropagationCli(argv = process.argv.slice(2)) {
   throw new Error(`unsupported release-propagation command: ${mode}`);
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (!process.env.BUILDCHAIN_EMBEDDED_ENTRYPOINT && process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   runReleasePropagationCli();
 }