@kungfu-tech/buildchain 4.0.1-alpha.5 → 4.0.1-alpha.55

package/packages/core/adopter-delivery-passport.js

@@ -0,0 +1,295 @@
+import {
+  ADOPTER_DELIVERY_GATE_RESULT_CONTRACT,
+  adopterDeliveryGateDigest,
+} from "./adopter-delivery-gate.js";
+
+export const ADOPTER_DELIVERY_PASSPORT_BINDING_CONTRACT =
+  "kungfu-buildchain-adopter-delivery-passport-binding";
+
+const ROOT_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const EXACT_SHA_PATTERN = /^[0-9a-f]{40}$/u;
+
+export function releasePassportKfdAdopterSourceSha({
+  passportSourceSha = "",
+  release = undefined,
+} = {}) {
+  const exactSha = (value) =>
+    EXACT_SHA_PATTERN.test(String(value || "").trim());
+  const candidateSourceSha = String(release?.candidateSourceSha || "").trim();
+  const builtSourceSha = String(release?.builtSourceSha || "").trim();
+  const promotionChannelSha = String(release?.promotionChannelSha || "").trim();
+  const candidateSourceTreeSha = String(
+    release?.candidateSourceTreeSha || "",
+  ).trim();
+  const builtSourceTreeSha = String(release?.builtSourceTreeSha || "").trim();
+  const promotionChannelTreeSha = String(
+    release?.promotionChannelTreeSha || "",
+  ).trim();
+  if (
+    release?.treeEquivalent !== true ||
+    !exactSha(passportSourceSha) ||
+    !exactSha(candidateSourceSha) ||
+    !exactSha(builtSourceSha) ||
+    !exactSha(promotionChannelSha) ||
+    candidateSourceSha !== builtSourceSha ||
+    promotionChannelSha !== passportSourceSha ||
+    !exactSha(candidateSourceTreeSha) ||
+    !exactSha(builtSourceTreeSha) ||
+    !exactSha(promotionChannelTreeSha) ||
+    candidateSourceTreeSha !== builtSourceTreeSha ||
+    candidateSourceTreeSha !== promotionChannelTreeSha
+  ) {
+    return passportSourceSha;
+  }
+  return candidateSourceSha;
+}
+
+function issue(code, message, details = {}) {
+  return { code, message, details };
+}
+
+function validateRootedJson(value, rootField, code, label) {
+  const root = value?.[rootField];
+  if (!ROOT_PATTERN.test(root ?? "")) {
+    return [issue(code, `${label} must be a canonical sha256 root`)];
+  }
+  try {
+    const preimage = structuredClone(value);
+    delete preimage[rootField];
+    return adopterDeliveryGateDigest(preimage) === root
+      ? []
+      : [issue(code, `${label} does not match its exact JSON closure`)];
+  } catch {
+    return [issue(code, `${label} requires finite acyclic JSON`)];
+  }
+}
+
+function validateGateIdentity(result) {
+  const issues = [];
+  if (
+    result.schemaVersion !== 1 ||
+    result.contract !== ADOPTER_DELIVERY_GATE_RESULT_CONTRACT
+  ) {
+    issues.push(
+      issue(
+        "adopterDelivery.gateResult.contract",
+        "adopter delivery gate result contract is unsupported",
+      ),
+    );
+  }
+  if (
+    !result.project ||
+    !result.artifact ||
+    !result.protocol ||
+    !result.artifactProfile
+  ) {
+    issues.push(
+      issue(
+        "adopterDelivery.gateResult.closure",
+        "gate result must retain project, artifact, protocol, and artifact-profile bindings",
+      ),
+    );
+  }
+  if (!ROOT_PATTERN.test(result.artifact?.root ?? "")) {
+    issues.push(
+      issue(
+        "adopterDelivery.gateResult.artifact.root",
+        "delivery artifact root must be a canonical sha256 root",
+      ),
+    );
+  }
+  if (result.qualifying !== false || result.selfCertified !== false) {
+    issues.push(
+      issue(
+        "adopterDelivery.gateResult.nonClaims",
+        "delivery evidence must remain non-qualifying and non-self-certifying",
+      ),
+    );
+  }
+  return issues;
+}
+
+function validatePassedGate(result) {
+  if (result.status !== "passed") {
+    return result.status === "failed"
+      ? []
+      : [
+          issue(
+            "adopterDelivery.gateResult.status",
+            "gate status must be passed or failed",
+          ),
+        ];
+  }
+  const passed =
+    result.protocol?.loaded === true &&
+    ROOT_PATTERN.test(result.protocol?.reportRoot ?? "") &&
+    result.artifactProfile?.loaded === true &&
+    result.artifactProfile?.valid === true &&
+    result.semanticReport !== null &&
+    (result.issues?.length ?? -1) === 0;
+  return passed
+    ? []
+    : [
+        issue(
+          "adopterDelivery.gateResult.status",
+          "a passed gate must retain successful exact driver and artifact-profile evidence",
+        ),
+      ];
+}
+
+export function validateAdopterDeliveryGateResult(result) {
+  if (!result || typeof result !== "object" || Array.isArray(result)) {
+    return {
+      valid: false,
+      passed: false,
+      issues: [
+        issue(
+          "adopterDelivery.gateResult",
+          "adopter delivery gate result must be an object",
+        ),
+      ],
+    };
+  }
+  const issues = [
+    ...validateGateIdentity(result),
+    ...validateRootedJson(
+      result,
+      "gateRoot",
+      "adopterDelivery.gateResult.gateRoot",
+      "adopter delivery gate root",
+    ),
+    ...validatePassedGate(result),
+  ];
+  const valid = issues.length === 0;
+  return { valid, passed: valid && result.status === "passed", issues };
+}
+
+export function createAdopterDeliveryPassportBinding(gateResult) {
+  const normalized = structuredClone(gateResult);
+  const validation = validateAdopterDeliveryGateResult(normalized);
+  const binding = {
+    schemaVersion: 1,
+    contract: ADOPTER_DELIVERY_PASSPORT_BINDING_CONTRACT,
+    valid: validation.passed,
+    qualifying: false,
+    selfCertified: false,
+    gateResult: normalized,
+    validationIssues: validation.issues,
+    nonClaims: [
+      "A passing adopter delivery gate does not grant runtime permission or release authority.",
+      "The selected protocol driver retains semantic authority; Buildchain only binds its exact result into delivery evidence.",
+    ],
+  };
+  binding.bindingRoot = adopterDeliveryGateDigest(binding);
+  return binding;
+}
+
+export function normalizeAdopterDeliveryPassportBinding(value) {
+  if (!value) return undefined;
+  return value.contract === ADOPTER_DELIVERY_PASSPORT_BINDING_CONTRACT
+    ? structuredClone(value)
+    : createAdopterDeliveryPassportBinding(value);
+}
+
+export function validateAdopterDeliveryPassportBinding(
+  binding,
+  { expectedProjectRepository = "" } = {},
+) {
+  if (!binding || typeof binding !== "object" || Array.isArray(binding)) {
+    return [
+      issue(
+        "adopterDelivery.binding",
+        "adopter delivery passport binding must be an object",
+      ),
+    ];
+  }
+  const gateValidation = validateAdopterDeliveryGateResult(binding.gateResult);
+  const issues = [
+    ...validateRootedJson(
+      binding,
+      "bindingRoot",
+      "adopterDelivery.binding.bindingRoot",
+      "adopter delivery binding root",
+    ),
+    ...gateValidation.issues,
+  ];
+  if (
+    binding.schemaVersion !== 1 ||
+    binding.contract !== ADOPTER_DELIVERY_PASSPORT_BINDING_CONTRACT
+  ) {
+    issues.push(
+      issue(
+        "adopterDelivery.binding.contract",
+        "adopter delivery passport binding contract is unsupported",
+      ),
+    );
+  }
+  if (
+    binding.valid !== gateValidation.passed ||
+    binding.qualifying !== false ||
+    binding.selfCertified !== false
+  ) {
+    issues.push(
+      issue(
+        "adopterDelivery.binding.status",
+        "binding status must preserve a passing non-authoritative gate result",
+      ),
+    );
+  }
+  if (!gateValidation.passed) {
+    issues.push(
+      issue(
+        "adopterDelivery.status",
+        "release passport requires a passed adopter delivery gate",
+      ),
+    );
+  }
+  if (
+    expectedProjectRepository &&
+    binding.gateResult?.project?.adopterId !== expectedProjectRepository
+  ) {
+    issues.push(
+      issue(
+        "adopterDelivery.project",
+        "delivery project must match the release passport product repository",
+      ),
+    );
+  }
+  return issues;
+}
+
+function sameJson(left, right) {
+  try {
+    return adopterDeliveryGateDigest(left) === adopterDeliveryGateDigest(right);
+  } catch {
+    return false;
+  }
+}
+
+export function validateAdopterDeliveryReleaseEvidence({
+  binding,
+  artifactBinding,
+  expectedProjectRepository = "",
+} = {}) {
+  if (!binding && !artifactBinding) return [];
+  if (!binding) {
+    return [
+      issue(
+        "adopterDelivery.passport",
+        "artifact evidence cannot introduce delivery authority absent from the passport",
+      ),
+    ];
+  }
+  const issues = validateAdopterDeliveryPassportBinding(binding, {
+    expectedProjectRepository,
+  });
+  if (!artifactBinding || !sameJson(artifactBinding, binding)) {
+    issues.push(
+      issue(
+        "adopterDelivery.artifactEvidence",
+        "passport and artifact evidence must bind the same exact delivery result",
+      ),
+    );
+  }
+  return issues;
+}

package/packages/core/adopter-delivery-vectors.js

@@ -0,0 +1,158 @@
+import vectorSuite from "./adopter-delivery-vectors.json" with { type: "json" };
+
+import { adopterDeliveryGateDigest } from "./adopter-delivery-gate.js";
+
+export const ADOPTER_DELIVERY_VECTOR_SUITE_CONTRACT =
+  "kungfu-buildchain-adopter-delivery-vectors/v1";
+
+const ROOT_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const REQUIRED_CASES = new Map([
+  ["golden-two-driver-offline-replay", "golden"],
+  ["negative-driver-mismatch", "negative"],
+  ["negative-category-conflict", "negative"],
+  ["negative-evidence-substitution", "negative"],
+  ["negative-stale-package-cut", "negative"],
+  ["fault-driver-throw", "fault"],
+]);
+
+function freezeJson(value) {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) freezeJson(child);
+  }
+  return value;
+}
+
+function issue(code, path, message) {
+  return { code, path, message };
+}
+
+function suiteDigest(suite) {
+  const preimage = structuredClone(suite);
+  delete preimage.suiteRoot;
+  return adopterDeliveryGateDigest(preimage);
+}
+
+export function validateAdopterDeliveryVectorSuite(suite) {
+  const issues = [];
+  if (!suite || typeof suite !== "object" || Array.isArray(suite)) {
+    return {
+      valid: false,
+      issues: [
+        issue(
+          "adopter-delivery-vectors.invalid",
+          "/",
+          "Vector suite must be a JSON object.",
+        ),
+      ],
+    };
+  }
+  if (
+    suite.schemaVersion !== 1 ||
+    suite.contract !== ADOPTER_DELIVERY_VECTOR_SUITE_CONTRACT
+  ) {
+    issues.push(
+      issue(
+        "adopter-delivery-vectors.contract",
+        "/contract",
+        "Vector suite contract is unsupported.",
+      ),
+    );
+  }
+  if (!Array.isArray(suite.cases)) {
+    issues.push(
+      issue(
+        "adopter-delivery-vectors.cases",
+        "/cases",
+        "Vector suite cases must be an array.",
+      ),
+    );
+  } else {
+    const seen = new Set();
+    for (const [index, entry] of suite.cases.entries()) {
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        issues.push(
+          issue(
+            "adopter-delivery-vectors.case",
+            `/cases/${index}`,
+            "Vector case must be an object.",
+          ),
+        );
+        continue;
+      }
+      if (typeof entry.id !== "string" || seen.has(entry.id)) {
+        issues.push(
+          issue(
+            "adopter-delivery-vectors.case-id",
+            `/cases/${index}/id`,
+            "Vector case id must be non-empty and unique.",
+          ),
+        );
+      }
+      seen.add(entry.id);
+      if (!entry.expected || typeof entry.expected !== "object") {
+        issues.push(
+          issue(
+            "adopter-delivery-vectors.expected",
+            `/cases/${index}/expected`,
+            "Vector case must declare its expected result.",
+          ),
+        );
+      }
+    }
+    for (const [id, className] of REQUIRED_CASES) {
+      const entry = suite.cases.find((candidate) => candidate?.id === id);
+      if (!entry || entry.class !== className) {
+        issues.push(
+          issue(
+            "adopter-delivery-vectors.required-case",
+            "/cases",
+            `Required ${className} vector ${id} is missing.`,
+          ),
+        );
+      }
+    }
+  }
+  if (!ROOT_PATTERN.test(suite.suiteRoot ?? "")) {
+    issues.push(
+      issue(
+        "adopter-delivery-vectors.root",
+        "/suiteRoot",
+        "Vector suite root must be a canonical sha256 root.",
+      ),
+    );
+  } else {
+    try {
+      if (suiteDigest(suite) !== suite.suiteRoot) {
+        issues.push(
+          issue(
+            "adopter-delivery-vectors.root",
+            "/suiteRoot",
+            "Vector suite root does not match the exact JSON closure.",
+          ),
+        );
+      }
+    } catch {
+      issues.push(
+        issue(
+          "adopter-delivery-vectors.root",
+          "/suiteRoot",
+          "Vector suite must contain finite acyclic JSON.",
+        ),
+      );
+    }
+  }
+  return { valid: issues.length === 0, issues };
+}
+
+export const ADOPTER_DELIVERY_VECTOR_SUITE = freezeJson(
+  structuredClone(vectorSuite),
+);
+
+export function getAdopterDeliveryVector(id) {
+  const entry = ADOPTER_DELIVERY_VECTOR_SUITE.cases.find(
+    (candidate) => candidate.id === id,
+  );
+  if (!entry) throw new RangeError(`Unknown adopter delivery vector: ${id}`);
+  return structuredClone(entry);
+}

package/packages/core/adopter-delivery-vectors.json

@@ -0,0 +1,77 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-adopter-delivery-vectors/v1",
+  "rootAlgorithm": "sha256-buildchain-canonical-json-v1",
+  "authorities": {
+    "kfdPackage": "@kungfu-tech/kfd@1.0.0-alpha.65",
+    "categoryProfileVectors": "@kungfu-tech/kfd/adopter-conformance/category-profile-vectors.json",
+    "categoryInstanceVectors": "@kungfu-tech/kfd/adopter-conformance/category-instance-vectors.json"
+  },
+  "cases": [
+    {
+      "id": "golden-two-driver-offline-replay",
+      "class": "golden",
+      "surface": "protocol-neutral-gate",
+      "operation": "evaluate identical exact requests with two isolated protocol drivers and replay each request offline",
+      "expected": {
+        "statuses": ["passed", "passed"],
+        "issueCodes": [],
+        "deterministicRoots": true,
+        "qualifying": false,
+        "selfCertified": false
+      }
+    },
+    {
+      "id": "negative-driver-mismatch",
+      "class": "negative",
+      "surface": "protocol-neutral-gate",
+      "operation": "select an exact protocol identity and version that are not registered",
+      "expected": {
+        "status": "failed",
+        "issueCodes": ["delivery-driver-unknown"]
+      }
+    },
+    {
+      "id": "negative-category-conflict",
+      "class": "negative",
+      "surface": "published-kfd-category-driver",
+      "operation": "append a duplicate published category profile to the exact KFD instance selection",
+      "expected": {
+        "status": "failed",
+        "issueCodes": ["acp-composition-invalid"]
+      }
+    },
+    {
+      "id": "negative-evidence-substitution",
+      "class": "negative",
+      "surface": "release-passport-binding",
+      "operation": "substitute the artifact root in artifact evidence after binding the passport",
+      "expected": {
+        "status": "failed",
+        "issueCodes": ["adopterDelivery.artifactEvidence"]
+      }
+    },
+    {
+      "id": "negative-stale-package-cut",
+      "class": "negative",
+      "surface": "published-kfd-category-driver",
+      "operation": "replace the KFD instance package version with an uninstalled stale cut",
+      "expected": {
+        "status": "failed",
+        "issueCodes": ["delivery-kfd-package-cut-mismatch"]
+      }
+    },
+    {
+      "id": "fault-driver-throw",
+      "class": "fault",
+      "surface": "protocol-neutral-gate",
+      "operation": "throw a private exception from the selected protocol driver",
+      "expected": {
+        "status": "failed",
+        "issueCodes": ["delivery-driver-error"],
+        "privateDetailRedacted": true
+      }
+    }
+  ],
+  "suiteRoot": "sha256:c978707556406ffda4ef4192032332c01c2da1cebb6ad8c4f0edfc65d5cef0c7"
+}

package/packages/core/buildchain-agent-manuals.js

@@ -30,6 +30,7 @@ export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
   { id: "kfd-agent-hub", title: "KFD Agent Hub Builder flow", path: "docs/kfd-agent-hub.md", plane: "use" },
   { id: "lifecycle-protocol", title: "Lifecycle protocol", path: "docs/lifecycle-protocol.md", plane: "use" },
   { id: "reusable-build-surface", title: "Reusable build surface", path: "docs/reusable-build-surface.md", plane: "use" },
+  { id: "v4-adopter-delivery", title: "V4 public adopter delivery", path: "docs/v4-adopter-delivery.md", plane: "verify" },
   { id: "publish-transaction", title: "Publish transaction", path: "docs/publish-transaction.md", plane: "verify" },
   { id: "release-tail-contract", title: "Declarative release-tail contract", path: "docs/release-tail-contract.md", plane: "verify" },
   { id: "release-tail-provider-plane", title: "Declarative release-tail provider plane", path: "docs/release-tail-provider-plane.md", plane: "use" },

package/packages/core/buildchain-config.js

@@ -236,6 +236,16 @@ export function normalizeBuildchainConfig(config) {
   if (normalized.publication !== undefined) {
     normalized.publication = normalizePublicationSection(normalized.publication);
   }
+  if (normalized.publication_rehearsal !== undefined) {
+    normalized.publication_rehearsal = normalizePublicationRehearsalSection(
+      normalized.publication_rehearsal,
+    );
+  }
+  if (normalized.adopter_delivery !== undefined) {
+    normalized.adopter_delivery = normalizeAdopterDeliverySection(
+      normalized.adopter_delivery,
+    );
+  }
   if (normalized.consumers !== undefined) {
     normalized.consumers = normalizeConsumersSection(normalized.consumers);
   }
@@ -700,6 +710,80 @@ function normalizePublicationSection(publication) {
   };
 }
 
+function normalizePublicationRehearsalSection(rehearsal) {
+  assertPlainObject(rehearsal, "publication_rehearsal");
+  const allowed = ["contract", "capsule_path", "candidate_root", "state_path", "evidence_path", "effect_default"];
+  const unknown = Object.keys(rehearsal).filter((key) => !allowed.includes(key));
+  if (unknown.length > 0) {
+    throw new Error(`publication_rehearsal contains unsupported fields: ${unknown.join(", ")}`);
+  }
+  const normalized = {
+    contract: assertString(rehearsal.contract, "publication_rehearsal.contract"),
+    capsulePath: posixPath(assertString(rehearsal.capsule_path, "publication_rehearsal.capsule_path")),
+    candidateRoot: posixPath(assertString(rehearsal.candidate_root, "publication_rehearsal.candidate_root")),
+    statePath: posixPath(assertString(rehearsal.state_path, "publication_rehearsal.state_path")),
+    evidencePath: posixPath(assertString(rehearsal.evidence_path, "publication_rehearsal.evidence_path")),
+    effectDefault: assertString(rehearsal.effect_default, "publication_rehearsal.effect_default"),
+  };
+  if (
+    normalized.contract !== "buildchain-v4-publication-rehearsal-capsule/v1" ||
+    normalized.effectDefault !== "disabled"
+  ) {
+    throw new Error("publication_rehearsal must use the v4 capsule contract with effect_default = disabled");
+  }
+  for (const [key, value] of Object.entries({
+    capsule_path: normalized.capsulePath,
+    candidate_root: normalized.candidateRoot,
+    state_path: normalized.statePath,
+    evidence_path: normalized.evidencePath,
+  })) {
+    if (value.startsWith("/") || value.includes("\\") || value.split("/").includes("..")) {
+      throw new Error(`publication_rehearsal.${key} must be repository-relative`);
+    }
+  }
+  return normalized;
+}
+
+function normalizeAdopterDeliverySection(delivery) {
+  assertPlainObject(delivery, "adopter_delivery");
+  const allowed = ["contract", "input_path", "readback_path", "bootstrap_path", "archive_path", "result_path", "driver_selector", "artifact_profile_selector"];
+  const unknown = Object.keys(delivery).filter((key) => !allowed.includes(key));
+  if (unknown.length > 0) {
+    throw new Error(`adopter_delivery contains unsupported fields: ${unknown.join(", ")}`);
+  }
+  const normalized = {
+    contract: assertString(delivery.contract, "adopter_delivery.contract"),
+    inputPath: posixPath(assertString(delivery.input_path, "adopter_delivery.input_path")),
+    readbackPath: posixPath(assertString(delivery.readback_path, "adopter_delivery.readback_path")),
+    bootstrapPath: posixPath(assertString(delivery.bootstrap_path, "adopter_delivery.bootstrap_path")),
+    archivePath: posixPath(assertString(delivery.archive_path, "adopter_delivery.archive_path")),
+    resultPath: posixPath(assertString(delivery.result_path, "adopter_delivery.result_path")),
+    driverSelector: assertString(delivery.driver_selector, "adopter_delivery.driver_selector"),
+    artifactProfileSelector: assertString(delivery.artifact_profile_selector, "adopter_delivery.artifact_profile_selector"),
+  };
+  if (normalized.contract !== "kungfu-buildchain-v4-adopter-delivery/v1") {
+    throw new Error("adopter_delivery contract is unsupported");
+  }
+  if (
+    !["json-assertion", "kfd-category", "legacy-kfd"].includes(normalized.driverSelector) ||
+    !["git-commit", "package"].includes(normalized.artifactProfileSelector)
+  ) {
+    throw new Error("adopter_delivery selector is unsupported");
+  }
+  for (const [key, value] of Object.entries({
+    input_path: normalized.inputPath,
+    readback_path: normalized.readbackPath,
+    bootstrap_path: normalized.bootstrapPath,
+    archive_path: normalized.archivePath,
+    result_path: normalized.resultPath,
+  })) {
+    if (value.startsWith("/") || value.includes("\\") || value.split("/").includes("..")) {
+      throw new Error(`adopter_delivery.${key} must be repository-relative`);
+    }
+  }
+  return normalized;
+}
+
 function normalizePublicationArchive(archive = undefined) {
   if (archive === undefined) {
     return undefined;

package/packages/core/buildchain-contract.js

@@ -166,6 +166,36 @@ function declarativeAuditableDemoSurface(root, pkg, majorLine) {
   });
 }
 
+function v4ReleaseCandidatePromoteSurface(root, majorLine) {
+  return surface(root, {
+    id: "v4-release-candidate-promote-action",
+    kind: "action",
+    path: "actions/v4-release-candidate-promote/action.yml",
+    publicRef: `kungfu-systems/buildchain/actions/v4-release-candidate-promote@${majorLine}`,
+    requiredInputs: [
+      "token", "repository", "source-sha", "version", "tag", "channel",
+      "candidate-passport-path", "stage-capsules-path",
+      "publication-qualification-path",
+    ],
+    requiredOutputs: [
+      "release-passport-path", "release-passport-root", "transaction-state",
+      "declaration-root", "transaction-root", "state-root",
+      "receipt-roots-json",
+    ],
+    breakingDefaults: {
+      statePath: ".buildchain/release-tail/state.json",
+      executionBoundary: "built-in-provider-plane-only",
+    },
+    optionalInputs: ["artifact-paths", "state-path", "failure-after-capability"],
+    guarantees: [
+      "v4 promotion consumes only sealed candidate, Stage Capsule, qualification, and artifact evidence",
+      "GitHub Release, signed-channel commit, activation, readback, and released-evidence synthesis use built-in provider adapters",
+      "durable provider checkpoints resume completed capabilities without replay",
+      "no consumer command, script, shell, checkout, or executable tail hook is accepted",
+    ],
+  });
+}
+
 export function createBuildchainContractWorld({
   root = process.cwd(),
   packageJson = undefined,
@@ -484,7 +514,7 @@ export function createBuildchainContractWorld({
         "Build Images owns encoding, Buildchain owns qualification and receipts, and site repositories own browser loading and accessibility behavior",
         "media qualification does not claim browser playback, responsive layout, reduced-motion behavior, accessibility, or production deployment",
       ],
-    }), declarativeAuditableDemoSurface(root, pkg, majorLine),
+    }), declarativeAuditableDemoSurface(root, pkg, majorLine), v4ReleaseCandidatePromoteSurface(root, majorLine),
     surface(root, {
       id: "promote-buildchain-ref-action",
       kind: "action",