#Distribution model

The profile supplies customer identity, control-plane location, policy trust, release channel and entitlement; none of it is compiled into the package.

The engine and latency-sensitive evaluation run on the customer's machine. Network services only distribute, activate, renew entitlements and deliver signed policy; they are not in the evaluation path.

A customer download portal may be added later without changing the runtime artifact or activation model.

The package contains:

• OMP and Pi extensions.
• Transport-neutral lifecycle adapters for Claude Code, Codex, and Cursor.
• The persistent Rerail event stream.
• Supported native binaries.
• The local model and generic runtime assets.

Customer-specific packages, branches and native builds are prohibited by default. Customer identity and leak attribution go in signed entitlements and policy bundles. Releases stay reproducible, and one security update serves every deployment.

Core (0.1.0, 0.1.1, …) and rule packs publish plain versions straight to latest:

1. .github/workflows/release-pr.yml keeps the Release pull request current with main. It bumps core's patch version if anything core ships changed since its last v<version> tag, beside the packs' changeset bumps.
2. Merging it is the release: the workflow tags core's new version.
3. release.yml builds and publishes core; release-packs.yml publishes packs. Each publish waits for a reviewer to approve the release environment. Each run then checks latest is the version it published (release, pack-format.md).

GitHub Releases: every released version, core's and each pack's, gets one on its tag. Its notes are that version's section of its CHANGELOG.md: notes are written once, in the changelog, for the people who upgrade. Core's latest release is the repository's latest; its next and beta releases are pre-releases (release).

next never trails latest, so whoever follows next gets every stable release too:

• A latest publish or promotion, core's or a pack's, also raises that package's next, unless next holds a newer preview (scripts/release/raise-next.mjs; releasePacks, promotePacks).
• Each run's dist-tag check fails if a package it released under latest or next has a next unset or older than its latest.
• A core next or beta preview older than latest is refused before it is built.
• Previews leave latest alone; putting a version back leaves next where it is.

Rollback moves only the dist-tag; bytes are never rebuilt between channels. workflow_dispatch with latest set on release.yml (core) or release-packs.yml (a pack) points latest at an earlier released version and holds it there. Both use npm trusted publishing, so no npm login is needed.

Provenance: every publish from CI carries an npm provenance attestation. Both workflows pass --provenance, so a publish npm cannot attest fails instead of going out without one.

~/.rerail/
|- update-state.json
|- current -> versions/<active>/node_modules/@neralabs/rerail
|- bin/rerail
|- daemon.json
|- packs/node_modules/@neralabs/rerail-pack-<id>/
|- packs/node_modules/[@<scope>/]rerail-pack-<id>/
`- versions/
   |- 0.2.0/node_modules/@neralabs/rerail/
   `- 0.2.1/node_modules/@neralabs/rerail/

• npm is the authenticated artifact transport. Rerail never copies, logs or sends npm credentials to a control plane.
• Rule packs are npm packages: Rerail's under @neralabs, a third party's as rerail-pack-<id> or @<scope>/rerail-pack-<id> (rule packs). They install with the same npm configuration into packs/, beside the versions, so rerail update keeps them.
• Pack compatibility is peerDependencies["@neralabs/rerail"]. After an update, packs whose range excludes the new version leave the catalog, reported by rerail packs list, until a newer pack is installed.
• update-state.json is the active-version pointer: selected dist-tag, current and previous known-good installs, last explicit check. It is written via a temporary file and atomic rename.

Explicit only. rerail events (internal testing), hooks and the daemon run the active version. Versions arrive via rerail update, /rerail-update (OMP, Pi, Claude Code, Cursor) or $rerail-update (Codex). Auto-updating a machine's global package without consent is out of scope.

New sessions only. A running event-loop process keeps its original version but evaluates nothing itself. Like every managed client, it sends events to the machine's one main daemon, which the new version's first hook or session replaces (One main instance).

An update:

1. Copies the database to $RERAIL_HOME/rerail.sqlite.pre-update, so every rule and repository's history can be restored by hand if the update changed the file (Database compatibility).
2. Resolves the exact version behind the configured dist-tag.
3. Compares it with the active semantic version.
4. Takes a machine-wide update lock.
5. Installs that exact version into a staging directory, production dependencies only.
6. Confirms package name and version.
7. Loads the native module and requires a successful health response.
8. Moves staging into its immutable version directory.
9. Atomically marks the old version previous and activates the new; the old stays in versions/.
10. Runs rerail install --refresh as the new CLI for every connected agent: commands, skills and hooks it ships arrive, retired ones go. It rewrites the launcher; hooks, status line and launcher then name the Node the update ran on.
    • Runs even with no newer version.
    • An agent that cannot be registered again fails alone; the update exits non-zero with the new version active.
    • Agents whose configuration cannot be read to tell whether they are connected are named and left alone.
    • The update that introduces this step runs the previous version's updater, which lacks it: run rerail install --refresh once after it.

Health gate: the native entrypoint and a real RERAIL-EVENTS/1 session-start exchange must pass, or the update is discarded without changing the active version.

Safe failure: failed resolution, authentication, installation or health checks leave the current version unchanged, so revoked npm access blocks only future updates. Concurrent updates share the lock and cannot race activation.

Channels are dist-tags (latest stable; beta, next opt-in). Production activation profiles will eventually constrain the channel; until activation is implemented, local update state selects it.

Trust root: public but security-critical. It must arrive through the authenticated installer, customer portal or another authenticated channel; one delivered beside an untrusted profile proves nothing. Once production keys exist, a release may embed the same public roots and drop the command-line requirement.

A short-lived, one-use code returns:

• A flattened JWS customer profile.
• A unique device credential.
• The selected control-plane endpoint.
• The delegated policy-signing public key.
• Product features and npm release channel.
• Entitlement and offline-grace expiration.

Device binding: the device generates an Ed25519 key pair. Its private key and the device credential live only in macOS Keychain, Linux Secret Service or Windows Credential Manager. They never go in npm config, agent manifests, profiles, logs or the package. The profile carries the public key's RFC 7638 thumbprint, so copied to another device it fails verification.

The launcher verifies the selected profile before starting:

• The local-policy-kernel feature authorizes local execution.
• The signed updateChannel is authoritative; a local --channel request cannot escape it.
• automaticUpdates is carried for compatibility but drives nothing; no code path installs a version unattended.
• Without an activated profile, the machine keeps the unbound local development mode.

Format: flattened JWS, alg: EdDSA, required media type rerail-profile+jws. The signature covers the encoded payload bytes. Rerail verifies it before parsing or trusting any profile field.

Verification checks a trusted kid, EdDSA, the Rerail JWS media type, a valid signature, exact issuer and audience, the local device-key thumbprint and the validity window.

Refreshes cannot change customer or deployment identity or lower the monotonic sequence. Public activation state is written atomically with mode 0600; the previous signed state is kept.

No Rerail code verifies a Nera signature on an update today. Before it runs a staged version, rerail update checks the registry signatures and provenance attestations of everything it installed with npm audit signatures. It installs with no install scripts. Those attestations come from Nera's trusted-publisher release workflow, so they bind a version to that workflow, not to a key Nera holds offline.

The runtime downloads a signed policy manifest. It checks customer and deployment identity, runtime compatibility, bundle digest and signature, and the complete policy schema, then activates atomically. The prior known-good bundle is kept for rollback.

During an outage the runtime uses its active bundle until the signed offline entitlement expires. A failed download or validation of a replacement never destroys the last-known-good state.

• Restricted distribution before launch limits who downloads built releases; it does not make code secret. The source is public under Apache-2.0.
• Administrators can always inspect the runtime and its decrypted memory.
• Device-bound credentials and signed assets protect integrity and attribute activations; they are not confidentiality controls.
• Policy and model encryption at rest stops casual file copying but cannot hide assets while the authorized runtime evaluates them.

Rerail is licensed under Apache-2.0. Restricted npm access does not limit the rights the licence grants recipients.