@kungfu-tech/buildchain 4.1.3-alpha.9 → 4.1.4-alpha.0

package/packages/core/release/cli/verification-handlers.mjs

@@ -3,34 +3,14 @@ import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { verifyInfraContractEvidenceBundle } from "../../providers/commands/infra-contract-core.mjs";
 import { verifyBuildchainLogEvents } from "../../observability/logging.js";
+import { verifyReleasePassport } from "../release-passport.js";
+import { verifyPublicationAdmission } from "../../publication/publication-authority.js";
 import {
-  explainReleaseLineDryRun,
-  formatReleaseLineDryRun,
-} from "../release-line-dry-run.js";
-import {
-  planReleaseLineBootstrap,
-  writeReleaseLineBootstrapVersionState,
-} from "../release-line-bootstrap.js";
-import { collectGitHubReleasePassport } from "../passport/collection.js";
-import { explainReleasePassport, verifyReleasePassport } from "../release-passport.js";
-import {
-  createPublicationAdmission,
-  createRunnerProvenance,
-  verifyPublicationAdmission,
-} from "../../publication/publication-authority.js";
-import {
-  createGitHubArtifactAttestationPolicy,
   createGitHubArtifactAttestationVerificationPlan,
   verifyGitHubArtifactAttestationEvidence,
 } from "../../build/github-artifact-attestation.js";
-import {
-  explainArtifactPassport,
-  verifyArtifactPassport,
-} from "../../build/artifact-passport.js";
-import {
-  projectArtifactVerificationEnvelopeToKfx,
-  verifyArtifactVerificationEnvelope,
-} from "../../build/artifact-verification-envelope.js";
+import { verifyArtifactPassport } from "../../build/artifact-passport.js";
+import { verifyArtifactVerificationEnvelope } from "../../build/artifact-verification-envelope.js";
 import {
   artifactEnvelopeOptions,
   printJson,
@@ -38,7 +18,6 @@ import {
   readFlag,
   readJsonInput,
   readRepeatedFlag,
-  writeJsonFile,
 } from "../../contracts/cli/options.mjs";
 
 async function verifyGitHubArtifactAttestationCommand({

package/packages/core/release/next-development-projection.js

@@ -266,19 +266,19 @@ invalid.
 
 ## Public self-dogfood and adoption
 
-\`.github/workflows/self-build-public-consumer-dogfood.yml\` remains the exact thin
-consumer of the public \`public-build-stage-capsule-canary.yml@v4-alpha\` contract. Its
-declared \`lifecycle.verify\` runs \`pnpm run check\`, so the same public path
-executes pure recovery tests that inject a transient durable-state write
-failure, restore the adapter operation on a fresh runner, supersede stale work
-when protected Dev moves, preserve \`pr-pending\` during protected-PR delay, and
-prove both legal version models. No caller-local qualification job, action,
-or private self-dogfood route is added.
-
-The existing dual-channel self-consumer separately retains exact hosted
-\`build.yml@v4-alpha\` and \`build.yml@v4\` runtime evidence. Consumers adopt
-the proved contract through the floating v4 coordinates; exact resolved SHAs
-remain audit evidence and never become durable selectors.
+\`.github/workflows/buildchain.yml\` calls the published
+\`public-ops-pipeline.yml@v4\` entry. Products declare their verification commands
+in schema-2 TOML, including the full repository check on each required platform.
+Next-development preparation, independent review, protected merge and settlement
+remain runtime responsibilities.
+
+\`.github/workflows/buildchain-recover.yml\` calls
+\`public-ops-recover.yml@v4\` with one exact attempt and an optional temporary
+repaired runtime. It preserves completed publication evidence while continuing
+unfinished follow-ups. Both callers use the same generated bytes as external
+consumers. Tool-maintained locks and retained receipts bind exact runtime SHAs.
+Earlier Stage Capsule and channel-build proofs retain their historical source
+identities; they do not define additional current consumer entrypoints.
 
 ## Local adapter
 

package/packages/core/release/passport/locations.js

@@ -1,29 +1,32 @@
 import path from "node:path";
 import fs from "node:fs";
-import { readJsonFile } from "./files.js";
 import https from "node:https";
 import http from "node:http";
 import { nonEmptyString } from "./identity.js";
-export async function resolveSiblingJson(basePath, relativePath) {
+export async function resolveSiblingJson(basePath, relativePath, options) {
   if (!basePath || !relativePath) {
     return undefined;
   }
   if (/^https?:\/\//.test(relativePath)) {
-    return readJsonFromLocation(relativePath);
+    return readJsonFromLocation(relativePath, 0, options);
   }
   if (/^https?:\/\//.test(basePath)) {
-    return readJsonFromLocation(new URL(relativePath, basePath).toString());
+    return readJsonFromLocation(
+      new URL(relativePath, basePath).toString(),
+      0,
+      options,
+    );
   }
   const candidate = path.resolve(path.dirname(basePath), relativePath);
   if (!fs.existsSync(candidate)) {
     return undefined;
   }
-  return readJsonFile(candidate);
+  return readJsonFromLocation(candidate, 0, options);
 }
 export async function readJsonFromLocation(
   location,
   redirectCount = 0,
-  { timeoutMs = 15_000 } = {},
+  { timeoutMs = 15_000, raw = false } = {},
 ) {
   const input = nonEmptyString(location, "location");
   if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
@@ -47,6 +50,7 @@ export async function readJsonFromLocation(
           response.resume();
           readJsonFromLocation(nextLocation, redirectCount + 1, {
             timeoutMs,
+            raw,
           }).then(resolve, reject);
           return;
         }
@@ -64,7 +68,7 @@ export async function readJsonFromLocation(
         });
         response.on("end", () => {
           try {
-            resolve(JSON.parse(body));
+            resolve(raw ? body : JSON.parse(body));
           } catch (error) {
             reject(error);
           }
@@ -78,5 +82,6 @@ export async function readJsonFromLocation(
       request.on("error", reject);
     });
   }
-  return readJsonFile(input);
+  const bytes = fs.readFileSync(input, "utf8");
+  return raw ? bytes : JSON.parse(bytes);
 }

package/packages/core/release/release-passport.js

@@ -1,3 +1,7 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { verifyPublishedDocuments } from "../publication/pipeline/stable-products.js";
 import { resolveReleasePassportVerificationInputs } from "./release-passport-contract.js";
 import { nowIso } from "./passport/identity.js";
 import {
@@ -5,6 +9,56 @@ import {
   resolveSiblingJson,
 } from "./passport/locations.js";
 import { createReleaseCheckReport } from "./passport/report.js";
+
+async function verifyPipelinePassport(location, release, checkedAt, execute) {
+  const directory = fs.mkdtempSync(
+    path.join(fs.realpathSync(os.tmpdir()), "buildchain-passport-"),
+  );
+  const report = {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-release-check-report",
+    checkedAt,
+    verificationScope: "signed-release-metadata",
+    artifactBytesVerified: false,
+    providerStateVerified: false,
+    completeness: { artifactCount: 0 },
+    issues: [],
+  };
+  try {
+    const values = { release };
+    for (const name of ["plan", "qualification", "capsules", "invocation"])
+      values[name] = await resolveSiblingJson(
+        location,
+        `buildchain.${name}.json`,
+      );
+    const bundle = await resolveSiblingJson(
+      location,
+      "buildchain.attestation.json",
+      { raw: true },
+    );
+    verifyPublishedDocuments(values, bundle, {
+      directory,
+      token: process.env.GH_TOKEN || process.env.GITHUB_TOKEN,
+      execute,
+    });
+    report.completeness.artifactCount = values.qualification.artifacts.length;
+    report.source = release.source;
+    report.release = release.release;
+  } catch {
+    report.issues.push({
+      level: "error",
+      code: "pipeline.evidence",
+      message:
+        "Signed release metadata verification failed. Supply all five unchanged companion files and GitHub CLI with attestation verification support.",
+    });
+  } finally {
+    fs.rmSync(directory, { recursive: true, force: true });
+  }
+  report.ok = report.issues.length === 0;
+  report.trust = report.ok ? "pass" : "fail";
+  return report;
+}
+
 export async function verifyReleasePassport({
   passportLocation,
   artifactEvidenceLocation = "",
@@ -17,7 +71,16 @@ export async function verifyReleasePassport({
   kfdAdopterManifestGateLocation = "",
   kfdSupportEvidenceLocation = "",
   checkedAt = nowIso(),
+  execute,
 } = {}) {
+  const passport = await readJsonFromLocation(passportLocation);
+  if (passport?.schema === "kungfu.buildchain.release-passport/v4")
+    return verifyPipelinePassport(
+      passportLocation,
+      passport,
+      checkedAt,
+      execute,
+    );
   const evidence = await resolveReleasePassportVerificationInputs({
     passportLocation,
     locations: {
@@ -34,10 +97,7 @@ export async function verifyReleasePassport({
     readJson: readJsonFromLocation,
     resolveSibling: resolveSiblingJson,
   });
-  return createReleaseCheckReport({
-    ...evidence,
-    checkedAt,
-  });
+  return createReleaseCheckReport({ ...evidence, checkedAt });
 }
 export async function explainReleasePassport({
   passportLocation,
@@ -46,7 +106,9 @@ export async function explainReleasePassport({
   const report = await verifyReleasePassport({ passportLocation });
   const passport = await readJsonFromLocation(passportLocation);
   const nextAction = report.ok
-    ? "install-or-upgrade-after-policy-review"
+    ? report.verificationScope === "signed-release-metadata"
+      ? "verify-artifact-bytes-and-review-policy"
+      : "install-or-upgrade-after-policy-review"
     : "block-release-and-report-verification-failure";
   return {
     schemaVersion: 1,
@@ -54,6 +116,9 @@ export async function explainReleasePassport({
     audience: forAudience,
     release: passport.release,
     trust: report.trust,
+    verificationScope: report.verificationScope,
+    artifactBytesVerified: report.artifactBytesVerified,
+    providerStateVerified: report.providerStateVerified,
     complete: report.ok,
     artifactCount: report.completeness.artifactCount,
     runnerPolicy: passport.runnerPolicy,

package/packages/core/web/cli/badges.mjs

@@ -13,10 +13,6 @@ import {
   printJson,
   readBooleanFlag,
   readFlag,
-  readJsonInput,
-  readRepeatedFlag,
-  readRepeatedJsonInputs,
-  writeJsonFile,
 } from "../../contracts/cli/options.mjs";
 
 export async function runReadmeBadgesCli(args = []) {

package/packages/core/web/publication-admission.js

@@ -56,7 +56,7 @@ export function assembleWebPublicationAdmission({
       "managed web-surface publication requires an ephemeral GitHub-hosted Actions runner",
     );
   }
-  const workflowPath = ".github/workflows/public-release-web.yml";
+  const workflowPath = ".github/workflows/.release-web.yml";
   const publisherWorkflowPath = workflowPath;
   const controlPlaneAudit = createPublicationControlPlaneAudit({
     repository,

package/packages/core/web/publication-capability.js

@@ -36,7 +36,7 @@ export function verifyWebPublicationCapability(request, now = Date.now()) {
   }
   const roleArn = required(request, "roleArn");
   const exact = {
-    workflowPath: ".github/workflows/public-release-web.yml",
+    workflowPath: ".github/workflows/.release-web.yml",
     repository: required(request, "repository"),
     sourceSha: required(request, "sourceSha").toLowerCase(),
     runtimeSha: required(request, "runtimeSha").toLowerCase(),

package/packages/core/web/readme-badges.js

@@ -457,7 +457,7 @@ function normalizePackageRepository(repository) {
 function discoverWorkflowFacts({ cwd, repository, badgeConfig = {} }) {
   const workflowDir = path.join(cwd, ".github", "workflows");
   const configured = normalizeStringArray(badgeConfig.workflows);
-  const defaults = ["verify.yml", "build.yml", "buildchain-ref-promotion.yml"];
+  const defaults = ["verify.yml", ".build-candidate.yml", "buildchain-ref-promotion.yml"];
   const names = configured.length > 0 ? configured : defaults;
   if (!fs.existsSync(workflowDir)) {
     return [];

package/packages/core/workflow/cli/main.mjs

@@ -1,10 +1,7 @@
 import { initializeCliRuntime } from "../../contracts/cli/context.mjs";
 import { BUILDCHAIN_USAGE } from "../commands/buildchain-cli-help.mjs";
 import { formatCliHelp } from "../../contracts/cli-reference.js";
-import {
-  TRUST_RELEASE_COMMANDS,
-  dispatchTrustReleaseCommand,
-} from "../../release/cli/trust-release.mjs";
+import { TRUST_RELEASE_COMMANDS } from "../../release/cli/trust-release.mjs";
 import { dispatchRegisteredCommand } from "../../contracts/command-registry.mjs";
 import { handleAdopterDeliveryCommand } from "../../adoption/cli/dispatch.mjs";
 import { handleKfdCommand } from "../../adoption/cli/kfd.mjs";

package/packages/core/workflow/cli/process.mjs

@@ -1,4 +1,4 @@
-import { spawn, spawnSync } from "node:child_process";
+import { spawnSync } from "node:child_process";
 import path from "node:path";
 import { root } from "../../contracts/cli/context.mjs";
 

package/packages/core/workflow/commands/buildchain-cli-help.mjs

@@ -20,7 +20,7 @@ export const BUILDCHAIN_USAGE = `Usage:
                                     [--cold-fallback-status not-run|passed|failed]
                                     [--output <file>] [--json]
   buildchain candidate timeline --input <file-or-json> [--output <file>] [--json]
-  buildchain init [--cwd <dir>] [--type package|native|web-surface|infra-contract|publication-artifact|anchored-package] [--force]
+  buildchain init [--cwd <dir>] [--type npm|binary|paper|package|native|publication-artifact|anchored-package] [--force]
                   [--package-manager pnpm|npm|yarn] [--runner-preset <preset>]
                   [--artifact-name <name>]
   buildchain validate [--cwd <dir>] [--require-version-state]
@@ -253,7 +253,7 @@ export const BUILDCHAIN_USAGE = `Usage:
                                                    [--output <file>] [--promote]
                                                    [--no-toolchain-pull]
                                                    [--allow-unpinned-toolchain] [--json]
-  buildchain paper scaffold --package <name> --repository <owner/repo> [--write] [--json]
+  buildchain paper scaffold --repository <owner/repo> [--package <name>] [--write] [--json]
   buildchain paper migrate [--cwd <dir>] [--write] [--json]
   buildchain paper work start <topic> [--cwd <dir>] [--branch <branch>] [--execute] [--json]
   buildchain paper work submit [--cwd <dir>] [--title <title>] [--body <body>] [--execute] [--json]
@@ -261,13 +261,7 @@ export const BUILDCHAIN_USAGE = `Usage:
   buildchain paper fleet update [--root <dir>] [--write] [--json]
   buildchain paper agent verify [--cwd <dir>] [--offline] [--json]
   buildchain paper preflight [--cwd <dir>] [--offline] [--json]
-  buildchain paper bootstrap npm [--cwd <dir>] [--execute]
-                                  [--confirm-public-package <name>] [--json]
-  buildchain paper build [--cwd <dir>] [--execute] [--json]
-  buildchain paper alpha [--cwd <dir>] [--source-ref <ref>] [--target-ref <ref>]
-                          [--execute] [--json]
   buildchain paper status [--cwd <dir>] [--json]
-  buildchain paper resume [--cwd <dir>] [--runtime-ref <ref>] [--execute] [--json]
   buildchain release-propagation <plan|write-lock|work|entry|pickup> ...
   buildchain badges readme [--cwd <dir>] [--readme <path>] [--check] [--write] [--json]
   buildchain badges bundle [--cwd <dir>] [--readme <path>] [--claims <csv>] [--check] [--write] [--json]

package/packages/core/workflow/engine/conformance.js

@@ -52,7 +52,7 @@ export function executeBootstrapConformance(
     const source = fs.readFileSync(path.join(runtimeRoot, relative), "utf8");
     if (
       relative !== architecture.bootstrap.publicWorkflow &&
-      !/(?:\.\/)?\.github\/workflows\/public-ops-bootstrap\.yml/u.test(source)
+      !/(?:\.\/)?\.github\/workflows\/\.ops-bootstrap\.yml/u.test(source)
     )
       fail(`candidate Bootstrap facade is not governed: ${relative}`);
   }

package/packages/core/workflow/pipeline/build.js

@@ -3,12 +3,15 @@ import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { bindConsumerSource } from "../../consumer/contract/identity.js";
+import { inspectConsumerContract } from "../../consumer/contract/inspection.js";
+import { validateConsumerWiring } from "../../consumer/contract/local-validation.js";
 import { recordDigest } from "../../release/discussion/envelope.js";
 import { consumerCommandSession } from "../../runtime/consumer-shell.js";
 import { createNativeChildEnvironment } from "../../dev-delivery/native/execution.js";
 
 function inspectTrackedBytes(cwd, tree) {
   const root = fs.realpathSync(cwd);
+  const files = Object.create(null);
   const entries = execFileSync(
     "git",
     ["-C", root, "ls-tree", "-r", "-z", tree],
@@ -48,7 +51,13 @@ function inspectTrackedBytes(cwd, tree) {
       throw new Error(
         `Build tracked source bytes differ from the admitted tree: ${file}`,
       );
+    Object.defineProperty(files, file, {
+      enumerable: true,
+      get: () =>
+        link ? fs.readlinkSync(absolute) : fs.readFileSync(absolute, "utf8"),
+    });
   }
+  return files;
 }
 
 export function inspectPipelineSource(cwd, expected) {
@@ -82,7 +91,18 @@ export function inspectPipelineSource(cwd, expected) {
       "Build source has tracked modifications at its verification boundary",
     );
   // Index flags and local Git filters cannot qualify different product bytes.
-  inspectTrackedBytes(cwd, expected.tree);
+  const files = inspectTrackedBytes(cwd, expected.tree);
+  const { channel } = validateConsumerWiring(cwd, expected.configPath);
+  const inspection = inspectConsumerContract(files, {
+    channel,
+    configPath: expected.configPath,
+  });
+  if (inspection.controlIssues.length)
+    throw new Error(
+      `Consumer control wiring is invalid: ${inspection.controlIssues.join("; ")}`,
+    );
+  // Unresolved product language/tool edges are not a static safety proof.
+  // Execution remains confined to the runtime's read-only product jobs below.
   return plan;
 }
 

package/packages/core/workflow/pipeline/delivery-observation.js

@@ -65,9 +65,13 @@ export async function observePipelineWorker(session, current, queue, host) {
         run,
       };
   }
+  // Retained executions keep the workflow identity that actually produced them.
+  // The old path is read-only evidence, never a new dispatch or consumer alias.
   const entries = (run.referenced_workflows || []).filter((entry) =>
-    entry.path?.startsWith(
-      "kungfu-systems/buildchain/.github/workflows/public-ops-dev-auto-merge.yml@",
+    [".ops-dev-auto-merge.yml", "public-ops-dev-auto-merge.yml"].some((file) =>
+      entry.path?.startsWith(
+        `kungfu-systems/buildchain/.github/workflows/${file}@`,
+      ),
     ),
   );
   if (entries.length !== 1) return null;

package/packages/core/workflow/workflow-taxonomy.mjs

@@ -64,13 +64,12 @@ function validateEntries(policy, errors) {
     if (
       entry.path &&
       !(
-        [".build", "build", "buildchain", "buildchain-recover"].includes(
-          entry.id,
-        ) && entry.path === `.github/workflows/${entry.id}.yml`
+        [".build", "buildchain", "buildchain-recover"].includes(entry.id) &&
+        entry.path === `.github/workflows/${entry.id}.yml`
       )
     )
       errors.push(
-        `${entry.id}: explicit path is reserved for build APIs and the generated consumer pair`,
+        `${entry.id}: explicit path is reserved for the internal build engine and generated consumer pair`,
       );
     const file = workflowPath(entry);
     if (!WORKFLOW.test(file) || paths.has(file))
@@ -82,6 +81,33 @@ function validateEntries(policy, errors) {
       );
     validateEntryOwnership(entry, errors);
   }
+  const publicEntries = policy.entries.filter(
+    (entry) => entry.role === "public",
+  );
+  if (
+    policy.entries
+      .filter((entry) => entry.role === "self")
+      .map((entry) => entry.id)
+      .sort()
+      .join(",") !== "buildchain,buildchain-recover"
+  )
+    errors.push(
+      "repository event roots must be exactly the generated consumer pair",
+    );
+  if (
+    publicEntries.length !== 2 ||
+    ["pipeline", "recover"].some(
+      (purpose) =>
+        !publicEntries.some(
+          (entry) =>
+            entry.id === purpose &&
+            entry.category === "ops" &&
+            entry.purpose === purpose &&
+            entry.invocation === "reusable",
+        ),
+    )
+  )
+    errors.push("consumer public entries must be exactly pipeline and recover");
   return policy.entries;
 }
 
@@ -100,11 +126,9 @@ export function discoverWorkflowFiles(root) {
   return visit(directory).sort();
 }
 
-function validateWorkflow(root, entry, declared, errors) {
+function validateWorkflow(entry, text, declared, errors) {
+  if (typeof text !== "string") return;
   const file = workflowPath(entry),
-    absolute = path.join(root, file);
-  if (!fs.existsSync(absolute) || !fs.lstatSync(absolute).isFile()) return;
-  const text = fs.readFileSync(absolute, "utf8"),
     document = parseWorkflowDocument(text);
   if (
     (entry.invocation === "reusable") !==
@@ -258,23 +282,41 @@ function validateGateIntegration(root, errors) {
 
 export function checkWorkflowTaxonomy(
   root,
-  { integration = true, documentation = true } = {},
+  { integration = true, documentation = true, files } = {},
 ) {
   const errors = [],
-    policy = readWorkflowTaxonomy(root),
+    policy = files
+      ? JSON.parse(files[TAXONOMY_PATH] || "null")
+      : readWorkflowTaxonomy(root),
     entries = validateEntries(policy, errors);
   if (errors.length) return { ok: false, errors };
+  files ??= Object.fromEntries(
+    discoverWorkflowFiles(root).map((file) => {
+      const absolute = path.join(root, file);
+      return [
+        file,
+        fs.lstatSync(absolute).isFile()
+          ? fs.readFileSync(absolute, "utf8")
+          : null,
+      ];
+    }),
+  );
   const declared = new Set(entries.map(workflowPath)),
-    observed = new Set(discoverWorkflowFiles(root));
+    observed = new Set(
+      Object.keys(files).filter((file) =>
+        /^\.github\/workflows\/.*\.ya?ml$/iu.test(file),
+      ),
+    );
   for (const file of observed) {
     if (!declared.has(file)) errors.push(`unregistered workflow: ${file}`);
-    if (!fs.lstatSync(path.join(root, file)).isFile())
+    if (typeof files[file] !== "string")
       errors.push(`workflow must be a regular file: ${file}`);
   }
   for (const file of declared)
     if (!observed.has(file))
       errors.push(`registered workflow missing: ${file}`);
-  for (const entry of entries) validateWorkflow(root, entry, declared, errors);
+  for (const entry of entries)
+    validateWorkflow(entry, files[workflowPath(entry)], declared, errors);
   if (integration) validateGateIntegration(root, errors);
   if (documentation) {
     const file = path.join(root, TAXONOMY_DOC);
@@ -324,9 +366,9 @@ export function renderWorkflowCatalog(policy) {
     "",
     "Generated from `architecture/workflow-taxonomy.json`. Every workflow has one canonical implementation; alternate paths and historical forwarding aliases are rejected.",
     "",
-    "Public workflows own the consumer API. Component workflows own reusable multi-job topology. Self workflows own Buildchain repository automation. Actions own execution steps; JS adapters and Rust/WASM own implementation.",
+    "The two public workflows own normal pipeline execution and exact-attempt recovery. Component workflows are internal runtime implementation, including once-only setup and the dispatch signing service; consumers do not wire these components. Self workflows are the generated consumer pair. Actions own execution steps; JS adapters and Rust/WASM own implementation.",
     "",
-    "Names use `public-<category>-<purpose>.yml`, `.<category>-<purpose>.yml`, and the generated self callers `buildchain.yml` and `buildchain-recover.yml`, with categories `build`, `release`, and `ops`. The primary build API and backbone use `build.yml` and `.build.yml`.",
+    "Names use `public-ops-pipeline.yml`, `public-ops-recover.yml`, internal `.<category>-<purpose>.yml`, and the generated self callers `buildchain.yml` and `buildchain-recover.yml`. Categories are `build`, `release`, and `ops`; the internal build engine retains `.build.yml`.",
     "",
     "Register ownership before adding a workflow. `pnpm run check:workflows` validates source, calls, required CI integration and independent review ownership. `pnpm run generate:workflows` regenerates this catalog.",
     "",
@@ -366,6 +408,8 @@ function validateEntryOwnership(entry, errors) {
     errors.push(`${entry.id}: invalid invocation`);
   if ((entry.role === "self") !== (entry.invocation === "repository"))
     errors.push(`${entry.id}: role and invocation disagree`);
-  if (entry.role === "component" && entry.invocation !== "reusable")
-    errors.push(`${entry.id}: component must be reusable`);
+  if (entry.invocation === "dispatch-service" && entry.role !== "component")
+    errors.push(
+      `${entry.id}: dispatch services must remain internal components`,
+    );
 }

package/scripts/check-code-layout.mjs

@@ -204,6 +204,8 @@ export function inspectPublicActionNodes(actions, publicNodes) {
   const issues = [];
   if (!Array.isArray(publicNodes))
     return ["public Action registry must be an array"];
+  if (publicNodes.length)
+    issues.push("Actions are internal runtime nodes; consumers use pipeline and recovery workflows");
   const known = new Set(
     actions.map((action) => action.directory.replace(/^actions\//u, "")),
   );

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

@@ -34,15 +34,24 @@ function registrySurfaceIds(root) {
     (entry) => `cli:${entry.id}`,
   );
   const workflows = loadJson(root, "dist/site/workflow-registry.json");
-  const workflowIds = workflows.workflows.flatMap((entry) => [
-    `workflow:${entry.id}`,
-    ...(entry.taxonomy ? [`workflow:${entry.taxonomy.id}`] : []),
+  const workflowIds = workflows.workflows.flatMap((entry) =>
+    [entry.id, ...(entry.taxonomy ? [entry.taxonomy.id] : [])].map((id) => [
+      `workflow:${id}`,
+      entry.apiRole === "public" ? "public" : "internal",
+    ]),
+  );
+  const actionIds = workflows.actions.map((entry) => [
+    `action:${entry.id}`,
+    entry.apiRole === "public" ? "public" : "internal",
   ]);
-  const actionIds = workflows.actions.map((entry) => `action:${entry.id}`);
   const exports = Object.keys(loadJson(root, "package.json").exports).map(
     (entry) => `export:${entry}`,
   );
-  return new Set([...cli, ...workflowIds, ...actionIds, ...exports]);
+  return new Map(
+    [...cli, ...exports]
+      .map((id) => [id, "public"])
+      .concat(workflowIds, actionIds),
+  );
 }
 
 function listFiles(root, relativeRoot) {
@@ -99,12 +108,12 @@ function validateOwnership(mechanism, ownedSources, issues) {
 }
 
 function validateSurfaces(mechanism, surfaces, issues) {
-  for (const surface of mechanism.publicSurfaces || []) {
-    if (!surfaces.has(surface))
-      issues.push(
-        `${mechanism.id}: public surface is absent from generated/package registries: ${surface}`,
-      );
-  }
+  for (const role of ["public", "internal"])
+    for (const surface of mechanism[`${role}Surfaces`] || [])
+      if (surfaces.get(surface) !== role)
+        issues.push(
+          `${mechanism.id}: ${role} surface is absent or has a different role in generated/package registries: ${surface}`,
+        );
 }
 
 function validateGitRefStore(root, mechanism, issues) {
@@ -140,12 +149,15 @@ function validateReverseScanReferences(root, reverseScan, issues) {
 function validateSurfaceKinds(inventory, issues) {
   const surfaceKinds = new Set(
     (inventory.mechanisms || []).flatMap((mechanism) =>
-      (mechanism.publicSurfaces || []).map((surface) => surface.split(":")[0]),
+      [
+        ...(mechanism.publicSurfaces || []),
+        ...(mechanism.internalSurfaces || []),
+      ].map((surface) => surface.split(":")[0]),
     ),
   );
   for (const kind of ["action", "cli", "export", "workflow"]) {
     if (!surfaceKinds.has(kind))
-      issues.push(`reverse scan has no ${kind} public surface coverage`);
+      issues.push(`reverse scan has no ${kind} surface coverage`);
   }
   return surfaceKinds;
 }
@@ -329,6 +341,10 @@ function checkCoreMechanismInventory({
       (sum, entry) => sum + entry.publicSurfaces.length,
       0,
     ),
+    internalSurfaces: inventory.mechanisms.reduce(
+      (sum, entry) => sum + (entry.internalSurfaces || []).length,
+      0,
+    ),
     dependencyCycles: inventory.maintainability.dependencyCycles,
     ...reverseScan,
   };