@bongos/core 1.20.69 → 1.20.71

package/scripts/gds/module-assess-version.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// scripts/gds/module-assess-version.js — re-assess a store version when it is
+// published: record Tests as pending, run the Security gate, compose the score
+// (task 1003794; ADR 0343; tables from core_265).
+//
+// WHY. A new version is a new thing to judge, so the store's publish route queues
+// this after it answers the author. Tests is recorded `pending`, and only when the
+// version has no Tests result yet: a published module's tests run only in the
+// separate test environment, never on the control plane (module-assess-tests.js).
+// The Security gate reads the tarball and asks npm about the declared dependencies
+// — it never runs the module's code, so it is safe here. Then the score is
+// composed (module-assess-score.js). Install, Reliability and Tester feedback
+// arrive later from their own tasks; each recompose picks them up.
+//
+// The route goes through queueAssessment, so the web process runs one assessment
+// at a time (the gate's npm resolve + audit can take two minutes) and holds at most
+// QUEUE_MAX waiting; past that a publish is logged as not assessed, and the CLI
+// below re-runs it. This file is apart from the composer so the signal CLIs can
+// recompose without a require cycle (composer <- security, tests, this).
+//
+//   node scripts/gds/module-assess-version.js <store_module_versions.id>   assess + print
+
+const { recomposeScore } = require('./module-assess-score');
+
+// Re-assess one version (on publish): Tests pending, the Security gate, then the
+// score. `recordSecurity` is injectable so tests need no npm. Never throws for a
+// failed measurement — that is recorded as the signal's outcome — and resolves
+// { ok: false, code } only when the version does not exist.
+async function assessVersion(versionId, { db, recordSecurity } = {}) {
+  const pool = db || require('../../src/bongos/pool').pool;
+  const { rows: [ver] } = await pool.query(
+    'SELECT id, module_key, version FROM store_module_versions WHERE id = $1', [versionId]);
+  if (!ver) return { ok: false, code: 'version_not_found', message: `no store_module_versions row ${versionId}` };
+
+  // Only a version with no Tests result yet: a re-assess must never hide a real
+  // score behind a newer "pending".
+  await pool.query(
+    `INSERT INTO module_assessment_signals (version_id, part, outcome, score, sample_size, reason, detail)
+     SELECT $1::bigint, 'tests', 'pending', NULL, NULL, $2::text, '{}'::jsonb
+      WHERE NOT EXISTS (SELECT 1 FROM module_assessment_signals WHERE version_id = $1::bigint AND part = 'tests')`,
+    [ver.id, 'waiting for the separate test environment: a published module\'s tests never run on the control plane']);
+  const record = recordSecurity || require('./module-assess-security').recordSecuritySignal;
+  const security = await record(ver.id, { db: pool });
+  const composed = await recomposeScore(ver.id, { db: pool });
+  return { ok: true, version: ver, security: security && security.signal, score: composed.score };
+}
+
+// One assessment at a time in this process, at most QUEUE_MAX waiting. Resolves
+// at once with whether the version was queued; a failed assessment is logged and
+// never stops the next one. `run` is injectable for tests.
+const QUEUE_MAX = 20;
+let tail = Promise.resolve();
+let waiting = 0;
+function queueAssessment(versionId, { log = console, run = (id) => module.exports.assessVersion(id) } = {}) {
+  if (waiting >= QUEUE_MAX) {
+    log.warn({ versionId }, `assessment queue full (${QUEUE_MAX} waiting): version not assessed; run module-assess-version.js ${versionId}`);
+    return false;
+  }
+  waiting += 1;
+  tail = tail.then(() => run(versionId))
+    .catch((e) => { log.error({ versionId, err: e && e.message }, 'assessment after publish failed'); })
+    .finally(() => { waiting -= 1; });
+  return true;
+}
+
+async function main(argv) {
+  const id = argv[0];
+  if (!/^\d+$/.test(String(id || ''))) {
+    console.error('usage: node scripts/gds/module-assess-version.js <store_module_versions.id>');
+    return 2;
+  }
+  const res = await assessVersion(id);
+  if (!res.ok) { console.error(res.message); return 1; }
+  console.log(`version ${id}: ${res.score.formula}`);
+  return 0;
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2)).then((code) => { process.exitCode = code; }, (e) => { console.error(e.stack || e.message); process.exitCode = 1; });
+}
+
+module.exports = { assessVersion, queueAssessment, QUEUE_MAX };

package/scripts/gds/module.js

@@ -58,7 +58,7 @@
 //   bongos module new <key>            scaffold modules/<key>/
 //   bongos module new <key> --force    overwrite an existing modules/<key>/
 //   bongos module list [--catalog]     browse the module catalog (author + origin credit)
-//   bongos upgrade                     pre-check enabled modules vs the core version
+//   bongos upgrade [--no-store]        pre-check enabled modules vs the core version + list store updates
 //   bongos module check <key> [--sign-off "Name <email>"]   AGPL/publish pre-check + DCO sign-off
 //   bongos module install <key> [--version X.Y.Z]   acquire from the store, verify, place (not enabled)
 //   bongos module update <key> [--version X.Y.Z]    move an installed store module forward
@@ -371,10 +371,10 @@ function gatherUpgrade({ modulesDir = MODULES_DIR, core = coreVersion(), env = p
 
   const rows = [];
   for (const { key, manifest } of loaded) {
-    rows.push({ key, coreVersion: manifest.coreVersion, enabled: enabled[key] === true, satisfied: true, ...upkeep(manifest) });
+    rows.push({ key, version: manifest.version || null, coreVersion: manifest.coreVersion, enabled: enabled[key] === true, satisfied: true, ...upkeep(manifest) });
   }
   for (const { key, manifest, reason } of skippedFull) {
-    rows.push({ key, coreVersion: manifest ? manifest.coreVersion : null, enabled: enabled[key] === true, satisfied: false, reason, ...upkeep(manifest) });
+    rows.push({ key, version: (manifest && manifest.version) || null, coreVersion: manifest ? manifest.coreVersion : null, enabled: enabled[key] === true, satisfied: false, reason, ...upkeep(manifest) });
   }
   rows.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
   return { rows, errors, core };
@@ -663,7 +663,76 @@ function cmdNew(args, { log = console.log, errlog = console.error } = {}) {
   return 0;
 }
 
-function cmdUpgrade(_args, { log = console.log, errlog = console.error, gather = gatherUpgrade } = {}) {
+// ---------------------------------------------------------------------------
+// Available module updates — the store half of `bongos upgrade` (task 1003787)
+// ---------------------------------------------------------------------------
+
+// Ask the store for the newest version of every module here that carries an exact
+// version (the I/O half). A key the store does not know is absent from the answer,
+// so a module built here, or one the core ships, simply has nothing to report.
+// Never throws: no session or an unreachable store comes back as
+// { checked: false, reason }, because the compatibility pre-check must work
+// offline and must never fail on the store's account.
+async function gatherUpdates(rows, { request } = {}) {
+  const keys = rows.filter((r) => r.version && parseVersion(String(r.version))).map((r) => r.key);
+  if (!keys.length) return { checked: true, latest: {} };
+  let call;
+  try { call = request || storeRequest(); }
+  catch (e) { return { checked: false, reason: e.message }; }
+  let res;
+  try { res = await call('GET', `/store/modules/latest?keys=${keys.map(encodeURIComponent).join(',')}`); }
+  catch (e) { return { checked: false, reason: `the store could not be reached — ${e.message}` }; }
+  // A 404 here is a server whose core predates this route, not a missing module.
+  if (res.status === 404) return { checked: false, reason: "this server's store does not answer update checks yet (its core is older)" };
+  if (!res.ok) return { checked: false, reason: `the store answered ${storeError(res)}` };
+  return { checked: true, latest: (res.data && res.data.latest) || {} };
+}
+
+// Decide what is stale from rows + the store's answer (pure — tests drive it).
+// UPDATES = a module whose store version is newer than the one installed; `fits`
+// says whether that newer version can mount on this core (when it cannot, the
+// update waits for the core — it is not something to run now). DELISTED = an
+// installed module the store has delisted: it keeps working, but no further
+// versions will come (ADR 0338 D2). Neither ever blocks — an update is news, and
+// what blocks `bongos upgrade` is still only an incompatible ENABLED module.
+function evaluateUpdates(rows = [], latest = {}, core) {
+  const { satisfies } = require('../../src/module-loader/semver');
+  const updates = [];
+  const delisted = [];
+  for (const r of rows) {
+    const store = latest[r.key];
+    const have = r.version && parseVersion(String(r.version));
+    if (!store || !have) continue;
+    if (store.status === 'delisted') { delisted.push({ key: r.key, installed: r.version, enabled: r.enabled }); continue; }
+    const next = parseVersion(String(store.version));
+    if (!next || cmp(next, have) <= 0) continue;
+    let fits = false;
+    try { fits = !!(core && store.core_version && satisfies(core, store.core_version)); } catch { fits = false; }
+    updates.push({ key: r.key, installed: r.version, latest: store.version, coreVersion: store.core_version, enabled: r.enabled, fits });
+  }
+  return { updates, delisted };
+}
+
+function reportUpdates(found, verdict, { log, errlog }) {
+  log('\nModule updates (from the store):');
+  if (!found.checked) {
+    log(`  not checked — ${found.reason}. The compatibility check above still stands.`);
+    return;
+  }
+  const { updates, delisted } = evaluateUpdates(verdict.rows, found.latest, verdict.core);
+  for (const u of updates) {
+    const how = u.fits
+      ? `run \`bongos module update ${u.key}\``
+      : `needs core ${u.coreVersion}; this core is ${verdict.core}, so it waits until the core moves`;
+    log(`  ↑ ${u.key.padEnd(18)} ${u.installed} → ${u.latest}  — ${how}`);
+  }
+  for (const d of delisted) {
+    errlog(`  ! ${d.key.padEnd(18)} ${d.installed}  — delisted in the store: it keeps working, but no further versions will come`);
+  }
+  if (!updates.length && !delisted.length) log('  every installed store module is on its newest version.');
+}
+
+async function cmdUpgrade(args = [], { log = console.log, errlog = console.error, gather = gatherUpgrade, checkUpdates = gatherUpdates } = {}) {
   const data = gather();
   const verdict = evaluateUpgrade(data);
 
@@ -701,6 +770,11 @@ function cmdUpgrade(_args, { log = console.log, errlog = console.error, gather =
     errlog(`  ! ${verdict.undeclared.length} module(s) declare no \`maintenance\` block — nobody is on the hook for them as the core advances (ADR 0166): ${verdict.undeclared.map((r) => r.key).join(', ')}`);
   }
 
+  // What is stale here, beside what is broken: the store's newer versions of the
+  // modules installed from it. Reported either way, and it never changes the exit
+  // code. `--no-store` skips the read (offline, or a CI pre-check).
+  if (!args.includes('--no-store')) reportUpdates(await checkUpdates(verdict.rows), verdict, { log, errlog });
+
   if (!verdict.ok) {
     errlog(`\nREFUSING: ${verdict.blocking.length} enabled module(s) incompatible with core ${verdict.core}: ${verdict.blocking.map((b) => b.key).join(', ')}.`);
     errlog(`Widen each module's coreVersion to a range that includes ${verdict.core} (or hold the core upgrade) before proceeding.`);
@@ -1200,7 +1274,8 @@ function printHelp(out = console.log) {
   out('  bongos module new <key>     Scaffold modules/<key>/ (manifest + skeleton + sample route + HOWTO.md + CLAUDE.md)');
   out('  bongos module list [--catalog] [--search <text>] [--json]');
   out('                              Browse the module catalog — what you can enable, with author + origin credit');
-  out('  bongos upgrade              Pre-check enabled modules against the core version (fail-closed)');
+  out('  bongos upgrade [--no-store] Pre-check enabled modules against the core version (fail-closed),');
+  out('                              then list newer store versions of installed modules (never blocks)');
   out('  bongos module check <key> [--sign-off "Name <email>"]');
   out('                              AGPL/publish pre-check before upstreaming + record a DCO-style sign-off');
   out('  bongos module submit <key> [--sign-off "Name <email>"]');
@@ -1236,7 +1311,7 @@ async function main(argv) {
 module.exports = {
   main, cmdNew, cmdList, cmdUpgrade, cmdCheck, cmdSubmit, cmdPublish, cmdInstall, cmdUpdate, printHelp,
   gatherCatalog, formatCatalog, ownProjectName,
-  scaffoldModule, gatherUpgrade, evaluateUpgrade, buildManifest,
+  scaffoldModule, gatherUpgrade, evaluateUpgrade, gatherUpdates, evaluateUpdates, buildManifest,
   formatMaintenanceHint, isPastRemoveAfter,
   checkModulePublishability, recordSignOff, readSignOff, DCO_STATEMENT,
   listModuleFiles, packageModuleForSubmission,
@@ -1245,8 +1320,11 @@ module.exports = {
 };
 
 if (require.main === module) {
+  // Set the exit code and drain, never a hard exit: install, update and upgrade end
+  // after a store request, and a hard exit there aborts natively on Windows + Node 24
+  // (task 1002734).
   Promise.resolve(main(process.argv)).then(
-    (code) => process.exit(code),
+    (code) => { process.exitCode = code; },
     (e) => { console.error(e); process.exit(1); }
   );
 }

package/scripts/gds/upgrade.js

@@ -1495,5 +1495,5 @@ module.exports = {
 };
 
 if (require.main === module) {
-  main().then((code) => process.exit(code)).catch((e) => { process.stderr.write(`✖ ${e.message}\n`); process.exit(1); });
+  main().then((code) => { if (arg('--to', process.argv.slice(2))) process.exit(code); else process.exitCode = code; }).catch((e) => { process.stderr.write(`✖ ${e.message}\n`); process.exit(1); }); // bare pre-check drains: it ends after a store read (task 1003787), and a hard exit there aborts on Windows (task 1002734)
 }

package/src/bongos/module-store.js

@@ -208,6 +208,30 @@ async function publishedVersionSet(keys, { db } = {}) {
   return new Set(rows.map((r) => `${r.module_key}@${r.version}`));
 }
 
+// The newest published version of each of these modules, for `bongos upgrade`'s
+// "updates available" report (task 1003787). Read-only: unlike resolveAcquirable it
+// takes no entitlement and refuses nothing, so a delisted module still answers,
+// with its status, and the caller says it gets no further versions (ADR 0338 D2).
+// A key the store does not know is simply absent. One query for the whole list.
+// Returns { [key]: { version, core_version, status } }.
+async function latestVersions(keys, { db } = {}) {
+  if (!keys.length) return {};
+  const pool = db || require('./pool').pool;
+  const { rows } = await pool.query(
+    `SELECT v.module_key, v.version, v.core_version, m.status
+       FROM store_module_versions v JOIN store_modules m ON m.module_key = v.module_key
+      WHERE v.module_key = ANY($1)`, [keys]);
+  const out = {};
+  for (const r of rows) {
+    const next = parseVersion(r.version);
+    if (!next) continue;
+    const have = out[r.module_key];
+    if (have && cmp(parseVersion(have.version), next) >= 0) continue;
+    out[r.module_key] = { version: r.version, core_version: r.core_version, status: r.status };
+  }
+  return out;
+}
+
 // The tarball on disk for a version row. artifact_path is relative to the store dir
 // (relativeArtifactPath), and artifactPath() re-validates key + version, so a row
 // can never point a read outside the store.
@@ -221,5 +245,5 @@ function versionArtifactFile(row, { dir = storeDir() } = {}) {
 
 module.exports = {
   stageArtifact, commitArtifact, removeArtifact, relativeArtifactPath, publishVersion,
-  isFreePrice, resolveAcquirable, resolveReadable, publishedVersionSet, versionArtifactFile,
+  isFreePrice, resolveAcquirable, resolveReadable, publishedVersionSet, latestVersions, versionArtifactFile,
 };

package/src/bongos/routes/modules.js

@@ -78,10 +78,11 @@ const modulesLib = require('../../modules');
 const moduleCli = require('../../../scripts/gds/module');
 const moduleSubmissions = require('../module-submissions');
 const moduleArtifact = require('../../../scripts/gds/module-artifact');
+const moduleAssessVersion = require('../../../scripts/gds/module-assess-version');
 const { checkEntitlement, listEntitlements, grantEntitlement, recordAcquired } = require('../module-entitlements');
 const {
   stageArtifact, commitArtifact, removeArtifact, relativeArtifactPath, publishVersion,
-  resolveAcquirable, resolveReadable, publishedVersionSet, versionArtifactFile,
+  resolveAcquirable, resolveReadable, publishedVersionSet, latestVersions, versionArtifactFile,
 } = require('../module-store');
 const { KEY_RE } = require('../../module-loader/manifest-schema');
 const { parseVersion } = require('../../module-loader/semver');
@@ -154,6 +155,11 @@ function listModules() {
 // the oldest entry is dropped.
 const HOWTO_CACHE_MAX = 200;
 
+// How many module keys one GET /store/modules/latest may ask about (task 1003787).
+// An instance installs a handful; the cap keeps the query string and the ANY()
+// list bounded.
+const STORE_LATEST_MAX_KEYS = 200;
+
 module.exports = function buildModulesRouter() {
   const router = express.Router();
   // Checked how-tos by "key@version:tarball_sha256". Per router, so a test's fresh
@@ -388,6 +394,12 @@ module.exports = function buildModulesRouter() {
 
       console.log(`[gds] module "${key}" ${v.version} published to the store by builder ${req.builder.id}`);
       res.status(201).json({ ok: true, created_module: result.created, version: result.version });
+      // A new version is a new thing to judge (task 1003794, ADR 0343): queue its
+      // assessment after answering, since the Security gate asks npm about its
+      // dependencies and can take a minute. The queue runs one at a time and is
+      // capped; a failure is logged, never the author's error, and
+      // `node scripts/gds/module-assess-version.js <id>` re-runs it.
+      setImmediate(() => moduleAssessVersion.queueAssessment(result.version.id, { log }));
     }));
 
   // GET /api/bongos/store/entitlements and /store/modules/:key/entitlement — the
@@ -565,6 +577,26 @@ module.exports = function buildModulesRouter() {
       });
     }));
 
+  // The newest published version of each named module — what `bongos upgrade`
+  // compares an instance's installed store modules against to report the updates
+  // available (task 1003787). `?keys=a,b,c`, at most STORE_LATEST_MAX_KEYS.
+  //
+  // rank: any-builder — a read of public store metadata (version numbers and the
+  // core range each needs, the same facts the how-to page shows). It takes no
+  // entitlement and changes nothing, unlike acquire; a key the store does not know
+  // is simply absent from the answer.
+  router.get('/store/modules/latest', auth.requireBuilder,
+    asyncHandler('GET /store/modules/latest', async (req, res) => {
+      const raw = typeof req.query.keys === 'string' ? req.query.keys : '';
+      const keys = [...new Set(raw.split(',').map((k) => k.trim()).filter(Boolean))];
+      if (!keys.length || keys.length > STORE_LATEST_MAX_KEYS || !keys.every((k) => KEY_RE.test(k))) {
+        return res.fail('bad_request', { status: 400, message: `keys is a comma-separated list of 1 to ${STORE_LATEST_MAX_KEYS} module keys (lowercase kebab-case).` });
+      }
+      const latest = await latestVersions(keys);
+      res.set('Cache-Control', 'no-store');
+      res.json({ latest });
+    }));
+
   router.post('/store/modules/:key/acquired', auth.requireBuilder,
     asyncHandler('POST /store/modules/:key/acquired', async (req, res) => {
       const { key } = req.params;

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.69'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.20.71'; // 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/module_assess_score.mjs

@@ -0,0 +1,276 @@
+// tests/module_assess_score.mjs — composing a store version's assessment signals
+// into its one overall score, and re-assessing a version when it is published
+// (task 1003794; ADR 0343 D2/D3/D5, ADR 0347 D5; tables from core_265). No real
+// DB and no npm: the composer is pure, the writers run against a fake pool that
+// keeps core_265's append-only rows in memory, and the Security gate is injected.
+//
+// Run:  node tests/module_assess_score.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const { composeScore, recomposeScore } = require('../scripts/gds/module-assess-score.js');
+const { assessVersion, queueAssessment, QUEUE_MAX } = require('../scripts/gds/module-assess-version.js');
+
+const sig = (id, part, outcome, score = null) => ({ id, part, outcome, score });
+
+// ---------------------------------------------------------------------------
+// composeScore — the rule, pure
+// ---------------------------------------------------------------------------
+
+test('overall is the plain average of the scored averaged parts, rounded', () => {
+  const s = composeScore({
+    security: sig(1, 'security', 'passed'),
+    tests: sig(2, 'tests', 'scored', 80),
+    install: sig(3, 'install', 'scored', 95),
+    reliability: sig(4, 'reliability', 'scored', 70),
+  });
+  assert.equal(s.overall, 82, '(80 + 95 + 70) / 3 = 81.67 → 82');
+  assert.equal(s.security_passed, true);
+  assert.equal(s.is_new, false);
+  assert.deepEqual(s.signal_ids, [1, 2, 3, 4]);
+  assert.match(s.formula, /Security passed; overall 82 = average of Tests 80, Install 95, Reliability 70; left out \(no data\): Tester feedback/);
+});
+
+test('a part with no data is left out, never a zero (D3)', () => {
+  const s = composeScore({
+    security: sig(1, 'security', 'passed'),
+    tests: sig(2, 'tests', 'scored', 60),
+    install: sig(3, 'install', 'no_data'),
+    reliability: sig(4, 'reliability', 'pending'),
+    tester_feedback: sig(5, 'tester_feedback', 'not_scored'),
+  });
+  assert.equal(s.overall, 60, 'only Tests counts');
+  assert.deepEqual(s.signal_ids, [1, 2], 'the score names only the rows it was composed from');
+});
+
+test('Security is a gate, never averaged in (D2): a failed gate keeps its parts visible', () => {
+  const s = composeScore({ security: sig(1, 'security', 'failed'), tests: sig(2, 'tests', 'scored', 100) });
+  assert.equal(s.security_passed, false);
+  assert.equal(s.overall, 100, 'the gate does not lower the number — it keeps the version off the listing');
+  assert.match(s.formula, /Security FAILED \(not listed, whatever the score\)/);
+});
+
+test('a Security check that has not run, or could not, is NULL — not a pass', () => {
+  assert.equal(composeScore({}).security_passed, null);
+  assert.equal(composeScore({ security: sig(1, 'security', 'not_scored') }).security_passed, null);
+  assert.match(composeScore({}).formula, /Security not checked yet/);
+});
+
+test('Docs is shown with the parts and never averaged (ADR 0347 D5)', () => {
+  const s = composeScore({ tests: sig(2, 'tests', 'scored', 50), docs: sig(9, 'docs', 'scored', 100) });
+  assert.equal(s.overall, 50);
+  assert.equal(s.signal_ids.includes(9), false);
+});
+
+test('no averaged part with data → overall NULL, labelled New', () => {
+  const s = composeScore({ security: sig(1, 'security', 'passed'), tests: sig(2, 'tests', 'pending') });
+  assert.equal(s.overall, null);
+  assert.equal(s.is_new, true);
+  assert.match(s.formula, /no overall score yet: no averaged part has data; .*labelled New/);
+});
+
+test('New until Install or Reliability is scored (D5) — Tests and Tester feedback alone do not lift it', () => {
+  assert.equal(composeScore({ tests: sig(1, 'tests', 'scored', 90), tester_feedback: sig(2, 'tester_feedback', 'scored', 90) }).is_new, true);
+  assert.equal(composeScore({ reliability: sig(1, 'reliability', 'scored', 40) }).is_new, false);
+});
+
+test('price is never an input: nothing in the composer reads one (D6)', () => {
+  for (const f of ['module-assess-score.js', 'module-assess-version.js']) {
+    const src = fs.readFileSync(new URL(`../scripts/gds/${f}`, import.meta.url), 'utf8').replace(/\/\/.*$/gm, '');
+    assert.doesNotMatch(src, /price|credits|cents/i, f);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// recomposeScore / assessVersion — against an append-only fake
+// ---------------------------------------------------------------------------
+
+function fakeDb({ versions = [{ id: 7, module_key: 'weather', version: '1.0.0' }] } = {}) {
+  const signals = [];
+  const scores = [];
+  let clock = 0;
+  const db = {
+    signals, scores,
+    async query(sql, params = []) {
+      if (/^SELECT id, module_key, version FROM store_module_versions WHERE id/.test(sql)) {
+        return { rows: versions.filter((v) => String(v.id) === String(params[0])) };
+      }
+      if (/SELECT DISTINCT ON \(part\)/.test(sql)) {
+        const cur = {};
+        for (const s of signals.filter((x) => String(x.version_id) === String(params[0]))) {
+          if (!cur[s.part] || s.t > cur[s.part].t || (s.t === cur[s.part].t && s.id > cur[s.part].id)) cur[s.part] = s;
+        }
+        return { rows: Object.values(cur) };
+      }
+      if (/FROM module_assessment_scores/.test(sql) && /^SELECT/.test(sql.trim())) {
+        const mine = scores.filter((x) => String(x.version_id) === String(params[0]) && x.kind === 'computed');
+        return { rows: mine.length ? [mine[mine.length - 1]] : [] };
+      }
+      if (/INSERT INTO module_assessment_scores/.test(sql)) {
+        const row = { id: scores.length + 1, version_id: params[0], kind: 'computed', overall: params[1], security_passed: params[2], is_new: params[3], formula: params[4], signal_ids: params[5].map(String) };
+        scores.push(row); return { rows: [row] };
+      }
+      if (/INSERT INTO module_assessment_signals/.test(sql) && /'pending'/.test(sql)) {
+        if (signals.some((s) => String(s.version_id) === String(params[0]) && s.part === 'tests')) return { rows: [] };
+        signals.push({ id: signals.length + 1, version_id: params[0], part: 'tests', outcome: 'pending', score: null, reason: params[1], t: ++clock });
+        return { rows: [] };
+      }
+      throw new Error(`unexpected SQL: ${sql.slice(0, 80)}`);
+    },
+  };
+  db.add = (versionId, part, outcome, score = null) => {
+    const row = { id: signals.length + 1, version_id: versionId, part, outcome, score, t: ++clock };
+    signals.push(row); return row;
+  };
+  return db;
+}
+
+test('recompose reads the NEWEST signal per part, so a re-run moves the score', async () => {
+  const db = fakeDb();
+  db.add(7, 'security', 'passed');
+  db.add(7, 'tests', 'scored', 40);
+  const first = await recomposeScore(7, { db });
+  assert.equal(first.written, true);
+  assert.equal(first.score.overall, 40);
+  db.add(7, 'tests', 'scored', 90);
+  const second = await recomposeScore(7, { db });
+  assert.equal(second.score.overall, 90);
+  assert.equal(db.scores.length, 2, 'append-only: the history keeps the 40');
+});
+
+test('a recompose that would repeat the current score writes nothing', async () => {
+  const db = fakeDb();
+  db.add(7, 'tests', 'scored', 70);
+  await recomposeScore(7, { db });
+  const again = await recomposeScore(7, { db });
+  assert.equal(again.written, false);
+  assert.equal(db.scores.length, 1);
+});
+
+test('assessVersion on publish: Tests pending, the Security gate, then the score — and the version is New', async () => {
+  const db = fakeDb();
+  const seen = [];
+  const recordSecurity = async (id, { db: d }) => { seen.push(id); const row = d.add(id, 'security', 'passed'); return { ok: true, signal: row }; };
+  const res = await assessVersion(7, { db, recordSecurity });
+  assert.equal(res.ok, true);
+  assert.deepEqual(seen, [7]);
+  const tests = db.signals.find((s) => s.part === 'tests');
+  assert.equal(tests.outcome, 'pending', 'a published module\'s tests never run on the control plane');
+  assert.match(tests.reason, /separate test environment/);
+  assert.equal(res.score.security_passed, true);
+  assert.equal(res.score.overall, null);
+  assert.equal(res.score.is_new, true);
+});
+
+test('re-assessing never hides a real Tests score behind a newer "pending"', async () => {
+  const db = fakeDb();
+  db.add(7, 'tests', 'scored', 85);
+  const res = await assessVersion(7, { db, recordSecurity: async (id, { db: d }) => ({ ok: true, signal: d.add(id, 'security', 'passed') }) });
+  assert.equal(db.signals.filter((s) => s.part === 'tests').length, 1);
+  assert.equal(res.score.overall, 85);
+});
+
+test('assessVersion on an unknown version writes nothing', async () => {
+  const db = fakeDb({ versions: [] });
+  const res = await assessVersion(99, { db, recordSecurity: async () => { throw new Error('must not run'); } });
+  assert.equal(res.ok, false);
+  assert.equal(res.code, 'version_not_found');
+  assert.equal(db.signals.length + db.scores.length, 0);
+});
+
+// ---------------------------------------------------------------------------
+// the queue — one assessment at a time, capped
+// ---------------------------------------------------------------------------
+
+const quietLog = () => { const lines = []; return { lines, warn: (o, m) => lines.push(['warn', m]), error: (o, m) => lines.push(['error', m, o.err]) }; };
+const gate = () => { let open; const p = new Promise((r) => { open = r; }); return { p, open }; };
+
+test('the queue runs one assessment at a time, in order', async () => {
+  const log = quietLog();
+  const order = [];
+  const g = gate();
+  const run = async (id) => { order.push(`start ${id}`); if (id === 1) await g.p; order.push(`end ${id}`); };
+  queueAssessment(1, { log, run });
+  queueAssessment(2, { log, run });
+  await new Promise((r) => setImmediate(r));
+  assert.deepEqual(order, ['start 1'], 'the second waits while the first runs');
+  g.open();
+  await new Promise((r) => setTimeout(r, 10));
+  assert.deepEqual(order, ['start 1', 'end 1', 'start 2', 'end 2']);
+});
+
+test('a failed assessment is logged and never stops the next one', async () => {
+  const log = quietLog();
+  const ran = [];
+  queueAssessment(5, { log, run: async () => { throw new Error('npm unreachable'); } });
+  queueAssessment(6, { log, run: async (id) => { ran.push(id); } });
+  await new Promise((r) => setTimeout(r, 10));
+  assert.deepEqual(ran, [6]);
+  assert.deepEqual(log.lines, [['error', 'assessment after publish failed', 'npm unreachable']]);
+});
+
+test(`past ${QUEUE_MAX} waiting, a publish is logged as not assessed instead of piling up`, async () => {
+  const log = quietLog();
+  const g = gate();
+  const accepted = [];
+  for (let i = 0; i < QUEUE_MAX + 3; i += 1) accepted.push(queueAssessment(100 + i, { log, run: () => g.p }));
+  assert.equal(accepted.filter(Boolean).length, QUEUE_MAX);
+  assert.equal(log.lines.filter(([lvl]) => lvl === 'warn').length, 3);
+  assert.match(log.lines[0][1], /queue full .*module-assess-version\.js/);
+  g.open();
+  await new Promise((r) => setTimeout(r, 10));
+  assert.equal(queueAssessment(200, { log, run: async () => {} }), true, 'room again once it drains');
+});
+
+// ---------------------------------------------------------------------------
+// the publish route triggers it
+// ---------------------------------------------------------------------------
+
+test('publishing a version re-assesses that version, after the author has their answer', async () => {
+  const STORE = fs.mkdtempSync(path.join(os.tmpdir(), 'mod-assess-score-store-'));
+  process.env.MODULE_STORE_DIR = STORE;
+  const state = { modules: {}, versions: [] };
+  const client = {
+    async query(sql, params = []) {
+      if (/^SELECT module_key, author_id, status FROM store_modules/.test(sql)) { const m = state.modules[params[0]]; return { rows: m ? [m] : [] }; }
+      if (/^INSERT INTO store_modules/.test(sql)) { state.modules[params[0]] = { module_key: params[0], author_id: params[3], status: 'listed' }; return { rows: [] }; }
+      if (/^SELECT version FROM store_module_versions/.test(sql)) return { rows: [] };
+      if (/^\s*INSERT INTO store_module_versions/.test(sql)) { const row = { id: 41, module_key: params[0], version: params[1] }; state.versions.push(row); return { rows: [row] }; }
+      return { rows: [] };
+    },
+    release() {},
+  };
+  const poolPath = require.resolve('../src/bongos/pool.js');
+  require.cache[poolPath] = { id: poolPath, filename: poolPath, loaded: true, exports: { pool: { connect: async () => client, query: client.query } } };
+  const score = require('../scripts/gds/module-assess-version.js');
+  const real = score.queueAssessment;
+  const calls = [];
+  score.queueAssessment = (id) => { calls.push(id); return true; };
+  try {
+    const buildModulesRouter = require('../src/bongos/routes/modules.js');
+    const artifact = require('../scripts/gds/module-artifact.js');
+    const src = fs.mkdtempSync(path.join(os.tmpdir(), 'mod-assess-score-src-'));
+    fs.mkdirSync(path.join(src, 'weather'));
+    fs.writeFileSync(path.join(src, 'weather', 'module.json'), JSON.stringify({ key: 'weather', title: 'Weather', description: 'd', version: '1.0.0', coreVersion: '^1.0.0', contributes: {} }));
+    fs.writeFileSync(path.join(src, 'weather', 'HOWTO.md'), artifact.HOWTO_SECTIONS.map((h) => `## ${h}\nSome text.\n`).join('\n'));
+    const { tgz } = artifact.packModule('weather', { modulesDir: src, modeOf: () => '644' });
+
+    const router = buildModulesRouter();
+    const layer = router.stack.find((l) => l.route && l.route.path === '/store/modules/:key/versions' && l.route.methods.post);
+    const handle = layer.route.stack[layer.route.stack.length - 1].handle;
+    const res = { statusCode: 200, body: null, json(b) { this.body = b; return this; }, status(c) { this.statusCode = c; return this; }, fail(code, o) { this.statusCode = o.status; this.body = { error: code }; return this; } };
+    await handle({ params: { key: 'weather' }, body: tgz, builder: { id: 42 } }, res, (e) => { if (e) throw e; });
+    assert.equal(res.statusCode, 201, JSON.stringify(res.body));
+    assert.deepEqual(calls, [], 'the author is answered first — the gate can take a minute');
+    await new Promise((r) => setImmediate(r));
+    assert.deepEqual(calls, [41], 'then the new version is queued for assessment');
+  } finally {
+    score.queueAssessment = real;
+  }
+});