#Releasing Rerail

1. Compile the native kernel for macOS, Linux glibc and Windows MSVC, on arm64 and x64.
   • Linux builds against glibc 2.17 with napi-rs's cross toolchain; a kernel needing glibc newer than 2.28 is rejected.
   • A Windows kernel importing the Visual C++ runtime is rejected. The kernels link it statically, so a clean Windows install needs no redistributable.
2. Smoke-test native loading and device storage on each host.
3. Build the runtime and bundled UI; pack only if all six native/*.node files are present.
4. Install the tarball into a scratch prefix; check rerail --help, the bundled UI and nativeHealth().
5. On Windows x64, Linux x64 and macOS arm64, install it as a user would and exercise the managed runtime: scripts/host/windows-install-smoke.ps1 on Windows, the environment matrix's scripts/host/azure/guest.sh through matrix.mjs local on Linux and macOS. Nothing publishes unless all three pass.

• The bump changes the root entries of package.json and package-lock.json. The CHANGELOG.md section comes from the unreleased lead and pending .changelog/ entries.
• The tag is pushed with the neralabs-ci app's token.
• Anything core ships: every path except packs, documentation, CI, changesets and pending changelog entries, tests, fixtures, corpora, benchmarks, development and release scripts, and repository files npm does not pack. package-lock.json counts only when more than its pack entries moved (NOT_SHIPPED in scripts/release/core-paths.mjs).

• Claude: developer portal; follows main, live when a reviewer publishes it.
• Codex: upload a new ZIP of plugins/codex at platform.openai.com/plugins.
• Cursor: Cursor's team reviews each repository update by hand.
• The bump updates each manifest's version and the npx @neralabs/rerail@<version> its install skill runs (PLUGIN_PINS in scripts/release/core.mjs).
• Checked-in manifests carry no version. npm pack stamps package.json's version in (prepack) and restores the source form (postpack). After a failed pack, run node scripts/build/stamp-plugin-versions.mjs restore.

• Publishing uses npm trusted publishing from the protected release environment. The channel is the npm dist-tag.
• Other prerelease suffixes are rejected. The run refuses a preview older than core's latest before building.
• next never trails latest: a latest release raises next to it (scripts/release/raise-next.mjs) unless next holds a newer preview. Whoever follows next gets every stable release. A beta or next release leaves other tags alone.
• Re-running the publish job is safe: npm refusing to publish over an existing version counts as published.
• The run's summary lists core's dist-tags. It fails if the channel's tag is not the new version, or, for latest and next releases, next is unset or older than latest.

Release tags can't be moved or deleted, and re-running a failed run reuses the tag's scripts. So when a release fails before publishing because of something that doesn't ship, such as a workflow or a release script, fix that on main and run:

gh workflow run release.yml --ref main -f publish=<version>

The run builds main, runs every check and publishes behind the same approval. The tag stays where it is, and npm's provenance names the main commit. It is refused unless all of these hold, so core's own code is the tag's:

• it runs from main with latest left empty, and main's package.json names that version;
• the v<version> tag exists;
• nothing core ships has changed since the tag (publishRetryRefusal in scripts/release/core-paths.mjs).

How the package is built and its changelog can still differ from the tag, so that a fix to the build can be retried too. The run summary lists every path changed since the tag, starting with those that can change the tarball (PACKAGE_INPUTS): the build workflow and its actions, the shrinkwrap step, .gitattributes and CHANGELOG.md. Check that list before approving.

If the fix changes what ships, it takes the next version: the Release pull request offers one as soon as the fix is on main. Say in that version's lead that the failed version was never published, since its notes won't reach anyone updating past it.

The put-back uses trusted publishing behind the same approval as a release, so no one needs an npm login to put core back. If next is older than that version, it raises next to it too. The run's GitHub Release job then makes that version's Release the repository's latest.

• A tag's run restores only caches saved on main; package.yml restores only the exact match.
• On main it runs nightly and after changes to those files. Each target lacking a matching cache builds from scratch and saves one.

• Throwaway Azure VMs: Ubuntu and Debian on x64 and arm64, RHEL on x64, Windows 11 on x64 and arm64.
• GitHub-hosted macOS runners: macOS 26 and 15 on Apple silicon, macOS 15 on Intel.

Each follows a user's path: npx @neralabs/rerail setup, the managed runtime, PATH in a new shell, the coding-agent hooks, daemon restart and removal.

Entry files mean pull requests never edit the same lines of CHANGELOG.md. Entries leave detail to the docs they link, and leave out commit hashes, ticket ids, pull request numbers and repository-internal maintenance. The lead goes before the first entry; add the ## Unreleased heading if the last release took it. It belongs on main because every push rewrites the Release pull request.

Assembly. The Release pull request renames the heading ## <version> (<date>), dated the day it last updated from main. It puts pending entries under the lead, under a ### <type> heading for each change type that has one (Added, Changed, Deprecated, Removed, Fixed, Security, in that order, file-name order within a type), and deletes their files. With neither lead nor entry, the section says no entries were written. Should an entry with no type reach main, core is left out of the Release pull request, and its description says why, until the file is renamed; the packs still release.

CI (scripts/release/core-changelog-check.mjs, in ci.yml's lint job) fails:

• a pull request with a pending .changelog/ entry that has no change type, or whose added or changed entry runs long, names a ticket, pull request or commit, or starts with its own - ;
• a pull request writing an entry into CHANGELOG.md's first section, under ## Unreleased or the last release's dated heading;
• the Release pull request until the dated section has its lead. One pull request releases core and packs, so this also holds back the packs' release.

• scripts/release/github-release.mjs builds them, so notes are written once.
• After the dist-tag check, release.yml's GitHub Release job makes core's, titled v<version>: a pre-release for next and beta, the repository's latest release for latest.
• A version without its own changelog section says no changelog entries were written.
• Re-runs rewrite an existing Release's notes, pre-release and latest flags. After a put-back, the restored version becomes the latest release.
• release-packs.yml makes a pack's Release (pack-format.md).
• Step 1 makes the checkout's tags the remote's. The dry run prints each Release it would create, with notes from the changelog at the tag's commit.
• Backfill reads only the remote's tags, and names each tag it skips: local-only, local commit differing from the remote's, or no changelog section for its version. So every Release it makes has notes.
• Only the highest core version on latest becomes the latest release.

• The checkout's only lockfile is package-lock.json; it never commits a shrinkwrap.
• npm honors a published shrinkwrap instead of resolving versions and integrity hashes fresh; the registry flags such versions (_hasShrinkwrap).
• Writing. npm pack writes it (prepack: node scripts/release/shrinkwrap-pack.mjs write) and deletes it after (postpack); package.json's files lists it.
• Contents. The root and every package its dependencies reach in package-lock.json: no development dependency, workspace pack, or optional peer nothing else needs. Packages reached only through optional dependencies are marked optional.
• Write failures. Writing fails if package-lock.json's root dependencies differ from package.json's, or the lockfile lacks a package a dependency needs.
• Release check. Before publishing, release.yml runs node scripts/release/shrinkwrap-pack.mjs check <tarball>. It fails on a missing shrinkwrap or one differing from the tag's package-lock.json, naming the packages that differ.
• Layout. npm installs a shrinkwrapped package's dependencies inside it, under node_modules/@neralabs/rerail/node_modules, not beside it.

• No production dependency needs an install script; better-sqlite3 ships prebuilt binaries.
• Before running staged code, it verifies registry signatures and provenance attestations of everything installed with npm audit signatures, stopping on any failure.
• A registry without signing keys, such as some private mirrors, gets a warning and the install continues.