@kungfu-tech/buildchain 4.0.0 → 4.0.1-alpha.2

package/packages/core/v4-runtime-selector-persistence.js

@@ -0,0 +1,228 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+export const V4_RUNTIME_PERSISTENCE_SCAN_CONTRACT =
+  "kungfu-buildchain-v4-runtime-persistence-scan/v1";
+
+const EXACT_SHA = /^[0-9a-f]{40}$/u;
+const TRAIN_V4_REF = /^train\/v4\/v4\.\d+\/[A-Za-z0-9._/-]+$/u;
+const AUTHORITY_V4_REF = /^authority\/v4\/v4\.\d+\/[A-Za-z0-9._/-]+$/u;
+const RUNTIME_SELECTOR =
+  /(?:buildchain[-_. ]?(?:ref|runtime)|runtime[-_. ]?sha|resume[-_. ]?buildchain)/iu;
+const EXACT_SHA_LITERAL = /\b[0-9a-f]{40}\b/giu;
+const EXTERNAL_AUTHORITY = Object.freeze([
+  ["oidc", /(?:id-token\s*:\s*write|oidc)/iu],
+  ["iam", /(?:role-to-assume|aws[-_. ]?(?:role|iam)|\biam\b)/iu],
+  ["repository-variable", /\$\{\{\s*vars\./u],
+  ["secret", /\$\{\{\s*secrets\./u],
+  ["environment", /\$\{\{\s*env\./u],
+]);
+
+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);
+}
+
+function documentRoot(value) {
+  return `sha256:${crypto.createHash("sha256").update(stableJson(value)).digest("hex")}`;
+}
+
+function normalizeRef(value) {
+  return String(value || "")
+    .trim()
+    .replace(/^refs\/(?:heads|tags)\//u, "");
+}
+
+function transientSelector(value) {
+  const normalized = normalizeRef(value);
+  return (
+    EXACT_SHA.test(normalized.toLowerCase()) ||
+    TRAIN_V4_REF.test(normalized) ||
+    AUTHORITY_V4_REF.test(normalized) ||
+    /\$\{\{\s*(?:vars|secrets|env)\./u.test(value)
+  );
+}
+
+function listFiles(rootPath, relative, output) {
+  const directory = path.join(rootPath, relative);
+  if (!fs.existsSync(directory)) return;
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const child = path.join(relative, entry.name);
+    if (entry.isDirectory()) listFiles(rootPath, child, output);
+    else if (entry.isFile() && /\.(?:json|toml|ya?ml)$/u.test(entry.name)) {
+      output.push(child.split(path.sep).join("/"));
+    }
+  }
+}
+
+function inputDefaultFailures(lines, sourcePath) {
+  const failures = [];
+  let current;
+  for (const [index, line] of lines.entries()) {
+    const key = line.match(/^(\s*)([a-z0-9-]+):\s*(?:#.*)?$/u);
+    if (key) {
+      const name = key[2];
+      if (RUNTIME_SELECTOR.test(name))
+        current = { indent: key[1].length, name };
+      else if (current && key[1].length <= current.indent) current = undefined;
+    }
+    if (!current) continue;
+    const defaultMatch = line.match(/^\s*default:\s*(.*?)\s*(?:#.*)?$/u);
+    if (!defaultMatch) continue;
+    const value = defaultMatch[1]
+      .replace(/^(?:["'])(.*)(?:["'])$/u, "$1")
+      .trim();
+    if (transientSelector(value)) {
+      failures.push({
+        code: "persistent-runtime-default",
+        path: sourcePath,
+        line: index + 1,
+        selector: current.name,
+      });
+    }
+  }
+  return failures;
+}
+
+function jsonSelectorFailures(value, sourcePath, trail = []) {
+  if (Array.isArray(value)) {
+    return value.flatMap((entry, index) =>
+      jsonSelectorFailures(entry, sourcePath, [...trail, index]),
+    );
+  }
+  if (!value || typeof value !== "object") return [];
+  return Object.entries(value).flatMap(([key, entry]) => {
+    const entryTrail = [...trail, key];
+    const selected =
+      (RUNTIME_SELECTOR.test(key) ||
+        trail.some((part) => RUNTIME_SELECTOR.test(String(part)))) &&
+      typeof entry === "string" &&
+      transientSelector(entry)
+        ? [
+            {
+              code: "persistent-runtime-json-value",
+              path: sourcePath,
+              jsonPointer: `/${entryTrail.map((part) => String(part).replaceAll("~", "~0").replaceAll("/", "~1")).join("/")}`,
+            },
+          ]
+        : [];
+    return [
+      ...selected,
+      ...jsonSelectorFailures(entry, sourcePath, entryTrail),
+    ];
+  });
+}
+
+function inspectSource({
+  resolvedRoot,
+  sourcePath,
+  files,
+  failures,
+  authorityUsage,
+}) {
+  const file = path.resolve(resolvedRoot, sourcePath);
+  if (!file.startsWith(`${resolvedRoot}${path.sep}`) || !fs.existsSync(file)) {
+    throw new Error(
+      `runtime persistence scan path is missing or escapes root: ${sourcePath}`,
+    );
+  }
+  const text = fs.readFileSync(file, "utf8");
+  const lines = text.split(/\r?\n/u);
+  files.push({ path: sourcePath, digest: documentRoot(text) });
+  failures.push(...inputDefaultFailures(lines, sourcePath));
+  if (sourcePath.endsWith(".json")) {
+    try {
+      failures.push(...jsonSelectorFailures(JSON.parse(text), sourcePath));
+    } catch (error) {
+      failures.push({
+        code: "runtime-selector-json-invalid",
+        path: sourcePath,
+        errorRoot: documentRoot(String(error?.message || error)),
+      });
+    }
+  }
+  for (const [index, line] of lines.entries()) {
+    if (RUNTIME_SELECTOR.test(line)) {
+      for (const match of line.matchAll(EXACT_SHA_LITERAL)) {
+        failures.push({
+          code: "persistent-runtime-exact-sha",
+          path: sourcePath,
+          line: index + 1,
+          selectorRoot: documentRoot(match[0].toLowerCase()),
+        });
+      }
+      if (/\$\{\{\s*(?:vars|secrets|env)\./u.test(line)) {
+        failures.push({
+          code: "persistent-runtime-external-indirection",
+          path: sourcePath,
+          line: index + 1,
+        });
+      }
+    }
+    for (const [authorityClass, pattern] of EXTERNAL_AUTHORITY) {
+      if (pattern.test(line)) {
+        authorityUsage.push({
+          class: authorityClass,
+          path: sourcePath,
+          line: index + 1,
+        });
+      }
+    }
+  }
+}
+
+export function scanV4RuntimeSelectorPersistence({
+  root: callerRoot = process.cwd(),
+  paths = undefined,
+} = {}) {
+  const resolvedRoot = path.resolve(callerRoot);
+  const sourcePaths = [];
+  if (paths) sourcePaths.push(...paths);
+  else {
+    for (const relative of [
+      ".github/workflows",
+      ".github/actions",
+      ".buildchain",
+    ]) {
+      listFiles(resolvedRoot, relative, sourcePaths);
+    }
+  }
+  const excluded = new Set([
+    ".buildchain/contract-lock.json",
+    ".buildchain/alpha-contract-lock.json",
+  ]);
+  const files = [];
+  const failures = [];
+  const authorityUsage = [];
+  for (const sourcePath of [...new Set(sourcePaths)].sort()) {
+    if (!excluded.has(sourcePath)) {
+      inspectSource({
+        resolvedRoot,
+        sourcePath,
+        files,
+        failures,
+        authorityUsage,
+      });
+    }
+  }
+  const payload = {
+    schemaVersion: 1,
+    contract: V4_RUNTIME_PERSISTENCE_SCAN_CONTRACT,
+    status: failures.length === 0 ? "passed" : "rejected",
+    files,
+    authorityUsage: authorityUsage.sort((left, right) =>
+      stableJson(left).localeCompare(stableJson(right)),
+    ),
+    failures: failures.sort((left, right) =>
+      stableJson(left).localeCompare(stableJson(right)),
+    ),
+  };
+  return { ...payload, root: documentRoot(payload) };
+}

package/packages/core/workflow-yaml-contract.js

@@ -263,6 +263,54 @@ export function parseWorkflowCallJobs(text) {
     .filter((job) => job.uses);
 }
 
+function blockScalarIndent(lines, lineIndex, parentIndent) {
+  for (let index = lineIndex + 1; index < lines.length; index += 1) {
+    if (!lines[index].trim()) continue;
+    const indent = indentation(lines[index]);
+    return indent > parentIndent ? indent : null;
+  }
+  return null;
+}
+
+/**
+ * Enumerate semantic `uses` mapping nodes without mistaking shell/heredoc text
+ * inside YAML block scalars for workflow syntax. The returned scalar retains
+ * expression-vs-literal classification used by the reusable-call contract.
+ */
+export function parseYamlUses(text) {
+  const lines = String(text || "").split(/\r?\n/);
+  const uses = [];
+  let block = null;
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    const indent = indentation(line);
+    if (block) {
+      if (!line.trim()) continue;
+      if (indent >= block.contentIndent) continue;
+      block = null;
+    }
+    const mapping = line.match(
+      /^(\s*)(?:-\s+)?([A-Za-z0-9_.-]+):(?:\s*(.*))?$/,
+    );
+    if (!mapping) continue;
+    const value = stripComment(mapping[3] || "");
+    if (/^[>|][+-]?$/.test(value)) {
+      const contentIndent = blockScalarIndent(lines, index, indent);
+      if (contentIndent !== null) block = { contentIndent };
+      continue;
+    }
+    if (mapping[2] !== "uses") continue;
+    uses.push({
+      line: index + 1,
+      column: mapping[1].length + 1,
+      raw: value,
+      scalar: scalar(value),
+      value: unquote(value),
+    });
+  }
+  return uses;
+}
+
 export function parseWorkflowDocument(text) {
   return {
     triggers: parseTriggers(String(text || "").split(/\r?\n/)),

package/scripts/audit-publication-control-plane.mjs

@@ -16,12 +16,21 @@ function flag(name, fallback = "") {
   return index === -1 ? fallback : String(process.argv[index + 1] || "");
 }
 
-function commandJson(command, args, label) {
-  const result = spawnSyncCommand(command, args, {
+function commandJson(command, args, label, { publicReadFallback = false } = {}) {
+  const options = {
     encoding: "utf8",
     timeout: 60_000,
     maxBuffer: GITHUB_JSON_MAX_BUFFER,
-  });
+  };
+  let result = spawnSyncCommand(command, args, options);
+  const fallbackToken = String(process.env.BUILDCHAIN_GITHUB_PUBLIC_READ_TOKEN || "");
+  const primaryToken = String(process.env.GH_TOKEN || process.env.GITHUB_TOKEN || "");
+  if (result.status !== 0 && publicReadFallback && fallbackToken && fallbackToken !== primaryToken) {
+    result = spawnSyncCommand(command, args, {
+      ...options,
+      env: { ...process.env, GH_TOKEN: fallbackToken, GITHUB_TOKEN: fallbackToken },
+    });
+  }
   if (result.status !== 0) {
     const category = /401|E401|unauthorized/i.test(result.stderr) ? "unauthorized" : "unavailable";
     throw new Error(`${label} is ${category}; publication control-plane audit fails closed`);
@@ -33,18 +42,22 @@ function commandJson(command, args, label) {
   }
 }
 
-function githubJson(apiPath, label) {
-  return commandJson("gh", ["api", apiPath, "-H", "Accept: application/vnd.github+json"], label);
+function githubJson(apiPath, label, { publicReadFallback = false } = {}) {
+  return commandJson("gh", ["api", apiPath, "-H", "Accept: application/vnd.github+json"], label, { publicReadFallback });
+}
+
+function githubPublicJson(apiPath, label) {
+  return githubJson(apiPath, label, { publicReadFallback: true });
 }
 
-function githubJsonOptional(apiPath, label, fallback) {
+function githubJsonOptional(apiPath, label, fallback, fallbackPattern = /404|not found/i) {
   const result = spawnSyncCommand("gh", ["api", apiPath, "-H", "Accept: application/vnd.github+json"], {
     encoding: "utf8",
     timeout: 60_000,
     maxBuffer: GITHUB_JSON_MAX_BUFFER,
   });
   if (result.status !== 0) {
-    if (/404|not found/i.test(`${result.stdout}\n${result.stderr}`)) return fallback;
+    if (fallbackPattern.test(`${result.stdout}\n${result.stderr}`)) return fallback;
     const category = /401|403|unauthorized|forbidden/i.test(`${result.stdout}\n${result.stderr}`) ? "unauthorized" : "unavailable";
     throw new Error(`${label} is ${category}; publication control-plane audit fails closed`);
   }
@@ -56,20 +69,7 @@ function githubJsonOptional(apiPath, label, fallback) {
 }
 
 function githubJsonReadLimited(apiPath, label, fallback) {
-  const result = spawnSyncCommand("gh", ["api", apiPath, "-H", "Accept: application/vnd.github+json"], {
-    encoding: "utf8",
-    timeout: 60_000,
-    maxBuffer: GITHUB_JSON_MAX_BUFFER,
-  });
-  if (result.status !== 0) {
-    if (/401|403|404|unauthorized|forbidden|not found/i.test(`${result.stdout}\n${result.stderr}`)) return fallback;
-    throw new Error(`${label} is unavailable; publication control-plane audit fails closed`);
-  }
-  try {
-    return JSON.parse(result.stdout);
-  } catch {
-    throw new Error(`${label} did not return JSON; publication control-plane audit fails closed`);
-  }
+  return githubJsonOptional(apiPath, label, fallback, /401|403|404|unauthorized|forbidden|not found/i);
 }
 
 function rulesetIncludesBranch(ruleset, branch, defaultBranch) {
@@ -218,7 +218,7 @@ function main() {
   if (!repository || !branch) throw new Error("--repository and --branch are required");
 
   const encodedWorkflow = workflowPath.split("/").map(encodeURIComponent).join("/");
-  const workflowFile = githubJson(
+  const workflowFile = githubPublicJson(
     `repos/${workflowRepository}/contents/${encodedWorkflow}${workflowRef ? `?ref=${encodeURIComponent(workflowRef)}` : ""}`,
     "publication workflow source",
   );
@@ -231,8 +231,8 @@ function main() {
     !/^\s*[a-z-]+:\s*write\s*$/m.test(workflowHeader) &&
     !/permissions\s*:\s*write-all/i.test(workflowHeader);
 
-  const repositoryState = githubJson(`repos/${repository}`, "repository metadata");
-  const branchState = githubJson(`repos/${repository}/branches/${encodeURIComponent(branch)}`, "branch summary");
+  const repositoryState = githubPublicJson(`repos/${repository}`, "repository metadata");
+  const branchState = githubPublicJson(`repos/${repository}/branches/${encodeURIComponent(branch)}`, "branch summary");
   const exactTransactionSource = /^[0-9a-f]{40}$/.test(sourceSha);
   const protection = exactTransactionSource
     ? null
@@ -290,7 +290,7 @@ function main() {
     if (!/^[0-9a-f]{40}$/.test(sourceSha)) {
       throw new Error("--source-sha is required when detailed branch policy is not readable");
     }
-    const sourceCommit = githubJson(`repos/${repository}/commits/${sourceSha}`, "source commit");
+    const sourceCommit = githubPublicJson(`repos/${repository}/commits/${sourceSha}`, "source commit");
     const sourceParents = Array.isArray(sourceCommit.parents) ? sourceCommit.parents.map((entry) => String(entry?.sha || "").toLowerCase()) : [];
     const sourceChangedPaths = Array.isArray(sourceCommit.files) ? sourceCommit.files.map((entry) => String(entry?.filename || "")) : [];
     const sourceMessage = String(sourceCommit.commit?.message || "").split("\n", 1)[0];
@@ -305,7 +305,7 @@ function main() {
     const branchHeadSha = String(branchState.commit?.sha || "").toLowerCase();
     const sourceComparison = sourceSha === branchHeadSha
       ? null
-      : githubJson(
+      : githubPublicJson(
         `repos/${repository}/compare/${sourceSha}...${branchHeadSha}`,
         "source protected-branch lineage",
       );
@@ -313,7 +313,7 @@ function main() {
       sourceComparison?.status === "ahead" &&
       String(sourceComparison?.merge_base_commit?.sha || "").toLowerCase() === sourceSha
     );
-    let pullRequests = githubJson(`repos/${repository}/commits/${authorizationSha}/pulls`, "source pull-request lineage");
+    let pullRequests = githubPublicJson(`repos/${repository}/commits/${authorizationSha}/pulls`, "source pull-request lineage");
     let mergedPullRequest = (Array.isArray(pullRequests) ? pullRequests : []).find((entry) =>
       entry?.merged_at &&
       (
@@ -324,7 +324,7 @@ function main() {
       entry.head?.repo?.full_name === repository
     );
     if (!mergedPullRequest && allowReleaseReconciliation) {
-      const packageFile = githubJson(
+      const packageFile = githubPublicJson(
         `repos/${repository}/contents/package.json?ref=${encodeURIComponent(sourceSha)}`,
         "release reconciliation package metadata",
       );
@@ -340,7 +340,7 @@ function main() {
       });
       if (releaseReconciliation.qualifying) {
         authorizationSha = parentSha;
-        pullRequests = githubJson(`repos/${repository}/commits/${authorizationSha}/pulls`, "release parent pull-request lineage");
+        pullRequests = githubPublicJson(`repos/${repository}/commits/${authorizationSha}/pulls`, "release parent pull-request lineage");
         mergedPullRequest = (Array.isArray(pullRequests) ? pullRequests : []).find((entry) =>
           entry?.merged_at &&
           entry.merge_commit_sha === authorizationSha &&
@@ -350,7 +350,7 @@ function main() {
       }
     }
     const reviews = mergedPullRequest
-      ? githubJson(`repos/${repository}/pulls/${mergedPullRequest.number}/reviews?per_page=100`, "source pull-request reviews")
+      ? githubPublicJson(`repos/${repository}/pulls/${mergedPullRequest.number}/reviews?per_page=100`, "source pull-request reviews")
       : [];
     const latestReviews = new Map();
     for (const review of Array.isArray(reviews) ? reviews : []) {
@@ -378,7 +378,7 @@ function main() {
       (prefixedRequiredStatusChecks.length === 1 ? prefixedRequiredStatusChecks[0] : requiredStatusCheck);
     const requiredStatusCheckMatchCount = exactRequiredStatusCheck ? 1 : prefixedRequiredStatusChecks.length;
     const checkRuns = /^[0-9a-f]{40}$/.test(pullRequestHeadSha)
-      ? githubJson(`repos/${repository}/commits/${pullRequestHeadSha}/check-runs?check_name=${encodeURIComponent(resolvedRequiredStatusCheck)}&filter=latest&per_page=100`, "merged pull-request required check runs")
+      ? githubPublicJson(`repos/${repository}/commits/${pullRequestHeadSha}/check-runs?check_name=${encodeURIComponent(resolvedRequiredStatusCheck)}&filter=latest&per_page=100`, "merged pull-request required check runs")
       : { check_runs: [] };
     const requiredCheckSource = (requiredStatusCheckPolicy.checks || []).find((entry) =>
       entry.context === resolvedRequiredStatusCheck

package/scripts/check-inventory.mjs

@@ -1019,7 +1019,7 @@ for (const requiredSnippet of [
   "resume-buildchain-runtime-sha:",
   "github-release: true",
   "release-passport-buildchain-self-kfd: true",
-  'artifact-patterns: "buildchain-package-*"',
+  "artifact-patterns: ${{ startsWith(github.event.workflow_run.head_branch || inputs['target-ref'], 'alpha/') && 'buildchain-package-*' || '' }}",
   "release-passport-impact-json: .buildchain/release-impact.json",
 ]) {
   if (!buildchainRefPromotionWorkflow.includes(requiredSnippet)) {

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

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseYamlUses } from "../packages/core/workflow-yaml-contract.js";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const read = (relative) => fs.readFileSync(path.join(root, relative), "utf8");
+
+function fail(message) {
+  throw new Error(`v4-floating-consumer-policy-contract: ${message}`);
+}
+
+export function workflowJobBlock(source, job) {
+  return (
+    source.match(
+      new RegExp(
+        `^  ${job}:\\n([\\s\\S]*?)(?=^  [a-z0-9_-]+:|(?![\\s\\S]))`,
+        "mu",
+      ),
+    )?.[1] || ""
+  );
+}
+
+export function assertTrustGatedJobs(source, jobs) {
+  for (const job of jobs) {
+    const block = workflowJobBlock(source, job);
+    if (!block.includes("- trust-gate")) {
+      fail(`.build.yml job ${job} is not directly gated by trust-gate`);
+    }
+  }
+}
+
+function jobDependsOn(source, job, dependency) {
+  const block = workflowJobBlock(source, job);
+  return new RegExp(
+    `^    needs:\\s*(?:${dependency}|\\[[^\\]]*\\b${dependency}\\b[^\\]]*\\])\\s*$`,
+    "mu",
+  ).test(block);
+}
+
+function assertOrdered(relative, markers) {
+  const source = read(relative);
+  let cursor = -1;
+  for (const marker of markers) {
+    const next = source.indexOf(marker, cursor + 1);
+    if (next < 0) fail(`${relative} is missing ${marker}`);
+    if (next <= cursor)
+      fail(`${relative} does not enforce ${markers.join(" -> ")}`);
+    cursor = next;
+  }
+}
+
+export function assertPromotionCertificationWiring(source) {
+  for (const marker of [
+    ".buildchain/runtime/promotion-shell/scripts/v4-consumer-policy.mjs certify",
+    '--caller-root "${{ github.workspace }}"',
+    '--stable-lock "${{ inputs.buildchain-stable-contract-lock-path }}"',
+    '--alpha-lock "${{ inputs.buildchain-alpha-contract-lock-path }}"',
+    "release-passport-v4-consumer-policy-certification-root: ${{ steps.v4-policy-certification.outputs.v4-consumer-policy-certification-root }}",
+  ]) {
+    if (!source.includes(marker)) {
+      fail(`promotion certification is missing ${marker}`);
+    }
+  }
+}
+
+function assertPersistedSelectors() {
+  const offenders = [];
+  const workflows = fs
+    .readdirSync(path.join(root, ".github/workflows"))
+    .filter((name) => /\.ya?ml$/u.test(name))
+    .sort();
+  for (const name of workflows) {
+    const relative = `.github/workflows/${name}`;
+    for (const node of parseYamlUses(read(relative))) {
+      const match = node.value.match(
+        /^kungfu-systems\/buildchain\/(.+)@(.+)$/u,
+      );
+      if (!match) continue;
+      const selector = match[2];
+      const isV4 =
+        selector === "v4" ||
+        selector === "v4-alpha" ||
+        /^v4(?:[./-]|$)/u.test(selector) ||
+        /^[0-9a-f]{40}$/iu.test(selector) ||
+        selector.includes("${{");
+      if (isV4 && !["v4", "v4-alpha"].includes(selector)) {
+        offenders.push(`${relative}:${node.line} @${selector}`);
+      }
+    }
+  }
+  if (offenders.length)
+    fail(
+      `persisted v4 selectors must be v4 or v4-alpha: ${offenders.join(", ")}`,
+    );
+}
+
+export function checkV4FloatingConsumerPolicyContract() {
+  const policy = JSON.parse(
+    read("architecture/v4-floating-consumer-policy.json"),
+  );
+  if (policy.contract !== "kungfu-buildchain-v4-floating-consumer-policy/v1") {
+    fail("architecture policy contract is missing");
+  }
+  if (
+    policy.contractLocks?.selectedLockMustBindResolvedWorkflowShell !== true
+  ) {
+    fail("contract lock must bind the visible workflow shell");
+  }
+  assertPersistedSelectors();
+  assertOrdered(".github/workflows/.build.yml", [
+    "Enforce v4 floating consumer policy",
+    "Validate consumer package manager contract",
+  ]);
+  assertTrustGatedJobs(read(".github/workflows/.build.yml"), [
+    "resolve-source",
+    "resolve-contract",
+    "controller-plan",
+    "artifact-transfer",
+    "build-native",
+    "build-linux-container",
+    "summarize",
+  ]);
+  assertOrdered(".github/workflows/publication-artifact.yml", [
+    "Enforce v4 floating consumer policy",
+    "Resolve controller identities",
+    "Install Buildchain runtime dependencies",
+  ]);
+  const stageCanary = read(".github/workflows/v4-stage-capsule-canary.yml");
+  if (
+    !stageCanary.includes("consumer-admission:") ||
+    !stageCanary.includes("needs: consumer-admission")
+  ) {
+    fail(
+      "Stage Capsule qualification is not transitively gated by consumer admission",
+    );
+  }
+  const promotion = read(".github/workflows/release-candidate-promote.yml");
+  if (
+    !promotion.includes("consumer-admission:") ||
+    !jobDependsOn(promotion, "alpha", "consumer-admission") ||
+    !jobDependsOn(promotion, "stable", "consumer-admission")
+  ) {
+    fail(
+      "release candidate promotion is not transitively gated by consumer admission",
+    );
+  }
+  assertPromotionCertificationWiring(
+    read(".github/workflows/.release-candidate-promote.yml"),
+  );
+  for (const [relative, marker] of [
+    ["packages/core/release-candidate.js", "consumerPolicy"],
+    ["packages/core/release-passport.js", "v4ConsumerPolicy"],
+    [
+      "actions/promote-buildchain-ref/action.yml",
+      "release-passport-v4-consumer-policy-certification-json",
+    ],
+    [
+      "actions/promote-buildchain-ref/action.yml",
+      "release-passport-v4-consumer-policy-certification-root",
+    ],
+    [
+      ".github/workflows/.release-candidate-promote.yml",
+      "v4-policy-certification",
+    ],
+  ]) {
+    if (!read(relative).includes(marker)) {
+      fail(
+        `${relative} does not bind v4 consumer policy evidence marker ${marker}`,
+      );
+    }
+  }
+  const agents = read("AGENTS.md");
+  for (const invariant of [
+    "source-persisted exact commit SHA",
+    "matching stable and alpha contract locks",
+    "trusted non-persistent runtime input",
+  ]) {
+    if (!agents.includes(invariant))
+      fail(`AGENTS.md is missing invariant: ${invariant}`);
+  }
+  return { ok: true, entrypoints: policy.scope.publicWorkflowEntrypoints };
+}
+
+if (
+  process.argv[1] &&
+  path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  try {
+    process.stdout.write(
+      `${JSON.stringify(checkV4FloatingConsumerPolicyContract(), null, 2)}\n`,
+    );
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}

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

@@ -10,9 +10,7 @@ const DEFAULT_ROOT = path.resolve(
 );
 const CALLER_PATH = ".github/workflows/v4-public-consumer-dogfood.yml";
 const REUSABLE_PATH = ".github/workflows/v4-stage-capsule-canary.yml";
-export const V4_PUBLIC_DOGFOOD_TRAIN_REF =
-  "train/v4/v4.0/public-consumer-self-dogfood";
-const EXACT_SHA = /^[0-9a-f]{40}$/u;
+export const V4_PUBLIC_DOGFOOD_ALPHA_REF = "v4-alpha";
 const PRIVATE_CONSUMER = ["buildchain", "self", "dogfood"].join("-");
 const PRIVATE_SHADOW = ["kungfu", "shadow"].join("-");
 
@@ -139,13 +137,8 @@ function assertArchitecture(root) {
   );
   const dogfood = architecture.publicConsumerDogfood;
   const validationRef = dogfood?.validationRef;
-  if (
-    validationRef !== V4_PUBLIC_DOGFOOD_TRAIN_REF &&
-    !EXACT_SHA.test(String(validationRef))
-  )
-    fail(
-      "architecture validationRef must be the exact public train or a protected commit SHA",
-    );
+  if (validationRef !== V4_PUBLIC_DOGFOOD_ALPHA_REF)
+    fail("architecture validationRef must use the floating v4-alpha channel");
   const caller = read(root, CALLER_PATH);
   if (caller !== expectedV4PublicDogfoodWorkflow(validationRef))
     fail(`${CALLER_PATH} must remain the exact thin public consumer caller`);
@@ -168,7 +161,7 @@ function assertArchitecture(root) {
     dogfood.relativeOrSelfInvocationAllowed !== false ||
     dogfood.directQualificationInvocationAllowed !== false ||
     dogfood.candidateBranchOverrideAllowed !== false ||
-    dogfood.recursionRecovery !== "public-train-ref-only"
+    dogfood.recursionRecovery !== "floating-selector-with-trusted-runtime-input"
   )
     fail(
       "architecture publicConsumerDogfood contract is incomplete or widened",
@@ -226,6 +219,8 @@ function assertPolicySources(root) {
     "No agent may add or restore a relative/self reusable-workflow call",
     "never solve recursion with an internal exception",
     "scripts/check-v4-public-dogfood-contract.mjs",
+    "source-persisted exact commit SHA",
+    "v4-alpha",
   ])
     if (!agents.includes(invariant))
       fail(`AGENTS.md is missing invariant: ${invariant}`);