@kungfu-tech/buildchain 3.0.5-alpha.6 → 3.0.5-alpha.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "3.0.5-alpha.6",
+  "version": "3.0.5-alpha.7",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",

package/packages/core/buildchain-contract.js

@@ -72,6 +72,41 @@ function majorLineFromPackageVersion(version = "") {
   return match ? `v${match[1]}` : "v3";
 }
 
+function declarativeAuditableDemoSurface(root, pkg, majorLine) {
+  return surface(root, {
+    id: "declarative-auditable-demo",
+    kind: "workflow",
+    path: ".github/workflows/.declarative-auditable-demo.yml",
+    publicRef: `${pkg.repository ? "kungfu-systems/buildchain" : "buildchain"}/.github/workflows/.declarative-auditable-demo.yml@${majorLine}`,
+    requiredInputs: ["binary-artifact-name", "binary-artifact-digest", "renderer-image"],
+    requiredOutputs: [
+      "source-sha", "capture-artifact-name", "capture-artifact-digest",
+      "evidence-artifact-name", "evidence-artifact-digest", "publication-pr-url",
+    ],
+    breakingDefaults: {
+      scenarioPathDefault: ".buildchain/auditable-demo.json",
+      renderMediaDefault: false,
+      materializeDefault: false,
+      mediaProfileDefault: "responsive-web-delivery-v1",
+      artifactRetentionDaysDefault: 14,
+      executionBoundary: "exact-binary-network-none-secret-free-60-seconds",
+    },
+    optionalInputs: [
+      "buildchain-repository", "source-ref", "scenario-path", "render-media",
+      "media-profile", "materialize", "materialize-base-ref", "artifact-retention-days",
+    ],
+    guarantees: [
+      "one versioned declaration can contain multiple demos with multiple ordered literal argv steps",
+      "every demo uses the exact same-run standalone binary admitted by producer-owned artifact name and digest",
+      "capture runs without network or inherited secrets and retains independent native 1080p and 720p terminal dimensions",
+      "the generic adapter feeds the required auditable demo Gate and immutable renderer without product-specific glue",
+      "full rendering emits a content-addressed Release Passport and idempotent protected README update pull request",
+      "manual, alpha, and release callers use the same capture, Gate, renderer, passport, and materializer implementation",
+      "identity, compliance, Product System metadata, package metadata, registry history, scans, and generation grant no authority",
+    ],
+  });
+}
+
 export function createBuildchainContractWorld({
   root = process.cwd(),
   packageJson = undefined,
@@ -360,7 +395,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),
     surface(root, {
       id: "promote-buildchain-ref-action",
       kind: "action",

package/packages/core/buildchain-publication-authority.js

@@ -5,6 +5,7 @@ import { createPublicationAuthorityRegistry } from "./publication-authority.js";
 
 const DESCRIPTORS = Object.freeze([
   [".github/workflows/.auditable-demo.yml", "non-publication-oidc"],
+  [".github/workflows/.declarative-auditable-demo.yml", "governance-write"],
   [".github/workflows/.build.yml", "non-publication-oidc"],
   [".github/workflows/.release-candidate-promote.yml", "product-publication", true, ["npm-publish", "github-release", "channel-ref"], "trusted-publishing", "none", "fixed", "caller-bound"],
   [".github/workflows/.publication-authority.yml", "evidence-publication"],
@@ -19,6 +20,7 @@ const DESCRIPTORS = Object.freeze([
   [".github/workflows/binary-distribution.yml", "evidence-publication"],
   [".github/workflows/binary-release-assets.yml", "governance-write"],
   [".github/workflows/artifact-signing-authority.yml", "evidence-publication"],
+  [".github/workflows/auditable-demo.yml", "governance-write"],
   [".github/workflows/build-surface-fixture.yml", "non-publication-oidc"],
   [".github/workflows/build.yml", "non-publication-oidc"],
   [".github/workflows/buildchain-alpha-self-dogfood.yml", "non-publication-oidc"],

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

@@ -0,0 +1,386 @@
+import {
+  assertExactFields,
+  assertPlainObject,
+  assertString,
+  normalizeChannel,
+  optionalString,
+} from "./release-propagation-common.js";
+import { normalizeExecutionProfile } from "./release-propagation-execution-profile.js";
+import { assertCommitSha } from "./release-propagation-work-control.js";
+import {
+  createReleasePropagationWork,
+  planReleasePropagation,
+} from "./release-propagation.js";
+import { normalizeUpstreamRelease } from "./release-propagation-release.js";
+
+export const MANUAL_UPSTREAM_PICKUP_CONFIG_CONTRACT =
+  "kungfu-buildchain-manual-upstream-pickup";
+export const MANUAL_UPSTREAM_PICKUP_PLAN_CONTRACT =
+  "kungfu-buildchain-manual-upstream-pickup-plan";
+
+function assertRepository(value, label) {
+  const repository = assertString(value, label);
+  if (!/^[^/\s]+\/[^/\s]+$/.test(repository)) {
+    throw new Error(`${label} must be owner/repo`);
+  }
+  return repository;
+}
+
+function normalizeStringList(values, label) {
+  if (!Array.isArray(values) || values.length === 0) {
+    throw new Error(`${label} must be a non-empty array`);
+  }
+  const normalized = values.map((value, index) =>
+    assertString(value, `${label}[${index}]`),
+  );
+  const canonical = [...new Set(normalized)].sort();
+  if (JSON.stringify(normalized) !== JSON.stringify(canonical)) {
+    throw new Error(`${label} must be sorted and unique`);
+  }
+  return canonical;
+}
+
+function normalizeRuntime(value) {
+  const runtime = assertExactFields(
+    value,
+    ["package", "version"],
+    "manual pickup runtime",
+  );
+  return {
+    package: assertString(runtime.package, "manual pickup runtime.package"),
+    version: assertString(runtime.version, "manual pickup runtime.version"),
+  };
+}
+
+function normalizeDownstream(value) {
+  const downstream = assertExactFields(
+    value,
+    ["id", "repository", "baseRef", "executionProfile"],
+    "manual pickup downstream",
+  );
+  return {
+    id: assertString(downstream.id, "manual pickup downstream.id"),
+    repository: assertRepository(
+      downstream.repository,
+      "manual pickup downstream.repository",
+    ),
+    baseRef: assertString(
+      downstream.baseRef,
+      "manual pickup downstream.baseRef",
+    ),
+    executionProfile: normalizeExecutionProfile(
+      downstream.executionProfile,
+      "manual pickup downstream.executionProfile",
+    ),
+  };
+}
+
+function normalizeSource(value, index) {
+  const label = `manual pickup sources[${index}]`;
+  const source = assertExactFields(
+    value,
+    [
+      "id",
+      "repository",
+      "package",
+      "lockPath",
+      "distTags",
+      "workflowPaths",
+      "workflowRefs",
+    ],
+    label,
+  );
+  const distTags = assertExactFields(
+    source.distTags,
+    ["alpha", "release"],
+    `${label}.distTags`,
+  );
+  return {
+    id: assertString(source.id, `${label}.id`),
+    repository: assertRepository(source.repository, `${label}.repository`),
+    package: assertString(source.package, `${label}.package`),
+    lockPath: assertString(source.lockPath, `${label}.lockPath`),
+    distTags: {
+      alpha: assertString(distTags.alpha, `${label}.distTags.alpha`),
+      release: assertString(distTags.release, `${label}.distTags.release`),
+    },
+    workflowPaths: normalizeStringList(
+      source.workflowPaths,
+      `${label}.workflowPaths`,
+    ),
+    workflowRefs: normalizeStringList(
+      source.workflowRefs,
+      `${label}.workflowRefs`,
+    ),
+  };
+}
+
+export function normalizeManualUpstreamPickupConfig(input) {
+  const config = assertExactFields(
+    input,
+    ["schemaVersion", "contract", "runtime", "downstream", "sources"],
+    "manual upstream pickup config",
+  );
+  if (
+    config.schemaVersion !== 1 ||
+    config.contract !== MANUAL_UPSTREAM_PICKUP_CONFIG_CONTRACT
+  ) {
+    throw new Error(
+      `manual upstream pickup config must use ${MANUAL_UPSTREAM_PICKUP_CONFIG_CONTRACT} v1`,
+    );
+  }
+  if (!Array.isArray(config.sources) || config.sources.length === 0) {
+    throw new Error(
+      "manual upstream pickup config sources must be a non-empty array",
+    );
+  }
+  const sources = config.sources.map(normalizeSource);
+  const ids = sources.map((source) => source.id);
+  if (new Set(ids).size !== ids.length)
+    throw new Error("manual pickup source ids must be unique");
+  return {
+    schemaVersion: 1,
+    contract: MANUAL_UPSTREAM_PICKUP_CONFIG_CONTRACT,
+    runtime: normalizeRuntime(config.runtime),
+    downstream: normalizeDownstream(config.downstream),
+    sources,
+  };
+}
+
+function decodePayload(attestation, label) {
+  const encoded = attestation?.bundle?.dsseEnvelope?.payload;
+  if (!encoded) throw new Error(`${label} is missing a DSSE payload`);
+  try {
+    return JSON.parse(Buffer.from(encoded, "base64").toString("utf8"));
+  } catch {
+    throw new Error(`${label} DSSE payload is not valid JSON`);
+  }
+}
+
+function repositoryFromUrl(value) {
+  return String(value || "")
+    .replace(/^git\+/, "")
+    .replace(/^https:\/\/github\.com\//, "")
+    .replace(/\.git$/, "");
+}
+
+export function resolveNpmRegistryRelease({
+  source: sourceInput,
+  channel,
+  packageMetadata,
+  attestations,
+}) {
+  const source = normalizeSource(sourceInput, 0);
+  const normalizedChannel = normalizeChannel(channel, "manual pickup channel");
+  const metadata = assertPlainObject(packageMetadata, "npm package metadata");
+  if (metadata.name !== source.package)
+    throw new Error("npm package name disagrees with manual pickup source");
+  if (
+    repositoryFromUrl(metadata.repository?.url || metadata.repository) !==
+    source.repository
+  ) {
+    throw new Error(
+      "npm package repository disagrees with manual pickup source",
+    );
+  }
+  const version = assertString(
+    metadata.version,
+    "npm package metadata.version",
+  );
+  const integrity = assertString(
+    metadata.dist?.integrity,
+    "npm package metadata.dist.integrity",
+  );
+  const attestationUrl = assertString(
+    metadata.dist?.attestations?.url,
+    "npm package metadata.dist.attestations.url",
+  );
+  const response = assertPlainObject(attestations, "npm attestations response");
+  const slsa = (response.attestations || []).find(
+    (entry) => entry.predicateType === "https://slsa.dev/provenance/v1",
+  );
+  if (!slsa) throw new Error("npm package does not expose SLSA provenance v1");
+  const statement = decodePayload(slsa, "npm SLSA provenance");
+  if (statement.predicateType !== "https://slsa.dev/provenance/v1") {
+    throw new Error(
+      "npm SLSA statement predicate type disagrees with its envelope",
+    );
+  }
+  const expectedSubject = `pkg:npm/${encodeURIComponent(source.package)}@${version}`;
+  const subject = (statement.subject || []).find(
+    (entry) => entry.name === expectedSubject,
+  );
+  if (!subject?.digest?.sha512)
+    throw new Error("npm SLSA provenance is missing the exact package subject");
+  const workflow =
+    statement.predicate?.buildDefinition?.externalParameters?.workflow || {};
+  const workflowRepository = repositoryFromUrl(workflow.repository);
+  if (workflowRepository !== source.repository) {
+    throw new Error(
+      "npm SLSA workflow repository disagrees with manual pickup source",
+    );
+  }
+  if (!source.workflowPaths.includes(workflow.path)) {
+    throw new Error(
+      "npm SLSA workflow path is not admitted by the manual pickup source",
+    );
+  }
+  if (!source.workflowRefs.includes(workflow.ref)) {
+    throw new Error(
+      "npm SLSA workflow ref is not admitted by the manual pickup source",
+    );
+  }
+  const dependency = (
+    statement.predicate?.buildDefinition?.resolvedDependencies || []
+  ).find(
+    (entry) =>
+      repositoryFromUrl(String(entry.uri || "").split("@")[0]) ===
+      source.repository,
+  );
+  const sourceSha = assertCommitSha(
+    dependency?.digest?.gitCommit,
+    "npm SLSA source commit",
+  );
+  const runUrl = assertString(
+    statement.predicate?.runDetails?.metadata?.invocationId,
+    "npm SLSA invocation URL",
+  );
+  return normalizeUpstreamRelease({
+    repository: source.repository,
+    channel: normalizedChannel,
+    tag: "",
+    tagTargetSha: "",
+    sourceSha,
+    package: {
+      name: source.package,
+      version,
+      integrity,
+      gitHead: optionalString(metadata.gitHead),
+    },
+    registryProvenance: {
+      registry: "https://registry.npmjs.org",
+      attestationUrl,
+      predicateType: slsa.predicateType,
+      subjectSha512: subject.digest.sha512,
+      repository: source.repository,
+      sourceSha,
+      workflowPath: workflow.path,
+      workflowRef: workflow.ref,
+      runUrl,
+    },
+  });
+}
+
+function pickupGraph(config, source) {
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-release-propagation-graph",
+    nodes: [
+      { id: source.id, repository: source.repository, package: source.package },
+      {
+        id: config.downstream.id,
+        repository: config.downstream.repository,
+        baseRef: config.downstream.baseRef,
+        lockPath: source.lockPath,
+        executionProfile: config.downstream.executionProfile,
+      },
+    ],
+    edges: [
+      {
+        id: `${source.id}-manual-pickup`,
+        from: source.id,
+        to: config.downstream.id,
+        channels: ["alpha", "release"],
+        channelPolicy: "preserve",
+        lockPath: source.lockPath,
+        prBaseRef: config.downstream.baseRef,
+      },
+    ],
+  };
+}
+
+export function createManualUpstreamPickupPlan({
+  config: configInput,
+  sourceId,
+  channel,
+  currentVersion,
+  upstreamRelease,
+}) {
+  const config = normalizeManualUpstreamPickupConfig(configInput);
+  const source = config.sources.find((entry) => entry.id === sourceId);
+  if (!source)
+    throw new Error(`manual pickup source is not configured: ${sourceId}`);
+  const release = normalizeUpstreamRelease(upstreamRelease);
+  const normalizedChannel = normalizeChannel(channel, "manual pickup channel");
+  if (
+    release.repository !== source.repository ||
+    release.package?.name !== source.package
+  ) {
+    throw new Error("manual pickup release disagrees with the selected source");
+  }
+  if (release.channel !== normalizedChannel)
+    throw new Error("manual pickup release channel disagrees with the request");
+  const installedVersion = assertString(
+    currentVersion,
+    "manual pickup currentVersion",
+  );
+  const status =
+    installedVersion === release.package.version
+      ? "current"
+      : "update-available";
+  const propagationPlan =
+    status === "current"
+      ? null
+      : planReleasePropagation({
+          graph: pickupGraph(config, source),
+          upstreamRelease: release,
+          sourceNode: source.id,
+        });
+  return {
+    schemaVersion: 1,
+    contract: MANUAL_UPSTREAM_PICKUP_PLAN_CONTRACT,
+    invocation: "downstream-manual",
+    automaticTrigger: false,
+    runtime: config.runtime,
+    source: {
+      id: source.id,
+      repository: source.repository,
+      package: source.package,
+      channel: normalizedChannel,
+      distTag: source.distTags[normalizedChannel],
+    },
+    currentVersion: installedVersion,
+    resolvedVersion: release.package.version,
+    status,
+    upstreamRelease: release,
+    propagationPlan,
+  };
+}
+
+export function createManualUpstreamPickupCapture({
+  plan,
+  expectedDownstreamBaseSha,
+}) {
+  const pickup = assertPlainObject(plan, "manual pickup plan");
+  if (
+    pickup.contract !== MANUAL_UPSTREAM_PICKUP_PLAN_CONTRACT ||
+    pickup.schemaVersion !== 1
+  ) {
+    throw new Error("manual pickup plan must use the v1 contract");
+  }
+  if (pickup.status === "current") {
+    return { plan: pickup, work: null, nextAction: "none" };
+  }
+  if (pickup.status !== "update-available" || !pickup.propagationPlan) {
+    throw new Error("manual pickup plan has an invalid status");
+  }
+  const expectedBaseSha = assertCommitSha(
+    expectedDownstreamBaseSha,
+    "expectedDownstreamBaseSha",
+  );
+  const work = createReleasePropagationWork({
+    plan: pickup.propagationPlan,
+    expectedDownstreamBaseSha: expectedBaseSha,
+  });
+  return { plan: pickup, work, nextAction: "claim" };
+}

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

@@ -31,7 +31,9 @@ function normalizePackageFact(pkg = {}) {
     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"),
+    gitHead: pkg.gitHead || pkg.git_head
+      ? 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");
@@ -39,6 +41,57 @@ function normalizePackageFact(pkg = {}) {
   return normalized;
 }
 
+function normalizeRegistryProvenance(value, packageFact, repository, sourceSha) {
+  if (!value) return undefined;
+  if (!packageFact) throw new Error("upstreamRelease.registryProvenance requires package");
+  const input = assertPlainObject(value, "upstreamRelease.registryProvenance");
+  const normalized = {
+    registry: assertString(input.registry, "upstreamRelease.registryProvenance.registry"),
+    attestationUrl: assertString(input.attestationUrl || input.attestation_url, "upstreamRelease.registryProvenance.attestationUrl"),
+    predicateType: assertString(input.predicateType || input.predicate_type, "upstreamRelease.registryProvenance.predicateType"),
+    subjectSha512: assertString(input.subjectSha512 || input.subject_sha512, "upstreamRelease.registryProvenance.subjectSha512"),
+    repository: assertString(input.repository, "upstreamRelease.registryProvenance.repository"),
+    sourceSha: assertCommitSha(input.sourceSha || input.source_sha, "upstreamRelease.registryProvenance.sourceSha"),
+    workflowPath: assertString(input.workflowPath || input.workflow_path, "upstreamRelease.registryProvenance.workflowPath"),
+    workflowRef: assertString(input.workflowRef || input.workflow_ref, "upstreamRelease.registryProvenance.workflowRef"),
+    runUrl: assertString(input.runUrl || input.run_url, "upstreamRelease.registryProvenance.runUrl"),
+  };
+  if (normalized.registry !== "https://registry.npmjs.org") throw new Error("upstreamRelease.registryProvenance.registry must be the public npm registry");
+  if (!normalized.attestationUrl.startsWith("https://registry.npmjs.org/-/npm/v1/attestations/")) throw new Error("upstreamRelease.registryProvenance.attestationUrl must use the npm attestation API");
+  if (normalized.predicateType !== "https://slsa.dev/provenance/v1") throw new Error("upstreamRelease.registryProvenance must use SLSA provenance v1");
+  if (!/^[0-9a-f]{128}$/.test(normalized.subjectSha512)) throw new Error("upstreamRelease.registryProvenance.subjectSha512 must be an exact SHA-512 digest");
+  const sriDigest = Buffer.from(packageFact.integrity.slice("sha512-".length), "base64").toString("hex");
+  if (normalized.subjectSha512 !== sriDigest) throw new Error("upstreamRelease registry provenance subject must match package integrity");
+  if (normalized.repository !== repository || normalized.sourceSha !== sourceSha) throw new Error("upstreamRelease registry provenance source must match the release envelope");
+  return normalized;
+}
+
+function normalizeReleaseEvidence(release, packageFact, repository, sourceSha, version) {
+  const registryProvenance = normalizeRegistryProvenance(
+    release.registryProvenance || release.registry_provenance,
+    packageFact,
+    repository,
+    sourceSha,
+  );
+  const tag = optionalString(release.tag);
+  const target = release.tagTargetSha || release.tag_target_sha;
+  const tagTargetSha = target ? assertCommitSha(target, "upstreamRelease.tagTargetSha") : "";
+  if (!registryProvenance) {
+    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");
+  } else if ((tag && tag !== `v${version}`) || (tagTargetSha && tagTargetSha !== sourceSha)) {
+    throw new Error("upstreamRelease optional tag evidence must match the provenance source");
+  }
+  const passportInput = release.releasePassport || release.release_passport;
+  return {
+    tag,
+    tagTargetSha,
+    registryProvenance,
+    releasePassport: passportInput ? normalizeReleasePassport(passportInput) : undefined,
+  };
+}
+
 function normalizeDigestUrlFact(value = {}, label) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw new Error(`${label} must be an object`);
@@ -117,33 +170,22 @@ export function normalizeUpstreamRelease(input) {
     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");
-  }
+  const evidence = normalizeReleaseEvidence(release, packageFact, repository, sourceSha, version);
+  if (!evidence.registryProvenance && !evidence.releasePassport) normalizeReleasePassport();
   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,
+    tag: evidence.tag,
+    tagTargetSha: evidence.tagTargetSha,
     sourceSha,
     package: packageFact,
     publicationArtifact,
-    releasePassport: normalizeReleasePassport(release.releasePassport || release.release_passport),
+    releasePassport: evidence.releasePassport,
+    registryProvenance: evidence.registryProvenance,
     siteBundle: release.siteBundle || release.site_bundle
       ? {
         manifestSha256: assertString(
@@ -166,6 +208,7 @@ export function verifyReleaseLockBinding({ release, lock, downstream, propagatio
     package: lock.upstream?.package,
     publicationArtifact: lock.upstream?.publicationArtifact,
     releasePassport: lock.upstream?.releasePassport,
+    registryProvenance: lock.upstream?.registryProvenance,
     siteBundle: lock.upstream?.siteBundle,
   });
   if (JSON.stringify(lockRelease) !== JSON.stringify(normalizedRelease)) {

package/packages/core/release-propagation.js

@@ -219,6 +219,7 @@ export function createReleasePropagationLock({
       package: upstreamRelease.package,
       publicationArtifact: upstreamRelease.publicationArtifact,
       releasePassport: upstreamRelease.releasePassport,
+      registryProvenance: upstreamRelease.registryProvenance,
       siteBundle: upstreamRelease.siteBundle,
     },
     downstream: {
@@ -406,7 +407,7 @@ export function createReleasePropagationReceipt({
             name: upstreamRelease.package.name,
             version: upstreamRelease.package.version,
             integrity: upstreamRelease.package.integrity,
-            gitHead: upstreamRelease.package.gitHead,
+            gitHead: upstreamRelease.package.gitHead || null,
           }
         : null,
     },
@@ -414,7 +415,8 @@ export function createReleasePropagationReceipt({
       state: release.channel === "alpha" ? "complete" : "not-applicable",
       evidence: release.channel === "alpha"
         ? {
-            releasePassportSha256: upstreamRelease.releasePassport.sha256,
+            releasePassportSha256: upstreamRelease.releasePassport?.sha256 || null,
+            registryProvenance: upstreamRelease.registryProvenance || null,
             tag: upstreamRelease.tag,
           }
         : null,
@@ -476,3 +478,11 @@ export {
   createPackageReleasePropagationCapture,
   normalizePackageReleasePropagationConfig,
 } from "./release-propagation-capture.js";
+export {
+  MANUAL_UPSTREAM_PICKUP_CONFIG_CONTRACT,
+  MANUAL_UPSTREAM_PICKUP_PLAN_CONTRACT,
+  createManualUpstreamPickupCapture,
+  createManualUpstreamPickupPlan,
+  normalizeManualUpstreamPickupConfig,
+  resolveNpmRegistryRelease,
+} from "./release-propagation-pickup.js";