@bongos/core 1.24.23 → 1.24.25

package/src/bongos/routes/core-update.js

@@ -31,6 +31,7 @@ const { asyncHandler } = require('./_helpers');
 const auth = require('../auth');
 const { readCoreUpdate, readCoreUpgrades } = require('../core-update');
 const { readSoftwareUpdate } = require('../software-update');
+const { followForShape } = require('../../../scripts/bongos/update-channel.js');
 const seams = require('../../module-seams');
 const { loadIdpConfig } = require('../auth-config');
 const upgradeRequest = require('../upgrade-request');
@@ -88,6 +89,13 @@ function updateDoor({ provisioning, idp, hubUpgradeUrl }) {
   return url ? { kind: 'hub', url } : { kind: 'cli', url: null };
 }
 
+// WHICH PUBLISHED VERSIONS THIS HALL MAY BE OFFERED (task 1004593, ADR 0361 D5): the hall that
+// runs the door is the platform's own, the one project that takes every candidate; every other
+// project follows releases, as the runner and /deploy offer them. followForShape is the runner's.
+function followFor(door) {
+  return followForShape(door && door.kind === 'local' ? 'control-plane' : null);
+}
+
 function safeHubUpgradeUrl() {
   try { return require('../../instance-config').resolveEnv('HUB_UPGRADE_URL') || null; } catch { return null; }
 }
@@ -327,12 +335,12 @@ function buildCoreUpdateRouter({
     asyncHandler('GET /software-update', async (req, res) => {
       let running = null;
       try { running = require('../../module-api').CORE_VERSION; } catch { /* version unknown */ }
+      const door = updateDoor(doorInputs());
       // canUpdate does not depend on the rule, so it runs beside the rule read, not after it.
       const [update, can] = await Promise.all([
-        resolveChannel(selfChannel).then(async ({ channel, source }) => ({ ...(await softwareUpdate({ running, channel })), channel_source: source })),
+        resolveChannel(selfChannel).then(async ({ channel, source }) => ({ ...(await softwareUpdate({ running, channel, follow: followFor(door) })), channel_source: source })),
         canUpdate(req),
       ]);
-      const door = updateDoor(doorInputs());
       const ask = await readAsk({ update, door, deps: askDeps() });
       const held = await safeHold(upgradeHold, { running, offered: update && update.reading === 'ok' ? update.offered : null });
       // The history only for a viewer who holds core.pin.move (see safeMoved's gate note).
@@ -357,8 +365,8 @@ function buildCoreUpdateRouter({
         let running = null;
         try { running = require('../../module-api').CORE_VERSION; } catch { /* version unknown */ }
         const { channel } = await resolveChannel(selfChannel);
-        const update = await softwareUpdate({ running, channel });
         const door = updateDoor(doorInputs());
+        const update = await softwareUpdate({ running, channel, follow: followFor(door) });
         const deps = askDeps();
         return upgradeRequest.requestUpgrade({
           host: deps.host,

package/src/bongos/routes/module-payouts.js

@@ -0,0 +1,114 @@
+'use strict';
+
+// src/bongos/routes/module-payouts.js — a module sale's split rule, the sale, and paying
+// each share (task 1004910, goal 1000092 N6; ADR 0388). The rules live in
+// ../module-payouts.js; the database repeats the ones that matter (core_291).
+//
+// rank: every route needs `payout.approve` (read fresh per request, ADR 0016), except
+// GET /payouts/module-shares/mine, where any signed-in builder sees their own shares and
+// the weight behind each (Art. VIII). Every write is a PERSONAL act: the person's own web
+// session, never a CLI token or a machine principal (payout-approvals' personalSession).
+//
+// No processor adapter exists yet (ADR 0397), so `processor` is null: a sale cannot be
+// read and a share is recorded as owed and held. Dependencies are injectable for tests.
+
+const express = require('express');
+const auth = require('../auth');
+const { validateOrRespond, parsePagination } = require('./_helpers');
+const modulePayouts = require('../module-payouts');
+const log = require('../logger').logger.child({ src: 'module-payouts' });
+
+const PERSONAL_REFUSAL = 'Moving module money must be done by you, signed in on the website. A command-line or AI session cannot do it.';
+
+module.exports = function buildModulePayoutsRouter({
+  payouts = modulePayouts,
+  store = require('../payout-approvals'),
+  processor = null,
+  requireBuilder = auth.requireBuilder,
+  requirePermission = auth.requirePermission,
+} = {}) {
+  const router = express.Router();
+
+  function personal(req, res) {
+    const p = store.personalSession(req);
+    if (!p.ok) {
+      res.fail('personal_approval_required', { status: 403, message: PERSONAL_REFUSAL });
+      return null;
+    }
+    return p.actor;
+  }
+
+  function fail(res, err, what) {
+    if (err instanceof payouts.PayoutRefusal) return res.fail(err.code, { status: err.status, message: err.message });
+    log.error({ err: err && err.message }, `${what} failed`);
+    if (!res.headersSent) res.fail('module_payout_failed', { status: 500, message: 'internal error' });
+  }
+
+  // GET /api/bongos/payouts/module-splits/:moduleKey — the module's split rule and the
+  // contributors' weights it would use now.
+  router.get('/payouts/module-splits/:moduleKey', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    try {
+      res.json(await payouts.previewSplit(req.params.moduleKey));
+    } catch (err) { fail(res, err, 'GET /payouts/module-splits'); }
+  });
+
+  // POST /api/bongos/payouts/module-splits/:moduleKey — record the project's rule.
+  // Body: { seller_id, seller_bps, contributors_bps, credit_row_kinds? }.
+  router.post('/payouts/module-splits/:moduleKey', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, {
+      seller_id: { required: true }, seller_bps: { required: true }, contributors_bps: { required: true }, credit_row_kinds: {},
+    })) return;
+    try {
+      const rule = await payouts.setSplitRule({ moduleKey: req.params.moduleKey, body: req.body, actorId: actor.id });
+      res.status(201).json({ rule });
+    } catch (err) { fail(res, err, 'POST /payouts/module-splits'); }
+  });
+
+  // POST /api/bongos/payouts/module-sales — record ONE sale the processor reports, and
+  // write every share as owed. Body: { processor_sale_ref }. The price is read from the
+  // processor, never the body. Recording the same sale again answers with the one there.
+  router.post('/payouts/module-sales', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, { processor_sale_ref: { required: true } })) return;
+    try {
+      const out = await payouts.recordSale({ processorSaleRef: req.body.processor_sale_ref, actorId: actor.id }, { processor });
+      res.status(out.already ? 200 : 201).json(out);
+    } catch (err) { fail(res, err, 'POST /payouts/module-sales'); }
+  });
+
+  // GET /api/bongos/payouts/module-shares — every share and where it stands.
+  router.get('/payouts/module-shares', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    try {
+      const { limit, offset } = parsePagination(req, { defaultLimit: 50, maxLimit: 200 });
+      res.json({ shares: await payouts.listShares(undefined, { limit, offset }) });
+    } catch (err) { fail(res, err, 'GET /payouts/module-shares'); }
+  });
+
+  // GET /api/bongos/payouts/module-shares/mine — the signed-in builder's own shares.
+  router.get('/payouts/module-shares/mine', requireBuilder, async (req, res) => {
+    try {
+      const { limit, offset } = parsePagination(req, { defaultLimit: 50, maxLimit: 200 });
+      res.set('Cache-Control', 'no-store');
+      res.json({ shares: await payouts.listShares(undefined, { recipientId: req.builder.id, limit, offset }) });
+    } catch (err) { fail(res, err, 'GET /payouts/module-shares/mine'); }
+  });
+
+  // POST /api/bongos/payouts/module-shares/:id/pay — send ONE share under ONE approval.
+  // Body: { approval_id }. The person and the amount come from the share; the approval
+  // must name exactly them. Pressing again is safe, as for a task payout.
+  router.post('/payouts/module-shares/:id/pay', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, { approval_id: { required: true } })) return;
+    try {
+      const out = await payouts.payShare({ shareId: req.params.id, approvalId: req.body.approval_id, actorId: actor.id }, { processor });
+      res.set('Cache-Control', 'no-store');
+      res.json(out);
+    } catch (err) { fail(res, err, 'POST /payouts/module-shares/:id/pay'); }
+  });
+
+  return router;
+};

package/src/bongos/routes/my-cash-outs.js

@@ -0,0 +1,103 @@
+'use strict';
+
+// src/bongos/routes/my-cash-outs.js — a person takes their own balance out to their bank
+// (task 1004911, goal 1000092 N7; ADR 0385 D1/D8, ADR 0397 D2/D7).
+//
+//   GET  /me/cash-outs               my withdrawals, each in plain words, the minimum, my balance
+//   POST /me/cash-outs               { amount_cents, instruction_id } → ask for one withdrawal
+//   POST /me/cash-outs/:id/retry     try an unfinished one again (never pays twice)
+//   POST /me/cash-outs/:id/cancel    withdraw a request that has not been sent
+//
+// Own-scoped (tests/own_scope_guard.mjs): every route acts on req.builder.id and nothing
+// else; someone else's withdrawal answers 404. Every write needs the person's own web
+// session: pressing it IS their logged personal approval (N9), so a CLI token, an agent or a
+// machine principal can never take a person's money out. ../cash-outs.js owns the order.
+//
+// The processor adapter (ADR 0397: the only code that may name the rail) does not exist
+// yet, so every withdrawal is recorded and held `no_processor` until it lands.
+
+const express = require('express');
+const auth = require('../auth');
+const { validateOrRespond } = require('./_helpers');
+const log = require('../logger').logger.child({ src: 'my-cash-outs' });
+
+const PERSONAL_REFUSAL = 'A cash-out is made by you, signed in on the website. A command-line or AI session cannot take money out.';
+
+function buildMyCashOutsRouter({
+  cashOuts = require('../cash-outs'),
+  approvals = require('../payout-approvals'),
+  processor = null,
+  requireBuilder = auth.requireBuilder,
+} = {}) {
+  const router = express.Router();
+
+  function personal(req, res) {
+    const p = approvals.personalSession(req);
+    if (!p.ok) {
+      res.fail('personal_approval_required', { status: 403, message: PERSONAL_REFUSAL });
+      return null;
+    }
+    return p.actor;
+  }
+
+  function fault(res, err, what) {
+    if (err instanceof cashOuts.CashOutRefusal) {
+      return res.fail(err.code, { status: err.status, message: err.message, ...(err.details ? { details: err.details } : {}) });
+    }
+    // a database rule refusing (core_293's triggers): say no in words, keep its text in the log
+    if (err && (err.code === '23514' || err.code === '42501' || err.code === '23505')) {
+      log.warn({ err: err.message }, `${what} refused by the database`);
+      return res.fail('cash_out_refused', { status: 409, message: 'The cash-out rules refused this. Nothing was sent.' });
+    }
+    log.error({ err: err && err.message }, `${what} failed`);
+    if (!res.headersSent) res.fail('cash_out_failed', { status: 500, message: 'internal error' });
+    return undefined;
+  }
+
+  const answer = (res, out) => {
+    res.set('Cache-Control', 'no-store');
+    res.status(out.status === 'sent' || out.status === 'paid' || out.status === 'cancelled' ? 200 : 202).json(out);
+  };
+
+  // GET /api/bongos/me/cash-outs — my withdrawals and where each stands.
+  router.get('/me/cash-outs', requireBuilder, async (req, res) => {
+    try {
+      const out = await cashOuts.listMyCashOuts(req.builder.id, { processor, limit: req.query.limit, log });
+      res.set('Cache-Control', 'no-store');
+      res.json(out);
+    } catch (err) { fault(res, err, 'GET /me/cash-outs'); }
+  });
+
+  // POST /api/bongos/me/cash-outs — ask to take amount_cents of my balance to my bank.
+  router.post('/me/cash-outs', requireBuilder, async (req, res) => {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, { amount_cents: { required: true }, instruction_id: { required: true } })) return;
+    try {
+      const out = await cashOuts.requestCashOut({
+        builderId: String(req.builder.id), actor, amountCents: req.body.amount_cents, instructionId: req.body.instruction_id,
+      }, { processor, log });
+      answer(res, out);
+    } catch (err) { fault(res, err, 'POST /me/cash-outs'); }
+  });
+
+  // POST /api/bongos/me/cash-outs/:id/retry — try one of my unfinished withdrawals again.
+  router.post('/me/cash-outs/:id/retry', requireBuilder, async (req, res) => {
+    if (!personal(req, res)) return;
+    try {
+      answer(res, await cashOuts.retryCashOut({ builderId: String(req.builder.id), cashOutId: req.params.id }, { processor }));
+    } catch (err) { fault(res, err, 'POST /me/cash-outs/:id/retry'); }
+  });
+
+  // POST /api/bongos/me/cash-outs/:id/cancel — withdraw one of my requests that has not been sent.
+  router.post('/me/cash-outs/:id/cancel', requireBuilder, async (req, res) => {
+    if (!personal(req, res)) return;
+    try {
+      answer(res, await cashOuts.cancelCashOut({ builderId: String(req.builder.id), cashOutId: req.params.id }));
+    } catch (err) { fault(res, err, 'POST /me/cash-outs/:id/cancel'); }
+  });
+
+  return router;
+}
+
+module.exports = buildMyCashOutsRouter;

package/src/bongos/routes/payout-gates.js

@@ -6,7 +6,8 @@
 // WHY. The gates themselves run inside every money route (../payout-gates.js,
 // called from routes/payout-approvals.js and from checkRun / checkApproval). This
 // file is where their facts are recorded — an age tier, a guardian link, a
-// sanctions screening, a hand-made hold — and where an appeal is decided. The
+// sanctions screening, a hand-made hold, and the contractor papers (an NDA on
+// file, tax details collected; task 1004908) — and where an appeal is decided. The
 // person whose pay is held reads why and appeals in routes/my-payouts.js (the
 // framework, cited by Article only, forbids withholding earned pay silently).
 //
@@ -137,6 +138,46 @@ function buildPayoutGatesRouter({
     } catch (err) { fault(res, err, 'POST /payouts/screenings'); }
   });
 
+  // POST /api/bongos/payouts/ndas — record that a builder's signed NDA is on file
+  // (or withdrawn), and where the signed copy lives. Never the NDA's text.
+  // Body: { builder_id, status: on_file|withdrawn, nda_version, reference? }.
+  router.post('/payouts/ndas', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, { builder_id: { required: true }, status: { required: true }, nda_version: { required: true }, reference: {} })) return;
+    const b = req.body;
+    if (!approvals.isId(b.builder_id)) return res.fail('bad_builder_id', { status: 400, message: 'builder_id must be a number' });
+    if (String(b.builder_id) === String(actor.id)) return res.fail('own_papers', { status: 403, message: 'Someone else must record your own NDA.' });
+    if (!gates.NDA_STATUSES.includes(b.status)) return res.fail('bad_status', { status: 400, message: `status must be one of ${gates.NDA_STATUSES.join(', ')}` });
+    if (typeof b.nda_version !== 'string' || !/^[A-Za-z0-9._-]{1,40}$/.test(b.nda_version)) return res.fail('bad_nda_version', { status: 400, message: 'nda_version must be a short label (letters, digits, dot, dash, underscore), such as beta-v1.' });
+    const reference = b.reference == null ? null : statement(b.reference, 200);
+    if (reference !== null && reference.length > 200) return res.fail('bad_reference', { status: 400, message: 'reference must be up to 200 characters' });
+    try {
+      res.status(201).json({ record: await gates.recordNda({ builderId: b.builder_id, status: b.status, ndaVersion: b.nda_version, reference, recordedBy: actor.id }) });
+    } catch (err) { fault(res, err, 'POST /payouts/ndas'); }
+  });
+
+  // POST /api/bongos/payouts/tax-details — record that the processor's onboarding has
+  // (or has not) collected a builder's identity and tax details, as checked by a
+  // person. The tax id itself never comes here: a reference that looks like one is
+  // refused. Body: { builder_id, status: collected|incomplete, reference? }.
+  router.post('/payouts/tax-details', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, { builder_id: { required: true }, status: { required: true }, reference: {} })) return;
+    const b = req.body;
+    if (!approvals.isId(b.builder_id)) return res.fail('bad_builder_id', { status: 400, message: 'builder_id must be a number' });
+    if (String(b.builder_id) === String(actor.id)) return res.fail('own_papers', { status: 403, message: 'Someone else must record your own tax details.' });
+    if (!gates.TAX_STATUSES.includes(b.status)) return res.fail('bad_status', { status: 400, message: `status must be one of ${gates.TAX_STATUSES.join(', ')}` });
+    const reference = b.reference == null ? null : statement(b.reference, 200);
+    if (reference !== null && reference.length > 200) return res.fail('bad_reference', { status: 400, message: 'reference must be up to 200 characters' });
+    if (reference !== null && gates.looksLikeTaxId(reference)) return res.fail('tax_id_refused', { status: 400, message: 'That looks like a tax id. Record the processor\'s onboarding reference instead; Bongos never stores tax ids.' });
+    const login = String(req.builder.github_login || actor.id).replace(/[^A-Za-z0-9._-]/g, '').slice(0, 60) || String(actor.id);
+    try {
+      res.status(201).json({ record: await gates.recordTaxDetails({ builderId: b.builder_id, status: b.status, collectedBy: `person:${login}`, reference, recordedBy: actor.id }) });
+    } catch (err) { fault(res, err, 'POST /payouts/tax-details'); }
+  });
+
   // POST /api/bongos/payouts/freezes — a person freezes a builder's payouts by hand.
   // The notice is required: there is no silent freeze. Body: { builder_id, notice_text, owed_cents? }.
   router.post('/payouts/freezes', requireBuilder, requirePermission('payout.approve'), async (req, res) => {

package/src/bongos/routes.js

@@ -37,6 +37,10 @@ const buildPayoutApprovalsRouter = require('./routes/payout-approvals');
 // Who may be paid at all: age tier, sanctions, a hold that tells the person (task 1004914).
 const buildPayoutGatesRouter = require('./routes/payout-gates');
 const buildMyPayoutsRouter = require('./routes/my-payouts');
+// A person takes their own balance out to their bank (task 1004911, N7).
+const buildMyCashOutsRouter = require('./routes/my-cash-outs');
+// A module sale's split rule, the sale and each share's payout (task 1004910, ADR 0388).
+const buildModulePayoutsRouter = require('./routes/module-payouts');
 const buildBuildersRouter = require('./routes/builders');
 // The LIFECYCLE routes (tasks · claims · versions · done-when · goals ·
 // dependencies · analytics) carved into modules/lifecycle/
@@ -179,6 +183,8 @@ function buildGdsRouter() {
   router.use(buildPayoutApprovalsRouter());
   router.use(buildPayoutGatesRouter());
   router.use(buildMyPayoutsRouter());
+  router.use(buildMyCashOutsRouter());
+  router.use(buildModulePayoutsRouter());
   router.use(buildBuildersRouter());
   // tasks · claims · versions · done-when · goals · dependencies · analytics now
   // mount via moduleLoader.mountModuleRoutes below (lifecycle module, BV1.R86) —

package/src/bongos/software-update.js

@@ -22,6 +22,12 @@
 // /deploy, via the provisioning.selfUpdateChannel seam — task 1004535), else the runner's
 // default. The banner (core-update.js) is handed the same rule, so the two cannot disagree.
 //
+// ONLY WHAT THIS PROJECT'S FOLLOW ADMITS IS OFFERED (task 1004593, ADR 0361 D5). Merges publish
+// as candidates above the registry's `latest` label; a project that follows releases is offered
+// nothing above it, through `versionsForFollow`, the function the runner and the banner use.
+// Before this the panel offered a candidate that /deploy then said did not exist. The route
+// names the follow: candidates only on the platform's own hall.
+//
 // A READING, NEVER A GUESS. `reading` is 'ok' only when the registry answered; "up to date"
 // is `offered: null` on an ok reading and nothing else. Notes that could not be read say so,
 // and a version whose notes are missing is shown as missing rather than as empty.
@@ -30,6 +36,8 @@ const {
   CORE_PKG,
   DEFAULT_CHANNEL,
   normalizeChannel,
+  normalizeFollow,
+  versionsForFollow,
   resolveChannelTarget,
   compareSemver,
 } = require('../../scripts/bongos/update-channel.js');
@@ -62,22 +70,29 @@ function entriesFor(notes, version) {
   return out;
 }
 
+/** The published versions `follow` admits, oldest first; [] when a release follower has no label. */
+function admittedVersions(follow, registry) {
+  return versionsForFollow({ follow, available: registry.versions, released: registry.latest });
+}
+
 /**
  * The panel's whole answer, from one registry reading. PURE — no clock, no I/O.
  *
  * `registry` and `notes` are package-registry.js's `readRegistry` result. Versions in the
- * update are the published ones above `running` and at or below `offered`, newest first.
+ * update are the admitted ones above `running` and at or below `offered`, newest first, and
+ * `newest` is the newest admitted version, so a candidate is never named to a release follower.
  */
-function softwareUpdateVerdict({ running, channel, registry, notes, checkedAt }) {
+function softwareUpdateVerdict({ running, channel, follow, registry, notes, checkedAt }) {
   const ch = normalizeChannel(channel == null ? DEFAULT_CHANNEL : channel);
-  const base = { checked_at: checkedAt, running: running || null, channel: ch };
-  if (!running || !VERSION_RE.test(String(running))) {
-    return { ...base, reading: 'no_answer', error: 'this project could not name the version it runs', offered: null, newest: null, whats_new: null };
-  }
-  if (!registry || !registry.ok) {
-    return { ...base, reading: 'no_answer', error: (registry && registry.error) || 'the registry could not be read', offered: null, newest: null, whats_new: null };
-  }
-  const offered = resolveChannelTarget({ installed: running, channel: ch, available: registry.versions }) || null;
+  const fol = normalizeFollow(follow);
+  const base = { checked_at: checkedAt, running: running || null, channel: ch, follow: fol };
+  const noAnswer = (error) => ({ ...base, reading: 'no_answer', error, offered: null, newest: null, whats_new: null });
+  if (!running || !VERSION_RE.test(String(running))) return noAnswer('this project could not name the version it runs');
+  if (!registry || !registry.ok) return noAnswer((registry && registry.error) || 'the registry could not be read');
+  const admitted = admittedVersions(fol, registry);
+  // No label, no answer: the runner moves a release follower on nothing it cannot call released.
+  if (!admitted.length) return noAnswer('the registry does not say which version is released');
+  const offered = resolveChannelTarget({ installed: running, channel: ch, available: admitted }) || null;
   const published = registry.published || {};
   const answer = {
     ...base,
@@ -85,12 +100,12 @@ function softwareUpdateVerdict({ running, channel, registry, notes, checkedAt })
     error: null,
     offered,
     offered_published_at: offered ? published[offered] || null : null,
-    newest: registry.newest || null,
+    newest: admitted.reduce((a, v) => (compareSemver(v, a) > 0 ? v : a)),
     whats_new: null,
   };
   if (!offered) return answer;
 
-  const inUpdate = registry.versions
+  const inUpdate = admitted
     .filter((v) => compareSemver(v, running) > 0 && compareSemver(v, offered) <= 0)
     .sort((a, b) => compareSemver(b, a));
   const shown = inUpdate.slice(0, VERSIONS_MAX);
@@ -115,14 +130,19 @@ function softwareUpdateVerdict({ running, channel, registry, notes, checkedAt })
  * `get`/`now`/`store` pass through to the registry reader, so a test drives the real
  * packument parsing, the real tarball stream and the real cache rather than a stub.
  */
-async function readSoftwareUpdate({ running, channel, get, now = Date.now, store } = {}) {
+async function readSoftwareUpdate({ running, channel, follow, get, now = Date.now, store } = {}) {
   const t = now();
+  const fol = normalizeFollow(follow);
   const { registry, notes } = await readRegistry({
     pkg: CORE_PKG, get, now, store,
-    // Nothing to describe when nothing newer is published: skip the download.
-    haveNotesFor: (newest) => !VERSION_RE.test(String(running || '')) || compareSemver(newest, running) <= 0,
+    // Nothing to describe when nothing this project could take is newer: skip the download.
+    haveNotesFor: (_newest, facts) => {
+      if (!VERSION_RE.test(String(running || ''))) return true;
+      const admitted = admittedVersions(fol, facts);
+      return !admitted.some((v) => compareSemver(v, running) > 0);
+    },
   });
-  return softwareUpdateVerdict({ running, channel, registry, notes, checkedAt: new Date(t).toISOString() });
+  return softwareUpdateVerdict({ running, channel, follow: fol, registry, notes, checkedAt: new Date(t).toISOString() });
 }
 
 module.exports = { readSoftwareUpdate };

package/src/module-api.js

@@ -81,7 +81,7 @@ const { sleep } = require('./sleep');
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.24.23'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.24.25'; // 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/builder_payouts_db.mjs

@@ -57,6 +57,7 @@ try {
   await client.query(`INSERT INTO payout_approvals (kind, recipient_id, amount_cents, currency)
                       VALUES ('payout_approved', 1, 12500, 'USD'), ('payout_approved', 1, 300, 'USD'), ('payout_approved', 1, 400, 'USD')`);
   await client.query(mig('modules', 'economy', 'migrations', 'economy_002_project_account.sql'));
+  await client.query(mig('modules', 'economy', 'migrations', 'economy_004_module_share_payouts.sql'));
   await client.query(mig('migrations', 'core_290_builder_payouts.sql'));
   await client.query('BEGIN');
 

package/tests/cash_outs.mjs

@@ -0,0 +1,96 @@
+// tests/cash_outs.mjs — task 1004911 (goal 1000092 N7). DB-free.
+//
+// The pure half of cash-outs: how a withdrawal's attempts fold into where it stands (and
+// which try, so which idempotency key, comes next), the refusals made before anything is
+// recorded, and the routes' own gate: only the person, signed in on the web, can take their
+// money out. The real tables and the real flow are tests/cash_outs_db.mjs.
+//
+// Run: node tests/cash_outs.mjs
+import { createRequire } from 'node:module';
+import { strict as assert } from 'node:assert';
+import http from 'node:http';
+const require = createRequire(import.meta.url);
+const express = require('express');
+const C = require('../src/bongos/cash-outs.js');
+const buildMyCashOuts = require('../src/bongos/routes/my-cash-outs.js');
+
+let pass = 0;
+const ok = (c, m) => { assert.ok(c, m); pass++; console.log(`  ok - ${m}`); };
+const refusal = async (fn) => { try { await fn(); } catch (e) { return e; } return null; };
+const at = (outcome, tryNo, ref = null) => ({ outcome, try_no: tryNo, processor_ref: ref, reason: ref ? null : 'x' });
+
+// ── standing ─────────────────────────────────────────────────────────────
+ok(C.standing([]).status === 'held' && C.standing([]).try_no === 1, 'nothing tried yet: waiting, try 1');
+ok(C.standing([at('failed', 1)]).try_no === 1, 'a failure we cannot trust keeps try 1 (the same key)');
+ok(C.standing([at('refused', 1)]).try_no === 2, 'a processor refusal moves on to try 2');
+ok(C.standing([at('sent', 1, 'po_1')]).status === 'sent', 'sent and not yet arrived');
+ok(C.standing([at('sent', 1, 'po_1'), at('paid', 1, 'po_1')]).status === 'paid', 'arrived');
+const back = C.standing([at('sent', 1, 'po_1'), at('paid', 1, 'po_1'), { outcome: 'returned', try_no: 1, processor_ref: 'po_1', reason: 'closed' }]);
+ok(back.status === 'returned' && back.try_no === 2, 'a bank return after arrival reopens it on try 2');
+ok(C.standing([at('held', 1), at('cancelled', 1)]).status === 'cancelled', 'cancelled');
+ok(C.idempotencyKey('7', 2) === 'bongos-cashout-7-2', 'the key names the withdrawal and the try');
+
+// ── refusals before anything is recorded ─────────────────────────────────
+const noDb = { query: async () => { throw new Error('the database must not be reached'); } };
+const me = { id: '5', session_id: '1', session_source: 'web' };
+let e = await refusal(() => C.requestCashOut({ builderId: '5', actor: me, amountCents: 999, instructionId: 'press-000001' }, { pool: noDb, account: { memberAccount: async () => 'acct_test' } }));
+ok(e && e.code === 'below_minimum', 'below the minimum is refused without touching the database');
+e = await refusal(() => C.requestCashOut({ builderId: '5', actor: me, amountCents: 1.5, instructionId: 'press-000001' }, { pool: noDb }));
+ok(e && e.code === 'bad_amount', 'a fractional amount is refused');
+e = await refusal(() => C.requestCashOut({ builderId: '5', actor: me, amountCents: 2000, instructionId: 'x' }, { pool: noDb }));
+ok(e && e.code === 'bad_instruction_id', 'a malformed instruction id is refused');
+e = await refusal(() => C.requestCashOut({ builderId: '5', actor: { ...me, id: '6' }, amountCents: 2000, instructionId: 'press-000001' }, { pool: noDb }));
+ok(e && e.code === 'personal_session_required', "nobody cashes out someone else's money");
+e = await refusal(() => C.requestCashOut({ builderId: '5', actor: me, amountCents: 2000, instructionId: 'press-000001' }, { pool: noDb, account: null }));
+ok(e && e.code === 'no_account_record', 'with balances switched off there is nothing to cash out');
+e = await refusal(() => C.requestCashOut({ builderId: '5', actor: me, amountCents: 2000, instructionId: 'press-000001' }, { pool: noDb, account: { memberAccount: async () => null } }));
+ok(e && e.code === 'no_account', 'no processor account here: nothing to cash out');
+e = await refusal(() => C.recordProcessorOutcome({ processorRef: 'po_1', outcome: 'returned' }, { pool: noDb }));
+ok(e && e.code === 'no_reason', 'a returned payout must say why');
+
+// ── the routes' gate ─────────────────────────────────────────────────────
+const seen = [];
+const stub = {
+  CashOutRefusal: C.CashOutRefusal,
+  listMyCashOuts: async (id) => { seen.push(['list', id]); return { cash_outs: [] }; },
+  requestCashOut: async (i) => { seen.push(['request', i.builderId, i.actor.id]); return { status: 'held' }; },
+  retryCashOut: async (i) => { seen.push(['retry', i.builderId, i.cashOutId]); throw new C.CashOutRefusal('no_such_cash_out', 'none', 404); },
+  cancelCashOut: async (i) => { seen.push(['cancel', i.builderId]); return { status: 'cancelled' }; },
+};
+function serve(as) {
+  const a = express();
+  a.use(express.json());
+  a.use((req, res, next) => { res.fail = (code, o = {}) => res.status(o.status || 400).json({ error: code, message: o.message }); req.builder = as.builder; req.gdsSession = as.gdsSession; next(); });
+  a.use('/', buildMyCashOuts({ cashOuts: stub, requireBuilder: (q, r, nx) => nx() }));
+  return http.createServer(a).listen(0);
+}
+async function call(srv, method, path, body) {
+  const r = await fetch(`http://127.0.0.1:${srv.address().port}${path}`, { method, headers: { 'content-type': 'application/json' }, body: body ? JSON.stringify(body) : undefined });
+  return { status: r.status, body: await r.json() };
+}
+const web = serve({ builder: { id: '5' }, gdsSession: { source: 'web', session_id: '3' } });
+const cli = serve({ builder: { id: '5' }, gdsSession: { source: 'cli', session_id: '4' } });
+const bot = serve({ builder: { id: '9', system_role: 'agent' }, gdsSession: { source: 'web', session_id: '5' } });
+try {
+  for (const [srv, who] of [[cli, 'a CLI session'], [bot, 'a machine principal']]) {
+    for (const [act, p] of [['request', '/me/cash-outs'], ['retry', '/me/cash-outs/1/retry'], ['cancel', '/me/cash-outs/1/cancel']]) {
+      const r = await call(srv, 'POST', p, { amount_cents: 2000, instruction_id: 'press-000001' });
+      ok(r.status === 403 && r.body.error === 'personal_approval_required', `${who} cannot ${act} a cash-out`);
+    }
+  }
+  ok(!seen.some(([k]) => k !== 'list'), 'nothing reached the cash-out code from a refused session');
+  let r = await call(cli, 'GET', '/me/cash-outs');
+  ok(r.status === 200 && seen.at(-1)[1] === '5', 'reading my own list works from any session, keyed on me');
+  r = await call(web, 'POST', '/me/cash-outs', { amount_cents: 2000, instruction_id: 'press-000001', builder_id: '6' });
+  ok(r.status === 400 && seen.at(-1)[0] === 'list', 'a body naming someone else is refused outright');
+  r = await call(web, 'POST', '/me/cash-outs', { amount_cents: 2000, instruction_id: 'press-000001' });
+  ok(r.status === 202 && seen.at(-1)[1] === '5' && seen.at(-1)[2] === '5', 'a request is mine: the signed-in person, never the body');
+  r = await call(web, 'POST', '/me/cash-outs/77/retry');
+  ok(r.status === 404 && r.body.error === 'no_such_cash_out', 'a refusal is passed on with its status');
+  r = await call(web, 'POST', '/me/cash-outs', {});
+  ok(r.status === 400, 'a request with no amount is refused');
+} finally {
+  for (const s of [web, cli, bot]) s.close();
+}
+
+console.log(`\ncash_outs.mjs: ${pass} passed`);