@bongos/core 1.19.910 → 1.19.912

package/modules/hall-ui/public/ideas.js

@@ -88,6 +88,12 @@
   let goalTouchedByUser = false; // once the builder picks, stop clobbering it with fresh suggestions
   let quickSuggestTimer = null;
   let quickFiling = false;
+  // GRAVITY (task 1004083 / spec R02). The landing verdict for the draft as it
+  // currently stands, read from POST /inbox/preview-landing. A monotonic token
+  // guards against the out-of-order arrival a debounced-but-concurrent read
+  // invites: two previews in flight can land in either order, and the older one
+  // winning would leave the line describing a draft that no longer exists.
+  let gravitySeq = 0;
 
   // ---------------------------------------------------------------------------
   // draft persistence
@@ -501,9 +507,108 @@
     }
   }
 
+  // ---------------------------------------------------------------------------
+  // gravity — which goal will catch this thought, said before it is released
+  // (task 1004083 / spec R02)
+  // ---------------------------------------------------------------------------
+
+  const fqGravityEl = () => $('#fq-gravity');
+
+  // THE SENTENCES, AND NOTHING ELSE. Every branch below READS a field of the
+  // server's verdict; not one of them decides a landing. That split is the whole
+  // point of the endpoint: modules/ideas/routing.js `decideLanding` stays the one
+  // place the matrix lives, and a second copy of it in this file is precisely the
+  // failure the #fq-kind comment above already records ("this markup used to
+  // spell the whole vocabulary and had gone stale ... a third copy nobody was
+  // watching"). If a sentence here ever needs an `if` over kind or rank, the
+  // verdict is missing a field and the fix belongs on the server.
+  //
+  // Returns null for "say nothing" — an unscorable draft, or a read that failed.
+  // Silence is the honest degraded state: it leaves the filer exactly where they
+  // were before this feature, rather than replacing a quiet lie with a loud one.
+  function gravitySentence(v) {
+    if (!v || !v.outcome) return null;
+    const goalName = v.goal ? (v.goal.title || `goal ${v.goal.id}`) : null;
+    const claimable = v.status === 'ready';
+
+    if (v.outcome === 'refused') {
+      // The protected-scope wall. The server wrote the reason for a human; it is
+      // the one branch that already reads as a sentence, so it is passed through.
+      return { tone: 'refused', text: v.refusal && v.refusal.reason ? v.refusal.reason : `${goalName} will not take this filing.` };
+    }
+    if (v.outcome === 'routed') {
+      return {
+        tone: 'lands',
+        text: claimable
+          ? `This lands in ${goalName} as a task anyone can claim.`
+          : `This lands in ${goalName}, waiting for a nod before anyone can claim it.`,
+      };
+    }
+    if (v.outcome === 'routed_home') {
+      // The label on the picker says "homeless"; since ADR 0262 that is not true
+      // of a bug, and this line is the correction. Naming the version rather than
+      // the goal is deliberate — the maintenance goal is created by the capture,
+      // so the preview has no row to name without making one (landing-preview.js).
+      return {
+        tone: 'lands',
+        text: claimable
+          ? `A bug always lands. With no goal picked this goes to ${v.version_id}'s maintenance goal, claimable straight away.`
+          : `A bug always lands. With no goal picked this goes to ${v.version_id}'s maintenance goal, waiting for a nod.`,
+      };
+    }
+    // outcome === 'floats' — the inbox. Two ways to get here, and they are
+    // different facts: nobody named a goal, or a goal was named and the matrix
+    // declined it. The second is the one the picker currently lies about.
+    if (v.reason === 'judgment_kind') {
+      return { tone: 'floats', text: `${goalName} will not catch this — this kind is judged, not queued. It waits in the inbox for triage.` };
+    }
+    if (v.reason === 'full_idea_never_routes') {
+      return { tone: 'floats', text: 'A Full Idea is ratified by the board rather than routed. It waits in the inbox.' };
+    }
+    return { tone: 'floats', text: 'This floats in the inbox until someone triages it.' };
+  }
+
+  function renderGravity(v) {
+    const el = fqGravityEl();
+    if (!el) return;
+    const said = gravitySentence(v);
+    // dataset, not setAttribute: it writes the same data-tone the sheet selects
+    // on, and it is the half of the element a DOM the page is rendered into and
+    // a test stub both really carry.
+    if (!said) { el.hidden = true; el.textContent = ''; el.dataset.tone = ''; return; }
+    el.textContent = said.text;
+    el.dataset.tone = said.tone;
+    el.hidden = false;
+  }
+
+  // The read. Shares the suggester's debounce rather than adding a second clock:
+  // the two answer the same question at the same moment ("given what is typed so
+  // far, where does this go?"), and spec decision 12 — filing never gets slower —
+  // is a reason not to grow the number of things a keystroke sets running.
+  //
+  // A draft with no title is not previewed: it cannot be filed either, so there
+  // is no outcome to state.
+  async function refreshGravity() {
+    const seq = ++gravitySeq;
+    const title = fqTitleEl().value.trim();
+    if (!title) { renderGravity(null); return; }
+    const goalId = fqGoalEl().value;
+    const body = { kind: fqKindEl().value };
+    if (goalId) body.goal_id = Number(goalId);
+    let r;
+    try {
+      r = await api.inbox.postInboxPreviewLanding({ body });
+    } catch (_) {
+      r = null;
+    }
+    // A stale answer never paints. See gravitySeq above.
+    if (seq !== gravitySeq) return;
+    renderGravity(r && r.ok ? r.data : null);
+  }
+
   function onQuickTitleEdit() {
     clearTimeout(quickSuggestTimer);
-    quickSuggestTimer = setTimeout(refreshGoalSuggestions, QUICK_SUGGEST_DEBOUNCE_MS);
+    quickSuggestTimer = setTimeout(() => { refreshGoalSuggestions(); refreshGravity(); }, QUICK_SUGGEST_DEBOUNCE_MS);
   }
 
   function showQuickErr(msg) {
@@ -570,6 +675,10 @@
     fqKindEl().value = 'bug';
     goalTouchedByUser = false;
     renderGoalOptions([]);
+    // The form is empty again, so the line has nothing to describe. The RECEIPT
+    // above is what survives the filing (task 1004082); gravity is a statement
+    // about a draft, and this draft is gone.
+    renderGravity(null);
   }
 
   async function bootQuickComposer() {
@@ -577,7 +686,11 @@
     renderGoalOptions([]);
     fqTitleEl().addEventListener('input', onQuickTitleEdit);
     fqKindEl().addEventListener('change', onQuickTitleEdit);
-    fqGoalEl().addEventListener('change', () => { goalTouchedByUser = true; });
+    // Changing the goal is the one edit that changes gravity WITHOUT changing
+    // what the suggester would return, so it redraws the line directly rather
+    // than going through onQuickTitleEdit. Deliberately undebounced: a select is a
+    // deliberate single act, not a stream of keystrokes.
+    fqGoalEl().addEventListener('change', () => { goalTouchedByUser = true; refreshGravity(); });
     $('#fq-form').addEventListener('submit', fileQuick);
 
     // Before any network call: the receipts are local, so a builder who reloads

package/modules/ideas/landing-preview.js

@@ -0,0 +1,180 @@
+'use strict';
+
+// modules/ideas/landing-preview.js — THE LANDING VERDICT, BEFORE THE WRITE
+// (task 1004083, BV2.R02 — "Gravity is visible before release").
+//
+// THE PROBLEM THIS ANSWERS. The composer's goal `<select>` is not invisible; it
+// is visible and it MISLEADS, in two directions that the filer cannot see:
+//
+//   1. `No goal (homeless)` is FALSE FOR A BUG. Since ADR 0262 a homeless
+//      kind='bug' filed through the `api` vector routes into the version's
+//      maintenance goal (./homeless-home.js). The filer is told their report
+//      will float. It will not.
+//   2. NAMING A GOAL IS FALSE FOR A JUDGMENT KIND. routing.NEVER_ROUTE_KINDS
+//      ('criterion-proposal', 'decision') and grade='full' never route, so the
+//      select shows a goal that will not catch the thought.
+//
+// So "gravity is visible" is not a restyle of the dropdown — the dropdown's own
+// labels are the thing that is wrong. It is met by stating the matrix's verdict.
+//
+// NO NEW ROUTING, and this file is where that promise is kept. It DECIDES
+// nothing: it calls the same `decideLanding` and `authorizeRoutedLanding` the
+// capture calls, over the same inputs, and reports what they said. A second copy
+// of the matrix in browser JS is the failure mode this exists to avoid — the
+// same one the composer's `#fq-kind` comment already records ("this markup used
+// to spell the whole vocabulary and had gone stale against the DB CHECK ... a
+// third copy nobody was watching"), and the same one `ideas.js` already forbids
+// in prose ("read it, never re-derive the landing matrix here").
+//
+// READ-ONLY IS A HARD CONTRACT, not an intention. Every statement below is a
+// SELECT. In particular it calls `currentBuildingVersionId` and NEVER
+// `ensureMaintenanceGoal` — that one is find-or-CREATE, and the preview runs on
+// every keystroke of a debounced composer. Previewing a homeless bug must not
+// mint a goal as a side effect of typing, so the preview names the version whose
+// maintenance goal will catch it and leaves the row to the real capture.
+//
+// ITS OWN FILE for the reason homeless-home.js gives: inbox.js sits at the
+// fitness line cap with no headroom, and "what will happen if I file this" is
+// one question with one answer that a reader should find as a file.
+
+const api = require('../../src/module-api');
+const { pool } = api;
+const { decideLanding, authorizeRoutedLanding } = require('./routing');
+
+// The verdict vocabulary the composer renders. Stable machine tokens, never
+// prose: the wording is the UI's business and the copy registry's, and a client
+// that wants a different sentence must not have to string-match English.
+//
+//   'routed'        — it becomes a task in a named goal. `status` says whether
+//                     that task is claimable ('ready') or awaiting a nod
+//                     ('backlog'); `goal` names the home.
+//   'routed_home'   — it becomes a task, but the goal is the MAINTENANCE goal the
+//                     system picks, not one the filer named (the homeless bug).
+//                     `version_id` names whose maintenance goal.
+//   'floats'        — it waits in the inbox for triage. The honest reading of
+//                     "no goal", and also of a goal the matrix declined.
+//   'refused'       — it will not be filed at all (the protected-scope wall).
+const OUTCOMES = Object.freeze({
+  ROUTED: 'routed',
+  ROUTED_HOME: 'routed_home',
+  FLOATS: 'floats',
+  REFUSED: 'refused',
+});
+
+// previewLanding — what pressing "File it" would do, without doing it.
+//
+// Takes exactly what the capture takes, and the caller resolves `filerRank` and
+// `vector` the same way POST /inbox does: the rank off the AUTHENTICATED builder
+// and the vector hardcoded. A preview that read either from the body would let a
+// filer see — and then, by symmetry of argument, demand — a landing they do not
+// hold. It is a read, so being wrong here leaks nothing; being wrong here
+// TEACHES something false, which is the whole defect this task is about.
+//
+// NEVER THROWS. A composer redrawing on every keystroke must degrade to "we
+// cannot say yet", never to a red error under a half-typed title. An outage in
+// any read below collapses to `{ outcome: null }` and the UI says nothing —
+// which leaves today's behaviour exactly as it is, rather than replacing a
+// silent lie with a loud one.
+async function previewLanding(input, deps = {}) {
+  // NORMALISE FIRST, DESTRUCTURE AFTER — the trap ./routing.js's `decideLanding`
+  // already records, and which the first cut of this function walked straight
+  // into. A default in the parameter list fires on `undefined` and NOT on
+  // `null`, so `previewLanding(null)` threw from the signature — BEFORE the
+  // try/catch below, so the "never throws" contract above was false for the one
+  // input a caller spreading an absent object actually produces.
+  const { goalId = null, kind = null, grade = null, filerRank = null, vector = null } = input || {};
+  const activePool = ((deps || {}).pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  try {
+    const landing = decideLanding({ goalId, kind, grade, filerRank, vector });
+
+    if (!landing.route) {
+      // A goal was named and the matrix declined it — the second lie above. The
+      // reason token travels so the UI can say WHY it still floats rather than
+      // showing a goal that is not going to catch anything.
+      return { outcome: OUTCOMES.FLOATS, reason: landing.reason, status: null, goal: null, version_id: null, refusal: null };
+    }
+
+    if (landing.homeless) {
+      // The first lie above. Read-only: name the version, never make the goal.
+      const lifecycle = api.resolveOptional && api.resolveOptional('lifecycle');
+      const versionId = lifecycle && lifecycle.currentBuildingVersionId
+        ? await lifecycle.currentBuildingVersionId()
+        : null;
+      // No building version means the real capture would fail closed
+      // (homeless-home.js NO_BUILDING_VERSION), so the preview must not promise
+      // a landing. It says nothing rather than naming a home that isn't there.
+      if (!versionId) return { outcome: null, reason: landing.reason, status: null, goal: null, version_id: null, refusal: null };
+      return {
+        outcome: OUTCOMES.ROUTED_HOME,
+        reason: landing.reason,
+        status: landing.status,
+        goal: null,
+        version_id: versionId,
+        refusal: null,
+      };
+    }
+
+    // A named goal. The same three facts the transaction checks — the goal is
+    // real, open, and on a building version — read WITHOUT the FOR SHARE lock,
+    // because a preview holds nothing and races nothing: it describes the world
+    // a moment before the write, and the write re-checks under its own lock.
+    const { rows } = await activePool.query(
+      `SELECT g.id, g.title, g.status, g.version_id, g.scope_modules, v.status AS version_status
+         FROM goals g
+         JOIN versions v ON v.id = g.version_id
+        WHERE g.id = $1`,
+      [goalId]
+    );
+    const goal = rows[0];
+    // A goal that is gone, archived, or on a closed version would be refused by
+    // the capture. The preview declines to guess a sentence for a state the
+    // filer cannot reach from the picker anyway (it lists open goals only), and
+    // lets the real 400 name it if they get there by other means.
+    if (!goal || goal.status !== 'open' || goal.version_status !== 'building') {
+      return { outcome: null, reason: landing.reason, status: null, goal: null, version_id: null, refusal: null };
+    }
+
+    // The binding gate, verbatim. `touches` is never declared by the composer —
+    // a person reporting a bug does not know which files it lives in — so the
+    // scope wall has nothing to subset-check and `scopeCheck` is null, exactly
+    // as it is for a human filing through POST /inbox. What CAN bite is the
+    // protected-scope refusal, and that is a server-only fact: it is the reason
+    // this preview cannot live in the browser.
+    const authorized = authorizeRoutedLanding({
+      landing,
+      filerRank,
+      scopeProtected: api.moduleScopeMap.scopeIncludesProtected(goal.scope_modules),
+      scopeCheck: null,
+    });
+    // The refusal NAMES the goal, and that is checked rather than assumed: the
+    // composer's own picker is filled from `GET /goals?status=open`, which applies
+    // no rank filter, so every open goal's title is already on screen for this
+    // caller — they picked this one FROM that list. Withholding it here would hide
+    // nothing and would cost the refusal its subject. If that read ever becomes
+    // rank-scoped, this line has to be revisited with it.
+    if (!authorized.ok) {
+      return {
+        outcome: OUTCOMES.REFUSED,
+        reason: landing.reason,
+        status: null,
+        goal: { id: goal.id, title: goal.title },
+        version_id: goal.version_id,
+        refusal: { code: authorized.code, reason: authorized.reason },
+      };
+    }
+
+    return {
+      outcome: OUTCOMES.ROUTED,
+      reason: landing.reason,
+      status: authorized.status,
+      goal: { id: goal.id, title: goal.title },
+      version_id: goal.version_id,
+      refusal: null,
+    };
+  } catch (_) {
+    // See the NEVER THROWS note above.
+    return { outcome: null, reason: null, status: null, goal: null, version_id: null, refusal: null };
+  }
+}
+
+module.exports = { previewLanding, OUTCOMES };

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.912",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.910",
+      "version": "1.19.912",
       "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.912",
   "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,
+};