@bongos/core 1.21.124 → 1.21.126

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

@@ -33,13 +33,16 @@
 // (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
+// secrets on disk: GitHub's free runners, driven by module-test-runner.js (task 1004460). `--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)
+//   node scripts/gds/module-assess-tests.js --tarball <f> --key <k> --version-id N --nonce X --json
+//                                    the testing environment's mode: no DB, prints the
+//                                    signal JSON (module-test-runner.js; task 1004460)
 
 const fs = require('node:fs');
 const path = require('node:path');
@@ -177,6 +180,18 @@ async function insertSignal(versionId, s, { db }) {
   return row;
 }
 
+const notScored = (e) => ({ outcome: 'not_scored', score: null, sample_size: null, reason: `the tests could not run (${e.code || 'error'})`, detail: {} });
+
+// Verify a tarball and run its tests: the signal fields, with a tarball that fails
+// verification as not_scored. No DB — this is what the separate testing
+// environment runs (`--tarball`, module-test-runner.js); assessTests keeps the gate.
+async function assessTarball(tgz, key, opts = {}) {
+  const { verifyModuleArtifact } = require('./module-artifact');
+  const v = await verifyModuleArtifact(tgz, { key, includeFiles: true });
+  if (!v.ok) return { outcome: 'not_scored', score: null, sample_size: null, reason: `the tarball failed verification (${v.code}): ${v.message}`, detail: {} };
+  return assessTests(key, v.files, opts);
+}
+
 // 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.
@@ -185,21 +200,16 @@ async function recordTestsSignal(versionId, { db, storeDir, root, timeoutMs, exe
   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: {} };
+    const tgz = await fs.promises.readFile(versionArtifactFile(ver, storeDir ? { dir: storeDir } : {}));
+    signal = await assessTarball(tgz, ver.module_key, { root, timeoutMs, exec, env });
   } catch (e) {
-    signal = { outcome: 'not_scored', score: null, sample_size: null, reason: `the tests could not run (${e.code || 'error'})`, detail: {} };
+    signal = notScored(e);
   }
   const row = await insertSignal(ver.id, signal, { db: pool });
   return { ok: true, version: ver, signal: row };
@@ -220,7 +230,26 @@ function readModuleDir(dir) {
   return out;
 }
 
+// The value after a flag, or null.
+const flag = (argv, name) => { const i = argv.indexOf(name); return i === -1 ? null : (argv[i + 1] || ''); };
+
 async function main(argv) {
+  // DB-free, for the separate testing environment: verify + run + print the signal
+  // JSON (with the run's version id and nonce, which the control plane checks when
+  // it pulls the result). The gate still applies: without MODULE_TEST_SANDBOX=1 and
+  // a secret-free environment this refuses before anything is read.
+  const tarball = flag(argv, '--tarball');
+  if (tarball !== null) {
+    const key = flag(argv, '--key');
+    if (!tarball || !key) { console.error('usage: --tarball <file> --key <module key> [--version-id N --nonce X] --json'); return 2; }
+    const refused = runRefusal();
+    if (refused) { console.error(refused.message); return 1; }
+    let s;
+    try { s = await assessTarball(fs.readFileSync(tarball), key); }
+    catch (e) { s = notScored(e); }
+    console.log(JSON.stringify({ version_id: flag(argv, '--version-id'), nonce: flag(argv, '--nonce'), ...s }));
+    return 0;
+  }
   const i = argv.indexOf('--dir');
   if (i !== -1) {
     const dir = path.resolve(argv[i + 1] || '');
@@ -231,7 +260,7 @@ async function main(argv) {
   }
   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>');
+    console.error('usage: node scripts/gds/module-assess-tests.js <store_module_versions.id> | --dir modules/<key> | --tarball <file> --key <k> --json');
     return 2;
   }
   const res = await recordTestsSignal(id);
@@ -246,4 +275,4 @@ 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 };
+module.exports = { discoverTestFiles, assessTests, assessTarball, recordTestsSignal, insertSignal, runRefusal, testEnv, SANDBOX_PREFIX };

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

@@ -7,6 +7,8 @@
 // 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).
+// When the runner is configured (module-test-runner.js) the tests are dispatched to
+// it here, and its result is pulled back into the row later.
 // 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. Docs is one Sonnet call over
 // the HOWTO.md text (module-assess-docs.js) — also no module code. Then the score is
@@ -27,12 +29,18 @@ const { recomposeScore } = require('./module-assess-score');
 // the score. `recordSecurity` / `recordDocs` are injectable so tests need no npm
 // and no model. 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, recordDocs } = {}) {
+async function assessVersion(versionId, { db, recordSecurity, recordDocs, dispatchTests } = {}) {
   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]);
+    '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}` };
 
+  // When the separate test environment is configured, send the run there first
+  // (module-test-runner.js; task 1004460): it records a pending row carrying the
+  // run's nonce, so the plain pending below then has nothing to add. Unconfigured
+  // (or a failed dispatch), nothing is sent and Tests stays plain pending.
+  await (dispatchTests || require('./module-test-runner').maybeDispatch)(ver, { db: pool });
+
   // Only a version with no Tests result yet: a re-assess must never hide a real
   // score behind a newer "pending".
   await pool.query(

package/scripts/gds/module-test-runner/README.md

@@ -0,0 +1,44 @@
+# Module test runner — setup (task 1004460)
+
+A published store module's own tests run on GitHub's free runners, in a separate
+**private** repo, never on the control plane (owner decision, 2026-10-14). The
+control plane sends each run and pulls its result back; the runner never gets a
+database credential. How and why: the header of
+[`scripts/gds/module-test-runner.js`](../module-test-runner.js).
+
+Until the three steps below are done, nothing changes: a new version's Tests part
+stays `pending`.
+
+## Owner steps (one time)
+
+1. **Create the private repo** on GitHub (any name, e.g. `<you>/bongos-module-tests`),
+   with a `main` branch. Copy [`module-tests.yml`](module-tests.yml) into it as
+   `.github/workflows/module-tests.yml`. Keep it private: run logs show test output.
+2. **Create a fine-grained token** (GitHub → Settings → Developer settings →
+   Fine-grained tokens) with **Repository access: only that repo**, and permissions
+   **Actions: Read and write** and **Contents: Read and write**. Nothing else.
+3. **Set it on the control plane** in the web env file, then restart the web service:
+   ```
+   MODULE_TEST_REPO=<owner>/<repo>
+   MODULE_TEST_TOKEN=<the token>
+   ```
+   Optional: `MODULE_TEST_CORE_REPO=<owner>/<name>` if the server's git `origin` is not
+   the public core repo, and `MODULE_TEST_REF=<branch>` if the test repo's workflow
+   lives on a branch other than `main`.
+
+On the runner, a module's tests run as a separate user with no admin rights and
+no network access (only the machine's own loopback), after the core is installed.
+
+Cost: free within GitHub's included Actions minutes for a private repo
+(about 2,000 a month on the free plan); each run is a few minutes.
+
+## Running it by hand
+
+```
+node scripts/gds/module-test-runner.js dispatch <store_module_versions.id>
+node scripts/gds/module-test-runner.js collect
+```
+
+`dispatch` only sends a run when the version has no Tests result yet (or only a
+pending one with no run). The web process collects on its own every five minutes
+while runs are pending; after a restart, `collect` picks up anything left.

package/scripts/gds/module-test-runner/module-tests.yml

@@ -0,0 +1,87 @@
+# The separate testing environment for a published module's own tests (task 1004460).
+#
+# THIS FILE DOES NOT RUN IN THE CORE REPO. Copy it to .github/workflows/module-tests.yml
+# in the owner's separate PRIVATE test repo (see README.md beside it). The control
+# plane (scripts/gds/module-test-runner.js) dispatches it and pulls the result back;
+# nothing here ever holds a DB credential or a control-plane secret.
+#
+# Two jobs on purpose: `fetch` can read the repo (where the tarball waits on a
+# throwaway branch) but runs no module code; `test` runs the module's code with a
+# GITHUB_TOKEN that has NO permissions, so a module that scrapes its token still
+# cannot read another run's tarball. Inside `test`, the module's code runs as an
+# unprivileged user with its network cut (see "Cut the network for module code").
+name: module-tests
+run-name: module-tests ${{ inputs.version_id }} ${{ inputs.nonce }}
+
+on:
+  workflow_dispatch:
+    inputs:
+      version_id: { description: store_module_versions.id, required: true, type: string }
+      module_key: { description: the module's key, required: true, type: string }
+      nonce: { description: this run's nonce (32 hex), required: true, type: string }
+      core_repo: { description: owner/name of the public core, required: true, type: string }
+      core_ref: { description: the core commit to test against, required: true, type: string }
+
+permissions: {}
+
+jobs:
+  fetch:
+    runs-on: ubuntu-latest
+    permissions: { contents: read }
+    timeout-minutes: 5
+    steps:
+      - name: Check the inputs
+        env: { NONCE: "${{ inputs.nonce }}", VERSION_ID: "${{ inputs.version_id }}" }
+        run: |
+          [[ "$NONCE" =~ ^[0-9a-f]{32}$ ]] || { echo "bad nonce"; exit 1; }
+          [[ "$VERSION_ID" =~ ^[0-9]+$ ]] || { echo "bad version id"; exit 1; }
+      - uses: actions/checkout@v4
+        with: { ref: "module-test/${{ inputs.nonce }}", path: tarball, persist-credentials: false }
+      - uses: actions/upload-artifact@v4
+        with: { name: "tarball-${{ inputs.nonce }}", path: tarball/module.tgz, retention-days: 1 }
+
+  test:
+    needs: fetch
+    runs-on: ubuntu-latest
+    permissions: {}
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+        with: { repository: "${{ inputs.core_repo }}", ref: "${{ inputs.core_ref }}", path: core, persist-credentials: false }
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - uses: actions/download-artifact@v4
+        with: { name: "tarball-${{ inputs.nonce }}", path: in }
+      - name: Install the core
+        working-directory: core
+        run: npm ci --no-audit --no-fund
+      # Module code never runs as `runner` (which has passwordless sudo and the
+      # runner's own files): it runs as `moduletest`, a fresh user with no sudo, and
+      # the firewall rejects every packet that user sends except on loopback. So a
+      # module's tests get no network egress, and cannot lift the block themselves.
+      # The install above was the last step that needed the network.
+      - name: Cut the network for module code
+        run: |
+          sudo useradd --create-home --shell /bin/bash moduletest
+          sudo mv core in /home/moduletest/
+          sudo chown -R moduletest:moduletest /home/moduletest
+          for t in iptables ip6tables; do
+            sudo "$t" -A OUTPUT -m owner --uid-owner moduletest -o lo -j ACCEPT
+            sudo "$t" -A OUTPUT -m owner --uid-owner moduletest -j REJECT
+          done
+          if sudo -u moduletest -H curl -sS --max-time 5 https://github.com >/dev/null 2>&1; then
+            echo "the network block did not hold"; exit 1
+          fi
+      - name: Run the module's own tests
+        env:
+          VERSION_ID: "${{ inputs.version_id }}"
+          MODULE_KEY: "${{ inputs.module_key }}"
+          NONCE: "${{ inputs.nonce }}"
+        run: |
+          mkdir -p out
+          NODE_DIR="$(dirname "$(command -v node)")"
+          sudo -u moduletest -H env -i PATH="$NODE_DIR:/usr/bin:/bin" HOME=/home/moduletest MODULE_TEST_SANDBOX=1 \
+            bash -c 'cd /home/moduletest/core && exec node scripts/gds/module-assess-tests.js --tarball ../in/module.tgz --key "$1" --version-id "$2" --nonce "$3" --json' \
+            _ "$MODULE_KEY" "$VERSION_ID" "$NONCE" > out/signal.json
+      - uses: actions/upload-artifact@v4
+        with: { name: "module-tests-${{ inputs.version_id }}-${{ inputs.nonce }}", path: out/signal.json, retention-days: 3 }

package/scripts/gds/module-test-runner.js

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+// scripts/gds/module-test-runner.js — the separate testing environment for a
+// published module's OWN tests (task 1004460; ADR 0343). The owner chose GitHub's
+// free runners (2026-10-14): no new server, nothing bought.
+//
+// WHY A SEPARATE PRIVATE REPO. A module's tests are third-party code, so they never
+// run on the control plane (module-assess-tests.js refuses outside
+// MODULE_TEST_SANDBOX=1), and never in this repo's own Actions either (.github/ is
+// protected substrate, and its runs can reach this repo's secrets). They run in a
+// separate PRIVATE repo the owner creates, holding only the workflow in
+// scripts/gds/module-test-runner/ — private so run logs and inputs stay non-public.
+//
+// THE ROUND TRIP. Nothing on the runner ever holds a DB credential:
+//   1. dispatch — the control plane pushes the version's tarball to a throwaway
+//      orphan branch `module-test/<nonce>` in the test repo and dispatches the
+//      workflow with { version_id, module_key, nonce, core_repo, core_ref }. The
+//      nonce goes into the pending Tests row's detail.runner.
+//   2. the run — a `fetch` job (contents: read, no module code) copies the tarball
+//      into the run as an artifact; a separate `test` job (permissions: {}) checks
+//      out the core at core_ref, runs module-assess-tests.js --tarball with
+//      MODULE_TEST_SANDBOX=1, and uploads the signal JSON as artifact
+//      module-tests-<version_id>-<nonce>.
+//   3. collect — the control plane PULLS: it finds the run whose run-name carries
+//      the pending row's nonce, takes only that run's artifact of that exact name,
+//      checks the payload names the same version and nonce, inserts the signal row
+//      itself, recomposes the score, and deletes the branch.
+//
+// WHY A PER-RUN BRANCH, NOT A DOWNLOAD TICKET. A ticket would mean a new
+// unauthenticated route on the control plane (and a change to the protected
+// route-rank-check), i.e. a fresh inbound path to the server holding the secrets.
+// The branch keeps every byte flowing OUT from the control plane. The cost: a paid
+// module's tarball sits in the private test repo for the length of one run. It is
+// safe from OTHER modules' runs because the only job that can read the repo's
+// contents (`fetch`) runs no module code, and the job that does (`test`) gets a
+// GITHUB_TOKEN with no permissions — so a module that scrapes its runner's token
+// still cannot read another run's branch. A module author can always make their own
+// tests pass, so the score is never trust-critical; what this protects is the
+// secrets and other authors' code.
+//
+// Configured by three control-plane env vars (all unset = off; Tests then stays
+// `pending`, exactly as before this task):
+//   MODULE_TEST_REPO       owner/name of the private test repo
+//   MODULE_TEST_TOKEN      a fine-grained token scoped to ONLY that repo, with
+//                          Actions: read & write and Contents: read & write
+//   MODULE_TEST_CORE_REPO  owner/name of the public core the runner checks out
+//                          (default: this checkout's `origin`)
+//   MODULE_TEST_REF        the test repo branch holding the workflow (default main)
+//
+//   node scripts/gds/module-test-runner.js dispatch <store_module_versions.id>
+//   node scripts/gds/module-test-runner.js collect
+
+const fs = require('node:fs');
+const crypto = require('node:crypto');
+const zlib = require('node:zlib');
+const { execFileSync } = require('node:child_process');
+
+const WORKFLOW_FILE = 'module-tests.yml';
+const BRANCH_PREFIX = 'module-test/';
+const API = 'https://api.github.com';
+// A run that has not finished this long after dispatch is recorded not_scored.
+const MAX_RUN_AGE_MS = 6 * 60 * 60_000;
+const MAX_SIGNAL_BYTES = 256 * 1024;
+const REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const NONCE_RE = /^[0-9a-f]{32}$/;
+
+const runName = (versionId, nonce) => `module-tests ${versionId} ${nonce}`;
+const artifactName = (versionId, nonce) => `module-tests-${versionId}-${nonce}`;
+
+function originRepo() {
+  try {
+    const url = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd: __dirname, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    const m = url.match(/github\.com[/:]([^/]+\/[^/]+?)(?:\.git)?$/);
+    return m ? m[1] : null;
+  } catch { return null; }
+}
+
+// The runner config, or null when it is not set up (the default: Tests stays pending).
+function runnerConfig(env = process.env, { origin = originRepo } = {}) {
+  const repo = (env.MODULE_TEST_REPO || '').trim();
+  const token = (env.MODULE_TEST_TOKEN || '').trim();
+  if (!repo || !token) return null;
+  if (!REPO_RE.test(repo)) throw new Error(`MODULE_TEST_REPO must be owner/name, got "${repo}"`);
+  const coreRepo = (env.MODULE_TEST_CORE_REPO || '').trim() || origin();
+  if (!coreRepo || !REPO_RE.test(coreRepo)) throw new Error('MODULE_TEST_CORE_REPO is unset and the core repo could not be read from git origin');
+  const ref = (env.MODULE_TEST_REF || '').trim() || 'main';
+  return { repo, token, coreRepo, ref };
+}
+
+// One GitHub REST call. Resolves the parsed body (or null for 204); throws with
+// .status on a non-2xx.
+async function gh(cfg, method, urlPath, body, { fetchImpl = fetch } = {}) {
+  const res = await fetchImpl(urlPath.startsWith('https://') ? urlPath : `${API}${urlPath}`, {
+    method,
+    headers: { Authorization: `Bearer ${cfg.token}`, Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28', 'User-Agent': 'bongos-module-test-runner', ...(body ? { 'Content-Type': 'application/json' } : {}) },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw Object.assign(new Error(`GitHub ${method} ${urlPath} → ${res.status} ${text.slice(0, 200)}`), { status: res.status });
+  }
+  return res.status === 204 ? null : res.json();
+}
+
+// The commit the control plane is running, so the runner tests against the same core.
+function currentCoreRef() {
+  const { buildInfo } = require('../../src/build-info');
+  return buildInfo().commit || 'main';
+}
+
+function readVersionTarball(ver) {
+  const { versionArtifactFile } = require('../../src/bongos/module-store');
+  return fs.promises.readFile(versionArtifactFile(ver));
+}
+
+// Push the tarball to a throwaway orphan branch and dispatch the workflow.
+// Resolves the runner record kept in the pending row: { nonce, branch, dispatched_at }.
+async function dispatchRun(ver, { cfg, fetchImpl, readTarball = readVersionTarball, coreRef = currentCoreRef, now = () => new Date() } = {}) {
+  const tgz = await readTarball(ver);
+  const nonce = crypto.randomBytes(16).toString('hex');
+  const branch = `${BRANCH_PREFIX}${nonce}`;
+  const r = `/repos/${cfg.repo}`;
+  const blob = await gh(cfg, 'POST', `${r}/git/blobs`, { content: tgz.toString('base64'), encoding: 'base64' }, { fetchImpl });
+  const tree = await gh(cfg, 'POST', `${r}/git/trees`, { tree: [{ path: 'module.tgz', mode: '100644', type: 'blob', sha: blob.sha }] }, { fetchImpl });
+  const commit = await gh(cfg, 'POST', `${r}/git/commits`, { message: `module tests: version ${ver.id}`, tree: tree.sha, parents: [] }, { fetchImpl });
+  await gh(cfg, 'POST', `${r}/git/refs`, { ref: `refs/heads/${branch}`, sha: commit.sha }, { fetchImpl });
+  try {
+    await gh(cfg, 'POST', `${r}/actions/workflows/${WORKFLOW_FILE}/dispatches`, {
+      ref: cfg.ref || 'main',
+      inputs: { version_id: String(ver.id), module_key: ver.module_key, nonce, core_repo: cfg.coreRepo, core_ref: coreRef() },
+    }, { fetchImpl });
+  } catch (e) {
+    await deleteBranch(cfg, branch, { fetchImpl });
+    throw e;
+  }
+  return { nonce, branch, dispatched_at: now().toISOString() };
+}
+
+async function deleteBranch(cfg, branch, { fetchImpl } = {}) {
+  try { await gh(cfg, 'DELETE', `/repos/${cfg.repo}/git/refs/heads/${branch}`, null, { fetchImpl }); }
+  catch (e) { if (e.status !== 404 && e.status !== 422) throw e; }
+}
+
+// The newest Tests row for a version, or null.
+async function newestTestsRow(versionId, db) {
+  const { rows: [row] } = await db.query(
+    `SELECT id, outcome, detail FROM module_assessment_signals
+      WHERE version_id = $1 AND part = 'tests' ORDER BY measured_at DESC, id DESC LIMIT 1`, [versionId]);
+  return row || null;
+}
+
+// Called where a version's Tests is recorded `pending` (module-assess-version.js).
+// Dispatches a run only when the runner is configured and the version has no Tests
+// result yet, or only a pending one no run was sent for — so a re-assess never hides
+// a real score behind a newer pending. Resolves null when nothing was dispatched.
+// Never throws: a failed dispatch is logged and Tests stays plain pending.
+async function maybeDispatch(ver, { db, env = process.env, log = console, ...opts } = {}) {
+  let cfg;
+  try { cfg = opts.cfg || runnerConfig(env); }
+  catch (e) { log.warn(`module test runner misconfigured: ${e.message}`); return null; }
+  if (!cfg) return null;
+  const newest = await newestTestsRow(ver.id, db);
+  if (newest && !(newest.outcome === 'pending' && !(newest.detail && newest.detail.runner))) return null;
+  let runner;
+  try { runner = await dispatchRun(ver, { cfg, ...opts }); }
+  catch (e) { log.warn(`module test run for version ${ver.id} not dispatched: ${e.message}`); return null; }
+  await db.query(
+    `INSERT INTO module_assessment_signals (version_id, part, outcome, score, sample_size, reason, detail)
+     VALUES ($1, 'tests', 'pending', NULL, NULL, $2, $3)`,
+    [ver.id, 'running in the separate test environment', JSON.stringify({ runner })]);
+  ensureSweeper({ db, cfg, log });
+  return runner;
+}
+
+// ---------------------------------------------------------------------------
+// The zip a GitHub artifact downloads as. A small reader (stored + deflate) so no
+// zip dependency joins package.json. Returns the named entry's bytes, or null.
+// ---------------------------------------------------------------------------
+function readZipEntry(zip, name, { maxBytes = MAX_SIGNAL_BYTES } = {}) {
+  let eocd = -1;
+  for (let i = zip.length - 22; i >= Math.max(0, zip.length - 22 - 0xffff); i -= 1) {
+    if (zip.readUInt32LE(i) === 0x06054b50) { eocd = i; break; }
+  }
+  if (eocd < 0) throw new Error('not a zip: no end-of-central-directory record');
+  const count = zip.readUInt16LE(eocd + 10);
+  let p = zip.readUInt32LE(eocd + 16);
+  for (let n = 0; n < count; n += 1) {
+    if (p + 46 > zip.length || zip.readUInt32LE(p) !== 0x02014b50) throw new Error('bad zip central directory');
+    const method = zip.readUInt16LE(p + 10);
+    const compSize = zip.readUInt32LE(p + 20);
+    const size = zip.readUInt32LE(p + 24);
+    const nameLen = zip.readUInt16LE(p + 28);
+    const extraLen = zip.readUInt16LE(p + 30);
+    const commentLen = zip.readUInt16LE(p + 32);
+    const local = zip.readUInt32LE(p + 42);
+    const entryName = zip.toString('utf8', p + 46, p + 46 + nameLen);
+    p += 46 + nameLen + extraLen + commentLen;
+    if (entryName !== name) continue;
+    if (size > maxBytes || compSize > maxBytes) throw new Error(`zip entry ${name} is over ${maxBytes} bytes`);
+    if (zip.readUInt32LE(local) !== 0x04034b50) throw new Error('bad zip local header');
+    const start = local + 30 + zip.readUInt16LE(local + 26) + zip.readUInt16LE(local + 28);
+    const data = zip.subarray(start, start + compSize);
+    if (method === 0) return Buffer.from(data);
+    if (method === 8) return zlib.inflateRawSync(data, { maxOutputLength: maxBytes });
+    throw new Error(`zip entry ${name} uses unsupported method ${method}`);
+  }
+  return null;
+}
+
+// The runner's payload is written by a job that ran third-party code, so it is
+// held to the exact shape insertSignal stores and clipped; it is never trusted to
+// name its own version or nonce (those must match the run it was taken from).
+function validateSignal(raw, { versionId, nonce }) {
+  if (!raw || typeof raw !== 'object') throw new Error('the result is not a JSON object');
+  if (String(raw.version_id) !== String(versionId) || raw.nonce !== nonce) throw new Error('the result names a different version or run');
+  const { outcome } = raw;
+  if (!['scored', 'no_data', 'not_scored'].includes(outcome)) throw new Error(`unknown outcome "${outcome}"`);
+  let score = null;
+  let sample = outcome === 'no_data' ? 0 : null;
+  if (outcome === 'scored') {
+    if (!Number.isInteger(raw.score) || raw.score < 0 || raw.score > 100) throw new Error('a scored result needs an integer score 0–100');
+    if (!Number.isInteger(raw.sample_size) || raw.sample_size < 1 || raw.sample_size > 10_000) throw new Error('a scored result needs a positive sample_size');
+    score = raw.score; sample = raw.sample_size;
+  }
+  const files = Array.isArray(raw.detail && raw.detail.files) ? raw.detail.files.slice(0, 200).map((f) => ({
+    file: String((f && f.file) || '').slice(0, 200),
+    passed: !!(f && f.passed),
+    ...(f && f.timed_out ? { timed_out: true } : {}),
+    ...(f && f.tail ? { tail: String(f.tail).slice(0, 600) } : {}),
+  })) : [];
+  return { outcome, score, sample_size: sample, reason: String(raw.reason || '').slice(0, 500), detail: { files } };
+}
+
+// Download one artifact's zip. GitHub answers with a redirect to blob storage; the
+// token is not sent past it.
+async function downloadArtifact(cfg, artifact, { fetchImpl = fetch } = {}) {
+  const res = await fetchImpl(artifact.archive_download_url, { headers: { Authorization: `Bearer ${cfg.token}`, 'User-Agent': 'bongos-module-test-runner' }, redirect: 'manual' });
+  let final = res;
+  if (res.status >= 300 && res.status < 400) final = await fetchImpl(res.headers.get('location'));
+  if (!final.ok) throw new Error(`artifact download → ${final.status}`);
+  return Buffer.from(await final.arrayBuffer());
+}
+
+// Every version whose newest Tests row is a pending run we dispatched. Driven
+// from the versions (one row each) with one lookup per version on core_265's
+// idx_module_assessment_signals_current, so the cost follows the number of
+// versions, never the length of the append-only signal history.
+async function pendingRuns(db) {
+  const { rows } = await db.query(
+    `SELECT s.id, s.version_id, s.outcome, s.detail
+       FROM store_module_versions v
+       CROSS JOIN LATERAL (
+         SELECT id, version_id, outcome, detail FROM module_assessment_signals
+          WHERE version_id = v.id AND part = 'tests'
+          ORDER BY measured_at DESC, id DESC LIMIT 1) s
+      WHERE s.outcome = 'pending' AND s.detail ? 'runner'`);
+  return rows.filter((r) => r.outcome === 'pending' && r.detail && r.detail.runner && NONCE_RE.test(r.detail.runner.nonce || ''));
+}
+
+// Pull finished runs' results into module_assessment_signals. Resolves one entry
+// per pending run: { version_id, status, outcome? } — status 'recorded' (the run
+// finished; its result, or why there is none), 'waiting' (still running), or
+// 'expired' (never started or never finished within MAX_RUN_AGE_MS: not_scored).
+async function collectResults({ db, cfg, fetchImpl, now = () => Date.now(), recompose, insert } = {}) {
+  const pool = db || require('../../src/bongos/pool').pool;
+  const pending = await pendingRuns(pool);
+  if (pending.length === 0) return [];
+  const { runs = [] } = await gh(cfg, 'GET', `/repos/${cfg.repo}/actions/workflows/${WORKFLOW_FILE}/runs?event=workflow_dispatch&per_page=100`, null, { fetchImpl });
+  const doInsert = insert || require('./module-assess-tests').insertSignal;
+  const doRecompose = recompose || ((id) => require('./module-assess-score').recomposeScore(id, { db: pool }));
+  const out = [];
+  for (const p of pending) {
+    const { nonce, branch, dispatched_at: at } = p.detail.runner;
+    const run = runs.find((r) => r.display_title === runName(p.version_id, nonce));
+    const expired = now() - Date.parse(at) > MAX_RUN_AGE_MS;
+    let signal = null;
+    let status = 'recorded';
+    if (!run || run.status !== 'completed') {
+      if (!expired) { out.push({ version_id: p.version_id, status: 'waiting' }); continue; }
+      signal = { outcome: 'not_scored', score: null, sample_size: null, reason: run ? 'the test run did not finish in time' : 'the test run never started', detail: {} };
+      status = 'expired';
+    } else {
+      try {
+        const { artifacts = [] } = await gh(cfg, 'GET', `/repos/${cfg.repo}/actions/runs/${run.id}/artifacts?per_page=100`, null, { fetchImpl });
+        const art = artifacts.find((a) => a.name === artifactName(p.version_id, nonce) && !a.expired);
+        if (!art) throw new Error(`the test run ended (${run.conclusion}) without a result`);
+        const json = readZipEntry(await downloadArtifact(cfg, art, { fetchImpl }), 'signal.json');
+        if (!json) throw new Error('the result artifact carries no signal.json');
+        signal = validateSignal(JSON.parse(json.toString('utf8')), { versionId: p.version_id, nonce });
+      } catch (e) {
+        signal = { outcome: 'not_scored', score: null, sample_size: null, reason: String(e.message).slice(0, 500), detail: {} };
+      }
+      signal.detail = { ...signal.detail, runner: { nonce, run_id: run.id } };
+    }
+    await doInsert(p.version_id, signal, { db: pool });
+    await doRecompose(p.version_id);
+    if (branch && branch.startsWith(BRANCH_PREFIX)) await deleteBranch(cfg, branch, { fetchImpl }).catch(() => {});
+    out.push({ version_id: p.version_id, status, outcome: signal.outcome });
+  }
+  return out;
+}
+
+// In the web process: once a run is dispatched, sweep for results every few
+// minutes until none are pending, then stop. A restart drops the timer; the next
+// dispatch restarts it, and `collect` below picks up anything left over.
+const SWEEP_MS = 5 * 60_000;
+let sweeper = null;
+
+// One sweep. Resolves true to keep sweeping (a run is still out, or the sweep
+// failed and should be tried again), false once nothing is left waiting.
+async function sweepTick({ db, cfg, log = console, collect = collectResults }) {
+  try {
+    const res = await collect({ db, cfg });
+    return res.some((r) => r.status === 'waiting');
+  } catch (e) {
+    log.warn(`module test result sweep failed: ${e.message}`);
+    return true;
+  }
+}
+
+function ensureSweeper({ db, cfg, log = console }) {
+  if (sweeper) return;
+  sweeper = setInterval(async () => {
+    if (!(await sweepTick({ db, cfg, log })) && sweeper) { clearInterval(sweeper); sweeper = null; }
+  }, SWEEP_MS);
+  if (sweeper.unref) sweeper.unref();
+}
+
+async function main(argv) {
+  const cfg = runnerConfig();
+  if (!cfg) { console.error('the module test runner is not configured (set MODULE_TEST_REPO and MODULE_TEST_TOKEN)'); return 1; }
+  const { pool } = require('../../src/bongos/pool');
+  try {
+    if (argv[0] === 'dispatch' && /^\d+$/.test(argv[1] || '')) {
+      const { rows: [ver] } = await pool.query('SELECT id, module_key, version, artifact_path FROM store_module_versions WHERE id = $1', [argv[1]]);
+      if (!ver) { console.error(`no store_module_versions row ${argv[1]}`); return 1; }
+      const runner = await maybeDispatch(ver, { db: pool, cfg });
+      console.log(runner ? `dispatched version ${ver.id}: run ${runName(ver.id, runner.nonce)}` : `version ${ver.id} already has a Tests result or a run in flight — nothing dispatched`);
+      return runner ? 0 : 1;
+    }
+    if (argv[0] === 'collect') {
+      const res = await collectResults({ db: pool, cfg });
+      for (const r of res) console.log(`version ${r.version_id}: ${r.status}${r.outcome ? ` (${r.outcome})` : ''}`);
+      if (res.length === 0) console.log('no test runs pending');
+      return 0;
+    }
+    console.error('usage: node scripts/gds/module-test-runner.js dispatch <version id> | collect');
+    return 2;
+  } finally {
+    if (sweeper) { clearInterval(sweeper); sweeper = null; }
+    await pool.end();
+  }
+}
+
+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 = { runnerConfig, maybeDispatch, collectResults, sweepTick, readZipEntry, validateSignal, runName, artifactName };

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