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

package/packages/core/release-passport.js

@@ -35,9 +35,13 @@ import {
 } from "./github-artifact-attestation.js";
 import { verifyV4FloatingConsumerPolicyCertification } from "./v4-floating-consumer-evidence.js";
 import {
+  normalizePromotionEvidence,
+  normalizePromotionRouting,
+  normalizeV4RuntimeResumeEvidence,
   isV4PromotionRouting,
   releasePassportCertificationVerificationOptions,
   requireV4ConsumerPolicyCertification,
+  resolveV4ConsumerPolicyCertificationIdentity,
 } from "./v4-floating-consumer-release-passport.js";
 import {
   verifyV4RuntimeAuthorizationReceipt,
@@ -400,13 +404,6 @@ function parseJsonInputWithMeta(value, fallback = undefined, { cwd = process.cwd
   };
 }
 
-function parseV4ConsumerPolicyCertification(input, cwd) {
-  return parseJsonInputWithMeta(input, undefined, {
-    cwd,
-    label: "v4ConsumerPolicyCertificationJson",
-  });
-}
-
 function mergeAuthoritativePassportBase(passport, basePassport = undefined, { requireKfd = false } = {}) {
   if (!basePassport) {
     if (requireKfd) {
@@ -439,11 +436,17 @@ function mergeAuthoritativePassportBase(passport, basePassport = undefined, { re
       kfd3: basePassport.evidence?.kfd3 || passport.evidence?.kfd3 || "",
     },
   };
-  for (const key of ["versionImpact", "surfaceImpacts"]) {
-    if (basePassport[key] !== undefined) {
-      merged[key] = basePassport[key];
-    }
-  }
+  for (const key of [
+    "versionImpact",
+    "surfaceImpacts",
+    "promotionRouting",
+    "v4ConsumerPolicy",
+    "v4RuntimeResume",
+    "transaction",
+    "trustedPublishing",
+    "distTagPromotion",
+  ])
+    if (basePassport[key] !== undefined) merged[key] = basePassport[key];
   if (basePassport.controllerReceipts !== undefined) {
     merged.controllerReceipts = basePassport.controllerReceipts;
   }
@@ -1065,103 +1068,6 @@ function normalizeTransaction(value = undefined) {
   };
 }
 
-function normalizePromotionRouting(value = undefined) {
-  if (value === undefined) return undefined;
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error("release.promotionRouting must be a JSON object");
-  }
-  if (value.contract !== "buildchain.promotion-routing/v1") {
-    throw new Error("release.promotionRouting contract must be buildchain.promotion-routing/v1");
-  }
-  for (const [label, field] of [
-    ["router.ref", value.router?.ref],
-    ["router.sha", value.router?.sha],
-    ["shell.ref", value.shell?.ref],
-    ["shell.sha", value.shell?.sha],
-    ["runtime.requestedRef", value.runtime?.requestedRef],
-    ["runtime.resolvedSha", value.runtime?.resolvedSha],
-    ["contractLock.path", value.contractLock?.path],
-    ["contractLock.digest", value.contractLock?.digest],
-    ["publication.channel", value.publication?.channel],
-    ["publication.targetRef", value.publication?.targetRef],
-  ]) {
-    if (!String(field || "").trim()) throw new Error(`release.promotionRouting.${label} is required`);
-  }
-  for (const [label, sha] of [
-    ["router.sha", value.router.sha],
-    ["shell.sha", value.shell.sha],
-    ["runtime.resolvedSha", value.runtime.resolvedSha],
-  ]) {
-    if (!/^[0-9a-f]{40}$/i.test(String(sha))) {
-      throw new Error(`release.promotionRouting.${label} must be a 40-character Git SHA`);
-    }
-  }
-  if (!/^sha256:[0-9a-f]{64}$/i.test(String(value.contractLock.digest))) {
-    throw new Error("release.promotionRouting.contractLock.digest must be a sha256 digest");
-  }
-  return JSON.parse(JSON.stringify(value));
-}
-
-function normalizePromotionEvidence({
-  release = {},
-  v4ConsumerPolicyCertification: certification,
-  v4ConsumerPolicyCertificationRoot: certificationRoot,
-  repository,
-  sourceSha,
-  cwd,
-}) {
-  const routing = normalizePromotionRouting(release.promotionRouting);
-  return {
-    routing,
-    consumerPolicy: requireV4ConsumerPolicyCertification({
-      value: certification,
-      repository,
-      sourceSha,
-      routing,
-      cwd,
-      certificationRoot,
-    }),
-  };
-}
-
-function normalizeV4RuntimeResumeEvidence(value, expected = {}) {
-  if (value === undefined || value === null || value === "") return undefined;
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error("v4RuntimeResumeEvidence must be a JSON object");
-  }
-  const authorizationVerification = verifyV4RuntimeAuthorizationReceipt({
-    receipt: value.authorization,
-    receiptRoot: value.authorizationRoot,
-    repository: expected.repository,
-    sourceSha: expected.sourceSha,
-    runtimeSha: expected.resumeRuntimeSha,
-    consumerPolicyReceiptRoot: expected.consumerPolicyReceiptRoot,
-  });
-  if (!authorizationVerification.ok) {
-    throw new Error(`v4 runtime authorization invalid: ${authorizationVerification.failures.join(", ")}`);
-  }
-  const lineageVerification = verifyV4RuntimeResumeLineage({
-    lineage: value.lineage,
-    lineageRoot: value.lineageRoot,
-    repository: expected.repository,
-    sourceSha: expected.sourceSha,
-    resumeRuntimeSha: expected.resumeRuntimeSha,
-    consumerPolicyReceiptRoot: expected.consumerPolicyReceiptRoot,
-  });
-  if (!lineageVerification.ok) {
-    throw new Error(`v4 runtime resume lineage invalid: ${lineageVerification.failures.join(", ")}`);
-  }
-  if (value.lineage?.authorizationRoot !== value.authorizationRoot) {
-    throw new Error("v4 runtime resume lineage authorization root mismatch");
-  }
-  return {
-    authorizationRoot: value.authorizationRoot,
-    authorization: structuredClone(value.authorization),
-    lineageRoot: value.lineageRoot,
-    lineage: structuredClone(value.lineage),
-  };
-}
-
 function prepareBuildEvidence({
   buildSummary,
   buildFacts,
@@ -1235,6 +1141,8 @@ function releaseField(release, camelKey, snakeKey, ...fallbacks) {
   return optionalString(firstTruthy(release[camelKey], release[snakeKey], ...fallbacks));
 }
 
+export { releasePassportKfdAdopterSourceSha } from "./adopter-delivery-passport.js";
+
 function optionalSections(entries) {
   return Object.fromEntries(entries.filter(([, value]) => value && (!Array.isArray(value) || value.length > 0)));
 }
@@ -1317,7 +1225,7 @@ export function createReleasePassport(options = {}) {
   const { promotion, buildEvidence } = preparePromotionBuild(options);
   const normalizedV4RuntimeResume = normalizeV4RuntimeResumeEvidence(v4RuntimeResumeEvidence, {
     repository,
-    sourceSha,
+    sourceSha: v4RuntimeResumeSourceSha(release, sourceSha),
     resumeRuntimeSha: promotion.routing?.runtime?.resolvedSha || "",
     consumerPolicyReceiptRoot: promotion.consumerPolicy?.certification?.receiptRoot || "",
   });
@@ -1862,7 +1770,6 @@ export function collectGitHubReleasePassport({
 function issue(level, code, message, details = {}) {
   return { level, code, message, details };
 }
-
 function validateContract(value, expectedContract, label, issues) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     issues.push(issue("error", `${label}.object`, `${label} must be a JSON object`));
@@ -2270,65 +2177,6 @@ function validateReleaseEvidenceAttachments({
   return { evidenceArtifacts, releaseEvidence };
 }
 
-function validateV4ConsumerPolicyPassportSection({ passport, issues }) {
-  const routing = passport?.promotionRouting;
-  const evidence = passport?.v4ConsumerPolicy;
-  if (isV4PromotionRouting(routing) && !evidence) {
-    issues.push(issue(
-      "error",
-      "v4ConsumerPolicy.missing",
-      "Buildchain v4 Release Passport requires an external floating consumer policy certification",
-    ));
-    return;
-  }
-  if (!evidence) return;
-  const verification = verifyV4FloatingConsumerPolicyCertification(
-    releasePassportCertificationVerificationOptions({
-      evidence,
-      passport,
-      routing,
-    }),
-  );
-  for (const failure of verification.failures) {
-    issues.push(issue("error", `v4ConsumerPolicy.${failure.code}`, failure.message));
-  }
-}
-
-function validateV4RuntimeResumePassportSection({ passport, issues }) {
-  const evidence = passport?.v4RuntimeResume;
-  if (!evidence) return;
-  const consumerPolicyReceiptRoot = passport?.v4ConsumerPolicy?.certification?.receiptRoot || "";
-  const authorization = verifyV4RuntimeAuthorizationReceipt({
-    receipt: evidence.authorization,
-    receiptRoot: evidence.authorizationRoot,
-    repository: passport?.product?.repository || "",
-    sourceSha: passport?.release?.sourceSha || "",
-    runtimeSha: passport?.promotionRouting?.runtime?.resolvedSha || "",
-    consumerPolicyReceiptRoot,
-  });
-  for (const failure of authorization.failures) {
-    issues.push(issue("error", `v4RuntimeResume.authorization.${failure}`, failure));
-  }
-  const lineage = verifyV4RuntimeResumeLineage({
-    lineage: evidence.lineage,
-    lineageRoot: evidence.lineageRoot,
-    repository: passport?.product?.repository || "",
-    sourceSha: passport?.release?.sourceSha || "",
-    resumeRuntimeSha: passport?.promotionRouting?.runtime?.resolvedSha || "",
-    consumerPolicyReceiptRoot,
-  });
-  for (const failure of lineage.failures) {
-    issues.push(issue("error", `v4RuntimeResume.lineage.${failure}`, failure));
-  }
-  if (evidence.lineage?.authorizationRoot !== evidence.authorizationRoot) {
-    issues.push(issue(
-      "error",
-      "v4RuntimeResume.authorization-root-mismatch",
-      "runtime resume lineage must bind the embedded authorization receipt root",
-    ));
-  }
-}
-
 function validatePublishEvidenceSection({ passport, publishEvidence, normalizedPublishEvidence, issues }) {
   const publishEvidenceSupplied =
     Boolean(passport?.evidence?.publishEvidence) ||
@@ -2956,3 +2804,80 @@ export function makeReleasePassportFixtureAssets(dir) {
 export function validateKnownReleasePassportContracts() {
   return [...CONTRACTS];
 }
+function parseV4ConsumerPolicyCertification(input, cwd) {
+  return parseJsonInputWithMeta(input, undefined, {
+    cwd,
+    label: "v4ConsumerPolicyCertificationJson",
+  });
+}
+
+function v4RuntimeResumeSourceSha(release, fallback = "") {
+  const builtSourceSha = releaseField(
+    release || {},
+    "builtSourceSha",
+    "built_source_sha",
+  );
+  return release?.treeEquivalent === true && builtSourceSha
+    ? builtSourceSha
+    : fallback;
+}
+
+
+function validateV4ConsumerPolicyPassportSection({ passport, issues }) {
+  const routing = passport?.promotionRouting;
+  const evidence = passport?.v4ConsumerPolicy;
+  if (isV4PromotionRouting(routing) && !evidence) {
+    issues.push(issue(
+      "error",
+      "v4ConsumerPolicy.missing",
+      "Buildchain v4 Release Passport requires an external floating consumer policy certification",
+    ));
+    return;
+  }
+  if (!evidence) return;
+  const verification = verifyV4FloatingConsumerPolicyCertification(
+    releasePassportCertificationVerificationOptions({
+      evidence,
+      passport,
+      routing,
+    }),
+  );
+  for (const failure of verification.failures) {
+    issues.push(issue("error", `v4ConsumerPolicy.${failure.code}`, failure.message));
+  }
+}
+
+function validateV4RuntimeResumePassportSection({ passport, issues }) {
+  const evidence = passport?.v4RuntimeResume;
+  if (!evidence) return;
+  const consumerPolicyReceiptRoot = passport?.v4ConsumerPolicy?.certification?.receiptRoot || "";
+  const authorization = verifyV4RuntimeAuthorizationReceipt({
+    receipt: evidence.authorization,
+    receiptRoot: evidence.authorizationRoot,
+    repository: passport?.product?.repository || "",
+    sourceSha: v4RuntimeResumeSourceSha(passport?.release, passport?.release?.sourceSha || ""),
+    runtimeSha: passport?.promotionRouting?.runtime?.resolvedSha || "",
+    consumerPolicyReceiptRoot,
+  });
+  for (const failure of authorization.failures) {
+    issues.push(issue("error", `v4RuntimeResume.authorization.${failure}`, failure));
+  }
+  const lineage = verifyV4RuntimeResumeLineage({
+    lineage: evidence.lineage,
+    lineageRoot: evidence.lineageRoot,
+    repository: passport?.product?.repository || "",
+    sourceSha: v4RuntimeResumeSourceSha(passport?.release, passport?.release?.sourceSha || ""),
+    resumeRuntimeSha: passport?.promotionRouting?.runtime?.resolvedSha || "",
+    consumerPolicyReceiptRoot,
+  });
+  for (const failure of lineage.failures) {
+    issues.push(issue("error", `v4RuntimeResume.lineage.${failure}`, failure));
+  }
+  if (evidence.lineage?.authorizationRoot !== evidence.authorizationRoot) {
+    issues.push(issue(
+      "error",
+      "v4RuntimeResume.authorization-root-mismatch",
+      "runtime resume lineage must bind the embedded authorization receipt root",
+    ));
+  }
+}

package/packages/core/v4-adopter-delivery-parity.js

@@ -31,10 +31,10 @@ const root = path.resolve(
 );
 
 export const V4_ADOPTER_DELIVERY_PARITY_SOURCE = Object.freeze({
-  v3Commit: "c3f58d76391c1c6ceddfc900a68e91c7ab82a575",
+  v3Commit: "6b96bdad8d9f8ccf9275f27d9370a226a9c78465",
   vectorSuiteRoot:
-    "sha256:cf329805d928a9883cbafbdfdf21ef66c6a0889ed8dfe14356b4e0d25d6738f9",
-  kfdPackage: "@kungfu-tech/kfd@1.0.0-alpha.62",
+    "sha256:c978707556406ffda4ef4192032332c01c2da1cebb6ad8c4f0edfc65d5cef0c7",
+  kfdPackage: "@kungfu-tech/kfd@1.0.0-alpha.65",
 });
 
 function clone(value) {

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

@@ -0,0 +1,359 @@
+import {
+  adopterDeliveryGateDigest,
+  createAdopterDeliveryGate,
+  createGitCommitArtifactProfile,
+  createPackageArtifactProfile,
+  defineAdopterProtocolDriver,
+  ADOPTER_PROTOCOL_DRIVER_INTERFACE,
+} from "./adopter-delivery-gate.js";
+import { qualifyBuildchainDeliveryInfrastructureBootstrap } from "./buildchain-delivery-bootstrap.js";
+import { createKfdAdopterCategoryProtocolDriver } from "./kfd-adopter-category-driver.js";
+import { createLegacyKfdAdopterProtocolDriver } from "./legacy-kfd-adopter-driver.js";
+import { loadPublishedBuildchainDeliveryAuthority } from "./published-delivery-authority.js";
+
+export const V4_ADOPTER_DELIVERY_CONTRACT =
+  "kungfu-buildchain-v4-adopter-delivery/v1";
+export const V4_ADOPTER_DELIVERY_READBACK_CONTRACT =
+  "kungfu-buildchain-v4-adopter-delivery-readback/v1";
+export const V4_ADOPTER_DELIVERY_BOOTSTRAP_LINEAGE_CONTRACT =
+  "kungfu-buildchain-v4-adopter-delivery-bootstrap-lineage/v1";
+export const V4_ADOPTER_DELIVERY_SOURCE = Object.freeze({
+  branch: "dev/v3/v3.0",
+  commit: "6b96bdad8d9f8ccf9275f27d9370a226a9c78465",
+  vectorSuiteRoot:
+    "sha256:c978707556406ffda4ef4192032332c01c2da1cebb6ad8c4f0edfc65d5cef0c7",
+  kfdPackage: "@kungfu-tech/kfd@1.0.0-alpha.65",
+  targetBranch: "dev/v4/v4.0",
+  initialTargetBase: "e5611377efc03178f8687d99968cfdfa3ce2825b",
+  targetBase: "e0342713c7447960c13bd73377282b2e93f4853d",
+});
+export const V4_ADOPTER_DELIVERY_ARCHIVE_AUTHORITY = Object.freeze({
+  buildchain: Object.freeze({
+    name: "@kungfu-tech/buildchain",
+    version: "3.0.9-alpha.16",
+    archiveRoot:
+      "sha256:3f425e2c77d11f0bee8eb9aa2448566bca7a9d14672a7e528ced3e505b3f14a3",
+    artifactRoot:
+      "sha256:3f425e2c77d11f0bee8eb9aa2448566bca7a9d14672a7e528ced3e505b3f14a3",
+  }),
+  kfd: Object.freeze({
+    name: "@kungfu-tech/kfd",
+    version: "1.0.0-alpha.65",
+    archiveRoot:
+      "sha256:c4dbd3f954910236d7f0823ea6887f4151e43b871df526ccdd599123421bced2",
+    artifactRoot:
+      "sha256:c0781bcaf191a58561ae32ee2fbedabbb48ed50b5725c356fbd83704089637f8",
+  }),
+  authorityRoot:
+    "sha256:9ba0cc6042b189ce749d01003617b57bcd03ea6ecf40e96d19e8ecbbfa347134",
+});
+
+const ROOT = /^sha256:[0-9a-f]{64}$/u;
+const SHA = /^[0-9a-f]{40}$/u;
+const BUILTIN_DRIVER_SELECTORS = Object.freeze({
+  "json-assertion": "buildchain.adopter/json-assertion@1.0.0",
+  "kfd-category": "kfd.adopter-category/instance-manifest@1.0.0",
+  "legacy-kfd": "buildchain.kfd-adopter/legacy-support-matrix@1.0.0",
+});
+const BUILTIN_PROFILE_SELECTORS = Object.freeze({
+  "git-commit": "buildchain.artifact/git-commit@1.0.0",
+  package: "buildchain.artifact/package@1.0.0",
+});
+
+function exactKeys(value, keys, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError(`${label} must be an object`);
+  }
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  if (
+    actual.length !== expected.length ||
+    actual.some((entry, index) => entry !== expected[index])
+  ) {
+    throw new TypeError(`${label} has an unsupported field set`);
+  }
+  return structuredClone(value);
+}
+
+function definitionKey(value) {
+  return `${value.id}@${value.version}`;
+}
+
+function resolveSelector(selector, table, definitions, label) {
+  const expected = table[selector];
+  if (!expected) throw new RangeError(`unknown ${label} selector: ${selector}`);
+  const selected = definitions.find(
+    (entry) => definitionKey(entry) === expected,
+  );
+  if (!selected)
+    throw new Error(
+      `${label} selector is not backed by an exact implementation`,
+    );
+  return selected;
+}
+
+export function createJsonAssertionAdopterProtocolDriver() {
+  return defineAdopterProtocolDriver({
+    interface: ADOPTER_PROTOCOL_DRIVER_INTERFACE,
+    id: "buildchain.adopter/json-assertion",
+    version: "1.0.0",
+    verify({ request }) {
+      const declaration = request.declaration;
+      const exact =
+        declaration &&
+        typeof declaration === "object" &&
+        !Array.isArray(declaration) &&
+        Object.keys(declaration).length === 1 &&
+        typeof declaration.valid === "boolean";
+      const valid = exact && declaration.valid === true;
+      const issues = valid
+        ? []
+        : [
+            {
+              code: "delivery-json-assertion-rejected",
+              path: "/declaration",
+              message:
+                "JSON assertion declarations must contain only valid: true.",
+            },
+          ];
+      const report = {
+        schemaVersion: 1,
+        contract: "kungfu-buildchain-json-assertion-driver-report/v1",
+        valid,
+        declaration: structuredClone(declaration),
+        qualifying: false,
+        selfCertified: false,
+        releaseAuthorized: false,
+      };
+      return {
+        valid,
+        report,
+        reportRoot: adopterDeliveryGateDigest(report),
+        issues,
+      };
+    },
+  });
+}
+
+export function createV4AdopterDeliveryRuntime({
+  drivers = [],
+  artifactProfiles = [],
+} = {}) {
+  const allDrivers = [
+    createJsonAssertionAdopterProtocolDriver(),
+    createKfdAdopterCategoryProtocolDriver(),
+    createLegacyKfdAdopterProtocolDriver(),
+    ...drivers,
+  ];
+  const allProfiles = [
+    createGitCommitArtifactProfile(),
+    createPackageArtifactProfile(),
+    ...artifactProfiles,
+  ];
+  return Object.freeze({
+    drivers: Object.freeze(allDrivers),
+    artifactProfiles: Object.freeze(allProfiles),
+    evaluate({
+      request,
+      context = {},
+      driverSelector,
+      artifactProfileSelector,
+    } = {}) {
+      const driver = resolveSelector(
+        driverSelector,
+        BUILTIN_DRIVER_SELECTORS,
+        allDrivers,
+        "driver",
+      );
+      const profile = resolveSelector(
+        artifactProfileSelector,
+        BUILTIN_PROFILE_SELECTORS,
+        allProfiles,
+        "artifact profile",
+      );
+      if (definitionKey(driver) !== definitionKey(request?.protocol ?? {})) {
+        throw new Error(
+          "driver selector does not match the exact request protocol",
+        );
+      }
+      if (
+        definitionKey(profile) !== definitionKey(request?.artifactProfile ?? {})
+      ) {
+        throw new Error(
+          "artifact profile selector does not match the exact request profile",
+        );
+      }
+      return createAdopterDeliveryGate({
+        drivers: [driver],
+        artifactProfiles: [profile],
+      }).evaluate(structuredClone(request), structuredClone(context));
+    },
+  });
+}
+
+export function runV4AdopterDeliveryGate(input, options = {}) {
+  const normalized = exactKeys(
+    input,
+    [
+      "schemaVersion",
+      "contract",
+      "driverSelector",
+      "artifactProfileSelector",
+      "request",
+      "context",
+    ],
+    "v4 adopter delivery input",
+  );
+  if (
+    normalized.schemaVersion !== 1 ||
+    normalized.contract !== V4_ADOPTER_DELIVERY_CONTRACT
+  ) {
+    throw new Error("v4 adopter delivery contract or version is unsupported");
+  }
+  const gateResult =
+    createV4AdopterDeliveryRuntime(options).evaluate(normalized);
+  const result = {
+    schemaVersion: 1,
+    contract: V4_ADOPTER_DELIVERY_READBACK_CONTRACT,
+    sourceAuthority: structuredClone(V4_ADOPTER_DELIVERY_SOURCE),
+    selection: {
+      driver: normalized.driverSelector,
+      artifactProfile: normalized.artifactProfileSelector,
+    },
+    gateResult,
+    qualifying: false,
+    selfCertified: false,
+    releaseAuthorized: false,
+    finalAuthority: "selected-public-driver-plus-exact-consumer-readback",
+  };
+  result.deliveryRoot = adopterDeliveryGateDigest(result);
+  return result;
+}
+
+export function verifyV4AdopterDeliveryReadback(
+  { input, readback } = {},
+  options = {},
+) {
+  if (!readback || !ROOT.test(readback.deliveryRoot ?? "")) {
+    throw new Error("exact adopter delivery readback is required");
+  }
+  const observed = runV4AdopterDeliveryGate(input, options);
+  if (
+    observed.deliveryRoot !== readback.deliveryRoot ||
+    adopterDeliveryGateDigest(observed) !== adopterDeliveryGateDigest(readback)
+  ) {
+    throw new Error(
+      "adopter delivery readback does not match exact recomputation",
+    );
+  }
+  return observed;
+}
+
+export function qualifyV4AdopterDeliveryBootstrap({ input, lineage } = {}) {
+  const normalizedLineage = exactKeys(
+    lineage,
+    [
+      "schemaVersion",
+      "contract",
+      "sourceAuthorityCommit",
+      "targetBaseCommit",
+      "authorityArchiveRoot",
+    ],
+    "bootstrap lineage",
+  );
+  if (
+    normalizedLineage.schemaVersion !== 1 ||
+    normalizedLineage.contract !==
+      V4_ADOPTER_DELIVERY_BOOTSTRAP_LINEAGE_CONTRACT ||
+    normalizedLineage.sourceAuthorityCommit !==
+      V4_ADOPTER_DELIVERY_SOURCE.commit ||
+    normalizedLineage.targetBaseCommit !==
+      V4_ADOPTER_DELIVERY_SOURCE.targetBase ||
+    !SHA.test(normalizedLineage.sourceAuthorityCommit) ||
+    !SHA.test(normalizedLineage.targetBaseCommit) ||
+    !ROOT.test(normalizedLineage.authorityArchiveRoot ?? "") ||
+    normalizedLineage.authorityArchiveRoot !== input?.authority?.packageRoot
+  ) {
+    throw new Error(
+      "bootstrap lineage does not bind the exact v3 authority and v4 base",
+    );
+  }
+  const bootstrap = qualifyBuildchainDeliveryInfrastructureBootstrap(input);
+  const result = {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-v4-adopter-delivery-bootstrap/v1",
+    sourceAuthority: structuredClone(V4_ADOPTER_DELIVERY_SOURCE),
+    lineage: normalizedLineage,
+    bootstrap,
+    qualifying: false,
+    selfCertified: false,
+    releaseAuthorized: false,
+  };
+  result.resultRoot = adopterDeliveryGateDigest(result);
+  return result;
+}
+
+export async function loadV4PublishedAdopterDeliveryAuthority({
+  packages,
+  expectedAuthorityRoot,
+} = {}) {
+  const request = assertV4PublishedAdopterDeliveryRequest({
+    packages,
+    expectedAuthorityRoot,
+  });
+  const authority = await loadPublishedBuildchainDeliveryAuthority(
+    request.packages,
+  );
+  if (authority.authorityRoot !== expectedAuthorityRoot) {
+    await authority.dispose();
+    throw new Error("published archive authority readback root does not match");
+  }
+  return authority;
+}
+
+export function assertV4PublishedAdopterDeliveryRequest({
+  packages,
+  expectedAuthorityRoot,
+} = {}) {
+  if (
+    !ROOT.test(expectedAuthorityRoot ?? "") ||
+    expectedAuthorityRoot !==
+      V4_ADOPTER_DELIVERY_ARCHIVE_AUTHORITY.authorityRoot
+  ) {
+    throw new Error(
+      "exact published archive authority readback root is required",
+    );
+  }
+  const normalizedPackages = exactKeys(
+    packages,
+    ["buildchain", "kfd"],
+    "published archive packages",
+  );
+  for (const key of ["buildchain", "kfd"]) {
+    const declaration = exactKeys(
+      normalizedPackages[key],
+      ["name", "version", "archivePath", "archiveRoot", "artifactRoot"],
+      `${key} archive identity`,
+    );
+    const expected = V4_ADOPTER_DELIVERY_ARCHIVE_AUTHORITY[key];
+    if (
+      typeof declaration.archivePath !== "string" ||
+      declaration.archivePath.length === 0 ||
+      declaration.name !== expected.name ||
+      declaration.version !== expected.version ||
+      declaration.archiveRoot !== expected.archiveRoot ||
+      declaration.artifactRoot !== expected.artifactRoot
+    ) {
+      throw new Error(`${key} archive identity is not the exact v3 authority`);
+    }
+  }
+  return {
+    packages: normalizedPackages,
+    expectedAuthorityRoot,
+  };
+}
+
+export const V4_ADOPTER_DELIVERY_SELECTORS = Object.freeze({
+  drivers: BUILTIN_DRIVER_SELECTORS,
+  artifactProfiles: BUILTIN_PROFILE_SELECTORS,
+});