fix(release): separate stable artifact identity

[kattsushi]

Refs #265

Type

• Bug fix
• New feature
• Documentation only
• Code refactoring
• Maintenance/tooling
• Breaking change

Summary

• separates current-master execution authorization from immutable stable artifact identity;
• makes historical dual-SHA replay verification-only and fail-closed if any artifact is missing or divergent;
• adds a real preflight_only workflow mode that exercises live Git/GitHub/npm reads without mutation.

Evidence

Run 33290154328 correctly stopped before mutation because existing stable tags peel to publication SHA f531cd1892b6e194a44637447f9f7b35426abfc1, while current master authorization uses ef35bd4119dc5dfb741e4a0581f03821ca4b088f.

Changes

File	Change
.github/workflows/release-stable.yml	Adds exclusive PREPARE/PREFLIGHT/FINALIZE routing and artifact_sha.
scripts/release-finalize-stable.mjs	Separates execution SHA from artifact SHA and guards historical replay.
scripts/release-finalize-stable.test.mjs	Adds dual-SHA, historical replay and workflow-preflight scenarios.
scripts/release-policy-contract.test.mjs	Enforces SHA separation, preflight isolation and negative mutations.

Test plan

• Runtime harness: 72/72
• Release policy contracts: 20/20
• Combined: 92/92
• Node syntax and shell wrapper syntax
• Ruby Psych workflow parsing
• pnpm format:check
• pnpm nx affected --target=lint --base=origin/master
• git diff --check

Contributor checklist

• Linked an approved issue
• Added exactly one type:* label
• Shell wrapper syntax checked
• Historical and same-SHA paths tested hermetically
• Documentation impact reviewed
• Conventional commit format
• No Co-Authored-By trailers

Summary by CodeRabbit

• New Features

  • Added a read-only preflight option for stable releases, allowing release checks without making changes.
  • Added support for validating and finalizing releases from a specific historical artifact.
  • Release summaries now display the validated artifact identifier.

• Bug Fixes

  • Improved safeguards for release identifiers and incompatible release modes.
  • Historical releases now verify tags, published releases, and package versions before finalization.

• Tests

  • Expanded coverage for preflight checks, historical releases, validation failures, and mutation prevention.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 9e6a0792-0930-4768-8bcb-e8ade7bb8888

📥 Commits

Reviewing files that changed from the base of the PR and between ef35bd4 and 9f7cd7e.

📒 Files selected for processing (4)

• .github/workflows/release-stable.yml
• scripts/release-finalize-stable.mjs
• scripts/release-finalize-stable.test.mjs
• scripts/release-policy-contract.test.mjs

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The stable release workflow adds read-only PREFLIGHT mode and separate artifact SHA input. The finalizer supports historical replay by validating existing tags, GitHub Releases, and npm latest states against the artifact SHA. Tests cover workflow wiring, SHA validation, authorization, and mutation isolation.

Changes

Stable release verification

Layer / File(s)	Summary
Historical replay finalizer scripts/release-finalize-stable.mjs	The finalizer uses ARTIFACT_SHA with an EXPECTED_SHA fallback. Historical replay validates exact existing tags, GitHub Releases, and npm latest states.
PREFLIGHT workflow mode .github/workflows/release-stable.yml	The workflow adds preflight_only and artifact_sha, validates mode-specific SHAs, checks expected SHA authorization, invokes the read-only preflight command, and reports both SHAs.
Replay and policy validation scripts/release-finalize-stable.test.mjs, scripts/release-policy-contract.test.mjs	Tests cover historical replay outcomes, workflow preflight invocation, strict SHA validation, mode authorization, mutation isolation, and workflow contract mutations.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: 🔵 Low · up to 9f7cd

The new preflight mode avoids release mutations by behavior, but it still runs with permissions capable of modifying repository state or obtaining federated credentials. The PR is mergeable with explicit owner awareness and follow-up to isolate preflight with read-only permissions and non-persistent checkout credentials.

Sequence Diagram(s)

sequenceDiagram
  participant ReleaseWorkflow
  participant Finalizer
  participant GitHub
  participant NpmRegistry
  ReleaseWorkflow->>Finalizer: invoke PREFLIGHT with expectedSha and artifactSha
  Finalizer->>GitHub: verify exact tags and Releases
  Finalizer->>NpmRegistry: verify latest package state
  Finalizer-->>ReleaseWorkflow: return JSON verification result

Loading

Poem

I am a rabbit, checking each SHA,

Through quiet preflight, I hop away.
Tags point true and releases align,
Npm states match the artifact line.
No push, no publish, no hurried flight,
Just exact replay in read-only light.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 3 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely identifies the main change: separating stable release artifact identity from current execution authorization.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 3 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/stable-artifact-sha

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}