Nightly releases: test in real use, then promote the tested commit to stable #507

Goal

Adopt upstream's release practice (Jackson, 2026-10-09). Verify a change as far as AI review, screenshots and videos go; merge; publish a nightly from j5/main; run the nightly in real daily work, including multi-server setups that are hard to reproduce in tests; fix what breaks; then cut a stable release from the commit that was tested.

Where J5 is today

The app code J5 carries from upstream already understands a nightly channel, pointed at J5's GitHub releases: j5 update --channel nightly, the installer's channel option, the desktop app's Settings → Update track, the nightly update feed, and "J5 Code (Nightly)" branding. Signing and notarization use the same secrets as stable.

What blocks it:

• J5 Release accepts only x.y.z and x.y.z-preview.<date>.<n> versions.
• Versions are committed on throwaway release branches, so a stable release is never the commit that was tested. Upstream stamps the version at build time and promotes the nightly's commit.
• Nothing publishes from j5/main on a schedule or on demand.
• A nightly migrates a person's real database one way, and only two specific migrations take a snapshot first. j5 update and desktop app updates take no copy.

Decisions (Jackson, 2026-10-09)

• Roll forward only. Going back to an older build is an emergency path: restore a snapshot. Supported downgrades are out of scope.
• Snapshot, no refusal. Take a snapshot before any pending migration. Do not add a refusal to start on a database with unknown migrations: upstream logs and starts, and refusing would be a new divergence. A runbook step covers the deliberate downgrade. If a silent bad downgrade ever bites, offer the refusal upstream (Upstream give-back backlog (hold until V2 merges upstream) #276).
• Version bump by pull request. After a stable release the bump to j5/main is a PR, not a bot push, so the branch rule stays as it is. It has to merge promptly: until it does, new nightlies sort below the stable just shipped.

Plan, in order

1. Data safety. Extend the existing snapshot (apps/server/src/j5/persistence/LedgerMigrationSnapshot.ts, called from the seam in apps/server/src/persistence/Sqlite.ts) to run whenever any migration is pending in either lane, named for the version being left, with a cap on how many are kept. Add the rollback steps to the runbook. Ship this in a stable release before any machine takes a nightly.
2. Callable workflows. Give j5-macos-build.yml and j5-release.yml a workflow_call entry taking a commit and a version, stamp the version in CI with scripts/update-release-package-versions.ts, and make the verify and publish steps channel-aware (J5 Code (Nightly).app, nightly-mac.yml, pre-release, never latest). The manual stable and preview paths keep working.
3. Nightly workflow. On demand first. Resolve 0.0.(Z+1)-nightly.<date>.<run> from j5/main with upstream's scripts/resolve-nightly-release.ts, then build, archive and publish.
4. Prove one nightly by hand. Install on a fresh server with the installer's nightly channel; switch an installed server with j5 update --channel nightly and the Mac app with Update track → Nightly; publish a second nightly and confirm both follow it; return both to stable.
5. Promotion. J5 Release builds a chosen nightly's commit as x.y.z, publishes it as latest, and opens the version-bump PR.
6. Docs, then a schedule. Runbook, the user docs' channel section, and FORK.md's CI section. Then turn on a daily schedule gated by upstream's .github/scripts/check-nightly-release.cjs (new commits since the last nightly).

Scope notes

• Stable and nightly share one install, one profile and one database on a machine, switched in place, as upstream's do.
• Mobile is out. The phone follows its host's channel for server updates, and J5 ships iOS only through a manual TestFlight build.
• Start with one server and one Mac. A nightly that changes the client-server or peer protocol splits a mixed fleet until every machine moves.
• Differences from upstream that remain, all in J5-owned workflows: a separate workflow (upstream's also publishes npm, the hosted app, the marketing site and AUR), two platforms, J5's own version line, and the PR for the bump.

To find out along the way

• Whether GitHub lets the workflow tag a release at a commit j5/main has moved past. Upstream does this; docs/j5/runbooks/macos-packaging.md warns about it. The fallback is to push the tag at the start of the run.
• How long a snapshot of a 2 GB database adds to startup, and how much disk the retention cap should allow.
• Whether j5-macos-build.yml and j5-release.yml need the vendored-gitlink cleanup step the other J5 workflows have (neither has run since the upstream advance in feat(j5): advance to upstream main at 29980a3140 #500).