@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/module-error-report.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/bongos/module-error-report.js — send this instance's daily runtime-error
+// count for each store module to the store, with the builder sign-in on this box
+// (task 1004637, follow-up to task 1003793; ADR 0343 D1).
+//
+// WHY. The store scores a module's Reliability from daily error counts, and nothing
+// sent one. The server keeps the tally (src/module-loader/error-tally.js writes
+// module-error-counts.json in the instance config dir); this script sends every
+// finished day it has not sent yet — including a 0, because a clean day is what
+// Reliability measures — and remembers which days went in module-error-sent.json.
+//
+// WHO SENDS (owner, 2026-10-15): a builder's sign-in on this box, because the store's
+// report routes take a builder and no project-to-store credential exists (that option
+// is parked as task 1004740). No sign-in here means nothing is sent, quietly.
+//
+// PRIVACY (owner, 2026-10-01): counts only, on by default, with an opt-out. If the
+// signed-in builder switched reporting off in Settings, nothing is sent and the days
+// are marked done; the store also drops a report from an opted-out holder, so the
+// rule holds whichever client sends.
+//
+// The server runs this every few hours (error-tally.js startDailySend); it is safe to
+// run by hand too:
+//   node scripts/bongos/module-error-report.js [--dry-run] [--quiet]
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { readTally, utcDay, FILE_NAME } = require('../../src/module-loader/error-tally');
+
+const SENT_FILE = 'module-error-sent.json';
+// The store takes days up to 30 back (module-usage-reports.js ERROR_DAY_WINDOW).
+const WINDOW_DAYS = 30;
+const ENTRY_RE = /^([a-z0-9][a-z0-9-]*)@(\d+\.\d+\.\d+)$/;
+
+function daysAgo(today, n) { return utcDay(Date.parse(`${today}T00:00:00Z`) - n * 86_400_000); }
+
+// The finished days still to send, oldest first. Pure.
+function pendingDays(days, sent, today) {
+  const oldest = daysAgo(today, WINDOW_DAYS);
+  return Object.keys(days || {}).filter((d) => d < today && d >= oldest && !(sent && sent[d])).sort();
+}
+
+// Send what is pending. `call(method, path, { json })` is the store client (module.js
+// storeRequest). Never throws for a store answer: a day is marked done only when
+// every count in it got a final answer — recorded, or refused for good (4xx: the store
+// does not have that version, or this builder does not hold the module). A 5xx or an
+// unreachable store leaves the day for the next run. Returns a summary.
+async function sendPending({ days, sent = {}, today, call, dryRun = false }) {
+  const out = { pending: pendingDays(days, sent, today), sentDays: [], posted: 0, skipped: 0, optedOut: false, retryLater: false };
+  if (!out.pending.length) return out;
+
+  const pref = await call('GET', '/store/usage-reporting');
+  if (!pref.ok) { out.retryLater = true; return out; }
+  if (pref.data && pref.data.enabled === false) {
+    out.optedOut = true;
+    if (!dryRun) out.sentDays = out.pending.slice();
+    return out;
+  }
+
+  const entries = new Set();
+  for (const d of out.pending) for (const e of Object.keys(days[d] || {})) if (ENTRY_RE.test(e)) entries.add(e);
+  const keys = [...new Set([...entries].map((e) => e.match(ENTRY_RE)[1]))];
+  let known = new Set();
+  if (keys.length) {
+    const res = await call('GET', `/store/modules/latest?keys=${keys.map(encodeURIComponent).join(',')}`);
+    if (!res.ok) { out.retryLater = true; return out; }
+    known = new Set(Object.keys((res.data && res.data.latest) || {}));
+  }
+
+  for (const day of out.pending) {
+    let done = true;
+    for (const [e, count] of Object.entries(days[day] || {})) {
+      const m = e.match(ENTRY_RE);
+      if (!m || !known.has(m[1]) || !Number.isInteger(count) || count < 0) { out.skipped += 1; continue; }
+      if (dryRun) { out.posted += 1; continue; }
+      let res;
+      try {
+        res = await call('POST', `/store/modules/${encodeURIComponent(m[1])}/versions/${encodeURIComponent(m[2])}/error-count`, { json: { day, count } });
+      } catch { res = { ok: false, status: 0 }; }
+      if (res.ok) out.posted += 1;
+      else if (res.status >= 400 && res.status < 500) out.skipped += 1;
+      else done = false;
+    }
+    if (done && !dryRun) out.sentDays.push(day);
+    else if (!done) out.retryLater = true;
+  }
+  return out;
+}
+
+function readSent(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return parsed && parsed.sent && typeof parsed.sent === 'object' ? parsed.sent : {};
+  } catch { return {}; }
+}
+
+// Record the days sent, dropping any older than the store's window.
+function writeSent(file, sent, newDays, today) {
+  const oldest = daysAgo(today, WINDOW_DAYS + 1);
+  const next = {};
+  for (const d of [...Object.keys(sent), ...newDays]) if (d >= oldest) next[d] = true;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify({ sent: next }, null, 2));
+  fs.renameSync(tmp, file);
+}
+
+async function main(argv = process.argv.slice(2), {
+  log = console.log, request, tallyFile, sentFile, today = utcDay(),
+} = {}) {
+  const quiet = argv.includes('--quiet');
+  const dryRun = argv.includes('--dry-run');
+  const say = (m) => { if (!quiet) log(m); };
+  const { configPath } = require('../../src/instance-config');
+  const tFile = tallyFile || configPath(FILE_NAME);
+  const sFile = sentFile || configPath(SENT_FILE);
+
+  const days = readTally(tFile);
+  const sent = readSent(sFile);
+  if (!pendingDays(days, sent, today).length) { say('module error counts: nothing to send.'); return 0; }
+
+  let call = request;
+  if (!call) {
+    try { call = require('./module').storeRequest(); }
+    catch { say('module error counts: no Bongos sign-in on this machine, so nothing was sent.'); return 0; }
+  }
+
+  let out;
+  try { out = await sendPending({ days, sent, today, call, dryRun }); }
+  catch (e) { say(`module error counts: the store could not be reached (${e.message}); will try again later.`); return 1; }
+  if (out.sentDays.length) writeSent(sFile, sent, out.sentDays, today);
+
+  if (out.optedOut) say('module error counts: reporting is switched off in your Settings, so nothing was sent.');
+  else say(`module error counts: ${dryRun ? 'would send' : 'sent'} ${out.posted} count(s) for ${out.pending.length} day(s); ${out.skipped} skipped (not a store module you hold)${out.retryLater ? '; some will be retried later' : ''}.`);
+  return out.retryLater ? 1 : 0;
+}
+
+module.exports = { pendingDays, sendPending, main };
+
+if (require.main === module) {
+  // Set the exit code and drain, never a hard exit after a request (task 1002734).
+  Promise.resolve(main()).then(
+    (code) => { process.exitCode = code; },
+    (e) => { console.error(e && e.message ? e.message : e); process.exitCode = 1; },
+  );
+}

package/scripts/{gds → bongos}/module-test-runner/README.md

@@ -4,7 +4,7 @@ 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).
+[`scripts/bongos/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`.
@@ -35,8 +35,8 @@ Cost: free within GitHub's included Actions minutes for a private repo
 ## Running it by hand
 
 ```
-node scripts/gds/module-test-runner.js dispatch <store_module_versions.id>
-node scripts/gds/module-test-runner.js collect
+node scripts/bongos/module-test-runner.js dispatch <store_module_versions.id>
+node scripts/bongos/module-test-runner.js collect
 ```
 
 `dispatch` only sends a run when the version has no Tests result yet (or only a

package/scripts/{gds → bongos}/module-test-runner/module-tests.yml

@@ -2,7 +2,7 @@
 #
 # 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;
+# plane (scripts/bongos/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
@@ -93,7 +93,7 @@ jobs:
           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' \
+            bash -c 'cd /home/moduletest/core && exec node scripts/bongos/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/bongos/module-test-runner.js

@@ -0,0 +1,414 @@
+#!/usr/bin/env node
+// scripts/bongos/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/bongos/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_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
+//      and the core snapshot into the run as artifacts; a separate `test` job
+//      (permissions: {}) unpacks the core, 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 THE CORE TRAVELS AS A SNAPSHOT (task 1004739). The core repo is private, so
+// a runner whose token has no permissions cannot check it out by name. Before the
+// first run against a core commit, dispatch pushes `git archive` of that commit
+// (tracked files only, so never node_modules; minus the design mocks in
+// .impeccable/, which nothing runs) to an orphan branch `core/<sha>` in the test
+// repo, with the same token. Once per commit: a later dispatch finds the ref and
+// reuses it. The `fetch` job reads it with its contents: read token like the
+// tarball, so the `test` job still needs no permission and no repo name at all.
+// GitHub refuses a blob over 100 MB and the archive goes up base64-encoded (a
+// third bigger), so a snapshot over MAX_CORE_BYTES fails the dispatch loudly: a
+// dispatch that cannot be sent is logged as an error, not a warning, because the
+// version's Tests part then stays pending until someone fixes the cause.
+//
+// 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 control-plane env vars (repo + token 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_REF        the test repo branch holding the workflow (default main)
+//
+//   node scripts/bongos/module-test-runner.js dispatch <store_module_versions.id>
+//   node scripts/bongos/module-test-runner.js collect
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const zlib = require('node:zlib');
+const { execFile } = require('node:child_process');
+const { promisify } = require('node:util');
+
+const execFileAsync = promisify(execFile);
+
+const WORKFLOW_FILE = 'module-tests.yml';
+const BRANCH_PREFIX = 'module-test/';
+const CORE_BRANCH_PREFIX = 'core/';
+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;
+// GitHub's blob limit is 100 MB and the snapshot is sent base64 (4/3 the size).
+const MAX_CORE_BYTES = 72 * 1024 * 1024;
+const CORE_ROOT = path.join(__dirname, '..', '..');
+const REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const NONCE_RE = /^[0-9a-f]{32}$/;
+const SHA_RE = /^[0-9a-f]{40}$/;
+
+const runName = (versionId, nonce) => `module-tests ${versionId} ${nonce}`;
+const artifactName = (versionId, nonce) => `module-tests-${versionId}-${nonce}`;
+
+// The runner config, or null when it is not set up (the default: Tests stays pending).
+function runnerConfig(env = process.env) {
+  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 ref = (env.MODULE_TEST_REF || '').trim() || 'main';
+  return { repo, token, 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;
+}
+
+// The core at one commit, as the tar.gz the runner unpacks. Async, so the web
+// process keeps serving while git compresses. It needs the commit in a git
+// checkout here: a vendored core (node_modules/@bongos/core) has none, and gets
+// an error that says so rather than git's own.
+async function archiveCore(sha) {
+  try {
+    const { stdout } = await execFileAsync('git', ['archive', '--format=tar.gz', sha, '--', '.', ':(exclude).impeccable', ':(exclude)node_modules'],
+      { cwd: CORE_ROOT, encoding: 'buffer', maxBuffer: 4 * MAX_CORE_BYTES });
+    return stdout;
+  } catch (e) {
+    const why = String((e.stderr && e.stderr.toString()) || e.message).trim().split('\n')[0];
+    throw new Error(`could not snapshot core commit ${sha.slice(0, 8)}: the core must run from a git checkout that holds it (a vendored install has none) — git said: ${why}`);
+  }
+}
+
+// Push a one-file orphan commit to a new branch of the test repo.
+async function pushOrphanBranch(cfg, branch, file, bytes, message, { fetchImpl } = {}) {
+  const r = `/repos/${cfg.repo}`;
+  const blob = await gh(cfg, 'POST', `${r}/git/blobs`, { content: bytes.toString('base64'), encoding: 'base64' }, { fetchImpl });
+  const tree = await gh(cfg, 'POST', `${r}/git/trees`, { tree: [{ path: file, mode: '100644', type: 'blob', sha: blob.sha }] }, { fetchImpl });
+  const commit = await gh(cfg, 'POST', `${r}/git/commits`, { message, tree: tree.sha, parents: [] }, { fetchImpl });
+  await gh(cfg, 'POST', `${r}/git/refs`, { ref: `refs/heads/${branch}`, sha: commit.sha }, { fetchImpl });
+}
+
+// Make sure branch core/<sha> holds the core snapshot, pushing it only the first
+// time. Resolves { branch, pushed }. Two dispatches racing on a new commit both
+// push; the loser's ref create is refused (422) and it uses the winner's.
+async function ensureCoreSnapshot(cfg, sha, { fetchImpl, archive = archiveCore } = {}) {
+  if (!SHA_RE.test(sha || '')) throw new Error(`the running core commit is unknown ("${sha || ''}"), so there is no core to test against`);
+  const branch = `${CORE_BRANCH_PREFIX}${sha}`;
+  try {
+    await gh(cfg, 'GET', `/repos/${cfg.repo}/git/ref/heads/${branch}`, null, { fetchImpl });
+    return { branch, pushed: false };
+  } catch (e) { if (e.status !== 404) throw e; }
+  const tgz = await archive(sha);
+  if (tgz.length > MAX_CORE_BYTES) {
+    throw new Error(`the core snapshot for ${sha.slice(0, 8)} is ${(tgz.length / 1048576).toFixed(1)} MB, over the ${MAX_CORE_BYTES / 1048576} MB the test repo can take; trim what archiveCore sends in scripts/bongos/module-test-runner.js`);
+  }
+  try {
+    await pushOrphanBranch(cfg, branch, 'core.tgz', tgz, `core snapshot ${sha}`, { fetchImpl });
+  } catch (e) {
+    if (e.status === 422) return { branch, pushed: false };
+    throw e;
+  }
+  return { branch, pushed: true };
+}
+
+function readVersionTarball(ver) {
+  const { versionArtifactFile } = require('../../src/bongos/module-store');
+  return fs.promises.readFile(versionArtifactFile(ver));
+}
+
+// Make sure the core snapshot is there, push the tarball to a throwaway orphan
+// branch, and dispatch the workflow. Resolves the runner record kept in the
+// pending row: { nonce, branch, core_ref, dispatched_at }.
+async function dispatchRun(ver, { cfg, fetchImpl, readTarball = readVersionTarball, coreRef = currentCoreRef, archive, now = () => new Date() } = {}) {
+  const sha = coreRef();
+  await ensureCoreSnapshot(cfg, sha, { fetchImpl, archive });
+  const tgz = await readTarball(ver);
+  const nonce = crypto.randomBytes(16).toString('hex');
+  const branch = `${BRANCH_PREFIX}${nonce}`;
+  await pushOrphanBranch(cfg, branch, 'module.tgz', tgz, `module tests: version ${ver.id}`, { fetchImpl });
+  try {
+    await gh(cfg, 'POST', `/repos/${cfg.repo}/actions/workflows/${WORKFLOW_FILE}/dispatches`, {
+      ref: cfg.ref || 'main',
+      inputs: { version_id: String(ver.id), module_key: ver.module_key, nonce, core_ref: sha },
+    }, { fetchImpl });
+  } catch (e) {
+    await deleteBranch(cfg, branch, { fetchImpl });
+    throw e;
+  }
+  return { nonce, branch, core_ref: sha, 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.error(`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/bongos/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, archiveCore, maybeDispatch, collectResults, sweepTick, readZipEntry, validateSignal, runName, artifactName };