@kungfu-tech/buildchain 4.0.2-alpha.41 → 4.0.2-alpha.43

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 = "") {
@@ -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) {
@@ -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/scripts/paper-work-fleet-cli.mjs

@@ -418,6 +418,8 @@ function runMigration(options) {
       options.buildchainVersion,
     ),
     buildchainSha: options.buildchainSha,
+    stableBuildchainRoot: readFlag(options.args, "stable-buildchain-root", ""),
+    alphaBuildchainRoot: readFlag(options.args, "alpha-buildchain-root", ""),
   });
   return options.args.some((entry) => ["--write", "--execute"].includes(entry))
     ? writePaperMigration(plan)