@kungfu-tech/buildchain 4.0.2-alpha.8 → 4.0.2

package/packages/core/paper-runtime-channels.js

@@ -0,0 +1,348 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  createBuildchainContractLock,
+  createBuildchainContractWorld,
+  finalizeBuildchainContractWorld,
+  readBuildchainContractWorld,
+  sha256Json,
+} from "./buildchain-contract.js";
+import {
+  commandResult,
+  gitValue,
+  readJson,
+  sha256Text,
+  stableJson,
+} from "./paper-repository.js";
+
+export const PAPER_ALPHA_LOCK = ".buildchain/alpha-contract-lock.json";
+
+export function resolvePaperNpmRuntimeSha(cwd, identity) {
+  if (!identity.version) return "";
+  const observed = commandResult(
+    "npm",
+    [
+      "view",
+      `${identity.name}@${identity.version}`,
+      "gitHead",
+      "--json",
+      "--registry=https://registry.npmjs.org",
+    ],
+    { cwd },
+  );
+  if (!observed.ok) return "";
+  let parsed;
+  try {
+    parsed = JSON.parse(observed.stdout || "null");
+  } catch {
+    return "";
+  }
+  const gitHead =
+    typeof parsed === "string" ? parsed : String(parsed?.gitHead || "");
+  return /^[0-9a-f]{40}$/i.test(gitHead)
+    ? gitHead
+    : resolvePaperPublishedTagSha(cwd, identity);
+}
+
+function resolvePaperPublishedTagSha(cwd, identity) {
+  if (
+    identity.name !== "@kungfu-tech/buildchain" ||
+    !/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.test(
+      identity.version,
+    )
+  )
+    return "";
+  const ref = `refs/tags/v${identity.version}`;
+  const observed = commandResult(
+    "git",
+    [
+      "ls-remote",
+      "--exit-code",
+      "https://github.com/kungfu-systems/buildchain.git",
+      ref,
+      `${ref}^{}`,
+    ],
+    { cwd },
+  );
+  if (!observed.ok || !observed.stdout) return "";
+  const refs = new Map();
+  for (const line of observed.stdout.split(/\r?\n/)) {
+    const [sha, name, extra] = line.split(/\s+/);
+    if (
+      !/^[0-9a-f]{40}$/.test(sha) ||
+      ![ref, `${ref}^{}`].includes(name) ||
+      extra ||
+      refs.has(name)
+    )
+      return "";
+    refs.set(name, sha);
+  }
+  if (!refs.has(ref)) return "";
+  return refs.get(`${ref}^{}`) || refs.get(ref);
+}
+
+function fileDigestMatches(cwd, relative, digest) {
+  if (!relative || !/^sha256:[0-9a-f]{64}$/.test(digest || "")) return false;
+  const absolute = path.resolve(cwd, relative);
+  return (
+    fs.existsSync(absolute) &&
+    sha256Text(fs.readFileSync(absolute, "utf8")) === digest
+  );
+}
+
+function workflowErrors(cwd, authority, workflow) {
+  if (!workflow?.path || !workflow?.sourceDigest)
+    return ["paper workflow authority is incomplete"];
+  if (!fileDigestMatches(cwd, workflow.path, workflow.sourceDigest))
+    return [`paper workflow source digest mismatch: ${workflow.path}`];
+  const floating = /^v4(?:-alpha)?$/.test(authority.runtime?.ref || "");
+  const refs = floating
+    ? workflow.reusablePath === ".github/workflows/paper-release-sealed.yml"
+      ? ["v4-alpha", "v4"]
+      : ["v4-alpha"]
+    : [authority.runtime.resolvedSha];
+  const text = fs.readFileSync(path.resolve(cwd, workflow.path), "utf8");
+  const errors = [];
+  if (
+    refs.some(
+      (ref) =>
+        !text.includes(
+          `uses: ${authority.runtime.repository}/${workflow.reusablePath}@${ref}\n`,
+        ),
+    )
+  )
+    errors.push(
+      `paper workflow reusable source is not exact: ${workflow.path}`,
+    );
+  if (
+    (floating || workflow.reusablePath !== ".github/workflows/check.yml") &&
+    refs.some((ref) => !text.includes(`buildchain-ref: ${ref}\n`))
+  )
+    errors.push(`paper workflow runtime input is not exact: ${workflow.path}`);
+  if (
+    floating &&
+    [
+      ...text.matchAll(/uses:\s*kungfu-systems\/buildchain\/[^\s@]+@([^\s]+)/g),
+    ].some((match) => !refs.includes(match[1]))
+  )
+    errors.push(
+      `paper workflow contains an unaccepted Buildchain selector: ${workflow.path}`,
+    );
+  return errors;
+}
+
+function channelLockMatches(cwd, authority, ref, expectedPath) {
+  const channel = authority.admission?.channels?.[ref];
+  const lock = readJson(path.resolve(cwd, expectedPath)).value;
+  const entry = readJson(
+    path.resolve(cwd, ".buildchain/paper/agent-entry.json"),
+  ).value;
+  return (
+    channel?.ref === ref &&
+    channel?.lockPath === expectedPath &&
+    fileDigestMatches(cwd, expectedPath, channel?.lockDigest) &&
+    lock?.buildchain?.ref === ref &&
+    lock?.buildchain?.resolvedSha === channel?.resolvedSha &&
+    lock?.buildchain?.majorLine === "v4" &&
+    entry?.runtime?.channels?.[ref] === channel?.resolvedSha
+  );
+}
+
+export function paperProvisioningWorkflowErrors(cwd, authority) {
+  const errors = [
+    authority.workflows?.build,
+    authority.workflows?.verify,
+    authority.workflows?.release,
+  ].flatMap((workflow) => workflowErrors(cwd, authority, workflow));
+  if (
+    !fileDigestMatches(
+      cwd,
+      authority.admission?.contractLockPath || ".buildchain/contract-lock.json",
+      authority.admission?.contractLockDigest,
+    )
+  )
+    errors.push("paper contract lock bytes differ from provisioning authority");
+  if (/^v4(?:-alpha)?$/.test(authority.runtime?.ref || "")) {
+    for (const [ref, lockPath] of [
+      ["v4", ".buildchain/contract-lock.json"],
+      ["v4-alpha", PAPER_ALPHA_LOCK],
+    ]) {
+      if (!channelLockMatches(cwd, authority, ref, lockPath))
+        errors.push(
+          `paper ${ref} contract lock is not bound to provisioning authority`,
+        );
+    }
+  }
+  return errors;
+}
+
+export function paperRuntimeSourceMatches(runtime, sha, mode, admission) {
+  return (
+    runtime?.sourceSha === sha ||
+    (mode === "ci" &&
+      /^4\./.test(runtime?.version || "") &&
+      ([runtime?.channels?.v4, runtime?.channels?.["v4-alpha"]].includes(sha) ||
+        (admission?.compatible === true &&
+          admission.sha === sha &&
+          /^v4(?:-alpha)?$/.test(admission.ref))))
+  );
+}
+
+export function selectPaperRuntime(runtime, authority) {
+  const channel = Object.values(authority?.admission?.channels || {}).find(
+    (entry) => entry.resolvedSha === runtime.resolvedSha,
+  );
+  const ref =
+    channel?.ref || (runtime.version.includes("-") ? "v4-alpha" : "v4");
+  return authority?.admission?.channels?.[ref] ? { ...runtime, ref } : runtime;
+}
+
+export function paperRuntimeLockPath(cwd, runtime, authority) {
+  return path.resolve(
+    cwd,
+    authority?.admission?.channels?.[runtime.ref]?.lockPath ||
+      ".buildchain/contract-lock.json",
+  );
+}
+
+function channelWorld(root, ref, current) {
+  if (current) return current;
+  const sha = gitValue(root, [
+    "rev-parse",
+    "--verify",
+    `refs/tags/${ref}^{commit}`,
+  ]);
+  const text =
+    sha &&
+    gitValue(root, ["show", `${sha}:dist/site/buildchain-contract.json`]);
+  if (!/^[0-9a-f]{40}$/.test(sha) || !text) {
+    throw new Error(
+      `Paper migration needs the fetched ${ref} tag or an explicit ${ref === "v4" ? "stable" : "alpha"} Buildchain root`,
+    );
+  }
+  const published = JSON.parse(text);
+  const world = Array.isArray(published.compatibilityFacts)
+    ? finalizeBuildchainContractWorld(published)
+    : {
+        ...published,
+        contractDigest: `sha256:${sha256Json({ ...published, contractDigest: undefined, compatibilityDigest: undefined })}`,
+        compatibilityDigest: `sha256:${sha256Json({ schemaVersion: published.schemaVersion, contract: published.contract, majorLine: published.majorLine, surfaces: published.surfaces.map(({ id, kind, breakingDigest }) => ({ id, kind, breakingDigest })) })}`,
+      };
+  if (
+    published.contractDigest !== world.contractDigest ||
+    published.compatibilityDigest !== world.compatibilityDigest
+  ) {
+    throw new Error(`Paper ${ref} contract digest mismatch`);
+  }
+  return {
+    sha,
+    world,
+    acceptedAt: gitValue(root, ["show", "-s", "--format=%cI", sha]),
+  };
+}
+
+function explicitWorld(root, ref) {
+  const sha = gitValue(root, ["rev-parse", "HEAD"]);
+  if (!/^[0-9a-f]{40}$/.test(sha))
+    throw new Error("Paper channel root must have exact Git provenance");
+  if (gitValue(root, ["status", "--porcelain", "--untracked-files=no"]))
+    throw new Error("Paper channel root must have committed runtime bytes");
+  const pkg = readJson(path.join(root, "package.json")).value;
+  if (
+    pkg?.name !== "@kungfu-tech/buildchain" ||
+    !/^4\./.test(pkg?.version || "") ||
+    pkg.version.includes("-") !== (ref === "v4-alpha")
+  )
+    throw new Error(`Paper channel root does not belong to ${ref}`);
+  const contractPath = path.join(root, "dist/site/buildchain-contract.json");
+  return {
+    sha,
+    world: fs.existsSync(contractPath)
+      ? readBuildchainContractWorld(contractPath)
+      : createBuildchainContractWorld({ root }),
+    acceptedAt: gitValue(root, ["show", "-s", "--format=%cI", sha]),
+  };
+}
+
+export function paperV4Channels({
+  cwd,
+  buildchainRoot,
+  buildchainVersion,
+  buildchainSha,
+  contractWorld,
+  acceptedAt,
+  stableBuildchainRoot = "",
+  alphaBuildchainRoot = "",
+}) {
+  const selectedRef = buildchainVersion.includes("-") ? "v4-alpha" : "v4";
+  const current = {
+    sha: buildchainSha,
+    world: contractWorld,
+    acceptedAt,
+  };
+  const channels = {};
+  for (const [ref, lockPath, explicitRoot] of [
+    ["v4", ".buildchain/contract-lock.json", stableBuildchainRoot],
+    ["v4-alpha", PAPER_ALPHA_LOCK, alphaBuildchainRoot],
+  ]) {
+    const resolved = explicitRoot
+      ? explicitWorld(explicitRoot, ref)
+      : channelWorld(buildchainRoot, ref, ref === selectedRef ? current : null);
+    if (resolved.world.majorLine !== "v4")
+      throw new Error(`Paper ${ref} contract must belong to v4`);
+    const existing = readJson(path.join(cwd, lockPath)).value;
+    const lock = createBuildchainContractLock({
+      buildchainRef: ref,
+      resolvedSha: resolved.sha,
+      contractWorld: resolved.world,
+      acceptedAt:
+        existing?.buildchain?.resolvedSha === resolved.sha
+          ? existing.buildchain.acceptedAt
+          : new Date(resolved.acceptedAt).toISOString(),
+    });
+    const content = `${JSON.stringify(lock, null, 2)}\n`;
+    channels[ref] = {
+      ref,
+      resolvedSha: resolved.sha,
+      lockPath,
+      lockDigest: sha256Text(content),
+      content,
+    };
+  }
+  return { selectedRef, channels };
+}
+
+export function bindPaperV4Authority(authority, channelPlan, files) {
+  const { selectedRef, channels } = channelPlan;
+  const entryPath = authority.agentEntry.policyPath;
+  const entry = JSON.parse(files.get(entryPath));
+  entry.runtime.channels = Object.fromEntries(
+    Object.entries(channels).map(([ref, channel]) => [
+      ref,
+      channel.resolvedSha,
+    ]),
+  );
+  const { entryDigest: _entryDigest, ...entryPayload } = entry;
+  entry.entryDigest = sha256Text(stableJson(entryPayload));
+  files.set(entryPath, `${JSON.stringify(entry, null, 2)}\n`);
+  authority.agentEntry.policyDigest = sha256Text(files.get(entryPath));
+  authority.runtime.ref = selectedRef;
+  authority.admission.acceptedRef = selectedRef;
+  authority.admission.contractLockPath = channels[selectedRef].lockPath;
+  authority.admission.contractLockDigest = channels[selectedRef].lockDigest;
+  authority.admission.channels = Object.fromEntries(
+    Object.entries(channels).map(([ref, { content: _content, ...channel }]) => [
+      ref,
+      channel,
+    ]),
+  );
+  for (const [role, workflow] of Object.entries(authority.workflows)) {
+    workflow.reusableRef = role === "release" ? "v4" : "v4-alpha";
+    workflow.reusableRefs =
+      role === "release" ? ["v4", "v4-alpha"] : ["v4-alpha"];
+    workflow.sourceDigest = sha256Text(files.get(workflow.path));
+  }
+  const { authorityDigest: _authorityDigest, ...payload } = authority;
+  authority.authorityDigest = sha256Text(stableJson(payload));
+  return authority;
+}

package/packages/core/paper-scaffold-content.js

@@ -10,6 +10,12 @@ function jsonText(value) {
   return `${JSON.stringify(value, null, 2)}\n`;
 }
 
+export function paperDependencyIgnore(current = "") {
+  return /^(?:\/)?node_modules\/?\s*$/m.test(current)
+    ? current
+    : `${current}${current.endsWith("\n") || !current ? "" : "\n"}node_modules/\n`;
+}
+
 function texEscape(value) {
   return String(value || "")
     .replaceAll("\\", "\\textbackslash{}")
@@ -380,6 +386,8 @@ function planPaperMigration(
     buildchainRoot = process.cwd(),
     buildchainVersion = "",
     buildchainSha = "",
+    stableBuildchainRoot = "",
+    alphaBuildchainRoot = "",
   } = {},
 ) {
   const resolvedCwd = path.resolve(cwd);
@@ -407,6 +415,8 @@ function planPaperMigration(
       buildchainRoot,
       buildchainVersion,
       buildchainSha,
+      stableBuildchainRoot,
+      alphaBuildchainRoot,
     }),
   ].map(([relativePath, content]) => {
     const target = path.resolve(resolvedCwd, relativePath);

package/packages/core/paper.js

@@ -1,4 +1,5 @@
 import crypto from "node:crypto";
+import { bindPaperV4Authority, paperV4Channels, selectPaperRuntime, paperRuntimeLockPath, paperProvisioningWorkflowErrors, resolvePaperNpmRuntimeSha } from "./paper-runtime-channels.js";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -40,6 +41,7 @@ import {
 import {
   createPaperScaffoldOperations,
   managedPaperPackageJson,
+  paperDependencyIgnore,
   scaffoldMainTex,
   scaffoldMakefile,
   scaffoldMap,
@@ -255,23 +257,7 @@ export function resolvePaperRuntimeGitSha(
   const value = resolvePaperBuildchainSha(buildchainRoot);
   if (GIT_SHA_PATTERN.test(value)) return value;
   const identity = buildchainPackageIdentity(buildchainRoot, buildchainVersion);
-  if (!identity.version) return "";
-  const observed = commandResult(
-    "npm",
-    [
-      "view",
-      `${identity.name}@${identity.version}`,
-      "gitHead",
-      "--json",
-      `--registry=${NPM_REGISTRY}`,
-    ],
-    { cwd: buildchainRoot },
-  );
-  if (!observed.ok) return "";
-  const parsed = safeParseJson(observed.stdout);
-  const gitHead =
-    typeof parsed === "string" ? parsed : String(parsed?.gitHead || "");
-  return GIT_SHA_PATTERN.test(gitHead) ? gitHead : "";
+  return resolvePaperNpmRuntimeSha(buildchainRoot, identity);
 }
 
 function runtimeAcceptedAt(buildchainRoot, sha, buildchainVersion = "") {
@@ -424,7 +410,7 @@ jobs:
 `;
 }
 
-function scaffoldVerifyWorkflow(buildchainSha) {
+function scaffoldVerifyWorkflow(buildchainSha, buildchainVersion = "") {
   return `${nextDevelopmentWorkflowHeader()}name: Verify
 
 on:
@@ -437,7 +423,7 @@ on:
   workflow_dispatch:
 
 permissions:
-  contents: read
+${buildchainVersion.startsWith("4.") ? "  actions: read\n  contents: read\n  pull-requests: read" : "  contents: read"}
 
 jobs:
   check:
@@ -635,7 +621,7 @@ function scaffoldFiles({
     artifactPaths: "_build/main.pdf",
     releasePassportProductName: title,
   });
-  const verifyWorkflow = scaffoldVerifyWorkflow(buildchainSha);
+  const verifyWorkflow = scaffoldVerifyWorkflow(buildchainSha, buildchainVersion);
   const agentEntry = paperAgentEntryFiles({
     cwd,
     buildchainVersion,
@@ -700,7 +686,7 @@ function scaffoldFiles({
     ["LICENSE", licenseText],
     [
       ".gitignore",
-      "_build/\n.buildchain/publication/\n.buildchain/release-state/\n.buildchain/release-evidence/\n.buildchain/paper/npm-bootstrap.json\n.buildchain/paper/npm-trust.json\n",
+      "node_modules/\n_build/\n.buildchain/publication/\n.buildchain/release-state/\n.buildchain/release-evidence/\n.buildchain/paper/npm-bootstrap.json\n.buildchain/paper/npm-trust.json\n",
     ],
   ]);
 }
@@ -710,6 +696,8 @@ function migrationFiles({
   buildchainRoot,
   buildchainVersion,
   buildchainSha,
+  stableBuildchainRoot,
+  alphaBuildchainRoot,
 }) {
   const configResult = paperConfig(cwd);
   if (configResult.error) {
@@ -768,7 +756,7 @@ function migrationFiles({
     artifactPaths: config.publication.artifactPaths.join(","),
     releasePassportProductName: config.publication.title,
   });
-  const verifyWorkflow = scaffoldVerifyWorkflow(runtimeSha);
+  const verifyWorkflow = scaffoldVerifyWorkflow(runtimeSha, runtimeIdentity.version);
   const agentEntry = paperAgentEntryFiles({
     cwd,
     buildchainVersion: runtimeIdentity.version,
@@ -817,7 +805,26 @@ function migrationFiles({
     [PAPER_PATHS.provisioningAuthority, jsonText(provisioningAuthority)],
     ...agentEntry,
     ["package.json", jsonText(packageJson)],
+    [".gitignore", paperDependencyIgnore(fs.existsSync(path.join(cwd, ".gitignore")) ? fs.readFileSync(path.join(cwd, ".gitignore"), "utf8") : "")],
   ]);
+  if (runtimeIdentity.version.startsWith("4.")) {
+    const channelPlan = paperV4Channels({
+      cwd, buildchainRoot, buildchainVersion: runtimeIdentity.version,
+      buildchainSha: runtimeSha, contractWorld: runtimeContractWorld(buildchainRoot),
+      acceptedAt: contractLock.buildchain.acceptedAt,
+      stableBuildchainRoot, alphaBuildchainRoot,
+    });
+    for (const channel of Object.values(channelPlan.channels)) files.set(channel.lockPath, channel.content);
+    for (const workflowPath of [PAPER_PATHS.buildWorkflow, PAPER_PATHS.verifyWorkflow]) {
+      files.set(workflowPath, files.get(workflowPath).replaceAll(runtimeSha, "v4-alpha").replaceAll(".buildchain/contract-lock.json", ".buildchain/alpha-contract-lock.json"));
+    }
+    const releaseStart = releaseWorkflow.indexOf("  paper-release:\n");
+    const releaseJob = releaseWorkflow.slice(releaseStart);
+    const alphaJob = releaseJob.replace("  paper-release:\n", "  paper-release-alpha:\n    if: ${{ startsWith(github.ref_name, 'alpha/') }}\n").replaceAll(runtimeSha, "v4-alpha").replaceAll(".buildchain/contract-lock.json", ".buildchain/alpha-contract-lock.json");
+    const stableJob = releaseJob.replace("  paper-release:\n", "  paper-release:\n    if: ${{ startsWith(github.ref_name, 'release/') }}\n").replaceAll(runtimeSha, "v4");
+    files.set(PAPER_PATHS.releaseWorkflow, `${releaseWorkflow.slice(0, releaseStart)}${alphaJob}\n${stableJob}`);
+    files.set(PAPER_PATHS.provisioningAuthority, jsonText(bindPaperV4Authority(provisioningAuthority, channelPlan, files)));
+  }
   return files;
 }
 
@@ -1326,6 +1333,7 @@ function validatePaperProvisioningAuthority(cwd) {
   }
   const value = source.value;
   const errors = [];
+  const floating = /^v4(?:-alpha)?$/.test(value.runtime?.ref || "");
   if (value.contract !== PAPER_PROVISIONING_CONTRACT) {
     errors.push("paper provisioning authority contract mismatch");
   }
@@ -1338,8 +1346,8 @@ function validatePaperProvisioningAuthority(cwd) {
   }
   if (
     !GIT_SHA_PATTERN.test(String(value.runtime?.resolvedSha || "")) ||
-    value.runtime?.ref !== value.runtime?.resolvedSha ||
-    value.admission?.acceptedRef !== value.runtime?.resolvedSha ||
+    (!floating && value.runtime?.ref !== value.runtime?.resolvedSha) ||
+    value.admission?.acceptedRef !== value.runtime?.ref ||
     value.admission?.acceptedSha !== value.runtime?.resolvedSha
   ) {
     errors.push("paper runtime and admission are not bound to one exact SHA");
@@ -1397,49 +1405,7 @@ function validatePaperProvisioningAuthority(cwd) {
       errors.push(`paper agent-entry source digest mismatch: ${entryPath}`);
     }
   }
-  for (const workflow of [
-    value.workflows?.build,
-    value.workflows?.verify,
-    value.workflows?.release,
-  ]) {
-    if (!workflow?.path || !workflow?.sourceDigest) {
-      errors.push("paper workflow authority is incomplete");
-      continue;
-    }
-    const absolute = path.resolve(cwd, workflow.path);
-    if (
-      !fs.existsSync(absolute) ||
-      sha256File(absolute) !== workflow.sourceDigest
-    ) {
-      errors.push(`paper workflow source digest mismatch: ${workflow.path}`);
-      continue;
-    }
-    const text = fs.readFileSync(absolute, "utf8");
-    const expectedUse = `${value.runtime.repository}/${workflow.reusablePath}@${value.runtime.resolvedSha}`;
-    if (!text.includes(`uses: ${expectedUse}`)) {
-      errors.push(
-        `paper workflow reusable source is not exact: ${workflow.path}`,
-      );
-    }
-    if (
-      workflow.reusablePath !== ".github/workflows/check.yml" &&
-      !text.includes(`buildchain-ref: ${value.runtime.resolvedSha}`)
-    ) {
-      errors.push(
-        `paper workflow runtime input is not exact: ${workflow.path}`,
-      );
-    }
-  }
-  const lockPath = path.resolve(
-    cwd,
-    value.admission?.contractLockPath || PAPER_PATHS.contractLock,
-  );
-  if (
-    !fs.existsSync(lockPath) ||
-    sha256File(lockPath) !== value.admission?.contractLockDigest
-  ) {
-    errors.push("paper contract lock bytes differ from provisioning authority");
-  }
+  errors.push(...paperProvisioningWorkflowErrors(cwd, value));
   return {
     exists: true,
     valid: errors.length === 0,
@@ -2077,12 +2043,11 @@ export function collectPaperPreflight({
   } catch (error) {
     validationError = error.message;
   }
-  const runtime = runtimeFacts({
+  const runtime = selectPaperRuntime(runtimeFacts({
     buildchainRoot, buildchainVersion,
     buildchainRef: provisioning.value?.runtime?.ref || buildchainRef, buildchainSha,
-  });
-  const agentEntry = collectPaperAgentEntry({ cwd: resolvedCwd, buildchainSha: runtime.resolvedSha, mode: agentEntryMode });
-  const lockPath = path.resolve(resolvedCwd, PAPER_PATHS.contractLock);
+  }), provisioning.value);
+  const lockPath = paperRuntimeLockPath(resolvedCwd, runtime, provisioning.value);
   let lockEvaluation = {
     status: "missing-lock",
     compatible: false,
@@ -2109,6 +2074,7 @@ export function collectPaperPreflight({
       reasons: [error.message],
     };
   }
+  const agentEntry = collectPaperAgentEntry({ cwd: resolvedCwd, buildchainSha: runtime.resolvedSha, mode: agentEntryMode, runtimeAdmission: { compatible: lockEvaluation.compatible, sha: runtime.resolvedSha, ref: runtime.ref } });
   const source = {
     repositoryRoot: gitValue(resolvedCwd, ["rev-parse", "--show-toplevel"]),
     head: gitValue(resolvedCwd, ["rev-parse", "HEAD"]),

package/packages/core/release-line-dry-run.js

@@ -201,7 +201,7 @@ function explainReleaseLineDryRun({
     );
     plan.branchUpdates.push(
       { ref: targetRef, action: "would move to alpha version-state commit" },
-      { ref: `dev/v${rule.major}/v${rule.major}.${rule.minor}`, action: "would align dev with the published alpha state" },
+      { ref: `dev/v${rule.major}/v${rule.major}.${rule.minor}`, action: rule.major === 4 ? "would prepare the next alpha version on dev through a separate protected PR after publication" : "would align dev with the published alpha state" },
     );
     plan.versionState.targetVersions = [exactAlpha.replace(/^next v?/, "").replace(/^v/, "")];
     plan.notes.push("Alpha promotion opens or advances the test channel; it does not move production refs.");

package/packages/core/release-passport-contract.js

@@ -405,7 +405,7 @@ export function prepareReleasePassportKfdSections({ kfd1, kfd2Claims, kfd3, kfdA
   };
 }
 
-export function collectKfdAdopterReleaseEvidence({ manifest, gateResults = [], comparisonMatrix, sourceSha = "", checkedAt } = {}) {
+export function collectKfdAdopterReleaseEvidence({ manifest, gateResults = [], comparisonMatrix, expectedAdopterId = "kungfu-systems/buildchain", expectedSourceRepository = "", sourceSha = "", checkedAt } = {}) {
   if (!manifest) {
     if (comparisonMatrix || gateResults.length > 0) {
       throw new Error("KFD support and product-gate inputs require --kfd-adopter-manifest-json; --kfd-support-matrix-json is comparison-only");
@@ -414,7 +414,7 @@ export function collectKfdAdopterReleaseEvidence({ manifest, gateResults = [], c
   }
   const manifestGate = createKfdAdopterManifestGate({
     manifest, packageArtifactRoot: installedKfdPackageArtifactRoot(), gateResults,
-    expectedSourceSha: sourceSha, checkedAt,
+    expectedAdopterId, expectedSourceRepository, expectedSourceSha: sourceSha, checkedAt,
   });
   const legacyProjection = createKfdLegacySupportMatrixProjection({ manifest, manifestGate });
   if (comparisonMatrix) {
@@ -425,18 +425,18 @@ export function collectKfdAdopterReleaseEvidence({ manifest, gateResults = [], c
   }
   return {
     manifest, manifestGate, legacyProjection,
-    binding: createKfdAdopterReleaseBinding({ manifest, manifestGate, legacyProjection, expectedSourceSha: sourceSha }),
+    binding: createKfdAdopterReleaseBinding({ manifest, manifestGate, legacyProjection, expectedAdopterId, expectedSourceRepository, expectedSourceSha: sourceSha }),
   };
 }
 
-export function validateKfdAdopterReleaseEvidence({ binding, artifactBinding, manifest, manifestGate, legacyProjection, passportLegacyProjection, expectedSourceSha = "" } = {}) {
+export function validateKfdAdopterReleaseEvidence({ binding, artifactBinding, manifest, manifestGate, legacyProjection, passportLegacyProjection, expectedAdopterId = "kungfu-systems/buildchain", expectedSourceRepository = "", expectedSourceSha = "" } = {}) {
   if (!binding) {
     return passportLegacyProjection
       ? [{ code: "kfdSupport.authority", message: "legacy KFD support projection requires the standard adopter manifest binding" }]
       : [];
   }
   const issues = validateKfdAdopterReleaseBinding(binding, {
-    manifest, manifestGate, legacyProjection, expectedSourceSha,
+    manifest, manifestGate, legacyProjection, expectedAdopterId, expectedSourceRepository, expectedSourceSha,
   }).issues.map((entry) => ({ code: `kfdAdopter.${entry.path || entry.code}`, message: entry.message, details: entry }));
   if (!artifactBinding || passportStableJson(artifactBinding) !== passportStableJson(binding)) {
     issues.push({ code: "kfdAdopter.artifactEvidence", message: "release passport and artifact evidence must bind the same exact KFD adopter closure" });

package/packages/core/release-passport.js

@@ -1431,7 +1431,7 @@ export function createReleasePassport(options = {}) {
   };
 }
 
-function collectKfdAdopterReleaseInputs({ cwd, manifestJson, supportMatrixJson, productGateJsons, sourceSha, checkedAt }) {
+function collectKfdAdopterReleaseInputs({ cwd, manifestJson, supportMatrixJson, productGateJsons, repository, sourceSha, checkedAt }) {
   const manifestMeta = parseJsonInputWithMeta(manifestJson, undefined, { cwd, label: "kfdAdopterManifestJson" });
   const supportMatrixMeta = parseJsonInputWithMeta(supportMatrixJson, undefined, { cwd, label: "kfdSupportMatrixJson" });
   const productGateMetas = (productGateJsons || [])
@@ -1442,7 +1442,7 @@ function collectKfdAdopterReleaseInputs({ cwd, manifestJson, supportMatrixJson,
     manifest: manifestMeta.value,
     gateResults: productGateMetas.map((meta) => meta.value),
     comparisonMatrix: supportMatrixMeta.value,
-    sourceSha,
+    expectedAdopterId: repository || "kungfu-systems/buildchain", expectedSourceRepository: repository, sourceSha,
     checkedAt,
   });
 }
@@ -1620,7 +1620,7 @@ export function collectGitHubReleasePassport({
   const productMechanism = defaultProductMechanism({ repository, productName });
   const kfdAdopterEvidence = collectKfdAdopterReleaseInputs({
     cwd, manifestJson: kfdAdopterManifestJson, supportMatrixJson: kfdSupportMatrixJson,
-    productGateJsons: kfdProductGateJsons, sourceSha, checkedAt: resolvedCheckedAt,
+    productGateJsons: kfdProductGateJsons, repository, sourceSha, checkedAt: resolvedCheckedAt,
   });
   const {
     manifest: kfdAdopterManifest,
@@ -2060,7 +2060,8 @@ function validateReleaseEvidenceContracts({
     manifestGate: kfdAdopterManifestGate,
     legacyProjection: kfdSupportEvidence,
     passportLegacyProjection: passport?.kfdSupport,
-    expectedSourceSha: optionalString(passport?.release?.sourceSha),
+    expectedAdopterId: optionalString(passport?.product?.repository) || "kungfu-systems/buildchain",
+    expectedSourceRepository: optionalString(passport?.product?.repository), expectedSourceSha: optionalString(passport?.release?.sourceSha),
   })) {
     issues.push(issue("error", entry.code, entry.message, entry.details));
   }