feat(updates): dev takes the newest bundle, because only its number is behind

The compatibility gate compares a bundle's stated minimum against the core's
package version, and on `dev` that version is the one thing that lags: the
branch carries the endpoints of the next release while still calling itself
the last one. So a console built against those endpoints — which dev can
serve perfectly well, having the endpoints — was refused by a check that is,
on this branch alone, measuring the wrong thing.

It showed up immediately. With adminui 6.1.0 published asking for
4.0.0-beta.22, the next push to dev would have failed the dev image build at
`fetch:admin`, and a dev install pressing update in the console would have
been told to update a server that already had what it needed.

Dev is therefore exempt outright, at every point the gate exists: the
build-time fetch, the in-place update's preflight, the release resolver
(which takes the newest of its channel rather than walking for a compatible
one, saving a request per candidate), and the status the console reads. What
dev is for is trying a fix, and what that needs is the newest of everything.

`isDevBuild` is deliberately not `readBuildChannel() === 'dev'`. That
function answers `dev` for anything that does not claim otherwise, which is
the right way round for a warning and the wrong way round for a permission —
a server-dist tarball unpacked outside a repository declares nothing, and
must not inherit what dev may do. It has to be said: BUILD_CHANNEL, the
build stamp, or a checkout literally on the branch.

Said in three places because none of them can read the others. The dev job
sets it on the build step, since a CI checkout is on a detached HEAD with no
branch to read; the Dockerfile declares it in the builder stage, since ARGs
do not cross stages and `.git` is not copied into the image; and the branch
is the fallback for a developer building in their own working copy.

Release builds are untouched. A beta or stable build still fails when its
bundles ask for a core it is not — which, since a release bumps the version
in the same commit that tags it, only fires when that bump is missing.

Author: rudyberends

.github/workflows/release.yml

@@ -134,8 +134,14 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      # Declared here as well as on the image below, because `npm run build` fetches the web
+      # bundles and checks them against this checkout's version — and on dev that version is
+      # behind the code by design, so the newest bundle is what this image should carry.
+      # A CI checkout is on a detached HEAD, so the branch cannot be read; it has to be said.
       - name: Build
         run: npm run build
+        env:
+          BUILD_CHANNEL: dev
 
       - name: Run tests
         run: npm test

Dockerfile

@@ -18,6 +18,14 @@ RUN npm config delete proxy \
     && npm config delete https-proxy \
     && npm ci
 COPY . .
+
+# The build fetches the Admin UI and Player bundles and checks them against this source
+# tree's version. On dev that version is behind the code by design, so the check is waived
+# there and the image carries the newest bundles — which is the point of a dev image.
+# It has to be declared in this stage: ARGs do not cross stages, `.git` is not copied in, so
+# the branch cannot be read here either, and without it every build looks like "not dev".
+ARG BUILD_CHANNEL
+ENV BUILD_CHANNEL=${BUILD_CHANNEL}
 RUN npm run build
 RUN npm prune --omit=dev
 

scripts/bundleCompat.mjs

@@ -10,7 +10,11 @@
  * Deliberately a hard failure rather than a warning. The asymmetry is what makes that safe:
  * it can only fire when the *bundle* is ahead of the core being built, never when the core
  * is ahead of the bundle, so an ordinary release — core moves first, bundles follow — never
- * sees it. `SONN_SKIP_BUNDLE_COMPAT=1` is there for the deliberate exception.
+ * sees it. `SONN_SKIP_BUNDLE_COMPAT=1` is there for the deliberate one-off.
+ *
+ * Dev is exempt outright — see `isDevBuild`. It is the one branch where the version number is
+ * routinely behind the code, so the comparison is measuring the wrong thing there and only
+ * there.
  *
  * A plain `.mjs` duplicate of `src/shared/semver.ts` on purpose: these scripts run before
  * `tsc` has produced `dist/`, so they cannot import the compiled module they mirror. The
@@ -78,6 +82,33 @@ export function satisfiesMin(running, minimum) {
   return compareVersions(have, min) >= 0;
 }
 
+/**
+ * Whether this build is explicitly a development one, in which case minimums do not apply.
+ *
+ * On `dev` the version number is the only thing behind: the branch carries the endpoints of
+ * the next release while still calling itself the last one, so a bundle built against those
+ * endpoints fails a check that is, on this branch alone, measuring the wrong thing. Dev takes
+ * the newest of everything — nobody runs it except to try a fix.
+ *
+ * Declared rather than assumed. `BUILD_CHANNEL` is what CI sets, and it is read first because
+ * a CI checkout is on a detached HEAD and has no branch to read. Falling back to the branch is
+ * for the developer running `npm run build` in their own working copy. A checkout that is
+ * neither is not dev, and stays gated.
+ */
+export async function isDevBuild(cwd) {
+  const declared = (process.env.BUILD_CHANNEL ?? '').trim().toLowerCase();
+  if (declared) return declared === 'dev';
+  const stamp = (process.env.BUILD_TIMESTAMP ?? '').trim().toLowerCase();
+  if (stamp.startsWith('dev-')) return true;
+  if (stamp.startsWith('testing-')) return false;
+  try {
+    const head = await fs.readFile(join(cwd, '.git', 'HEAD'), 'utf8');
+    return /^ref:\s*refs\/heads\/dev\s*$/i.test(head.trim());
+  } catch {
+    return false;
+  }
+}
+
 export async function readCoreVersion(cwd) {
   try {
     const pkg = JSON.parse(await fs.readFile(join(cwd, 'package.json'), 'utf8'));
@@ -96,6 +127,10 @@ export async function readCoreVersion(cwd) {
  */
 export async function assertBundleFitsCore(dir, coreVersion, label) {
   if ((process.env.SONN_SKIP_BUNDLE_COMPAT ?? '').trim() === '1') return;
+  if (await isDevBuild(process.cwd())) {
+    console.log(`[bundle-compat] dev build, taking ${label} as published`);
+    return;
+  }
   let manifest;
   try {
     manifest = JSON.parse(await fs.readFile(join(dir, 'version.json'), 'utf8'));

src/adapters/http/adminApi/misc/miscHandlers.ts

@@ -6,7 +6,7 @@ import https from 'node:https';
 import os from 'node:os';
 import { join, resolve } from 'node:path';
 import { pipeline } from 'node:stream/promises';
-import { readBuildChannel, readBuildVersion, readGitBranch, readPackageVersion } from '@/shared/serverVersion';
+import { isDevBuild, readBuildChannel, readBuildVersion, readGitBranch, readPackageVersion } from '@/shared/serverVersion';
 import { compareVersions, satisfiesMin } from '@/shared/semver';
 import {
   describeBundle,
@@ -426,8 +426,13 @@ function handleInfo(
     // stamp distinguishes two builds of the same core and must not change whether a
     // bundle fits it.
     const publicDir = deps.runtimeConfig.http.publicDir;
-    const player = describeBundle(publicDir, 'player', pkgVersion);
-    const adminUi = describeBundle(publicDir, 'admin', pkgVersion);
+    // On dev every bundle fits, because dev installs every bundle. Reporting otherwise would
+    // put a permanent "built for a newer server" note on a branch that is meant to run ahead.
+    const dev = isDevBuild();
+    const fitsAnything = (bundle: ReturnType<typeof describeBundle>) =>
+      dev ? { ...bundle, satisfied: true } : bundle;
+    const player = fitsAnything(describeBundle(publicDir, 'player', pkgVersion));
+    const adminUi = fitsAnything(describeBundle(publicDir, 'admin', pkgVersion));
     // The oldest, because that is what "the speakers run X" has to mean when they disagree.
     const runningClients = (deps.sonnClientVersions?.() ?? []).filter(Boolean).sort(compareVersions);
     const sonnClient = { installed: runningClients[0] ?? null };
@@ -886,6 +891,10 @@ async function resolveWebBundleRelease(
 
   const channel = detectReleaseChannel();
   const runningCore = readPackageVersion();
+  // Dev takes the newest of its channel outright. Walking for a compatible release would be
+  // walking past bundles this server can serve, on the strength of a version string that is
+  // stale by design between releases — and it would spend a request per candidate doing it.
+  const newestWins = isDevBuild();
 
   let releases: BundleRelease[] = [];
   try {
@@ -905,6 +914,19 @@ async function resolveWebBundleRelease(
       ? [...releases.filter((r) => r.prerelease), ...releases.filter((r) => !r.prerelease)]
       : releases.filter((r) => !r.prerelease);
 
+  const first = candidates[0];
+  if (newestWins && first) {
+    log.debug(`${spec.label} taking the newest release, minimums are waived on dev`, {
+      tag: first.tag,
+    });
+    return {
+      release: first.tag,
+      distUrl: bundleAssetUrl(spec, first.tag),
+      channel,
+      picked: 'newest',
+    };
+  }
+
   for (const candidate of candidates.slice(0, BUNDLE_LOOKBACK)) {
     let manifest: BundleManifest;
     try {
@@ -1008,7 +1030,10 @@ async function performWebBundleUpdate(
      * also what makes it free: nothing is rolled back because nothing moved.
      */
     const staged = readBundleManifest(stagingDir);
-    const rejection = rejectIfCoreTooOld(runningCore, staged);
+    // Waived on dev, where the version number is the only thing behind: the branch already
+    // carries the endpoints of the next release while still calling itself the last one, so
+    // the minimum would refuse a bundle this server can serve perfectly well.
+    const rejection = isDevBuild() ? null : rejectIfCoreTooOld(runningCore, staged);
     if (rejection) {
       await fs.rm(stagingDir, { recursive: true, force: true }).catch(() => {});
       deps.log.warn(`${spec.label} update refused, needs a newer core`, { release, ...rejection });

src/shared/serverVersion.ts

@@ -89,6 +89,36 @@ export function readBuildChannel(): BuildChannel {
   return 'dev';
 }
 
+/**
+ * Whether this is explicitly a development build.
+ *
+ * Separate from `readBuildChannel` because of that function's default: it answers `dev`
+ * for anything that does not claim otherwise, which is the right way round for a warning
+ * ("this might not be a release") and the wrong way round for a permission. A deployment
+ * that simply carries no channel — a server-dist tarball unpacked outside a repository —
+ * must not inherit whatever dev is allowed to do.
+ *
+ * What it is allowed to do is skip the bundle compatibility gate. On `dev` the version
+ * number is the only thing that lags: the branch carries the endpoints of the next release
+ * while still calling itself the last one, so a bundle built against those endpoints is
+ * refused by a check that is, on this branch alone, measuring the wrong thing. Nobody runs
+ * dev except to try a fix, and what they need there is the newest of everything.
+ */
+export function isDevBuild(): boolean {
+  const declared = process.env.BUILD_CHANNEL?.trim().toLowerCase();
+  if (declared && (BUILD_CHANNELS as readonly string[]).includes(declared)) {
+    return declared === 'dev';
+  }
+  const stamp = process.env.BUILD_TIMESTAMP?.trim().toLowerCase() ?? '';
+  if (stamp.startsWith('dev-')) {
+    return true;
+  }
+  if (stamp.startsWith('testing-')) {
+    return false;
+  }
+  return readGitBranch()?.trim().toLowerCase() === 'dev';
+}
+
 /** Appends the CI build stamp when present, so nightly builds are distinguishable. */
 export function readBuildVersion(pkgVersion: string = readPackageVersion()): string {
   const tsRaw = process.env.BUILD_TIMESTAMP?.trim();

tests/bundleCompat.test.ts

@@ -13,6 +13,7 @@ import {
   rejectIfCoreTooOld,
 } from '../src/shared/bundleManifest';
 import { buildMiscRoutes } from '../src/adapters/http/adminApi/misc/miscHandlers';
+import { isDevBuild } from '../src/shared/serverVersion';
 
 /*
  * The Admin UI and the Player are separate repositories, updated by separate buttons, in
@@ -173,3 +174,51 @@ test('info reports both bundles, so the console is no longer the one part unname
   assert.equal(sent.body.player.satisfied, true);
   assert.ok('requires' in sent.body, 'the other direction is reported even when unset');
 });
+
+/*
+ * Dev is exempt. It is the one branch whose version number is behind its own code — it
+ * carries the endpoints of the next release while still calling itself the last one — so a
+ * minimum written against those endpoints refuses a bundle the server can serve. Nobody runs
+ * dev except to try a fix, and what they need there is the newest of everything.
+ */
+
+function withEnv<T>(env: Record<string, string | undefined>, fn: () => T): T {
+  const previous = new Map(Object.keys(env).map((key) => [key, process.env[key]]));
+  for (const [key, value] of Object.entries(env)) {
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+  try {
+    return fn();
+  } finally {
+    for (const [key, value] of previous) {
+      if (value === undefined) delete process.env[key];
+      else process.env[key] = value;
+    }
+  }
+}
+
+test('a dev build is one that says so, never one that failed to say otherwise', () => {
+  const clean = { BUILD_CHANNEL: undefined, BUILD_TIMESTAMP: undefined };
+  assert.equal(withEnv({ ...clean, BUILD_CHANNEL: 'dev' }, isDevBuild), true);
+  assert.equal(withEnv({ ...clean, BUILD_CHANNEL: 'beta' }, isDevBuild), false);
+  assert.equal(withEnv({ ...clean, BUILD_CHANNEL: 'stable' }, isDevBuild), false);
+  // Older images predate BUILD_CHANNEL and stamp the channel into the build id.
+  assert.equal(withEnv({ ...clean, BUILD_TIMESTAMP: 'dev-20260912' }, isDevBuild), true);
+  assert.equal(withEnv({ ...clean, BUILD_TIMESTAMP: 'testing-20260912' }, isDevBuild), false);
+
+  /*
+   * The one that matters. `readBuildChannel` answers `dev` for anything that does not claim
+   * otherwise, which is right for a warning and wrong for a permission: a server-dist tarball
+   * unpacked outside a repository declares nothing, and must not inherit what dev may do.
+   * Asserted from a working directory with no `.git`, which is exactly that deployment.
+   */
+  const nowhere = mkdtempSync(join(tmpdir(), 'sonn-nogit-'));
+  const cwd = process.cwd();
+  process.chdir(nowhere);
+  try {
+    assert.equal(withEnv(clean, isDevBuild), false, 'silence is not a claim to be dev');
+  } finally {
+    process.chdir(cwd);
+  }
+});