@bongos/core 1.20.78 → 1.20.80

package/scripts/gds/release-core.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+'use strict';
+// scripts/gds/release-core.js — may this version of @bongos/core be RELEASED? (task 1004298, ADR 0361)
+//
+// Merges publish as candidates (under the `next` label). A version reaches other projects only when
+// the owner presses Release on /deploy, which runs publish.yml's release job, which asks this script
+// and then moves the registry's `latest` label. Every consumer that offers a version to a project
+// other than the platform hall reads `latest` (update-channel.js versionsForFollow), so this label IS
+// the release.
+//
+// WHY A SCRIPT AND NOT A SHELL STEP. The rule has four ways to say no, and a shell `if` chain inside
+// a workflow file is the one place nothing can test it. The decision is pure and unit-tested
+// (tests/release_core.mjs); the workflow only runs it and acts on `go`.
+//
+// THE RULE:
+//   - the version must be a plain x.y.z (it is interpolated into an npm command line);
+//   - it must be PUBLISHED — Release labels a version, it never builds one;
+//   - it must be newer than the current release. Releasing an OLDER version would move every
+//     project's offer backwards, which is a rollback for everyone, not a release; that is a
+//     different act and needs a person at a terminal, not a button.
+//   - releasing the version already released is a no-op, not an error — a double press is harmless.
+//
+// Usage (in publish.yml's release job):
+//   node scripts/gds/release-core.js --version 1.20.80
+// Prints the decision; writes go=true|false to $GITHUB_OUTPUT when set. Exit 0 for go and no-op,
+// 1 for a refusal.
+
+const fs = require('node:fs');
+const { spawnSync } = require('node:child_process');
+const { CORE_PKG, parseSemver, compareSemver, isStable } = require('./update-channel.js');
+
+const VERSION_RE = /^[0-9]+\.[0-9]+\.[0-9]+$/;
+
+/**
+ * PURE. `versions`: every published version. `latest`: the version the registry labels `latest`
+ * now, or null. Returns { go, noop, reason }.
+ */
+function releaseDecision({ version, versions, latest } = {}) {
+  const v = String(version == null ? '' : version).trim();
+  if (!VERSION_RE.test(v)) return { go: false, noop: false, reason: `"${v}" is not a version (x.y.z)` };
+  const list = Array.isArray(versions) ? versions : [];
+  if (!list.includes(v)) return { go: false, noop: false, reason: `${v} is not published — Release labels a published version, it never builds one` };
+  if (!isStable(v)) return { go: false, noop: false, reason: `${v} is a prerelease` };
+  if (latest && parseSemver(latest)) {
+    const c = compareSemver(v, latest);
+    if (c === 0) return { go: false, noop: true, reason: `${v} is already the release` };
+    if (c < 0) return { go: false, noop: false, reason: `${v} is older than the current release ${latest} — releasing it would move every project backwards` };
+  }
+  return { go: true, noop: false, reason: latest ? `release ${v} (was ${latest})` : `release ${v} (no release yet)` };
+}
+
+function readRegistry({ pkg = CORE_PKG, run = spawnSync } = {}) {
+  const res = run('npm', ['view', pkg, 'versions', 'dist-tags', '--json'], { encoding: 'utf8', timeout: 60000 });
+  if (!res || res.status !== 0) return { ok: false, error: String((res && res.stderr) || 'npm view failed').trim().split('\n')[0] };
+  try {
+    const doc = JSON.parse(String(res.stdout || '{}'));
+    const versions = Array.isArray(doc.versions) ? doc.versions : (typeof doc.versions === 'string' ? [doc.versions] : []);
+    const tags = doc['dist-tags'] || {};
+    return { ok: true, versions, latest: typeof tags.latest === 'string' ? tags.latest : null };
+  } catch (e) {
+    return { ok: false, error: `unparseable npm output: ${e.message}` };
+  }
+}
+
+function main(argv = process.argv.slice(2), { env = process.env, read = readRegistry, log = console.log, err = console.error } = {}) {
+  const i = argv.indexOf('--version');
+  const version = i >= 0 ? argv[i + 1] : '';
+  const out = (go) => { if (env.GITHUB_OUTPUT) fs.appendFileSync(env.GITHUB_OUTPUT, `go=${go}\n`); };
+  const reg = read();
+  if (!reg.ok) { err(`release-core: could not read the registry (${reg.error})`); out(false); return 1; }
+  const d = releaseDecision({ version, versions: reg.versions, latest: reg.latest });
+  out(d.go);
+  if (d.go || d.noop) { log(`release-core: ${d.reason}`); return 0; }
+  err(`release-core: refused — ${d.reason}`);
+  return 1;
+}
+
+if (require.main === module) process.exit(main());
+
+module.exports = { releaseDecision, main };

package/scripts/gds/update-channel.js

@@ -23,9 +23,9 @@
 //                has released to other projects. DEFAULT, for every project.
 //   candidates — every published version, the moment it is published. The platform's own hall, and
 //                only it: Bongos runs each version before anyone else is offered it.
-// The channel bounds how FAR a jump may go; the follow bounds which versions exist to jump to. Until
-// candidates publish under their own label (task 1004298), `latest` is the newest version and the two
-// follows pick the same target — the axis exists first so that the split changes nothing for Bongos.
+// The channel bounds how FAR a jump may go; the follow bounds which versions exist to jump to. Once
+// merges publish as candidates (task 1004298, ADR 0361), `latest` moves only when the owner presses
+// Release, so the two follows part: the platform hall takes each candidate, everyone else the release.
 //
 // WHY the registry as the source (not vendored tarballs): a subscription needs a LIVE source of
 // truth for "what's the newest published core?" — that's `npm view @bongos/core versions` against the
@@ -139,6 +139,14 @@ function versionsForFollow({ follow, available, released } = {}) {
   return list.filter((v) => compareSemver(v, released) <= 0);
 }
 
+// The follow a provisioned project takes, from its hosting shape (task 1004298, ADR 0361). The
+// control-plane row IS the platform's own hall, the one project that runs every candidate; every other
+// shape follows releases. Derived, not stored: there is exactly one platform hall, and a column an
+// operator could set on a tenant would be one more way to hand a project an unreleased version.
+function followForShape(hostingShape) {
+  return hostingShape === 'control-plane' ? 'candidates' : DEFAULT_FOLLOW;
+}
+
 // Would `channel` permit an unattended jump from `installed` to `candidate`? True only when candidate
 // is a STABLE release strictly newer than installed AND within the channel's blast radius. Any invalid
 // input, an unknown installed version, a prerelease candidate, or a major bump ⇒ false (fail-closed).
@@ -463,6 +471,7 @@ module.exports = {
   normalizeFollow,
   versionsForFollow,
   readReleaseTags,
+  followForShape,
   SUBSCRIPTIONS_REL,
   parseSemver,
   isStable,

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.78'; // 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/init.mjs

@@ -389,15 +389,18 @@ test('layerPackageJson: no package.json → creates one; second run → present,
 // ---- greenfield installability: package.json minting + writeConfigs (ADR 0108 gap 1/4, task 2053) ----
 // PURE — no fs, no npm. The imperative vendor + `npm install` lockfile step lives in main()
 // and is deliberately NOT unit-tested (keeps real npm out of the suite, per the task).
-test('buildInstancePackageJson: no package.json → mints a private one with the caret core dep + start/migrate scripts', () => {
+test('buildInstancePackageJson: no package.json → mints a private one with the caret core dep + hall/migrate scripts', () => {
   const pkg = init.buildInstancePackageJson(null, { name: 'demo' });
   assert.equal(pkg.name, 'demo');
   assert.equal(pkg.private, true);
   assert.equal(pkg.dependencies[init.CORE_PKG], init.coreDepRange());   // caret when no tarball vendored
-  assert.equal(pkg.scripts.start, init.INSTANCE_START_SCRIPT);
+  assert.equal(pkg.scripts.hall, init.INSTANCE_HALL_SCRIPT);
   assert.equal(pkg.scripts.migrate, init.INSTANCE_MIGRATE_SCRIPT);
-  // the start/migrate scripts must target the installed core package so `npm ci` output is runnable
-  assert.match(pkg.scripts.start, /node_modules\/@bongos\/core\/src\/platform-server\.js$/);
+  // `npm start` is left for the project's OWN app (task 1004484): a host like Render reads it
+  // as "how this app starts", and the hall there has no database and times out.
+  assert.equal(pkg.scripts.start, undefined);
+  // the hall/migrate scripts must target the installed core package so `npm ci` output is runnable
+  assert.match(pkg.scripts.hall, /node_modules\/@bongos\/core\/src\/platform-server\.js$/);
   assert.match(pkg.scripts.migrate, /node_modules\/@bongos\/core\/scripts\/migrate\.sh$/);
 });
 
@@ -419,6 +422,18 @@ test('buildInstancePackageJson: preserves existing fields + never clobbers a cus
   assert.equal(pkg.dependencies[init.CORE_PKG], 'file:vendor/bongos-core-1.17.0.tgz'); // dep (re)pinned
 });
 
+test('buildInstancePackageJson: a start that is exactly the old scaffolded hall command moves to "hall" (task 1004484)', () => {
+  const old = 'node node_modules/@bongos/core/src/platform-server.js';
+  const pkg = init.buildInstancePackageJson({ scripts: { start: old, test: 'node --test' } }, { name: 'demo' });
+  assert.equal(pkg.scripts.start, undefined, 'npm start no longer runs the hall');
+  assert.equal(pkg.scripts.hall, old);
+  assert.equal(pkg.scripts.test, 'node --test');
+  // an owner's own "hall" script is never overwritten by the move
+  const kept = init.buildInstancePackageJson({ scripts: { start: old, hall: 'node my-hall.js' } }, { name: 'demo' });
+  assert.equal(kept.scripts.hall, 'node my-hall.js');
+  assert.equal(kept.scripts.start, old, 'with "hall" taken, start is left as the owner has it');
+});
+
 // --- enabled-module dep composition (ADR 0138 / task 2160) --------------------
 
 test('enabledModuleDeps: merges only the ENABLED modules’ declared deps', () => {
@@ -475,7 +490,8 @@ test('writeConfigs (greenfield): mints package.json with the caret core dep + st
     assert.equal(pkg.name, 'cloud-bongos');                  // slugified productName
     assert.equal(pkg.private, true);
     assert.equal(pkg.dependencies[init.CORE_PKG], init.coreDepRange());
-    assert.equal(pkg.scripts.start, init.INSTANCE_START_SCRIPT);
+    assert.equal(pkg.scripts.hall, init.INSTANCE_HALL_SCRIPT);
+    assert.equal(pkg.scripts.start, undefined);
     assert.equal(pkg.scripts.migrate, init.INSTANCE_MIGRATE_SCRIPT);
   } finally {
     rmSync(dir, { recursive: true, force: true });

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');
+});