@bongos/core 1.20.79 → 1.20.80

package/src/bongos/core-update.js

@@ -25,6 +25,12 @@
 // OWN function (scripts/gds/update-channel.js) and is imported, not copied: the
 // banner must never offer a version the runner would then refuse, and ADR 0280
 // is the record of what a second copy of this contract costs when it drifts.
+//
+// ONLY RELEASED VERSIONS ARE OFFERED (task 1004298, ADR 0361). Merges publish as candidates; a
+// version reaches other projects when the owner presses Release, which moves the registry's
+// `latest` label. So the banner offers versions at or below `latest` (versionsForFollow, the same
+// function the sweep uses), and with no readable label it has no answer rather than offering a
+// candidate. The platform hall runs ahead of `latest` by design, so it simply reads "current".
 
 const https = require('node:https');
 const {
@@ -32,6 +38,7 @@ const {
   DEFAULT_CHANNEL,
   normalizeChannel,
   resolveChannelTarget,
+  versionsForFollow,
 } = require('../../scripts/gds/update-channel.js');
 
 const REGISTRY_ORIGIN = 'https://registry.npmjs.org';
@@ -50,9 +57,9 @@ const FETCH_TIMEOUT_MS = 4000;
  * same field for the same reason; the failure it prevents is a project that is
  * months behind being told, confidently, that it is current.
  */
-function coreUpdateVerdict({ running, available, channel } = {}) {
+function coreUpdateVerdict({ running, available, released, channel } = {}) {
   const ch = normalizeChannel(channel == null ? DEFAULT_CHANNEL : channel);
-  const versions = Array.isArray(available) ? available.filter((v) => typeof v === 'string') : [];
+  const versions = versionsForFollow({ follow: 'released', available, released });
   if (!running || typeof running !== 'string' || !versions.length) {
     return { running: running || null, latest: null, behind: false, reading: 'no_answer', channel: ch };
   }
@@ -88,7 +95,9 @@ function fetchPublishedVersions({ pkg = CORE_PKG, origin = REGISTRY_ORIGIN, time
           try {
             const doc = JSON.parse(body);
             const versions = Object.keys((doc && doc.versions) || {});
-            done(versions.length ? { ok: true, versions } : { ok: false, versions: [], error: 'no versions in packument' });
+            const tag = doc && doc['dist-tags'] && doc['dist-tags'].latest;
+            const released = typeof tag === 'string' ? tag : null;
+            done(versions.length ? { ok: true, versions, released } : { ok: false, versions: [], error: 'no versions in packument' });
           } catch (e) { done({ ok: false, versions: [], error: `unparseable packument: ${e.message}` }); }
         });
       });
@@ -103,13 +112,13 @@ function fetchPublishedVersions({ pkg = CORE_PKG, origin = REGISTRY_ORIGIN, time
 
 // Process-local cache. Deliberately not a table: it is a derived fact with a
 // six-hour life, and a restart re-deriving it costs one request.
-const cache = { at: 0, versions: [], ok: false, inflight: null };
+const cache = { at: 0, versions: [], released: null, ok: false, inflight: null };
 
 
 
 async function publishedVersions({ now = Date.now, ttlMs = TTL_MS, fetch = fetchPublishedVersions, store = cache } = {}) {
   const t = now();
-  if (store.ok && t - store.at < ttlMs) return { ok: true, versions: store.versions, cached: true };
+  if (store.ok && t - store.at < ttlMs) return { ok: true, versions: store.versions, released: store.released, cached: true };
   // IN-FLIGHT DE-DUPE. Without it, every request arriving during a cold-cache
   // window starts its OWN registry read — the cache only collapses them once the
   // first one has landed. Small, because the audience is archon-only and the TTL
@@ -119,8 +128,8 @@ async function publishedVersions({ now = Date.now, ttlMs = TTL_MS, fetch = fetch
   store.inflight = (async () => {
     try {
       const r = await fetch();
-      if (r.ok) { store.ok = true; store.at = t; store.versions = r.versions; }
-      return { ok: r.ok, versions: r.versions, cached: false, error: r.error };
+      if (r.ok) { store.ok = true; store.at = t; store.versions = r.versions; store.released = r.released || null; }
+      return { ok: r.ok, versions: r.versions, released: r.released || null, cached: false, error: r.error };
     } finally {
       store.inflight = null;
     }
@@ -141,7 +150,7 @@ async function publishedVersions({ now = Date.now, ttlMs = TTL_MS, fetch = fetch
 async function readCoreUpdate({ running, channel, get, ...deps } = {}) {
   const fetch = deps.fetch || (get ? () => fetchPublishedVersions({ get }) : fetchPublishedVersions);
   const r = await publishedVersions({ ...deps, fetch });
-  return coreUpdateVerdict({ running, available: r.ok ? r.versions : [], channel });
+  return coreUpdateVerdict({ running, available: r.ok ? r.versions : [], released: r.ok ? r.released : null, channel });
 }
 
 // readCoreUpgrades — the instance's own core-upgrade ledger, newest first: when the

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.20.79'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.20.80'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/core_update_banner.mjs

@@ -21,8 +21,10 @@ const CU = require_(path.join(ROOT, 'src/bongos/core-update.js'));
 // through it rather than reaching past it into internals that no route uses.
 // `store` is per-call so the unit assertions never share the module's own cache.
 const freshStore = () => ({ at: 0, versions: [], ok: false, inflight: null });
-const verdictFor = (running, available, channel) =>
-  CU.readCoreUpdate({ running, channel, store: freshStore(), fetch: async () => ({ ok: true, versions: available }) });
+// `released` is the registry's `latest` label. It defaults to the newest version listed, which is
+// what it was before merges published as candidates (task 1004298); the candidate tests pass it.
+const verdictFor = (running, available, channel, released = available[available.length - 1]) =>
+  CU.readCoreUpdate({ running, channel, store: freshStore(), fetch: async () => ({ ok: true, versions: available, released }) });
 const SHELL = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/shell.js'), 'utf8');
 
 // ── the verdict ────────────────────────────────────────────────────────────────
@@ -53,6 +55,40 @@ test('a prerelease ahead is not offered', async () => {
   assert.equal(v.behind, false);
 });
 
+// ── only released versions are offered (task 1004298, ADR 0361) ──────────────────
+
+test('a candidate newer than the release is NOT offered; the release is', async () => {
+  const v = await verdictFor('1.19.861', ['1.19.861', '1.19.865', '1.19.871'], undefined, '1.19.865');
+  assert.equal(v.latest, '1.19.865', 'the newest RELEASED version, not the newest published');
+  assert.equal(v.behind, true);
+});
+
+test('a project already on the release is current, however many candidates follow it', async () => {
+  const v = await verdictFor('1.19.865', ['1.19.865', '1.19.870', '1.19.871'], undefined, '1.19.865');
+  assert.equal(v.behind, false);
+  assert.equal(v.latest, null);
+  assert.equal(v.reading, 'ok');
+});
+
+test('the platform hall, running ahead of the release, reads current — never "behind" a version older than it', async () => {
+  const v = await verdictFor('1.19.871', ['1.19.865', '1.19.871'], undefined, '1.19.865');
+  assert.equal(v.behind, false);
+});
+
+test('a registry that names no release is NO ANSWER, never the newest candidate', async () => {
+  const v = await verdictFor('1.19.861', ['1.19.861', '1.19.871'], undefined, null);
+  assert.equal(v.reading, 'no_answer');
+  assert.equal(v.latest, null);
+});
+
+test('the packument\'s `latest` label is what bounds the offer', async () => {
+  const v = await CU.readCoreUpdate({
+    running: '1.19.861', store: freshStore(),
+    get: fakeGet((res) => { res._body = JSON.stringify({ 'dist-tags': { latest: '1.19.865', next: '1.19.871' }, versions: { '1.19.861': {}, '1.19.865': {}, '1.19.871': {} } }); }),
+  });
+  assert.equal(v.latest, '1.19.865');
+});
+
 test('NO ANSWER is not "up to date" — the distinction the banner turns on', async () => {
   // A registry that cannot be reached, and a box that cannot name its own core:
   // two different roads to the same must-say-nothing state.
@@ -96,7 +132,7 @@ test('a real packument is parsed, and its newest version reaches the verdict', a
   // Drives the ACTUAL https parsing path, only the socket is fake.
   const v = await CU.readCoreUpdate({
     running: '1.19.861', store: freshStore(),
-    get: fakeGet((res) => { res._body = JSON.stringify({ versions: { '1.19.861': {}, '1.19.871': {} } }); }),
+    get: fakeGet((res) => { res._body = JSON.stringify({ 'dist-tags': { latest: '1.19.871' }, versions: { '1.19.861': {}, '1.19.871': {} } }); }),
   });
   assert.equal(v.reading, 'ok');
   assert.equal(v.latest, '1.19.871');
@@ -120,7 +156,7 @@ test('the cache spares the registry a second read inside the TTL', async () => {
 test('concurrent cold-cache reads make ONE outbound call, not one each', async () => {
   const store = freshStore();
   let calls = 0;
-  const fetch = () => { calls++; return new Promise((r) => setTimeout(() => r({ ok: true, versions: ['1.19.871'] }), 5)); };
+  const fetch = () => { calls++; return new Promise((r) => setTimeout(() => r({ ok: true, versions: ['1.19.871'], released: '1.19.871' }), 5)); };
   const args = { running: '1.19.861', store, fetch, now: () => 1 };
   const all = await Promise.all([CU.readCoreUpdate(args), CU.readCoreUpdate(args), CU.readCoreUpdate(args)]);
   assert.equal(calls, 1, 'three simultaneous cold reads share one registry call');
@@ -179,7 +215,7 @@ test('a real request through the assembled router returns the verdict, not a 500
 
   // Warm the module's OWN cache through the public door, so the route's own
   // dependency-free call is served from it and the test never touches the network.
-  await CU.readCoreUpdate({ running: '1.19.861', fetch: async () => ({ ok: true, versions: ['1.19.861', '1.19.871'] }) });
+  await CU.readCoreUpdate({ running: '1.19.861', fetch: async () => ({ ok: true, versions: ['1.19.861', '1.19.871'], released: '1.19.871' }) });
   const express = r2('express');
   const app = express();
   app.use(r2(routePath)());

package/tests/core_upgrade_runner.mjs

@@ -1416,7 +1416,14 @@ console.log('\nthe project\'s own update rule (task 1004445):');
 const realChannel = require('../scripts/gds/update-channel.js');
 const withRealChannel = (over) => {
   const d = makeDeps(over);
-  d.updateChannel = { ...realChannel, listAvailableVersions: () => ({ ok: true, versions: over.available }) };
+  // readReleaseTags is stubbed too: the real one shells out to npm. `released` defaults to the newest
+  // version listed, which is what `latest` was before candidates (task 1004298).
+  const released = over.released !== undefined ? over.released : over.available[over.available.length - 1];
+  d.updateChannel = {
+    ...realChannel,
+    listAvailableVersions: () => ({ ok: true, versions: over.available }),
+    readReleaseTags: () => (released ? { ok: true, released, tags: { latest: released } } : { ok: false, error: 'no latest label', released: null, tags: {} }),
+  };
   return d;
 };
 
@@ -1528,5 +1535,63 @@ await t('the drain loop writes the class beside the sentence (behaviour: tests/p
   assert.match(src, /SET failure_class = \$2, failure_reason = \$3/);
 });
 
+console.log('\nwho is offered a candidate (task 1004298, ADR 0361):');
+
+await t('the platform hall (control-plane) is moved to a candidate newer than the release', async () => {
+  const d = withRealChannel({ installed: '1.19.1081', served: '1.19.1083', available: ['1.19.1081', '1.19.1082', '1.19.1083'], released: '1.19.1082' });
+  const r = await R.coreUpgradeInstance(inst({ hosting_shape: 'control-plane' }), d, intent({ target_version: '1.19.1083' }));
+  assert.ok(!(r.error && /not a published|unknown version|outside/.test(r.error)), `the candidate must be admitted: ${r.error}`);
+  assert.ok(d.ran.some((c) => /upgrade\.js/.test(c) && /--to 1\.19\.1083/.test(c)), 'the upgrade was invoked for the candidate');
+});
+
+await t('any other project is refused a candidate the owner has not released', async () => {
+  const d = withRealChannel({ installed: '1.19.1081', served: '1.19.1081', available: ['1.19.1081', '1.19.1082', '1.19.1083'], released: '1.19.1082' });
+  const r = await R.coreUpgradeInstance(inst({ hosting_shape: 'co-tenant', slug: 'demo' }), d, intent({ target_version: '1.19.1083' }));
+  assert.equal(r.ok, false);
+  assert.ok(!d.ran.some((c) => /upgrade\.js/.test(c)), 'and nothing was run');
+});
+
+await t('…and takes the released version', async () => {
+  const d = withRealChannel({ installed: '1.19.1081', served: '1.19.1082', available: ['1.19.1081', '1.19.1082', '1.19.1083'], released: '1.19.1082' });
+  const r = await R.coreUpgradeInstance(inst({ hosting_shape: 'co-tenant', slug: 'demo' }), d, intent({ target_version: '1.19.1082' }));
+  assert.ok(d.ran.some((c) => /upgrade\.js/.test(c) && /--to 1\.19\.1082/.test(c)), `the release was invoked: ${r.error}`);
+});
+
+await t('a project that follows releases is offered nothing when the registry names no release', async () => {
+  const queries = [];
+  await R.snapshotCoreVersions(inst({ hosting_shape: 'co-tenant', slug: 'demo' }), withRealChannel({ served: '1.19.1081', available: ['1.19.1081', '1.19.1083'], released: null, queries }));
+  const q = queries.find((x) => /provisioning_core_version_snapshot/.test(x.sql));
+  assert.equal(q.params[3], null, 'no recommended version on a guess');
+});
+
+await t('the snapshot offers a tenant the release and the platform hall the newest candidate', async () => {
+  const available = ['1.19.1081', '1.19.1082', '1.19.1083'];
+  const offered = async (hosting_shape) => {
+    const queries = [];
+    await R.snapshotCoreVersions(inst({ hosting_shape, slug: hosting_shape }), withRealChannel({ served: '1.19.1081', available, released: '1.19.1082', queries }));
+    return queries.find((x) => /provisioning_core_version_snapshot/.test(x.sql)).params[3];
+  };
+  assert.equal(await offered('co-tenant'), '1.19.1082');
+  assert.equal(await offered('control-plane'), '1.19.1083');
+});
+
+await t('a pass over several projects reads the released label ONCE, not once per project', async () => {
+  const d = withRealChannel({ served: '1.19.1081', available: ['1.19.1081', '1.19.1082', '1.19.1083'], released: '1.19.1082', queries: [] });
+  let reads = 0;
+  const real = d.updateChannel.readReleaseTags;
+  d.updateChannel.readReleaseTags = (...a) => { reads++; return real(...a); };
+  for (const slug of ['a', 'b', 'c']) await R.snapshotCoreVersions(inst({ hosting_shape: 'co-tenant', slug }), d);
+  assert.equal(reads, 1, `three projects, one npm view — read ${reads} times`);
+});
+
+await t('a FAILED label read is not kept: the next project asks again', async () => {
+  const d = withRealChannel({ served: '1.19.1081', available: ['1.19.1081', '1.19.1083'], released: null, queries: [] });
+  let reads = 0;
+  const real = d.updateChannel.readReleaseTags;
+  d.updateChannel.readReleaseTags = (...a) => { reads++; return real(...a); };
+  for (const slug of ['a', 'b']) await R.snapshotCoreVersions(inst({ hosting_shape: 'co-tenant', slug }), d);
+  assert.equal(reads, 2);
+});
+
 console.log(`\ncore_upgrade_runner: ${passed} passed, ${failed} failed`);
 if (failed) process.exit(1);

package/tests/npm_release_release.mjs

@@ -0,0 +1,195 @@
+// tests/npm_release_release.mjs — the deploy page's Release button (task 1004298, ADR 0361).
+//
+// Merges publish as candidates; Release on /deploy makes a version the one every other project is
+// offered. Pinned here: the evidence beside each button (how long a version ran on this hall, and
+// whether it was rolled back), what a press does and refuses, the GitHub call it makes, and the
+// route's gate.
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+
+const require = createRequire(import.meta.url);
+const { releaseCandidates, requestRelease } = require('../modules/npm-release/release.js');
+const gp = require('../modules/lifecycle/workflow-dispatch.js');
+const buildRouter = require('../modules/npm-release/routes/release.js');
+
+const H = 3600000;
+const NOW = Date.parse('2026-10-01T12:00:00Z');
+const at = (hoursAgo) => new Date(NOW - hoursAgo * H).toISOString();
+
+// ── the evidence ─────────────────────────────────────────────────────────────────
+
+const VERSIONS = ['1.20.70', '1.20.71', '1.20.72', '1.20.73', '1.20.74'];
+
+test('candidates are the versions newer than the release and no newer than this hall runs, newest first', () => {
+  const c = releaseCandidates({ rows: [], versions: VERSIONS, released: '1.20.71', live: '1.20.73', now: NOW });
+  assert.deepEqual(c.map((x) => x.version), ['1.20.73', '1.20.72']);
+});
+
+test('with no release yet, everything up to what this hall runs is a candidate', () => {
+  const c = releaseCandidates({ rows: [], versions: VERSIONS, released: null, live: '1.20.71', now: NOW });
+  assert.deepEqual(c.map((x) => x.version), ['1.20.71', '1.20.70']);
+});
+
+test('the version still running here has run from when it went in until now', () => {
+  const rows = [
+    { to_version: '1.20.72', applied_at: at(30), note: 'auto-subscription' },
+    { to_version: '1.20.73', applied_at: at(6), note: 'auto-subscription' },
+  ];
+  const [top, older] = releaseCandidates({ rows, versions: VERSIONS, released: '1.20.71', live: '1.20.73', now: NOW });
+  assert.equal(top.version, '1.20.73');
+  assert.equal(top.still_running, true);
+  assert.equal(top.hours_on_hall, 6);
+  assert.equal(older.still_running, false);
+  assert.equal(older.hours_on_hall, 24, 'it ran until the next version replaced it, not until now');
+});
+
+test('a rolled-back move to a version is shown against that version only', () => {
+  const rows = [
+    { to_version: '1.20.72', applied_at: at(30), note: '' },
+    { to_version: '1.20.72', applied_at: at(10), note: 'rolled_back: health check failed (attempted 1.20.72 → 1.20.73, restored 1.20.72)' },
+    { to_version: '1.20.73', applied_at: at(5), note: 'auto-subscription' },
+  ];
+  const c = releaseCandidates({ rows, versions: VERSIONS, released: '1.20.71', live: '1.20.73', now: NOW });
+  assert.equal(c.find((x) => x.version === '1.20.73').rolled_back, true);
+  assert.equal(c.find((x) => x.version === '1.20.72').rolled_back, false);
+  assert.equal(c.find((x) => x.version === '1.20.72').hours_on_hall, 25, 'a rollback row is not a move away');
+});
+
+test('a version the ledger never shows going in has no evidence, not a made-up duration', () => {
+  const [c] = releaseCandidates({ rows: [], versions: VERSIONS, released: '1.20.72', live: '1.20.73', now: NOW });
+  assert.equal(c.on_hall_since, null);
+  assert.equal(c.hours_on_hall, null);
+});
+
+test('no live version means no candidates (a package this hall does not run)', () => {
+  assert.deepEqual(releaseCandidates({ rows: [], versions: VERSIONS, released: null, live: null, now: NOW }), []);
+});
+
+// ── a press ──────────────────────────────────────────────────────────────────────
+
+const REG = { ok: true, versions: VERSIONS, latest: '1.20.71' };
+
+test('a releasable version dispatches publish.yml\'s release job with that version, and answers 202', async () => {
+  const calls = [];
+  const r = await requestRelease({ version: '1.20.73', registry: REG, dispatch: async (a) => { calls.push(a); return { ok: true }; } });
+  assert.equal(r.status, 202);
+  assert.deepEqual(calls, [{ workflow: 'publish.yml', ref: 'main', inputs: { release_version: '1.20.73' } }]);
+});
+
+test('an older version, an unpublished one and a non-version are refused before GitHub is asked', async () => {
+  const dispatch = async () => { throw new Error('must not dispatch'); };
+  for (const version of ['1.20.70', '1.20.99', 'latest']) {
+    const r = await requestRelease({ version, registry: REG, dispatch });
+    assert.equal(r.status, 409, version);
+    assert.equal(r.body.error.code, 'not_releasable');
+  }
+});
+
+test('the version already released is a no-op, not a GitHub run', async () => {
+  const r = await requestRelease({ version: '1.20.71', registry: REG, dispatch: async () => { throw new Error('must not dispatch'); } });
+  assert.equal(r.status, 200);
+  assert.equal(r.body.noop, true);
+});
+
+test('an unreadable registry and a missing dispatcher both release nothing, and say so', async () => {
+  assert.equal((await requestRelease({ version: '1.20.73', registry: { ok: false }, dispatch: async () => ({ ok: true }) })).status, 503);
+  assert.equal((await requestRelease({ version: '1.20.73', registry: REG, dispatch: null })).body.error.code, 'dispatch_unavailable');
+});
+
+test('GitHub refusing for want of Actions: write is named as exactly that', async () => {
+  const r = await requestRelease({ version: '1.20.73', registry: REG, dispatch: async () => ({ ok: false, code: 'REFUSED', status: 403 }) });
+  assert.equal(r.status, 502);
+  assert.match(r.body.error.message, /Actions: write/);
+});
+
+// ── the GitHub call ──────────────────────────────────────────────────────────────
+
+const REPO = { owner: 'someowner', repo: 'somerepo' };
+
+test('dispatchWorkflow POSTs ref + inputs to the workflow\'s dispatches endpoint', async () => {
+  let captured = null;
+  const fetchImpl = async (url, opts) => { captured = { url, opts, body: JSON.parse(opts.body) }; return { ok: false, status: 204 }; };
+  const r = await gp.dispatchWorkflow({ workflow: 'publish.yml', ref: 'main', inputs: { release_version: '1.20.73' } }, { token: 'T', repoInfo: REPO, fetchImpl });
+  assert.deepEqual(r, { ok: true });
+  assert.equal(captured.url, 'https://api.github.com/repos/someowner/somerepo/actions/workflows/publish.yml/dispatches');
+  assert.equal(captured.opts.method, 'POST');
+  assert.deepEqual(captured.body, { ref: 'main', inputs: { release_version: '1.20.73' } });
+});
+
+test('dispatchWorkflow starts only publish.yml, and refuses an unsafe ref, without calling GitHub otherwise', async () => {
+  const fetchImpl = async () => { throw new Error('must not fetch'); };
+  for (const args of [{ workflow: '../x.yml' }, { workflow: 'publish.yml', ref: 'main; rm' }, { workflow: 'publish' }, { workflow: 'unit.yml' }, { workflow: 'deploy-prod.yml' }]) {
+    assert.equal((await gp.dispatchWorkflow(args, { token: 'T', repoInfo: REPO, fetchImpl })).code, 'BAD_INPUT', JSON.stringify(args));
+  }
+});
+
+test('dispatchWorkflow: no credential is UNCONFIGURED; a 403 is REFUSED with its status; a throw is UNREACHABLE', async () => {
+  // resolveToken also tries the GitHub App, which this process has no key for, then the PAT env.
+  const saved = process.env.GITHUB_PUSH_TOKEN;
+  delete process.env.GITHUB_PUSH_TOKEN;
+  try {
+    assert.equal((await gp.dispatchWorkflow({ workflow: 'publish.yml' }, { token: null, repoInfo: REPO, fetchImpl: async () => { throw new Error('must not fetch'); } })).code, 'UNCONFIGURED');
+  } finally {
+    if (saved !== undefined) process.env.GITHUB_PUSH_TOKEN = saved;
+  }
+  assert.deepEqual(await gp.dispatchWorkflow({ workflow: 'publish.yml' }, { token: 'T', repoInfo: REPO, fetchImpl: async () => ({ ok: false, status: 403 }) }), { ok: false, code: 'REFUSED', status: 403 });
+  assert.equal((await gp.dispatchWorkflow({ workflow: 'publish.yml' }, { token: 'T', repoInfo: REPO, fetchImpl: async () => { throw new Error('down'); } })).code, 'UNREACHABLE');
+});
+
+// ── the route ────────────────────────────────────────────────────────────────────
+
+test('the route is gated like the deploy page (core.pin.move), never by rank', () => {
+  const router = buildRouter();
+  const layer = router.stack.find((l) => l.route && l.route.path === '/npm-release/release');
+  assert.ok(layer.route.methods.post);
+  assert.equal(layer.route.stack.length, 3, 'requireBuilder, the permission gate, then the handler');
+  const src = fs.readFileSync(new URL('../modules/npm-release/routes/release.js', import.meta.url), 'utf8');
+  assert.match(src, /api\.requireBuilder,\s*\n\s*api\.requirePermission\('core\.pin\.move'\)/);
+  assert.doesNotMatch(src, /api\.requireRank\(/);
+});
+
+const handlerOf = (opts) => buildRouter(opts).stack.find((l) => l.route).route.stack.at(-1).handle;
+const fakeRes = () => ({ code: 200, body: null, status(s) { this.code = s; return this; }, json(v) { this.body = v; return this; } });
+
+test('the handler refuses a body that is not { version: x.y.z }', async () => {
+  const h = handlerOf({ readRegistry: async () => { throw new Error('must not read'); } });
+  for (const body of [{}, { version: 'latest' }, { version: '1.20.73', extra: 1 }]) {
+    const res = fakeRes();
+    await h({ body, builder: { id: 1 } }, res);
+    assert.equal(res.code, 400, JSON.stringify(body));
+  }
+});
+
+test('the handler refuses on a deploy page for another package', async () => {
+  const res = fakeRes();
+  await handlerOf({ pkg: () => 'left-pad', readRegistry: async () => { throw new Error('must not read'); } })({ body: { version: '1.20.73' }, builder: { id: 1 } }, res);
+  assert.equal(res.code, 409);
+  assert.equal(res.body.error.code, 'not_the_core');
+});
+
+test('the handler dispatches through the lifecycle port and relays the 202', async () => {
+  const calls = [];
+  const res = fakeRes();
+  await handlerOf({
+    readRegistry: async () => ({ registry: REG }),
+    port: () => ({ dispatchWorkflow: async (a) => { calls.push(a); return { ok: true }; } }),
+  })({ body: { version: '1.20.73' }, builder: { id: 1 } }, res);
+  assert.equal(res.code, 202);
+  assert.equal(calls[0].inputs.release_version, '1.20.73');
+});
+
+test('the handler with no lifecycle port releases nothing (503)', async () => {
+  const res = fakeRes();
+  await handlerOf({ readRegistry: async () => ({ registry: REG }), port: () => null })({ body: { version: '1.20.73' }, builder: { id: 1 } }, res);
+  assert.equal(res.code, 503);
+});
+
+test('the page renders the Release section and posts to the route', () => {
+  const src = fs.readFileSync(new URL('../modules/npm-release/public/work.js', import.meta.url), 'utf8');
+  assert.match(src, /\$\{releaseHtml\(data\)\}/);
+  assert.match(src, /client\.request\('POST', `\$\{API\}\/npm-release\/release`, \{ body: \{ version \} \}\)/);
+  assert.match(src, /window\.confirm\(/, 'a release is confirmed before it is sent');
+});

package/tests/release_core.mjs

@@ -0,0 +1,110 @@
+// tests/release_core.mjs — may this version be released? (task 1004298, ADR 0361)
+//
+// release-core.js is what publish.yml's release job asks before it moves the registry's `latest`
+// label — the label every project other than the platform hall is offered. These pin each way it
+// says no, and that a refusal never reaches the label.
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const { releaseDecision, main } = require('../scripts/gds/release-core.js');
+
+const VERSIONS = ['1.20.70', '1.20.75', '1.20.80', '1.20.81-rc.1'];
+
+test('a published version newer than the release goes', () => {
+  const d = releaseDecision({ version: '1.20.80', versions: VERSIONS, latest: '1.20.70' });
+  assert.equal(d.go, true);
+  assert.match(d.reason, /was 1\.20\.70/);
+});
+
+test('with no release yet, any published stable version goes', () => {
+  assert.equal(releaseDecision({ version: '1.20.75', versions: VERSIONS, latest: null }).go, true);
+});
+
+test('the version already released is a harmless no-op, not a refusal', () => {
+  const d = releaseDecision({ version: '1.20.75', versions: VERSIONS, latest: '1.20.75' });
+  assert.equal(d.go, false);
+  assert.equal(d.noop, true);
+});
+
+test('an OLDER version is refused: it would move every project backwards', () => {
+  const d = releaseDecision({ version: '1.20.70', versions: VERSIONS, latest: '1.20.75' });
+  assert.equal(d.go, false);
+  assert.equal(d.noop, false);
+  assert.match(d.reason, /backwards/);
+});
+
+test('a version that was never published is refused', () => {
+  const d = releaseDecision({ version: '1.20.99', versions: VERSIONS, latest: '1.20.70' });
+  assert.equal(d.go, false);
+  assert.match(d.reason, /not published/);
+});
+
+test('anything that is not a plain x.y.z is refused before it reaches a command line', () => {
+  for (const v of ['', '1.20', 'latest', '1.20.80; rm -rf /', '1.20.81-rc.1', null, undefined]) {
+    assert.equal(releaseDecision({ version: v, versions: VERSIONS, latest: '1.20.70' }).go, false, String(v));
+  }
+});
+
+const run = (argv, registry) => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'release-core-'));
+  const out = path.join(dir, 'out');
+  const lines = [];
+  const code = main(argv, { env: { GITHUB_OUTPUT: out }, read: () => registry, log: (s) => lines.push(s), err: (s) => lines.push(s) });
+  return { code, output: fs.existsSync(out) ? fs.readFileSync(out, 'utf8') : '', lines };
+};
+
+test('the CLI writes go=true and exits 0 for a release', () => {
+  const r = run(['--version', '1.20.80'], { ok: true, versions: VERSIONS, latest: '1.20.75' });
+  assert.equal(r.code, 0);
+  assert.equal(r.output, 'go=true\n');
+});
+
+test('the CLI writes go=false and exits 1 for a refusal, so the label never moves', () => {
+  const r = run(['--version', '1.20.70'], { ok: true, versions: VERSIONS, latest: '1.20.75' });
+  assert.equal(r.code, 1);
+  assert.equal(r.output, 'go=false\n');
+});
+
+test('the CLI writes go=false and exits 0 for a double press', () => {
+  const r = run(['--version', '1.20.75'], { ok: true, versions: VERSIONS, latest: '1.20.75' });
+  assert.equal(r.code, 0);
+  assert.equal(r.output, 'go=false\n');
+});
+
+test('an unreadable registry is a refusal, never a guess', () => {
+  const r = run(['--version', '1.20.80'], { ok: false, error: 'E503' });
+  assert.equal(r.code, 1);
+  assert.equal(r.output, 'go=false\n');
+});
+
+// ── the workflow wires it as described ─────────────────────────────────────────
+
+const YML = fs.readFileSync(fileURLToPath(new URL('../.github/workflows/publish.yml', import.meta.url)), 'utf8');
+
+test('publish.yml: the release job asks release-core.js and moves `latest` only on go', () => {
+  assert.match(YML, /release_version:/, 'the dispatch input exists');
+  assert.match(YML, /node scripts\/gds\/release-core\.js --version "\$RELEASE_VERSION"/);
+  assert.match(YML, /if: steps\.decide\.outputs\.go == 'true'\s+run: npm dist-tag add "@bongos\/core@\$RELEASE_VERSION" latest/);
+});
+
+test('publish.yml: the version reaches the shell through env, never inline ${{ }} interpolation', () => {
+  assert.doesNotMatch(YML, /release-core\.js --version "\$\{\{/);
+  assert.doesNotMatch(YML, /dist-tag add "@bongos\/core@\$\{\{/);
+});
+
+test('publish.yml: a release dispatch never also runs the publish job', () => {
+  assert.match(YML, /github\.event_name == 'workflow_dispatch' && inputs\.release_version == ''/);
+});
+
+test('publish.yml: candidates publish under `next` only when the owner has armed it', () => {
+  assert.match(YML, /CANDIDATES: \$\{\{ vars\.PUBLISH_AS_CANDIDATE \}\}/);
+  assert.match(YML, /if \[ "\$CANDIDATES" = "1" \]; then TAG_ARGS="--tag next"; fi/);
+  assert.match(YML, /npm publish "\$TGZ" --access public \$TAG_ARGS/);
+});

package/tests/update_channel.mjs

@@ -348,6 +348,13 @@ t('normalizeFollow: released and candidates are the words; anything else reads a
   for (const v of [undefined, null, '', 'every', 'latest', 'next', 42]) assert.equal(uc.normalizeFollow(v), 'released', String(v));
 });
 
+t('followForShape: only the platform hall (control-plane) follows candidates (task 1004298)', () => {
+  assert.equal(uc.followForShape('control-plane'), 'candidates');
+  for (const shape of ['co-tenant', 'cloud-host', 'byo-host', undefined, null, 'bogus']) {
+    assert.equal(uc.followForShape(shape), 'released', `${shape} follows releases`);
+  }
+});
+
 t('versionsForFollow: candidates takes every version; released stops at the released label', () => {
   const available = ['1.19.1038', '1.19.1039', '1.19.1040', '1.19.1041'];
   assert.deepEqual(uc.versionsForFollow({ follow: 'candidates', available, released: '1.19.1039' }), available);