release: registry integrity propagation can outlive verification retries

[steipete]

Problem

The v0.5.1 trusted-publishing run successfully published the workflow-validated tarball with provenance, but publish-or-verify.mjs exhausted all 13 registry retries because npm view transiently reported a different dist.integrity. The GitHub Release job was skipped even though publication was good.

This is the residual propagation failure after #73/#74 fixed local re-packing and extended the retry window.

Forensic proof

• Failed run: https://github.com/openclaw/fs-safe/actions/runs/30729002894
• Workflow artifact and current registry tarball are byte-for-byte identical (cmp clean), both 5,609,950 bytes.
• Both have SHA-1 f4dabf3ed706bf08ea7a282750baa4ebf1707b60 and integrity sha512-WcaG3NUMd4q+puq/I55zxwc0+OjNVhqxSprKzpS17c2cDd9bYc8c2DrYrs6Io3mmNXNa90re/UWSwVkX4I6PkA==.
• Extracted inventories match: 417 files, 17,092,354 bytes, with identical paths, modes, sizes, and per-file hashes.
• The publish log reported the same SHA-1 and integrity, then observed stale/different registry metadata until the retry budget expired. Current npm view reports the correct integrity and provenance.

Expected

Keep strict artifact identity, but avoid a false-negative when packument metadata is temporarily inconsistent after a successful trusted publish. On an integrity mismatch, consider downloading the versioned registry tarball and verifying its SHA-512 directly before failing, and log the observed integrity to make propagation incidents diagnosable.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed August 2, 2026, 2:47 PM ET / 18:47 UTC.

Summary
This issue remains necessary: current main still exhausts its bounded retries and fails whenever npm continues to return a different dist.integrity, so the GitHub Release job remains blocked even if the actual registry tarball matches. The requested fallback changes the supply-chain evidence accepted by the release gate and needs an explicit maintainer security-boundary decision before implementation.

Reproducibility: yes. Current source deterministically treats any persistent dist.integrity mismatch as pending and throws after the configured retry budget; the existing focused test demonstrates only the eventually-convergent variant.

Root-cause cluster
Relationship: canonical
Canonical: #81
Summary: This is the remaining registry-metadata propagation problem after the earlier validated-tarball and retry-window work.

Members:

• adjacent_distinct: Release workflow: publish re-packs instead of publishing the validated tarball, and registry verification times out #73 - The closed report covered repacking and retry-window defects; this issue documents the remaining case where metadata stays inconsistent even though the registry tarball itself is identical.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Maintainer decision needed

Question	Recommendation
May the verifier accept an npm-version tarball whose SHA-512 matches the validated manifest when npm view still reports a different dist.integrity, and which registry-origin and provenance checks must remain mandatory?	Permit a constrained tarball fallback: Fetch only the expected version from the configured registry, verify its SHA-512 against the local manifest, require provenance independently, and log the conflicting metadata.

Why: This is not only a retry policy: it defines which independent evidence can satisfy the project’s trusted-publishing release gate after registry metadata has not converged.

Next step
The behavior is source-proven, but a repair must wait for a maintainer choice about the release integrity and provenance trust boundary.

Security
Needs attention: The proposed fallback changes the evidence accepted by a trusted-publishing release gate and needs explicit security-boundary approval before implementation.

Review details

Best possible solution:

Keep the validated-artifact identity requirement, then add a bounded, tested direct registry-tarball verification fallback only if maintainers define it as acceptable alongside an independently verified provenance signal and audit logging of the conflicting metadata.

Do we have a high-confidence way to reproduce the issue?

Yes. Current source deterministically treats any persistent dist.integrity mismatch as pending and throws after the configured retry budget; the existing focused test demonstrates only the eventually-convergent variant.

Is this the best way to solve the issue?

Unclear. Direct tarball hashing is the narrowest technical repair, but a maintainer must first decide whether it is sufficient evidence under this package’s trusted-publishing security model.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• Accepting a tarball despite inconsistent packument metadata could weaken the release trust boundary unless the registry origin, redirect policy, tarball hash source, and independent provenance requirement are explicitly constrained and tested.

Codex review notes: model internal, reasoning high; reviewed against 2477f5681f68.

Label changes

Label justifications:

• P2: The defect can block GitHub Release publication after a successful npm trusted publish, but it is a bounded release-operation failure rather than a user-data or runtime emergency.
• impact:other: The concrete impact is release workflow reliability and registry propagation, outside the more specific owned impact categories.

Evidence reviewed

Security concerns:

• [medium] Define trusted registry-tarball verification — scripts/publish-or-verify.mjs:66
  A direct tarball fallback must constrain registry origin and redirects, verify the downloaded bytes against the validated manifest, and retain an independently checked provenance condition so inconsistent metadata does not silently weaken the release gate.
  Confidence: 0.96

What I checked:

• Current source still fails the reported case: A registry integrity mismatch is classified as pending, and after the retry budget publishOrVerify throws; there is no direct download-and-hash verification path for the versioned registry tarball. (scripts/publish-or-verify.mjs:66, 2477f5681f68)
• Coverage confirms the missing boundary: The focused test accepts stale metadata only when it converges within retries; it has no case for persistent packument mismatch with a byte-identical downloadable tarball. (test/publish-or-verify.test.ts:85, 2477f5681f68)
• Release consequence is wired on main: The publish job executes publish-or-verify.mjs, and the GitHub Release job depends on that publish job, so verifier exhaustion prevents release creation. (.github/workflows/release.yml:260, 2477f5681f68)
• Feature provenance and shipped baseline: git blame attributes the current verifier lines to the v0.5.1 release commit, which shipped the validated-tarball and bounded-backoff solution but retained the metadata-only final check. (scripts/publish-or-verify.mjs:58, 16e1bd489ae8)
• Release provenance check: The annotated v0.5.1 tag points to commit 16e1bd489ae8a1c0e752797ca1e8501a36790d98, dated 2026-08-01T19:29:39-07:00; current main is descended from that tag and its changelog records bounded registry backoff. (CHANGELOG.md:20, 16e1bd489ae8)
• Earlier report covers only the prerequisite fixes: The supplied context for the closed earlier report shows it covered publishing the validated tarball and extending the retry window; this persistent-metadata case remains outside that fix. (CHANGELOG.md:20, 2477f5681f68)

Likely related people:

• steipete: The current verifier lines and release workflow history trace to the v0.5.1 release commit associated with steipete's release-area work. (role: introduced current release-verification behavior; confidence: high; commits: 16e1bd489ae8; files: scripts/publish-or-verify.mjs, .github/workflows/release.yml, test/publish-or-verify.test.ts)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[steipete]

Fixed on main in 8926c33 (#90).

The framing in this issue turned out to be backwards, and that changed the fix. The gate was not strong-and-being-loosened: it accepted exactly two packument facts — an integrity string match, and that dist.attestations.url was truthy. The URL was never fetched, no Sigstore bundle was verified, no DSSE subject digest checked, dist.signatures never verified against -/npm/v1/keys, and dist.tarball never downloaded. Hashing the published bytes is therefore strictly stronger evidence than string-comparing a field that describes them.

There was also a second gate that would have made a narrow fix useless: scripts/append-release-proof.mjs repeated the same comparison inside the release job, without --prefer-online and with zero retries. Fixing only publish-or-verify.mjs would have moved the v0.5.1 failure downstream rather than curing it. Both gates now share one verifier.

What landed:

• Draft-then-promote. The Release is created as an idempotent draft before publication and promoted only after verification, so a propagation incident leaves a recoverable draft instead of a successful npm publish with no Release. This addresses the actual v0.5.1 damage, which was an operational cliff rather than a wrong verdict.
• Direct byte verification, pinned to registry.npmjs.org, rejecting redirects, bounding the response, and constructing the canonical tarball URL rather than following one supplied by the metadata that is itself in question.
• Real provenance, replacing the truthiness check: npm's ECDSA registry signature, the DSSE subject digest bound to this exact package and version, and the Sigstore bundle under a policy pinning this repository, the release workflow, the version tag, the builder identity and the issuer.
• A real retryable-vs-fatal taxonomy, instead of treating every non-success as pending.
• Tests for the exhaustion path — the exact failure mode from this incident, which had no coverage at all — plus a new suite for append-release-proof.mjs, which had no test file.

Verified against the really-published 0.5.1, and the observed values match this issue's forensics exactly: 5,609,950 bytes, 417 files, SHA-1 f4dabf3ed706bf08ea7a282750baa4ebf1707b60, integrity sha512-WcaG3NUMd4q+puq/I55zxwc0+OjNVhqxSprKzpS17c2cDd9bYc8c2DrYrs6Io3mmNXNa90re/UWSwVkX4I6PkA==, registry key SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U, subject pkg:npm/%40openclaw/fs-safe@0.5.1, workflow ref refs/tags/v0.5.1.

Both directions proven: with only dist.integrity altered, the old code exhausts all 13 attempts while the new verifier logs the conflict, downloads the real tarball and passes signature and provenance. Flip a single byte and it fails fatally in 6 ms with tarball-integrity-mismatch, no retry — the fallback cannot mask real corruption.

sigstore@5.0.0 is a devDependency; the package still ships zero runtime dependencies.

Not exercised: an actual publish, tag push, or real draft promotion from a protected release tag. Those only prove out on the next real release.