fix(release): avoid post-publish registry checks

Author: hyfdev

.agents/docs/release.md

@@ -6,9 +6,9 @@ TaffyJS has two independently dispatched release groups. Core publishes `@taffyj
 
 Dispatch `Publish Core` or `Publish Yoga` from `main`. The default `auto` bump reads Conventional Commits that changed the selected group's owned paths since its previous tag. A feature or breaking change selects a minor bump; a fix, performance change, or revert selects a patch bump. An explicit patch or minor override exists for an intentional release whose commit type does not carry a bump. A group's first stable plan is always `0.0.1`.
 
-The dispatch is the sole human authorization. Build jobs have read-only repository access and no npm identity. Ordinary pull requests retain the Linux x64 GNU and Windows x64 MSVC native runtime jobs and the complete Wasm verification graph; they do not build macOS or any other publication artifact. The publication workflows run the complete Wasm package verification graph, and Core publication is the only place that builds all 13 supported native release targets. The assembly job downloads every required build artifact, requires the exact target or package set, writes final metadata, packs the public packages, records each tarball integrity, and installs those same tarballs in a fresh consumer. Only the final job receives `id-token: write`; it publishes the verified tarballs in dependency order, verifies each published version against its assembled integrity, then pushes the group tag and writes the release notes into the workflow summary. The workflow creates no GitHub Release.
+The dispatch is the sole human authorization. Build jobs have read-only repository access and no npm identity. Ordinary pull requests retain the Linux x64 GNU and Windows x64 MSVC native runtime jobs and the complete Wasm verification graph; they do not build macOS or any other publication artifact. The publication workflows run the complete Wasm package verification graph, and Core publication is the only place that builds all 13 supported native release targets. The assembly job downloads every required build artifact, requires the exact target or package set, writes final metadata, packs the public packages, records each tarball integrity, and installs those same tarballs in a fresh consumer. Only the final job receives `id-token: write`; it preflights the complete package group, publishes the missing verified tarballs in dependency order, then pushes the group tag and writes the release notes into the workflow summary. The workflow creates no GitHub Release.
 
-Publishing is not transactional. A retry uses the retained bundle: a package version already present with the same integrity is skipped, a different integrity stops the release, and missing packages continue in dependency order. Before the first npm write, the workflow requires the group tag to be absent or already point to the bundle commit; it verifies that identity again after pushing the tag, and the tag is pushed only after the complete npm group reaches the registry. Nothing is installed from the registry afterwards: npm serves a new version from its exact-version endpoint immediately but refreshes the package index that installers read a few minutes later, and a check placed after an irreversible publication cannot prevent a bad release. The assembly job's consumer install is the test that gates publication. Workflow concurrency never cancels an in-progress publication.
+Publishing is not transactional. Every attempt first checks the complete retained bundle against npm: a package version already present with the same integrity is skipped, a different integrity stops the attempt before any new package is written, and every missing package is then published in dependency order. A successful `pnpm publish` command is the write boundary. Registry reads are eventually consistent, so the workflow neither re-reads nor installs a package after a successful publication; a command failure stops the attempt, and rerunning the same failed job repeats the complete preflight before resuming from the retained bundle. Before the first npm write, the workflow requires the group tag to be absent or already point to the bundle commit; it verifies that identity again after pushing the tag, and the tag is pushed only after every required publish command succeeds. The assembly job's consumer install is the test that gates publication. [Core publish job 97179548726](https://github.com/hyfdev/taffyjs/actions/runs/32633281695/job/97179548726) is durable evidence for the eventual-consistency trap: npm accepted a package while the exact-version read remained unavailable beyond the workflow's retry window and later exposed the expected integrity. Workflow concurrency never cancels an in-progress publication.
 
 ## One-time npm bootstrap
 

tools/release/lib.ts

@@ -69,10 +69,6 @@ export async function sha512Integrity(path: string): Promise<string> {
   return `sha512-${createHash("sha512").update(contents).digest("base64")}`;
 }
 
-export async function wait(milliseconds: number): Promise<void> {
-  await new Promise((resolvePromise) => setTimeout(resolvePromise, milliseconds));
-}
-
 export function packageSlug(name: string): string {
   return name.replace(/^@/, "").replaceAll("/", "-");
 }

tools/release/publish.ts

@@ -5,42 +5,49 @@ import { resolve, sep } from "node:path";
 import { npmRegistry, releaseGroups } from "./config.ts";
 import {
   capture,
+  isMainModule,
   parseRemoteTagCommit,
   pnpmCommand,
   readJson,
   root,
   run,
   sha512Integrity,
-  wait,
 } from "./lib.ts";
 import type { ReleaseBundleManifest, ReleaseBundlePackage } from "./assemble.ts";
 
-const options = parseOptions(process.argv.slice(2));
-const bundleDirectory = safePath(options.bundle);
-const manifest = await readJson<ReleaseBundleManifest>(
-  resolve(bundleDirectory, "release-manifest.json"),
-);
-await verifyBundle(bundleDirectory, manifest);
+if (isMainModule(import.meta.url)) {
+  await main();
+}
 
-if (!options.publish) {
-  console.log(
-    `Validated ${manifest.packages.length} ${manifest.group} tarballs for ${manifest.tag}; pass --publish only from the trusted workflow`,
+async function main(): Promise<void> {
+  const options = parseOptions(process.argv.slice(2));
+  const bundleDirectory = safePath(options.bundle);
+  const manifest = await readJson<ReleaseBundleManifest>(
+    resolve(bundleDirectory, "release-manifest.json"),
   );
-  process.exit(0);
-}
+  await verifyBundle(bundleDirectory, manifest);
 
-const githubSha = process.env.GITHUB_SHA;
-if (!githubSha) throw new Error("Publishing requires GITHUB_SHA");
-assert.equal(githubSha, manifest.commit, "The release bundle must belong to the workflow commit");
-assert.equal(process.env.GITHUB_REF, "refs/heads/main", "Publishing is restricted to main");
-await assertRemoteTag(manifest.tag, manifest.commit, true);
+  if (!options.publish) {
+    console.log(
+      `Validated ${manifest.packages.length} ${manifest.group} tarballs for ${manifest.tag}; pass --publish only from the trusted workflow`,
+    );
+    return;
+  }
 
-for (const packageArtifact of manifest.packages) {
-  await publishPackage(bundleDirectory, packageArtifact);
-}
+  const githubSha = process.env.GITHUB_SHA;
+  if (!githubSha) throw new Error("Publishing requires GITHUB_SHA");
+  assert.equal(githubSha, manifest.commit, "The release bundle must belong to the workflow commit");
+  assert.equal(process.env.GITHUB_REF, "refs/heads/main", "Publishing is restricted to main");
+  await assertRemoteTag(manifest.tag, manifest.commit, true);
+
+  await publishReleasePackages(manifest.packages, {
+    registryIntegrity,
+    publish: async (packageArtifact) => publishPackage(bundleDirectory, packageArtifact),
+  });
 
-await pushReleaseTag(manifest);
-await writeSummary(bundleDirectory, manifest);
+  await pushReleaseTag(manifest);
+  await writeSummary(bundleDirectory, manifest);
+}
 
 async function verifyBundle(
   bundleDirectory: string,
@@ -64,47 +71,51 @@ async function verifyBundle(
   }
 }
 
-async function publishPackage(
-  bundleDirectory: string,
-  packageArtifact: ReleaseBundlePackage,
+// A successful publish command is the write boundary. Registry reads are
+// eventually consistent, so they are used only by an attempt's initial preflight.
+export async function publishReleasePackages(
+  packages: readonly ReleaseBundlePackage[],
+  operations: {
+    readonly registryIntegrity: (name: string, version: string) => Promise<string | null>;
+    readonly publish: (packageArtifact: ReleaseBundlePackage) => Promise<void>;
+  },
 ): Promise<void> {
-  const existingIntegrity = await registryIntegrity(packageArtifact.name, packageArtifact.version);
-  if (existingIntegrity !== null) {
-    assert.equal(
-      existingIntegrity,
-      packageArtifact.integrity,
-      `${packageArtifact.name}@${packageArtifact.version} already exists with different bytes`,
+  const missing: ReleaseBundlePackage[] = [];
+  for (const packageArtifact of packages) {
+    const existingIntegrity = await operations.registryIntegrity(
+      packageArtifact.name,
+      packageArtifact.version,
     );
-    console.log(`Skipping verified ${packageArtifact.name}@${packageArtifact.version}`);
-    return;
+    if (existingIntegrity === null) {
+      missing.push(packageArtifact);
+    } else {
+      assert.equal(
+        existingIntegrity,
+        packageArtifact.integrity,
+        `${packageArtifact.name}@${packageArtifact.version} already exists with different bytes`,
+      );
+      console.log(`Skipping verified ${packageArtifact.name}@${packageArtifact.version}`);
+    }
   }
 
-  await retry(`publish ${packageArtifact.name}@${packageArtifact.version}`, 3, async () => {
-    try {
-      await run(pnpmCommand, [
-        "publish",
-        resolve(bundleDirectory, packageArtifact.tarball),
-        "--access",
-        "public",
-        "--no-git-checks",
-        "--ignore-scripts",
-        "--provenance",
-        "--registry",
-        npmRegistry,
-      ]);
-    } catch (error) {
-      const integrity = await registryIntegrity(packageArtifact.name, packageArtifact.version);
-      if (integrity === packageArtifact.integrity) return;
-      throw error;
-    }
-  });
+  for (const packageArtifact of missing) await operations.publish(packageArtifact);
+}
 
-  await retry(`verify ${packageArtifact.name}@${packageArtifact.version}`, 5, async () => {
-    assert.equal(
-      await registryIntegrity(packageArtifact.name, packageArtifact.version),
-      packageArtifact.integrity,
-    );
-  });
+async function publishPackage(
+  bundleDirectory: string,
+  packageArtifact: ReleaseBundlePackage,
+): Promise<void> {
+  await run(pnpmCommand, [
+    "publish",
+    resolve(bundleDirectory, packageArtifact.tarball),
+    "--access",
+    "public",
+    "--no-git-checks",
+    "--ignore-scripts",
+    "--provenance",
+    "--registry",
+    npmRegistry,
+  ]);
 }
 
 async function registryIntegrity(name: string, version: string): Promise<string | null> {
@@ -121,17 +132,14 @@ async function registryIntegrity(name: string, version: string): Promise<string
   return integrity;
 }
 
-// npm publication cannot be undone, so the tag is recorded as soon as the
-// complete group reached the registry.
+// The tag marks completion only after every required publish command succeeds.
 async function pushReleaseTag(manifest: ReleaseBundleManifest): Promise<void> {
   if (await assertRemoteTag(manifest.tag, manifest.commit, true)) {
     console.log(`Verified existing release tag ${manifest.tag}`);
     return;
   }
-  await run("git", ["tag", "--force", manifest.tag, manifest.commit]);
-  await retry(`push release tag ${manifest.tag}`, 3, async () => {
-    await run("git", ["push", "origin", `refs/tags/${manifest.tag}`]);
-  });
+  await run("git", ["tag", manifest.tag, manifest.commit]);
+  await run("git", ["push", "origin", `refs/tags/${manifest.tag}`]);
   await assertRemoteTag(manifest.tag, manifest.commit, false);
 }
 
@@ -161,27 +169,6 @@ async function remoteTagCommit(tag: string): Promise<string | null> {
   return parseRemoteTagCommit(output, tag);
 }
 
-async function retry(
-  label: string,
-  attempts: number,
-  operation: () => Promise<void>,
-): Promise<void> {
-  let lastError: unknown;
-  for (let attempt = 1; attempt <= attempts; attempt += 1) {
-    try {
-      await operation();
-      return;
-    } catch (error) {
-      lastError = error;
-      if (attempt < attempts) {
-        console.warn(`${label} failed on attempt ${attempt}; retrying`);
-        await wait(2_000 * attempt);
-      }
-    }
-  }
-  throw lastError;
-}
-
 async function writeSummary(
   bundleDirectory: string,
   manifest: ReleaseBundleManifest,

tools/release/release.test.ts

@@ -2,7 +2,11 @@ import assert from "node:assert/strict";
 import { resolve } from "node:path";
 import test from "node:test";
 
-import { rewriteNodeLoaderVersion, shouldCopyStagePath } from "./assemble.ts";
+import {
+  rewriteNodeLoaderVersion,
+  shouldCopyStagePath,
+  type ReleaseBundlePackage,
+} from "./assemble.ts";
 import { bootstrapState } from "./bootstrap-registry.ts";
 import { bootstrapVersion, isReleasePath, npmRegistry } from "./config.ts";
 import { parseRemoteTagCommit, root } from "./lib.ts";
@@ -12,6 +16,7 @@ import {
   revokeTemporaryAuthentication,
   type CommandRunner,
 } from "./npm-trust.ts";
+import { publishReleasePackages } from "./publish.ts";
 import {
   automaticBump,
   incrementVersion,
@@ -70,6 +75,71 @@ void test("remote release tags resolve lightweight and annotated commits", () =>
   assert.equal(parseRemoteTagCommit("", "v0.0.1"), null);
 });
 
+void test("publication preflights every package before the first registry write", async () => {
+  const missing = releasePackage("@taffyjs/missing", "sha512-missing");
+  const conflicting = releasePackage("@taffyjs/conflicting", "sha512-expected");
+  const published: string[] = [];
+
+  await assert.rejects(
+    () =>
+      publishReleasePackages([missing, conflicting], {
+        registryIntegrity: async (name) => (name === missing.name ? null : "sha512-unexpected"),
+        publish: async ({ name }) => {
+          published.push(name);
+        },
+      }),
+    /already exists with different bytes/,
+  );
+
+  assert.deepEqual(published, []);
+});
+
+void test("publication skips matching versions and does not read them again after writing", async () => {
+  const existing = releasePackage("@taffyjs/existing", "sha512-existing");
+  const firstMissing = releasePackage("@taffyjs/first-missing", "sha512-first-missing");
+  const secondMissing = releasePackage("@taffyjs/second-missing", "sha512-second-missing");
+  const events: string[] = [];
+
+  await publishReleasePackages([existing, firstMissing, secondMissing], {
+    registryIntegrity: async (name) => {
+      events.push(`read ${name}`);
+      return name === existing.name ? existing.integrity : null;
+    },
+    publish: async ({ name }) => {
+      events.push(`publish ${name}`);
+    },
+  });
+
+  assert.deepEqual(events, [
+    `read ${existing.name}`,
+    `read ${firstMissing.name}`,
+    `read ${secondMissing.name}`,
+    `publish ${firstMissing.name}`,
+    `publish ${secondMissing.name}`,
+  ]);
+});
+
+void test("publication stops at a command failure without retrying or continuing", async () => {
+  const first = releasePackage("@taffyjs/first", "sha512-first");
+  const failing = releasePackage("@taffyjs/failing", "sha512-failing");
+  const unattempted = releasePackage("@taffyjs/unattempted", "sha512-unattempted");
+  const attempts: string[] = [];
+
+  await assert.rejects(
+    () =>
+      publishReleasePackages([first, failing, unattempted], {
+        registryIntegrity: async () => null,
+        publish: async ({ name }) => {
+          attempts.push(name);
+          if (name === failing.name) throw new Error("publish failed");
+        },
+      }),
+    /publish failed/,
+  );
+
+  assert.deepEqual(attempts, [first.name, failing.name]);
+});
+
 void test("bootstrap revokes only the npm login it creates", async () => {
   const events: string[] = [];
   let authenticated = false;
@@ -213,6 +283,17 @@ function commit(subject: string, paths: readonly string[]): ConventionalCommit {
   return { hash: "1234567890abcdef", subject, body: "", paths };
 }
 
+function releasePackage(name: string, integrity: string): ReleaseBundlePackage {
+  return {
+    name,
+    kind: "binding",
+    version: "0.0.2",
+    tarball: `${name.replaceAll("/", "-")}.tgz`,
+    integrity,
+    files: ["package.json"],
+  };
+}
+
 function parsed(subject: string) {
   return parseConventionalCommit(commit(subject, ["packages/taffyjs-node/src/index.ts"]));
 }