@kungfu-tech/buildchain 3.0.4-alpha.2 → 3.0.4-alpha.3

package/packages/core/public-surface-cli.js

@@ -96,6 +96,10 @@ export function enumerateCliCommandsFromBin({
 } = {}) {
   const binSource = readText(root, binPath);
   const helpSource = readText(root, "scripts/buildchain-cli-help.mjs");
+  const registrySource = readText(
+    root,
+    "bin/internal/command-registry.mjs",
+  );
   const dispatchSource = [
     binSource,
     ...listFiles(root, "bin/internal", (name) => name.endsWith(".mjs")).map(
@@ -106,7 +110,14 @@ export function enumerateCliCommandsFromBin({
   const dispatch = [
     ...dispatchSource.matchAll(/if\s*\(\s*command\s*===\s*"([^"]+)"/g),
   ].map((match) => commandId(match[1]));
-  return uniqueSorted([...usage.map((entry) => entry.id), ...dispatch]).map(
+  const registered = [
+    ...registrySource.matchAll(/\{\s*id:\s*"([^"]+)"/g),
+  ].map((match) => commandId(match[1]));
+  return uniqueSorted([
+    ...usage.map((entry) => entry.id),
+    ...dispatch,
+    ...registered,
+  ]).map(
     (id) => ({
       id,
       source: "bin/buildchain.mjs",

package/packages/core/release-passport.js

@@ -1189,6 +1189,28 @@ export function createArtifactEvidence({ assets = [], repository = "", tag = "",
   };
 }
 
+function firstTruthy(...values) {
+  for (const value of values) {
+    if (value) return value;
+  }
+  return values.at(-1);
+}
+
+function releaseField(release, camelKey, snakeKey, ...fallbacks) {
+  return optionalString(firstTruthy(release[camelKey], release[snakeKey], ...fallbacks));
+}
+
+function optionalSections(entries) {
+  return Object.fromEntries(entries.filter(([, value]) => value && (!Array.isArray(value) || value.length > 0)));
+}
+
+function acceptedControllerSourceShas(input) {
+  const { treeEquivalent, builtSourceSha, promotionChannelSha, sourceSha, recoveryTreeEquivalent } = input;
+  return treeEquivalent && builtSourceSha && (promotionChannelSha === sourceSha || recoveryTreeEquivalent)
+    ? [builtSourceSha]
+    : [];
+}
+
 export function createReleasePassport({
   cwd = process.cwd(),
   repository = "",
@@ -1272,14 +1294,10 @@ export function createReleasePassport({
     kfd1Section: normalizedKfd1?.passportSection,
     kfd3Section: normalizedKfd3?.passportSection,
   });
-  const builtSourceSha = optionalString(release.builtSourceSha || release.built_source_sha);
-  const builtSourceTreeSha = optionalString(
-    release.builtSourceTreeSha || release.built_source_tree_sha,
-  );
-  const promotionChannelSha = optionalString(release.promotionChannelSha || release.promotion_channel_sha);
-  const promotionChannelTreeSha = optionalString(
-    release.promotionChannelTreeSha || release.promotion_channel_tree_sha,
-  );
+  const builtSourceSha = releaseField(release, "builtSourceSha", "built_source_sha");
+  const builtSourceTreeSha = releaseField(release, "builtSourceTreeSha", "built_source_tree_sha");
+  const promotionChannelSha = releaseField(release, "promotionChannelSha", "promotion_channel_sha");
+  const promotionChannelTreeSha = releaseField(release, "promotionChannelTreeSha", "promotion_channel_tree_sha");
   const treeEquivalent = release.treeEquivalent === true;
   const recoveryTreeEquivalent = Boolean(
     treeEquivalent &&
@@ -1291,11 +1309,13 @@ export function createReleasePassport({
     receipts: controllerReceipts,
     references: controllerReceiptReferences,
     expectedSourceSha: sourceSha,
-    acceptedSourceShas: treeEquivalent && builtSourceSha && (
-      promotionChannelSha === sourceSha || recoveryTreeEquivalent
-    )
-      ? [builtSourceSha]
-      : [],
+    acceptedSourceShas: acceptedControllerSourceShas({
+      treeEquivalent,
+      builtSourceSha,
+      promotionChannelSha,
+      sourceSha,
+      recoveryTreeEquivalent,
+    }),
     requirePassed: true,
   });
   const normalizedGitHubArtifactAttestations = (githubArtifactAttestations || [])
@@ -1306,37 +1326,13 @@ export function createReleasePassport({
     publishEvidence: normalizedPublishEvidence,
     publish,
   });
-  const releaseMaterialSha = optionalString(
-    release.releaseMaterialSha ||
-    release.release_material_sha ||
-    normalizedPublishEvidence?.releaseMaterialSha ||
-    normalizedTransaction?.releaseMaterialSha,
-  );
-  const releaseSha = optionalString(
-    release.releaseSha ||
-    release.release_sha ||
-    normalizedPublishEvidence?.releaseSha ||
-    normalizedTransaction?.releaseSha,
-  );
-  const targetRef = optionalString(release.targetRef || release.target_ref || normalizedPublishEvidence?.targetRef);
-  const packageDisplayVersion = optionalString(
-    packageVersion ||
-    normalizedPackageSet?.main?.version ||
-    normalizedPublishSummary?.packages?.find((entry) => entry.role === "main")?.publishedVersion ||
-    normalizedPublishEvidence?.version ||
-    normalizedTransaction?.version ||
-    readPackageVersion(cwd),
-  );
-  const publishedVersion = optionalString(
-    release.publishedVersion ||
-    release.published_version ||
-    packageDisplayVersion,
-  );
-  const internalVersion = optionalString(
-    release.internalVersion ||
-    release.internal_version ||
-    normalizedTransaction?.version,
-  );
+  const releaseMaterialSha = releaseField(release, "releaseMaterialSha", "release_material_sha", normalizedPublishEvidence?.releaseMaterialSha, normalizedTransaction?.releaseMaterialSha);
+  const releaseSha = releaseField(release, "releaseSha", "release_sha", normalizedPublishEvidence?.releaseSha, normalizedTransaction?.releaseSha);
+  const targetRef = releaseField(release, "targetRef", "target_ref", normalizedPublishEvidence?.targetRef);
+  const mainPublishedVersion = normalizedPublishSummary?.packages?.find((entry) => entry.role === "main")?.publishedVersion;
+  const packageDisplayVersion = optionalString(firstTruthy(packageVersion, normalizedPackageSet?.main?.version, mainPublishedVersion, normalizedPublishEvidence?.version, normalizedTransaction?.version, readPackageVersion(cwd)));
+  const publishedVersion = releaseField(release, "publishedVersion", "published_version", packageDisplayVersion);
+  const internalVersion = releaseField(release, "internalVersion", "internal_version", normalizedTransaction?.version);
   return {
     schemaVersion: 1,
     contract: RELEASE_PASSPORT_CONTRACT,
@@ -1344,7 +1340,7 @@ export function createReleasePassport({
     surfaceTimestampPolicy: createSurfaceTimestampPolicy({
       generatedAt,
       publishedAt: optionalString(release.publishedAt || release.published_at || normalizedPublishEvidence?.publishedAt),
-      sourceRevision: optionalString(sourceSha || releaseSha || normalizedTransaction?.releaseSha),
+      sourceRevision: optionalString(firstTruthy(sourceSha, releaseSha, normalizedTransaction?.releaseSha)),
       timestampPolicy: "ci-injected",
       deterministicInputs: [
         "release.sourceSha",
@@ -1366,14 +1362,14 @@ export function createReleasePassport({
     },
     release: {
       tag: normalizedTag,
-      publicTag: optionalString(release.publicTag || release.public_tag || normalizedTag),
-      internalTag: optionalString(release.internalTag || release.internal_tag || normalizedTag),
+      publicTag: releaseField(release, "publicTag", "public_tag", normalizedTag),
+      internalTag: releaseField(release, "internalTag", "internal_tag", normalizedTag),
       internalVersion,
       publishedVersion,
-      versionLabel: optionalString(release.versionLabel || release.version_label || publishedVersion || normalizedTag),
+      versionLabel: releaseField(release, "versionLabel", "version_label", publishedVersion, normalizedTag),
       line: optionalString(line),
       sourceSha: optionalString(sourceSha),
-      channel: optionalString(release.channel || normalizedPublishEvidence?.channel || publish.channel),
+      channel: optionalString(firstTruthy(release.channel, normalizedPublishEvidence?.channel, publish.channel)),
       targetRef,
       releaseSha,
       releaseMaterialSha,
@@ -1411,28 +1407,28 @@ export function createReleasePassport({
       compatibilityFixture: "self-hosted",
       note: "Runner facts are recorded in artifact evidence; the protocol does not require self-hosted runners.",
     },
-    ...(normalizedPackageSet ? { packageSet: normalizedPackageSet } : {}),
-    ...(normalizedPublishSummary ? { publish: normalizedPublishSummary } : {}),
-    ...(anchorManifest ? { anchorManifest } : {}),
-    ...(versionMaterial ? { versionMaterial } : {}),
-    ...(normalizedTrustedPublishing ? { trustedPublishing: normalizedTrustedPublishing } : {}),
-    ...(normalizedTransaction ? { transaction: normalizedTransaction } : {}),
-    ...(normalizedPromotionRouting ? { promotionRouting: normalizedPromotionRouting } : {}),
-    ...(normalizedBuildSummary ? { buildSummary: normalizedBuildSummary } : {}),
-    ...(normalizedBuildFacts.length > 0 ? { buildFacts: normalizedBuildFacts } : {}),
-    ...(normalizedPlatformArtifactManifests.length > 0 ? { platformArtifactManifests: normalizedPlatformArtifactManifests } : {}),
-    ...(normalizedDistTagPromotionEvidence ? { distTagPromotion: normalizedDistTagPromotionEvidence } : {}),
-    ...(normalizedKfd1 ? { [normalizedKfd1.key || kfd1Metadata.key]: normalizedKfd1.passportSection } : {}),
-    ...(normalizedKfd2 ? { "kfd-2": normalizedKfd2 } : {}),
-    ...(normalizedKfd3 ? { [normalizedKfd3.key || "kfd-3"]: normalizedKfd3.passportSection } : {}),
-    ...(normalizedKfdSupport ? { kfdSupport: normalizedKfdSupport } : {}),
-    ...(normalizedKfdAgentHub ? { kfdAgentHub: normalizedKfdAgentHub } : {}),
-    ...(invariantPassports ? { invariantPassports } : {}),
-    ...(releaseEvidence.length > 0 ? { releaseEvidence } : {}),
-    ...(normalizedControllerReceipts.length > 0 ? { controllerReceipts: normalizedControllerReceipts } : {}),
-    ...(normalizedGitHubArtifactAttestations.length > 0
-      ? { githubArtifactAttestations: normalizedGitHubArtifactAttestations }
-      : {}),
+    ...optionalSections([
+      ["packageSet", normalizedPackageSet],
+      ["publish", normalizedPublishSummary],
+      ["anchorManifest", anchorManifest],
+      ["versionMaterial", versionMaterial],
+      ["trustedPublishing", normalizedTrustedPublishing],
+      ["transaction", normalizedTransaction],
+      ["promotionRouting", normalizedPromotionRouting],
+      ["buildSummary", normalizedBuildSummary],
+      ["buildFacts", normalizedBuildFacts],
+      ["platformArtifactManifests", normalizedPlatformArtifactManifests],
+      ["distTagPromotion", normalizedDistTagPromotionEvidence],
+      [firstTruthy(normalizedKfd1?.key, kfd1Metadata.key), normalizedKfd1?.passportSection],
+      ["kfd-2", normalizedKfd2],
+      [firstTruthy(normalizedKfd3?.key, "kfd-3"), normalizedKfd3?.passportSection],
+      ["kfdSupport", normalizedKfdSupport],
+      ["kfdAgentHub", normalizedKfdAgentHub],
+      ["invariantPassports", invariantPassports],
+      ["releaseEvidence", releaseEvidence],
+      ["controllerReceipts", normalizedControllerReceipts],
+      ["githubArtifactAttestations", normalizedGitHubArtifactAttestations],
+    ]),
     versionImpact: normalizedImpact.versionImpact,
     surfaceImpacts: normalizedImpact.surfaceImpacts,
     artifacts: [

package/packages/core/release-propagation-common.js

@@ -0,0 +1,64 @@
+import crypto from "node:crypto";
+
+const SUPPORTED_CHANNELS = new Set(["alpha", "release"]);
+
+export const RELEASE_PROPAGATION_PLAN_CONTRACT = "kungfu-buildchain-release-propagation-plan";
+
+export function stableJson(value) {
+  return `${JSON.stringify(sortJson(value), null, 2)}\n`;
+}
+
+export function sortJson(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortJson);
+  }
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  return Object.fromEntries(
+    Object.entries(value)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, entry]) => [key, sortJson(entry)]),
+  );
+}
+
+export function sha256Json(value) {
+  return crypto.createHash("sha256").update(stableJson(value)).digest("hex");
+}
+
+export function assertPlainObject(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value;
+}
+
+export function assertString(value, label) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+export function optionalString(value) {
+  return value === undefined || value === null ? "" : String(value).trim();
+}
+
+export function normalizeChannel(value, label) {
+  const channel = assertString(value, label);
+  if (!SUPPORTED_CHANNELS.has(channel)) {
+    throw new Error(`${label} must be alpha or release`);
+  }
+  return channel;
+}
+
+
+export function assertExactFields(value, fields, label) {
+  const object = assertPlainObject(value, label);
+  const actual = Object.keys(object).sort();
+  const expected = [...fields].sort();
+  if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+    throw new Error(`${label} has an invalid field set`);
+  }
+  return object;
+}

package/packages/core/release-propagation-execution-profile.js

@@ -0,0 +1,59 @@
+import { assertExactFields, assertString } from "./release-propagation-common.js";
+
+const WEB_SURFACE_EXECUTION_PROFILE_CONTRACT = "kungfu-buildchain-github-web-surface-execution";
+
+export function normalizeExecutionProfile(value, label) {
+  if (value === undefined || value === null) {
+    return null;
+  }
+  const profile = assertExactFields(value, [
+    "contract",
+    "workflow",
+    "productionReleaseLabel",
+    "productionReleaseHeadPrefix",
+    "productionStatusUrl",
+    "readbackUrls",
+    "updateCommand",
+    "prepareCommand",
+    "verifyCommand",
+  ], label);
+  if (profile.contract !== WEB_SURFACE_EXECUTION_PROFILE_CONTRACT) {
+    throw new Error(`${label}.contract must be ${WEB_SURFACE_EXECUTION_PROFILE_CONTRACT}`);
+  }
+  const productionStatusUrl = assertString(profile.productionStatusUrl, `${label}.productionStatusUrl`);
+  if (!/^https:\/\/[^?\s]+$/.test(productionStatusUrl)) {
+    throw new Error(`${label}.productionStatusUrl must be a stable HTTPS URL without query parameters`);
+  }
+  if (!Array.isArray(profile.readbackUrls) || profile.readbackUrls.length === 0) {
+    throw new Error(`${label}.readbackUrls must be a non-empty array`);
+  }
+  const readbackUrls = [...new Set(profile.readbackUrls.map((entry, index) => {
+    const url = assertString(entry, `${label}.readbackUrls[${index}]`);
+    if (!/^https:\/\/[^?\s]+$/.test(url)) {
+      throw new Error(`${label}.readbackUrls[${index}] must be a stable HTTPS URL without query parameters`);
+    }
+    return url;
+  }))].sort();
+  if (JSON.stringify(readbackUrls) !== JSON.stringify(profile.readbackUrls)) {
+    throw new Error(`${label}.readbackUrls must be sorted and unique`);
+  }
+  const command = (entry, field) => {
+    const text = assertString(entry, `${label}.${field}`);
+    if (/[\r\n]/.test(text)) {
+      throw new Error(`${label}.${field} must be a single-line command`);
+    }
+    return text;
+  };
+  return {
+    contract: WEB_SURFACE_EXECUTION_PROFILE_CONTRACT,
+    workflow: assertString(profile.workflow, `${label}.workflow`),
+    productionReleaseLabel: assertString(profile.productionReleaseLabel, `${label}.productionReleaseLabel`),
+    productionReleaseHeadPrefix: assertString(profile.productionReleaseHeadPrefix, `${label}.productionReleaseHeadPrefix`),
+    productionStatusUrl,
+    readbackUrls,
+    updateCommand: command(profile.updateCommand, "updateCommand"),
+    prepareCommand: command(profile.prepareCommand, "prepareCommand"),
+    verifyCommand: command(profile.verifyCommand, "verifyCommand"),
+  };
+}
+

package/packages/core/release-propagation-release.js

@@ -0,0 +1,196 @@
+import {
+  assertPlainObject,
+  assertString,
+  normalizeChannel,
+  optionalString,
+} from "./release-propagation-common.js";
+import { assertCommitSha } from "./release-propagation-work-control.js";
+
+function normalizeReleasePassport(passport = {}) {
+  if (!passport || typeof passport !== "object" || Array.isArray(passport)) {
+    throw new Error("upstreamRelease.releasePassport must be an object");
+  }
+  const normalized = {
+    url: assertString(passport.url, "upstreamRelease.releasePassport.url"),
+    sha256: assertString(passport.sha256 || passport.digest, "upstreamRelease.releasePassport.sha256"),
+  };
+  if (!/^[0-9a-f]{64}$/.test(normalized.sha256)) {
+    throw new Error("upstreamRelease.releasePassport.sha256 must be an exact SHA-256 digest");
+  }
+  if (/[?&](?:token|signature|x-amz-|x-goog-)/i.test(normalized.url)) {
+    throw new Error("upstreamRelease.releasePassport.url must not contain signed or credential parameters");
+  }
+  return normalized;
+}
+
+function normalizePackageFact(pkg = {}) {
+  if (!pkg || typeof pkg !== "object" || Array.isArray(pkg)) {
+    throw new Error("upstreamRelease.package must be an object");
+  }
+  const normalized = {
+    name: assertString(pkg.name, "upstreamRelease.package.name"),
+    version: assertString(pkg.version, "upstreamRelease.package.version"),
+    integrity: assertString(pkg.integrity, "upstreamRelease.package.integrity"),
+    gitHead: assertCommitSha(pkg.gitHead || pkg.git_head, "upstreamRelease.package.gitHead"),
+  };
+  if (!/^sha512-[A-Za-z0-9+/]+={0,2}$/.test(normalized.integrity)) {
+    throw new Error("upstreamRelease.package.integrity must be an exact sha512 SRI value");
+  }
+  return normalized;
+}
+
+function normalizeDigestUrlFact(value = {}, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  const normalized = {
+    url: assertString(value.url, `${label}.url`),
+    sha256: assertString(value.sha256 || value.digest, `${label}.sha256`),
+  };
+  if (!/^[0-9a-f]{64}$/.test(normalized.sha256)) {
+    throw new Error(`${label}.sha256 must be an exact SHA-256 digest`);
+  }
+  if (/[?&](?:token|signature|x-amz-|x-goog-)/i.test(normalized.url)) {
+    throw new Error(`${label}.url must not contain signed or credential parameters`);
+  }
+  return normalized;
+}
+
+function normalizeOptionalPathDigestUrlFact(value = undefined, label) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  const normalized = normalizeDigestUrlFact(value, label);
+  return {
+    path: optionalString(value.path),
+    bytes: value.bytes === undefined ? undefined : Number(value.bytes),
+    ...normalized,
+  };
+}
+
+function normalizePublicationArtifactFact(value = undefined) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  const artifact = assertPlainObject(value, "upstreamRelease.publicationArtifact");
+  return {
+    id: optionalString(artifact.id),
+    kind: optionalString(artifact.kind),
+    version: assertString(artifact.version, "upstreamRelease.publicationArtifact.version"),
+    canonicalUrl: assertString(
+      artifact.canonicalUrl || artifact.canonical_url,
+      "upstreamRelease.publicationArtifact.canonicalUrl",
+    ),
+    latestUrl: assertString(
+      artifact.latestUrl || artifact.latest_url,
+      "upstreamRelease.publicationArtifact.latestUrl",
+    ),
+    latestEvidenceUrl: optionalString(artifact.latestEvidenceUrl || artifact.latest_evidence_url),
+    immutableVersionUrl: assertString(
+      artifact.immutableVersionUrl || artifact.immutable_version_url || artifact.immutableVersionPrefix || artifact.immutable_version_prefix,
+      "upstreamRelease.publicationArtifact.immutableVersionUrl",
+    ),
+    immutableVersionPrefix: optionalString(artifact.immutableVersionPrefix || artifact.immutable_version_prefix),
+    registry: normalizeDigestUrlFact(artifact.registry, "upstreamRelease.publicationArtifact.registry"),
+    manifest: normalizeDigestUrlFact(artifact.manifest, "upstreamRelease.publicationArtifact.manifest"),
+    passport: normalizeDigestUrlFact(artifact.passport, "upstreamRelease.publicationArtifact.passport"),
+    primaryArtifact: normalizeOptionalPathDigestUrlFact(
+      artifact.primaryArtifact || artifact.primary_artifact,
+      "upstreamRelease.publicationArtifact.primaryArtifact",
+    ),
+    sourceBundle: normalizeOptionalPathDigestUrlFact(
+      artifact.sourceBundle || artifact.source_bundle,
+      "upstreamRelease.publicationArtifact.sourceBundle",
+    ),
+  };
+}
+
+export function normalizeUpstreamRelease(input) {
+  const release = assertPlainObject(input, "upstreamRelease");
+  const publicationArtifact = normalizePublicationArtifactFact(release.publicationArtifact || release.publication_artifact);
+  const packageFact = release.package === undefined ? undefined : normalizePackageFact(release.package);
+  if (!packageFact && !publicationArtifact) {
+    throw new Error("upstreamRelease requires package or publicationArtifact");
+  }
+  const repository = assertString(release.repository, "upstreamRelease.repository");
+  if (!/^[^/\s]+\/[^/\s]+$/.test(repository)) {
+    throw new Error("upstreamRelease.repository must be owner/repo");
+  }
+  const sourceSha = assertCommitSha(release.sourceSha || release.source_sha, "upstreamRelease.sourceSha");
+  const tagTargetSha = assertCommitSha(
+    release.tagTargetSha || release.tag_target_sha,
+    "upstreamRelease.tagTargetSha",
+  );
+  const version = packageFact?.version || publicationArtifact?.version || "";
+  const tag = assertString(release.tag, "upstreamRelease.tag");
+  if (tag !== `v${version}`) {
+    throw new Error("upstreamRelease.tag must exactly match the published version");
+  }
+  if (tagTargetSha !== sourceSha) {
+    throw new Error("upstreamRelease tag target must match sourceSha");
+  }
+  if (packageFact && packageFact.gitHead !== sourceSha) {
+    throw new Error("upstreamRelease package gitHead must match sourceSha");
+  }
+  if (packageFact && publicationArtifact && packageFact.version !== publicationArtifact.version) {
+    throw new Error("upstreamRelease package and publication artifact versions must match");
+  }
+  return {
+    repository,
+    channel: normalizeChannel(release.channel, "upstreamRelease.channel"),
+    tag,
+    tagTargetSha,
+    sourceSha,
+    package: packageFact,
+    publicationArtifact,
+    releasePassport: normalizeReleasePassport(release.releasePassport || release.release_passport),
+    siteBundle: release.siteBundle || release.site_bundle
+      ? {
+        manifestSha256: assertString(
+          release.siteBundle?.manifestSha256 || release.site_bundle?.manifest_sha256,
+          "upstreamRelease.siteBundle.manifestSha256",
+        ),
+      }
+      : undefined,
+  };
+}
+
+export function verifyReleaseLockBinding({ release, lock, downstream, propagationKey }) {
+  const normalizedRelease = normalizeUpstreamRelease(release);
+  const lockRelease = normalizeUpstreamRelease({
+    repository: lock.upstream?.repository,
+    channel: lock.upstream?.channel,
+    tag: lock.upstream?.tag,
+    tagTargetSha: lock.upstream?.tagTargetSha,
+    sourceSha: lock.upstream?.sourceSha,
+    package: lock.upstream?.package,
+    publicationArtifact: lock.upstream?.publicationArtifact,
+    releasePassport: lock.upstream?.releasePassport,
+    siteBundle: lock.upstream?.siteBundle,
+  });
+  if (JSON.stringify(lockRelease) !== JSON.stringify(normalizedRelease)) {
+    throw new Error("release propagation work upstream release disagrees with its lock");
+  }
+  const expectedCoordinates = {
+    target: lock.downstream?.node,
+    repository: lock.downstream?.repository,
+    channel: lock.downstream?.channel,
+    baseRef: lock.downstream?.baseRef,
+    branch: lock.propagation?.branch,
+    lockPath: lock.downstream?.lockPath,
+    propagationKey: lock.propagation?.propagationKey,
+  };
+  const actualCoordinates = {
+    target: downstream.target,
+    repository: downstream.repository,
+    channel: downstream.channel,
+    baseRef: downstream.baseRef,
+    branch: downstream.branch,
+    lockPath: downstream.lockPath,
+    propagationKey,
+  };
+  if (JSON.stringify(actualCoordinates) !== JSON.stringify(expectedCoordinates)) {
+    throw new Error("release propagation work downstream coordinates disagree with its lock");
+  }
+  return normalizedRelease;
+}