reasampler/docs/product/versioning-and-release.md

# Versioning & release — product notes

Framing behind two release-milestone (M11-adjacent) capabilities Daniel wants made
concrete and decidable:

1. **A release version scheme** — so a "real" stable build can be deployed and
   identified.
2. **A beta side-channel** — so development can continue and a beta build run
   *alongside* the stable one without the beta clobbering the release.

This doc holds the *why*, the forks, and a recommendation. The tickable points'
landed history is in `docs/ARCHIVE.md`; the deploy/build wiring hands off to dev-ops.
This is a framing note; it changes no source or CMake.

Status: framed by product-designer (2026-07-26); **all four forks settled by Daniel
(2026-07-26); V1–V4 implemented and landed (2026-07-26).** V1 approved as recommended
(ext-state version stamp prioritized to the first wave); V2 plain `-beta` suffix
(`git describe` decoration rejected); V3 recommendation accepted (console line + panel
readout, about-box deferred); **V4 reversed the recommendation** — Daniel chose
**beta-in-isolation / full coexistence** (separate binary, isolated ext-state
namespace, isolated command-id prefix) rather than the branch-discipline/one-at-a-time
path the note originally recommended. The "Recommendation" and "Open decisions"
sections below have been superseded to reflect the settled state; each records what
was chosen and why. Deploy/build wiring hands off to dev-ops.

---

## The one constraint that shapes everything: REAPER's startup dlopen

REAPER, at startup only, scans `UserPlugins/` and `dlopen()`s **every** file
matching `reaper_*.dll|dylib|so`, then calls each one's `ReaperPluginEntry`
(CLAUDE.md §REAPER extension contract). Three consequences drive every decision
below:

- **Two matching files load simultaneously.** If both `reaper_reasampler.dll` and
  `reaper_reasampler_beta.dll` sit in `UserPlugins/`, REAPER loads *both* — two
  independent extension instances in one REAPER process. This is the mechanism a
  beta side-channel would exploit, and also its central hazard.
- **No hot reload.** Deploy = copy the binary in, restart REAPER. Any scheme is
  "restart to pick up," never live-swap.
- **Everything is process-global inside REAPER.** Two coexisting instances share
  one REAPER, one Actions list, one project, one ext-state store. Anything keyed by
  a global string (command ids, ext-state namespace, docked-window identity) is a
  potential collision surface between the two.

Two sharp edges follow directly and recur throughout this note:

- **The `STABLE_FOREVER_STRING` command-id contract** (CLAUDE.md; `app_version.h`'s `commandIdPrefix()`,
  prefix `CEREBELLUM_REASAMPLER_`). Command-id strings are minted once and **never
  changed after shipping** — user keybindings key off them. Two coexisting binaries
  that register the *same* id strings collide in REAPER's Actions list.
- **The `"reasampler"` project ext-state namespace** (shared by the `banks`,
  `view_state`, `project_guid`, `tail_setting` keys, plus the retired `bank_index`).
  Both binaries reading/writing the same namespace on the same open project means a
  **beta can read — and rewrite — a stable project's saved bank/view state.** Given
  the forward-only migrations already in the design (legacy `bank_index` retired
  after promotion; `banks` authoritative thereafter — `docs/ARCHIVE.md` §Phase B), a
  beta that writes a newer schema into a project a user then reopens in stable is a
  real corruption path, not a theoretical one.

Everything below is really about how much of that global surface a beta channel is
allowed to touch.

---

# Part 1 — Version scheme + where the version lives

## What we have today

- No version anywhere. `CMakeLists.txt` is `project(reaper_reasampler LANGUAGES
  CXX)` — no `VERSION`. The binary announces itself only as `"ReaSampler loaded.\n"`
  to the console (`main.cpp`). There is no number a user, a bug report, or a
  future migration can key off.
- The natural user-visible readout already exists: the docked LICE bank panel, and
  the console (`ShowConsoleMsg`). A version has cheap homes; none is wired.

## The number itself (V1) — SETTLED (2026-07-26): **semver, sourced from CMake; ext-state stamp lands ASAP / first wave**

> **Decision (V1).** Approved as recommended. Semver, single source of truth in CMake
> `project(reaper_reasampler VERSION x.y.z)`, threaded into the binary. **The
> `"reasampler"` ext-state writing-version stamp is prioritized to the first wave, not
> deferred** — Daniel emphasized ASAP because *every project saved without the stamp
> is harder to migrate later*, so the migration seam must exist before more real
> projects accrue un-stamped state. Treat the stamp as an early, high-priority
> deliverable that ships with (or ahead of) the first versioned build.

Recommend **semantic versioning** (`MAJOR.MINOR.PATCH`) with the number's single
source of truth in `CMakeLists.txt` via `project(reaper_reasampler VERSION x.y.z)`,
threaded into the binary as a compile definition and surfaced to the user.

Semver fits because ReaSampler already has the two events semver exists to signal,
and they matter here specifically:

- **MAJOR / MINOR** track user-visible capability (a new pillar landing: Phase R
  prune, M9 slots).
- **PATCH** tracks fixes.
- Most importantly, ReaSampler carries **persisted, migrating project state** (the
  `"reasampler"` ext-state, forward-only migrations). A version stamped *into the
  saved blob* is what lets a future build say "this project was written by 1.4, I am
  1.6, run the 1.4→1.6 migration" — or refuse gracefully. That is a concrete,
  already-latent need, not ceremony. **Recommend stamping the writing version into
  the ext-state blob** as part of whichever release wave ships (small addition to
  the persist section; a sibling `schema`/`app_version` field).

**Source of truth: CMake `project(VERSION)`.** One number, in the build system,
flowed outward — never hand-edited in a header. `project(... VERSION x.y.z)`
populates `PROJECT_VERSION` / `PROJECT_VERSION_MAJOR|MINOR|PATCH`, which a
`target_compile_definitions` (e.g. `REASAMPLER_VERSION="…"`) threads into the
binary. This is the standard CMake idiom and keeps the tag, the binary, and any
about-string in lockstep from one edit.

**Alternatives considered:**

- **Git-derived version (`git describe --tags`)** baked at configure time. Pro: the
  build literally cannot disagree with the tag; encodes commits-since-tag + dirty
  state, which is *excellent for a beta* ("1.4.0-beta.3+7.gab12cd"). Con: needs git
  present at build and a tag discipline; a source tarball without `.git` builds
  "unknown." **This was originally recommended for the beta suffix — Daniel rejected
  it** (V2 settled below: a plain `-beta` suffix is more legible than a decorated
  `git describe` string). `project(VERSION)` still owns the release triple; the beta
  simply carries `-beta`. (See V2.)
- **A hand-maintained `version.h`.** Rejected — a second source of truth that drifts
  from the tag. The whole point of one source is that release can't ship a binary
  that lies about its number.
- **Date-based / CalVer (`2026.07`).** Coherent, but ReaSampler's changes are
  capability-shaped (pillars landing), not time-shaped, and CalVer says nothing
  about migration compatibility, which is the load-bearing use here. Semver earns
  its place; CalVer doesn't.

## Where the user sees it (V3) — SETTLED (2026-07-26): **panel readout + startup log; about box deferred**

> **Decision (V3).** Recommendation accepted (Daniel deferred to product-designer
> judgment — "whatever"). Startup console line (`"ReaSampler x.y.z loaded"`) + a
> bank-panel version/channel readout ship; the about-box stays deferred. Panel
> placement (header corner / footer / folded into existing chrome) remains a small
> residual polish call, same class as the settled active-bank-indicator placement.

Three candidate homes, cheap to expensive:

1. **Startup console line** — upgrade `"ReaSampler loaded.\n"` to `"ReaSampler
   x.y.z loaded.\n"`. Nearly free, and it lands the version in exactly the place a
   user copies from when filing a bug. **Do this regardless of the other choices.**
2. **Bank-panel readout** — a small version string in the docked LICE panel
   (header corner or footer, near the existing tail toggle / mode switch). Always
   visible, no new window, matches the LICE-drawn house style. **Recommend this as
   the primary user-facing home.**
3. **An "about" action / dialog** — a bindable `ReaSampler: about` that pops
   version + build channel + build hash. More than the moment needs; a SWELL dialog
   is real surface to maintain. **Defer** — the panel readout + console line cover
   the actual need (identify the running build). Pick this up only if a beta channel
   makes "which build am I running" a frequent question.

Recommendation: **(1) + (2) now, (3) deferred.** The version wants to be visible
*passively* (panel) and *copyably* (console), and a beta channel makes the panel
readout do double duty as the channel indicator (Part 2).

**Open decision V3 for Daniel:** panel placement — header corner vs. footer strip
vs. folded into the existing mode-switch/tail-toggle chrome. This is a small panel
polish call, same class as the settled "active-bank indicator placement" residual.

---

# Part 2 — Beta side-channel

The goal: keep shipping a stable build users depend on, while running a beta of
in-progress work **alongside** it, so the beta can be exercised in real projects
without the beta's newer/rougher state clobbering the stable install or stable
projects.

The design axis is **coexistence**: must stable and beta load into the *same REAPER
at the same time* (true side-by-side), or is it enough to run *one at a time* with
clean, safe switching? That axis splits the options.

## Option A — Separate binary name, both load simultaneously (true coexistence)

Ship `reaper_reasampler_beta.dll` next to `reaper_reasampler.dll`. REAPER loads
both; the user has a stable ReaSampler and a beta ReaSampler live in one session.

This is the most powerful shape — and the most dangerous, because of the three
global-collision surfaces the startup-dlopen constraint creates. **A separate
binary name alone does not isolate them; it just makes them coexist.** For Option A
to be safe, *three* things must diverge in lockstep, not just the filename:

1. **Command-id strings must diverge.** Both binaries register actions; if the beta
   mints `CEREBELLUM_REASAMPLER_CAPTURE_TRACK` too, REAPER's Actions list has two
   entries claiming one id — collision, and the `STABLE_FOREVER_STRING` contract is
   violated. The beta needs its **own prefix** (e.g. `CEREBELLUM_REASAMPLER_BETA_`).
   Sharp edge: that means the beta's ids are a *distinct forever-family* — a user's
   beta keybindings won't carry to stable, and vice versa. That is arguably correct
   (they're different installs), but it must be a deliberate decision, because once
   the beta ships those beta ids are *also* forever-stable. **You are minting a
   second permanent id namespace, not a throwaway.**

2. **The ext-state namespace must diverge — or the beta corrupts stable projects.**
   This is the severe one. If the beta writes `banks`/`view_state` under
   `"reasampler"`, a project saved by the beta carries beta-schema state that stable
   then reads (and the forward-only migration may have already retired the key
   stable expected). The beta must write under its **own namespace** (e.g.
   `"reasampler_beta"`). Consequence, and it cuts both ways: a **beta cannot see a
   stable project's bank** (different namespace), so testing the beta against a real
   populated project means the bank looks empty until re-captured. That is the price
   of isolation, and it is the *right* price — a beta that shares stable's namespace
   is a data-loss bug waiting to happen. **This divergence is non-negotiable if
   Option A is chosen.**

3. **The docked-window / docker identity should diverge**, so the two panels are
   distinguishable and don't fight over one dock slot. Lower-severity (a UX
   annoyance, not corruption), but part of the same "everything global must fork"
   picture.

Net: Option A delivers genuine side-by-side at the cost of forking *every global
identity the extension owns*. It is a **compile-time-parameterized second product**,
not a branch artifact — which points straight at Option C as the *mechanism* for how
you'd actually build it.

## Option B — One binary, branch discipline, one installed at a time

`dev` → beta builds, `main` → release builds; the version string carries a
`-beta`/`-dev` suffix so the running build self-identifies; **only one is installed
at a time.** No coexistence — you swap the binary and restart REAPER to change
channels.

- **Pro:** *zero* collision surface. Same command ids, same ext-state namespace, one
  file — because only one is ever loaded. Nothing forks. Simplest by a wide margin.
- **Pro:** matches the repo's existing branch reality (`dev` is the working branch,
  `main` the release branch — visible in the current git state).
- **Con:** no true side-by-side. To A/B stable against beta you swap files and
  restart. For a solo developer this is often *entirely fine* — the friction is a
  file copy + restart, not a corruption risk.
- **Sharp edge (the reason it's still not free):** if the beta writes a
  newer/experimental ext-state schema into a real project, then you swap back to
  stable and open that project, **stable reads beta-written state.** One-binary
  branch discipline removes the *simultaneous* collision but not the *sequential*
  one — the project file is the shared surface across a channel swap. Mitigation:
  either (a) keep the beta strictly schema-compatible with stable (no ext-state
  shape changes on the beta channel — often true, since most beta work is behavior,
  not persistence), or (b) accept "don't open beta-touched real projects in stable"
  as a discipline, or (c) stamp the writing version into the blob (V1) so stable can
  at least *detect* and refuse/migrate rather than silently mis-read.

## Option C — Compile-time build flag (the mechanism, usable under A or B)

A CMake/preprocessor switch (`-DREASAMPLER_CHANNEL=beta`) that, in one build tree,
sets: output name, command-id prefix, ext-state namespace, version suffix, and the
panel channel indicator. This is not really a *third* strategy — it's *how you
implement* the divergence Option A demands, or *how you stamp the suffix* Option B
wants. It's the knob; A and B are policies for the knob.

- Under **Option A**, the flag is what forks the two binaries from one source
  cleanly — flip `REASAMPLER_CHANNEL`, get the beta's name/prefix/namespace/suffix
  as a coordinated set, so the three-way divergence can't get out of sync by hand.
- Under **Option B**, the flag just sets the suffix + a channel tag; name/prefix/
  namespace stay shared because only one loads.

The flag is worth having either way because it makes "what makes a beta a beta" a
**single, auditable definition** instead of scattered `#ifdef`s.

## Decision (V4) — SETTLED (2026-07-26): **Option A — beta-in-isolation / full coexistence**

> **This reverses the note's original recommendation.** The note originally
> recommended Option B (branch discipline, one installed at a time) built on the
> Option C channel flag, with Option A (true simultaneous coexistence) *seam-designed
> but deferred*. **Daniel chose the coexistence path instead.** The superseded
> recommendation prose is retained below the decision (struck through in intent, kept
> for the reasoning trail) so a future reader sees what was weighed; the decision here
> governs.

**Settled shape: beta ships as a separate, fully isolated binary that coexists with
stable in one REAPER.** Concretely, all three global identities fork (this *is*
Option A, built through the Option C compile-time channel flag as the mechanism):

- **Separate binary** — `reaper_reasampler_beta` alongside `reaper_reasampler`, so
  REAPER's startup dlopen loads both and the user runs stable and beta side-by-side.
- **Isolated ext-state namespace** — the beta writes under its own namespace (e.g.
  `"reasampler_beta"`), distinct from stable's `"reasampler"`, so **a beta can never
  read or rewrite a stable project's saved bank/view/tail state.** The price is
  accepted: a beta does not see a stable project's bank (it looks empty until
  re-captured under the beta namespace). That is the correct price — isolation over
  convenience.
- **Isolated forever-stable command-id prefix** — the beta mints its own prefix (e.g.
  `CEREBELLUM_REASAMPLER_BETA_`), so beta and stable actions never collide in
  REAPER's one Actions list and their keybindings stay independent.

The compile-time channel flag (`-DREASAMPLER_CHANNEL=beta`, Option C) remains the
implementation mechanism: one flip coordinates output name + command-id prefix +
ext-state namespace + `-beta` version suffix + panel channel badge as a single
auditable definition, so the three-way divergence can't drift by hand.

### The two permanent commitments this locks in (recorded honestly)

Choosing coexistence over the deferred-seam path accepts two commitments that are
**permanent once the first beta ships** — exactly the prices the original
recommendation flagged as reasons to defer:

1. **A second forever-stable command-id prefix.** The beta's ids are their own
   forever-family (`STABLE_FOREVER_STRING` contract applies to them too the moment a
   beta ships). Beta keybindings do not carry to stable and vice versa. Irreversible.
2. **A second ext-state namespace.** `"reasampler_beta"` is permanent — and its
   isolation means beta and stable never share a project's bank. This is the safety
   property, but it is also a fork of your own test data that you own from day one.

Both are deliberate and accepted; recorded here so no future reader treats them as
oversights.

### Deploy / CD implication (dev-ops hand-off)

The build now **produces two named artifacts per platform** — `reaper_reasampler`
(stable) and `reaper_reasampler_beta` (beta) — selected by `REASAMPLER_CHANNEL`.
That is a dev-ops handoff: the pipeline builds, names, and publishes both channels
(three platform artifacts each). See Part 3.

### The ext-state safety property, now settled by isolation

The sharp edge the original note flagged as the genuine V4 sub-decision — *can a beta
write experimental ext-state that a stable build later reads?* — is **resolved by the
isolated namespace: no.** Beta writes only under `"reasampler_beta"`; stable reads
only `"reasampler"`. There is no shared-project corruption path across the channels,
neither simultaneous nor sequential. V1's writing-version stamp still lands first-wave
(it guards *within-channel* forward migration — stable-1.4 reading stable-1.6 state —
which isolation does not address), but it is no longer load-bearing for cross-channel
safety.

---

### Superseded recommendation (retained for the reasoning trail)

> The following was the note's original V4 recommendation. **It is superseded by the
> settled decision above** (Daniel chose coexistence). Kept because the trade-off
> reasoning — the permanent-price argument in particular — is what the decision was
> weighed against.

~~Start with **Option B (branch discipline, one at a time) implemented through a
compile-time channel flag (Option C)**~~: ship stable as `reaper_reasampler` from
`main`; build beta from `dev` via the channel flag with only a `-beta` suffix + panel
badge; **do not fork the command-id prefix or ext-state namespace**, since under B
only one binary loads and forking prematurely commits a second forever-stable id
family for no gain. Then treat **Option A (true coexistence) as a later, deliberate
upgrade** if swap-and-restart proved too slow — the upgrade being clean precisely
because B was built on the channel flag (flip A on = extend the flag to fork name +
`_BETA_` prefix + `"reasampler_beta"` namespace). The stated reason to defer A: it
forces minting a **second permanent command-id namespace** and a **second ext-state
namespace** on day one — a large, permanent price for a convenience (simultaneous
compare) that might not be needed. **Daniel weighed that price and chose to pay it:
the value of running stable and beta side-by-side, with hard isolation guaranteeing a
beta can never corrupt stable state, outweighed avoiding the two permanent
commitments.**

---

# Part 3 — Deploy / CD touchpoints (hand-off to dev-ops)

Framing only — the actual pipeline is dev-ops's to author. The strategy above
implies these touchpoints:

- **Tag → version.** Release is cut from a git tag on `main`; `project(VERSION)` is
  bumped to match the tag (or the tag is derived from it — pick one direction and
  keep it one-way). Beta builds from `dev` carry `git describe` in the suffix.
- **Channel is a build parameter.** `-DREASAMPLER_CHANNEL=release|beta` selects the
  suffix/badge now (Option B) and, if Option A is ever turned on, the output
  name/prefix/namespace too. One flag, one definition of "what is a beta."
- **Artifact per platform.** The binary is `reaper_*.dll|.dylib|.so`; the macOS/Linux
  builds need the SWELL resgen step (CLAUDE.md §SWELL dialog resources) baked into
  the pipeline. Three platform artifacts per channel per release.
- **Install is copy-in + restart** (no hot reload). A release "deploy" is publishing
  the artifact for the user to drop into `UserPlugins/`; there is no server-side
  rollout. Any auto-update story is out of scope here and would be its own note.
- **The ext-state version stamp (V1)** is the one piece of forward-compatibility
  plumbing the pipeline should ensure ships in the first versioned release, so every
  subsequent build can reason about older saved state.

---

# Settled decisions (all four — Daniel, 2026-07-26)

- **V1 — version scheme: APPROVED as recommended.** Semver, single source of truth in
  CMake `project(reaper_reasampler VERSION x.y.z)`, threaded into the binary. **The
  `"reasampler"` ext-state writing-version stamp is prioritized to the first wave** —
  every project saved without it is harder to migrate later, so the migration seam
  lands early, not deferred.
- **V2 — beta suffix: plain `-beta`.** `project(VERSION)` owns the release triple;
  beta builds carry a `-beta` suffix. The `git describe` decoration was considered and
  **rejected** for legibility ("-beta is better than a random string").
- **V3 — user-visible home: recommendation accepted.** Startup console line
  (`"ReaSampler x.y.z loaded"`) + a bank-panel version/channel readout; about-box
  deferred. Panel placement remains a small residual polish call.
- **V4 — beta channel shape: BETA-IN-ISOLATION (full coexistence).** *Reverses the
  original recommendation.* Beta ships as a **separate binary**
  (`reaper_reasampler_beta`) with an **isolated ext-state namespace** and an
  **isolated forever-stable command-id prefix**, so stable and beta install and run
  side-by-side with no shared-state corruption path. Locks in two permanent
  commitments — a second forever-stable command-id prefix and a second ext-state
  namespace — both accepted. Dev-ops implication: the build now produces two named
  artifacts (stable + beta) per platform.