@kungfu-tech/buildchain 3.0.9-alpha.1 → 3.0.9-alpha.11

package/scripts/release-candidate-tail-reseal.mjs

@@ -0,0 +1,426 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const CONTRACT = "kungfu-buildchain-release-candidate-tail-reseal/v1";
+const SHA = /^[0-9a-f]{40}$/u;
+const ROOT = /^sha256:[0-9a-f]{64}$/u;
+const REQUIRED_PLATFORMS = ["linux-arm64", "linux-x64", "macos-arm64", "windows-x64"];
+const REQUIRED_SUCCESS_JOBS = [
+  "build / Linux ARM64",
+  "build / Linux x64",
+  "build / macOS ARM64",
+  "build / Windows x64",
+  "build / Control detached signing Linux ARM64",
+  "build / Control detached signing Linux x64",
+  "build / Control detached signing macOS ARM64",
+  "build / Control detached signing Windows x64",
+  "build / Finalize signed artifact Linux ARM64",
+  "build / Finalize signed artifact Linux x64",
+  "build / Finalize signed artifact Windows x64",
+];
+
+function required(value, label) {
+  const result = String(value ?? "").trim();
+  if (!result) throw new Error(`${label} is required`);
+  return result;
+}
+
+function exactSha(value, label) {
+  const result = required(value, label);
+  if (!SHA.test(result)) throw new Error(`${label} must be an exact lowercase Git SHA`);
+  return result;
+}
+
+function contentRoot(value, label) {
+  const result = required(value, label);
+  if (!ROOT.test(result)) throw new Error(`${label} must be a sha256 content root`);
+  return result;
+}
+
+function integer(value, label) {
+  const result = Number(value);
+  if (!Number.isSafeInteger(result) || result <= 0) throw new Error(`${label} must be a positive integer`);
+  return result;
+}
+
+function object(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object`);
+  return value;
+}
+
+function readJson(file, label = file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    throw new Error(`could not read ${label}: ${error.message}`);
+  }
+}
+
+function writeJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function sha256Json(value) {
+  return `sha256:${crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex")}`;
+}
+
+function sha256File(file) {
+  const hash = crypto.createHash("sha256");
+  const descriptor = fs.openSync(file, "r");
+  const buffer = Buffer.allocUnsafe(1024 * 1024);
+  try {
+    for (;;) {
+      const count = fs.readSync(descriptor, buffer, 0, buffer.length, null);
+      if (count === 0) break;
+      hash.update(buffer.subarray(0, count));
+    }
+  } finally {
+    fs.closeSync(descriptor);
+  }
+  return `sha256:${hash.digest("hex")}`;
+}
+
+function appendOutputs(values) {
+  const output = process.env.GITHUB_OUTPUT;
+  if (!output) return;
+  const lines = [];
+  for (const [name, value] of Object.entries(values)) {
+    const text = String(value ?? "");
+    if (text.includes("\n")) {
+      const marker = `BUILDCHAIN_${crypto.randomBytes(8).toString("hex")}`;
+      lines.push(`${name}<<${marker}\n${text}\n${marker}`);
+    } else {
+      lines.push(`${name}=${text}`);
+    }
+  }
+  fs.appendFileSync(output, `${lines.join("\n")}\n`);
+}
+
+async function githubJson(repository, apiPath, token) {
+  const response = await fetch(`https://api.github.com/repos/${repository}${apiPath}`, {
+    headers: {
+      accept: "application/vnd.github+json",
+      authorization: `Bearer ${required(token, "GITHUB_TOKEN")}`,
+      "x-github-api-version": "2022-11-28",
+    },
+  });
+  if (!response.ok) throw new Error(`GitHub API ${apiPath} failed: HTTP ${response.status}`);
+  return response.json();
+}
+
+async function pagedGithubItems(repository, apiPath, key, token) {
+  const values = [];
+  for (let page = 1; ; page += 1) {
+    const separator = apiPath.includes("?") ? "&" : "?";
+    const response = await githubJson(repository, `${apiPath}${separator}per_page=100&page=${page}`, token);
+    const items = Array.isArray(response?.[key]) ? response[key] : [];
+    values.push(...items);
+    if (items.length < 100) return values;
+  }
+}
+
+export function normalizeTailResealRequest(raw) {
+  const request = object(raw, "tail reseal request");
+  if (request.contract !== CONTRACT) throw new Error(`tail reseal contract must be ${CONTRACT}`);
+  const source = object(request.source, "source");
+  const target = object(request.target, "target");
+  const candidateRuntime = object(request.candidateRuntime, "candidateRuntime");
+  const controller = object(request.consumerController, "consumerController");
+  const failure = object(request.failure, "failure");
+  const authority = object(request.authority, "authority");
+  const platforms = Array.isArray(request.platforms) ? request.platforms : [];
+  if (platforms.length !== REQUIRED_PLATFORMS.length) throw new Error("tail reseal requires exactly four platform bindings");
+  const normalizedPlatforms = platforms.map((entry, index) => {
+    const platform = object(entry, `platforms[${index}]`);
+    return {
+      id: required(platform.id, `platforms[${index}].id`),
+      name: required(platform.name, `platforms[${index}].name`),
+      runner: required(platform.runner, `platforms[${index}].runner`),
+      artifactName: required(platform.artifactName, `platforms[${index}].artifactName`),
+      artifactDigest: contentRoot(platform.artifactDigest, `platforms[${index}].artifactDigest`),
+      manifestArtifactName: required(platform.manifestArtifactName, `platforms[${index}].manifestArtifactName`),
+      manifestArtifactDigest: contentRoot(platform.manifestArtifactDigest, `platforms[${index}].manifestArtifactDigest`),
+      artifactPaths: required(platform.artifactPaths, `platforms[${index}].artifactPaths`),
+    };
+  }).sort((left, right) => left.id.localeCompare(right.id));
+  if (JSON.stringify(normalizedPlatforms.map(({ id }) => id)) !== JSON.stringify([...REQUIRED_PLATFORMS].sort())) {
+    throw new Error(`tail reseal platforms must be ${REQUIRED_PLATFORMS.join(", ")}`);
+  }
+  if (new Set(normalizedPlatforms.flatMap((entry) => [entry.artifactName, entry.manifestArtifactName])).size !== 8) {
+    throw new Error("tail reseal artifact names must be unique");
+  }
+  return {
+    contract: CONTRACT,
+    repository: required(request.repository, "repository"),
+    source: {
+      runId: integer(source.runId, "source.runId"),
+      runAttempt: integer(source.runAttempt, "source.runAttempt"),
+      sha: exactSha(source.sha, "source.sha"),
+      tree: exactSha(source.tree, "source.tree"),
+      workflowFile: required(source.workflowFile, "source.workflowFile").replace(/^\.github\/workflows\//u, ""),
+      workflowName: required(source.workflowName, "source.workflowName"),
+    },
+    target: {
+      channel: required(target.channel, "target.channel"),
+      ref: required(target.ref, "target.ref").replace(/^refs\/heads\//u, ""),
+      baseSha: exactSha(target.baseSha, "target.baseSha"),
+      version: required(target.version, "target.version"),
+    },
+    candidateRuntime: {
+      repository: required(candidateRuntime.repository, "candidateRuntime.repository"),
+      ref: required(candidateRuntime.ref, "candidateRuntime.ref"),
+      sha: exactSha(candidateRuntime.sha, "candidateRuntime.sha"),
+      contractDigest: contentRoot(candidateRuntime.contractDigest, "candidateRuntime.contractDigest"),
+    },
+    consumerController: {
+      repository: required(controller.repository, "consumerController.repository"),
+      sha: exactSha(controller.sha, "consumerController.sha"),
+      tree: exactSha(controller.tree, "consumerController.tree"),
+    },
+    failure: {
+      jobId: integer(failure.jobId, "failure.jobId"),
+      jobName: required(failure.jobName, "failure.jobName"),
+      stepName: required(failure.stepName, "failure.stepName"),
+    },
+    authority: {
+      repository: required(authority.repository, "authority.repository"),
+      runId: integer(authority.runId, "authority.runId"),
+      runtimeSha: exactSha(authority.runtimeSha, "authority.runtimeSha"),
+      resultArtifact: required(authority.resultArtifact, "authority.resultArtifact"),
+      resultArtifactDigest: contentRoot(authority.resultArtifactDigest, "authority.resultArtifactDigest"),
+    },
+    controllerPlanArtifact: required(request.controllerPlanArtifact, "controllerPlanArtifact"),
+    platforms: normalizedPlatforms,
+  };
+}
+
+function exactArtifact(artifacts, name, digest, label) {
+  const matches = artifacts.filter((artifact) => artifact.name === name);
+  if (matches.length !== 1) throw new Error(`${label} must resolve to exactly one retained artifact`);
+  const artifact = matches[0];
+  if (artifact.expired === true) throw new Error(`${label} is expired`);
+  if (artifact.digest !== digest) throw new Error(`${label} digest mismatch`);
+  return artifact;
+}
+
+function validateTailResealEvent({ request, event, repository }) {
+  const allowedActions = new Set(["opened", "synchronize", "reopened", "ready_for_review"]);
+  if (request.repository !== repository) throw new Error("tail reseal repository differs from the caller repository");
+  if (!allowedActions.has(event.action)) {
+    throw new Error(`tail reseal requires a pull_request source event, got ${event.action || "<none>"}`);
+  }
+  if (event.pull_request?.head?.repo?.full_name !== repository) throw new Error("tail reseal rejects fork pull requests");
+  if (event.pull_request?.head?.sha !== request.source.sha) throw new Error("tail reseal source SHA differs from the exact PR head");
+  if (event.pull_request?.base?.ref !== request.target.ref || event.pull_request?.base?.sha !== request.target.baseSha) {
+    throw new Error("tail reseal target ref or frozen base SHA differs from the exact PR event");
+  }
+  if (request.target.channel !== "alpha" || !/^alpha\/v\d+\/v\d+\.\d+$/u.test(request.target.ref)) {
+    throw new Error("tail reseal is limited to an exact Alpha channel");
+  }
+  if (request.candidateRuntime.repository !== "kungfu-systems/buildchain" || request.candidateRuntime.ref !== "v3-alpha") {
+    throw new Error("tail reseal requires the deployed floating v3-alpha candidate contract");
+  }
+  if (request.consumerController.repository !== repository) throw new Error("tail reseal consumer controller must remain in the caller repository");
+}
+
+function validateTailResealRun({ request, run }) {
+  const workflowFile = String(run.path || "").split("@")[0].replace(/^\.github\/workflows\//u, "");
+  const exactRun =
+    Number(run.id) === request.source.runId &&
+    Number(run.run_attempt) === request.source.runAttempt &&
+    run.event === "workflow_dispatch" &&
+    run.status === "completed" &&
+    run.conclusion === "failure" &&
+    run.head_sha === request.source.sha &&
+    workflowFile === request.source.workflowFile &&
+    run.name === request.source.workflowName;
+  if (!exactRun) throw new Error("tail reseal source run is not the exact retained failed Build run");
+}
+
+function validateTailResealJobs({ request, jobs }) {
+  const byName = new Map(jobs.map((job) => [job.name, job]));
+  for (const name of REQUIRED_SUCCESS_JOBS) {
+    if (byName.get(name)?.conclusion !== "success") throw new Error(`tail reseal required source job did not succeed: ${name}`);
+  }
+  const failedJob = jobs.find((job) => Number(job.id) === request.failure.jobId);
+  const failedSteps = (failedJob?.steps || []).filter((step) => step.conclusion === "failure").map((step) => step.name);
+  const exactFailure =
+    failedJob?.name === request.failure.jobName &&
+    failedJob?.conclusion === "failure" &&
+    JSON.stringify(failedSteps) === JSON.stringify([request.failure.stepName]);
+  if (!exactFailure) throw new Error("tail reseal failure boundary differs from the single allowed macOS finalization step");
+  if (request.failure.jobName !== "build / Finalize signed artifact macOS ARM64" || request.failure.stepName !== "Recompute manifest over final signed bytes") {
+    throw new Error("tail reseal only accepts the known macOS finalization blocker");
+  }
+}
+
+function validateTailResealArtifacts({ request, artifacts, authorityRun, authorityArtifacts }) {
+  for (const platform of request.platforms) {
+    exactArtifact(artifacts, platform.artifactName, platform.artifactDigest, `${platform.id} payload`);
+    exactArtifact(artifacts, platform.manifestArtifactName, platform.manifestArtifactDigest, `${platform.id} manifest`);
+  }
+  const controllerPlan = artifacts.filter((artifact) => artifact.name === request.controllerPlanArtifact);
+  if (controllerPlan.length !== 1 || controllerPlan[0].expired === true) throw new Error("tail reseal controller plan artifact is unavailable");
+  if (authorityRun.status !== "completed" || authorityRun.conclusion !== "success") throw new Error("tail reseal signing authority run is not successful");
+  exactArtifact(authorityArtifacts, request.authority.resultArtifact, request.authority.resultArtifactDigest, "macOS signing authority result");
+}
+
+function writeTailResealPlan(request) {
+  const output = path.resolve(process.env.BUILDCHAIN_TAIL_RESEAL_REQUEST_PATH || ".buildchain/tail-reseal/request.json");
+  writeJson(output, request);
+  appendOutputs({
+    enabled: "true",
+    "request-path": path.relative(process.cwd(), output),
+    "request-root": sha256Json(request),
+    "platforms-json": JSON.stringify(request.platforms),
+    "source-run-id": request.source.runId,
+    "source-run-attempt": request.source.runAttempt,
+    "source-sha": request.source.sha,
+    "source-tree": request.source.tree,
+    "target-channel": request.target.channel,
+    "target-ref": request.target.ref,
+    "target-version": request.target.version,
+    "candidate-runtime-ref": request.candidateRuntime.ref,
+    "candidate-runtime-sha": request.candidateRuntime.sha,
+    "candidate-runtime-contract-digest": request.candidateRuntime.contractDigest,
+    "consumer-controller-sha": request.consumerController.sha,
+    "authority-run-id": request.authority.runId,
+    "authority-result-artifact": request.authority.resultArtifact,
+    "controller-plan-artifact": request.controllerPlanArtifact,
+  });
+}
+
+async function plan() {
+  const token = required(process.env.GITHUB_TOKEN, "GITHUB_TOKEN");
+  const raw = required(process.env.BUILDCHAIN_TAIL_RESEAL_REQUEST_JSON, "BUILDCHAIN_TAIL_RESEAL_REQUEST_JSON");
+  const request = normalizeTailResealRequest(JSON.parse(raw));
+  const event = readJson(required(process.env.GITHUB_EVENT_PATH, "GITHUB_EVENT_PATH"), "GitHub event");
+  const repository = required(process.env.GITHUB_REPOSITORY, "GITHUB_REPOSITORY");
+  validateTailResealEvent({ request, event, repository });
+
+  const [sourceCommit, controllerCommit, run, jobs, artifacts, authorityRun, authorityArtifacts] = await Promise.all([
+    githubJson(repository, `/git/commits/${request.source.sha}`, token),
+    githubJson(repository, `/git/commits/${request.consumerController.sha}`, token),
+    githubJson(repository, `/actions/runs/${request.source.runId}`, token),
+    pagedGithubItems(repository, `/actions/runs/${request.source.runId}/jobs?filter=latest`, "jobs", token),
+    pagedGithubItems(repository, `/actions/runs/${request.source.runId}/artifacts`, "artifacts", token),
+    githubJson(request.authority.repository, `/actions/runs/${request.authority.runId}`, token),
+    pagedGithubItems(request.authority.repository, `/actions/runs/${request.authority.runId}/artifacts`, "artifacts", token),
+  ]);
+  if (sourceCommit.tree?.sha !== request.source.tree) throw new Error("tail reseal source tree mismatch");
+  if (controllerCommit.tree?.sha !== request.consumerController.tree) throw new Error("tail reseal consumer controller tree mismatch");
+  validateTailResealRun({ request, run });
+  validateTailResealJobs({ request, jobs });
+  validateTailResealArtifacts({ request, artifacts, authorityRun, authorityArtifacts });
+  writeTailResealPlan(request);
+  return request;
+}
+
+function locateManifest(root, platformId) {
+  const matches = [];
+  const visit = (directory) => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const absolute = path.join(directory, entry.name);
+      if (entry.isDirectory()) visit(absolute);
+      else if (entry.name === "manifest.json") {
+        const value = readJson(absolute);
+        if (value?.contract === "kungfu-buildchain-artifact" && value?.platform?.id === platformId) matches.push({ absolute, value });
+      }
+    }
+  };
+  visit(root);
+  if (matches.length !== 1) throw new Error(`expected exactly one ${platformId} platform manifest under ${root}, found ${matches.length}`);
+  return matches[0];
+}
+
+export function verifyTailResealPlatform() {
+  const request = normalizeTailResealRequest(readJson(required(process.env.BUILDCHAIN_TAIL_RESEAL_REQUEST_PATH, "BUILDCHAIN_TAIL_RESEAL_REQUEST_PATH")));
+  const platformId = required(process.env.BUILDCHAIN_TAIL_RESEAL_PLATFORM_ID, "BUILDCHAIN_TAIL_RESEAL_PLATFORM_ID");
+  const platform = request.platforms.find((entry) => entry.id === platformId);
+  if (!platform) throw new Error(`tail reseal request does not bind platform ${platformId}`);
+  const root = path.resolve(process.env.BUILDCHAIN_TAIL_RESEAL_ARTIFACT_ROOT || ".");
+  const { absolute, value: manifest } = locateManifest(root, platformId);
+  if (manifest.artifactName !== platform.artifactName) throw new Error(`${platformId} manifest artifact name mismatch`);
+  if (manifest.git?.repository !== request.repository || manifest.git?.sha !== request.source.sha) throw new Error(`${platformId} manifest source mismatch`);
+  if (String(manifest.git?.runId || "") !== String(request.source.runId) || String(manifest.git?.runAttempt || "") !== String(request.source.runAttempt)) {
+    throw new Error(`${platformId} manifest original run mismatch`);
+  }
+  const files = Array.isArray(manifest.files) ? manifest.files : [];
+  if (files.length === 0) throw new Error(`${platformId} manifest has no files`);
+  for (const file of files) {
+    const relative = required(file.path || file.name, `${platformId} manifest file path`);
+    const absoluteFile = path.resolve(root, relative);
+    if (!absoluteFile.startsWith(`${root}${path.sep}`) || !fs.existsSync(absoluteFile) || !fs.statSync(absoluteFile).isFile()) {
+      throw new Error(`${platformId} manifest file is missing: ${relative}`);
+    }
+    if (Number(file.size ?? file.bytes) !== fs.statSync(absoluteFile).size) throw new Error(`${platformId} manifest file size mismatch: ${relative}`);
+    const expected = contentRoot(`sha256:${String(file.sha256 || "").replace(/^sha256:/u, "")}`, `${platformId} ${relative} digest`);
+    if (sha256File(absoluteFile) !== expected) throw new Error(`${platformId} manifest file digest mismatch: ${relative}`);
+  }
+  appendOutputs({ "manifest-path": path.relative(process.cwd(), absolute), "manifest-root": sha256File(absolute) });
+  return manifest;
+}
+
+export function sealTailResealReceipt() {
+  const request = normalizeTailResealRequest(readJson(required(process.env.BUILDCHAIN_TAIL_RESEAL_REQUEST_PATH, "BUILDCHAIN_TAIL_RESEAL_REQUEST_PATH")));
+  const manifestsRoot = path.resolve(required(process.env.BUILDCHAIN_TAIL_RESEAL_MANIFESTS_ROOT, "BUILDCHAIN_TAIL_RESEAL_MANIFESTS_ROOT"));
+  const manifests = request.platforms.map((platform) => {
+    const { absolute, value } = locateManifest(manifestsRoot, platform.id);
+    if (value.artifactName !== platform.artifactName || value.git?.sha !== request.source.sha) throw new Error(`${platform.id} resealed manifest identity mismatch`);
+    return { platformId: platform.id, artifactName: platform.artifactName, manifestRoot: sha256File(absolute) };
+  });
+  const receipt = {
+    contract: CONTRACT,
+    action: "reused-tail-reseal",
+    repository: request.repository,
+    source: request.source,
+    target: request.target,
+    candidateRuntime: request.candidateRuntime,
+    recoveryTooling: {
+      ref: required(process.env.BUILDCHAIN_TAIL_RESEAL_TOOLING_REF, "BUILDCHAIN_TAIL_RESEAL_TOOLING_REF"),
+      sha: exactSha(process.env.BUILDCHAIN_TAIL_RESEAL_TOOLING_SHA, "BUILDCHAIN_TAIL_RESEAL_TOOLING_SHA"),
+    },
+    consumerController: request.consumerController,
+    originalFailure: request.failure,
+    signingAuthority: request.authority,
+    artifacts: request.platforms.map(({ id, artifactName, artifactDigest, manifestArtifactName, manifestArtifactDigest }) => ({
+      platformId: id,
+      artifactName,
+      originalArtifactDigest: artifactDigest,
+      manifestArtifactName,
+      originalManifestArtifactDigest: manifestArtifactDigest,
+    })),
+    resealedManifests: manifests,
+    skippedStages: ["install", "build", "verify", "platform-matrix"],
+    rerunStages: ["macos-signing-finalization", "aggregate", "candidate-passport"],
+    payloadPolicy: "reuse-exact-platform-bytes-except-authoritative-macos-signing-import",
+    currentRun: {
+      id: required(process.env.GITHUB_RUN_ID, "GITHUB_RUN_ID"),
+      attempt: required(process.env.GITHUB_RUN_ATTEMPT, "GITHUB_RUN_ATTEMPT"),
+    },
+  };
+  receipt.root = sha256Json(receipt);
+  const output = path.resolve(process.env.BUILDCHAIN_TAIL_RESEAL_RECEIPT_PATH || ".buildchain/tail-reseal/receipt.json");
+  writeJson(output, receipt);
+  appendOutputs({ "receipt-path": path.relative(process.cwd(), output), "receipt-root": receipt.root, "receipt-json": JSON.stringify(receipt) });
+  return receipt;
+}
+
+export async function releaseCandidateTailResealCli(argv = process.argv.slice(2)) {
+  const command = argv[0];
+  if (command === "plan") return plan();
+  if (command === "verify-platform") return verifyTailResealPlatform();
+  if (command === "seal") return sealTailResealReceipt();
+  throw new Error("usage: release-candidate-tail-reseal.mjs <plan|verify-platform|seal>");
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  releaseCandidateTailResealCli().catch((error) => {
+    console.error(`::error::${String(error.message || error).replace(/\r?\n/gu, "%0A")}`);
+    process.exitCode = 1;
+  });
+}

package/scripts/seal-artifact-signing-requests.mjs

@@ -275,16 +275,19 @@ export function sealArtifactSigningRequests({
   sourceTreeSha = process.env.BUILDCHAIN_SOURCE_TREE_SHA,
   runtimeSha = process.env.BUILDCHAIN_RUNTIME_SHA,
   platformId = process.env.BUILDCHAIN_PLATFORM_ID,
+  requestsEnabled = process.env.BUILDCHAIN_SIGNING_REQUESTS_ENABLED !== "false",
 } = {}) {
   const resolvedWorkspace = path.resolve(workspace);
   const resolvedCwd = path.resolve(resolvedWorkspace, cwd);
   assertInside(resolvedWorkspace, resolvedCwd, "signing working directory");
   const loaded = loadBuildchainConfig(resolvedCwd);
   const declarations = loaded?.config?.signing?.artifacts || [];
-  const selected = declarations.filter(
-    (entry) =>
-      entry.platforms.length === 0 || entry.platforms.includes(platformId),
-  );
+  const selected = requestsEnabled
+    ? declarations.filter(
+        (entry) =>
+          entry.platforms.length === 0 || entry.platforms.includes(platformId),
+      )
+    : [];
   const resolvedOutputRoot = path.resolve(resolvedWorkspace, outputRoot);
   assertInside(resolvedWorkspace, resolvedOutputRoot, "signing request output");
   if (selected.length === 0) {

package/scripts/site-capability-metadata.mjs

@@ -92,6 +92,17 @@ export function cliCommandMeta(id) {
     "kfd-upstream-roles": { group: "kfd-trust", purpose: "List Buildchain-managed KFD upstream role values and inference policy." },
     lifecycle: { group: "reusable-build", purpose: "Run configured lifecycle commands and write deterministic artifact manifests." },
     dev: { group: "governance-versioning", purpose: "Inspect protected development-channel governance command families." },
+    "dev-authority-admit-merge-group": { group: "governance-versioning", purpose: "Verify that one exact candidate holds the exclusive Landing Warrant before merge_group admission." },
+    "dev-authority-complete-qualification": { group: "governance-versioning", purpose: "Bind qualification evidence and release one bounded Qualification Lease without granting landing authority." },
+    "dev-authority-heartbeat-landing": { group: "governance-versioning", purpose: "Extend the exact fenced Landing Warrant while final landing work remains live." },
+    "dev-authority-heartbeat-qualification": { group: "governance-versioning", purpose: "Extend one exact fenced Qualification Lease while qualification work remains live." },
+    "dev-authority-lease-landing": { group: "governance-versioning", purpose: "Issue or retain the single exclusive Landing Warrant for a qualified candidate." },
+    "dev-authority-lease-qualification": { group: "governance-versioning", purpose: "Issue one qualification-only lease within the configured bounded lane count." },
+    "dev-authority-migrate": { group: "governance-versioning", purpose: "Migrate one exact v1 Warrant state into v2 without rewriting candidate or fencing evidence." },
+    "dev-authority-observe": { group: "governance-versioning", purpose: "Read bounded Qualification Leases and the exclusive Landing Warrant without mutating authority." },
+    "dev-authority-recover": { group: "governance-versioning", purpose: "Recover expired qualification or Landing authority and emit one rooted wake instruction." },
+    "dev-authority-settle": { group: "governance-versioning", purpose: "Settle terminal candidate evidence idempotently and release held qualification or Landing authority immediately." },
+    "dev-authority-submit": { group: "governance-versioning", purpose: "Submit an exact candidate to the opt-in bounded-qualification authority state." },
     "dev-proof-classify": { group: "governance-versioning", purpose: "Classify source-qualified candidate changes against a current integration base." },
     "dev-proof-integration": { group: "governance-versioning", purpose: "Seal final exact integration delivery proof for a warranted candidate." },
     "dev-proof-replay": { group: "governance-versioning", purpose: "Replay source qualification against a Project Cut without rewriting candidate source." },
@@ -174,7 +185,8 @@ export function nodeApiMeta(exportName) {
     "./build-facts": { group: "observability-diagnostics", summary: "Git source, version, module output, product artifact, and legacy Kungfu build fact APIs." },
     "./candidate-timeline": { group: "observability-diagnostics", summary: "Source-bound candidate event normalization, per-attempt critical-path-safe aggregation, and compact reporting APIs." },
     "./channel-candidate": { group: "governance-versioning", summary: "Exact-source channel candidate decisions, same-SHA workflow evidence validation, and deterministic source-lock reference APIs." },
-    "./dev-delivery-warrant": { group: "governance-versioning", summary: "Durable fair Dev Delivery Warrant queue, fenced lease, and split source and integration proof APIs." },
+    "./dev-delivery-authority": { group: "governance-versioning", summary: "Opt-in bounded Qualification Lease, exclusive Landing Warrant, exact v1 migration, admission, and terminal settlement APIs." },
+    "./dev-delivery-warrant": { group: "governance-versioning", summary: "Durable single-flight Warrant queue, fenced lease, and split source and integration proof APIs." },
     "./cache-evidence": { group: "observability-diagnostics", summary: "Content-addressed cache operation receipts and source/platform-bound evidence-set verification APIs." },
     "./diagnostics": { group: "observability-diagnostics", summary: "Native diagnostics collection, summarization, cache, compiler, and process-sampler APIs." },
     "./logging": { group: "observability-diagnostics", summary: "Buildchain JSONL logging, span, summary, and verification APIs." },
@@ -203,6 +215,9 @@ export function nodeApiMeta(exportName) {
     "./release-candidate": { group: "reusable-build", summary: "PR-stage release-candidate artifact, passport, and promote-only resolver APIs." },
     "./release-candidate-recovery": { group: "release-passport-trust", summary: "Fail-closed verification and immutable receipts for reusing a successful sealed candidate run without rebuilding product payloads." },
     "./release-train": { group: "governance-versioning", summary: "Frozen Release Cut identity, rooted Release Train transitions, Dev observations, supersession, replay, and legacy read compatibility APIs." },
+    "./next-development-transition": { group: "governance-versioning", summary: "Provider-neutral completed-Alpha preservation and rooted next-development state, version-model, idempotency, and local materialization APIs." },
+    "./next-development-controller": { group: "governance-versioning", summary: "Durable completed-Alpha child scheduling, fresh-runner checkpoint resume, latest protected-Dev reconciliation, and exact version-root readback APIs." },
+    "./next-development-projection": { group: "governance-versioning", summary: "Canonical generated config, Agent, and manual projections for the next-development transition contract." },
     "./stable-candidate-ledger": { group: "governance-versioning", summary: "Immutable alpha candidate ledger, qualification, revocation, selection, and exact stable source-lock APIs." },
     "./release-propagation": { group: "site-and-propagation", summary: "Release propagation graph, plan, and exact upstream lock APIs." },
     "./release-activation-transaction": { group: "release-passport-trust", summary: "Ordered cross-repository activation, exact receipt-set binding, retry, abort, rollback, and shadow-rehearsal APIs." },
@@ -219,6 +234,15 @@ export function nodeApiMeta(exportName) {
     "./buildchain-layout": { group: "kfd-trust", summary: "Versioned Buildchain repository-layout discovery contract plus canonical .buildchain path resolution and migration APIs." },
     "./kfd": { group: "kfd-trust", summary: "Unified KFD standards, schema discovery, KFD-1/KFD-2/KFD-3 grouped APIs, KFD-4 schema discovery, upstream KFD aggregate facts, and Buildchain KFD claim helpers." },
     "./kfd-adopter-manifest": { group: "kfd-trust", summary: "Exact-cut KFD adopter manifest verification, Buildchain evidence binding, and one-way legacy support-matrix projection APIs." },
+    "./adopter-delivery-gate": { group: "release-passport-trust", summary: "Protocol-neutral exact-driver and explicit artifact-profile delivery gate APIs." },
+    "./kfd-adopter-category-driver": { group: "kfd-trust", summary: "Thin delivery driver over exact published KFD category profiles and instance verification." },
+    "./buildchain-delivery-infrastructure": { group: "kfd-trust", summary: "Buildchain-owned delivery-infrastructure category instance construction and published-KFD verification APIs." },
+    "./buildchain-delivery-bootstrap": { group: "release-passport-trust", summary: "Anti-circular protected N-1 bootstrap evidence verification for one exact Buildchain delivery-infrastructure candidate." },
+    "./buildchain-delivery-self-dogfood": { group: "release-passport-trust", summary: "Pure exact-package self-dogfood assembly through injected published N-1 Buildchain and KFD abilities." },
+    "./published-delivery-authority": { group: "release-passport-trust", summary: "Exact npm archive-byte loading and constrained N-1 delivery authority imports with guaranteed cleanup." },
+    "./legacy-kfd-adopter-driver": { group: "kfd-trust", summary: "Explicit one-way legacy standard adopter manifest and support-matrix delivery adapter." },
+    "./adopter-delivery-passport": { group: "release-passport-trust", summary: "Exact adopter delivery gate binding and Release Passport evidence verification APIs." },
+    "./adopter-delivery-vectors": { group: "release-passport-trust", summary: "Rooted golden, negative, fault, and offline replay vector suite APIs." },
     "./kfd-adopter-release-binding": { group: "kfd-trust", summary: "Release Passport and artifact-evidence binding for one exact standard adopter manifest closure." },
     "./kfd-product-gates": { group: "kfd-trust", summary: "Fail-closed KFD-4, KFD-5, and KFD-7 product evidence gates plus non-widening KFD support-matrix release projections." },
     "./public-surface-audit": { group: "kfd-trust", summary: "Reverse audit APIs for CLI, workflow, action, site page, and documentation command surfaces." },

package/scripts/stable-candidate-qualification.mjs

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 
+import { validateHostedSelfDogfoodEvidence } from "./next-development-self-dogfood.mjs";
+
 const DEFAULTS = {
   buildWorkflowFile: "build-surface-fixture.yml",
   buildWorkflowName: "Build Surface Fixture",
@@ -48,13 +50,11 @@ export function resolveStableCandidateQualificationCandidate({ eventName, inputC
   if (text(eventName) !== "workflow_run") {
     throw new Error(`qualification candidate resolver does not admit event ${eventName || "<empty>"}`);
   }
-  const evidence = selfDogfoodEvidence;
-  if (
-    evidence?.contract !== "kungfu-buildchain-alpha-self-dogfood"
-    || evidence?.status !== "passed"
-    || evidence?.observed?.alpha?.ref !== "v3-alpha"
-  ) {
-    throw new Error("self-dogfood evidence is not a passing v3-alpha observation");
+  let evidence;
+  try {
+    evidence = validateHostedSelfDogfoodEvidence(selfDogfoodEvidence);
+  } catch (error) {
+    throw new Error(`self-dogfood evidence is not a passing rooted v3-alpha observation: ${error.message}`);
   }
   const observedSha = optionalSha(evidence.observed.alpha.sha, "observed v3-alpha SHA");
   const expectedSha = optionalSha(evidence.observed.alpha.expectedSha, "expected v3-alpha SHA");

package/scripts/workflow-call-contract.mjs

@@ -6,7 +6,7 @@ import { pathToFileURL } from "node:url";
 import { evaluateWorkflowCallContract } from "../packages/core/workflow-call-contract.js";
 import { parseWorkflowDocument } from "../packages/core/workflow-yaml-contract.js";
 
-export const SELF_RELEASE_REF = "769b221bad7a6b9104afad4c2628d9dca396ab0f";
+export const SELF_RELEASE_REF = "15db8a9d7c39f7a649a0e3971af68490356dd9ac";
 export const SELF_RELEASE_PUBLIC_WORKFLOW = `kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@${SELF_RELEASE_REF}`;
 
 function parityFailure(message) {

package/templates/native-dev-delivery.yml

@@ -0,0 +1,86 @@
+name: Protected Dev Delivery
+
+on:
+  repository_dispatch:
+    types: [buildchain-dev-delivery-wake]
+  workflow_dispatch:
+    inputs:
+      target-branch:
+        description: "Protected dev/vN/vN.M branch"
+        required: true
+      expected-pr-number:
+        description: "Exact ready and approved PR number"
+        required: true
+        type: number
+      expected-head-sha:
+        description: "Exact immutable PR head"
+        required: true
+      source-identity-root:
+        description: "Semantic source identity root"
+        required: true
+      source-patch-root:
+        description: "Semantic patch root"
+        required: true
+      assignment-root:
+        description: "Native Assignment root"
+        required: true
+      initiative-root:
+        description: "Parent Initiative root"
+        required: true
+      plan-root:
+        description: "Native qualification plan root"
+        required: true
+      closure-root:
+        description: "Affected closure root"
+        required: true
+      dependency-root:
+        description: "Dependency graph root"
+        required: true
+      toolchain-root:
+        description: "Native toolchain root"
+        required: true
+      environment-root:
+        description: "Native execution environment contract root"
+        required: true
+      affected-paths-json:
+        description: "JSON array representing the affected closure"
+        required: true
+      native-proof-json:
+        description: "Optional reusable native proof"
+        required: false
+        default: ""
+
+permissions:
+  actions: write
+  contents: write
+  pull-requests: write
+  checks: read
+  statuses: write
+
+jobs:
+  deliver:
+    uses: kungfu-systems/buildchain/.github/workflows/dev-pr-auto-merge.yml@v3
+    with:
+      target-branch: ${{ github.event.client_payload.candidate.targetBranch || inputs.target-branch }}
+      expected-pr-number: ${{ github.event.client_payload.candidate.pullRequestNumber || inputs.expected-pr-number }}
+      expected-head-sha: ${{ github.event.client_payload.candidate.sourceHead || inputs.expected-head-sha }}
+      source-workflow-run-id: ${{ github.event.client_payload.candidate.sourceWorkflowRunId || github.run_id }}
+      delivery-warrant-mode: required
+      assignment-root: ${{ github.event.client_payload.candidate.assignmentRoot || inputs.assignment-root }}
+      initiative-root: ${{ github.event.client_payload.candidate.initiativeRoot || inputs.initiative-root }}
+      source-identity-root: ${{ github.event.client_payload.candidate.sourceIdentityRoot || inputs.source-identity-root }}
+      source-patch-root: ${{ github.event.client_payload.candidate.sourcePatchRoot || inputs.source-patch-root }}
+      plan-root: ${{ github.event.client_payload.candidate.planRoot || inputs.plan-root }}
+      closure-root: ${{ github.event.client_payload.candidate.closureRoot || inputs.closure-root }}
+      dependency-root: ${{ github.event.client_payload.candidate.dependencyRoot || inputs.dependency-root }}
+      toolchain-root: ${{ github.event.client_payload.candidate.toolchainRoot || inputs.toolchain-root }}
+      environment-root: ${{ github.event.client_payload.candidate.environmentRoot || inputs.environment-root }}
+      affected-paths-json: ${{ github.event_name == 'repository_dispatch' && toJSON(github.event.client_payload.candidate.affectedPaths) || inputs.affected-paths-json }}
+      native-proof-json: ${{ inputs.native-proof-json || '' }}
+      native-command: cmake -S . -B build && cmake --build build --parallel && ctest --test-dir build --output-on-failure
+      native-heartbeat-seconds: 300
+      delivery-class: native-proof-required
+      landing-mode: queue
+      dry-run: false
+    secrets:
+      github-token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}