@bongos/core 1.20.36 → 1.20.38

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

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+// scripts/gds/module-assess-tests.js — the Tests part of a module's assessment:
+// run a published module version's OWN test suite and record the pass rate as a
+// module_assessment_signals row (task 1003791, ADR 0343; table from core_265).
+//
+// Why this cannot reuse the unit gate. run-unit-tests.js discovers
+// modules/<key>/tests/*.mjs but runs them only when isModuleEnabled(key) — and a
+// catalog module ships default:false (ADR 0107 §6), so every store module's tests
+// are skipped there by construction (the trap task 1003630 documented). This runs
+// the tests straight from the published TARBALL, with no enabled/disabled check at
+// all, so what is measured is exactly the build a buyer would install.
+//
+// Outcomes (core_265's vocabulary — a missing part is never a zero):
+//   scored      the module has tests and they ran: score = round(100 × files that
+//               passed / files run), sample_size = files run. The unit is a test
+//               FILE (one process, its exit code), the same unit the core gate uses.
+//   no_data     the module declares no tests — NOT a fail (the task says the two
+//               must not score the same).
+//   not_scored  the tarball could not be read or verified, so nothing could run.
+//
+// Where the tests run. A module's tests reach into the core by relative path
+// (`../../../docs/…`) and resolve packages from the core's node_modules, so the
+// module is unpacked at the same depth modules/<key>/ sits at:
+// <core root>/.module-assess-<run>/<key>/ — node's walk-up resolution then finds
+// the core with no junctions to create (and so none a cleanup could follow; see
+// worktree.js). Each file runs in its own node process, serially, with a timeout
+// and a stripped environment: no DATABASE_URL, tokens or keys are handed to
+// third-party code. That is a floor, not a sandbox: a test process can still read
+// any file the OS user can (the core's own .env sits two directories up) and reach
+// the network.
+//
+// SO A PUBLISHED MODULE'S TESTS RUN ONLY IN A SEPARATE TESTING ENVIRONMENT
+// (owner, 2026-09-30): never on the control plane, where the secrets live. The
+// store path (recordTestsSignal) refuses unless the process declares it is that
+// environment with MODULE_TEST_SANDBOX=1 — set only on the isolated test box, no
+// secrets on disk, which is its own task. `--dir` stays open: it runs a module
+// from your own checkout, i.e. code you already chose to run.
+//
+//   node scripts/gds/module-assess-tests.js <store_module_versions.id>   run + record
+//   node scripts/gds/module-assess-tests.js --dir modules/<key>          dry run on a
+//                                                                        local module
+//                                                                        (prints; no DB)
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execFile } = require('node:child_process');
+const { isCleanTeardownAbort } = require('./run-unit-tests');
+
+const CORE_ROOT = path.resolve(__dirname, '..', '..');
+const PER_FILE_TIMEOUT_MS = 90_000; // the unit gate's own per-file cap
+const SANDBOX_PREFIX = '.module-assess-';
+// The only variables a module's test process inherits. PATH to find tools; the
+// Windows ones node needs to start at all; nothing that names a credential.
+const ENV_KEEP = ['PATH', 'Path', 'SystemRoot', 'SYSTEMROOT', 'windir', 'TEMP', 'TMP', 'TMPDIR', 'COMSPEC', 'PATHEXT'];
+
+// The module's test files: tests/*.mjs at the top of tests/, exactly what
+// run-unit-tests.js discovers for a module on disk. `files` is module-relative paths.
+function discoverTestFiles(paths) {
+  return paths.filter((p) => /^tests\/[^/]+\.mjs$/.test(p)).sort();
+}
+
+function testEnv(sandbox) {
+  const env = {};
+  for (const k of ENV_KEEP) if (process.env[k] !== undefined) env[k] = process.env[k];
+  env.NODE_ENV = 'test';
+  env.HOME = sandbox;
+  env.USERPROFILE = sandbox;
+  return env;
+}
+
+// Run one file; resolve { file, passed, timedOut, code, tail }. Never rejects.
+function runFile(file, { cwd, env, timeoutMs, exec = execFile }) {
+  return new Promise((resolve) => {
+    exec(process.execPath, [file], { cwd, env, timeout: timeoutMs, maxBuffer: 8 * 1024 * 1024, windowsHide: true },
+      (err, stdout, stderr) => {
+        const out = String(stdout || '');
+        const errText = String(stderr || '');
+        // A suite that passed but aborted in libuv teardown on Windows passed (task 1003845).
+        const passed = !err || isCleanTeardownAbort(out, errText);
+        const timedOut = !!(err && err.killed);
+        // Why it failed: the suite's last stdout lines (its verdict) and the HEAD of
+        // stderr, where node puts the thrown error — its tail is only the stack and version.
+        const lines = (t, n, fromEnd) => { const ls = t.split(/\r?\n/).filter((l) => l.trim()); return (fromEnd ? ls.slice(-n) : ls.slice(0, n)).join('\n'); };
+        const tail = passed ? '' : [lines(out, 3, true), lines(errText, 4, false)].filter(Boolean).join('\n').slice(0, 600);
+        resolve({ passed, timedOut, code: err ? (err.code ?? null) : 0, tail });
+      });
+  });
+}
+
+// Remove a sandbox this file made. It holds only real files written by placeFiles
+// (never a link), and the name check means a bad argument cannot aim this anywhere else.
+function removeSandbox(dir, root) {
+  if (!path.basename(dir).startsWith(SANDBOX_PREFIX) || path.dirname(dir) !== root) {
+    throw new Error(`refusing to remove ${dir}: not a module-assess sandbox`);
+  }
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+function placeFiles(files, target) {
+  for (const f of files) {
+    const dest = path.join(target, ...f.path.split('/'));
+    if (!dest.startsWith(target + path.sep)) throw new Error(`"${f.path}" would land outside the module`);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, f.buf);
+  }
+}
+
+// The gate in front of running module code. `trusted` is only for code you
+// already chose to run (a module in your own checkout, `--dir`). Anything else — a
+// published, third-party module — runs only where the process declares itself the
+// separate testing environment (MODULE_TEST_SANDBOX=1) AND nothing secret is
+// visible: no credential-looking variable in the environment, no .env at the core
+// root. The second half is what stops a mis-set flag on a real server from
+// quietly reopening the hole. Returns null (go) or { code, message }.
+const SECRET_ENV_RE = /(^DATABASE_URL$|^PG(PASSWORD|PASSFILE)$|TOKEN|SECRET|PASSWORD|API_KEY|PRIVATE_KEY|_KEY$)/i;
+function inTestSandbox(env = process.env) {
+  return env.MODULE_TEST_SANDBOX === '1';
+}
+function runRefusal({ trusted = false, env = process.env, root = CORE_ROOT } = {}) {
+  if (trusted) return null;
+  if (!inTestSandbox(env)) {
+    return { code: 'not_in_test_sandbox', message: "refusing to run a published module's tests here: they run only in the separate testing environment (MODULE_TEST_SANDBOX=1), never on a server holding secrets" };
+  }
+  const leaked = Object.keys(env).filter((k) => SECRET_ENV_RE.test(k) && env[k]);
+  if (leaked.length || fs.existsSync(path.join(root, '.env'))) {
+    return { code: 'secrets_present', message: `refusing: MODULE_TEST_SANDBOX=1 is set but secrets are visible here (${leaked.length ? leaked.sort().join(', ') : '.env at the core root'}) — the testing environment must hold none` };
+  }
+  return null;
+}
+
+// Run a module's own tests from its files ([{ path, buf }], module-relative) and
+// return the signal fields: { outcome, score, sample_size, reason, detail }.
+// Pure apart from the sandbox it writes and removes; `exec` is injectable for tests.
+async function assessTests(key, files, { root = CORE_ROOT, timeoutMs = PER_FILE_TIMEOUT_MS, exec, trusted = false, env = process.env } = {}) {
+  // Checked here too, not only in recordTestsSignal, so no caller can reach the
+  // code that runs a module without passing the gate.
+  const refused = runRefusal({ trusted, env, root });
+  if (refused) throw Object.assign(new Error(refused.message), { code: refused.code });
+  const tests = discoverTestFiles(files.map((f) => f.path));
+  if (tests.length === 0) {
+    return { outcome: 'no_data', score: null, sample_size: 0, reason: 'the module declares no tests (no tests/*.mjs)', detail: { files: [] } };
+  }
+  const sandbox = path.join(root, `${SANDBOX_PREFIX}${process.pid}-${crypto.randomBytes(4).toString('hex')}`);
+  const moduleDir = path.join(sandbox, key);
+  try {
+    placeFiles(files, moduleDir);
+    const env = testEnv(sandbox);
+    const results = [];
+    for (const t of tests) {
+      // Serial on purpose, like the unit gate: tests share the core tree around them.
+      const r = await runFile(path.join(moduleDir, ...t.split('/')), { cwd: moduleDir, env, timeoutMs, exec });
+      results.push({ file: t, ...r });
+    }
+    const passed = results.filter((r) => r.passed).length;
+    const failed = results.filter((r) => !r.passed);
+    return {
+      outcome: 'scored',
+      score: Math.round((100 * passed) / results.length),
+      sample_size: results.length,
+      reason: failed.length ? `${failed.length} of ${results.length} test file(s) failed` : `all ${results.length} test file(s) passed`,
+      detail: { files: results.map(({ file, passed: ok, timedOut, tail }) => ({ file, passed: ok, ...(timedOut ? { timed_out: true } : {}), ...(tail ? { tail } : {}) })) },
+    };
+  } finally {
+    removeSandbox(sandbox, root);
+  }
+}
+
+// Append one Tests signal row for a store version. Never UPDATEs (core_265 is
+// append-only: the current result is the newest row per (version, part)).
+async function insertSignal(versionId, s, { db }) {
+  const { rows: [row] } = await db.query(
+    `INSERT INTO module_assessment_signals (version_id, part, outcome, score, sample_size, reason, detail)
+     VALUES ($1, 'tests', $2, $3, $4, $5, $6)
+     RETURNING id, version_id, part, outcome, score, sample_size, reason, measured_at`,
+    [versionId, s.outcome, s.score, s.sample_size, s.reason, JSON.stringify(s.detail || {})]);
+  return row;
+}
+
+// Read, verify and test one published version, then record the result. A tarball
+// that is missing or fails verification is recorded as not_scored — the part could
+// not be measured, which is not the same as the module failing its tests.
+async function recordTestsSignal(versionId, { db, storeDir, root, timeoutMs, exec, env = process.env } = {}) {
+  const refused = runRefusal({ env, root });
+  if (refused) return { ok: false, ...refused };
+  const pool = db || require('../../src/bongos/pool').pool;
+  const { versionArtifactFile } = require('../../src/bongos/module-store');
+  const { verifyModuleArtifact } = require('./module-artifact');
+  const { rows: [ver] } = await pool.query(
+    'SELECT id, module_key, version, artifact_path FROM store_module_versions WHERE id = $1', [versionId]);
+  if (!ver) return { ok: false, code: 'version_not_found', message: `no store_module_versions row ${versionId}` };
+
+  let signal;
+  try {
+    const file = versionArtifactFile(ver, storeDir ? { dir: storeDir } : {});
+    const tgz = await fs.promises.readFile(file);
+    const v = await verifyModuleArtifact(tgz, { key: ver.module_key, includeFiles: true });
+    signal = v.ok
+      ? await assessTests(ver.module_key, v.files, { root, timeoutMs, exec, env })
+      : { outcome: 'not_scored', score: null, sample_size: null, reason: `the tarball failed verification (${v.code}): ${v.message}`, detail: {} };
+  } catch (e) {
+    signal = { outcome: 'not_scored', score: null, sample_size: null, reason: `the tests could not run (${e.code || 'error'})`, detail: {} };
+  }
+  const row = await insertSignal(ver.id, signal, { db: pool });
+  return { ok: true, version: ver, signal: row };
+}
+
+// Local dry run: read modules/<key>/ from disk and print what the signal would be.
+function readModuleDir(dir) {
+  const out = [];
+  const walk = (rel) => {
+    for (const e of fs.readdirSync(path.join(dir, rel), { withFileTypes: true })) {
+      if (e.name === 'node_modules' || e.name === '.git') continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(r);
+      else if (e.isFile()) out.push({ path: r, buf: fs.readFileSync(path.join(dir, r)) });
+    }
+  };
+  walk('');
+  return out;
+}
+
+async function main(argv) {
+  const i = argv.indexOf('--dir');
+  if (i !== -1) {
+    const dir = path.resolve(argv[i + 1] || '');
+    const key = JSON.parse(fs.readFileSync(path.join(dir, 'module.json'), 'utf8')).key;
+    const s = await assessTests(key, readModuleDir(dir), { trusted: true });
+    console.log(JSON.stringify(s, null, 2));
+    return 0;
+  }
+  const id = argv[0];
+  if (!/^\d+$/.test(String(id || ''))) {
+    console.error('usage: node scripts/gds/module-assess-tests.js <store_module_versions.id> | --dir modules/<key>');
+    return 2;
+  }
+  const res = await recordTestsSignal(id);
+  if (!res.ok) { console.error(res.message); return 1; }
+  const s = res.signal;
+  console.log(`${res.version.module_key} ${res.version.version}: tests ${s.outcome}${s.score !== null ? ` ${s.score}/100` : ''} — ${s.reason} (signal ${s.id})`);
+  return 0;
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2)).then((code) => process.exit(code), (e) => { console.error(e.stack || e.message); process.exit(1); });
+}
+
+module.exports = { discoverTestFiles, assessTests, recordTestsSignal, insertSignal, runRefusal, testEnv, SANDBOX_PREFIX };

package/scripts/gds/update-channel.js

@@ -228,6 +228,82 @@ function loadSubscriptions({ instanceDir = process.cwd(), fsImpl = fs, file = SU
   };
 }
 
+// ---- the per-project rule set on /deploy (task 1004468, ADR 0357) -----------
+// The owner sets each project's update rule on /deploy, which writes
+// provisioning_instances.update_channel (migration provisioning_029, task 1004445). That column
+// is the rule; the roster's `channel` is only the fallback for an entry no project row matches,
+// or for a sweep that cannot reach the database. Before this, the button followed the column and
+// the sweep followed the roster, so a project set to `minor` on /deploy was still swept as `patch`.
+//
+// Matched by slug — the one stable key the table has (it records no directory). Read over psql,
+// which is how upgrade.js recordLedger reaches a PGDATABASE (a bare name over the unix socket +
+// peer auth, the self-host shape). recordLedger uses the pg driver for DATABASE_URL; this passes
+// the URL to `psql -d` instead, because the sweep is synchronous and pg is not. With no psql the
+// sweep falls back to the roster and says so.
+//
+// A failure's reason is a fixed class, never psql's own text: stderr can name a DB user or host,
+// and the reason is printed into the sweep's log.
+const CHANNEL_SOURCE_DEPLOY = 'deploy';
+const CHANNEL_SOURCE_ROSTER = 'roster';
+const DB_CHANNELS_SQL = 'SELECT slug, update_channel FROM provisioning_instances';
+const DB_CHANNELS_TIMEOUT_MS = 15000;
+
+// PURE. psql's stderr reduced to a class that is safe to log.
+function psqlFailureClass(stderr) {
+  const s = String(stderr || '');
+  if (/relation .*provisioning_instances.* does not exist/i.test(s)) return 'no provisioning_instances table (provisioning module off?)';
+  if (/column .*update_channel.* does not exist/i.test(s)) return 'no update_channel column (migration provisioning_029 not applied)';
+  if (/authentication failed|role .* does not exist|permission denied/i.test(s)) return 'the sweep\'s database login was refused';
+  if (/could not connect|connection refused|no such file or directory|could not translate host/i.test(s)) return 'database unreachable';
+  if (/database .* does not exist/i.test(s)) return 'the named database does not exist';
+  return 'query failed';
+}
+
+// The line a sweep prints for one entry's channel. PURE.
+function channelLine(inst) {
+  return `  • ${inst.slug}: channel ${inst.channel}, ${inst.channelNote}`;
+}
+
+// Read every project's update rule. Never throws: { ok:true, channels: Map<slug, channel> }, or
+// { ok:false, reason } when there is no database to ask, psql is missing, or the table is absent
+// (an instance with the provisioning module off). The caller falls back to the roster and says why.
+function readDbChannels({ env = process.env, run = spawnSync } = {}) {
+  const target = env.DATABASE_URL || env.PGDATABASE;
+  if (!target) return { ok: false, reason: 'no DATABASE_URL or PGDATABASE set for the sweep' };
+  const r = run('psql', ['-d', target, '-At', '-F', '\t', '-v', 'ON_ERROR_STOP=1', '--no-psqlrc', '-c', DB_CHANNELS_SQL],
+    { encoding: 'utf8', timeout: DB_CHANNELS_TIMEOUT_MS });
+  if (!r || r.error) {
+    const code = r && r.error && r.error.code;
+    return { ok: false, reason: code === 'ENOENT' ? 'psql not found' : code === 'ETIMEDOUT' ? 'psql timed out' : 'psql could not be started' };
+  }
+  if (r.status !== 0) return { ok: false, reason: `psql exit ${r.status}: ${psqlFailureClass(r.stderr)}` };
+  const channels = new Map();
+  for (const line of String(r.stdout || '').split('\n')) {
+    const [slug, ch] = line.split('\t');
+    if (slug && ch) channels.set(slug.trim(), ch.trim());
+  }
+  return { ok: true, channels };
+}
+
+// PURE. Give each roster entry the channel it is actually under, and say where it came from:
+// `channelSource` is 'deploy' (the project row) or 'roster', `channelNote` the one-line reason a
+// sweep log prints. The roster's own value is kept as `rosterChannel`, so a disagreement stays
+// visible in the log instead of silently vanishing.
+function applyDbChannels(instances, db) {
+  return instances.map((inst) => {
+    if (db && db.ok && db.channels.has(inst.slug)) {
+      const ch = normalizeChannel(db.channels.get(inst.slug));
+      const differs = ch !== inst.channel;
+      return {
+        ...inst, channel: ch, channelSource: CHANNEL_SOURCE_DEPLOY, rosterChannel: inst.channel,
+        channelNote: `set on /deploy${differs ? ` (roster says ${inst.channel}, ignored)` : ''}`,
+      };
+    }
+    const why = db && db.ok ? 'no project row for this slug' : (db && db.reason) || 'database not read';
+    return { ...inst, channelSource: CHANNEL_SOURCE_ROSTER, rosterChannel: inst.channel, channelNote: `from the roster — ${why}` };
+  });
+}
+
 // ---- reporting: make "nothing happened" audible -----------------------------
 
 // Turn a loadSubscriptions() result into the line a routine prints EVERY run, plus a level a caller
@@ -322,6 +398,12 @@ module.exports = {
   listAvailableVersions,
   parseNpmViewVersions,
   loadSubscriptions,
+  readDbChannels,
+  applyDbChannels,
+  channelLine,
+  psqlFailureClass,
+  CHANNEL_SOURCE_DEPLOY,
+  CHANNEL_SOURCE_ROSTER,
   ROSTER_OK,
   ROSTER_ABSENT,
   ROSTER_MALFORMED,

package/src/bongos/routes/feedback.js

@@ -0,0 +1,110 @@
+'use strict';
+
+// src/bongos/routes/feedback.js — POST /api/bongos/feedback (task 1004462).
+//
+// `bongos feedback "…"` lands here, on the builder's OWN project, with the session
+// they already hold. This route stamps who sent it and which core this project
+// runs, then relays it to the hub's POST /sso/feedback over the hub-federation
+// client credential (ADR 0141) — the channel the activity rollup already uses. So
+// a builder never signs in to cloudbongos.com to report something about Bongos.
+//
+// Only the text the builder typed and version stamps travel. No code, transcript,
+// task or file content from this project is attached.
+//
+// In the CORE, not a module, for the reason core-update.js gives: the hub link is
+// kernel (src/bongos/auth-config.js), and every hosted project must have this door
+// whatever modules it runs. A project with no hub link (self-hosted, or the hub
+// itself) answers 409 not_hub_connected — told, not silently dropped.
+
+const express = require('express');
+const { asyncHandler, validateOrRespond } = require('./_helpers');
+const auth = require('../auth');
+const { loadIdpConfig } = require('../auth-config');
+const { userAgent } = require('../../branding');
+
+const MESSAGE_MAX = 4000;
+const HUB_TIMEOUT_MS = 15000;
+
+function safeIdpConfig() {
+  try { return loadIdpConfig(); } catch { return null; }
+}
+
+function runningCore() {
+  try { return require('../../module-api').CORE_VERSION || null; } catch { return null; }
+}
+
+// Hub refusals the builder can act on are passed through by code; anything else
+// is one generic failure, so the hub's internals never leak through this door.
+const PASS_THROUGH = new Set(['membership_required', 'rate_limited', 'feedback_unavailable', 'validation_failed']);
+
+async function relayToHub({ idp, builder, message, kind, context, fetchImpl = fetch }) {
+  const res = await fetchImpl(`${idp.origin.replace(/\/+$/, '')}/api/bongos/sso/feedback`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'User-Agent': userAgent() },
+    body: JSON.stringify({
+      client_id: idp.clientId,
+      client_secret: idp.clientSecret,
+      github_id: builder.github_id,
+      message,
+      kind,
+      context,
+    }),
+    signal: AbortSignal.timeout(HUB_TIMEOUT_MS),
+  });
+  let body = null;
+  try { body = await res.json(); } catch { /* non-JSON answer */ }
+  return { status: res.status, body };
+}
+
+function buildFeedbackRouter({ idpConfig = safeIdpConfig, fetchImpl = fetch } = {}) {
+  const router = express.Router();
+
+  // rank: any signed-in builder — reporting a problem with Bongos grants nothing
+  // here, and the hub files every report at 'backlog' behind a Metic+ nod.
+  router.post(
+    '/feedback',
+    auth.requireBuilder,
+    asyncHandler('POST /feedback', async (req, res) => {
+      if (validateOrRespond(req, res, {
+        message: { required: true, type: 'string', maxLength: MESSAGE_MAX },
+        kind: { type: 'string', enum: ['bug', 'idea'] },
+        context: {},
+      })) return;
+      const b = req.body || {};
+      const message = b.message.trim();
+      if (!message) return res.fail('message_required', 400);
+      const kind = b.kind || 'bug';
+
+      const idp = idpConfig();
+      if (!idp) return res.fail('not_hub_connected', 409);
+
+      const ctx = b.context && typeof b.context === 'object' ? b.context : {};
+      const context = {
+        core_version: runningCore(),
+        cli_version: typeof ctx.cli_version === 'string' ? ctx.cli_version.slice(0, 40) : null,
+        os: typeof ctx.os === 'string' ? ctx.os.slice(0, 40) : null,
+      };
+
+      let hub;
+      try {
+        hub = await relayToHub({ idp, builder: req.builder, message, kind, context, fetchImpl });
+      } catch {
+        return res.fail('hub_unreachable', 502);
+      }
+      if (hub.status === 201 && hub.body && hub.body.ok) {
+        const { ok: _ok, ...landing } = hub.body;
+        return res.status(201).json({ ok: true, hub_origin: idp.origin, ...landing });
+      }
+      const err = hub.body && hub.body.error && typeof hub.body.error === 'object' ? hub.body.error : null;
+      if (err && PASS_THROUGH.has(err.code)) {
+        const retry = err.details && err.details.retry_after_seconds;
+        return res.fail(err.code, hub.status, retry ? { retry_after_seconds: retry } : undefined);
+      }
+      return res.fail('hub_refused', 502, { hub_status: hub.status });
+    }, { errorCode: 'feedback_failed', message: false }),
+  );
+
+  return router;
+}
+
+module.exports = buildFeedbackRouter;

package/src/bongos/routes.js

@@ -20,6 +20,7 @@ const express = require('express');
 const buildHealthzRouter = require('./routes/healthz');
 const buildInstanceRouter = require('./routes/instance');
 const buildCoreUpdateRouter = require('./routes/core-update');
+const buildFeedbackRouter = require('./routes/feedback');
 const buildAuthRouter = require('./routes/auth');
 const buildGithubRouter = require('./routes/github');
 const buildMeRouter = require('./routes/me');
@@ -144,6 +145,7 @@ function buildGdsRouter() {
   router.use(buildHealthzRouter());
   router.use(buildInstanceRouter());
   router.use(buildCoreUpdateRouter());
+  router.use(buildFeedbackRouter());
   router.use(buildAuthRouter());
   router.use(buildGithubRouter());
   router.use(buildMeRouter());

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

@@ -260,3 +260,65 @@ test('no request means every allowlisted goal', () => {
   assert.deepEqual(allowedGoals(f, []).goals, [1, 2]);
   assert.deepEqual(allowedGoals(f).goals, [1, 2]);
 });
+
+// ── the priority goal (task 1004453) ────────────────────────────────────────────
+//
+// Owner ruling: whoever starts the runner names the goal it works FIRST, as well as
+// the set it may touch. The priority ORDERS the allowlist; it must never widen it.
+
+test('the priority goal is read off the fence and moved to the front', () => {
+  const f = open({ goals: [{ goal_id: 1 }, { goal_id: 2 }, { goal_id: 3 }], priority_goal_id: 3 });
+  assert.equal(normaliseFence(f).priorityGoal, 3);
+  const d = decideRun({ fence: f, ...GRADER_OK });
+  assert.equal(d.go, true);
+  assert.deepEqual(d.goals, [3, 1, 2], 'the runner walks goals in this order, so the priority goes first');
+  assert.equal(d.priorityGoal, 3);
+});
+
+test('a priority that is not on the allowlist is ignored, never added', () => {
+  // The database refuses this with a foreign key; the pure half refuses it again,
+  // because a priority that could add a goal would be a second, unguarded allowlist.
+  const f = open({ goals: [{ goal_id: 1 }, { goal_id: 2 }], priority_goal_id: 99 });
+  assert.equal(normaliseFence(f).priorityGoal, null);
+  const d = decideRun({ fence: f, ...GRADER_OK });
+  assert.deepEqual(d.goals, [1, 2]);
+  assert.equal(d.priorityGoal, null);
+});
+
+test('a malformed or missing priority reads as "no priority", not as a refusal', () => {
+  for (const p of [undefined, null, '', 0, -4, 'abc', 1.5, {}]) {
+    const d = decideRun({ fence: open({ goals: [{ goal_id: 1 }, { goal_id: 2 }], priority_goal_id: p }), ...GRADER_OK });
+    assert.equal(d.go, true, `priority ${JSON.stringify(p)} must not stop the run`);
+    assert.deepEqual(d.goals, [1, 2], `priority ${JSON.stringify(p)} must not reorder`);
+    assert.equal(d.priorityGoal, null);
+  }
+});
+
+test('a stringified priority id (a bigint from the database) still counts', () => {
+  const d = decideRun({ fence: open({ goals: [{ goal_id: 1 }, { goal_id: 2 }], priority_goal_id: '2' }), ...GRADER_OK });
+  assert.deepEqual(d.goals, [2, 1]);
+  assert.equal(d.priorityGoal, 2);
+});
+
+test('narrowing on the command line keeps the priority first, and can drop it', () => {
+  const f = normaliseFence(open({ goals: [{ goal_id: 1 }, { goal_id: 2 }, { goal_id: 3 }], priority_goal_id: 3 }));
+  assert.deepEqual(allowedGoals(f, [1, 3]).goals, [3, 1]);
+  // An operator narrowing to goals that leave the priority out gets no priority —
+  // it is not quietly re-added behind their back.
+  assert.deepEqual(allowedGoals(f, [1, 2]).goals, [1, 2]);
+  const d = decideRun({ fence: open({ goals: [{ goal_id: 1 }, { goal_id: 2 }, { goal_id: 3 }], priority_goal_id: 3 }), requestedGoals: [1, 2], ...GRADER_OK });
+  assert.equal(d.priorityGoal, null, 'a row must not claim a pick came from a priority this run excluded');
+});
+
+test('prioritise only reorders: same members, same count', () => {
+  assert.deepEqual(fence.prioritise([5, 6, 7], 6), [6, 5, 7]);
+  assert.deepEqual(fence.prioritise([5, 6, 7], 8), [5, 6, 7]);
+  assert.deepEqual(fence.prioritise([5, 6, 7], null), [5, 6, 7]);
+});
+
+test('a closed fence still refuses whatever the priority says', () => {
+  const d = decideRun({ fence: open({ enabled: false, priority_goal_id: 1000119 }), ...GRADER_OK });
+  assert.equal(d.go, false);
+  assert.equal(d.code, 'kill_switch');
+  assert.deepEqual(d.goals, []);
+});