@bongos/core 1.21.125 → 1.21.126

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.125'; // 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');

package/tests/goal_forest_lib.mjs

@@ -141,6 +141,34 @@ await test('describe states the numbers plainly, and an empty forest says so', (
   assert.equal(L.describe(L.analyse({})), 'No task in this goal depends on another task in this goal.');
 });
 
+// ---- the band card's summary (task 1004738) ---------------------------------------
+
+await test('brief is the short form of describe, and falls back to it for an empty forest', () => {
+  const a = L.analyse({ nodes: [1, 2, 3, 4, 5].map((i) => node(i)), edges: [edge(2, 1), edge(3, 2), edge(5, 4)] });
+  assert.equal(L.brief(a), '5 tasks linked by dependencies, in 2 chains.');
+  assert.equal(L.brief(L.analyse({})), L.describe(L.analyse({})));
+});
+
+await test('shipFirst ranks the open tasks nothing open blocks by how many open tasks wait on them, down the chain', () => {
+  // 1 ← 2 ← 3 and 1 ← 4: task 1 unblocks three. 5 ← 6: task 5 unblocks one.
+  const a = L.analyse({ nodes: [1, 2, 3, 4, 5, 6].map((i) => node(i)), edges: [edge(2, 1), edge(3, 2), edge(4, 1), edge(6, 5)] });
+  assert.deepEqual(L.shipFirst(a, 3).map((r) => [r.id, r.unblocks]), [['1', 3], ['5', 1]],
+    'a task still waiting on an open one is never "first"; one that unblocks nothing is left off');
+});
+
+await test('shipFirst: a shipped dependency frees what waits on it, and closed work is never listed or counted', () => {
+  const a = L.analyse({
+    nodes: [node(1, { status: 'shipped' }), node(2), node(3), node(4, { status: 'abandoned' })],
+    edges: [edge(2, 1), edge(3, 2), edge(4, 2)],
+  });
+  assert.deepEqual(L.shipFirst(a, 3).map((r) => [r.id, r.unblocks]), [['2', 1]], 'task 2 is up next and unblocks only the open task 3');
+});
+
+await test('shipFirst stops at the limit and breaks ties by task id', () => {
+  const a = L.analyse({ nodes: [1, 2, 3, 4, 5, 6, 7, 8].map((i) => node(i)), edges: [edge(5, 4), edge(6, 3), edge(7, 2), edge(8, 1)] });
+  assert.deepEqual(L.shipFirst(a, 3).map((r) => r.id), ['1', '2', '3']);
+});
+
 // ---- purity -----------------------------------------------------------------------
 
 await test('the lib is pure: no DOM, no fetch, no cross-goal input', () => {

package/tests/goal_forest_page.mjs

@@ -36,10 +36,11 @@ const settle = async () => { for (let i = 0; i < 20; i++) await tick(); };
 const t = (id, extra = {}) => ({ task_id: String(id), title: `Task ${id}`, status: 'ready', priority: 3, ...extra });
 const e = (from, to) => ({ from: String(from), to: String(to) });
 
-async function boot({ status = 200, fail = false, payload = { nodes: [], edges: [] } } = {}) {
+async function boot({ status = 200, fail = false, payload = { nodes: [], edges: [] }, conflictPairs = null, view = 'dependencies' } = {}) {
   const root = makeEl('div');
   const reg = (id) => { const el = makeEl('div', { id }); root.appendChild(el); return el; };
-  ['goal-deps-h', 'goal-deps-count', 'goal-deps-lede', 'goal-deps-body'].forEach(reg);
+  ['goal-deps-h', 'goal-deps-count', 'goal-deps-lede', 'goal-deps-body', 'goal-deps-back',
+    'goal-deps-card-count', 'goal-deps-card-lede', 'goal-deps-card-body', 'goal-deps-card-foot'].forEach(reg);
 
   const documentObj = {
     getElementById: (id) => walk(root, (el) => (el.id === id ? el : null)),
@@ -83,7 +84,7 @@ async function boot({ status = 200, fail = false, payload = { nodes: [], edges:
   vm.runInContext(read('bulk-toolbar.js'), sandbox, { filename: 'bulk-toolbar.js' }); // task 1003141
   vm.runInContext(RENDER_JS, sandbox, { filename: 'goals-render.js' });
 
-  const state = { current: 7, forest: null, forestError: false };
+  const state = { current: 7, view, forest: null, forestError: false, conflictPairs };
   const ctx = {
     API: '/api/bongos',
     state,
@@ -96,7 +97,10 @@ async function boot({ status = 200, fail = false, payload = { nodes: [], edges:
     },
   };
   const renderers = windowObj.OTBGoalsRender(ctx);
-  return { $: documentObj.getElementById, requests, state, renderers };
+  // The band card's renderer is the forest module's own export — goals-render.js
+  // reaches it through its private `forestRender`, so the test makes its own.
+  const card = windowObj.OTBGoalForestRender(ctx);
+  return { $: documentObj.getElementById, requests, state, renderers, card };
 }
 
 // ---- the honest states (ADR 0227) ---------------------------------------------
@@ -217,14 +221,105 @@ await test('renderDetail calls loadDependencyForest, beside loadGoalTasks, for t
   assert.match(RENDER_JS, /loadGoalTasks\(g\.id\);\s*\n\s*loadDependencyForest\(g\.id\);/);
 });
 
-await test('the section is its OWN full-width block, not squeezed into the three-column band', () => {
+// ---- the band card + the full view (task 1004738) ----------------------------
+
+const sectionOf = (html, id) => {
+  const start = html.indexOf(`<section id="${id}"`);
+  return start < 0 ? '' : html.slice(start, html.indexOf('</section>', start));
+};
+
+await test('the band\'s third column is the compact Dependencies card, where Conflicts was — no long block before Tasks', () => {
   const html = fs.readFileSync(path.join(HALL, 'goals.html'), 'utf8');
-  const bandAt = html.indexOf('class="scroll goal-band"');
-  const depsAt = html.indexOf('id="goal-deps-scroll"');
-  const tasksAt = html.indexOf('<h2 class="scroll__h">Tasks</h2>');
-  assert.ok(bandAt > -1 && depsAt > -1 && tasksAt > -1);
-  assert.ok(bandAt < depsAt && depsAt < tasksAt, 'band, then dependencies, then tasks');
-  assert.equal(/id="goal-deps-scroll"[\s\S]{0,400}goal-band__col/.test(html), false, 'not inside a band column');
+  const detail = sectionOf(html, 'goal-detail-view');
+  const cols = detail.split('class="goal-band__col"').slice(1);
+  assert.equal(cols.length, 3, 'still three columns');
+  assert.match(cols[2], /^\s*id="goal-deps-card"/, 'Dependencies takes the third slot');
+  assert.equal(/>Conflicts</.test(cols.join('')), false, 'no Conflicts column left in the band');
+  assert.equal(detail.includes('id="goal-deps-scroll"'), false, 'the forest is off the goal page');
+});
+
+await test('the full picture is #/goal/N/dependencies: the forest, then the whole conflict set; the old /conflicts lands there', () => {
+  const html = fs.readFileSync(path.join(HALL, 'goals.html'), 'utf8');
+  const view = sectionOf(html, 'goal-dependencies-view');
+  const depsAt = view.indexOf('id="goal-deps-scroll"');
+  const conflictsAt = view.indexOf('id="goal-conflicts-full"');
+  assert.ok(view.includes('id="goal-deps-back"') && depsAt > -1 && depsAt < conflictsAt, 'back link, forest, then conflicts');
+  assert.equal(sectionOf(html, 'goal-conflicts-view'), '', 'no separate conflicts view any more');
+  const page = read('goals-page.js');
+  assert.match(page, /dependencies: '#goal-dependencies-view'/);
+  assert.match(page, /\(dependencies\|conflicts\|members\|completion\)/);
+  assert.match(page, /mSub\[2\] === 'conflicts' \? 'dependencies'/, 'the inbox\'s /conflicts links keep working');
+  assert.match(RENDER_JS, /function renderConflicts\(\) \{[\s\S]*?forestRender\.renderDependencyCard\(\);/, 'the card re-renders when the conflicts land');
+});
+
+await test('the card states the shape, lists what to ship first, counts conflicts, and links to the full view', async () => {
+  const h = await boot({
+    payload: { nodes: [t(1, { title: 'Base' }), t(2), t(3), t(4, { title: 'Other root' }), t(5)], edges: [e(2, 1), e(3, 2), e(5, 4)] },
+    conflictPairs: [{ a: 2, b: 5 }, { a: 3, b: 5 }],
+  });
+  await h.renderers.loadDependencyForest(7);
+  assert.equal(h.$('goal-deps-card-count').hidden, false);
+  assert.equal(h.$('goal-deps-card-count').textContent, '5');
+  assert.equal(h.$('goal-deps-card-lede').textContent, '5 tasks linked by dependencies, in 2 chains.');
+  const body = h.$('goal-deps-card-body');
+  const rows = body.querySelectorAll('.gf-brief__row');
+  assert.deepEqual(rows.map((r) => r.querySelector('a').getAttribute('href')), ['#/task/1', '#/task/4']);
+  assert.deepEqual(rows.map((r) => r.querySelector('.gf-brief__n').textContent), ['unblocks 2', 'unblocks 1']);
+  const line = body.querySelector('.gf-brief__conflicts');
+  assert.equal(line.textContent, '2 file conflicts between open tasks.');
+  assert.match(line.className, /gf-brief__conflicts--live/);
+  const foot = h.$('goal-deps-card-foot');
+  assert.equal(foot.hidden, false);
+  assert.equal(foot.querySelector('a').getAttribute('href'), '#/goal/7/dependencies');
+  assert.equal(h.$('goal-deps-back').getAttribute('href'), '#/goal/7');
+});
+
+await test('on the goal page only the card is drawn — the forest waits for its own view, where its titles can be measured', async () => {
+  const h = await boot({ view: 'detail', payload: { nodes: [t(1), t(2)], edges: [e(2, 1)] } });
+  await h.renderers.loadDependencyForest(7);
+  assert.equal(h.$('goal-deps-body').querySelector('svg'), null, 'no forest drawn into the hidden view');
+  assert.equal(h.$('goal-deps-body').innerHTML, '');
+  assert.equal(h.$('goal-deps-card-lede').textContent, '2 tasks linked by dependencies, in 1 chain.');
+  h.state.view = 'dependencies';
+  h.renderers.renderDependencyForest();
+  assert.ok(h.$('goal-deps-body').querySelector('svg'), 'opening the view draws it');
+});
+
+await test('the card: no conflicts says so, unknown conflicts says nothing, and an empty goal has no door to an empty page', async () => {
+  const none = await boot({ payload: { nodes: [], edges: [] }, conflictPairs: [] });
+  await none.renderers.loadDependencyForest(7);
+  assert.match(none.$('goal-deps-card-lede').textContent, /No task in this goal depends on another/);
+  assert.equal(none.$('goal-deps-card-count').hidden, true);
+  assert.equal(none.$('goal-deps-card-body').querySelector('.gf-brief__conflicts').textContent, 'No file conflicts between open tasks.');
+  assert.equal(none.$('goal-deps-card-foot').hidden, true);
+
+  const unknown = await boot({ payload: { nodes: [], edges: [] }, conflictPairs: null });
+  await unknown.renderers.loadDependencyForest(7);
+  assert.equal(unknown.$('goal-deps-card-body').querySelector('.gf-brief__conflicts'), null, 'a failed or pending conflicts read draws no line, not a zero');
+
+  const onlyConflicts = await boot({ payload: { nodes: [], edges: [] }, conflictPairs: [{ a: 1, b: 2 }] });
+  await onlyConflicts.renderers.loadDependencyForest(7);
+  assert.equal(onlyConflicts.$('goal-deps-card-foot').hidden, false, 'conflicts alone still earn the full view');
+});
+
+await test('the card: while reading, and after a failed read, it says so — and a late conflicts list re-renders it', async () => {
+  const h = await boot({ fail: true });
+  const p = h.renderers.loadDependencyForest(7);
+  assert.equal(h.$('goal-deps-card-lede').textContent, 'Reading…');
+  await p;
+  assert.match(h.$('goal-deps-card-lede').textContent, /Couldn.t load this goal.s task dependencies/);
+  h.state.conflictPairs = [{ a: 1, b: 2 }];
+  h.card.renderDependencyCard();
+  assert.equal(h.$('goal-deps-card-body').querySelector('.gf-brief__conflicts').textContent, '1 file conflict between open tasks.');
+});
+
+await test('a "ship first" title is builder-authored text and never becomes markup in the card either', async () => {
+  const evil = '<img src=x onerror=alert(1)>';
+  const h = await boot({ payload: { nodes: [t(1, { title: evil }), t(2)], edges: [e(2, 1)] } });
+  await h.renderers.loadDependencyForest(7);
+  const body = h.$('goal-deps-card-body');
+  assert.equal(body.querySelector('img'), null);
+  assert.ok(body.textContent.includes(evil));
 });
 
 summary();