@bongos/core 1.19.910 → 1.19.911

package/modules/ideas/routes/inbox.js

@@ -52,6 +52,10 @@ const { completenessScore, weakestSectionPayload, scoreFieldValues } = require('
 // The trusted tier, spelled once (task 1003197 (D)) — routing.js owns METIC_PLUS
 // and already names 'criterion-proposal' in NEVER_ROUTE_KINDS.
 const { mayProposeCriterion, METIC_PLUS } = require('../routing');
+// "Gravity" — the landing verdict read BEFORE the write (task 1004083, BV2.R02).
+// Read-only and never-throwing; it calls the same matrix the capture calls so the
+// composer can state the outcome instead of implying one. See ../landing-preview.js.
+const { previewLanding } = require('../landing-preview');
 // task 1003208: structured logging (pino via the doorway) — was console.*.
 const log = api.logger('ideas');
 const { validateOrRespond, LIMITS, parseId } = api;
@@ -514,6 +518,49 @@ module.exports = function buildInboxRouter() {
     const { score, fields } = scoreFieldValues(req.body.field_values, templateKey ? { templateKey } : undefined);
     return res.json({ score, fields, template_key: templateKey || null });
   }, { errorCode: 'score_failed' }));
+  // POST /inbox/preview-landing — GRAVITY, MADE VISIBLE (task 1004083, BV2.R02).
+  //
+  // What pressing "File it" would do, without doing it. The composer draws one
+  // line from this so a filer can see which goal will catch the thought, change
+  // it, or deliberately let it float — the criterion's done-when, read literally.
+  //
+  // A DRY RUN IN THE SHAPE OF /inbox/score DIRECTLY ABOVE: same POST-with-a-body
+  // reason (the draft is the input, not an id), same "a half-formed draft is a
+  // legal state" contract. It differs in one way worth naming, because the file
+  // header above claims /score is pure: this one READS (the goal row, the
+  // building version). It still WRITES NOTHING — see ../landing-preview.js, which
+  // calls `currentBuildingVersionId` and deliberately never `ensureMaintenanceGoal`,
+  // so previewing a homeless bug cannot mint a goal as a side effect of typing.
+  //
+  // THE RANK AND THE VECTOR ARE NOT READ FROM THE BODY, exactly as POST /inbox
+  // refuses to read them: the rank comes off the authenticated builder and the
+  // vector is hardcoded to 'api'. A preview is only worth having if it is the
+  // same question the capture will be asked — one that answered a rank the filer
+  // does not hold would teach them a landing they cannot have.
+  //
+  // NEVER A 4xx FOR A DRAFT. Only the input SHAPE is validated; an unknown kind,
+  // an absent title, a goal that vanished all come back as `outcome: null`
+  // ("nothing to say yet"), because a composer redrawing on every keystroke must
+  // degrade to silence rather than to a red error under a half-typed thought.
+  //
+  // rank: any-builder — it answers only about the caller's own prospective
+  // filing, and filing itself is open to every rank.
+  router.post('/inbox/preview-landing', api.requireBuilder, api.asyncHandler('POST /inbox/preview-landing', async (req, res) => {
+    if (validateOrRespond(req, res, {
+      goal_id: { type: 'integer', min: 1 },
+      kind: { type: 'string', maxLength: 64 },
+      grade: { type: 'string', maxLength: 16 },
+    })) return;
+    const body = req.body || {};
+    const verdict = await previewLanding({
+      goalId: body.goal_id ?? null,
+      kind: body.kind ?? null,
+      grade: body.grade ?? null,
+      filerRank: req.builder?.rank ?? null,
+      vector: 'api',
+    });
+    return res.json(verdict);
+  }, { errorCode: 'preview_landing_failed' }));
   // GET /inbox/sparks — THE SPARK QUEUE (task 1002921 / BV1.R145, goal 1000062).
   //
   // Big Idea Sparks awaiting development: the ideator craft's pickup surface,

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.910",
+  "version": "1.19.911",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.910",
+      "version": "1.19.911",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.910",
+  "version": "1.19.911",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/api-alias-caller-scan.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+'use strict';
+// api-alias-caller-scan.js — the detector behind the lowercase `/api/gds` CALLER ratchet
+// (task 1004064, from idea 1001030; the sibling of gds-literal-scan.js).
+//
+// WHY THIS EXISTS. Task 1003707 (criterion C3e of goal 1000073) moved 665 in-repo callers off the
+// permanent `/api/gds` alias onto the canonical `/api/bongos`. The ratchet that already guards the
+// rename, `legacy_gds_literals`, is CASE-SENSITIVE on the shouting acronym — deliberately, because
+// `GDS` is the word a newcomer trips over. So that metric read 1135 before the sweep and 1135
+// after it, and it was right to: the alias is spelled in lowercase.
+//
+// The consequence is the gap this file closes. The lowercase spelling is invisible to CI in BOTH
+// directions: the 665-caller sweep earned no credit, and — the half that matters — a caller written
+// against `/api/gds` tomorrow moves no number and reds no build. 1003707's own session log says it
+// plainly: "the 665 will quietly grow back". `tests/api_alias_exceptions.mjs` pins the callers that
+// were deliberately LEFT behind and why, but it polices the exceptions, not new offenders. That is
+// a ratchet's job.
+//
+// WHY A COUNT AND NOT ZERO. Every remaining occurrence has a reason, and most of them are reasons
+// that will never expire — the OAuth callbacks are registered in GitHub's and Discord's app
+// settings, the uptime poller is the one production caller proving the alias still answers, and
+// tests are what keep it exercised in CI. A zero-rule would demand deleting things that must not be
+// deleted. So this holds the line the same way its sibling does: the number may fall, never rise.
+//
+// WHAT IS NEVER COUNTED, and why each one. The exclusion list is not invented here — it is
+// 1003707's own worked-out list, transcribed from docs/session-logs/2026-09-16-task-1003707-api-gds-callers.md
+// so that a future move has to argue with a stated reason rather than with a leftover:
+//
+//   1. THE ALIAS CONTRACT (path-excluded). api-prefix.js and api-path-404.js ARE the alias; they
+//      cannot name it less often than they do.
+//   2. THE PINNED OAUTH CALLBACKS (path-excluded). routes/auth.js, provisioning.js and the scripts
+//      + skills that register the same callback for a new instance. These paths live in the GitHub
+//      and Discord app settings; a repo-only change silently breaks sign-in.
+//   3. THE LIVE PROOF (path-excluded). uptime-poller.js and smoke-gds.js exercise the alias on
+//      purpose — if nothing calls it, its eventual breakage is found by a user rather than by us.
+//      Note fitness-ratchets.js belongs here too: it is the GATE, and its builder-facing hint has
+//      to spell the alias out to tell anyone what they tripped over.
+//   4. THE RENAME GUARDRAILS (path-excluded). rename-history-check.js, rename-ledger-prose.js,
+//      gds-literal-scan.js, codemod-rename-src-gds.js, fitness-ratchets.js and THIS FILE name the
+//      old path because that is what they are for. Same principle as GDS_RULE_FILES next door: a
+//      gate that cannot state its own rule cannot explain itself.
+//   5. tests/ (path-excluded). Tests are what keeps the alias exercised in CI. Moving them off it
+//      would retire the alias by accident.
+//   6. docs/ (path-excluded) — a DELIBERATE SCOPE CALL, not an oversight. It is the largest
+//      remaining bucket (~320) and it is where rename-history-check's per-file floors live, so a
+//      docs pass has to separate the record of what we used to call it from instructions that
+//      still teach the old spelling. 1004064's own brief says to treat docs as out of scope and
+//      file it rather than widen the task; filed as the follow-up named in that task's session log.
+//   7. MIGRATIONS + THE FROZEN RECORD (path-excluded). Same rule as the sibling detector: an
+//      applied migration renamed is an applied migration re-run, and a rewritten ADR destroys the
+//      evidence that the words changed.
+//   8. A LINE THAT IS ABOUT THE ALIAS (line-excluded). Any line that ALSO names `/api/bongos`, or
+//      carries the words alias / legacy / permanent / forever, is commentary on the alias rather
+//      than a caller of it. This is the same rule 1003707's codemod used to decide what to leave,
+//      so the ratchet and the sweep agree by construction.
+//   9. CAPTURED FIXTURES (path-excluded). scripts/hall-preview/fixtures/*.json are snapshots of
+//      real API responses; rewriting one would make the fixture misreport what the server returned.
+//
+// Usage:
+//   node scripts/gds/api-alias-caller-scan.js            # count + the top offending files
+//   node scripts/gds/api-alias-caller-scan.js --files    # every file with its count
+//   node scripts/gds/api-alias-caller-scan.js --json
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+
+// The alias, lowercase — the whole point of this detector, since its sibling is case-sensitive on
+// the shouting form and therefore blind to exactly this spelling.
+const ALIAS = '/api/gds';
+const ALIAS_RE = /\/api\/gds/g;
+
+// The canonical prefix. A line naming BOTH is commentary on the alias, not a caller of it.
+const CANONICAL = '/api/bongos';
+
+// Path exclusions, matched against the repo-relative path (forward slashes), at any depth.
+// Every entry maps to a numbered reason in the header above — keep them in step.
+const ALIAS_EXCLUDED_PATHS = [
+  // 1. the alias contract
+  /^src\/bongos\/api-prefix\.js$/,
+  /^src\/bongos\/api-path-404\.js$/,
+  // 2. the pinned OAuth callbacks + everything that registers them for a new instance
+  /^src\/bongos\/routes\/auth\.js$/,
+  /^modules\/provisioning\/provisioning\.js$/,
+  /^scripts\/gds\/(onboard|provision-net|dev|login)\.js$/,
+  /^modules\/lifecycle\/kickoff-checklist\.js$/,
+  /^modules\/public-landing\/public\/projects\.html$/,
+  /^\.claude\/skills\/new-project\/SKILL\.md$/,
+  // 3. the live proof that the alias still answers
+  /^src\/bongos\/uptime-poller\.js$/,
+  /^scripts\/gds\/smoke-gds\.js$/,
+  // 4. the rename guardrails — they name the old path on purpose
+  /^scripts\/gds\/(rename-history-check|rename-ledger-prose|gds-literal-scan|codemod-rename-src-gds|api-alias-caller-scan|fitness-ratchets)\.js$/,
+  /^config\/(fitness-baselines|rename-history-baseline)\.json$/,
+  // 5. tests keep the alias exercised in CI — the repo's own two spellings, `tests/` at the root
+  //    and a module's `tests/` or `test/` dir. Deliberately NOT a blanket `\.mjs$`: three .mjs
+  //    files are not tests (clients/bongos-client/index.mjs and its example, scripts/status-probe.mjs)
+  //    and the client is exactly the kind of caller this ratchet exists to police.
+  /(^|\/)tests?\//,
+  // 6. docs are a separate pass (scope call, see the header)
+  /(^|\/)docs\//,
+  // 7. migrations + the frozen record
+  /(^|\/)migrations\//,
+  /(^|\/)limitations\//,
+  // 9. captured API-response fixtures
+  /(^|\/)fixtures\//,
+];
+
+// Vendored / generated / third-party trees — the same exclusion the sibling detector applies.
+const ALIAS_EXCLUDED_TREES = /(^|\/)(node_modules|public-docs)\/|\.min\.js$|(^|\/)vendor\//;
+
+// A line that is ABOUT the alias rather than a caller of it. Rule 8 above.
+const ALIAS_COMMENTARY_RE = /\balias\b|\blegacy\b|\bpermanent\b|\bforever\b/i;
+
+function isExcludedPath(relPath) {
+  const p = relPath.replace(/\\/g, '/');
+  if (ALIAS_EXCLUDED_TREES.test(p)) return true;
+  return ALIAS_EXCLUDED_PATHS.some((re) => re.test(p));
+}
+
+// isCountedLine — a line naming the alias that is a CALLER rather than commentary. Exported so the
+// test and any future sweep share ONE decision (the gds-literal-scan precedent: a gate whose
+// detector drifts from its sweep is worse than no gate).
+function isCountedLine(line) {
+  if (!line.includes(ALIAS)) return false;
+  if (line.includes(CANONICAL)) return false;
+  if (ALIAS_COMMENTARY_RE.test(line)) return false;
+  return true;
+}
+
+// countInText — alias occurrences on counted lines only. A line can legitimately carry more than
+// one (two fetches, a usage banner), so occurrences are counted rather than lines: that is what
+// makes the number fall when a caller is actually moved.
+function countInText(text) {
+  let n = 0;
+  for (const line of String(text).split(/\r?\n/)) {
+    if (!isCountedLine(line)) continue;
+    n += (line.match(ALIAS_RE) || []).length;
+  }
+  return n;
+}
+
+function trackedFiles() {
+  const out = execFileSync('git', ['ls-files'], { cwd: ROOT, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  return out.split('\n').map((s) => s.trim()).filter(Boolean);
+}
+
+// scanAliasCallers — { total, byFile, scanned } across every tracked, countable file.
+//
+// `scanned` is the NON-VACUITY channel, and it is the whole reason this function returns it. A
+// static scan breaks by finding nothing, and a green run looks identical to a working one: if
+// `git ls-files` returns nothing, or every path is excluded, this reports total 0 and a caller
+// that reads only `total` cannot tell a clean tree from a broken scanner. The ratchet and the test
+// both assert `scanned > 0`, so an enumeration that collapses fails LOUDLY instead of passing.
+//
+// `files` and `readFile` are injectable for tests, so the real aggregation — exclusions, the
+// commentary rule, per-file totals — is exercised without writing into the repo. The unit lane runs
+// test files in parallel; a test that edited a tracked file would break whichever suite happened to
+// be scanning the tree at that moment.
+function scanAliasCallers({ files = null, readFile = null } = {}) {
+  const read = readFile || ((relPath) => fs.readFileSync(path.join(ROOT, relPath), 'utf8'));
+  const byFile = {};
+  let total = 0;
+  let scanned = 0;
+  for (const relPath of files || trackedFiles()) {
+    if (isExcludedPath(relPath)) continue;
+    let text;
+    try {
+      text = read(relPath);
+    } catch {
+      continue;
+    }
+    if (text.includes(String.fromCharCode(0))) continue; // binary (a NUL byte)
+    scanned += 1;
+    const n = countInText(text);
+    if (n) {
+      byFile[relPath] = n;
+      total += n;
+    }
+  }
+  return { total, byFile, scanned };
+}
+
+function main() {
+  const { total, byFile, scanned } = scanAliasCallers();
+  const ranked = Object.entries(byFile).sort((a, b) => b[1] - a[1]);
+  if (process.argv.includes('--json')) {
+    process.stdout.write(`${JSON.stringify({ total, byFile, scanned }, null, 2)}\n`);
+    return;
+  }
+  const show = process.argv.includes('--files') ? ranked : ranked.slice(0, 20);
+  console.log(`in-repo /api/gds callers: ${total} across ${ranked.length} file(s) (${scanned} file(s) scanned)`);
+  console.log('(the alias contract, the pinned OAuth callbacks, the uptime poller + smoke, the rename guardrails,');
+  console.log(' tests/, docs/, migrations/ and captured fixtures are excluded by construction; so is any line that');
+  console.log(' also names /api/bongos or carries the words alias / legacy / permanent / forever)');
+  console.log('');
+  for (const [f, n] of show) console.log(`  ${String(n).padStart(5)}  ${f}`);
+  if (show.length < ranked.length) console.log(`  … and ${ranked.length - show.length} more file(s) — pass --files for all`);
+}
+
+if (require.main === module) main();
+
+// Only what a consumer actually calls. The constants above stay module-private on purpose: an
+// export nobody imports reads as dead code to knip and costs a ratchet point for nothing, and the
+// rules are meant to be read here rather than re-implemented by a caller.
+module.exports = {
+  isExcludedPath,
+  isCountedLine,
+  countInText,
+  scanAliasCallers,
+};

package/scripts/gds/fitness-ratchets.js

@@ -347,6 +347,15 @@ const METRIC_HINTS = {
     + 'Write Bongos instead. Run `node scripts/gds/gds-literal-scan.js` to see every counted file. '
     + 'Version ids (GDS-V##), docs/adr, docs/session-logs, docs/audits, limitations and migrations '
     + 'are excluded by construction — if your literal is history, it belongs in one of those.',
+  legacy_api_gds_callers:
+    ' — a NEW in-repo caller was written against the permanent `/api/gds` alias (task 1004064, '
+    + 'idea 1001030). Ask for `/api/bongos` instead: the alias exists for callers we CANNOT update '
+    + '(shipped Dev Box binaries, live dev boxes), not for code in this repo. Run '
+    + '`node scripts/gds/api-alias-caller-scan.js --files` to see every counted line. The alias '
+    + 'contract, the pinned OAuth callbacks, the uptime poller + smoke, the rename guardrails, '
+    + 'tests/, docs/, migrations/ and captured fixtures are excluded by construction — and so is '
+    + 'any line that also names /api/bongos or carries the words alias / legacy / permanent / forever, '
+    + 'so if your line is ABOUT the alias rather than a call to it, say so on the line.',
 };
 
 function compareToBaselines(metrics, baselines) {
@@ -379,6 +388,27 @@ function gdsMetrics() {
   return { legacy_gds_literals: scanGdsLiterals().total };
 }
 
+// legacy_api_gds_callers — the LOWERCASE half of the same rename (task 1004064, idea 1001030).
+// `legacy_gds_literals` above is case-sensitive on the shouting acronym, so it read 1135 both
+// before and after task 1003707 moved 665 in-repo callers off `/api/gds` — correct for what it
+// measures, and exactly why a caller written against the alias tomorrow moves no number and reds
+// no build. This counts that spelling instead. Detector + the reason for every exclusion:
+// scripts/gds/api-alias-caller-scan.js.
+//
+// It FAILS CLOSED on a collapsed enumeration. A static scan breaks by finding nothing, and a
+// green run looks identical to a working one — so if the scanner scanned no files at all, the
+// metric is OMITTED with a reason on stderr rather than reported as a flattering 0 that would
+// invite someone to ratchet the baseline down to it.
+function apiAliasCallerMetrics() {
+  const { scanAliasCallers } = require('./api-alias-caller-scan.js');
+  const { total, scanned } = scanAliasCallers();
+  if (!scanned) {
+    process.stderr.write('fitness-ratchets: legacy_api_gds_callers NOT MEASURED — the caller scan enumerated ZERO files, which is a scan defect, not a clean tree\n');
+    return {};
+  }
+  return { legacy_api_gds_callers: total };
+}
+
 // skill_listing_chars — the resident cost of the skill listing (every name +
 // description, both skill homes). Ratcheted rather than merely warned about
 // because this number has now been trimmed three times (tasks 1003548, 1003587,
@@ -411,6 +441,7 @@ function computeMetrics({ withDocs = true } = {}) {
     require_cycle_count: countCycles(requireGraph(contents)),
     console_call_count: consoleCallCount(contents),
     ...gdsMetrics(),
+    ...apiAliasCallerMetrics(),
     ...skillListingMetrics(),
     ...(withDocs ? docMetrics() : {}),
   };

package/scripts/hall-preview/server.js

@@ -231,7 +231,20 @@ app.use((req, res, next) => {
     return res.end(png);
   }
 
-  if (req.method !== 'GET') {
+  // READ-SHAPED POSTS. A handful of routes are POSTs only because the INPUT is a
+  // draft rather than an id — they write nothing. Serving them the 501 below made
+  // their surfaces permanently un-demoable here: the page renders its degraded
+  // state forever, which is the "a page that only ever renders its empty state
+  // cannot be redesigned by looking" trap modules/hall-ui/CLAUDE.md names. They
+  // fall through to the ordinary fixture lookup instead.
+  //
+  // AN ALLOWLIST, and it stays short. Anything absent is still refused, so a real
+  // write cannot reach the harness by growing a comment — adding a member means
+  // asserting that route writes nothing, which is checkable at its handler.
+  const READ_SHAPED_POSTS = new Set([
+    'inbox/preview-landing', // the landing verdict for a draft (task 1004083)
+  ]);
+  if (req.method !== 'GET' && !READ_SHAPED_POSTS.has(apiPath)) {
     return res.status(501).json({ error: { code: 'preview_readonly', message: 'the preview harness serves fixtures; writes are not wired' } });
   }
   // Your own account wins over the checked-in snapshot; a me-scoped read that

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.910'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.911'; // 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('dev-box'); log.info('mounted');

package/tests/api_alias_caller_ratchet.mjs

@@ -0,0 +1,130 @@
+// tests/api_alias_caller_ratchet.mjs — the lowercase `/api/gds` CALLER ratchet
+// (task 1004064, from idea 1001030). Mirrors tests/fitness_gds_ratchet.mjs, its
+// case-sensitive sibling.
+//
+// WHAT THIS FILE IS DEFENDING AGAINST. The brief names the trap exactly: "this is a static scan;
+// it breaks by finding nothing, and a green run looks identical to a working one." Every case
+// below is written so that a scanner which enumerates nothing, excludes everything, or counts
+// nothing FAILS here rather than passing quietly. The aggregation cases inject their own file
+// list and reader, so the real exclusion + counting path runs without writing into the repo —
+// the unit lane runs test files in parallel, and a test that edited a tracked file would break
+// whichever suite happened to be scanning the tree at that moment.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const scan = require(path.join(ROOT, 'scripts', 'gds', 'api-alias-caller-scan.js'));
+
+// A reader over an in-memory tree — no repo writes.
+const fake = (tree) => ({ files: Object.keys(tree), readFile: (rel) => tree[rel] });
+
+test('the counter COUNTS — a file that should count, does (the trap case)', () => {
+  const r = scan.scanAliasCallers(fake({
+    'src/bongos/routes/thing.js': "await fetch(`${base}/api/gds/tasks/${id}`);\n",
+  }));
+  assert.equal(r.total, 1, 'a plain in-repo caller must be counted');
+  assert.deepEqual(Object.keys(r.byFile), ['src/bongos/routes/thing.js']);
+  assert.equal(r.scanned, 1, 'and the file must actually have been scanned');
+});
+
+test('a collapsed enumeration is visible as scanned=0, not as a flattering total of 0', () => {
+  const empty = scan.scanAliasCallers(fake({}));
+  assert.equal(empty.total, 0);
+  assert.equal(empty.scanned, 0, 'scanned is what distinguishes "nothing to find" from "nothing looked at"');
+
+  const allExcluded = scan.scanAliasCallers(fake({
+    'tests/x.mjs': '/api/gds\n',
+    'docs/x.md': '/api/gds\n',
+  }));
+  assert.equal(allExcluded.total, 0);
+  assert.equal(allExcluded.scanned, 0, 'an every-path-excluded run is also scanned=0 — the same signal');
+});
+
+test('the REAL scan enumerates the repo and lands on the committed baseline', () => {
+  const r = scan.scanAliasCallers();
+  assert.ok(r.scanned > 500, `the real tree must enumerate substantially (got ${r.scanned})`);
+  const baselines = JSON.parse(readFileSync(path.join(ROOT, 'config', 'fitness-baselines.json'), 'utf8'));
+  const floor = baselines.metrics.legacy_api_gds_callers;
+  assert.equal(typeof floor, 'number', 'the metric must have a baseline, or the ratchet only warns');
+  assert.ok(r.total <= floor, `caller count ${r.total} is ABOVE baseline ${floor} — a new /api/gds caller entered the tree`);
+});
+
+test('the exclusions are real and each one is reachable', () => {
+  // Rule numbers refer to the header of api-alias-caller-scan.js.
+  for (const p of [
+    'src/bongos/api-prefix.js',            // 1 the alias contract
+    'src/bongos/routes/auth.js',           // 2 the pinned OAuth callbacks
+    'modules/provisioning/provisioning.js',
+    'src/bongos/uptime-poller.js',         // 3 the live proof
+    'scripts/gds/smoke-gds.js',
+    'scripts/gds/gds-literal-scan.js',     // 4 the rename guardrails
+    'scripts/gds/fitness-ratchets.js',
+    'scripts/gds/api-alias-caller-scan.js',
+    'tests/api_alias_exceptions.mjs',      // 5 tests
+    'modules/dev-box/app/test/thing.mjs',
+    'docs/architecture.md',                // 6 docs
+    'migrations/033_audit_log.sql',        // 7 migrations
+    'scripts/hall-preview/fixtures/tasks.json', // 9 captured fixtures
+    'node_modules/pkg/index.js',           // vendored
+  ]) {
+    assert.equal(scan.isExcludedPath(p), true, `${p} must be excluded`);
+  }
+  // …and the exclusion is not a blanket that swallows the tree.
+  for (const p of [
+    'src/bongos/serve-internal.js',
+    'modules/lifecycle/abandon-leftovers.js',
+    'clients/bongos-client/index.mjs', // a .mjs that is NOT a test — a blanket \.mjs$ would blind the ratchet
+    'bin/bongos.js',
+    'CLAUDE.md',
+  ]) {
+    assert.equal(scan.isExcludedPath(p), false, `${p} must NOT be excluded`);
+  }
+});
+
+test('a line ABOUT the alias is not a caller of it — and the rule is not so loose it excuses everything', () => {
+  // Excluded: names the canonical prefix too, or says what it is.
+  assert.equal(scan.isCountedLine('mount /api/bongos and /api/gds'), false);
+  assert.equal(scan.isCountedLine('// /api/gds is a permanent alias'), false);
+  assert.equal(scan.isCountedLine('// the legacy /api/gds mount'), false);
+  assert.equal(scan.isCountedLine('// /api/gds stays FOREVER'), false);
+  // Counted: a bare caller, with none of those tells.
+  assert.equal(scan.isCountedLine('const r = await fetch(`${base}/api/gds/me`);'), true);
+  assert.equal(scan.isCountedLine('  node scripts/gds/api.js GET /api/gds/tasks/1'), true);
+  // And a line with no alias at all is never counted, whatever else it says.
+  assert.equal(scan.isCountedLine('fetch(`${base}/api/bongos/me`)'), false);
+  assert.equal(scan.isCountedLine('a line about a legacy alias, forever'), false);
+});
+
+test('occurrences are counted, not lines — moving ONE of two callers on a line lowers the number', () => {
+  assert.equal(scan.countInText('f("/api/gds/a"); f("/api/gds/b");\n'), 2);
+  assert.equal(scan.countInText('f("/api/bongos/a"); f("/api/gds/b");\n'), 0, 'the canonical name on the line is the alias-commentary rule, by design');
+  assert.equal(scan.countInText('nothing here\n'), 0);
+});
+
+test('the ratchet is WIRED — computeMetrics reports the metric and compareToBaselines fails a rise', () => {
+  const ratchets = require(path.join(ROOT, 'scripts', 'gds', 'fitness-ratchets.js'));
+  const baselines = JSON.parse(readFileSync(path.join(ROOT, 'config', 'fitness-baselines.json'), 'utf8')).metrics;
+
+  // A rise is a violation…
+  const worse = ratchets.compareToBaselines(
+    { legacy_api_gds_callers: baselines.legacy_api_gds_callers + 1 },
+    baselines,
+  );
+  assert.equal(worse.violations.length, 1, 'one more caller must RED the build');
+  assert.match(worse.violations[0], /legacy_api_gds_callers regressed/);
+  assert.match(worse.violations[0], /api-alias-caller-scan/, 'the hint must name the tool that lists the offenders');
+
+  // …a fall is a ratchet-down warning, not a failure.
+  const better = ratchets.compareToBaselines(
+    { legacy_api_gds_callers: baselines.legacy_api_gds_callers - 1 },
+    baselines,
+  );
+  assert.equal(better.violations.length, 0);
+  assert.equal(better.warnings.length, 1);
+  assert.match(better.warnings[0], /ratchet-down available/);
+});