@kungfu-tech/buildchain 3.0.3 → 3.0.4-alpha.1

package/packages/core/paper.js

@@ -31,8 +31,34 @@ import {
   sha256Text,
   stableJson,
 } from "./paper-repository.js";
+import {
+  PAPER_AGENT_ENTRY_CONTRACT,
+  collectPaperAgentEntry,
+  paperAgentEntryFiles,
+  resolvePaperBuildchainSha,
+} from "./paper-agent-entry.js";
+import {
+  managedPaperPackageJson,
+  scaffoldMainTex,
+  scaffoldMakefile,
+  scaffoldMap,
+  scaffoldPackageJson,
+  scaffoldReadme,
+} from "./paper-scaffold-content.js";
 
 export { PAPER_PATHS, resolvePaperRepository } from "./paper-repository.js";
+export {
+  PAPER_AGENT_ENTRY_CONTRACT,
+  PAPER_AGENT_ENTRY_SCHEMA_VERSION,
+  PAPER_AGENT_ENTRY_SECTION_END,
+  PAPER_AGENT_ENTRY_SECTION_START,
+  collectPaperAgentEntry,
+  createPaperAgentEntry,
+  mergePaperAgentEntryInstructions,
+  paperAgentEntryFiles,
+  paperAgentEntryInstructions,
+  resolvePaperBuildchainSha,
+} from "./paper-agent-entry.js";
 export {
   PAPER_WORK_START_PLAN_CONTRACT,
   PAPER_WORK_SUBMIT_PLAN_CONTRACT,
@@ -79,9 +105,12 @@ export const PAPER_STATE_ORDER = Object.freeze([
 
 const PAPER_SCAFFOLD_PATHS = Object.freeze([
   PAPER_PATHS.config,
+  PAPER_PATHS.agentEntry,
+  PAPER_PATHS.agentInstructions,
   PAPER_PATHS.contractLock,
   PAPER_PATHS.versionPin,
   PAPER_PATHS.buildWorkflow,
+  PAPER_PATHS.verifyWorkflow,
   PAPER_PATHS.releaseWorkflow,
   PAPER_PATHS.provisioningAuthority,
   "Makefile",
@@ -149,8 +178,11 @@ function buildchainPackageIdentity(buildchainRoot, explicitVersion = "") {
   };
 }
 
-function runtimeGitSha(buildchainRoot, buildchainVersion = "") {
-  const value = gitValue(buildchainRoot, ["rev-parse", "HEAD"]);
+export function resolvePaperRuntimeGitSha(
+  buildchainRoot,
+  buildchainVersion = "",
+) {
+  const value = resolvePaperBuildchainSha(buildchainRoot);
   if (GIT_SHA_PATTERN.test(value)) return value;
   const identity = buildchainPackageIdentity(buildchainRoot, buildchainVersion);
   if (!identity.version) return "";
@@ -227,18 +259,6 @@ function tomlString(value) {
   return JSON.stringify(String(value || ""));
 }
 
-function texEscape(value) {
-  return String(value || "")
-    .replaceAll("\\", "\\textbackslash{}")
-    .replaceAll("&", "\\&")
-    .replaceAll("%", "\\%")
-    .replaceAll("$", "\\$")
-    .replaceAll("#", "\\#")
-    .replaceAll("_", "\\_")
-    .replaceAll("{", "\\{")
-    .replaceAll("}", "\\}");
-}
-
 function joinUrl(base, suffix = "") {
   const normalizedBase = String(base || "")
     .trim()
@@ -334,6 +354,31 @@ jobs:
 `;
 }
 
+function scaffoldVerifyWorkflow(buildchainSha) {
+  return `name: Verify
+
+on:
+  pull_request:
+  push:
+    branches:
+      - "dev/v*/v*"
+      - "alpha/v*/v*"
+      - "release/v*/v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    uses: kungfu-systems/buildchain/.github/workflows/check.yml@${buildchainSha}
+    with:
+      buildchain-ref: ${buildchainSha}
+      require-version-state: true
+      upload-artifacts: true
+`;
+}
+
 function scaffoldReleaseWorkflow(
   buildchainSha,
   { artifactPaths = "_build/main.pdf", releasePassportProductName = "" } = {},
@@ -413,7 +458,10 @@ export function createPaperProvisioningAuthority({
   buildchainSha,
   contractLock,
   buildWorkflow,
+  verifyWorkflow,
   releaseWorkflow,
+  agentEntry,
+  agentInstructions,
   environment = "",
 }) {
   const policy = paperProvisioningPolicy();
@@ -439,6 +487,12 @@ export function createPaperProvisioningAuthority({
         reusablePath: ".github/workflows/publication-artifact.yml",
         reusableRef: buildchainSha,
       },
+      verify: {
+        path: PAPER_PATHS.verifyWorkflow,
+        sourceDigest: sha256Text(verifyWorkflow),
+        reusablePath: ".github/workflows/check.yml",
+        reusableRef: buildchainSha,
+      },
       release: {
         path: PAPER_PATHS.releaseWorkflow,
         sourceDigest: sha256Text(releaseWorkflow),
@@ -446,6 +500,13 @@ export function createPaperProvisioningAuthority({
         reusableRef: buildchainSha,
       },
     },
+    agentEntry: {
+      contract: PAPER_AGENT_ENTRY_CONTRACT,
+      policyPath: PAPER_PATHS.agentEntry,
+      policyDigest: sha256Text(agentEntry),
+      instructionsPath: PAPER_PATHS.agentInstructions,
+      instructionsDigest: sha256Text(agentInstructions),
+    },
     admission: {
       contractLockPath: PAPER_PATHS.contractLock,
       contractLockDigest: sha256Text(contractLock),
@@ -469,150 +530,6 @@ export function createPaperProvisioningAuthority({
   };
 }
 
-function scaffoldMakefile() {
-  const image = `${DEFAULT_TOOLCHAIN_IMAGE}@${DEFAULT_TOOLCHAIN_DIGEST}`;
-  return `.PHONY: check pdf clean
-
-BUILDER_IMAGE := ${image}
-SOURCE_DATE_EPOCH ?= 0
-
-check:
-\t@test -f paper/main.tex
-\t@test -f paper/references.bib
-\t@git diff --check
-
-pdf:
-\t@mkdir -p _build
-\tdocker run --rm --network=none \\
-\t\t-e SOURCE_DATE_EPOCH="$(SOURCE_DATE_EPOCH)" \\
-\t\t-e TZ=UTC -e LANG=C.UTF-8 -e LC_ALL=C.UTF-8 -e HOME=/tmp \\
-\t\t-v "$(CURDIR):/workspace" -w /workspace \\
-\t\t"$(BUILDER_IMAGE)" bash -lc '${DEFAULT_TOOLCHAIN_COMMAND}'
-
-clean:
-\trm -rf _build
-`;
-}
-
-function paperPackageScripts(current = {}) {
-  return {
-    ...current,
-    "buildchain:paper": "buildchain paper",
-    "paper:preflight": "buildchain paper preflight --json",
-    "paper:work:start": "buildchain paper work start",
-    "paper:work:submit": "buildchain paper work submit",
-    "paper:status": "buildchain paper status --json",
-  };
-}
-
-function managedPaperPackageJson(current, buildchainVersion) {
-  if (!/^3\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(buildchainVersion)) {
-    throw new Error(
-      "paper repositories require an exact Buildchain v3 version",
-    );
-  }
-  const packageManager = current.packageManager || "pnpm@11.7.0";
-  if (!packageManager.startsWith("pnpm@")) {
-    throw new Error("paper repositories require a pnpm packageManager");
-  }
-  return {
-    ...current,
-    private: true,
-    scripts: paperPackageScripts(current.scripts),
-    devDependencies: {
-      ...(current.devDependencies || {}),
-      "@kungfu-tech/buildchain": buildchainVersion,
-    },
-    packageManager,
-  };
-}
-
-function scaffoldPackageJson({
-  name,
-  packageName,
-  repository,
-  buildchainVersion,
-}) {
-  return jsonText({
-    ...managedPaperPackageJson(
-      {
-        name: packageName,
-        description: `${name} publication source repository.`,
-        repository: {
-          type: "git",
-          url: `git+https://github.com/${repository}.git`,
-        },
-        license: "Apache-2.0",
-      },
-      buildchainVersion,
-    ),
-  });
-}
-
-function scaffoldReadme({ title, packageName }) {
-  return `# ${title}
-
-This repository is a Buildchain-governed publication artifact source.
-
-## Local workflow
-
-\`\`\`sh
-pnpm paper:preflight
-pnpm paper:work:start -- <topic>
-pnpm paper:work:submit
-make pdf
-\`\`\`
-
-The public package identity is \`${packageName}\`. Buildchain owns reproducible
-artifact generation, sealed publication, npm Trusted Publishing, and recovery;
-this repository owns the paper source and review history.
-
-See [docs/MAP.md](docs/MAP.md) for the repository map.
-`;
-}
-
-function scaffoldMap() {
-  return `# Repository Map
-
-- \`paper/main.tex\`: paper source entrypoint.
-- \`paper/references.bib\`: bibliography source.
-- \`.buildchain/buildchain.toml\`: publication identity, toolchain, package, and lifecycle contract.
-- \`.buildchain/contract-lock.json\`: accepted Buildchain runtime contract.
-- \`.github/workflows/build.yml\`: thin read-only build and reproducibility caller.
-- \`.github/workflows/paper-release.yml\`: thin protected sealed-release caller.
-
-The repository does not own npm transaction logic, publication authority,
-release-state recovery, or site deployment mechanics. Those remain Buildchain,
-npm/GitHub, and downstream site responsibilities respectively.
-`;
-}
-
-function scaffoldMainTex(title) {
-  return `\\documentclass[11pt]{article}
-\\usepackage[T1]{fontenc}
-\\usepackage{lmodern}
-\\usepackage{hyperref}
-
-\\title{${texEscape(title)}}
-\\author{}
-\\date{}
-
-\\begin{document}
-\\maketitle
-
-\\begin{abstract}
-Replace this paragraph with the paper abstract.
-\\end{abstract}
-
-\\section{Introduction}
-Replace this section with the reviewed paper content.
-
-\\bibliographystyle{plain}
-\\bibliography{paper/references}
-\\end{document}
-`;
-}
-
 function scaffoldFiles({
   buildchainRoot,
   buildchainVersion,
@@ -647,6 +564,15 @@ function scaffoldFiles({
     artifactPaths: "_build/main.pdf",
     releasePassportProductName: title,
   });
+  const verifyWorkflow = scaffoldVerifyWorkflow(buildchainSha);
+  const agentEntry = paperAgentEntryFiles({
+    cwd,
+    buildchainVersion,
+    buildchainSha,
+    developmentRef: `dev/v${parsePaperVersion(version).major}/v${
+      parsePaperVersion(version).major
+    }.${parsePaperVersion(version).minor}`,
+  });
   const provisioningAuthority = createPaperProvisioningAuthority({
     repository,
     packageName,
@@ -654,7 +580,10 @@ function scaffoldFiles({
     buildchainSha,
     contractLock: contractLockText,
     buildWorkflow,
+    verifyWorkflow,
     releaseWorkflow,
+    agentEntry: agentEntry.get(PAPER_PATHS.agentEntry),
+    agentInstructions: agentEntry.get(PAPER_PATHS.agentInstructions),
   });
   const licenseText = runtimeLicenseText(buildchainRoot);
   return new Map([
@@ -671,9 +600,18 @@ function scaffoldFiles({
     [PAPER_PATHS.contractLock, contractLockText],
     [PAPER_PATHS.versionPin, `${buildchainVersion}\n`],
     [PAPER_PATHS.buildWorkflow, buildWorkflow],
+    [PAPER_PATHS.verifyWorkflow, verifyWorkflow],
     [PAPER_PATHS.releaseWorkflow, releaseWorkflow],
     [PAPER_PATHS.provisioningAuthority, jsonText(provisioningAuthority)],
-    ["Makefile", scaffoldMakefile()],
+    ...agentEntry,
+    [
+      "Makefile",
+      scaffoldMakefile({
+        image: DEFAULT_TOOLCHAIN_IMAGE,
+        digest: DEFAULT_TOOLCHAIN_DIGEST,
+        command: DEFAULT_TOOLCHAIN_COMMAND,
+      }),
+    ],
     [
       "package.json",
       scaffoldPackageJson({
@@ -727,7 +665,8 @@ export function planPaperScaffold({
     buildchainVersion,
   );
   const runtimeSha =
-    buildchainSha || runtimeGitSha(buildchainRoot, runtimeIdentity.version);
+    buildchainSha ||
+    resolvePaperRuntimeGitSha(buildchainRoot, runtimeIdentity.version);
   if (!GIT_SHA_PATTERN.test(runtimeSha)) {
     throw new Error(
       "paper scaffold cannot resolve the exact Buildchain runtime SHA; pass buildchainSha or use a published Buildchain package with npm gitHead provenance",
@@ -920,7 +859,8 @@ function migrationFiles({
     "paper publish package",
   );
   const runtimeSha =
-    buildchainSha || runtimeGitSha(buildchainRoot, buildchainVersion);
+    buildchainSha ||
+    resolvePaperRuntimeGitSha(buildchainRoot, buildchainVersion);
   if (!GIT_SHA_PATTERN.test(runtimeSha)) {
     throw new Error("paper migration requires an exact Buildchain source SHA");
   }
@@ -957,6 +897,12 @@ function migrationFiles({
     artifactPaths: config.publication.artifactPaths.join(","),
     releasePassportProductName: config.publication.title,
   });
+  const verifyWorkflow = scaffoldVerifyWorkflow(runtimeSha);
+  const agentEntry = paperAgentEntryFiles({
+    cwd,
+    buildchainVersion: runtimeIdentity.version,
+    buildchainSha: runtimeSha,
+  });
   const provisioningAuthority = createPaperProvisioningAuthority({
     repository,
     packageName,
@@ -964,7 +910,10 @@ function migrationFiles({
     buildchainSha: runtimeSha,
     contractLock: contractLockText,
     buildWorkflow,
+    verifyWorkflow,
     releaseWorkflow,
+    agentEntry: agentEntry.get(PAPER_PATHS.agentEntry),
+    agentInstructions: agentEntry.get(PAPER_PATHS.agentInstructions),
   });
   const currentPackage = readJson(path.resolve(cwd, "package.json"));
   if (!currentPackage.exists || currentPackage.error || !currentPackage.value) {
@@ -978,21 +927,12 @@ function migrationFiles({
     [PAPER_PATHS.contractLock, contractLockText],
     [PAPER_PATHS.versionPin, `${runtimeIdentity.version}\n`],
     [PAPER_PATHS.buildWorkflow, buildWorkflow],
+    [PAPER_PATHS.verifyWorkflow, verifyWorkflow],
     [PAPER_PATHS.releaseWorkflow, releaseWorkflow],
     [PAPER_PATHS.provisioningAuthority, jsonText(provisioningAuthority)],
+    ...agentEntry,
     ["package.json", jsonText(packageJson)],
   ]);
-  const verifyWorkflowPath = path.resolve(cwd, PAPER_PATHS.verifyWorkflow);
-  if (fs.existsSync(verifyWorkflowPath)) {
-    const currentVerifyWorkflow = fs.readFileSync(verifyWorkflowPath, "utf8");
-    const migratedVerifyWorkflow = currentVerifyWorkflow.replace(
-      /(uses:\s*kungfu-systems\/buildchain\/\.github\/workflows\/check\.yml@)[^\s]+/g,
-      `$1${runtimeSha}`,
-    );
-    if (migratedVerifyWorkflow !== currentVerifyWorkflow) {
-      files.set(PAPER_PATHS.verifyWorkflow, migratedVerifyWorkflow);
-    }
-  }
   return files;
 }
 
@@ -1687,7 +1627,27 @@ function validatePaperProvisioningAuthority(cwd) {
       "paper release policy permits avoidable bookkeeping pull requests",
     );
   }
-  for (const workflow of [value.workflows?.build, value.workflows?.release]) {
+  if (value.agentEntry?.contract !== PAPER_AGENT_ENTRY_CONTRACT) {
+    errors.push("paper agent-entry authority contract mismatch");
+  }
+  for (const [entryPath, expectedDigest] of [
+    [value.agentEntry?.policyPath, value.agentEntry?.policyDigest],
+    [value.agentEntry?.instructionsPath, value.agentEntry?.instructionsDigest],
+  ]) {
+    if (!entryPath || !SHA256_PATTERN.test(String(expectedDigest || ""))) {
+      errors.push("paper agent-entry authority is incomplete");
+      continue;
+    }
+    const absolute = path.resolve(cwd, entryPath);
+    if (!fs.existsSync(absolute) || sha256File(absolute) !== expectedDigest) {
+      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;
@@ -1707,7 +1667,10 @@ function validatePaperProvisioningAuthority(cwd) {
         `paper workflow reusable source is not exact: ${workflow.path}`,
       );
     }
-    if (!text.includes(`buildchain-ref: ${value.runtime.resolvedSha}`)) {
+    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}`,
       );
@@ -1777,7 +1740,8 @@ function runtimeFacts({
     version: identity.version,
     ref: buildchainRef,
     resolvedSha:
-      buildchainSha || runtimeGitSha(buildchainRoot, identity.version),
+      buildchainSha ||
+      resolvePaperRuntimeGitSha(buildchainRoot, identity.version),
     contract: contractWorld.contract,
     contractDigest: contractWorld.contractDigest,
     compatibilityDigest: contractWorld.compatibilityDigest,
@@ -2094,6 +2058,7 @@ export function collectPaperPreflight({
   buildchainSha = "",
   registry = NPM_REGISTRY,
   offline = false,
+  agentEntryMode = "contract",
 } = {}) {
   const resolvedCwd = path.resolve(cwd);
   const status = collectPaperStatus({ cwd: resolvedCwd });
@@ -2114,6 +2079,11 @@ export function collectPaperPreflight({
     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);
   let lockEvaluation = {
     status: "missing-lock",
@@ -2220,6 +2190,11 @@ export function collectPaperPreflight({
     configResult.loaded?.config?.publication,
   );
   const checks = [
+    ...agentEntry.checks.map((entry) => ({
+      ...entry,
+      blocking: true,
+      scope: "local",
+    })),
     {
       id: "provisioning.authority",
       status: provisioning.valid ? "pass" : "fail",
@@ -2486,6 +2461,7 @@ export function collectPaperPreflight({
       policyDigest: provisioning.value?.policy?.policyDigest || "",
       errors: provisioning.errors,
     },
+    agentEntry,
     repositoryPermissions,
     repositoryActions,
     generatedWriteAuthority,

package/scripts/aggregate-build-summary.mjs

@@ -8,6 +8,51 @@ function readEnv(name, fallback = "") {
   return process.env[name] || fallback;
 }
 
+function parsePlatformIds(name) {
+  const raw = readEnv(name, "").trim();
+  if (!raw) return [];
+  const parsed = JSON.parse(raw);
+  if (!Array.isArray(parsed)) {
+    throw new Error(`${name} must be a JSON array`);
+  }
+  const ids = parsed.map((entry) => String(
+    typeof entry === "string" ? entry : entry?.id || "",
+  ).trim());
+  if (ids.some((id) => !id)) {
+    throw new Error(`${name} entries must declare non-empty platform ids`);
+  }
+  if (new Set(ids).size !== ids.length) {
+    throw new Error(`${name} must not contain duplicate platform ids`);
+  }
+  return ids;
+}
+
+function readManifest(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function selectPlatformManifests({ inputRoot, expectedPlatformIds }) {
+  const candidates = findJsonFiles(inputRoot)
+    .filter((file) => path.basename(file) === "manifest.json")
+    .sort()
+    .map((file) => ({ file, manifest: readManifest(file) }))
+    .filter(({ manifest }) => manifest?.contract === "kungfu-buildchain-artifact");
+  if (expectedPlatformIds.length === 0) return candidates;
+  return expectedPlatformIds.map((platformId) => {
+    const matches = candidates.filter(({ manifest }) => manifest.platform?.id === platformId);
+    if (matches.length !== 1) {
+      throw new Error(
+        `expected exactly one platform manifest for ${platformId}, found ${matches.length} under ${inputRoot}`,
+      );
+    }
+    return matches[0];
+  });
+}
+
 export function aggregateBuildSummaryCli() {
   const inputRoot = path.resolve(readEnv("BUILDCHAIN_SUMMARY_INPUT", ".buildchain/downloaded-manifests"));
   const outputPath = path.resolve(readEnv("BUILDCHAIN_SUMMARY_OUTPUT", ".buildchain/artifacts/build-summary.json"));
@@ -18,10 +63,28 @@ export function aggregateBuildSummaryCli() {
     throw new Error("BUILDCHAIN_ADDITIONAL_PLATFORM_COUNT must be a non-negative integer");
   }
   const expectedManifestCount = expectedPlatformCount + additionalPlatformCount;
-  const manifestFiles = findJsonFiles(inputRoot)
-    .filter((file) => path.basename(file) === "manifest.json")
-    .sort();
-  const manifests = manifestFiles.map((file) => JSON.parse(fs.readFileSync(file, "utf8")));
+  const platformIds = parsePlatformIds("BUILDCHAIN_EXPECTED_PLATFORMS_JSON");
+  const additionalPlatformIds = parsePlatformIds("BUILDCHAIN_ADDITIONAL_PLATFORM_IDS_JSON");
+  if (platformIds.length > 0 && platformIds.length !== expectedPlatformCount) {
+    throw new Error(
+      `BUILDCHAIN_EXPECTED_PLATFORMS_JSON declares ${platformIds.length} platforms, expected ${expectedPlatformCount}`,
+    );
+  }
+  if (additionalPlatformIds.length !== additionalPlatformCount) {
+    throw new Error(
+      `BUILDCHAIN_ADDITIONAL_PLATFORM_IDS_JSON declares ${additionalPlatformIds.length} platforms, expected ${additionalPlatformCount}`,
+    );
+  }
+  const expectedPlatformIds = [...platformIds, ...additionalPlatformIds];
+  if (new Set(expectedPlatformIds).size !== expectedPlatformIds.length) {
+    throw new Error("declared platform ids must be unique across primary and additional platforms");
+  }
+  const selected = selectPlatformManifests({
+    inputRoot,
+    expectedPlatformIds,
+  });
+  const manifestFiles = selected.map(({ file }) => file);
+  const manifests = selected.map(({ manifest }) => manifest);
   if (expectedManifestCount > 0 && manifests.length !== expectedManifestCount) {
     throw new Error(
       `expected ${expectedManifestCount} platform manifests, found ${manifests.length} under ${inputRoot}`,