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

package/packages/core/engineering-housekeeper.js

@@ -0,0 +1,259 @@
+import crypto from "node:crypto";
+
+export const ENGINEERING_HOUSEKEEPER_CONTRACT =
+  "kungfu-buildchain-engineering-housekeeper/v1";
+export const ENGINEERING_HOUSEKEEPER_SCHEMA_VERSION = 1;
+
+export const HOUSEKEEPER_REASON_CODES = Object.freeze({
+  ELIGIBLE_MERGED_BRANCH: "eligible.merged-branch",
+  PROTECTED_BRANCH: "branch.protected",
+  RETAINED_BRANCH: "branch.retained",
+  DEFAULT_BRANCH: "branch.default",
+  TARGET_BRANCH: "branch.target",
+  OPEN_PR_HEAD: "branch.open-pr-head",
+  CROSS_REPOSITORY: "branch.cross-repository",
+  NOT_MERGED: "branch.not-merged",
+  HEAD_ADVANCED: "branch.head-advanced",
+  RENAMED: "branch.renamed",
+  TARGET_ADVANCED: "branch.target-advanced",
+  PERMISSION_DENIED: "branch.permission-denied",
+  PR_ACTIVE: "pull-request.active",
+  PR_STALE_REPORT: "pull-request.stale-report",
+  PR_LABEL_ELIGIBLE: "pull-request.label-eligible",
+  PR_AUTO_CLOSE_DISABLED: "pull-request.auto-close-disabled",
+  PR_FORKED: "pull-request.forked",
+  REPEATED_NO_OP: "replay.already-applied",
+});
+
+export const DEFAULT_HOUSEKEEPER_POLICY = Object.freeze({
+  protectedPatterns: ["dev/**", "alpha/**", "release/**", "publish-gate/**"],
+  retainedPatterns: ["train/**", "authority/**"],
+  pullRequests: Object.freeze({
+    reportStale: true,
+    label: "",
+    autoClose: false,
+  }),
+});
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export function engineeringHousekeeperRoot(value) {
+  return `sha256:${crypto.createHash("sha256").update(stableJson(value)).digest("hex")}`;
+}
+
+function globMatches(pattern, value) {
+  const expression = String(pattern)
+    .split("**")
+    .map((chunk) =>
+      chunk
+        .split("*")
+        .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+        .join("[^/]*"),
+    )
+    .join(".*");
+  return new RegExp(`^${expression}$`).test(value);
+}
+
+function matchesAny(patterns, value) {
+  return [...(patterns || [])].some((pattern) => globMatches(pattern, value));
+}
+
+function normalizePolicy(policy = {}) {
+  return {
+    protectedPatterns: [
+      ...(policy.protectedPatterns ||
+        DEFAULT_HOUSEKEEPER_POLICY.protectedPatterns),
+    ].sort(),
+    retainedPatterns: [
+      ...(policy.retainedPatterns ||
+        DEFAULT_HOUSEKEEPER_POLICY.retainedPatterns),
+    ].sort(),
+    pullRequests: {
+      reportStale: policy.pullRequests?.reportStale !== false,
+      label: String(policy.pullRequests?.label || ""),
+      autoClose: false,
+    },
+  };
+}
+
+function sortedUnique(values) {
+  return [...new Set(values)].sort();
+}
+
+export function classifyHousekeeperBranch(branch, policyInput = {}) {
+  const policy = normalizePolicy(policyInput);
+  const reasons = [];
+  if (branch.isDefault) reasons.push(HOUSEKEEPER_REASON_CODES.DEFAULT_BRANCH);
+  if (branch.name === branch.target?.name)
+    reasons.push(HOUSEKEEPER_REASON_CODES.TARGET_BRANCH);
+  if (
+    branch.isProtected === true ||
+    matchesAny(policy.protectedPatterns, branch.name)
+  )
+    reasons.push(HOUSEKEEPER_REASON_CODES.PROTECTED_BRANCH);
+  if (matchesAny(policy.retainedPatterns, branch.name))
+    reasons.push(HOUSEKEEPER_REASON_CODES.RETAINED_BRANCH);
+  if (branch.sourceRepository && branch.sourceRepository !== branch.repository)
+    reasons.push(HOUSEKEEPER_REASON_CODES.CROSS_REPOSITORY);
+  if ((branch.openPullRequestNumbers || []).length > 0)
+    reasons.push(HOUSEKEEPER_REASON_CODES.OPEN_PR_HEAD);
+  if (branch.ancestry !== "ancestor")
+    reasons.push(HOUSEKEEPER_REASON_CODES.NOT_MERGED);
+  const eligible =
+    reasons.length === 0 &&
+    Boolean(branch.headOid) &&
+    Boolean(branch.target?.headOid);
+  return {
+    kind: "branch",
+    repository: branch.repository,
+    name: branch.name,
+    headOid: branch.headOid,
+    target: { name: branch.target?.name, headOid: branch.target?.headOid },
+    eligible,
+    decision: eligible ? "delete" : "retain",
+    reasonCodes: eligible
+      ? [HOUSEKEEPER_REASON_CODES.ELIGIBLE_MERGED_BRANCH]
+      : sortedUnique(reasons),
+  };
+}
+
+export function classifyHousekeeperPullRequest(pullRequest, policyInput = {}) {
+  const policy = normalizePolicy(policyInput);
+  const active = ["open", "draft"].includes(pullRequest.state);
+  const forked = pullRequest.headRepository !== pullRequest.repository;
+  const stale = active && pullRequest.stale === true;
+  const actions = stale && policy.pullRequests.reportStale ? ["report"] : [];
+  if (stale && policy.pullRequests.label) actions.push("label");
+  const reasons = [HOUSEKEEPER_REASON_CODES.PR_AUTO_CLOSE_DISABLED];
+  if (active) reasons.push(HOUSEKEEPER_REASON_CODES.PR_ACTIVE);
+  if (stale) reasons.push(HOUSEKEEPER_REASON_CODES.PR_STALE_REPORT);
+  if (stale && policy.pullRequests.label)
+    reasons.push(HOUSEKEEPER_REASON_CODES.PR_LABEL_ELIGIBLE);
+  if (forked) reasons.push(HOUSEKEEPER_REASON_CODES.PR_FORKED);
+  return {
+    kind: "pull-request",
+    repository: pullRequest.repository,
+    number: pullRequest.number,
+    headRepository: pullRequest.headRepository,
+    headRef: pullRequest.headRef,
+    headOid: pullRequest.headOid,
+    state: pullRequest.state,
+    actions: actions.sort(),
+    reasonCodes: sortedUnique(reasons),
+  };
+}
+
+export function createEngineeringHousekeeperPlan({
+  repository,
+  target,
+  branches = [],
+  pullRequests = [],
+  policy = {},
+  observedAt,
+}) {
+  const normalizedPolicy = normalizePolicy(policy);
+  const inventory = [
+    ...branches.map((branch) =>
+      classifyHousekeeperBranch(branch, normalizedPolicy),
+    ),
+    ...pullRequests.map((pullRequest) =>
+      classifyHousekeeperPullRequest(pullRequest, normalizedPolicy),
+    ),
+  ].sort((left, right) =>
+    `${left.kind}:${left.name || String(left.number).padStart(12, "0")}`.localeCompare(
+      `${right.kind}:${right.name || String(right.number).padStart(12, "0")}`,
+    ),
+  );
+  const body = {
+    contract: ENGINEERING_HOUSEKEEPER_CONTRACT,
+    schemaVersion: ENGINEERING_HOUSEKEEPER_SCHEMA_VERSION,
+    mode: "plan",
+    repository,
+    target,
+    observedAt,
+    policy: normalizedPolicy,
+    inventory,
+    actions: inventory.flatMap((entry) =>
+      entry.kind === "branch" && entry.eligible
+        ? [
+            {
+              kind: "delete-branch",
+              name: entry.name,
+              expectedHeadOid: entry.headOid,
+              targetName: entry.target.name,
+              expectedTargetHeadOid: entry.target.headOid,
+            },
+          ]
+        : entry.kind === "pull-request"
+          ? entry.actions.map((action) => ({
+              kind: `${action}-pull-request`,
+              number: entry.number,
+              expectedHeadOid: entry.headOid,
+            }))
+          : [],
+    ),
+  };
+  return { ...body, planRoot: engineeringHousekeeperRoot(body) };
+}
+
+export function revalidateHousekeeperBranchAction(
+  action,
+  current,
+  policy = {},
+) {
+  const reasons = [];
+  if (current.name !== action.name)
+    reasons.push(HOUSEKEEPER_REASON_CODES.RENAMED);
+  if (current.headOid !== action.expectedHeadOid)
+    reasons.push(HOUSEKEEPER_REASON_CODES.HEAD_ADVANCED);
+  if (current.target?.headOid !== action.expectedTargetHeadOid)
+    reasons.push(HOUSEKEEPER_REASON_CODES.TARGET_ADVANCED);
+  const classification = classifyHousekeeperBranch(current, policy);
+  if (!classification.eligible) reasons.push(...classification.reasonCodes);
+  return {
+    ok: reasons.length === 0,
+    action,
+    currentHeadOid: current.headOid,
+    currentTargetHeadOid: current.target?.headOid,
+    reasonCodes: sortedUnique(reasons),
+  };
+}
+
+export function createEngineeringHousekeeperReceipt({
+  plan,
+  outcomes,
+  appliedAt,
+}) {
+  const orderedOutcomes = [...outcomes].sort((a, b) =>
+    stableJson(a).localeCompare(stableJson(b)),
+  );
+  const body = {
+    contract: ENGINEERING_HOUSEKEEPER_CONTRACT,
+    schemaVersion: ENGINEERING_HOUSEKEEPER_SCHEMA_VERSION,
+    mode: "receipt",
+    planRoot: plan.planRoot,
+    appliedAt,
+    outcomes: orderedOutcomes,
+  };
+  return { ...body, receiptRoot: engineeringHousekeeperRoot(body) };
+}
+
+export function classifyHousekeeperReplay(plan, priorReceipt) {
+  const alreadyApplied = priorReceipt?.planRoot === plan.planRoot;
+  return {
+    alreadyApplied,
+    action: alreadyApplied ? "no-op" : "apply",
+    reasonCodes: alreadyApplied
+      ? [HOUSEKEEPER_REASON_CODES.REPEATED_NO_OP]
+      : [],
+  };
+}

package/packages/core/index.js

@@ -58,6 +58,45 @@ export {
   writeReleaseTransaction,
 } from "./publish-transaction.js";
 
+export {
+  RELEASE_TAIL_CAPABILITY_REGISTRY,
+  RELEASE_TAIL_DECLARATION_CONTRACT,
+  RELEASE_TAIL_EFFECT_SCHEMA,
+  RELEASE_TAIL_OBSERVATION_SCHEMA,
+  RELEASE_TAIL_RECEIPT_SCHEMA,
+  RELEASE_TAIL_STATES,
+  RELEASE_TAIL_TRANSACTION_POLICY,
+  RELEASE_TAIL_TRANSACTION_SCHEMA,
+  compileReleaseTailDeclaration,
+  createReleaseTailAdapterSet,
+  createReleaseTailTransaction,
+  executeReleaseTailTransaction,
+  parseReleaseTailDeclaration,
+  readReleaseTailTransaction,
+  releaseTailRetryPolicyFromDeclaration,
+  releaseTailRoot,
+  releaseTailStableJson,
+  validateReleaseTailEffectPlan,
+  validateReleaseTailTransaction,
+  writeReleaseTailTransaction,
+} from "./release-tail-provider-plane.js";
+
+export {
+  ReleaseTailProviderError,
+  createActivationReceiptProjectorAdapter,
+  createGitHubReleaseAssetsAdapter,
+  createHttpJsonReadback,
+  createSignedStaticChannelAdapter,
+  createSiteReleaseActivationAdapter,
+  githubReleaseAssetsTargetRoot,
+} from "./release-tail-provider-adapters.js";
+
+export {
+  RELEASE_TAIL_COMPATIBILITY_CONTRACT,
+  RELEASE_TAIL_LEGACY_HOOKS,
+  diagnoseLegacyReleaseTailHooks,
+} from "./release-tail-compatibility.js";
+
 export {
   createPortableDevCachePlan,
   createPortableDevCacheReceipt,
@@ -248,6 +287,9 @@ export {
   verifyGithubGovernanceReceipt,
 } from "./github-governance-authority.js";
 
+export * from "./engineering-housekeeper.js";
+export * from "./engineering-housekeeper-github.js";
+
 export {
   ARTIFACT_PASSPORT_LOCATOR_CONTRACT,
   ARTIFACT_PASSPORT_POINTER_CONTRACT,

package/packages/core/kfd-gate.js

@@ -944,26 +944,49 @@ export function normalizeKfd1ContractWorldWitness(witness, { metadata = resolveK
   };
 }
 
-function resolveArtifactFile({ cwd, artifactRoot, artifacts = [], artifactPath }) {
-  const candidates = [
-    path.resolve(cwd, artifactPath),
-    artifactRoot ? path.resolve(artifactRoot, artifactPath) : "",
-  ].filter(Boolean);
+function indexArtifactSearchRoots({ roots = [], artifactPaths = [] } = {}) {
+  const wanted = [...new Set(artifactPaths.filter(Boolean))];
+  const indexed = new Map();
+  const stack = roots.filter((root) => root && fs.existsSync(root) && fs.statSync(root).isDirectory());
+  while (stack.length > 0) {
+    const current = stack.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const candidate = path.join(current, entry.name);
+      if (entry.isDirectory()) { stack.push(candidate); continue; }
+      if (!entry.isFile()) continue;
+      const normalized = candidate.replace(/\\/g, "/");
+      for (const artifactPath of wanted) {
+        if (normalized === artifactPath || normalized.endsWith(`/${artifactPath}`)) {
+          const candidates = indexed.get(artifactPath) || [];
+          candidates.push(candidate);
+          indexed.set(artifactPath, candidates);
+        }
+      }
+    }
+  }
+  return indexed;
+}
+
+function resolveArtifactFile({ cwd, artifactRoot, artifactIndex = new Map(), artifacts = [], artifactPath, expectedSha256 = "" }) {
+  const candidates = artifactIndex.size > 0
+    ? [...(artifactIndex.get(artifactPath) || []), artifactRoot ? path.resolve(artifactRoot, artifactPath) : "", path.resolve(cwd, artifactPath)]
+    : [path.resolve(cwd, artifactPath), artifactRoot ? path.resolve(artifactRoot, artifactPath) : ""];
   for (const artifact of artifacts) {
     const sourcePath = artifact.sourcePath || artifact.path || "";
-    if (!sourcePath) {
-      continue;
-    }
+    if (!sourcePath) continue;
     const normalizedSource = sourcePath.replace(/\\/g, "/");
-    if (normalizedSource === artifactPath || normalizedSource.endsWith(`/${artifactPath}`)) {
-      candidates.push(path.resolve(sourcePath));
-    }
+    if (normalizedSource === artifactPath || normalizedSource.endsWith(`/${artifactPath}`)) candidates.push(path.resolve(sourcePath));
     const name = artifact.name || artifact.filename || "";
-    if (name && name === artifactPath) {
-      candidates.push(path.resolve(sourcePath));
-    }
+    if (name && name === artifactPath) candidates.push(path.resolve(sourcePath));
   }
-  return candidates.find((candidate) => candidate && fs.existsSync(candidate) && fs.statSync(candidate).isFile()) || "";
+  const existing = [...new Set(candidates)].filter(
+    (candidate) => candidate && fs.existsSync(candidate) && fs.statSync(candidate).isFile(),
+  );
+  if (expectedSha256) {
+    const exact = existing.find((candidate) => sha256File(candidate) === expectedSha256);
+    if (exact) return exact;
+  }
+  return existing[0] || "";
 }
 
 function resolveSourceFile({ cwd, sourcePath }) {
@@ -977,6 +1000,7 @@ function resolveSourceFile({ cwd, sourcePath }) {
 export function createKfd1ReleaseGateEvidence({
   cwd = process.cwd(),
   artifactRoot = "",
+  artifactSearchRoots = [],
   artifacts = [],
   witnesses = [],
   verifiedAt = new Date().toISOString(),
@@ -986,6 +1010,10 @@ export function createKfd1ReleaseGateEvidence({
   if (normalizedWitnesses.length === 0) {
     return undefined;
   }
+  const artifactIndex = indexArtifactSearchRoots({
+    roots: artifactSearchRoots,
+    artifactPaths: normalizedWitnesses.flatMap((witness) => witness.surfaces.map((surface) => surface.artifactPath)),
+  });
   const worlds = normalizedWitnesses.map((witness) => {
     const preBuildWitnessSha256 = sha256Json(witness);
     const sourceResults = witness.surfaces.map((surface) => {
@@ -1025,8 +1053,10 @@ export function createKfd1ReleaseGateEvidence({
       const filePath = resolveArtifactFile({
         cwd,
         artifactRoot,
+        artifactIndex,
         artifacts,
         artifactPath: surface.artifactPath,
+        expectedSha256: surface.expectedSha256,
       });
       if (!filePath) {
         return {

package/packages/core/paper-agent-entry.js

@@ -12,6 +12,7 @@ import {
   stableJson,
   workCheck,
 } from "./paper-repository.js";
+import { mergePublicationRehearsalAgentInstructions } from "./publication-rehearsal-projection.js";
 
 export const PAPER_AGENT_ENTRY_CONTRACT = "kungfu-buildchain-paper-agent-entry";
 export const PAPER_AGENT_ENTRY_SCHEMA_VERSION = 1;
@@ -167,9 +168,11 @@ export function paperAgentEntryFiles({
     [PAPER_PATHS.agentEntry, jsonText(entry)],
     [
       PAPER_PATHS.agentInstructions,
-      mergePaperAgentEntryInstructions(currentAgents, {
-        developmentRef: resolvedDevelopmentRef,
-      }),
+      mergePublicationRehearsalAgentInstructions(
+        mergePaperAgentEntryInstructions(currentAgents, {
+          developmentRef: resolvedDevelopmentRef,
+        }),
+      ),
     ],
   ]);
 }
@@ -205,8 +208,11 @@ function ciContext({ env, developmentRef }) {
     sourceBranch.startsWith(versionStatePrefix) &&
     /^[0-9a-f]{12}$/i.test(sourceBranch.slice(versionStatePrefix.length));
   const branchOk = pullRequest
-    ? (PAPER_WORK_BRANCH_PATTERN.test(sourceBranch) && targetBranch === developmentRef) ||
-      (channelIndex > 0 && sourceBranch === channelBranches[channelIndex - 1]) || generatedVersionState
+    ? (PAPER_WORK_BRANCH_PATTERN.test(sourceBranch) &&
+        targetBranch === developmentRef) ||
+      (channelIndex > 0 &&
+        sourceBranch === channelBranches[channelIndex - 1]) ||
+      generatedVersionState
     : channelBranches.includes(refName);
   return {
     mode: "ci",

package/packages/core/paper-repository.js

@@ -13,6 +13,7 @@ export const PAPER_PATHS = Object.freeze({
   buildWorkflow: ".github/workflows/build.yml",
   verifyWorkflow: ".github/workflows/verify.yml",
   releaseWorkflow: ".github/workflows/paper-release.yml",
+  rehearsalWorkflow: ".github/workflows/publication-rehearsal.yml",
   pnpmWorkspace: "pnpm-workspace.yaml",
   reproducibilityReceipt:
     ".buildchain/publication/reproducibility-receipt.json",

package/packages/core/paper-scaffold-content.js

@@ -1,3 +1,10 @@
+import {
+  PUBLICATION_REHEARSAL_CAPSULE_CONTRACT,
+  PUBLICATION_REHEARSAL_COMMAND,
+  RELEASE_LOCAL_CONSTRUCTIBILITY_ADR,
+  RELEASE_LOCAL_CONSTRUCTIBILITY_INVARIANT,
+} from "./publication-rehearsal-runtime.js";
+
 function jsonText(value) {
   return `${JSON.stringify(value, null, 2)}\n`;
 }
@@ -47,6 +54,7 @@ export function paperPackageScripts(current = {}) {
     "paper:work:start": "buildchain paper work start",
     "paper:work:submit": "buildchain paper work submit",
     "paper:status": "buildchain paper status --json",
+    "publication:rehearse": PUBLICATION_REHEARSAL_COMMAND,
   };
 }
 
@@ -106,6 +114,7 @@ pnpm paper:preflight
 pnpm paper:agent:verify
 pnpm paper:work:start -- <topic>
 pnpm paper:work:submit
+pnpm publication:rehearse
 make pdf
 \`\`\`
 
@@ -114,6 +123,11 @@ 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.
+
+Publication qualification follows the Buildchain
+\`${RELEASE_LOCAL_CONSTRUCTIBILITY_ADR}\` invariant:
+${RELEASE_LOCAL_CONSTRUCTIBILITY_INVARIANT} The capsule contract is
+\`${PUBLICATION_REHEARSAL_CAPSULE_CONTRACT}\`.
 `;
 }
 
@@ -129,10 +143,17 @@ export function scaffoldMap() {
 - \`.github/workflows/build.yml\`: thin read-only build and reproducibility caller.
 - \`.github/workflows/verify.yml\`: thin required check that enforces the Paper entry and acceptance policy.
 - \`.github/workflows/paper-release.yml\`: thin protected sealed-release caller.
+- \`.github/workflows/publication-rehearsal.yml\`: thin hosted adapter over the same local capsule runtime.
 
 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.
+
+The exact local pre-publication command is:
+
+\`\`\`sh
+${PUBLICATION_REHEARSAL_COMMAND}
+\`\`\`
 `;
 }
 

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");