changelog and releases

orcr ships the CLI binary and the TypeScript SDK together, in lockstep, from a single tag. this page covers how a release is produced, what artifacts it contains, and the compatibility rules you need when the CLI, the SDK, herdr, and the store are not all the same age.

release history

the project is pre-1.0 and developed against a milestone plan (M0 through M7 are complete; see contributing). there are no versions published to the package registries yet:

• the orchestratr crate is not yet claimed on crates.io.
• @orchestratr/sdk is unpublished (0.0.0 in the manifest). orcr scaffold installs it locally, pinned to the CLI version.

prebuilt CLI binaries are published as GitHub release assets per tag. future released versions will each get an entry here summarizing what changed, following the feat: / fix: / chore: commit convention the repo already uses.

how releases work

releases are tag-driven. pushing a vX.Y.Z tag runs the release workflow, which builds the orcr binaries, creates a GitHub release, and (when the publish tokens are configured) pushes to crates.io and npm.

the one-command path bumps both manifests in lockstep, runs a sanity build, commits, tags, and pushes:

scripts/release.sh patch          # 0.1.0 -> 0.1.1  (bug fixes)
scripts/release.sh minor          # 0.1.0 -> 0.2.0  (backward-compatible features)
scripts/release.sh major          # 0.1.0 -> 1.0.0  (breaking changes)
scripts/release.sh 0.4.2          # or an explicit version
scripts/release.sh minor --dry-run   # preview, change nothing

it refuses unless you are on a clean main in sync with origin. it bumps Cargo.toml and sdk/ts/package.json (plus the lockfiles), does a cargo build, commits chore(release): vX.Y.Z, tags, and pushes. the Cargo.toml version and the tag must match; the workflow's version guard fails the run otherwise.

the binaries job always runs. the crates.io and npm publish jobs run only when their repo secrets (CARGO_REGISTRY_TOKEN, NPM_TOKEN) are present, and they never block or fail the release when absent. registry versions are immutable: you cannot re-publish X.Y.Z, so bump the patch and re-tag if a publish half-fails.

install artifacts

each release ships a tarball per platform, and each tarball ships a .sha256 checksum alongside it:

ways to install:

# one-liner: detects the platform, verifies the .sha256, installs orcr to ~/.local/bin
curl -fsSL https://orchestratr.dev/install.sh | sh
curl -fsSL https://orchestratr.dev/install.sh | sh -s -- v0.1.0   # pin a version

# prebuilt binary, by hand
tar -xzf orcr-<version>-<platform>.tar.gz && mv orcr /usr/local/bin/

# from source (Rust >= 1.89)
cargo install orchestratr        # installs the orcr binary

orcr needs a running herdr on your PATH at runtime, with the claude and codex integrations installed. only orcr scaffold and the SDK need Node (>= 20). full setup is on the installation page.

note. until the install script is hosted at orchestratr.dev/install.sh, the raw GitHub release URL works auth-free because the repo is public. see the roadmap.

SDK version pinning

orcr scaffold generates a package.json that pins @orchestratr/sdk to the CLI's own version. this keeps the SDK you write against and the server you talk to in the same generation, which matters because both are version-negotiated (below).

because the SDK is not on npm yet, the scaffolded project installs the pinned version from wherever ORCR_SDK_SPEC points:

• unset: the scaffold uses the pinned CLI version (works once @orchestratr/sdk is published).
• set to a file: path or a local tarball: the scaffold installs from there. this is the offline and local-development path, and it is how the recipe e2e suite installs the SDK.

# install the SDK from a local tarball instead of npm
ORCR_SDK_SPEC=/path/to/orchestratr-sdk.tgz orcr scaffold my-workflow

orcr scaffold is purely local: it never talks to the server, and it fails with state_conflict (touching nothing) if any of its three files already exist. see the SDK quickstart.

version compatibility

three boundaries carry a version, and each fails loudly on a mismatch rather than guessing.

• orcr client to orcr server. the socket protocol is negotiated on the first request. a mismatch returns unsupported_version. the current orcr socket protocol version is 1. because orcr scaffold pins the SDK to the CLI version, a scaffolded project and its CLI stay in step; a hand-updated SDK against an older CLI (or the reverse) is what this check catches.
• orcr server to herdr. orcr declares a minimum herdr protocol version and handshake-checks it on connect. a mismatch fails with a clear error naming the required herdr version (surfaced as herdr_unreachable style version-skew). the driver's operation set is pinned to named herdr methods and checked against the installed herdr's live api schema, so herdr version drift is caught, not silently tolerated.
• two orcr versions sharing one store. the store stamps a schema_version. a binary that finds an incompatible on-disk schema refuses to open the store with a message rather than migrating blindly.

the socket protocol is additive: unknown fields are ignored, so newer payload fields do not break an older reader. orcr api schema publishes the full contract (methods, params, results, event kinds, error codes, protocol version) and is the source of truth for what a given version speaks. see the socket API reference.