@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/module-assess-security.js

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+// scripts/bongos/module-assess-security.js — the Security part of a module's
+// assessment: a pass/fail GATE over one published store version, recorded as a
+// module_assessment_signals row (task 1003792; ADR 0343 D2; table from core_265).
+//
+// WHY a gate and not a score. ADR 0343 D2: a version that fails the security
+// check is not listed, whatever else it scores, and security is never averaged
+// in — so a module cannot buy back a vulnerability with good tests. The outcome
+// is therefore only ever passed / failed, or not_scored when the check could not
+// be completed (which is NOT a pass: a gate that cannot run must not open).
+//
+// The check reuses what the project already enforces rather than re-typing it:
+//   1. the publish denylist — module-artifact.js deniedFiles (the repo-wide
+//      matchesDeny list + credential-named files; ADR 0107 §4). Publish already
+//      refuses these; re-checking here means a rule added later still reaches
+//      versions published before it.
+//   2. dependency SOURCES — every entry in module.json `dependencies` (ADR 0138)
+//      must be a plain registry package name with a plain semver range or dist-
+//      tag. That is an ALLOWLIST (registrySpec below), deliberately stricter than
+//      a list of bad protocols: a git/http/file, aliased or GitHub-shorthand spec
+//      — or anything else unrecognised — installs code from somewhere nobody
+//      vetted, and fails the gate. (It mirrors the artifact-scan floor's grading,
+//      but a core script may not require a module's files, so it is its own
+//      small rule.) Floating ranges and wildcards are only noted.
+//   3. KNOWN VULNERABILITIES in those dependencies — only when every spec passed
+//      check 2, so nothing a module names is ever fetched from a place of its
+//      choosing and no `file:` path is ever resolved on this host. npm resolves the ranges in a
+//      throwaway directory (--package-lock-only --ignore-scripts: registry
+//      metadata only, no package code downloaded or run), then `npm audit`; any
+//      high or critical advisory fails the gate (the threshold scripts/security/
+//      dep-audit.js uses for the core, whose parser this reuses).
+// And one input that is reported, never failed on: the `maintenance` posture
+// (ADR 0166). "Undeclared", "deprecated" or "orphaned" is something a buyer
+// should see, but it is upkeep, not a vulnerability — that call is recorded in
+// the row's detail so the hall (task 1003799) can surface it.
+//
+// Nothing here executes the module's own code, so unlike module-assess-tests.js
+// this is safe to run on the control plane.
+//
+//   node scripts/bongos/module-assess-security.js <store_module_versions.id>   run + record
+//   node scripts/bongos/module-assess-security.js --dir modules/<key>          dry run (prints; no DB)
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFile } = require('node:child_process');
+const { deniedFiles, verifyModuleArtifact } = require('./module-artifact');
+const { extractNpmFindings } = require('../security/dep-audit');
+
+const AUDIT_TIMEOUT_MS = 120_000;
+// npm is a .cmd shim on Windows, which execFile cannot start without a shell; go
+// through cmd.exe explicitly rather than shell:true (the args are fixed constants).
+const npmCommand = (args) => (process.platform === 'win32'
+  ? ['cmd.exe', ['/d', '/s', '/c', 'npm', ...args]]
+  : ['npm', args]);
+
+// Run one npm command in `cwd`; resolve { ok, stdout, stderr, error }. Never rejects.
+function npmRun(args, cwd, { exec = execFile, timeoutMs = AUDIT_TIMEOUT_MS } = {}) {
+  return new Promise((resolve) => {
+    const [cmd, argv] = npmCommand(args);
+    exec(cmd, argv, { cwd, timeout: timeoutMs, maxBuffer: 32 * 1024 * 1024, windowsHide: true },
+      (err, stdout, stderr) => resolve({ err, stdout: String(stdout || ''), stderr: String(stderr || '') }));
+  });
+}
+
+// Audit a dependency map { name: range } for known high/critical advisories.
+// Resolves { ok: true, findings } or { ok: false, reason } when npm could not
+// resolve or audit (offline, unknown package, npm missing) — the caller treats
+// that as not_scored, never as a pass.
+async function auditDependencies(deps, { exec, timeoutMs } = {}) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'module-assess-security-'));
+  try {
+    fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name: 'module-assess-audit', private: true, version: '0.0.0', dependencies: deps }));
+    const lock = await npmRun(['install', '--package-lock-only', '--ignore-scripts', '--no-audit', '--no-fund'], dir, { exec, timeoutMs });
+    if (lock.err || !fs.existsSync(path.join(dir, 'package-lock.json'))) {
+      return { ok: false, reason: 'npm could not resolve the declared dependencies' };
+    }
+    // npm audit exits 1 when it finds anything; the JSON on stdout is the answer either way.
+    const audit = await npmRun(['audit', '--json'], dir, { exec, timeoutMs });
+    let parsed;
+    try { parsed = JSON.parse(audit.stdout || ''); } catch { return { ok: false, reason: 'npm audit produced no readable report' }; }
+    if (parsed && parsed.error) return { ok: false, reason: 'npm audit could not reach the advisory database' };
+    return { ok: true, findings: extractNpmFindings(parsed) };
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// npm's package-name rule (scoped or not, lowercase, no path segments).
+const NPM_NAME_RE = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+// A semver range: versions, x/* wildcards, ^ ~ comparators, hyphen and || unions,
+// prerelease/build suffixes. No ':' '/' '#' '@' — so no protocol, path, alias or ref.
+const RANGE_RE = /^[0-9A-Za-z.*^~<>=|\s+-]+$/;
+const DIST_TAGS = new Set(['latest', 'next']);
+
+// Grade one declared dependency. { ok: false } means it would install from
+// somewhere other than the public registry (or cannot be read as a registry
+// spec): the gate fails and it is never handed to npm. { ok: true, kind } is a
+// registry spec; kind names how much the registry decides at install time.
+function registrySpec(name, spec) {
+  const s = String(spec).trim();
+  if (!NPM_NAME_RE.test(name)) return { ok: false, kind: 'invalid package name' };
+  if (DIST_TAGS.has(s) || s === '*' || s === '' || /^[xX]$/.test(s)) return { ok: true, kind: 'wildcard' };
+  if (/^[a-z+]+:/i.test(s)) return { ok: false, kind: 'non-registry source' };
+  // Every whitespace/||-separated token must start with a comparator or a digit/x.
+  const tokens = s.split(/\s*\|\|\s*|\s+/).filter(Boolean);
+  if (!RANGE_RE.test(s) || !tokens.every((t) => t === '-' || /^(?:[\^~]|[<>]=?|=)?\s*[0-9xX*]/.test(t))) {
+    return { ok: false, kind: 'not a registry range' };
+  }
+  if (/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(s)) return { ok: true, kind: 'pinned' };
+  return { ok: true, kind: 'floating range' };
+}
+
+// The maintenance posture as a buyer would read it (ADR 0166).
+function maintenancePosture(moduleJson) {
+  const m = moduleJson && moduleJson.maintenance;
+  return m && typeof m.status === 'string' ? m.status : 'undeclared';
+}
+
+// The gate over one version's files ([{ path, buf }], module-relative) and its
+// parsed module.json. Returns the signal fields { outcome, score, sample_size,
+// reason, detail }. `audit` is injectable so tests need no network.
+async function assessSecurity(key, files, moduleJson, { audit = auditDependencies } = {}) {
+  const failures = [];
+  const notes = [];
+
+  const denied = deniedFiles(key, files.map((f) => f.path));
+  if (denied.length) failures.push({ check: 'denylist', files: denied });
+
+  const deps = (moduleJson && moduleJson.dependencies) || {};
+  const names = Object.keys(deps).sort();
+  const sources = [];
+  for (const name of names) {
+    const graded = registrySpec(name, deps[name]);
+    const entry = { package: name.slice(0, 214), spec: String(deps[name]).slice(0, 200), kind: graded.kind };
+    if (!graded.ok) sources.push(entry);
+    else if (graded.kind === 'wildcard') notes.push({ check: 'dependency_wildcard', ...entry });
+    else if (graded.kind === 'floating range') notes.push({ check: 'dependency_range', ...entry });
+  }
+  if (sources.length) failures.push({ check: 'dependency_source', dependencies: sources });
+
+  // Audit only an all-registry list: a failed source already fails the gate, and
+  // handing it to npm would make this host fetch (or resolve a file: path) of the
+  // module's choosing.
+  let advisories = [];
+  if (names.length && !sources.length) {
+    const a = await audit(deps);
+    if (!a.ok) {
+      return {
+        outcome: 'not_scored', score: null, sample_size: names.length,
+        reason: `the dependency audit could not run: ${a.reason}`,
+        detail: { failures, notes, maintenance: maintenancePosture(moduleJson) },
+      };
+    }
+    advisories = a.findings.map((f) => ({ package: f.package, severity: f.severity, id: f.id, summary: f.summary, fix: f.fix }));
+    if (advisories.length) failures.push({ check: 'vulnerable_dependency', advisories });
+  }
+
+  const maintenance = maintenancePosture(moduleJson);
+  if (maintenance !== 'maintained' && maintenance !== 'core-maintained') {
+    notes.push({ check: 'maintenance', status: maintenance });
+  }
+
+  const detail = { failures, notes, maintenance, dependencies_checked: names.length };
+  if (failures.length) {
+    return { outcome: 'failed', score: null, sample_size: names.length, reason: `failed: ${failures.map((f) => f.check).join(', ')}`, detail };
+  }
+  return {
+    outcome: 'passed', score: null, sample_size: names.length,
+    reason: names.length ? `passed: ${names.length} dependency(ies) from the registry, no high or critical advisory` : 'passed: no denied files and no dependencies',
+    detail,
+  };
+}
+
+// Append one Security row. Never UPDATEs (core_265 is append-only).
+async function insertSecuritySignal(versionId, s, { db }) {
+  const { rows: [row] } = await db.query(
+    `INSERT INTO module_assessment_signals (version_id, part, outcome, score, sample_size, reason, detail)
+     VALUES ($1, 'security', $2, $3, $4, $5, $6)
+     RETURNING id, version_id, part, outcome, score, sample_size, reason, measured_at`,
+    [versionId, s.outcome, s.score, s.sample_size, s.reason, JSON.stringify(s.detail || {})]);
+  return row;
+}
+
+// Read and verify one published version, run the gate, record the result. A
+// tarball that is missing or fails verification is not_scored — the gate could
+// not be run, so it stays closed.
+async function recordSecuritySignal(versionId, { db, storeDir, audit } = {}) {
+  const pool = db || require('../../src/bongos/pool').pool;
+  const { versionArtifactFile } = require('../../src/bongos/module-store');
+  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 tgz = await fs.promises.readFile(versionArtifactFile(ver, storeDir ? { dir: storeDir } : {}));
+    const v = await verifyModuleArtifact(tgz, { key: ver.module_key, includeFiles: true });
+    if (v.ok) {
+      signal = await assessSecurity(ver.module_key, v.files, v.moduleJson, { audit });
+    } else if (v.code === 'denied_content') {
+      signal = { outcome: 'failed', score: null, sample_size: null, reason: 'failed: denylist', detail: { failures: [{ check: 'denylist' }] } };
+    } else {
+      signal = { outcome: 'not_scored', score: null, sample_size: null, reason: `the tarball failed verification (${v.code})`, detail: {} };
+    }
+  } catch (e) {
+    signal = { outcome: 'not_scored', score: null, sample_size: null, reason: `the check could not run (${e.code || 'error'})`, detail: {} };
+  }
+  const row = await insertSecuritySignal(ver.id, signal, { db: pool });
+  return { ok: true, version: ver, signal: row };
+}
+
+function readModuleDir(dir) {
+  const out = [];
+  const walk = (rel) => {
+    for (const e of fs.readdirSync(path.join(dir, rel), { withFileTypes: true })) {
+      if (e.name === 'node_modules' || e.name === '.git') continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(r);
+      else if (e.isFile()) out.push({ path: r, buf: fs.readFileSync(path.join(dir, r)) });
+    }
+  };
+  walk('');
+  return out;
+}
+
+async function main(argv) {
+  const i = argv.indexOf('--dir');
+  if (i !== -1) {
+    const dir = path.resolve(argv[i + 1] || '');
+    const moduleJson = JSON.parse(fs.readFileSync(path.join(dir, 'module.json'), 'utf8'));
+    console.log(JSON.stringify(await assessSecurity(moduleJson.key, readModuleDir(dir), moduleJson), null, 2));
+    return 0;
+  }
+  const id = argv[0];
+  if (!/^\d+$/.test(String(id || ''))) {
+    console.error('usage: node scripts/bongos/module-assess-security.js <store_module_versions.id> | --dir modules/<key>');
+    return 2;
+  }
+  const res = await recordSecuritySignal(id);
+  if (!res.ok) { console.error(res.message); return 1; }
+  const s = res.signal;
+  console.log(`${res.version.module_key} ${res.version.version}: security ${s.outcome} — ${s.reason} (signal ${s.id})`);
+  await require('./module-assess-score').printRecomposed(res.version.id); // new data re-composes the score (task 1003794)
+  return 0;
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2)).then((code) => process.exit(code), (e) => { console.error(e.stack || e.message); process.exit(1); });
+}
+
+module.exports = { assessSecurity, auditDependencies, recordSecuritySignal, insertSecuritySignal, maintenancePosture, registrySpec };

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

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

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

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+// scripts/bongos/module-assess-version.js — re-assess a store version when it is
+// published: record Tests as pending, run the Security gate, compose the score
+// (task 1003794; ADR 0343; tables from core_265).
+//
+// WHY. A new version is a new thing to judge, so the store's publish route queues
+// 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
+// composed (module-assess-score.js). Install, Reliability and Tester feedback
+// arrive later from their own tasks; each recompose picks them up.
+//
+// The route goes through queueAssessment, so the web process runs one assessment
+// at a time (the gate's npm resolve + audit can take two minutes) and holds at most
+// QUEUE_MAX waiting; past that a publish is logged as not assessed, and the CLI
+// below re-runs it. This file is apart from the composer so the signal CLIs can
+// recompose without a require cycle (composer <- security, tests, this).
+//
+//   node scripts/bongos/module-assess-version.js <store_module_versions.id>   assess + print
+
+const { recomposeScore } = require('./module-assess-score');
+
+// Re-assess one version (on publish): Tests pending, the Security gate, Docs, then
+// 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, dispatchTests } = {}) {
+  const pool = db || require('../../src/bongos/pool').pool;
+  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}` };
+
+  // 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(
+    `INSERT INTO module_assessment_signals (version_id, part, outcome, score, sample_size, reason, detail)
+     SELECT $1::bigint, 'tests', 'pending', NULL, NULL, $2::text, '{}'::jsonb
+      WHERE NOT EXISTS (SELECT 1 FROM module_assessment_signals WHERE version_id = $1::bigint AND part = 'tests')`,
+    [ver.id, 'waiting for the separate test environment: a published module\'s tests never run on the control plane']);
+  const record = recordSecurity || require('./module-assess-security').recordSecuritySignal;
+  const security = await record(ver.id, { db: pool });
+  const docs = await (recordDocs || require('./module-assess-docs').recordDocsSignal)(ver.id, { db: pool });
+  const composed = await recomposeScore(ver.id, { db: pool });
+  return { ok: true, version: ver, security: security && security.signal, docs: docs && docs.signal, score: composed.score };
+}
+
+// One assessment at a time in this process, at most QUEUE_MAX waiting. Resolves
+// at once with whether the version was queued; a failed assessment is logged and
+// never stops the next one. `run` is injectable for tests.
+const QUEUE_MAX = 20;
+let tail = Promise.resolve();
+let waiting = 0;
+function queueAssessment(versionId, { log = console, run = (id) => module.exports.assessVersion(id) } = {}) {
+  if (waiting >= QUEUE_MAX) {
+    log.warn({ versionId }, `assessment queue full (${QUEUE_MAX} waiting): version not assessed; run module-assess-version.js ${versionId}`);
+    return false;
+  }
+  waiting += 1;
+  tail = tail.then(() => run(versionId))
+    .catch((e) => { log.error({ versionId, err: e && e.message }, 'assessment after publish failed'); })
+    .finally(() => { waiting -= 1; });
+  return true;
+}
+
+async function main(argv) {
+  const id = argv[0];
+  if (!/^\d+$/.test(String(id || ''))) {
+    console.error('usage: node scripts/bongos/module-assess-version.js <store_module_versions.id>');
+    return 2;
+  }
+  const res = await assessVersion(id);
+  if (!res.ok) { console.error(res.message); return 1; }
+  console.log(`version ${id}: ${res.score.formula}`);
+  return 0;
+}
+
+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 = { assessVersion, queueAssessment, QUEUE_MAX };