@kungfu-tech/buildchain 2.9.0 → 2.9.1

package/docs/MAP.md

@@ -21,6 +21,7 @@ manuals explain those facts and give operator examples.
 | Capability | Machine-readable entry | Manual entry |
 | --- | --- | --- |
 | KFD-1 / KFD-2 / KFD-3 release-passport gates | `dist/site/kfd-claims.json`, `dist/site/buildchain-contract.json`, `dist/site/artifact-schemas.json` | [`release-passport.md`](release-passport.md) |
+| KFD-3 public surface reverse audit | `dist/site/public-surface-audit.json`, `dist/site/cli-registry.json`, `dist/site/workflow-registry.json`, `dist/site/page-registry.json` | [`cli.md`](cli.md), [`site-bundle-contract.md`](site-bundle-contract.md) |
 | Floating `@v2` drift detection and compatibility issues | `dist/site/buildchain-contract.json` | [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock) |
 | npm publish transactions, evidence, dist-tags, and recovery | `dist/site/release-model.json`, `dist/site/artifact-schemas.json` | [`publish-transaction.md`](publish-transaction.md) |
 | Git/source/version/module/product build facts | `dist/site/node-api-registry.json`, `dist/site/cli-registry.json`, `kungfu-buildchain-module-build-facts`, `kungfu-buildchain-product-build-facts` | [`build-facts.md`](build-facts.md) |

package/docs/cli.md

@@ -71,9 +71,12 @@ import { collectBadgeBundleFacts } from "@kungfu-tech/buildchain/badges";
 import { collectReadmeBadgeFacts } from "@kungfu-tech/buildchain/readme-badges";
 import { verifyReleasePassport } from "@kungfu-tech/buildchain/release-passport";
 import { createReleasePropagationPlan } from "@kungfu-tech/buildchain/release-propagation";
+import { planReleaseLineBootstrap } from "@kungfu-tech/buildchain/release-line-bootstrap";
+import { collectPublicSurfaceReverseAudit } from "@kungfu-tech/buildchain/public-surface-audit";
 import contractWorld from "@kungfu-tech/buildchain/site/buildchain-contract.json" with { type: "json" };
 import manualRegistry from "@kungfu-tech/buildchain/site/manual-registry.json" with { type: "json" };
 import nodeApiRegistry from "@kungfu-tech/buildchain/site/node-api-registry.json" with { type: "json" };
+import publicSurfaceAudit from "@kungfu-tech/buildchain/site/public-surface-audit.json" with { type: "json" };
 ```
 
 Use `dist/site/manual-registry.json` to find the packaged operating manuals and
@@ -121,6 +124,50 @@ buildchain lifecycle run build \
   --artifact-name "{repo}-{version}-{platform}"
 ```
 
+`buildchain release line open` plans or writes the first version-state commit
+for a new semver minor line. It does not publish anything. The dry-run mode is
+the default and returns the dev/alpha/release refs, protection contract, default
+branch action, and initial version before any GitHub mutation happens:
+
+```bash
+buildchain release line open \
+  --major 2 \
+  --minor 10 \
+  --source-ref release/v2/v2.9 \
+  --json
+```
+
+The write mode only updates local version-state files. The repository workflow
+`Release Line Bootstrap` wraps this command and, when `apply=true`, commits the
+initial version state, creates `dev/vX/vX.Y`, `alpha/vX/vX.Y`, and
+`release/vX/vX.Y`, applies one-review branch protection, switches the default
+branch, and opens the first dev-to-alpha channel PR:
+
+```bash
+buildchain release line open \
+  --major 2 \
+  --minor 10 \
+  --source-ref release/v2/v2.9 \
+  --write \
+  --json
+```
+
+`buildchain` also publishes a public surface reverse audit as
+`dist/site/public-surface-audit.json`. The audit enumerates CLI commands from
+`bin/buildchain.mjs`, workflow inputs, action inputs, site pages, and docs
+command references, then compares them with the generated registries. Buildchain
+self-checks fail closed when an enumerable public surface is missing from the
+registry:
+
+```js
+import {
+  collectPublicSurfaceReverseAudit,
+  assertPublicSurfaceReverseAudit,
+} from "@kungfu-tech/buildchain/public-surface-audit";
+
+assertPublicSurfaceReverseAudit(collectPublicSurfaceReverseAudit({ root: process.cwd() }));
+```
+
 Lifecycle runs also write a Buildchain observability JSONL log at
 `.buildchain/logs/events.jsonl` by default. Framework events use
 `source=buildchain`; consumer lifecycle commands use `source=user`. This lets a

package/docs/release-flow.md

@@ -73,6 +73,37 @@ The intended governance split is:
 - protected branches still require reviewed channel PRs before Buildchain can
   move any exact or floating release refs.
 
+## Opening a Minor Line
+
+New minor lines should be opened through Buildchain instead of hand-created
+branches. The reusable entrypoint is the `Release Line Bootstrap` workflow. It
+defaults to dry-run so maintainers can inspect the planned refs, protection
+contract, initial version, and first alpha PR before any mutation.
+
+The workflow is backed by the CLI command:
+
+```bash
+buildchain release line open \
+  --major 2 \
+  --minor 10 \
+  --source-ref release/v2/v2.9 \
+  --json
+```
+
+When the workflow is run with `apply=true`, Buildchain:
+
+- writes the initial version-state commit, such as `2.10.0-alpha.0`;
+- creates `dev/v2/v2.10` from that commit;
+- creates `alpha/v2/v2.10` and `release/v2/v2.10` from the selected source ref;
+- applies branch protection with one approving review and the configured
+  required status check;
+- switches the repository default branch to the new dev line when requested;
+- opens the first `dev/v2/v2.10 -> alpha/v2/v2.10` channel PR when requested.
+
+This makes minor-line creation a single audited operation. The channel PR still
+goes through the normal verify/review/promotion path before an alpha is
+published.
+
 ## Alpha Promotion
 
 ```mermaid

package/docs/release-passport.md

@@ -261,6 +261,16 @@ by downstream sites and by Buildchain's own release passport. Exact release
 version/SHA binding is deliberately deferred to the promotion witness, so the
 source registry can remain stable across semver version-state bumps.
 
+Buildchain also performs a reverse audit before that witness is used. The
+generated `dist/site/public-surface-audit.json` enumerates real CLI commands
+from `bin/buildchain.mjs`, workflow inputs, action inputs, site pages, and docs
+command references, then compares them with the generated registries. Buildchain
+self KFD witnesses include that audit result and classify the collaboration
+interface as closed-world only when the reverse audit passes. If a public
+command, workflow input, action input, or site page is exposed without a
+registry entry, `pnpm run check` fails before release promotion can produce a
+passport.
+
 The product remains the fact source. Before build/publish, the product writes a
 pre-build witness:
 

package/docs/site-bundle-contract.md

@@ -17,6 +17,7 @@ dist/site/
   manual-registry.json
   node-api-registry.json
   workflow-registry.json
+  public-surface-audit.json
   release-model.json
   artifact-schemas.json
   buildchain-contract.json
@@ -51,6 +52,12 @@ internal paths.
 from `packages/core/buildchain-kfd-claims.js` and enumerates the public release
 claims plus the KFD-3 collaboration surfaces that Buildchain self-verifies
 during release promotion.
+`public-surface-audit.json` is the reverse enumeration report for those
+surfaces. It enumerates real CLI commands from `bin/buildchain.mjs`, workflow
+inputs, action inputs, site pages, and documentation command references, then
+compares those sets with `cli-registry.json`, `workflow-registry.json`, and
+`page-registry.json`. Buildchain's self-check fails closed when an enumerable
+public surface is missing from the generated registries.
 
 ## Timestamp and Reproducibility Policy
 

package/docs/web-surface-deployments.md

@@ -384,6 +384,16 @@ and `pr-29/buildchain/docs/`. This makes surface-host requests for `/` and
 `/docs/` resolve to the surface's `index.html` files even when the CloudFront
 origin is an S3 REST origin rather than an S3 website endpoint.
 
+For host-per-surface previews, Buildchain also ensures each configured
+CloudFront distribution has `DefaultRootObject = "index.html"` before syncing
+the surface payload. This is required because the child surface host root
+request (`https://buildchain-pr-29.preview.libkungfu.dev/`) must first resolve
+to `/index.html`; the existing host/prefix mapping can then serve the object
+`pr-29/buildchain/index.html`, the same object that explicit
+`/index.html` requests already reach. The operation is idempotent per
+distribution and is emitted once even when multiple surfaces share the same
+CloudFront distribution.
+
 It can also execute a previously saved deploy plan. In that mode Buildchain
 recomputes the local artifact hash before running AWS commands and fails closed
 if the artifact no longer matches the saved plan:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.9.0",
+  "version": "2.9.1",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -20,7 +20,9 @@
     "./diagnostics": "./packages/core/diagnostics.js",
     "./homebrew": "./packages/core/homebrew.js",
     "./issue-reporting": "./packages/core/issue-reporting.js",
+    "./release-line-bootstrap": "./packages/core/release-line-bootstrap.js",
     "./readme-badges": "./packages/core/readme-badges.js",
+    "./public-surface-audit": "./packages/core/public-surface-audit.js",
     "./logging": "./packages/core/logging.js",
     "./kfd-gate": "./packages/core/kfd-gate.js",
     "./release-candidate": "./packages/core/release-candidate.js",
@@ -36,6 +38,7 @@
     "./site/node-api-registry.json": "./dist/site/node-api-registry.json",
     "./site/kfd-claims.json": "./dist/site/kfd-claims.json",
     "./site/workflow-registry.json": "./dist/site/workflow-registry.json",
+    "./site/public-surface-audit.json": "./dist/site/public-surface-audit.json",
     "./site/release-model.json": "./dist/site/release-model.json",
     "./site/artifact-schemas.json": "./dist/site/artifact-schemas.json",
     "./site/buildchain-contract.json": "./dist/site/buildchain-contract.json",

package/packages/core/buildchain-kfd-claims.js

@@ -2,6 +2,10 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { createBuildchainContractWorld, sha256Json } from "./buildchain-contract.js";
+import {
+  BUILDCHAIN_PUBLIC_SURFACE_AUDIT_CONTRACT,
+  collectPublicSurfaceReverseAudit,
+} from "./public-surface-audit.js";
 
 export const BUILDCHAIN_KFD_CLAIM_REGISTRY_CONTRACT = "kungfu-buildchain-kfd-claim-registry";
 export const BUILDCHAIN_KFD_COLLABORATION_INTERFACE_CONTRACT = "kungfu-buildchain-kfd-collaboration-interface";
@@ -41,6 +45,7 @@ const SITE_CONTRACT_FILES = Object.freeze([
   "dist/site/manual-registry.json",
   "dist/site/node-api-registry.json",
   "dist/site/workflow-registry.json",
+  "dist/site/public-surface-audit.json",
   "dist/site/release-model.json",
   "dist/site/artifact-schemas.json",
   "dist/site/buildchain-contract.json",
@@ -55,6 +60,7 @@ const SCHEMA_AND_STANDARD_FILES = Object.freeze([
   "packages/core/release-passport.js",
   "packages/core/buildchain-contract.js",
   "packages/core/buildchain-kfd-claims.js",
+  "packages/core/public-surface-audit.js",
   "dist/site/artifact-schemas.json",
   "dist/site/buildchain-contract.json",
 ]);
@@ -79,6 +85,51 @@ const EXTRA_KFD1_FILES = Object.freeze([
   "scripts/ensure-github-release.mjs",
 ]);
 
+function publicSurfaceReverseAudit({ root }) {
+  if (!fileExists(root, "bin/buildchain.mjs")) {
+    return {
+      schemaVersion: 1,
+      contract: BUILDCHAIN_PUBLIC_SURFACE_AUDIT_CONTRACT,
+      status: "unavailable",
+      summary: { failureCount: 0 },
+      enumerated: {
+        cliCommands: [],
+        workflowInputs: [],
+        actionInputs: [],
+        sitePages: [],
+        docCommandRefs: [],
+      },
+      declared: {},
+      comparison: {
+        missingCliRegistry: [],
+        missingWorkflowRegistry: [],
+        missingActionRegistry: [],
+        missingPageRegistry: [],
+        unknownDocCommandRefs: [],
+      },
+      auditBoundary: {
+        mode: "not-enumerated",
+        scope: "Fixture or partial source tree without bin/buildchain.mjs",
+        residualRisk: ["Reverse audit is only enforceable in a complete Buildchain source tree."],
+      },
+    };
+  }
+  return collectPublicSurfaceReverseAudit({ root });
+}
+
+function publicSurfaceAuditEvidence(root) {
+  const relPath = "dist/site/public-surface-audit.json";
+  const audit = publicSurfaceReverseAudit({ root });
+  return {
+    contract: BUILDCHAIN_PUBLIC_SURFACE_AUDIT_CONTRACT,
+    path: relPath,
+    status: audit.status,
+    sha256: fileExists(root, relPath) ? sha256File(root, relPath) : "",
+    summary: audit.summary,
+    auditBoundary: audit.auditBoundary,
+  };
+}
+
 function immediateReadmes(root, dir) {
   const absoluteDir = path.join(root, dir);
   if (!fs.existsSync(absoluteDir)) return [];
@@ -214,6 +265,23 @@ export function createBuildchainPublicClaimDefinitions() {
         "dist/site/site-manifest.json",
       ],
     },
+    {
+      id: "claim:buildchain-public-surface-reverse-audit",
+      claim: "Buildchain fails closed when enumerable public CLI, workflow, action, site page, or documentation command surfaces are exposed without a matching machine registry entry.",
+      sourcePaths: [
+        "packages/core/public-surface-audit.js",
+        "scripts/generate-site-bundle.mjs",
+        "scripts/check-inventory.mjs",
+        "bin/buildchain.mjs",
+      ],
+      artifactPaths: [
+        "dist/site/public-surface-audit.json",
+        "dist/site/cli-registry.json",
+        "dist/site/workflow-registry.json",
+        "dist/site/page-registry.json",
+        "dist/site/kfd-claims.json",
+      ],
+    },
     {
       id: "claim:buildchain-readme-badge-facts",
       claim: "Buildchain README status badges are generated from repository-owned facts and verified release-passport evidence, not hand-maintained README prose.",
@@ -309,6 +377,7 @@ export function createBuildchainPublicClaimDefinitions() {
 
 export function createBuildchainKfdSurfaceRegistry({ root = process.cwd() } = {}) {
   const pkg = packageJson(root);
+  const reverseAudit = publicSurfaceReverseAudit({ root });
   const exports = Object.entries(pkg.exports || {})
     .filter(([specifier]) => !specifier.startsWith("./site/") && specifier !== "./package.json")
     .map(([specifier, target]) => surface(
@@ -337,18 +406,40 @@ export function createBuildchainKfdSurfaceRegistry({ root = process.cwd() } = {}
   ];
   const siteConsumptionContracts = SITE_CONTRACT_FILES.map((relPath) => surface(`site:${relPath}`, "site-consumption-contract", relPath));
   const controlSurfaces = WORKFLOW_AND_ACTION_FILES.map((relPath) => surface(`control:${relPath}`, relPath.includes("actions/") ? "action" : "workflow", relPath));
+  const reverseEnumeratedSurfaces = uniqueById([
+    ...reverseAudit.enumerated.cliCommands.map((entry) => surface(`cli:${entry.id}`, "cli-command", "bin/buildchain.mjs", {
+      name: entry.usage,
+      reverseAuditSource: entry.source,
+    })),
+    ...reverseAudit.enumerated.workflowInputs.map((entry) => surface(`workflow:${entry.id}`, "workflow", entry.path, {
+      inputCount: entry.inputCount,
+      inputs: entry.inputs,
+      reverseAuditSource: ".github/workflows",
+    })),
+    ...reverseAudit.enumerated.actionInputs.map((entry) => surface(`action:${entry.id}`, "action", entry.path, {
+      inputCount: entry.inputCount,
+      inputs: entry.inputs,
+      reverseAuditSource: "actions/*/action.yml",
+    })),
+    ...reverseAudit.enumerated.sitePages.map((entry) => surface(`site-page:${entry.id}`, "site-page", "dist/site/page-registry.json", {
+      pagePath: entry.path,
+      reverseAuditSource: "dist/site/page-registry.json",
+    })),
+  ]);
   return {
     schemaVersion: 1,
     contract: BUILDCHAIN_KFD_COLLABORATION_INTERFACE_CONTRACT,
+    reverseAudit: publicSurfaceAuditEvidence(root),
     groups: {
       docs,
       schemas,
       standardsMetadata,
       packageExports: exports,
       siteConsumptionContracts,
+      reverseEnumeratedSurfaces,
     },
     additionalSurfaces: controlSurfaces,
-    publicSurfaceCount: docs.length + schemas.length + standardsMetadata.length + exports.length + siteConsumptionContracts.length + controlSurfaces.length,
+    publicSurfaceCount: docs.length + schemas.length + standardsMetadata.length + exports.length + siteConsumptionContracts.length + reverseEnumeratedSurfaces.length + controlSurfaces.length,
   };
 }
 
@@ -366,6 +457,7 @@ export function createBuildchainKfdClaimRegistry({ root = process.cwd(), sourceS
       sourceModule: "packages/core/buildchain-kfd-claims.js",
     },
     runtimeContract: runtimeContractSummary({ root }),
+    publicSurfaceReverseAudit: publicSurfaceAuditEvidence(root),
     publicClaims: createBuildchainPublicClaimDefinitions(),
     collaborationSurfaces: createBuildchainKfdSurfaceRegistry({ root }),
   };
@@ -427,6 +519,7 @@ export function createBuildchainKfd1Witness({ root = process.cwd(), sourceSha =
 export function createBuildchainKfd3PrebuildWitness({ root = process.cwd(), sourceSha = "" } = {}) {
   const registry = createBuildchainKfdClaimRegistry({ root, sourceSha });
   const surfaces = createBuildchainKfdSurfaceRegistry({ root });
+  const reverseAudit = publicSurfaceAuditEvidence(root);
   const digest = `sha256:${sha256Json(registry)}`;
   return {
     schemaVersion: 1,
@@ -458,21 +551,24 @@ export function createBuildchainKfd3PrebuildWitness({ root = process.cwd(), sour
       standardsMetadata: surfaces.groups.standardsMetadata,
       packageExports: surfaces.groups.packageExports,
       siteConsumptionContracts: surfaces.groups.siteConsumptionContracts,
+      reverseEnumeratedSurfaces: surfaces.groups.reverseEnumeratedSurfaces,
       surfaces: surfaces.additionalSurfaces,
+      reverseAudit,
       closure: {
-        classificationMode: "closed-world",
-        reachableSurfaceMode: "declared-boundary",
+        classificationMode: reverseAudit.status === "passed" ? "closed-world" : "partial",
+        reachableSurfaceMode: reverseAudit.status === "passed" ? "reverse-enumerated-boundary" : "declared-boundary",
         unclassifiedEntrypointsPolicy: "fail",
-        nonExhaustivelyEnumerableSurfaces: [],
+        nonExhaustivelyEnumerableSurfaces: reverseAudit.status === "passed" ? [] : [reverseAudit.auditBoundary?.scope || "public surface reverse audit unavailable"],
         explicitlyExemptedSurfaces: [],
       },
     },
     auditBoundary: {
-      mode: "closed-world",
+      mode: reverseAudit.status === "passed" ? "closed-world" : "partial",
       scope: "Buildchain public human/agent release, workflow, package, and site-consumption surfaces",
-      reachableSurfaceMode: "declared-boundary",
+      reachableSurfaceMode: reverseAudit.status === "passed" ? "reverse-enumerated-boundary" : "declared-boundary",
       unclassifiedPolicy: "fail",
-      nonExhaustivelyEnumerableSurfaces: [],
+      reverseAudit,
+      nonExhaustivelyEnumerableSurfaces: reverseAudit.status === "passed" ? [] : [reverseAudit.auditBoundary?.scope || "public surface reverse audit unavailable"],
       explicitlyExemptedSurfaces: [],
     },
     residualRisk: [],
@@ -487,6 +583,7 @@ export function createBuildchainKfd3PrebuildWitness({ root = process.cwd(), sour
 export function createBuildchainKfd3ArtifactWitness({ root = process.cwd(), sourceSha = "" } = {}) {
   const registry = createBuildchainKfdClaimRegistry({ root, sourceSha });
   const surfaces = createBuildchainKfdSurfaceRegistry({ root });
+  const reverseAudit = publicSurfaceAuditEvidence(root);
   return {
     schemaVersion: 1,
     id: "buildchain-collaboration-interface",
@@ -507,7 +604,15 @@ export function createBuildchainKfd3ArtifactWitness({ root = process.cwd(), sour
     standardsMetadata: surfaces.groups.standardsMetadata,
     packageExports: surfaces.groups.packageExports,
     siteConsumptionContracts: surfaces.groups.siteConsumptionContracts,
+    reverseEnumeratedSurfaces: surfaces.groups.reverseEnumeratedSurfaces,
     surfaces: surfaces.additionalSurfaces,
+    reverseAudit,
+    auditBoundary: {
+      mode: reverseAudit.status === "passed" ? "closed-world" : "partial",
+      reachableSurfaceMode: reverseAudit.status === "passed" ? "reverse-enumerated-boundary" : "declared-boundary",
+      reverseAudit,
+      nonExhaustivelyEnumerableSurfaces: reverseAudit.status === "passed" ? [] : [reverseAudit.auditBoundary?.scope || "public surface reverse audit unavailable"],
+    },
     verifier: {
       name: "Buildchain self KFD witness generator",
       source: "scripts/generate-buildchain-kfd-witnesses.mjs",
@@ -519,11 +624,17 @@ export function createBuildchainKfd2Claims({ root = process.cwd(), witnessFiles
   const evidenceFiles = Object.entries(witnessFiles)
     .filter(([, relPath]) => relPath)
     .map(([id, relPath]) => fileEvidence(root, relPath, { id }));
+  const reverseAuditEvidence = publicSurfaceAuditEvidence(root);
   return createBuildchainPublicClaimDefinitions().map((definition) => {
     const sourceBindings = uniqueById(definition.sourcePaths.map((relPath) => fileEvidence(root, relPath)));
     const artifacts = uniqueById(definition.artifactPaths.map((relPath) => fileEvidence(root, relPath)));
     const machineEvidence = [
       ...evidenceFiles,
+      fileEvidence(root, "dist/site/public-surface-audit.json", {
+        id: "public-surface-reverse-audit",
+        contract: reverseAuditEvidence.contract,
+        status: reverseAuditEvidence.status,
+      }),
       { id: "buildchain-kfd-claim-definition", digest: `sha256:${sha256Json(definition)}` },
     ];
     return {

package/packages/core/index.js

@@ -137,6 +137,11 @@ export {
   sha256Json as sha256BuildchainContractJson,
 } from "./buildchain-contract.js";
 
+export {
+  planReleaseLineBootstrap,
+  writeReleaseLineBootstrapVersionState,
+} from "./release-line-bootstrap.js";
+
 export {
   BUILDCHAIN_JSON_FORMATTING_POLICY,
   KFD1_RELEASE_GATE_CONTRACT,
@@ -169,6 +174,17 @@ export {
   createBuildchainPublicClaimDefinitions,
 } from "./buildchain-kfd-claims.js";
 
+export {
+  BUILDCHAIN_PUBLIC_SURFACE_AUDIT_CONTRACT,
+  assertPublicSurfaceReverseAudit,
+  collectPublicSurfaceReverseAudit,
+  enumerateActionInputs,
+  enumerateCliCommandsFromBin,
+  enumerateDocCommandRefs,
+  enumerateSitePages,
+  enumerateWorkflowInputs,
+} from "./public-surface-audit.js";
+
 export {
   AGENT_INDEX_CONTRACT,
   ARTIFACT_EVIDENCE_CONTRACT,