@bongos/core 1.21.175 → 1.21.177

package/scripts/bongos/find-untested.js

@@ -0,0 +1,371 @@
+#!/usr/bin/env node
+'use strict';
+// scripts/bongos/find-untested.js — list source modules that no test names, for the
+// newcomer "add a unit test" chore (task 1002458, from idea 1000574).
+//
+// WHY. The evergreen newcomer task `unit-test-pass` (scripts/bongos/newcomer-floor.templates.json)
+// used to carry a HARDCODED list of "untested" helpers. Every newcomer who completed it made
+// the list a little more wrong, and a blanket rename broke three of its five paths outright.
+// This script is the METHOD instead of the list: run it and it names candidates from the live
+// tree, so the task cannot decay.
+//
+// THE DEFINITION (decided at claim time; recorded on the task). A module is a candidate when
+// NO TEST FILE NAMES IT — no test requires/imports it, builds its path with path.join, or
+// spawns it. That is the "no dedicated test" definition. The stricter one, "unreachable from
+// any test at all", is reported alongside as the `reach` column rather than used as the
+// filter: measured in this repo it leaves only a handful of modules, most of them DB pollers,
+// so filtering on it would hand newcomers an empty list. `--unreachable` applies it anyway.
+//
+// THE TWO NAIVE SCANS THIS AVOIDS (both measured before building):
+//   - Matching on BASENAME ("does settings.js appear in any test?") falsely drops common-word
+//     modules — quality.js, settings.js, hierarchy.js match dozens of unrelated tests. So a
+//     reference only counts when it resolves to the module's full repo-relative path.
+//   - Scanning only literal `require('…')` misses the ~65 tests that reach their module
+//     through `require(path.join(ROOT, 'scripts', 'bongos', 'x.js'))`, a `const GOV = path.join(…)`
+//     prefix, or a spawned `node scripts/bongos/x.js`; that scan wrongly flagged the well-tested
+//     memory-map.js. So every path.join/resolve call is evaluated (through the file's own
+//     path constants) and every path-shaped string literal counts.
+//
+// PURITY IS A HEURISTIC, and the output says so. A module is marked impure when it, or a
+// module it statically requires, reaches Postgres (`pg` or a db*.js module), a subprocess or
+// the network — the propagation is what catches a helper that reaches the database through a
+// module doorway rather than a literal `pg` require. Filesystem use is shown but does not
+// exclude: a module may read files in its CLI half and still export pure helpers. A newcomer
+// still checks the helper they pick.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+
+// Where candidate modules live, and the directories never scanned for them.
+const SOURCE_ROOTS = ['scripts', 'src', 'modules'];
+const SKIP_DIRS = new Set(['node_modules', '.git', 'migrations', 'fixtures', 'vendor', 'public']);
+const CODE_EXT = /\.(?:c|m)?js$/;
+
+// ---- pure helpers ----------------------------------------------------------
+
+/** Is this repo-relative path a test file? A file under any `tests/` directory, or a
+ *  `*.test.js` beside its module (scripts/bongos/newcomer-floor.test.js is one). */
+function isTestPath(rel) {
+  const p = String(rel).split(path.sep).join('/');
+  return /(^|\/)tests\//.test(p) || /\.test\.(?:c|m)?js$/.test(p);
+}
+
+/** Normalize a path to repo-relative posix form, clamping any climb above the root to the
+ *  root itself. Returns '' for the root. */
+function normRel(p) {
+  const out = [];
+  for (const seg of String(p).split(/[\\/]+/)) {
+    if (!seg || seg === '.') continue;
+    if (seg === '..') out.pop();
+    else out.push(seg);
+  }
+  return out.join('/');
+}
+
+/** Directory of a repo-relative file path ('' at the root). */
+function dirOf(rel) {
+  const i = rel.lastIndexOf('/');
+  return i < 0 ? '' : rel.slice(0, i);
+}
+
+// A single argument of a path.join/resolve call, evaluated to a repo-relative string, or
+// null when it cannot be known. `first` lets an unknown leading identifier stand for the
+// repo root — a `ROOT`/`REPO` constant imported from a helper is the overwhelming case.
+function evalArg(arg, env, fileDir, first) {
+  const a = arg.trim();
+  const lit = /^(['"`])((?:\\.|(?!\1)[^\\])*)\1$/.exec(a);
+  if (lit) return lit[2].includes('${') ? null : lit[2];
+  if (a === '__dirname' || a === 'HERE' || a === '__here') return '/' + fileDir;
+  if (Object.prototype.hasOwnProperty.call(env, a)) return env[a] == null ? null : '/' + env[a];
+  if (first && /^[A-Za-z_$][\w$]*$/.test(a)) return '/';
+  return null;
+}
+
+// Evaluate the argument text of one path.join/resolve call to a repo-relative path.
+function evalJoin(argText, env, fileDir) {
+  const args = argText.split(',');
+  let acc = null;
+  for (let i = 0; i < args.length; i++) {
+    const v = evalArg(args[i], env, fileDir, i === 0);
+    if (v == null) return null;
+    if (v.startsWith('/')) acc = v.slice(1);
+    else acc = acc == null ? v : acc + '/' + v;
+  }
+  return acc == null ? null : normRel(acc);
+}
+
+const JOIN_RE = /path\.(?:join|resolve)\s*\(([^()]*)\)/g;
+const CONST_JOIN_RE = /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*path\.(?:join|resolve)\s*\(([^()]*)\)/g;
+const CONST_URL_RE = /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:path\.dirname\s*\(\s*)?fileURLToPath\s*\(\s*(?:new URL\s*\(\s*(['"])([^'"]*)\2\s*,\s*)?import\.meta\.url/g;
+const URL_RE = /new URL\s*\(\s*(['"])([^'"]+)\1\s*,\s*import\.meta\.url\s*\)/g;
+const STRING_RE = /(['"`])((?:\\.|(?!\1)[^\\\n])*)\1/g;
+
+/** Every repo-relative path a source text names: evaluated path.join/resolve calls (through
+ *  the file's own path constants), `new URL(…, import.meta.url)`, and path-shaped string
+ *  literals (relative ones resolved from the file's directory). Pure — it reads no files.
+ *  This is deliberately BROAD: it is how a test's reach is measured, and a test reaches its
+ *  module through any of these shapes. */
+function extractPathRefs(src, fileRel) {
+  const text = String(src);
+  const fileDir = dirOf(normRel(fileRel));
+  const env = {};
+  const refs = new Set();
+  let m;
+  CONST_URL_RE.lastIndex = 0;
+  while ((m = CONST_URL_RE.exec(text))) {
+    // fileURLToPath(import.meta.url) is the file itself; with dirname or a relative URL it
+    // is a directory. Either way the directory is the useful prefix.
+    env[m[1]] = m[3] ? normRel(fileDir + '/' + m[3]) : fileDir;
+  }
+  CONST_JOIN_RE.lastIndex = 0;
+  while ((m = CONST_JOIN_RE.exec(text))) env[m[1]] = evalJoin(m[2], env, fileDir);
+  JOIN_RE.lastIndex = 0;
+  while ((m = JOIN_RE.exec(text))) {
+    const v = evalJoin(m[1], env, fileDir);
+    if (v) refs.add(v);
+  }
+  URL_RE.lastIndex = 0;
+  while ((m = URL_RE.exec(text))) refs.add(normRel(fileDir + '/' + m[2]));
+  STRING_RE.lastIndex = 0;
+  while ((m = STRING_RE.exec(text))) {
+    const s = m[2];
+    if (!s || s.includes('${') || !/\.(?:c|m)?js$|\//.test(s) || /\s/.test(s) || /^[a-z]+:/i.test(s)) continue;
+    refs.add(s.startsWith('.') ? normRel(fileDir + '/' + s) : normRel(s));
+  }
+  return refs;
+}
+
+const REQUIRE_RE = /(?:require|import)\s*\(\s*(['"])([^'"]+)\1\s*\)|\bfrom\s+(['"])([^'"]+)\3/g;
+const REQUIRE_JOIN_RE = /require\s*\(\s*path\.(?:join|resolve)\s*\(([^()]*)\)\s*\)/g;
+
+/** The module specifiers a SOURCE file statically loads: bare package names as-is, and
+ *  in-repo paths (relative, or built with path.join from __dirname) as repo-relative paths
+ *  WITHOUT extension resolution. Narrower than extractPathRefs on purpose — this is the
+ *  require graph, and a path merely mentioned in a comment is not an edge. */
+function extractRequires(src, fileRel) {
+  const text = String(src);
+  const fileDir = dirOf(normRel(fileRel));
+  const env = {};
+  const out = { local: new Set(), packages: new Set() };
+  let m;
+  CONST_JOIN_RE.lastIndex = 0;
+  while ((m = CONST_JOIN_RE.exec(text))) env[m[1]] = evalJoin(m[2], env, fileDir);
+  REQUIRE_RE.lastIndex = 0;
+  while ((m = REQUIRE_RE.exec(text))) {
+    const spec = m[2] || m[4];
+    if (spec.startsWith('.')) out.local.add(normRel(fileDir + '/' + spec));
+    else out.packages.add(spec.replace(/^node:/, '').split('/')[0]);
+  }
+  REQUIRE_JOIN_RE.lastIndex = 0;
+  while ((m = REQUIRE_JOIN_RE.exec(text))) {
+    const v = evalJoin(m[1], env, fileDir);
+    if (v) out.local.add(v);
+  }
+  return out;
+}
+
+/** Resolve a reference against the set of known module paths the way Node would for a
+ *  local specifier: exact, then with .js/.mjs/.cjs, then as a directory's index.js.
+ *  Returns the module path or null. Full-path matching is what keeps a common-word
+ *  basename like settings.js from matching an unrelated module. */
+function resolveRef(ref, modules) {
+  if (!ref) return null;
+  for (const c of [ref, ref + '.js', ref + '.mjs', ref + '.cjs', ref + '/index.js']) {
+    if (modules.has(c)) return c;
+  }
+  return null;
+}
+
+/** Does this source export anything a test could call? CommonJS or ESM. */
+function hasExports(src) {
+  return /\bmodule\.exports\b|\bexports\.[A-Za-z_$]|^\s*export\s/m.test(String(src));
+}
+
+/** Rough count of exported names — a size hint for picking a newcomer-sized module. */
+function countExports(src) {
+  const text = String(src);
+  const names = new Set();
+  let m;
+  const objRe = /module\.exports\s*=\s*\{([\s\S]*?)\};?/g;
+  while ((m = objRe.exec(text))) {
+    for (const part of m[1].split(',')) {
+      const k = /^\s*(?:\.\.\.)?([A-Za-z_$][\w$]*)/.exec(part.replace(/\/\/.*$/gm, ''));
+      if (k) names.add(k[1]);
+    }
+  }
+  const dotRe = /\b(?:module\.)?exports\.([A-Za-z_$][\w$]*)\s*=/g;
+  while ((m = dotRe.exec(text))) names.add(m[1]);
+  const esmRe = /^\s*export\s+(?:async\s+)?(?:function\*?|const|let|class)\s+([A-Za-z_$][\w$]*)/gm;
+  while ((m = esmRe.exec(text))) names.add(m[1]);
+  return names.size;
+}
+
+const NETWORK_PKGS = new Set(['http', 'https', 'net', 'tls', 'undici', 'ws', 'dgram']);
+
+/** The impurity markers a single source shows on its own: 'postgres', 'subprocess',
+ *  'network' (hard — the module cannot be tested DB-free and offline) and 'filesystem'
+ *  (soft). `requires` is extractRequires' output for the same text. */
+function ownImpurity(src, requires) {
+  const text = String(src);
+  const hard = new Set();
+  const pk = requires.packages;
+  if (pk.has('pg')) hard.add('postgres');
+  if (pk.has('child_process')) hard.add('subprocess');
+  for (const p of pk) if (NETWORK_PKGS.has(p)) hard.add('network');
+  if (/(?:^|[^\w.])fetch\s*\(/.test(text)) hard.add('network');
+  for (const r of requires.local) if (/(?:^|\/|-)db(?:-[\w-]+)?(?:\.js)?$/.test(r)) hard.add('postgres');
+  return { hard, fs: pk.has('fs') || pk.has('fs/promises') };
+}
+
+/** Rank candidates for a newcomer: unreachable before indirectly-covered, pure before
+ *  filesystem-touching, then smallest first (a newcomer-sized module). */
+function rankCandidates(rows) {
+  return rows.slice().sort((a, b) =>
+    (a.reach === 'unreachable' ? 0 : 1) - (b.reach === 'unreachable' ? 0 : 1)
+    || (a.fs ? 1 : 0) - (b.fs ? 1 : 0)
+    || a.lines - b.lines
+    || a.path.localeCompare(b.path));
+}
+
+// ---- tree scan -------------------------------------------------------------
+
+function walk(relDir, out) {
+  let entries;
+  try { entries = fs.readdirSync(path.join(ROOT, relDir), { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    const rel = relDir ? relDir + '/' + e.name : e.name;
+    if (e.isDirectory()) {
+      if (!SKIP_DIRS.has(e.name) && !e.name.startsWith('public-') && !e.name.startsWith('.')) walk(rel, out);
+    } else if (CODE_EXT.test(e.name)) out.push(rel);
+  }
+}
+
+/** Scan the live tree and return every exported source module with its coverage, reach and
+ *  purity: [{ path, lines, exports, tested, reach, impure: [..], fs }]. `tested` is true
+ *  when some test file names the module directly; `reach` is 'direct' | 'indirect' |
+ *  'unreachable' (indirect = only loaded through another module a test names). */
+function scanTree() {
+  const files = [];
+  for (const r of SOURCE_ROOTS) walk(r, files);
+  walk('tests', files);
+  const tests = files.filter((f) => isTestPath(f) && !f.includes('/fixtures/'));
+  const sources = files.filter((f) => !isTestPath(f) && !f.includes('/fixtures/'));
+  const text = new Map();
+  for (const f of files) text.set(f, fs.readFileSync(path.join(ROOT, f), 'utf8'));
+  const modules = new Set(sources);
+
+  // The require graph and each module's own impurity.
+  const edges = new Map();
+  const own = new Map();
+  for (const f of sources) {
+    const req = extractRequires(text.get(f), f);
+    const local = new Set();
+    for (const r of req.local) { const t = resolveRef(r, modules); if (t) local.add(t); }
+    edges.set(f, local);
+    own.set(f, ownImpurity(text.get(f), req));
+  }
+
+  // Hard impurity propagates along the require graph (the "module doorway" case).
+  const impure = new Map();
+  function impurityOf(f, seen) {
+    if (impure.has(f)) return impure.get(f);
+    if (seen.has(f)) return own.get(f).hard;
+    seen.add(f);
+    const acc = new Set(own.get(f).hard);
+    for (const d of edges.get(f)) for (const x of impurityOf(d, seen)) acc.add(x);
+    seen.delete(f);
+    impure.set(f, acc);
+    return acc;
+  }
+
+  // Direct test references, then everything reachable from them.
+  const direct = new Set();
+  for (const t of tests) {
+    for (const r of extractPathRefs(text.get(t), t)) {
+      const hit = resolveRef(r, modules);
+      if (hit) direct.add(hit);
+    }
+    const req = extractRequires(text.get(t), t);
+    for (const r of req.local) { const hit = resolveRef(r, modules); if (hit) direct.add(hit); }
+  }
+  const reached = new Set(direct);
+  const queue = [...direct];
+  while (queue.length) {
+    for (const d of edges.get(queue.pop()) || []) if (!reached.has(d)) { reached.add(d); queue.push(d); }
+  }
+
+  const rows = [];
+  for (const f of sources) {
+    const src = text.get(f);
+    if (!hasExports(src)) continue;
+    rows.push({
+      path: f,
+      lines: src.split('\n').length,
+      exports: countExports(src),
+      tested: direct.has(f),
+      reach: direct.has(f) ? 'direct' : reached.has(f) ? 'indirect' : 'unreachable',
+      impure: [...impurityOf(f, new Set())].sort(),
+      fs: own.get(f).fs,
+    });
+  }
+  return rows;
+}
+
+// ---- CLI -------------------------------------------------------------------
+
+const USAGE = `usage: node scripts/bongos/find-untested.js [--unreachable] [--all] [--limit N] [--json]
+
+Lists source modules (scripts/, src/, modules/) that NO test file names, for the newcomer
+"add a unit test" task. Candidates come first when no test reaches them at all, then when
+they look pure, then smallest first.
+
+  --unreachable  only modules no test reaches even indirectly (the strict definition)
+  --all          include modules that look impure (Postgres, subprocess, network)
+  --limit N      how many to print (default 25; 0 = all)
+  --json         machine-readable rows
+
+Purity is a heuristic: check the helper you pick really is DB-free before testing it.`;
+
+function main(argv) {
+  if (argv.includes('--help') || argv.includes('-h')) { console.log(USAGE); return 0; }
+  const li = argv.indexOf('--limit');
+  const limit = li >= 0 ? parseInt(argv[li + 1], 10) : 25;
+  if (li >= 0 && !(limit >= 0)) { console.error('find-untested: --limit needs a number'); return 2; }
+  const all = scanTree();
+  let rows = all.filter((r) => !r.tested);
+  if (argv.includes('--unreachable')) rows = rows.filter((r) => r.reach === 'unreachable');
+  if (!argv.includes('--all')) rows = rows.filter((r) => r.impure.length === 0);
+  rows = rankCandidates(rows);
+  const shown = limit ? rows.slice(0, limit) : rows;
+  if (argv.includes('--json')) { console.log(JSON.stringify(shown, null, 2)); return 0; }
+  const untested = all.filter((r) => !r.tested).length;
+  console.log(`find-untested: ${all.length} exported modules scanned; ${untested} have no test naming them; `
+    + `${rows.length} match the filters.`);
+  if (!shown.length) { console.log('  (none — try --all, or strengthen a thin existing test instead)'); return 0; }
+  const w = Math.max(...shown.map((r) => r.path.length));
+  console.log(`  ${'module'.padEnd(w)}  lines  exports  reach        notes`);
+  for (const r of shown) {
+    const notes = [r.impure.length ? 'impure: ' + r.impure.join('+') : 'looks pure', r.fs ? 'uses fs' : ''].filter(Boolean).join(', ');
+    console.log(`  ${r.path.padEnd(w)}  ${String(r.lines).padStart(5)}  ${String(r.exports).padStart(7)}  ${r.reach.padEnd(11)}  ${notes}`);
+  }
+  if (rows.length > shown.length) console.log(`  … ${rows.length - shown.length} more (--limit 0 for all)`);
+  return 0;
+}
+
+if (require.main === module) process.exitCode = main(process.argv.slice(2));
+
+module.exports = {
+  isTestPath,
+  normRel,
+  extractPathRefs,
+  extractRequires,
+  resolveRef,
+  hasExports,
+  countExports,
+  ownImpurity,
+  rankCandidates,
+  scanTree,
+  main,
+};

package/scripts/bongos/fitness-checks-error-envelope.js

@@ -0,0 +1,134 @@
+// scripts/bongos/fitness-checks-error-envelope.js — Check 17: no route hand-rolls a
+// FLAT error (BV1 R03 / task 1990 / ADR 0116).
+//
+// Carved out of scripts/bongos/fitness.js by task 1003825 alongside the packaging pair,
+// for the headroom reason documented there. Self-contained: the scan needs only
+// CORE_ROOT / rel / walkJs / walkJsAllRoots from fitness-lib.js, and FLAT_ERROR_BASELINE
+// travels WITH the check rather than staying behind — the baseline and the gate that
+// reads it are one decision, and splitting them is how a ratchet quietly loses its floor.
+//
+// fitness.js requires the four public names straight back (checkErrorEnvelope,
+// scanFlatErrorSites, countFlatErrors, FLAT_ERROR_BASELINE — the last three are read by
+// the R04 sweep and its tests), so nothing outside this file changes shape.
+// stripCommentsForFlat stays PRIVATE here: it was never on fitness.js's exports, and
+// exporting it now to mirror the carve would be a new public name nothing consumes.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { CORE_ROOT, rel, walkJs, walkJsAllRoots } = require('./fitness-lib.js');
+// ============================================================================
+// Check 17 — no route hand-rolls a FLAT error (BV1 R03 / task 1990 / ADR 0116)
+// ============================================================================
+//
+// The error-envelope contract (ADR 0116) says every failure is the ONE envelope
+// `{error:{code,message,details}}`, emitted via res.fail() or a thrown ApiError
+// (the R02 middleware, task 1989). A hand-rolled flat error —
+// `res.status(n).json({ error: 'x' })` or `.json({ error })` — breaks the
+// contract: the caller gets a bare string where the envelope should be.
+//
+// RATCHET, not big-bang. The R04 sweep (task 1991) migrates the ~562 existing
+// sites; until it finishes they'd all "fail" a strict check, so this HOLDS THE
+// LINE: it fails only when the count rises ABOVE the committed baseline (a NEW
+// hand-rolled flat error), and nudges the baseline DOWN as the sweep shrinks it.
+// When the sweep reaches 0, FLAT_ERROR_BASELINE is 0 and any new flat error
+// hard-fails immediately. Detector is shared with the sweep + its test.
+const FLAT_ERROR_BASELINE = 0; // R04 sweep (task 1991) landed the surface at 0 — the gate is now hard-zero: any new hand-rolled flat error fails the build immediately.
+// A flat error is a `.json({ … })` whose FIRST key is `error` with a value that
+// is NOT an object literal (a string/var/shorthand). The envelope's nested
+// `error: { … }` and `.json(envelope(…))` deliberately do NOT match.
+// The `(?!\s*\{)` lookahead is whitespace-aware: without the inner `\s*` the
+// preceding `\s*` backtracks to zero and the lookahead is tested at the space in
+// `error: {`, so the compliant nested envelope was wrongly flagged (task 2029).
+const FLAT_ERROR_VALUE_RE = /\.json\(\s*\{\s*error\s*:\s*(?!\s*\{)/g; // error: 'x' | error: code
+const FLAT_ERROR_SHORTHAND_RE = /\.json\(\s*\{\s*error\s*[,}]/g;   // { error } | { error, … }
+
+// Strip // line comments + /* */ block comments AND blank out string/template
+// contents (keeping the delimiters) so neither a DOC example of the anti-pattern
+// — e.g. the res.fail() usage note in middleware/error-envelope.js — nor a
+// pattern quoted inside a string literal is counted as a real flat error once
+// the gate is hard-zero (task 1991). Real flat errors are unaffected: in
+// `res.status(404).json({ error: 'x' })` the `.json({ error:` the detector keys
+// on is CODE (outside the string), so blanking the `'x'` content still matches.
+function stripCommentsForFlat(src) {
+  let out = '';
+  let i = 0;
+  let quote = null;
+  while (i < src.length) {
+    const c = src[i];
+    const d = src[i + 1];
+    if (quote) {
+      // inside a string/template: drop content, keep only the closing delimiter
+      if (c === '\\') { i += 2; continue; }
+      if (c === quote) { out += c; quote = null; }
+      i++; continue;
+    }
+    if (c === '"' || c === "'" || c === '`') { quote = c; out += c; i++; continue; }
+    if (c === '/' && d === '/') { while (i < src.length && src[i] !== '\n') i++; continue; }
+    if (c === '/' && d === '*') { i += 2; while (i < src.length && !(src[i] === '*' && src[i + 1] === '/')) i++; i += 2; continue; }
+    out += c; i++;
+  }
+  return out;
+}
+
+function countFlatErrors(text) {
+  const code = stripCommentsForFlat(text);
+  return (code.match(FLAT_ERROR_VALUE_RE) || []).length
+       + (code.match(FLAT_ERROR_SHORTHAND_RE) || []).length;
+}
+
+// scanFlatErrorSites() — per-file flat-error counts across the API surface
+// (core src/bongos + every module), skipping tests. Shared by the check below, the
+// R04 codemod, and tests/api_error_envelope_buildcheck.mjs.
+function scanFlatErrorSites() {
+  const seen = new Set();
+  const byFile = {};
+  let total = 0;
+  const files = [
+    ...walkJs(path.join(CORE_ROOT, 'src', 'bongos')),
+    ...walkJsAllRoots('modules'),
+  ];
+  for (const abs of files) {
+    const relFile = rel(abs);
+    if (seen.has(relFile)) continue;
+    seen.add(relFile);
+    if (relFile.includes('/tests/') || relFile.endsWith('.test.js')) continue;
+    const n = countFlatErrors(fs.readFileSync(abs, 'utf8'));
+    if (n) { byFile[relFile] = n; total += n; }
+  }
+  return { total, byFile };
+}
+
+function checkErrorEnvelope() {
+  const { total, byFile } = scanFlatErrorSites();
+  const violations = [];
+  const warnings = [];
+  if (total > FLAT_ERROR_BASELINE) {
+    const top = Object.entries(byFile).sort((a, b) => b[1] - a[1]).slice(0, 8)
+      .map(([f, n]) => `${f} (${n})`).join(', ');
+    violations.push(
+      `${total} hand-rolled flat-error sites — ABOVE the ${FLAT_ERROR_BASELINE} baseline. A new route emitted a flat \`res.status(n).json({error:'x'})\` instead of \`res.fail('x', n)\` / \`throw new ApiError('x')\` (ADR 0116). Top files: ${top}. Use the envelope helper (src/bongos/middleware/error-envelope.js).`
+    );
+  } else if (total < FLAT_ERROR_BASELINE) {
+    warnings.push(
+      `${total} flat-error sites — BELOW the ${FLAT_ERROR_BASELINE} baseline. The sweep tightened; lower FLAT_ERROR_BASELINE to ${total} in fitness.js so the ratchet can't slip back (BV1 R04 / task 1991).`
+    );
+  }
+  return {
+    name: 'no route hand-rolls a flat error (ADR 0116 / R03)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings,
+    note: `≤ ${FLAT_ERROR_BASELINE} flat \`.json({error:'…'})\` sites (ratchet → 0 as the R04 sweep lands); currently ${total}. New failures must use res.fail()/ApiError (the R02 envelope).`,
+  };
+}
+
+module.exports = {
+  checkErrorEnvelope,
+  scanFlatErrorSites,
+  countFlatErrors,
+  FLAT_ERROR_BASELINE,
+};