@kungfu-tech/buildchain 4.0.2-alpha.34 → 4.0.2-alpha.36

package/scripts/binary-publication-evidence.mjs

@@ -0,0 +1,135 @@
+import fs from "node:fs";
+import crypto from "node:crypto";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  SETTLEMENT_ASSET,
+  verifyPublicationSettlement,
+} from "./v4-publication-settlement.mjs";
+import { releaseAssetClient } from "./release-asset-client.mjs";
+
+export async function readBinaryPublicationEvidence({
+  client,
+  repository,
+  tag,
+  sourceSha,
+  attempts = 40,
+  wait = () => new Promise((resolve) => setTimeout(resolve, 15000)),
+}) {
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    let release;
+    try {
+      release = client.release(tag);
+    } catch {
+      /* Tag creation can precede Release creation. */
+    }
+    const assets = release?.assets || [];
+    const settlements = assets.filter(({ name }) => name === SETTLEMENT_ASSET);
+    const passports = assets.filter(
+      ({ name }) => name === "buildchain.release.json",
+    );
+    if (settlements.length > 1 || passports.length > 1)
+      throw new Error("ambiguous immutable publication evidence");
+    if (settlements.length === 1 && passports.length === 1) {
+      const settlement = JSON.parse(client.assetBytes(settlements[0]));
+      const publicPassport = JSON.parse(client.assetBytes(passports[0]));
+      if (
+        settlement.contract !== "buildchain-v4-publication-settlement/v1" ||
+        settlement.release.sourceSha !== sourceSha ||
+        settlement.release.tag !== tag
+      )
+        throw new Error("binary publication settlement identity mismatch");
+      const tagSha = client.json(
+        `repos/${repository}/commits/${encodeURIComponent(tag)}`,
+      ).sha;
+      if (tagSha !== sourceSha)
+        throw new Error("binary source does not match the exact release tag");
+      verifyPublicationSettlement(settlement.documents, {
+        repository,
+        tag,
+        sourceSha,
+        publicPassport,
+      });
+      return settlement;
+    }
+    if (attempt + 1 < attempts) await wait();
+  }
+  throw new Error(
+    "completed v4 publication evidence is not available within the bounded wait",
+  );
+}
+
+export function prepareBinaryAssetPaths({
+  binaryDir,
+  passportDir,
+  outputDir,
+  capabilityPath,
+}) {
+  fs.mkdirSync(outputDir, { recursive: true });
+  const files = [];
+  for (const directory of [binaryDir, passportDir]) {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      if (!entry.isFile()) continue;
+      const source = path.join(directory, entry.name);
+      if (
+        directory === passportDir &&
+        entry.name === "buildchain.release.json"
+      ) {
+        const renamed = path.join(outputDir, "buildchain.binary.release.json");
+        fs.copyFileSync(source, renamed);
+        files.push(renamed);
+      } else files.push(source);
+    }
+  }
+  if (capabilityPath) {
+    const bytes = fs.readFileSync(capabilityPath);
+    const digest = crypto.createHash("sha256").update(bytes).digest("hex");
+    const retained = path.join(
+      outputDir,
+      `buildchain.binary.capability-${digest}.json`,
+    );
+    fs.writeFileSync(retained, bytes);
+    files.push(retained);
+  }
+  return files;
+}
+
+async function main(mode) {
+  const repository = process.env.GITHUB_REPOSITORY;
+  const tag = process.env.RELEASE_TAG;
+  const client = releaseAssetClient(repository);
+  if (mode === "read") {
+    const settlement = await readBinaryPublicationEvidence({
+      client,
+      repository,
+      tag,
+      sourceSha: process.env.SOURCE_SHA,
+    });
+    const directory = ".buildchain/publication-evidence";
+    client.write(`${directory}/${SETTLEMENT_ASSET}`, settlement);
+    client.write(`${directory}/release.json`, {
+      channel: settlement.release.channel,
+    });
+  } else if (mode === "publish") {
+    const release = client.release(tag);
+    const files = prepareBinaryAssetPaths({
+      binaryDir: "dist/binary",
+      passportDir: ".buildchain/release-passport",
+      outputDir: ".buildchain/binary-publication",
+      capabilityPath: ".buildchain/publication-authority/capability.json",
+    });
+    const results = await client.publish(release, files);
+    client.write(".buildchain/binary-publication/readback.json", {
+      repository,
+      tag,
+      assets: results,
+    });
+    console.log(JSON.stringify({ published: results.length, repository, tag }));
+  } else throw new Error(`unknown binary publication mode: ${mode}`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
+  main(process.argv[2]).catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });

package/scripts/check-ci-lane-change-budget.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import crypto from "node:crypto";
+import { projectWorkflowIdentities } from "./workflow-taxonomy.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
@@ -14,7 +15,7 @@ const policyPath = path.join(
   "ci-lane-change-budget.json",
 );
 
-const workflows = fs
+const physicalWorkflows = fs
   .readdirSync(workflowRoot, { withFileTypes: true })
   .filter((entry) => entry.isFile() && /\.(?:yaml|yml)$/u.test(entry.name))
   .map((entry) => {
@@ -26,6 +27,8 @@ const workflows = fs
   })
   .sort((left, right) => left.path.localeCompare(right.path));
 
+const workflows = projectWorkflowIdentities(root, physicalWorkflows);
+
 const policy = JSON.parse(fs.readFileSync(policyPath, "utf8"));
 const baselineRevision = String(policy.baseline?.gitRevision || "").trim();
 if (!/^[0-9a-f]{40}$/u.test(baselineRevision)) {

package/scripts/check-core-mechanism-inventory.mjs

@@ -34,9 +34,10 @@ function registrySurfaceIds(root) {
     (entry) => `cli:${entry.id}`,
   );
   const workflows = loadJson(root, "dist/site/workflow-registry.json");
-  const workflowIds = workflows.workflows.map(
-    (entry) => `workflow:${entry.id}`,
-  );
+  const workflowIds = workflows.workflows.flatMap((entry) => [
+    `workflow:${entry.id}`,
+    ...(entry.taxonomy ? [`workflow:${entry.taxonomy.id}`] : []),
+  ]);
   const actionIds = workflows.actions.map((entry) => `action:${entry.id}`);
   const exports = Object.keys(loadJson(root, "package.json").exports).map(
     (entry) => `export:${entry}`,

package/scripts/check-inventory.mjs

@@ -145,39 +145,39 @@ const requiredPaths = [
   ".buildchain/alpha-contract-lock.json",
   ".buildchain/release-impact.json",
   ".github/actionlint.yaml",
-  ".github/workflows/self-hosted-runner-smoke.yml",
-  ".github/workflows/buildchain-ref-promotion.yml",
-  ".github/workflows/buildchain-candidate-recovery-dogfood-failure.yml",
-  ".github/workflows/release-line-bootstrap.yml",
+  ".github/workflows/self-ops-runner-smoke.yml",
+  ".github/workflows/self-release-promote.yml",
+  ".github/workflows/self-ops-recovery-failure-dogfood.yml",
+  ".github/workflows/self-release-line-open.yml",
   ".github/workflows/release-governance-reconcile.yml",
   ".github/workflows/dev-pr-auto-merge.yml",
-  ".github/workflows/buildchain-dev-delivery.yml",
+  ".github/workflows/self-ops-dev-delivery.yml",
   ".github/workflows/buildchain-patrol.yml",
   ".github/workflows/patrol-daily.yml",
   ".github/workflows/patrol-weekly.yml",
   ".github/workflows/patrol-monthly.yml",
   ".github/workflows/patrol-observed-evidence.yml",
-  ".github/workflows/buildchain-patrol-daily.yml",
-  ".github/workflows/buildchain-patrol-weekly.yml",
-  ".github/workflows/buildchain-patrol-monthly.yml",
-  ".github/workflows/buildchain-alpha-self-dogfood.yml",
+  ".github/workflows/self-ops-patrol-daily.yml",
+  ".github/workflows/self-ops-patrol-weekly.yml",
+  ".github/workflows/self-ops-patrol-monthly.yml",
+  ".github/workflows/self-build-alpha-dogfood.yml",
   ".github/workflows/release-candidate-promote.yml",
   ".github/workflows/.release-candidate-promote.yml",
   ".github/workflows/release-propagation.yml",
-  ".github/workflows/npm-publish.yml",
+  ".github/workflows/self-release-npm-dry-run.yml",
   ".github/workflows/paper-release.yml",
-  ".github/workflows/binary-distribution.yml",
+  ".github/workflows/self-build-binary-distribution.yml",
   ".github/workflows/.binary-release-assets.yml",
-  ".github/workflows/binary-release-assets.yml",
-  ".github/workflows/verify.yml",
+  ".github/workflows/self-release-binary-assets.yml",
+  ".github/workflows/self-build-verify.yml",
   ".github/workflows/.build.yml",
   ".github/workflows/.gate-profile.yml",
   ".github/workflows/.auditable-demo.yml",
   ".github/workflows/.declarative-auditable-demo.yml",
-  ".github/workflows/auditable-demo.yml",
+  ".github/workflows/self-build-demo-dogfood.yml",
   ".github/workflows/build.yml",
-  ".github/workflows/build-surface-fixture.yml",
-  ".github/workflows/candidate-lab.yml",
+  ".github/workflows/self-build-fixture.yml",
+  ".github/workflows/self-build-candidate-lab.yml",
   "fixtures/libnode-shaped/buildchain.toml",
   "fixtures/libnode-shaped/.github/workflows/build.yml",
   "fixtures/libnode-shaped/package.json"
@@ -197,7 +197,7 @@ if (rootPackage.private !== false) {
   throw new Error("root package must be publishable with private=false");
 }
 const selfDogfoodWorkflow = fs.readFileSync(
-  path.join(root, ".github/workflows/buildchain-alpha-self-dogfood.yml"),
+  path.join(root, ".github/workflows/self-build-alpha-dogfood.yml"),
   "utf8",
 );
 const selfDogfoodAlphaLock = JSON.parse(
@@ -285,7 +285,7 @@ const channelPromotionWorkflow = fs.readFileSync(
   "utf8",
 );
 const boundedAlphaRecoveryWorkflow = fs.readFileSync(
-  path.join(root, ".github/workflows/buildchain-ref-promotion-recovery.yml"),
+  path.join(root, ".github/workflows/self-ops-promotion-recovery.yml"),
   "utf8",
 );
 const promotionShellRouting = parsePromotionShellRouting(
@@ -1000,11 +1000,11 @@ for (const requiredSnippet of [
 if (commonJsSourcePattern.test(standaloneBinaryScript)) {
   throw new Error("scripts/build-standalone-binary.mjs must use ESM syntax");
 }
-const npmPublishWorkflow = fs.readFileSync(path.join(root, ".github/workflows/npm-publish.yml"), "utf8");
-const buildchainRefPromotionWorkflow = fs.readFileSync(path.join(root, ".github/workflows/buildchain-ref-promotion.yml"), "utf8");
-const binaryDistributionWorkflow = fs.readFileSync(path.join(root, ".github/workflows/binary-distribution.yml"), "utf8");
+const npmPublishWorkflow = fs.readFileSync(path.join(root, ".github/workflows/self-release-npm-dry-run.yml"), "utf8");
+const buildchainRefPromotionWorkflow = fs.readFileSync(path.join(root, ".github/workflows/self-release-promote.yml"), "utf8");
+const binaryDistributionWorkflow = fs.readFileSync(path.join(root, ".github/workflows/self-build-binary-distribution.yml"), "utf8");
 const binaryReleaseAssetsWorkflow = fs.readFileSync(path.join(root, ".github/workflows/.binary-release-assets.yml"), "utf8");
-const selfHostedRunnerSmokeWorkflow = fs.readFileSync(path.join(root, ".github/workflows/self-hosted-runner-smoke.yml"), "utf8");
+const selfHostedRunnerSmokeWorkflow = fs.readFileSync(path.join(root, ".github/workflows/self-ops-runner-smoke.yml"), "utf8");
 const npmDryRunScript = fs.readFileSync(path.join(root, "scripts/npm-publish-dry-run.mjs"), "utf8");
 const npmPublishTransactionScript = fs.readFileSync(path.join(root, "scripts/npm-publish-transaction.mjs"), "utf8");
 const rootPackageJson = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));

package/scripts/check-v4-floating-consumer-policy-contract.mjs

@@ -80,7 +80,7 @@ function assertPersistedSelectors() {
       const selector = match[2];
       const protectedBootstrap =
         relative ===
-          ".github/workflows/buildchain-ref-promotion-recovery.yml" &&
+          ".github/workflows/self-ops-promotion-recovery.yml" &&
         match[1] === ".github/workflows/.release-candidate-promote.yml" &&
         selector === "alpha/v4/v4.0";
       const isV4 =

package/scripts/check-v4-public-dogfood-contract.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import fs from "node:fs";
+import { readWorkflowTaxonomy, workflowPath } from "./workflow-taxonomy.mjs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -8,7 +9,7 @@ const DEFAULT_ROOT = path.resolve(
   path.dirname(fileURLToPath(import.meta.url)),
   "..",
 );
-const CALLER_PATH = ".github/workflows/v4-public-consumer-dogfood.yml";
+const CALLER_PATH = ".github/workflows/self-build-public-consumer-dogfood.yml";
 const REUSABLE_PATH = ".github/workflows/v4-stage-capsule-canary.yml";
 export const V4_PUBLIC_DOGFOOD_ALPHA_REF = "v4-alpha";
 const PRIVATE_CONSUMER = ["buildchain", "self", "dogfood"].join("-");
@@ -93,10 +94,19 @@ function assertReusableWorkflow(root) {
 
 function assertWorkflowInventory(root) {
   const workflowRoot = path.join(root, ".github/workflows");
+  const taxonomy = readWorkflowTaxonomy(root);
   for (const entry of fs.readdirSync(workflowRoot, { withFileTypes: true })) {
     if (!entry.isFile() || !/\.ya?ml$/u.test(entry.name)) continue;
-    const relative = `.github/workflows/${entry.name}`;
+    let relative = `.github/workflows/${entry.name}`;
     const text = read(root, relative);
+    const canonical = taxonomy?.entries.find(
+      (item) => workflowPath(item) === relative && item.compatibility,
+    );
+    if (canonical) {
+      if (read(root, canonical.compatibility.path) !== text)
+        fail(`${relative} differs from its public compatibility identity`);
+      relative = canonical.compatibility.path;
+    }
     if (
       relative !== REUSABLE_PATH &&
       text.includes("scripts/v4-stage-capsule-qualification.mjs")
@@ -113,11 +123,13 @@ function assertWorkflowInventory(root) {
 }
 
 function assertProtectedVerify(root) {
-  const verify = read(root, ".github/workflows/verify.yml");
+  const verify = read(root, ".github/workflows/self-build-verify.yml");
   for (const required of [
     "needs: stage-capsule-checkpoints",
-    "name: Enforce public consumer-only v4 dogfood",
-    "run: node scripts/check-v4-public-dogfood-contract.mjs",
+    "name: Run declared verify lifecycle (full source tests and generated artifact checks)",
+    "node .buildchain/runtime/bin/buildchain.mjs lifecycle run verify",
+    "run: node scripts/source-verification-evidence.mjs plan",
+    "run: node scripts/source-verification-evidence.mjs seal",
   ])
     if (!verify.includes(required))
       fail(`Verify is missing protected gate ${required}`);
@@ -193,6 +205,7 @@ function assertConsumerLifecycle(root) {
     '[lifecycle.install]\ncommand = "corepack enable pnpm && corepack pnpm@11.7.0 install --frozen-lockfile"',
     '[lifecycle.build]\ncommand = "corepack pnpm@11.7.0 run build && corepack pnpm@11.7.0 run generate:site"',
     "[lifecycle.verify]\ncommands = [",
+    '"corepack pnpm@11.7.0 run check",',
   ])
     if (!lifecycle.includes(declaration))
       fail(

package/scripts/check-v4-release-topology.mjs

@@ -3,6 +3,8 @@
 import assert from "node:assert/strict";
 import crypto from "node:crypto";
 import fs from "node:fs";
+import ts from "typescript";
+import { workflowCompatibilityIdentity } from "./workflow-taxonomy.mjs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
@@ -21,13 +23,35 @@ function read(relative) {
 const LOCAL_MODULE_EXTENSIONS = ["", ".js", ".mjs", ".cjs"];
 const PRIVILEGED_ENTRYPOINTS = [
   "actions/v4-release-candidate-promote/index.js",
+  "scripts/binary-publication-evidence.mjs",
+  "scripts/next-development-review.mjs",
+  "scripts/v4-publication-settlement.mjs",
 ];
 
-function localModuleSpecifiers(source) {
+export function localModuleSpecifiers(source) {
   const specifiers = [];
-  const expression =
-    /(?:\bfrom\s+|\bimport\s*\(\s*|\bimport\s+)["'](\.[^"']+)["']/gu;
-  for (const match of source.matchAll(expression)) specifiers.push(match[1]);
+  const visit = (node) => {
+    let value;
+    if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node))
+      value = node.moduleSpecifier;
+    else if (
+      ts.isCallExpression(node) &&
+      node.expression.kind === ts.SyntaxKind.ImportKeyword
+    )
+      value = node.arguments[0];
+    if (value && ts.isStringLiteral(value) && value.text.startsWith("."))
+      specifiers.push(value.text);
+    ts.forEachChild(node, visit);
+  };
+  visit(
+    ts.createSourceFile(
+      "module.mjs",
+      source,
+      ts.ScriptTarget.Latest,
+      true,
+      ts.ScriptKind.JS,
+    ),
+  );
   return [...new Set(specifiers)].sort();
 }
 
@@ -341,7 +365,12 @@ export function findUnknownV4ReleaseTopology(
 ) {
   const declared = new Set(workflowPaths);
   return allWorkflowPaths
-    .filter((relative) => !declared.has(relative))
+    .filter(
+      (relative) =>
+        !declared.has(
+          workflowCompatibilityIdentity(root, relative, readWorkflow(relative)),
+        ),
+    )
     .filter((relative) => {
       const source = readWorkflow(relative);
       const usesReleaseAuthority = parseYamlUses(source).some(({ value }) =>
@@ -431,7 +460,7 @@ function assertAuthorityClosure(ledger) {
   );
   assert.equal(
     closure.recoveryEntry,
-    ".github/workflows/buildchain-ref-promotion-recovery.yml",
+    ".github/workflows/self-ops-promotion-recovery.yml",
   );
   const engineSurface = [
     ".github/workflows/.release-candidate-promote.yml",

package/scripts/check-v4-runtime-semantic-closure.mjs

@@ -35,7 +35,10 @@ function publicSurfaceIds(root) {
   return new Set([
     ...Object.keys(packageJson.exports || {}).map((id) => `export:${id}`),
     ...(cli.commands || []).map((entry) => `cli:${entry.id}`),
-    ...(workflows.workflows || []).map((entry) => `workflow:${entry.id}`),
+    ...(workflows.workflows || []).flatMap((entry) => [
+      `workflow:${entry.id}`,
+      ...(entry.taxonomy ? [`workflow:${entry.taxonomy.id}`] : []),
+    ]),
     ...(workflows.actions || []).map((entry) => `action:${entry.id}`),
   ]);
 }

package/scripts/check-v4-universal-workflow-bootstrap.mjs

@@ -1,4 +1,5 @@
 import assert from "node:assert/strict";
+import { projectWorkflowIdentities } from "./workflow-taxonomy.mjs";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
@@ -25,16 +26,11 @@ const fileRoot = (relative) =>
     .digest("hex")}`;
 
 const workflowRoot = path.join(root, ".github/workflows");
-const discovered = fs
-  .readdirSync(workflowRoot)
+const discovered = projectWorkflowIdentities(root, fs.readdirSync(workflowRoot)
   .filter((name) => /\.ya?ml$/u.test(name))
-  .map((name) => `.github/workflows/${name}`)
-  .filter((relative) =>
-    /(?:^|\n)\s*workflow_call:\s*(?:\n|$)/u.test(
-      fs.readFileSync(path.join(root, relative), "utf8"),
-    ),
-  )
-  .sort();
+  .map((name) => ({ path: `.github/workflows/${name}`, text: fs.readFileSync(path.join(workflowRoot, name), "utf8") })))
+  .filter((entry) => /(?:^|\n)\s*workflow_call:\s*(?:\n|$)/u.test(entry.text))
+  .map((entry) => entry.path).sort();
 
 assert.equal(
   contract.schema,

package/scripts/check-workflow-taxonomy.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { checkWorkflowTaxonomy } from "./workflow-taxonomy.mjs";
+
+const result = checkWorkflowTaxonomy(process.cwd());
+process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+if (!result.ok) process.exitCode = 1;

package/scripts/generate-channel-build-workflow.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import fs from "node:fs";
+import { writeWorkflowSource } from "./workflow-taxonomy.mjs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { migrateV4UniversalWorkflowFacade } from "./generate-v4-universal-workflow-facades.mjs";
@@ -421,7 +422,7 @@ function main() {
     }
     return;
   }
-  fs.writeFileSync(targetPath, generated);
+  writeWorkflowSource(root, path.relative(root, targetPath), generated);
 }
 
 const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);

package/scripts/generate-channel-promotion-workflow.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import fs from "node:fs";
+import { writeWorkflowSource } from "./workflow-taxonomy.mjs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { migrateV4UniversalWorkflowFacade } from "./generate-v4-universal-workflow-facades.mjs";
@@ -215,9 +216,9 @@ function consumerAdmissionJob() {
         id: policy
         env:
           BUILDCHAIN_CONSUMER_ROOT: .buildchain/consumer
-          BUILDCHAIN_INVOCATION_SOURCE_PATH: \${{ inputs.publication-publisher-workflow-path == '.github/workflows/buildchain-ref-promotion-recovery.yml' && '.github/workflows/release-candidate-promote.yml' || inputs.publication-publisher-workflow-path }}
+          BUILDCHAIN_INVOCATION_SOURCE_PATH: \${{ inputs.publication-publisher-workflow-path == '.github/workflows/self-ops-promotion-recovery.yml' && '.github/workflows/release-candidate-promote.yml' || inputs.publication-publisher-workflow-path }}
           BUILDCHAIN_EXPECTED_INVOCATION_CHANNEL: \${{ needs.resolve-promotion.outputs.channel }}
-          BUILDCHAIN_INVOKED_WORKFLOW: \${{ inputs.publication-publisher-workflow-path == '.github/workflows/buildchain-ref-promotion-recovery.yml' && '.github/workflows/.release-candidate-promote.yml' || '.github/workflows/release-candidate-promote.yml' }}
+          BUILDCHAIN_INVOKED_WORKFLOW: \${{ inputs.publication-publisher-workflow-path == '.github/workflows/self-ops-promotion-recovery.yml' && '.github/workflows/.release-candidate-promote.yml' || '.github/workflows/release-candidate-promote.yml' }}
           BUILDCHAIN_WORKFLOW_SHA: \${{ needs.resolve-promotion.outputs.router-sha }}
           BUILDCHAIN_RUNTIME_SHA: \${{ needs.resolve-promotion.outputs.router-sha }}
           BUILDCHAIN_STABLE_CONTRACT_LOCK_PATH: \${{ inputs.buildchain-stable-contract-lock-path }}
@@ -532,7 +533,7 @@ function main() {
     }
     return;
   }
-  fs.writeFileSync(targetPath, generated);
+  writeWorkflowSource(root, path.relative(root, targetPath), generated);
 }
 
 const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);

package/scripts/generate-site-bundle.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { readWorkflowTaxonomy, workflowPath } from "./workflow-taxonomy.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
@@ -755,9 +756,7 @@ function buildSiteBundle() {
     timestampFieldsParticipateInArtifactDigest: true,
     artifactDigestScope: "npm package dist/site JSON files",
   });
-
   const cliRegistry = createCliRegistry(packageJson);
-
   const manualRegistry = {
     schemaVersion: 1,
     contract: "kungfu-buildchain-agent-manual-registry",
@@ -805,7 +804,6 @@ function buildSiteBundle() {
     ],
     guidance: "Agent consumers should use this registry to find packaged Buildchain manuals before inferring behavior from workflow snippets or release notes.",
   };
-
   const pageRegistry = {
     schemaVersion: 1,
     contract: "kungfu-buildchain-site-page-registry",
@@ -821,14 +819,15 @@ function buildSiteBundle() {
     capabilityGroups: CAPABILITY_GROUPS.map((group) => group.id),
     pages,
   };
-
   const nodeApiRegistry = createSiteNodeApiRegistry({ root, packageJson, nodeApiMeta, sha256File, publicSurfaceLifecycle });
-
+  const taxonomy = readWorkflowTaxonomy(root);
   const workflowRegistry = {
     schemaVersion: 1,
     contract: "kungfu-buildchain-workflow-registry",
     workflowSource: ".github/workflows reverse input enumeration",
     workflows: enumerateWorkflowInputs({ root }).map((entry) => {
+      const classification = taxonomy?.entries.find((item) => workflowPath(item) === entry.path || item.compatibility?.path === entry.path);
+      const semanticId = classification?.id || entry.id;
       const surfaceById = new Map([
         ["build", "channel-build-router"],
         [".build", "reusable-build"],
@@ -878,18 +877,19 @@ function buildSiteBundle() {
         ["engineering-housekeeper-monthly", "preview"],
         ["self-hosted-runner-smoke", "compatibility-fixture"],
       ]);
-      const engineeringHousekeeper = entry.id.startsWith("engineering-housekeeper");
+      const engineeringHousekeeper = semanticId.startsWith("engineering-housekeeper");
       return {
         ...entry,
-        surface: surfaceById.get(entry.id) || (entry.path.includes("/.") ? "reusable-workflow" : "repository-workflow"),
+        ...(classification ? { taxonomy: { id: classification.id, role: classification.role, category: classification.category, purpose: classification.purpose, status: classification.status, canonicalPath: workflowPath(classification), ...(classification.role === "self" && classification.migration ? { contractPath: classification.migration.previousPath } : {}), compatibilityAlias: entry.path !== workflowPath(classification) } } : {}),
+        surface: surfaceById.get(semanticId) || (entry.path.includes("/.") ? "reusable-workflow" : "repository-workflow"),
         capabilityGroup: workflowCapabilityGroup({
-          ...entry,
-          status: statusById.get(entry.id) || "active",
+          ...entry, id: semanticId,
+          status: statusById.get(semanticId) || "active",
         }),
-        status: statusById.get(entry.id) || "active",
+        status: statusById.get(semanticId) || "active",
         ...publicSurfaceLifecycle({
           owner: "buildchain-workflows",
-          maturity: statusById.get(entry.id) || "active",
+          maturity: statusById.get(semanticId) || "active",
           introducedVersion: engineeringHousekeeper ? packageJson.version : undefined,
           nonDuplicationRationale: engineeringHousekeeper
             ? "One reusable policy and evidence boundary owns Engineering Housekeeper execution; scheduled callers contain cadence values only."

package/scripts/generate-v4-universal-workflow-facades.mjs

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import fs from "node:fs";
+import crypto from "node:crypto";
+import { writeWorkflowSource, rewriteRepositoryWorkflowPaths } from "./workflow-taxonomy.mjs";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
@@ -198,11 +200,27 @@ function addRuntimeBootstrapDependencies(source, relative) {
   );
 }
 
+function applyPublicationFacadePatches(source, relative) {
+  const document = JSON.parse(fs.readFileSync(path.join(root,
+    "architecture/v4-publication-facade-patches.json"), "utf8"));
+  const patch = document.facades.find(entry => entry.workflow === relative);
+  if (!patch) return source;
+  const digest = value => crypto.createHash("sha256").update(value).digest("hex");
+  if (digest(source) === patch.afterSha256) return source;
+  if (digest(source) !== patch.beforeSha256) fail(`${relative}: publication facade source drift`);
+  for (const { before, after } of patch.replacements) {
+    if (source.split(before).length !== 2) fail(`${relative}: ambiguous publication patch`);
+    source = source.replace(before, () => after);
+  }
+  if (digest(source) !== patch.afterSha256) fail(`${relative}: publication facade result drift`);
+  return source;
+}
+
 export function migrateV4UniversalWorkflowFacade(source, relative) {
-  return guardCompatibilityJobs(
+  return rewriteRepositoryWorkflowPaths(root, applyPublicationFacadePatches(guardCompatibilityJobs(
     addUniversalInput(addRuntimeBootstrapDependencies(source, relative), relative),
     relative,
-  );
+  ), relative));
 }
 
 function verify(source, relative) {
@@ -402,8 +420,8 @@ function main() {
         "consumer recovery workflow differs from its pre-positioned template",
       );
   } else {
-    fs.writeFileSync(
-      recoveryWorkflowPath,
+    writeWorkflowSource(
+      root, path.relative(root, recoveryWorkflowPath),
       fs.readFileSync(recoveryTemplatePath, "utf8"),
     );
   }
@@ -414,8 +432,8 @@ function main() {
       : fs.readFileSync(target, "utf8");
     if (check) verify(source, relative);
     else
-      fs.writeFileSync(
-        target,
+      writeWorkflowSource(
+        root, relative,
         migrateV4UniversalWorkflowFacade(source, relative),
       );
   }

package/scripts/generate-workflow-taxonomy.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import {
+  readWorkflowTaxonomy,
+  renderWorkflowCatalog,
+  TAXONOMY_DOC,
+  workflowPath,
+  writeWorkflowSource,
+} from "./workflow-taxonomy.mjs";
+
+const root = process.cwd();
+const policy = readWorkflowTaxonomy(root);
+if (!policy) throw new Error("workflow taxonomy is missing");
+for (const entry of policy.entries) {
+  writeWorkflowSource(
+    root,
+    workflowPath(entry),
+    fs.readFileSync(path.join(root, workflowPath(entry)), "utf8"),
+  );
+}
+fs.writeFileSync(path.join(root, TAXONOMY_DOC), renderWorkflowCatalog(policy));
+process.stdout.write(
+  `Generated ${policy.entries.length} canonical workflow declarations and their exact compatibility projections.\n`,
+);