@kungfu-tech/buildchain 4.0.2-alpha.9 → 4.0.3-alpha.0

package/scripts/{v4-platform-stage-checkpoint-rehearsal.mjs → platform-stage-checkpoint-rehearsal.mjs}

@@ -5,14 +5,14 @@ import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
-import { v4CanonicalBytes } from "../packages/core/v4-canonical-contracts.js";
-import { V4StageCapsuleLocalStore } from "../packages/core/v4-stage-capsule-local-store.js";
-import { v4StageCapsuleBlobRoot } from "../packages/core/v4-stage-capsule-store.js";
+import { domainCanonicalBytes } from "../packages/core/canonical-contracts.js";
+import { StageCapsuleLocalStore } from "../packages/core/stage-capsule-local-store.js";
+import { stageCapsuleBlobRoot } from "../packages/core/stage-capsule-store.js";
 import {
-  emitV4PlatformStageCheckpoint,
-  restoreV4PlatformStageCheckpoint,
-  validateV4PlatformStageCheckpointDeclaration,
-} from "../packages/core/v4-platform-stage-checkpoints.js";
+  emitPlatformStageCheckpoint,
+  restorePlatformStageCheckpoint,
+  validatePlatformStageCheckpointDeclaration,
+} from "../packages/core/platform-stage-checkpoints.js";
 
 const repoRoot = path.resolve(
   path.dirname(fileURLToPath(import.meta.url)),
@@ -32,10 +32,10 @@ function required(name) {
 }
 
 function readDeclaration() {
-  return validateV4PlatformStageCheckpointDeclaration(
+  return validatePlatformStageCheckpointDeclaration(
     JSON.parse(
       fs.readFileSync(
-        path.join(repoRoot, "architecture/v4-platform-stage-checkpoints.json"),
+        path.join(repoRoot, "architecture/platform-stage-checkpoints.json"),
         "utf8",
       ),
     ),
@@ -49,12 +49,12 @@ function stageFor(declaration, stageId) {
 }
 
 function rooted(label) {
-  return v4StageCapsuleBlobRoot(Buffer.from(`${label}\n`, "utf8"));
+  return stageCapsuleBlobRoot(Buffer.from(`${label}\n`, "utf8"));
 }
 
 function writeJson(file, value) {
   fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, v4CanonicalBytes(value), { flag: "wx" });
+  fs.writeFileSync(file, domainCanonicalBytes(value), { flag: "wx" });
 }
 
 function emit({ workRoot, platformId, stageId, recordedAt }) {
@@ -87,11 +87,11 @@ function emit({ workRoot, platformId, stageId, recordedAt }) {
   const productionOutputRoots = Object.fromEntries(
     Object.entries(outputs).map(([name, bytes]) => [
       name,
-      v4StageCapsuleBlobRoot(bytes),
+      stageCapsuleBlobRoot(bytes),
     ]),
   );
-  const store = new V4StageCapsuleLocalStore(path.join(workRoot, "store"));
-  const result = emitV4PlatformStageCheckpoint({
+  const store = new StageCapsuleLocalStore(path.join(workRoot, "store"));
+  const result = emitPlatformStageCheckpoint({
     declaration,
     platformId,
     stageId,
@@ -131,8 +131,8 @@ function restore({ workRoot, platformId, stageId, recordedAt }) {
   );
   if (emission.platform !== platformId || emission.stage !== stageId)
     throw new Error("emission identity does not match restore request");
-  const store = new V4StageCapsuleLocalStore(path.join(workRoot, "store"));
-  const result = restoreV4PlatformStageCheckpoint({
+  const store = new StageCapsuleLocalStore(path.join(workRoot, "store"));
+  const result = restorePlatformStageCheckpoint({
     declaration,
     expectedPlatform: platformId,
     expectedStage: stageId,
@@ -201,7 +201,7 @@ else if (action === "rehearse") {
     providerCredentialsUsed: restored.providerCredentialsUsed,
   };
   writeJson(path.join(common.workRoot, "evidence.json"), evidence);
-  process.stdout.write(v4CanonicalBytes(evidence));
+  process.stdout.write(domainCanonicalBytes(evidence));
 } else {
   throw new Error("action must be emit, restore, or rehearse");
 }

package/scripts/{v4-product-publication-intent.mjs → product-publication-intent.mjs}

@@ -5,8 +5,8 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 
 import { spawnSyncCommand } from "../packages/core/spawn-command.js";
-import { selectV4ProductPublicationIntent } from "../packages/core/v4-product-publication.js";
-import { v4ContentRoot } from "../packages/core/v4-canonical-contracts.js";
+import { selectProductPublicationIntent } from "../packages/core/product-publication.js";
+import { domainContentRoot } from "../packages/core/canonical-contracts.js";
 
 function env(name, required = false) {
   const value = String(process.env[name] || "").trim();
@@ -18,7 +18,8 @@ function readJson(file) {
   return JSON.parse(fs.readFileSync(path.resolve(file), "utf8"));
 }
 
-function packageName() {
+function packageName(artifactKind) {
+  if (artifactKind !== "npm") return "";
   const declared = env("BUILDCHAIN_PUBLISH_PACKAGE_MAIN");
   if (declared) return declared;
   const manifestPath = env("BUILDCHAIN_SEALED_BUNDLE_MANIFEST", true);
@@ -58,36 +59,50 @@ function writeOutput(name, value) {
   fs.appendFileSync(output, `${name}=${String(value)}\n`);
 }
 
-export function resolveV4ProductPublicationIntent() {
-  const name = packageName();
+export function resolveProductPublicationIntent() {
+  const artifactKind = env("BUILDCHAIN_PUBLISH_ARTIFACT_KIND") || "npm";
+  const name = packageName(artifactKind);
   const sourceSha = env("BUILDCHAIN_SOURCE_SHA", true);
-  const manifest = readJson(env("BUILDCHAIN_SEALED_BUNDLE_MANIFEST", true));
+  const manifestPath = env(
+    "BUILDCHAIN_SEALED_BUNDLE_MANIFEST",
+    artifactKind !== "custom",
+  );
+  const manifest = manifestPath ? readJson(manifestPath) : null;
   const requiredArtifacts = readJson(
     env("BUILDCHAIN_REQUIRED_ARTIFACTS_PATH", true),
   );
   const channel = env("BUILDCHAIN_CHANNEL", true);
-  const intent = selectV4ProductPublicationIntent({
+  const intent = selectProductPublicationIntent({
     channel,
     targetRef: env("BUILDCHAIN_TARGET_REF", true),
     sourceSha,
     sourceTimestamp: env("BUILDCHAIN_SOURCE_TIMESTAMP", true),
     repository: env("BUILDCHAIN_REPOSITORY", true),
+    artifactKind,
     packageName: name,
+    ...(manifest?.npmPackages
+      ? {
+          npmPackages: manifest.npmPackages.map((entry) => ({
+            ...entry,
+            sha256: `sha256:${entry.sha256}`,
+          })),
+        }
+      : {}),
     distTag:
       env("BUILDCHAIN_PUBLISH_DIST_TAG") ||
       (channel === "alpha" ? "alpha" : "latest"),
-    sealedBundleRoot: manifest.root,
-    requiredArtifactsRoot: v4ContentRoot(
+    sealedBundleRoot: manifest?.root,
+    requiredArtifactsRoot: domainContentRoot(
       "v4-product-required-artifacts",
       requiredArtifacts,
     ),
     candidateVersion: env("BUILDCHAIN_CANDIDATE_VERSION", true),
     recoveredVersion: env("BUILDCHAIN_RECOVERED_PUBLICATION_VERSION"),
-    observedVersions: observedVersions(name),
+    observedVersions: artifactKind === "npm" ? observedVersions(name) : [],
   });
   const outputPath = path.resolve(
     env("BUILDCHAIN_PRODUCT_PUBLICATION_INTENT_PATH") ||
-      ".buildchain/release-candidate/v4-product-publication-intent.json",
+      ".buildchain/release-candidate/product-publication-intent.json",
   );
   fs.mkdirSync(path.dirname(outputPath), { recursive: true });
   fs.writeFileSync(outputPath, `${JSON.stringify(intent, null, 2)}\n`);
@@ -95,7 +110,7 @@ export function resolveV4ProductPublicationIntent() {
   writeOutput("exact-tag", intent.exactTag);
   writeOutput("intent-path", outputPath);
   writeOutput("intent-root", intent.intentRoot);
-  return { name, intent, outputPath };
+  return { name: name || artifactKind, intent, outputPath };
 }
 
 if (
@@ -103,7 +118,7 @@ if (
   import.meta.url === pathToFileURL(process.argv[1]).href
 ) {
   try {
-    const result = resolveV4ProductPublicationIntent();
+    const result = resolveProductPublicationIntent();
     process.stdout.write(
       `v4 product publication intent: ${result.name}@${result.intent.version} (${result.intent.mode})\n`,
     );

package/scripts/publication-candidate-kind.mjs

@@ -0,0 +1,93 @@
+import fs from "node:fs";
+import path from "node:path";
+import { ociPublicationTag } from "../packages/core/oci-publication-graph.js";
+import { verifyOciPublicationBundle } from "../packages/core/oci-publication-bundle.js";
+
+export function resolveOciCandidate({ payloadRoot, passport }) {
+  const matches = [];
+  function visit(directory) {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      if (entry.isSymbolicLink())
+        throw new Error("OCI candidate cannot contain symlinks");
+      const file = path.join(directory, entry.name);
+      if (entry.isDirectory()) visit(file);
+      else if (entry.name === "oci-family.json") matches.push(file);
+    }
+  }
+  visit(payloadRoot);
+  if (matches.length !== 1)
+    throw new Error("OCI candidate requires exactly one sealed image family");
+  const manifest = JSON.parse(fs.readFileSync(matches[0]));
+  const bundleRoot = path.dirname(matches[0]);
+  const verified = verifyOciPublicationBundle({
+    bundleRoot,
+    manifest,
+    repository: passport.repository,
+    sourceSha: passport.source.headSha,
+    version: passport.target.version,
+  });
+  return {
+    root: bundleRoot,
+    manifest: verified.manifest,
+    requiredArtifacts: manifest.images.map((image) => ({
+      kind: "oci",
+      name: image.repository,
+      ref: ociPublicationTag(image, manifest.version),
+      digest: image.digest,
+      platform: image.platform,
+      required: true,
+    })),
+  };
+}
+
+export function resolveRecoveredPublicationVersion({
+  artifactVersion,
+  channel,
+  rematerializeOnResume = false,
+} = {}) {
+  const version = String(artifactVersion || "").trim(),
+    match = version.match(
+      /^(\d+\.\d+\.\d+)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u,
+    );
+  if (!match)
+    throw new Error(
+      `recovered npm artifact has invalid publication version: ${version || "<empty>"}`,
+    );
+  return channel === "release" && rematerializeOnResume ? match[1] : version;
+}
+export function resolveRecoveredCandidateVersion({
+  artifactVersion,
+  publicationVersion,
+  channel,
+  rematerializeOnResume = false,
+  targetRef = "",
+  candidateRef = "",
+} = {}) {
+  const version = String(artifactVersion || "").trim(),
+    target = String(targetRef || "").replace(/^refs\/heads\//u, ""),
+    candidate = String(candidateRef || "").replace(/^refs\/heads\//u, "");
+  if (channel !== "release" || !rematerializeOnResume) return version;
+  const prefix = `publish-gate/${target}/`;
+  if (!target || !candidate.startsWith(prefix))
+    throw new Error(
+      `stable recovery candidate ref must descend from ${prefix || "publish-gate/<target>/"}`,
+    );
+  const candidateVersion = candidate.slice(prefix.length);
+  if (!/^\d+\.\d+\.\d+-alpha\.\d+$/u.test(candidateVersion))
+    throw new Error(
+      `stable recovery candidate ref must bind an exact alpha version, got ${candidateVersion || "<empty>"}`,
+    );
+  if (candidateVersion.replace(/-alpha\.\d+$/u, "") !== publicationVersion)
+    throw new Error(
+      `stable recovery candidate ${candidateVersion} does not match publication ${publicationVersion || "<empty>"}`,
+    );
+  if (
+    (version.match(
+      /^(\d+\.\d+\.\d+)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u,
+    )?.[1] || "") !== publicationVersion
+  )
+    throw new Error(
+      `recovered npm artifact version ${version || "<empty>"} does not match publication ${publicationVersion}`,
+    );
+  return candidateVersion;
+}

package/scripts/publication-candidate-sealer.mjs

@@ -1,3 +1,4 @@
+import { resolveOciCandidate } from "./publication-candidate-kind.mjs";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
@@ -69,7 +70,7 @@ export function createResolvedPublicationSealedBundle({
   });
   const main = resolvedNpmArtifacts.find((entry) => entry.metadata.role === "main")
     || (resolvedNpmArtifacts.length === 1 ? resolvedNpmArtifacts[0] : undefined);
-  if (!main) throw new Error("candidate npm payload set has no unique main package tarball");
+  if (!main || resolvedNpmArtifacts.filter((entry) => entry.metadata.role === "main").length > 1) throw new Error("candidate npm payload set has no unique main package tarball");
   const selectedReleaseAssets = (releaseAssetPaths.length > 0
     ? releaseAssetPaths
     : resolvedNpmArtifacts.map((entry) => entry.file.absolutePath))
@@ -88,6 +89,12 @@ export function createResolvedPublicationSealedBundle({
     releaseCandidateRoot: `sha256:${normalizeSha256(releaseCandidateRoot, "releaseCandidateRoot")}`,
     files: files.map(({ path: filePath, size, sha256 }) => ({ path: filePath, size, sha256 })),
   };
+  if (resolvedNpmArtifacts.length > 1) {
+    candidatePayload.npmPackages = resolvedNpmArtifacts.map(({file, metadata}) => ({
+      name: metadata.name, version: metadata.ref, role: metadata.role,
+      path: file.path, size: file.size, sha256: file.sha256, integrity: metadata.integrity,
+    }));
+  }
   const candidate = {
     ...candidatePayload,
     candidateDigest: publicationArtifactCandidateDigest(candidatePayload),
@@ -102,3 +109,11 @@ export function createResolvedPublicationSealedBundle({
   });
   return { root: resolvedRoot, manifest, npmArtifacts: resolvedNpmArtifacts, files };
 }
+
+export function resolveCandidatePublicationBundle({ kind, payloadDir, passport, runtimeSha, npmArtifacts, releaseAssetPaths }) {
+  if (kind === "oci") return resolveOciCandidate({ payloadRoot: payloadDir, passport });
+  if (kind !== "npm") return undefined;
+  return createResolvedPublicationSealedBundle({ bundleRoot: payloadDir, repository: passport.repository,
+    sourceSha: passport.source?.headSha, sourceTreeSha: passport.source?.treeHash,
+    runtimeSha, releaseCandidateRoot: passport.candidateHash, npmArtifacts, releaseAssetPaths });
+}

package/scripts/{v4-publication-rehearsal-fixture.mjs → publication-rehearsal-fixture.mjs}

@@ -6,9 +6,9 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import {
-  createV4PublicationRehearsalCapsule,
-  executeV4PublicationRehearsal,
-} from "../packages/core/v4-publication-rehearsal.js";
+  createDomainPublicationRehearsalCapsule,
+  executeDomainPublicationRehearsal,
+} from "../packages/core/publication-rehearsal.js";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const fixtureRoot = path.join(
@@ -61,7 +61,7 @@ async function generated() {
     path: relative,
     root: files.find((entry) => entry.path === relative).root,
   });
-  const capsule = createV4PublicationRehearsalCapsule({
+  const capsule = createDomainPublicationRehearsalCapsule({
     source: {
       repository: "kungfu-systems/buildchain",
       revision: "bc12cd0ff18a7e1d918777ea093c169349952d34",
@@ -100,7 +100,7 @@ async function generated() {
   });
   const vectors = [];
   for (const platform of ["linux", "macos", "windows"]) {
-    const result = await executeV4PublicationRehearsal({
+    const result = await executeDomainPublicationRehearsal({
       capsule,
       candidateRoot,
       mode: "simulate",

package/scripts/publication-settlement.mjs

@@ -0,0 +1,211 @@
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  createReleaseInvocation,
+  createReleaseReceipt,
+  createDomainReleaseTransaction,
+} from "../packages/core/release-invocation.js";
+import {
+  releaseTailRoot,
+  validateReleaseTailTransaction,
+} from "../packages/core/release-tail-provider-plane.js";
+
+export const SETTLEMENT_ASSET = "buildchain-publication-settlement.json";
+
+export function verifyPublicationSettlement(
+  documents,
+  { repository, tag, sourceSha, publicPassport, candidateSha } = {},
+) {
+  const {
+    invocation,
+    transaction,
+    receipt,
+    passport,
+    product,
+    providerState,
+    productState,
+  } = documents;
+  const projected = createReleaseInvocation(invocation);
+  const roots = createDomainReleaseTransaction({
+    invocationRoot: projected.roots.invocationRoot,
+    publisherRoot: projected.roots.publisherRoot,
+    runtimeRoot: projected.roots.runtimeRoot,
+    providerRoot: projected.roots.providerRoot,
+    parentRoot: projected.roots.parentRoot,
+  });
+  const { receiptRoot, ...receiptBody } = receipt;
+  const { passportRoot, ...passportBody } = passport;
+  const { root: productRoot, ...productBody } = product;
+  if (
+    !validateReleaseTailTransaction(providerState).valid ||
+    !validateReleaseTailTransaction(productState).valid
+  )
+    throw new Error("invalid provider transaction state");
+  if (
+    releaseTailRoot(transaction) !==
+      releaseTailRoot({
+        ...roots.transaction,
+        transactionRoot: roots.transactionRoot,
+      }) ||
+    createReleaseReceipt(receiptBody).receiptRoot !== receiptRoot ||
+    receipt.transactionRoot !== roots.transactionRoot ||
+    receipt.outcome !== "complete" ||
+    passportRoot !== releaseTailRoot(passportBody) ||
+    receipt.releasePassportRoot !== passportRoot ||
+    productRoot !== releaseTailRoot(productBody) ||
+    !receipt.providerReceiptRoots.includes(productRoot) ||
+    receipt.providerTransactionRoot !== providerState.transactionRoot ||
+    receipt.providerStateRoot !== providerState.stateRoot ||
+    providerState.state !== "complete" ||
+    productState.state !== "complete" ||
+    product.transaction.stateRoot !== productState.stateRoot ||
+    product.transaction.transactionRoot !== productState.transactionRoot ||
+    productState.transactionRoot !== roots.transactionRoot ||
+    providerState.receipts.some(
+      ({ receiptRoot: root }) => !receipt.providerReceiptRoots.includes(root),
+    )
+  )
+    throw new Error("terminal publication receipt lineage does not verify");
+  verifyPublicationCoordinates(documents, {
+    repository,
+    tag,
+    sourceSha,
+    publicPassport,
+    candidateSha,
+  });
+  return { publication: "complete", receiptRoot, sourceSha, tag, repository };
+}
+
+function verifyPublicationCoordinates(
+  { invocation, passport, product },
+  { repository, tag, sourceSha, publicPassport, candidateSha },
+) {
+  if (
+    invocation.candidate.repository !== repository ||
+    (candidateSha && invocation.candidate.commit !== candidateSha) ||
+    passport.repository !== repository ||
+    invocation.provider.repository !== repository ||
+    invocation.target.tag !== tag ||
+    passport.release.tag !== tag ||
+    passport.release.version !== tag.replace(/^v/u, "") ||
+    product.publication.exactTag !== tag ||
+    product.publication.version !== passport.release.version ||
+    product.publication.releaseSha !== sourceSha ||
+    product.publication.state !== "complete" ||
+    product.publication.finalizationNeeded ||
+    passport.source.headSha !== invocation.candidate.commit ||
+    passport.source.treeHash !== invocation.candidate.tree ||
+    passport.policyDigest !== invocation.authority.policyRoot ||
+    passport.publicationQualificationRoot !==
+      invocation.authority.qualificationRoot ||
+    (publicPassport &&
+      releaseTailRoot(publicPassport) !== releaseTailRoot(passport))
+  )
+    throw new Error(
+      "publication evidence does not match exact provider release coordinates",
+    );
+}
+
+export function readApplyDocuments(base) {
+  const read = (relative) =>
+    JSON.parse(fs.readFileSync(path.join(base, relative)));
+  return {
+    invocation: read("release-tail/release-invocation.json"),
+    transaction: read("release-tail/release-transaction.json"),
+    receipt: read("release-tail/release-receipt.json"),
+    product: read("release-tail/product-provider-result.json"),
+    providerState: read("release-tail/state.json"),
+    productState: read("release-tail/product-provider-transaction.json"),
+    passport: read("release-passport/buildchain.release.json"),
+  };
+}
+
+export async function settlePublication({
+  base,
+  client,
+  applyOutcome,
+  repository,
+  candidateSha,
+}) {
+  const documents = readApplyDocuments(base);
+  if (
+    documents.invocation.candidate.repository !== repository ||
+    (candidateSha && documents.invocation.candidate.commit !== candidateSha)
+  )
+    throw new Error(
+      "publication settlement does not match the admitted repository and candidate",
+    );
+  const tag = documents.invocation.target.tag;
+  const release = client.release(tag);
+  const sourceSha = client.json(
+    `repos/${repository}/commits/${encodeURIComponent(tag)}`,
+  ).sha;
+  const matches = release.assets.filter(
+    ({ name }) => name === "buildchain.release.json",
+  );
+  if (matches.length !== 1)
+    throw new Error(
+      "exact public publication passport is missing or ambiguous",
+    );
+  const publicPassport = JSON.parse(client.assetBytes(matches[0]));
+  const status = verifyPublicationSettlement(documents, {
+    repository,
+    tag,
+    sourceSha,
+    publicPassport,
+  });
+  // Publication completion is immutable; next-development and distribution progress stay separate.
+  const settlement = {
+    schemaVersion: 1,
+    contract: "buildchain-v4-publication-settlement/v1",
+    id: "v4-publication",
+    release: { sourceSha, tag, channel: documents.invocation.target.channel },
+    documents,
+  };
+  const file = path.join(base, "release-tail", SETTLEMENT_ASSET);
+  client.write(file, settlement);
+  await client.publish(release, [file]);
+  const summary = {
+    ...status,
+    nextDevelopment: applyOutcome === "success" ? "advanced" : "incomplete",
+    binaryDistribution: "pending-provider-readback",
+  };
+  client.write(
+    path.join(base, "release-tail", "delivery-summary.json"),
+    summary,
+  );
+  return { summary, receipt: documents.receipt };
+}
+
+async function main() {
+  const { releaseAssetClient } = await import("./release-asset-client.mjs");
+  const repository = process.env.GITHUB_REPOSITORY;
+  const result = await settlePublication({
+    base: process.argv[2],
+    client: releaseAssetClient(repository),
+    repository,
+    candidateSha: process.env.CANDIDATE_SHA,
+    applyOutcome: process.env.APPLY_OUTCOME,
+  });
+  if (process.env.GITHUB_OUTPUT)
+    fs.appendFileSync(
+      process.env.GITHUB_OUTPUT,
+      `receipt-json=${JSON.stringify(result.receipt)}\nreceipt-root=${result.receipt.receiptRoot}\nstatus=complete\n`,
+    );
+  if (process.env.GITHUB_STEP_SUMMARY)
+    fs.appendFileSync(
+      process.env.GITHUB_STEP_SUMMARY,
+      `Publication: **complete**, receipt \`${result.receipt.receiptRoot}\`. Next development: **${result.summary.nextDevelopment}**. Binary distribution: **pending provider readback**.\n`,
+    );
+}
+
+if (
+  process.argv[1] &&
+  path.basename(process.argv[1]) === "publication-settlement.mjs" &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+)
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });

package/scripts/release-asset-client.mjs

@@ -0,0 +1,91 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import {
+  reconcileImmutableReleaseAssets,
+  uniqueReleaseAssets,
+} from "../actions/promote-buildchain-ref/reuse-complete-release.js";
+
+export function releaseAssetClient(
+  repository,
+  { execute = execFileSync, token } = {},
+) {
+  if (!/^[\w.-]+\/[\w.-]+$/u.test(repository))
+    throw new Error("exact repository required");
+  const [owner, repo] = repository.split("/");
+  const raw = (endpoint, args = []) =>
+    execute("gh", ["api", endpoint, ...args], {
+      maxBuffer: 128 * 1024 * 1024,
+      stdio: ["ignore", "pipe", "pipe"],
+      ...(token ? { env: { ...process.env, GH_TOKEN: token } } : {}),
+    });
+  const json = (endpoint) => JSON.parse(raw(endpoint));
+  const assetBytes = (asset) =>
+    raw(`repos/${repository}/releases/assets/${asset.id}`, [
+      "-H",
+      "Accept: application/octet-stream",
+    ]);
+  return {
+    json,
+    assetBytes,
+    release: (tag) =>
+      json(`repos/${repository}/releases/tags/${encodeURIComponent(tag)}`),
+    async publish(release, files) {
+      const octokit = {
+        rest: {
+          repos: {
+            getReleaseAsset: async ({ asset_id }) => ({
+              data: assetBytes({ id: asset_id }),
+            }),
+          },
+        },
+      };
+      const result = await reconcileImmutableReleaseAssets({
+        octokit,
+        owner,
+        repo,
+        releaseId: release.id,
+        remoteAssets: uniqueReleaseAssets(release.assets || []),
+        assetPaths: files,
+        uploadReleaseAsset: async ({ name }) => {
+          const file = files.find((file) => path.basename(file) === name);
+          return JSON.parse(
+            raw(
+              `https://uploads.github.com/repos/${repository}/releases/${release.id}/assets?name=${encodeURIComponent(name)}`,
+              [
+                "--method",
+                "POST",
+                "--input",
+                file,
+                "-H",
+                "Content-Type: application/octet-stream",
+              ],
+            ),
+          );
+        },
+      });
+      // A successful upload response alone is not the provider readback.
+      const observed = this.release(release.tag_name);
+      await reconcileImmutableReleaseAssets({
+        octokit,
+        owner,
+        repo,
+        releaseId: release.id,
+        remoteAssets: uniqueReleaseAssets(observed.assets || []),
+        assetPaths: files,
+        uploadReleaseAsset: async () => {
+          throw new Error("uploaded release asset missing on readback");
+        },
+      });
+      return result.map(({ action, name, digest }) => ({
+        action,
+        name,
+        digest,
+      }));
+    },
+    write(file, value) {
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+    },
+  };
+}

package/scripts/{v4-release-candidate-adapter.mjs → release-candidate-adapter.mjs}

@@ -6,7 +6,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
-export function resolveV4ReleaseCandidateAdapter({
+export function resolveReleaseCandidateAdapter({
   resumeCandidateRunId = "",
 } = {}) {
   const mode = String(resumeCandidateRunId || "").trim() ? "recovery" : "fresh";
@@ -19,11 +19,11 @@ export function resolveV4ReleaseCandidateAdapter({
   });
 }
 
-export function runV4ReleaseCandidateAdapter({
+export function runReleaseCandidateAdapter({
   env = process.env,
   exec = execFileSync,
 } = {}) {
-  const route = resolveV4ReleaseCandidateAdapter({
+  const route = resolveReleaseCandidateAdapter({
     resumeCandidateRunId: env.BUILDCHAIN_RESUME_CANDIDATE_RUN_ID,
   });
   exec(process.execPath, [path.join(root, route.script)], {
@@ -37,5 +37,5 @@ if (
   process.argv[1] &&
   import.meta.url === pathToFileURL(process.argv[1]).href
 ) {
-  runV4ReleaseCandidateAdapter();
+  runReleaseCandidateAdapter();
 }