@kungfu-tech/buildchain 2.9.0 → 2.9.1

package/packages/core/public-surface-audit.js

@@ -0,0 +1,298 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+export const BUILDCHAIN_PUBLIC_SURFACE_AUDIT_CONTRACT = "kungfu-buildchain-public-surface-reverse-audit";
+
+function readText(root, relPath) {
+  return fs.readFileSync(path.join(root, relPath), "utf8");
+}
+
+function readJson(root, relPath, fallback = undefined) {
+  const filePath = path.join(root, relPath);
+  if (!fs.existsSync(filePath)) return fallback;
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function uniqueSorted(values) {
+  return [...new Set(values.filter(Boolean))].sort();
+}
+
+function listFiles(root, dir, predicate = () => true) {
+  const base = path.join(root, dir);
+  if (!fs.existsSync(base)) return [];
+  return fs.readdirSync(base, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && predicate(entry.name))
+    .map((entry) => `${dir}/${entry.name}`)
+    .sort();
+}
+
+function listDirectories(root, dir) {
+  const base = path.join(root, dir);
+  if (!fs.existsSync(base)) return [];
+  return fs.readdirSync(base, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => `${dir}/${entry.name}`)
+    .sort();
+}
+
+function commandId(first = "", second = "") {
+  const head = String(first || "").trim();
+  const sub = String(second || "").trim();
+  if (!head) return "";
+  if (["-h", "--help", "help"].includes(head)) return "help";
+  if (["-v", "--version", "version"].includes(head)) return "version";
+  if (head === "release" && ["--dry-run", "dry-run", "explain"].includes(sub)) return "release-dry-run";
+  if (head === "release" && sub === "line") return "release-line-open";
+  if (head === "release") return "release-transaction";
+  if (head === "transaction") return "transaction-inspect";
+  if (head === "collect" && sub) return `collect-${sub}`;
+  if (head === "verify" && sub) return `verify-${sub}`;
+  if (head === "explain" && sub) return `explain-${sub}`;
+  if (head === "inspect" && sub) return `inspect-${sub}`;
+  if (head === "npm" && sub) return `npm-${sub}`;
+  if (head === "lifecycle" && sub) return "lifecycle";
+  if (head === "log" && sub) return "logging";
+  if (head === "diagnostics" && sub) return `diagnostics-${sub}`;
+  if (head === "facts" && sub) return "build-facts";
+  if (head === "sample" && sub) return `sample-${sub}`;
+  if (head === "badges" && sub) return `badges-${sub}`;
+  if (head === "homebrew" && sub) return `homebrew-${sub}`;
+  if (head === "release-propagation") return "release-propagation";
+  if (head === "publish-source") return "publish-source";
+  if (head === "build-contract") return "build-contract";
+  if (head === "infra-contract") return "infra-contract";
+  if (head === "web-surface") return "web-surface";
+  return head;
+}
+
+export function enumerateCliCommandsFromBin({ root = process.cwd(), binPath = "bin/buildchain.mjs" } = {}) {
+  const source = readText(root, binPath);
+  const usageMatch = source.match(/return `Usage:\n([\s\S]*?)`;\n}/);
+  const usage = usageMatch?.[1] || "";
+  const usageCommands = [];
+  for (const line of usage.split(/\r?\n/)) {
+    const match = line.trim().match(/^buildchain\s+([^\s]+)(?:\s+([^\s]+))?/);
+    if (!match) continue;
+    usageCommands.push({
+      id: commandId(match[1], match[2]),
+      usage: line.trim().replace(/\s+/g, " "),
+    });
+  }
+  const dispatchCommands = [...source.matchAll(/if\s*\(\s*command\s*===\s*"([^"]+)"/g)]
+    .map((match) => commandId(match[1]));
+  return uniqueSorted([
+    ...usageCommands.map((entry) => entry.id),
+    ...dispatchCommands,
+  ]).map((id) => ({
+    id,
+    source: "bin/buildchain.mjs",
+    usage: usageCommands.find((entry) => entry.id === id)?.usage || `buildchain ${id}`,
+  }));
+}
+
+function parseYamlTopLevelInputs(text) {
+  const lines = text.split(/\r?\n/);
+  const inputs = [];
+  let inInputs = false;
+  let indent = 0;
+  for (const line of lines) {
+    const match = line.match(/^(\s*)inputs:\s*$/);
+    if (match) {
+      inInputs = true;
+      indent = match[1].length;
+      continue;
+    }
+    if (!inInputs) continue;
+    const currentIndent = line.match(/^(\s*)/)?.[1].length || 0;
+    if (line.trim() && currentIndent <= indent) {
+      inInputs = false;
+      continue;
+    }
+    const inputMatch = line.match(new RegExp(`^\\s{${indent + 2}}([A-Za-z0-9_-]+):\\s*$`));
+    if (inputMatch) inputs.push(inputMatch[1]);
+  }
+  return uniqueSorted(inputs);
+}
+
+export function enumerateWorkflowInputs({ root = process.cwd() } = {}) {
+  return listFiles(root, ".github/workflows", (name) => /\.ya?ml$/.test(name)).map((relPath) => {
+    const inputs = parseYamlTopLevelInputs(readText(root, relPath));
+    return {
+      id: relPath.replace(/^\.github\/workflows\//, "").replace(/\.ya?ml$/, ""),
+      path: relPath,
+      inputs,
+      inputCount: inputs.length,
+    };
+  });
+}
+
+export function enumerateActionInputs({ root = process.cwd() } = {}) {
+  return listDirectories(root, "actions").map((dir) => {
+    const relPath = `${dir}/action.yml`;
+    const inputs = fs.existsSync(path.join(root, relPath))
+      ? parseYamlTopLevelInputs(readText(root, relPath))
+      : [];
+    return {
+      id: dir.replace(/^actions\//, ""),
+      path: relPath,
+      inputs,
+      inputCount: inputs.length,
+    };
+  });
+}
+
+export function enumerateSitePages({ root = process.cwd() } = {}) {
+  const pageRegistry = readJson(root, "dist/site/page-registry.json", {});
+  return (Array.isArray(pageRegistry?.pages) ? pageRegistry.pages : []).map((page) => ({
+    id: page.id || page.path,
+    path: page.path,
+    category: page.category || "",
+  })).sort((a, b) => String(a.id).localeCompare(String(b.id)));
+}
+
+export function enumerateDocCommandRefs({ root = process.cwd() } = {}) {
+  const knownCommandIds = new Set(enumerateCliCommandsFromBin({ root }).map((entry) => entry.id));
+  const docs = [
+    "README.md",
+    ...listFiles(root, "docs", (name) => name.endsWith(".md")),
+    ...listDirectories(root, "actions").map((dir) => `${dir}/README.md`).filter((relPath) => fs.existsSync(path.join(root, relPath))),
+  ];
+  const refs = [];
+  for (const relPath of docs) {
+    const text = readText(root, relPath);
+    const codeSegments = [];
+    for (const match of text.matchAll(/```[\w-]*\n([\s\S]*?)```/g)) {
+      codeSegments.push({ kind: "block", text: match[1] });
+    }
+    for (const match of text.matchAll(/`([^`\n]*\bbuildchain\b[^`\n]*)`/g)) {
+      codeSegments.push({ kind: "inline", text: match[1] });
+    }
+    for (const segment of codeSegments) {
+      const commandText = segment.kind === "block"
+        ? segment.text.split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => /^(?:[$>]\s*)?(?:npx\s+(?:@kungfu-tech\/buildchain|buildchain)\s+|node\s+bin\/buildchain\.mjs\s+|buildchain\s+)/.test(line))
+            .join("\n")
+        : segment.text;
+      for (const match of commandText.matchAll(/(?:^|[\s$>])(?:npx\s+(?:@kungfu-tech\/buildchain|buildchain)\s+|node\s+bin\/buildchain\.mjs\s+|buildchain\s+)([a-z0-9][a-z0-9-]*|--help|--version|-h|-v)(?:\s+([a-z0-9][a-z0-9-]*|--[a-z0-9-]+))?/gm)) {
+        const id = commandId(match[1], match[2]);
+        if (segment.kind === "inline" && !knownCommandIds.has(id)) {
+          continue;
+        }
+        refs.push({
+          id,
+          path: relPath,
+          command: `buildchain ${match[1]}${match[2] ? ` ${match[2]}` : ""}`,
+        });
+      }
+    }
+  }
+  return refs
+    .filter((entry) => entry.id)
+    .sort((a, b) => `${a.id}:${a.path}`.localeCompare(`${b.id}:${b.path}`));
+}
+
+function registryIds(entries) {
+  return new Set((entries || []).map((entry) => entry.id).filter(Boolean));
+}
+
+export function collectPublicSurfaceReverseAudit({
+  root = process.cwd(),
+  cliRegistry: suppliedCliRegistry = undefined,
+  workflowRegistry: suppliedWorkflowRegistry = undefined,
+  pageRegistry: suppliedPageRegistry = undefined,
+} = {}) {
+  const cliCommands = enumerateCliCommandsFromBin({ root });
+  const workflowInputs = enumerateWorkflowInputs({ root });
+  const actionInputs = enumerateActionInputs({ root });
+  const sitePages = suppliedPageRegistry
+    ? (Array.isArray(suppliedPageRegistry?.pages) ? suppliedPageRegistry.pages : []).map((page) => ({
+        id: page.id || page.path,
+        path: page.path,
+        category: page.category || "",
+      })).sort((a, b) => String(a.id).localeCompare(String(b.id)))
+    : enumerateSitePages({ root });
+  const docCommandRefs = enumerateDocCommandRefs({ root });
+  const cliRegistry = suppliedCliRegistry || readJson(root, "dist/site/cli-registry.json", { commands: [] });
+  const workflowRegistry = suppliedWorkflowRegistry || readJson(root, "dist/site/workflow-registry.json", { workflows: [], actions: [] });
+  const pageRegistry = suppliedPageRegistry || readJson(root, "dist/site/page-registry.json", { pages: [] });
+  const declaredCli = registryIds(cliRegistry.commands);
+  const declaredWorkflows = registryIds(workflowRegistry.workflows);
+  const declaredActions = registryIds(workflowRegistry.actions);
+  const declaredPages = registryIds(pageRegistry.pages);
+  const missingCliRegistry = cliCommands.filter((entry) => !declaredCli.has(entry.id));
+  const missingWorkflowRegistry = workflowInputs.filter((entry) => !declaredWorkflows.has(entry.id) && entry.inputCount > 0);
+  const missingActionRegistry = actionInputs.filter((entry) => !declaredActions.has(entry.id) && entry.inputCount > 0);
+  const missingPageRegistry = sitePages.filter((entry) => entry.id && !declaredPages.has(entry.id));
+  const unknownDocCommandRefs = docCommandRefs.filter((entry) => !declaredCli.has(entry.id));
+  const failures = [
+    ...missingCliRegistry.map((entry) => `cli:${entry.id}`),
+    ...missingWorkflowRegistry.map((entry) => `workflow:${entry.id}`),
+    ...missingActionRegistry.map((entry) => `action:${entry.id}`),
+    ...missingPageRegistry.map((entry) => `site:${entry.id}`),
+    ...unknownDocCommandRefs.map((entry) => `doc-command:${entry.id}:${entry.path}`),
+  ];
+  const result = {
+    schemaVersion: 1,
+    contract: BUILDCHAIN_PUBLIC_SURFACE_AUDIT_CONTRACT,
+    status: failures.length === 0 ? "passed" : "failed",
+    summary: {
+      cliCommandCount: cliCommands.length,
+      workflowCount: workflowInputs.length,
+      actionCount: actionInputs.length,
+      sitePageCount: sitePages.length,
+      docCommandRefCount: docCommandRefs.length,
+      failureCount: failures.length,
+    },
+    enumerated: {
+      cliCommands,
+      workflowInputs,
+      actionInputs,
+      sitePages,
+      docCommandRefs,
+    },
+    declared: {
+      cliRegistryPath: "dist/site/cli-registry.json",
+      workflowRegistryPath: "dist/site/workflow-registry.json",
+      pageRegistryPath: "dist/site/page-registry.json",
+      cliRegistryDigest: fs.existsSync(path.join(root, "dist/site/cli-registry.json")) ? sha256(readText(root, "dist/site/cli-registry.json")) : "",
+      workflowRegistryDigest: fs.existsSync(path.join(root, "dist/site/workflow-registry.json")) ? sha256(readText(root, "dist/site/workflow-registry.json")) : "",
+      pageRegistryDigest: fs.existsSync(path.join(root, "dist/site/page-registry.json")) ? sha256(readText(root, "dist/site/page-registry.json")) : "",
+    },
+    comparison: {
+      missingCliRegistry,
+      missingWorkflowRegistry,
+      missingActionRegistry,
+      missingPageRegistry,
+      unknownDocCommandRefs,
+    },
+    auditBoundary: {
+      mode: "closed-world-enumerable",
+      scope: "Buildchain CLI usage/dispatch, reusable workflow inputs, action inputs, site pages, and documentation command references",
+      residualRisk: [
+        "Shell commands delegated through helper scripts are only counted when exposed through bin/buildchain.mjs usage or docs.",
+        "YAML parsing is limited to first-class action/workflow inputs, not arbitrary step environment variables.",
+      ],
+    },
+  };
+  return result;
+}
+
+export function assertPublicSurfaceReverseAudit(report) {
+  if (report.status !== "passed") {
+    const failures = [
+      ...report.comparison.missingCliRegistry.map((entry) => `missing CLI registry: ${entry.id}`),
+      ...report.comparison.missingWorkflowRegistry.map((entry) => `missing workflow registry: ${entry.id}`),
+      ...report.comparison.missingActionRegistry.map((entry) => `missing action registry: ${entry.id}`),
+      ...report.comparison.missingPageRegistry.map((entry) => `missing site page registry: ${entry.id}`),
+      ...report.comparison.unknownDocCommandRefs.map((entry) => `unknown docs command ref: ${entry.command} in ${entry.path}`),
+    ];
+    throw new Error(`Buildchain public surface reverse audit failed:\n${failures.join("\n")}`);
+  }
+  return report;
+}

package/packages/core/release-line-bootstrap.js

@@ -0,0 +1,242 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import {
+  discoverConfiguredVersionStateFiles,
+  getLifecycleStage,
+  loadBuildchainConfig,
+  runLifecycleStage,
+  updateConfiguredVersionStateContents,
+} from "./buildchain-config.js";
+
+function asPositiveInteger(value, name) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new Error(`${name} must be a non-negative integer`);
+  }
+  return parsed;
+}
+
+function assertSemver(value, name) {
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(String(value || ""))) {
+    throw new Error(`${name} must be a semver version without a leading v`);
+  }
+}
+
+function normalizeRef(ref) {
+  return String(ref || "").trim().replace(/^refs\/heads\//, "");
+}
+
+function defaultSourceRef({ major, minor }) {
+  if (minor > 0) {
+    return `release/v${major}/v${major}.${minor - 1}`;
+  }
+  return `v${major}`;
+}
+
+function defaultInitialVersion({ major, minor }) {
+  return `${major}.${minor}.0-alpha.0`;
+}
+
+function defaultBootstrapBranch({ major, minor }) {
+  return `buildchain/release-line/v${major}.${minor}`;
+}
+
+function currentGitHead(cwd) {
+  try {
+    return execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+function readJsonIfExists(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return undefined;
+  }
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function writeJson(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function discoverVersionStateFiles(cwd, loadedConfig) {
+  if (loadedConfig?.config?.version?.files?.length) {
+    return discoverConfiguredVersionStateFiles(cwd, loadedConfig);
+  }
+  const files = [];
+  for (const relativePath of ["lerna.json", "package.json"]) {
+    const filePath = path.join(cwd, relativePath);
+    const content = readJsonIfExists(filePath);
+    if (content && typeof content.version === "string") {
+      files.push({
+        path: relativePath,
+        kind: relativePath === "lerna.json" ? "lerna" : "package",
+        content,
+      });
+    }
+  }
+  return files;
+}
+
+function updateDiscoveredVersionStateContents(files, version) {
+  if (files.some((file) => file.type)) {
+    return updateConfiguredVersionStateContents(files, version);
+  }
+  return files
+    .map((file) => {
+      const next = { ...file.content, version };
+      const content = writeJson(next);
+      return {
+        path: file.path,
+        kind: file.kind,
+        changed: content !== writeJson(file.content),
+        content,
+      };
+    })
+    .filter((file) => file.changed);
+}
+
+function changedPaths(cwd) {
+  const output = execFileSync("git", ["status", "--porcelain", "--untracked-files=all"], {
+    cwd,
+    encoding: "utf8",
+  }).trimEnd();
+  return output
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map((line) => line.slice(3).trim())
+    .sort();
+}
+
+export function planReleaseLineBootstrap({
+  cwd = process.cwd(),
+  major,
+  minor,
+  sourceRef = "",
+  initialVersion = "",
+  requiredStatusCheck = "check",
+  setDefault = true,
+  createAlphaPr = true,
+  approvalCount = 1,
+  bootstrapBranch = "",
+} = {}) {
+  const parsedMajor = asPositiveInteger(major, "major");
+  const parsedMinor = asPositiveInteger(minor, "minor");
+  const resolvedInitialVersion = initialVersion || defaultInitialVersion({ major: parsedMajor, minor: parsedMinor });
+  assertSemver(resolvedInitialVersion, "initialVersion");
+  const line = `v${parsedMajor}.${parsedMinor}`;
+  const devRef = `dev/v${parsedMajor}/${line}`;
+  const alphaRef = `alpha/v${parsedMajor}/${line}`;
+  const releaseRef = `release/v${parsedMajor}/${line}`;
+  const loadedConfig = loadBuildchainConfig(cwd);
+  const versionFiles = discoverVersionStateFiles(cwd, loadedConfig);
+  const lifecycleVersionState =
+    getLifecycleStage(loadedConfig, "version-state") ||
+    getLifecycleStage(loadedConfig, "version_state");
+  const source = normalizeRef(sourceRef) || defaultSourceRef({ major: parsedMajor, minor: parsedMinor });
+  const branch = normalizeRef(bootstrapBranch) || defaultBootstrapBranch({ major: parsedMajor, minor: parsedMinor });
+
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-release-line-bootstrap",
+    dryRun: true,
+    cwd,
+    line,
+    major: parsedMajor,
+    minor: parsedMinor,
+    initialVersion: resolvedInitialVersion,
+    source: {
+      ref: source,
+      sha: currentGitHead(cwd) || "",
+    },
+    refs: {
+      dev: devRef,
+      alpha: alphaRef,
+      release: releaseRef,
+      bootstrap: branch,
+    },
+    versionState: {
+      files: versionFiles.map((file) => file.path),
+      lifecycle: lifecycleVersionState ? "version-state" : "none",
+    },
+    protection: {
+      requiredStatusCheck,
+      strictStatusChecks: true,
+      requiredApprovingReviewCount: approvalCount,
+      requiredConversationResolution: true,
+      enforceAdmins: true,
+      protectedRefs: [devRef, alphaRef, releaseRef],
+    },
+    repositoryActions: [
+      { action: "create-or-verify-source-ref", ref: source },
+      { action: "commit-initial-version-state", ref: branch, version: resolvedInitialVersion },
+      { action: "create-dev-branch", ref: devRef, from: branch },
+      { action: "create-alpha-branch", ref: alphaRef, from: source },
+      { action: "create-release-branch", ref: releaseRef, from: source },
+      ...(setDefault ? [{ action: "set-default-branch", ref: devRef }] : []),
+      { action: "protect-branch", ref: devRef },
+      { action: "protect-branch", ref: alphaRef },
+      { action: "protect-branch", ref: releaseRef },
+      ...(createAlphaPr ? [{ action: "open-alpha-pr", head: devRef, base: alphaRef }] : []),
+    ],
+    notes: [
+      "This bootstrap creates the new minor line before the first alpha promotion.",
+      "The source ref stays as the baseline for alpha/release until reviewed channel PRs move them.",
+      "The dev branch receives only the initial version-state commit and becomes the active line when setDefault is true.",
+    ],
+  };
+}
+
+export function writeReleaseLineBootstrapVersionState({
+  cwd = process.cwd(),
+  major,
+  minor,
+  sourceRef = "",
+  initialVersion = "",
+  runVersionStateLifecycle = true,
+  generatedAt = "",
+} = {}) {
+  const plan = planReleaseLineBootstrap({ cwd, major, minor, sourceRef, initialVersion });
+  const loadedConfig = loadBuildchainConfig(cwd);
+  const files = discoverVersionStateFiles(cwd, loadedConfig);
+  if (files.length === 0) {
+    throw new Error("release line bootstrap requires at least one version-state file");
+  }
+  const changed = updateDiscoveredVersionStateContents(files, plan.initialVersion);
+  for (const file of changed) {
+    fs.writeFileSync(path.join(cwd, file.path), file.content);
+  }
+  const lifecycleVersionState =
+    getLifecycleStage(loadedConfig, "version-state") ||
+    getLifecycleStage(loadedConfig, "version_state");
+  if (runVersionStateLifecycle && lifecycleVersionState) {
+    const timestamp = generatedAt || new Date().toISOString();
+    runLifecycleStage({
+      cwd,
+      loadedConfig,
+      name: "version-state",
+      stage: lifecycleVersionState,
+      env: {
+        BUILDCHAIN_VERSION: plan.initialVersion,
+        BUILDCHAIN_SITE_GENERATED_AT: timestamp,
+        BUILDCHAIN_SITE_PUBLISHED_AT: timestamp,
+        BUILDCHAIN_SITE_TIMESTAMP_POLICY: "ci-injected",
+        BUILDCHAIN_SURFACE_GENERATED_AT: timestamp,
+        BUILDCHAIN_SURFACE_PUBLISHED_AT: timestamp,
+        BUILDCHAIN_SURFACE_TIMESTAMP_POLICY: "ci-injected",
+        BUILDCHAIN_SOURCE_SHA: plan.source.sha,
+      },
+    });
+  }
+  return {
+    ...plan,
+    dryRun: false,
+    changedFiles: changedPaths(cwd),
+  };
+}

package/scripts/check-inventory.mjs

@@ -1,5 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
+import {
+  assertPublicSurfaceReverseAudit,
+  collectPublicSurfaceReverseAudit,
+} from "../packages/core/public-surface-audit.js";
 
 const root = process.cwd();
 const sharedActionTsupConfig = fs.readFileSync(path.join(root, "scripts/tsup-action.config.mjs"), "utf8");
@@ -16,6 +20,8 @@ const requiredPaths = [
   "bin/buildchain.mjs",
   "packages/core/homebrew.js",
   "packages/core/build-facts.js",
+  "packages/core/release-line-bootstrap.js",
+  "packages/core/public-surface-audit.js",
   "docs/MAP.md",
   "docs/build-facts.md",
   "docs/binary-distribution.md",
@@ -52,6 +58,7 @@ const requiredPaths = [
   ".github/actionlint.yaml",
   ".github/workflows/self-hosted-runner-smoke.yml",
   ".github/workflows/buildchain-ref-promotion.yml",
+  ".github/workflows/release-line-bootstrap.yml",
   ".github/workflows/dev-pr-auto-merge.yml",
   ".github/workflows/buildchain-patrol.yml",
   ".github/workflows/patrol-daily.yml",
@@ -119,6 +126,9 @@ if (rootPackage.exports?.["./buildchain-contract"] !== "./packages/core/buildcha
 if (rootPackage.exports?.["./issue-reporting"] !== "./packages/core/issue-reporting.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/issue-reporting");
 }
+if (rootPackage.exports?.["./release-line-bootstrap"] !== "./packages/core/release-line-bootstrap.js") {
+  throw new Error("root package must export @kungfu-tech/buildchain/release-line-bootstrap");
+}
 if (rootPackage.exports?.["./readme-badges"] !== "./packages/core/readme-badges.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/readme-badges");
 }
@@ -146,6 +156,9 @@ if (rootPackage.exports?.["./surface-manifest"] !== "./packages/core/surface-man
 if (rootPackage.exports?.["./buildchain-kfd-claims"] !== "./packages/core/buildchain-kfd-claims.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/buildchain-kfd-claims");
 }
+if (rootPackage.exports?.["./public-surface-audit"] !== "./packages/core/public-surface-audit.js") {
+  throw new Error("root package must export @kungfu-tech/buildchain/public-surface-audit");
+}
 if (rootPackage.exports?.["./site/buildchain-site.json"] !== "./dist/site/buildchain-site.json") {
   throw new Error("root package must export @kungfu-tech/buildchain/site/buildchain-site.json");
 }
@@ -164,6 +177,9 @@ if (rootPackage.exports?.["./site/node-api-registry.json"] !== "./dist/site/node
 if (rootPackage.exports?.["./site/kfd-claims.json"] !== "./dist/site/kfd-claims.json") {
   throw new Error("root package must export @kungfu-tech/buildchain/site/kfd-claims.json");
 }
+if (rootPackage.exports?.["./site/public-surface-audit.json"] !== "./dist/site/public-surface-audit.json") {
+  throw new Error("root package must export @kungfu-tech/buildchain/site/public-surface-audit.json");
+}
 if (rootPackage.publishConfig?.access !== "public") {
   throw new Error("root package publishConfig.access must be public");
 }
@@ -190,6 +206,7 @@ const siteBundle = JSON.parse(fs.readFileSync(path.join(root, "dist/site/buildch
 const siteManifest = JSON.parse(fs.readFileSync(path.join(root, "dist/site/site-manifest.json"), "utf8"));
 const pageRegistry = JSON.parse(fs.readFileSync(path.join(root, "dist/site/page-registry.json"), "utf8"));
 const badgeEndpointRegistry = JSON.parse(fs.readFileSync(path.join(root, "dist/site/badge-endpoint-registry.json"), "utf8"));
+const publicSurfaceAudit = JSON.parse(fs.readFileSync(path.join(root, "dist/site/public-surface-audit.json"), "utf8"));
 if (!cliSource.startsWith("#!/usr/bin/env node")) {
   throw new Error("bin/buildchain.mjs must be executable with a node shebang");
 }
@@ -306,6 +323,18 @@ if (siteBundle.pageRegistry?.path !== "page-registry.json" || siteBundle.pageReg
 if (!siteManifest.facts?.includes("page-registry.json") || !siteBundle.entrypoints?.includes("page-registry.json")) {
   throw new Error("site bundle entrypoints must include page-registry.json");
 }
+if (!siteManifest.facts?.includes("public-surface-audit.json") || !siteBundle.entrypoints?.includes("public-surface-audit.json")) {
+  throw new Error("site bundle entrypoints must include public-surface-audit.json");
+}
+if (publicSurfaceAudit.contract !== "kungfu-buildchain-public-surface-reverse-audit") {
+  throw new Error("public-surface-audit.json must expose the reverse audit contract");
+}
+assertPublicSurfaceReverseAudit(publicSurfaceAudit);
+const livePublicSurfaceAudit = collectPublicSurfaceReverseAudit({ root });
+assertPublicSurfaceReverseAudit(livePublicSurfaceAudit);
+if (JSON.stringify(publicSurfaceAudit.summary) !== JSON.stringify(livePublicSurfaceAudit.summary)) {
+  throw new Error("public-surface-audit.json summary is stale; run pnpm run generate:site");
+}
 for (const [name, manifest] of [["buildchain-site.json", siteBundle], ["site-manifest.json", siteManifest]]) {
   if (!manifest.generatedAt) {
     throw new Error(`${name} must expose generatedAt`);
@@ -361,6 +390,8 @@ for (const requiredSnippet of [
   "createBuildchainKfd2Claims",
   "createBuildchainKfd3PrebuildWitness",
   "BUILDCHAIN_AGENT_MANUALS",
+  "collectPublicSurfaceReverseAudit",
+  "assertPublicSurfaceReverseAudit",
 ]) {
   if (!coreIndexSource.includes(requiredSnippet)) {
     throw new Error(`packages/core/index.js must export Buildchain self KFD claim API: ${requiredSnippet}`);
@@ -820,7 +851,7 @@ if (!badgeEndpointRegistry.badges?.some((entry) => entry.id === "buildchain-rele
   throw new Error("badge endpoint registry must include Buildchain Release Passport badge");
 }
 
-for (const siteFile of ["buildchain-site.json", "site-manifest.json", "badge-endpoint-registry.json", "cli-registry.json", "manual-registry.json", "node-api-registry.json", "release-model.json", "buildchain-contract.json"]) {
+for (const siteFile of ["buildchain-site.json", "site-manifest.json", "badge-endpoint-registry.json", "cli-registry.json", "manual-registry.json", "node-api-registry.json", "workflow-registry.json", "public-surface-audit.json", "release-model.json", "buildchain-contract.json"]) {
   if (!fs.existsSync(path.join(root, "dist", "site", siteFile))) {
     throw new Error(`site bundle missing ${siteFile}`);
   }