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

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/buildchain-cli-help.mjs

@@ -8,6 +8,11 @@ export const BUILDCHAIN_USAGE = `Usage:
   buildchain architecture qualify --authority-revision <git-revision>
                                       [--candidate-revision <git-revision>]
                                       [--cwd <dir>] [--json]
+  buildchain adopter-delivery run --input <json-or-path> [--output <path>]
+  buildchain adopter-delivery verify --input <json-or-path>
+                                      --readback <json-or-path> [--output <path>]
+  buildchain adopter-delivery bootstrap --input <json-or-path> [--output <path>]
+  buildchain adopter-delivery archive --input <json-or-path> [--output <path>]
   buildchain portable-cache plan --manifest <file-or-json> [--output <file>]
                                  [--github-output <file>] [--json]
   buildchain portable-cache receipt --plan <file-or-json> [--matched-key <key>]
@@ -44,6 +49,23 @@ export const BUILDCHAIN_USAGE = `Usage:
   buildchain release-tail init --declaration <json-or-path> [--state <path>]
   buildchain release-tail <status|verify> [--state <path>] [--output <path>]
   buildchain release-tail compat --hooks-json <json-or-path> [--output <path>]
+  buildchain release-tail rehearse --capsule <absolute-path>
+                                      --candidate-root <absolute-path>
+                                      --mode <simulate|replay>
+                                      --state <absolute-path>
+                                      --evidence <absolute-path>
+  buildchain tail-reseal plan --request <request.json> [--output <plan.json>]
+  buildchain tail-reseal admit --request <request.json> [--output <admission.json>]
+  buildchain tail-reseal verify-platform --request <request.json> --platform <id>
+                                      [--artifact-root <dir>] [--mode retained|resealed]
+                                      [--provider-readback-root <sha256:...>]
+                                      [--output <readback.json>]
+  buildchain tail-reseal seal --request <request.json> --plan <plan.json>
+                                      --readbacks <dir> --passport <passport.json>
+                                      --protected-readback-root <sha256:...>
+                                      [--output <receipt.json>]
+  buildchain next-development materialize --input <request.json> [--cwd <dir>]
+                                      [--write] [--output <path>] [--json]
   buildchain github-governance <plan|apply|rollback|protection-policy-plan|ruleset-policy-plan> ...
   buildchain release <inspect|recover|finalize|abort> ...
   buildchain transaction inspect ...
@@ -127,11 +149,20 @@ export const BUILDCHAIN_USAGE = `Usage:
                              [--from-config | --workflow <required-workflow.yml>...] [--cwd <dir>]
                              [--check-response-timeout-minutes <n>]
                              [--max-entries-to-build <n>] [--apply]
-  buildchain dev warrant <submit|select|heartbeat|recover|close|cancel-queued|observe>
+  buildchain dev warrant <submit|select|heartbeat|qualify|recover|close|settle|cancel-queued|observe>
                              --repository <owner/repo> --branch <dev/vN/vN.M>
                              [--execute] [--output <file>] [--json]
-  buildchain dev proof <source|verify-source|classify|replay|integration|verify-integration>
+  buildchain dev authority <migrate|submit|lease-qualification|heartbeat-qualification|complete-qualification|lease-landing|heartbeat-landing|recover|admit-merge-group|settle|observe>
+                             --repository <owner/repo> --branch <dev/vN/vN.M>
+                             [--environment-root <root>] [--qualification-domains <json>]
+                             [--provider-attempt <admitted-attempt.json>]
+                             [--execute] [--output <file>] [--json]
+  buildchain dev proof <source|verify-source|classify|native|verify-native|classify-native|verify-native-reuse|replay|integration|verify-integration>
                              [--output <file>] [--json]
+  buildchain dev two-phase --repository <owner/repo> --branch <dev/vN/vN.M>
+                             --pull-request <n> --expected-head <sha>
+                             --warrant-result <file> --native-command <command>
+                             [--native-proof <file>] [--output <file>] [--json]
   buildchain log <info|warn|error> --event <name> [--phase <phase>]
                  [--component <name>] [--source <name>] [--attribute key=value]...
                  [--path <jsonl>] [--json]
@@ -145,6 +176,14 @@ export const BUILDCHAIN_USAGE = `Usage:
                              [--module-fact <file>]... [--artifact <path>]...
                              [--output <file>] [--json]
   buildchain facts verify [--cwd <dir>] --fact <file> [--json]
+  buildchain facts compatibility project [--cwd <dir>] [--registry <json-or-path>]
+                                      [--output <file>] [--json]
+  buildchain facts compatibility verify [--cwd <dir>] [--registry <json-or-path>] [--json]
+  buildchain facts compatibility query --query <json-or-path>
+                                      [--registry <json-or-path>] [--cwd <dir>] [--json]
+  buildchain facts compatibility query-template --fact-root <sha256:...>
+                                      [--query-id <id>] [--registry <json-or-path>]
+                                      [--cwd <dir>] [--json]
   buildchain kfd ...
   buildchain kfd hub <init|inspect|test|explain> [--cwd <dir>]
                      [--declaration <path>] [--output-dir <path>]

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

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { execFileSync } from "node:child_process";
+import { evaluateCiLaneChangeBudget } from "../packages/core/ci-lane-change-budget.js";
+
+const root = process.cwd();
+const workflowRoot = path.join(root, ".github", "workflows");
+const policyPath = path.join(
+  root,
+  "architecture",
+  "ci-lane-change-budget.json",
+);
+
+const workflows = fs
+  .readdirSync(workflowRoot, { withFileTypes: true })
+  .filter((entry) => entry.isFile() && /\.(?:yaml|yml)$/u.test(entry.name))
+  .map((entry) => {
+    const workflowPath = path.posix.join(".github/workflows", entry.name);
+    return {
+      path: workflowPath,
+      text: fs.readFileSync(path.join(workflowRoot, entry.name), "utf8"),
+    };
+  })
+  .sort((left, right) => left.path.localeCompare(right.path));
+
+const policy = JSON.parse(fs.readFileSync(policyPath, "utf8"));
+const baselineRevision = String(policy.baseline?.gitRevision || "").trim();
+if (!/^[0-9a-f]{40}$/u.test(baselineRevision)) {
+  throw new Error("baseline.gitRevision must be an exact Git commit");
+}
+const embeddedBaselineLanes = policy.baseline?.lanes;
+if (
+  !Array.isArray(embeddedBaselineLanes) ||
+  embeddedBaselineLanes.length === 0
+) {
+  throw new Error("baseline.lanes must contain the exact offline lane set");
+}
+const embeddedLaneSetRoot = `sha256:${crypto
+  .createHash("sha256")
+  .update(`${JSON.stringify(embeddedBaselineLanes)}\n`)
+  .digest("hex")}`;
+if (embeddedLaneSetRoot !== policy.baseline?.laneSetRoot) {
+  throw new Error("baseline laneSetRoot does not match baseline.lanes");
+}
+
+let baselineWorkflows = null;
+try {
+  execFileSync("git", ["cat-file", "-e", `${baselineRevision}^{commit}`], {
+    cwd: root,
+    stdio: "ignore",
+  });
+  const baselinePaths = execFileSync(
+    "git",
+    [
+      "ls-tree",
+      "-r",
+      "--name-only",
+      baselineRevision,
+      "--",
+      ".github/workflows",
+    ],
+    { cwd: root, encoding: "utf8" },
+  )
+    .split(/\r?\n/u)
+    .filter((value) => /\.(?:yaml|yml)$/u.test(value))
+    .sort();
+  baselineWorkflows = baselinePaths.map((workflowPath) => ({
+    path: workflowPath,
+    text: execFileSync("git", ["show", `${baselineRevision}:${workflowPath}`], {
+      cwd: root,
+      encoding: "utf8",
+    }),
+  }));
+} catch {
+  // Shallow and exported source cuts may not contain the pinned commit object.
+  // The content-rooted embedded lane set remains the exact offline authority.
+}
+
+const embeddedEvaluation = evaluateCiLaneChangeBudget({
+  policy,
+  workflows,
+});
+const evaluation = baselineWorkflows
+  ? evaluateCiLaneChangeBudget({ policy, workflows, baselineWorkflows })
+  : embeddedEvaluation;
+if (
+  baselineWorkflows &&
+  (evaluation.baselineLaneCount !== embeddedEvaluation.baselineLaneCount ||
+    JSON.stringify(evaluation.newLanes) !==
+      JSON.stringify(embeddedEvaluation.newLanes))
+) {
+  throw new Error(
+    "embedded baseline lanes do not match the pinned baseline revision",
+  );
+}
+process.stdout.write(`${JSON.stringify(evaluation, null, 2)}\n`);
+if (!evaluation.ok) process.exitCode = 1;

package/scripts/check-inventory.mjs

@@ -54,6 +54,10 @@ const requiredPaths = [
   "packages/core/homebrew.js",
   "packages/core/artifact-verification-envelope.js",
   "packages/core/anchored-version-material.js",
+  "packages/core/next-development-transition.js",
+  "packages/core/next-development-controller.js",
+  "packages/core/next-development-candidate-reservation.js",
+  "packages/core/next-development-projection.js",
   "packages/core/build-facts.js",
   "packages/core/publication-package.js",
   "packages/core/publication-reproducibility.js",
@@ -76,6 +80,8 @@ const requiredPaths = [
   "docs/auditable-demo.md",
   "contracts/auditable-demo-scenario-v1.schema.json",
   "contracts/release-candidate-recovery-v1.schema.json",
+  "contracts/next-development-request-v1.schema.json",
+  "contracts/next-development-transition-v1.schema.json",
   "contracts/auditable-demo-media-profiles-v1.json",
   "contracts/evidence/auditable-demo-web-delivery-v1.json",
   "contracts/evidence/auditable-demo-responsive-web-delivery-v1.json",
@@ -87,10 +93,15 @@ const requiredPaths = [
   "contracts/fixtures/auditable-demo-responsive-web-delivery-v1/public-projection.json",
   "contracts/fixtures/auditable-demo-responsive-web-delivery-v1/scene.json",
   "docs/release-propagation.md",
+  "docs/next-development-transition.md",
   "docs/site-bundle-contract.md",
   "docs/toolkit-observability.md",
   "docs/versioning.md",
   "scripts/release-line-dry-run.mjs",
+  "scripts/next-development-transition.mjs",
+  "scripts/next-development-self-dogfood.mjs",
+  "scripts/next-development-self-dogfood-harness.mjs",
+  "scripts/generate-next-development-guidance.mjs",
   "scripts/reconcile-release-governance.mjs",
   "scripts/buildchain-channel-router.mjs",
   "scripts/generate-channel-build-workflow.mjs",
@@ -1010,16 +1021,16 @@ for (const forbiddenSnippet of [
 for (const requiredSnippet of [
   "id-token: write",
   "actions: write",
-  "uses: ./.github/workflows/.release-candidate-promote.yml",
+  "uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v4-alpha",
   "github.event.workflow_run.event == 'push'",
   "!startsWith(github.event.workflow_run.display_title, 'chore(release): prepare v')",
   "!startsWith(github.event.workflow_run.display_title, 'chore(release): release v')",
   "resume-candidate-run-id:",
   "resume-expected-source-tree:",
   "resume-buildchain-runtime-sha:",
-  "github-release: true",
+  "uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v4",
   "release-passport-buildchain-self-kfd: true",
-  'artifact-patterns: "buildchain-package-*"',
+  "buildchain-channel: alpha",
   "release-passport-impact-json: .buildchain/release-impact.json",
 ]) {
   if (!buildchainRefPromotionWorkflow.includes(requiredSnippet)) {

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

@@ -0,0 +1,217 @@
+#!/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 [
+    "path: .buildchain/runtime/candidate-policy-runtime",
+    "BUILDCHAIN_EXPECTED_RUNTIME_SHA: ${{ steps.v4-policy-caller.outputs.runtime-sha }}",
+    "policy_runtime=.buildchain/runtime",
+    'node "${policy_runtime}/scripts/v4-consumer-policy.mjs" certify',
+    "passport.consumerPolicy?.receipt?.caller?.sourceSha",
+    "path: .buildchain/runtime/policy-caller",
+    '--caller-root "${{ github.workspace }}/.buildchain/runtime/policy-caller"',
+    '--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 protectedBootstrap =
+        relative ===
+          ".github/workflows/buildchain-ref-promotion-recovery.yml" &&
+        match[1] === ".github/workflows/.release-candidate-promote.yml" &&
+        selector === "alpha/v4/v4.0";
+      const isV4 =
+        selector === "v4" ||
+        selector === "v4-alpha" ||
+        /^v4(?:[./-]|$)/u.test(selector) ||
+        /^[0-9a-f]{40}$/iu.test(selector) ||
+        selector.includes("${{");
+      if (
+        (isV4 || protectedBootstrap) &&
+        !["v4", "v4-alpha"].includes(selector) &&
+        !protectedBootstrap
+      ) {
+        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",
+  ]);
+  if (
+    !read(".github/workflows/.build.yml").includes(
+      "BUILDCHAIN_EXPECTED_INVOCATION_CHANNEL: ${{ inputs.buildchain-expected-channel }}",
+    )
+  )
+    fail("channel builds must disambiguate dual-channel caller invocations");
+  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}`);