@kungfu-tech/buildchain 3.0.6 → 3.0.7-alpha.0

package/packages/core/paper.js

@@ -46,6 +46,11 @@ import {
   scaffoldReadme,
 } from "./paper-scaffold-content.js";
 import { executePaperNpmBootstrap as executePaperNpmBootstrapOperation } from "./paper-npm-bootstrap.js";
+import {
+  appendPublicationRehearsalToml,
+  projectPublicationRehearsalToml,
+  publicationRehearsalWorkflow,
+} from "./publication-rehearsal-projection.js";
 
 export { PAPER_PATHS, resolvePaperRepository } from "./paper-repository.js";
 export {
@@ -114,6 +119,7 @@ const PAPER_SCAFFOLD_PATHS = Object.freeze([
   PAPER_PATHS.buildWorkflow,
   PAPER_PATHS.verifyWorkflow,
   PAPER_PATHS.releaseWorkflow,
+  PAPER_PATHS.rehearsalWorkflow,
   PAPER_PATHS.pnpmWorkspace,
   PAPER_PATHS.provisioningAuthority,
   "Makefile",
@@ -350,7 +356,7 @@ immutable_base_url = ${tomlString(joinUrl(siteBaseUrl, "archive").replace(/\/$/,
 registry_path = ".buildchain/publication/publication-registry.json"
 `
     : "";
-  return `schema = 1
+  return appendPublicationRehearsalToml(`schema = 1
 
 [project]
 type = "publication-artifact"
@@ -384,7 +390,7 @@ command = "make pdf"
 
 [lifecycle.verify]
 command = "make check"
-`;
+`);
 }
 
 function scaffoldBuildWorkflow(
@@ -525,6 +531,7 @@ export function createPaperProvisioningAuthority({
   buildWorkflow,
   verifyWorkflow,
   releaseWorkflow,
+  rehearsalWorkflow,
   agentEntry,
   agentInstructions,
   environment = "",
@@ -564,6 +571,12 @@ export function createPaperProvisioningAuthority({
         reusablePath: ".github/workflows/paper-release-sealed.yml",
         reusableRef: buildchainSha,
       },
+      rehearsal: {
+        path: PAPER_PATHS.rehearsalWorkflow,
+        sourceDigest: sha256Text(rehearsalWorkflow),
+        reusablePath: ".github/workflows/release-tail.yml",
+        reusableRef: buildchainSha,
+      },
     },
     agentEntry: {
       contract: PAPER_AGENT_ENTRY_CONTRACT,
@@ -630,6 +643,7 @@ function scaffoldFiles({
     releasePassportProductName: title,
   });
   const verifyWorkflow = scaffoldVerifyWorkflow(buildchainSha);
+  const rehearsalWorkflow = publicationRehearsalWorkflow(buildchainSha);
   const agentEntry = paperAgentEntryFiles({
     cwd,
     buildchainVersion,
@@ -647,6 +661,7 @@ function scaffoldFiles({
     buildWorkflow,
     verifyWorkflow,
     releaseWorkflow,
+    rehearsalWorkflow,
     agentEntry: agentEntry.get(PAPER_PATHS.agentEntry),
     agentInstructions: agentEntry.get(PAPER_PATHS.agentInstructions),
   });
@@ -667,6 +682,7 @@ function scaffoldFiles({
     [PAPER_PATHS.buildWorkflow, buildWorkflow],
     [PAPER_PATHS.verifyWorkflow, verifyWorkflow],
     [PAPER_PATHS.releaseWorkflow, releaseWorkflow],
+    [PAPER_PATHS.rehearsalWorkflow, rehearsalWorkflow],
     [PAPER_PATHS.pnpmWorkspace, paperPnpmWorkspace("", buildchainVersion)],
     [PAPER_PATHS.provisioningAuthority, jsonText(provisioningAuthority)],
     ...agentEntry,
@@ -964,6 +980,7 @@ function migrationFiles({
     releasePassportProductName: config.publication.title,
   });
   const verifyWorkflow = scaffoldVerifyWorkflow(runtimeSha);
+  const rehearsalWorkflow = publicationRehearsalWorkflow(runtimeSha);
   const agentEntry = paperAgentEntryFiles({
     cwd,
     buildchainVersion: runtimeIdentity.version,
@@ -978,6 +995,7 @@ function migrationFiles({
     buildWorkflow,
     verifyWorkflow,
     releaseWorkflow,
+    rehearsalWorkflow,
     agentEntry: agentEntry.get(PAPER_PATHS.agentEntry),
     agentInstructions: agentEntry.get(PAPER_PATHS.agentInstructions),
   });
@@ -997,11 +1015,18 @@ function migrationFiles({
     runtimeIdentity.version,
   );
   const files = new Map([
+    [
+      PAPER_PATHS.config,
+      projectPublicationRehearsalToml(
+        fs.readFileSync(path.resolve(cwd, PAPER_PATHS.config), "utf8"),
+      ),
+    ],
     [PAPER_PATHS.contractLock, contractLockText],
     [PAPER_PATHS.versionPin, `${runtimeIdentity.version}\n`],
     [PAPER_PATHS.buildWorkflow, buildWorkflow],
     [PAPER_PATHS.verifyWorkflow, verifyWorkflow],
     [PAPER_PATHS.releaseWorkflow, releaseWorkflow],
+    [PAPER_PATHS.rehearsalWorkflow, rehearsalWorkflow],
     [PAPER_PATHS.pnpmWorkspace, pnpmWorkspace],
     [PAPER_PATHS.provisioningAuthority, jsonText(provisioningAuthority)],
     ...agentEntry,
@@ -1755,6 +1780,7 @@ function validatePaperProvisioningAuthority(cwd) {
     value.workflows?.build,
     value.workflows?.verify,
     value.workflows?.release,
+    value.workflows?.rehearsal,
   ]) {
     if (!workflow?.path || !workflow?.sourceDigest) {
       errors.push("paper workflow authority is incomplete");

package/packages/core/publication-rehearsal-projection.js

@@ -0,0 +1,173 @@
+import {
+  PUBLICATION_REHEARSAL_CAPSULE_CONTRACT,
+  PUBLICATION_REHEARSAL_COMMAND,
+  RELEASE_LOCAL_CONSTRUCTIBILITY_ADR,
+  RELEASE_LOCAL_CONSTRUCTIBILITY_INVARIANT,
+} from "./publication-rehearsal-runtime.js";
+
+export const PUBLICATION_REHEARSAL_AGENT_SECTION_START =
+  "<!-- buildchain:publication-rehearsal:v1:start -->";
+export const PUBLICATION_REHEARSAL_AGENT_SECTION_END =
+  "<!-- buildchain:publication-rehearsal:v1:end -->";
+export const PUBLICATION_REHEARSAL_WORKFLOW_PATH =
+  ".github/workflows/publication-rehearsal.yml";
+
+function tomlString(value) {
+  return JSON.stringify(value);
+}
+
+export function publicationRehearsalToml() {
+  return `[publication_rehearsal]
+contract = ${tomlString(PUBLICATION_REHEARSAL_CAPSULE_CONTRACT)}
+adr = ${tomlString(RELEASE_LOCAL_CONSTRUCTIBILITY_ADR)}
+invariant = ${tomlString(RELEASE_LOCAL_CONSTRUCTIBILITY_INVARIANT)}
+command = ${tomlString(PUBLICATION_REHEARSAL_COMMAND)}
+capsule = ".buildchain/publication/rehearsal-capsule.json"
+capsule_root = ".buildchain/publication/candidate"
+state = ".buildchain/publication/rehearsal-state.json"
+evidence = ".buildchain/publication/rehearsal-evidence.json"
+`;
+}
+
+export function assertPublicationRehearsalConfig(config) {
+  const section = config?.publication_rehearsal;
+  if (!section || typeof section !== "object" || Array.isArray(section)) {
+    throw new Error("publication_rehearsal table is missing");
+  }
+  const expected = {
+    contract: PUBLICATION_REHEARSAL_CAPSULE_CONTRACT,
+    adr: RELEASE_LOCAL_CONSTRUCTIBILITY_ADR,
+    invariant: RELEASE_LOCAL_CONSTRUCTIBILITY_INVARIANT,
+    command: PUBLICATION_REHEARSAL_COMMAND,
+    capsule: ".buildchain/publication/rehearsal-capsule.json",
+    capsule_root: ".buildchain/publication/candidate",
+    state: ".buildchain/publication/rehearsal-state.json",
+    evidence: ".buildchain/publication/rehearsal-evidence.json",
+  };
+  const actualKeys = Object.keys(section).sort();
+  const expectedKeys = Object.keys(expected).sort();
+  if (actualKeys.join("\n") !== expectedKeys.join("\n")) {
+    throw new Error(
+      `publication_rehearsal fields must be exactly: ${expectedKeys.join(", ")}`,
+    );
+  }
+  for (const [key, value] of Object.entries(expected)) {
+    if (section[key] !== value) {
+      throw new Error(`publication_rehearsal.${key} is stale or unsupported`);
+    }
+  }
+  return structuredClone(section);
+}
+
+export function appendPublicationRehearsalToml(source) {
+  const current = String(source || "").trimEnd();
+  if (/^\[publication_rehearsal\]$/mu.test(current)) {
+    throw new Error(
+      "buildchain config already contains a publication_rehearsal table",
+    );
+  }
+  return `${current}\n\n${publicationRehearsalToml()}`;
+}
+
+export function projectPublicationRehearsalToml(source) {
+  const current = String(source || "");
+  const start = current.search(/^\[publication_rehearsal\]\s*$/mu);
+  if (start === -1) return appendPublicationRehearsalToml(current);
+  const remainder = current.slice(start);
+  const nextTable = remainder
+    .slice(remainder.indexOf("\n") + 1)
+    .search(/^\[[^\n]+\]\s*$/mu);
+  const end =
+    nextTable === -1
+      ? current.length
+      : start + remainder.indexOf("\n") + 1 + nextTable;
+  const prefix = current.slice(0, start).trimEnd();
+  const suffix = current.slice(end).trimStart();
+  return `${prefix}\n\n${publicationRehearsalToml()}${suffix ? `\n${suffix}` : ""}`;
+}
+
+export function publicationRehearsalAgentInstructions() {
+  return `${PUBLICATION_REHEARSAL_AGENT_SECTION_START}
+## Publication rehearsal (required)
+
+Buildchain release behavior follows
+\`${RELEASE_LOCAL_CONSTRUCTIBILITY_ADR}\`. ${RELEASE_LOCAL_CONSTRUCTIBILITY_INVARIANT}
+
+Before hosted publication, restore the explicit
+\`${PUBLICATION_REHEARSAL_CAPSULE_CONTRACT}\` capsule and run exactly:
+
+\`\`\`sh
+${PUBLICATION_REHEARSAL_COMMAND}
+\`\`\`
+
+Simulation and replay evidence never claim external publication truth. GitHub
+Actions may add only declared credentials, transport, and unavoidable provider
+effects; it may not add semantic inputs from runner environment or workspace.
+${PUBLICATION_REHEARSAL_AGENT_SECTION_END}`;
+}
+
+export function mergePublicationRehearsalAgentInstructions(current = "") {
+  const source = String(current || "");
+  const section = publicationRehearsalAgentInstructions();
+  const start = source.indexOf(PUBLICATION_REHEARSAL_AGENT_SECTION_START);
+  const end = source.indexOf(PUBLICATION_REHEARSAL_AGENT_SECTION_END);
+  if ((start === -1) !== (end === -1)) {
+    throw new Error(
+      "AGENTS.md has an incomplete Buildchain publication rehearsal section",
+    );
+  }
+  if (start === -1) {
+    return source.trim()
+      ? `${source.trimEnd()}\n\n${section}\n`
+      : `# AGENTS.md\n\n${section}\n`;
+  }
+  if (
+    source.indexOf(PUBLICATION_REHEARSAL_AGENT_SECTION_START, start + 1) !==
+      -1 ||
+    source.indexOf(PUBLICATION_REHEARSAL_AGENT_SECTION_END, end + 1) !== -1 ||
+    end < start
+  ) {
+    throw new Error(
+      "AGENTS.md has ambiguous Buildchain publication rehearsal sections",
+    );
+  }
+  return `${source.slice(0, start)}${section}${source.slice(
+    end + PUBLICATION_REHEARSAL_AGENT_SECTION_END.length,
+  )}`;
+}
+
+export function publicationRehearsalWorkflow(buildchainRef) {
+  const ref = String(buildchainRef || "").trim();
+  if (!ref)
+    throw new Error("publication rehearsal workflow requires a Buildchain ref");
+  return `name: Publication Rehearsal
+
+on:
+  workflow_dispatch:
+    inputs:
+      capsule-path:
+        description: "Content-addressed publication rehearsal capsule"
+        required: true
+        default: ".buildchain/publication/rehearsal-capsule.json"
+      capsule-root:
+        description: "Repository-relative capsule file root"
+        required: true
+        default: ".buildchain/publication/candidate"
+
+permissions:
+  contents: write
+
+jobs:
+  rehearsal:
+    uses: kungfu-systems/buildchain/.github/workflows/release-tail.yml@${ref}
+    with:
+      buildchain-ref: ${ref}
+      capsule-contract: ${JSON.stringify(PUBLICATION_REHEARSAL_CAPSULE_CONTRACT)}
+      capsule-path: \${{ inputs.capsule-path }}
+      capsule-root: \${{ inputs.capsule-root }}
+      state-path: ".buildchain/publication/rehearsal-state.json"
+      evidence-path: ".buildchain/publication/rehearsal-evidence.json"
+    secrets:
+      http-token: \${{ secrets.BUILDCHAIN_PUBLICATION_HTTP_TOKEN }}
+`;
+}