@bongos/core 1.19.607 → 1.19.608

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.607",
-  "core_contract": "1.19.607",
-  "source_commit": "a2068c523c1b4845be5d94b006e95f1d213717ed",
+  "core_version": "1.19.608",
+  "core_contract": "1.19.608",
+  "source_commit": "f112591192f3c6ab69e73f3703bd2f2e2f6f746e",
   "source_ref": "HEAD",
-  "built_at": "2026-09-08T23:51:21.550Z",
+  "built_at": "2026-09-09T00:10:53.531Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 458,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2078,
+    "functional_verbatim": 2080,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2560,
-  "tree_sha256": "1e9d9d267269d69cf9e5cf933d04757d0d20961047ab7f9cd2bfed3cbc721bd7",
+  "file_count": 2562,
+  "tree_sha256": "53d8a68171007b0b61fd34bff5aaf036110d1cb584228a250f606a4300cabf7d",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -2732,7 +2732,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "69fd2cbffee9e8396923dd5984eafe6b647809c1695b87f1d5d0543748187904"
+      "sha256": "afddf5268d6326d2d128069afcb0e0ed2bc06cd6040bfa7e7f8531227a9ca891"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7632,12 +7632,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "65e25f20c4196fe1064184914552bf3ffbd5fca85db7c6115084d5d5b1e9a210"
+      "sha256": "021b578efabb07b661729dd8120695a9ff976b409e355f1ffd35e3c1f3f22a40"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "bfbaa26f7eb3571a6c520e890c2c55c8558643fc195d4a3e963896a22f8faef6"
+      "sha256": "22dc9b83baf7d5765ca7ab8ec400e15e0ac5ada03b98895c33f9bd5d4dc0cc62"
     },
     {
       "path": "public-docs/index.html",
@@ -8117,7 +8117,7 @@
     {
       "path": "scripts/gds/gds-literal-scan.js",
       "mode": "0000644",
-      "sha256": "3f873da74a012f73e30e659f070b3476eda81ac55f802913307494a645d8ee88"
+      "sha256": "30a05f9d8d476e83740f0630e17d1accc3e29d67cebfc74d19abfeae6608e514"
     },
     {
       "path": "scripts/gds/gen-api-client.js",
@@ -8494,6 +8494,11 @@
       "mode": "0000644",
       "sha256": "06ad6a69304cfc66509f4ab283e7f76196ac7edcac97f8eba55ea3ab92c3eecb"
     },
+    {
+      "path": "scripts/gds/rename-ledger-prose.js",
+      "mode": "0000644",
+      "sha256": "f73e495ab63fbca755e652d284e378d9b2afef67fe43c4c5a66e2962c92cef1d"
+    },
     {
       "path": "scripts/gds/render-ideas.js",
       "mode": "0000644",
@@ -9357,7 +9362,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "504ef9943bde8940c3e32850ffb6206a3a2f0869cbd293e3482e7309ea0e3608"
+      "sha256": "d5e97cf6a460b1d69da907cfdfa0acf06bbb010067bf23f07de1940dcf36336a"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -12014,6 +12019,11 @@
       "mode": "0000644",
       "sha256": "2cbc4981c0f33a6597445f268055d10107b6696be4de42e5790e7efefc087edd"
     },
+    {
+      "path": "tests/rename_ledger_prose.mjs",
+      "mode": "0000644",
+      "sha256": "39eaa32121eae07fa7f508d60324e896e4c1b98c53ff390bb8bdca4b952c874f"
+    },
     {
       "path": "tests/render_prefs.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -1663,5 +1663,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.605 with no explicit bump. run 34291868670. (task 1002620)
   1.19.607 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.606 with no explicit bump. run 34292436274. (task 1002620)
+  1.19.608 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.607 with no explicit bump. run 34293848928. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.607",
+  "version": "1.19.608",
   "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/gds-literal-scan.js

@@ -76,6 +76,12 @@ const GDS_RULE_FILES = new Set([
   'scripts/gds/rename-history-check.js',
   'tests/rename_history_restraint.mjs',
   'config/rename-history-baseline.json',
+  // The LEDGER pass (task 1003698, criterion C4). It has to spell out every
+  // identifier it protects and every phrase shape it rewrites, so it names the
+  // literal more often than any other file in the tree — and its test names it
+  // once per case. Same exemption, same reason.
+  'scripts/gds/rename-ledger-prose.js',
+  'tests/rename_ledger_prose.mjs',
 ]);
 
 // A version id is a row key, not vocabulary. Stripped before matching so it is

package/scripts/gds/rename-ledger-prose.js

@@ -0,0 +1,482 @@
+#!/usr/bin/env node
+'use strict';
+// rename-ledger-prose.js — criterion C4 of goal 1000073, "the live ledger reads
+// Bongos" (task 1003698).
+//
+// WHAT IS LEFT TO RENAME, AND WHY IT IS THE LEDGER. The code and the API were
+// renamed long ago (src/gds/ is src/bongos/, /api/bongos is canonical). What
+// still says the old name to a live reader is the PROSE INSIDE DB ROWS — goal
+// and task titles and descriptions, read every day in the hall and by every
+// agent that claims work.
+//
+// THE ONE RULE, inherited from the goal: rename what the project says about
+// itself GOING FORWARD; leave what it recorded about its PAST. Its enforcement
+// is its sibling scripts/gds/rename-history-check.js (criterion C5), which
+// fails the build if the frozen record is erased. This script is the other
+// direction, and it is deliberately narrow about what it will touch.
+//
+// THREE KINDS OF OCCURRENCE, and only ONE of them is this script's business.
+// Measured over all 3,369 task rows on 2026-09-07 — the goal's own estimate of
+// ~119 rows was taken before this split was understood and is low by ~2.4x:
+//
+//   1. FROZEN ARCHIVES (157 rows). Anything whose version_id is GDS-V3 or
+//      GDS-V4. Those versions shipped; their rows are the record. Skipped by
+//      version, not by heuristic.
+//
+//   2. IDENTIFIERS (77 rows carry nothing else). `GDS_TOKEN`, `GDS_API_BASE`,
+//      `GDS_BRANDING_FILE`, `MEDUSA_GDS_ONLY`, the `gds_session` cookie, the
+//      `scripts/gds/` path, and `/api/gds`. These are NOT vocabulary — they are
+//      the true names of things that still exist under those names. Renaming
+//      the prose would make the ledger LIE about what the code does. The env
+//      names and paths belong to criterion C3, which renames the THING and the
+//      prose together, behind a fallback release; `/api/gds` is a permanent
+//      alias and is never renamed at all. So every one of these is masked out
+//      before substitution and restored afterwards, byte for byte.
+//
+//   3. VOCABULARY — the acronym used as a word: "the GDS", "GDS tasks",
+//      "GDS-internal", "the GDS DB". This, and only this, is what C4 rewrites.
+//
+// WHY A REVIEWED PROPOSAL AND NOT A FIND-REPLACE. "the GDS exists to support
+// builders" must become "Bongos exists to support builders" — the article has
+// to go — while "the GDS database" keeps it. No regex settles that reliably, so
+// the rules below handle the shapes that recur and EXEMPT_ROWS/OVERRIDES carry
+// the ones a rule would get wrong. The default mode prints every proposed diff
+// and changes nothing; --apply is a separate, deliberate act.
+//
+// WRITES GO THROUGH THE API, NOT SQL. The builder box holds no DATABASE_URL and
+// no psql by design, and PATCH /tasks/:id and PATCH /goals/:id are permission-
+// checked and land every edit in audit_log. That is a better audit trail than
+// hand-run SQL, which was the shape this task was originally filed with.
+//
+// Usage:
+//   node scripts/gds/rename-ledger-prose.js              # dry run: every proposed diff
+//   node scripts/gds/rename-ledger-prose.js --summary    # counts only
+//   node scripts/gds/rename-ledger-prose.js --json
+//   node scripts/gds/rename-ledger-prose.js --apply      # write, one PATCH per row
+
+const { execFileSync } = require('node:child_process');
+const path = require('node:path');
+
+// ONE detector, shared with the C2 ratchet. GDS_VERSION_ID_RE is the rule that
+// says a version id is a row key rather than vocabulary; PINNED_VERSION_IDS in
+// rename-history-check.js is the list those keys are pinned to. Importing both
+// is what stops this pass and the two gates around it from disagreeing about
+// what counts as history — a second, divergent copy is the failure the task
+// named explicitly.
+const { GDS_VERSION_ID_RE } = require('./gds-literal-scan.js');
+const { PINNED_VERSION_IDS } = require('./rename-history-check.js');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+
+// Versions whose rows ARE the record. Not a heuristic — a list.
+// Derived from the C5 pin, not re-typed. If a version id is ever added to the
+// frozen record, it becomes frozen HERE in the same commit rather than a
+// release later.
+const FROZEN_VERSION_IDS = new Set(PINNED_VERSION_IDS);
+
+// Rows that STATE the rule, and so must keep naming what they retire. The
+// ledger's analogue of GDS_RULE_FILES in gds-literal-scan.js: a goal that says
+// "finish the GDS→Bongos rename" cannot be rewritten to say "finish the
+// Bongos→Bongos rename" without becoming nonsense.
+const EXEMPT_ROWS = new Set([
+  'goal:1000073',   // Finish the GDS→Bongos rename — this goal
+  'goal:1000010',   // "GDS core modularization (Config B)" — a shipped goal's own title
+  'task:1001933',   // Part B2: rename internal gds→bongos names
+  'task:1003698',   // this task
+]);
+
+// ---------- the identifier mask ----------
+
+// Longest / most specific first: GDS_API_BASE must be consumed before a bare
+// GDS could match inside it. Each is a REAL NAME that still exists, so it is
+// removed from the text before substitution and put back byte-for-byte after.
+const IDENTIFIER_PATTERNS = [
+  // IMPORTED, not re-declared. The version-id rule is the one exclusion this
+  // script genuinely shares with the C2 ratchet, and two copies of it would
+  // drift the moment either side learned about a new version id. The ratchet's
+  // other exclusions are PATH-based (docs/adr, migrations) and have no meaning
+  // for a database row, so they are deliberately not pulled in here.
+  GDS_VERSION_ID_RE,
+  /\/api\/gds\b/gi,               // the permanent alias (src/bongos/api-prefix.js)
+  /\bMEDUSA_GDS_[A-Z0-9_]+/g,
+  /\bGDS_[A-Z0-9_]+/g,            // env names — criterion C3, with a fallback release
+  /\bOTB_GDS_[A-Z0-9_]+/g,
+  /\bgds_session\b/gi,            // cookie name — C3
+  /\bgds-session(?:\.json)?\b/gi, // the CLI session file — C3
+  /\bscripts\/gds\b/gi,           // paths — C3
+  /\bsrc\/gds\b/gi,
+  /\bapi\/gds\b/gi,
+];
+
+const SENTINEL = '
MASK';
+
+// maskIdentifiers — replace every real name with an opaque token, returning the
+// masked text plus the list needed to restore it. Exported so the test can
+// assert the round trip is lossless: an identifier that came back changed would
+// be a silent corruption of the ledger, not a visible failure.
+function maskIdentifiers(text) {
+  const masks = [];
+  let out = text;
+  for (const re of IDENTIFIER_PATTERNS) {
+    out = out.replace(re, (m) => {
+      masks.push(m);
+      return `${SENTINEL}${masks.length - 1}`;
+    });
+  }
+  return { masked: out, masks };
+}
+
+function unmask(masked, masks) {
+  return masked.replace(/
MASK(\d+)/g, (_, i) => masks[Number(i)]);
+}
+
+// ---------- mention vs use ----------
+
+// THE FAILURE THIS PREVENTS, found by reading all 147 proposed diffs before
+// applying any of them. Some rows do not USE the acronym as a name, they MENTION
+// it as a token — and renaming a mention destroys the sentence:
+//
+//   "GDS is a legacy term inherited from Primea"  → "Bongos is a legacy term…"  (now false)
+//   "the primer still says GDS (should be Bongos)" → "…says Bongos (should be Bongos)"
+//   "fails the build on a NEW literal `GDS`"       → the gate's own rule, erased
+//   "records the bongos-as-GDS-successor intent"   → nonsense
+//   "Nightly pg_dump of Cloud Bongos GDS Postgres" → "Cloud Bongos Bongos Postgres"
+//
+// This is the same principle as GDS_RULE_FILES in gds-literal-scan.js, applied
+// to rows instead of files: text that STATES the rule has to be able to name
+// what it retires. The bias is deliberate — a match SKIPS the row and reports
+// it for a human, so the cost of a false positive is a row left alone and
+// listed, never a corrupted one. Acceptance criterion 4 of the task asks for
+// exactly that list.
+const MENTION_MARKERS = [
+  /["'`«]\s*GDS\s*["'`»]/,          // quoted or backticked: the token itself
+  /\bliteral\s+`?GDS/i,
+  /\bcalled\s+GDS\b/i,
+  /\bsays?\s+GDS\b/i,
+  /\bnamed?\s+GDS\b/i,
+  /\bterm\b[^.\n]{0,40}GDS/i,
+  /GDS[^.\n]{0,40}\blegacy\b/i,
+  /\blegacy\b[^.\n]{0,40}GDS/i,
+  /GDS\s*(?:→|->|to)\s*Bongos/i,     // the rename, written out
+  /(?:PMS|Medusa)\s*(?:→|->)\s*GDS/i, // the PREVIOUS rename, which is history
+  /GDS-successor/i,
+  /\brename\b[^.\n]{0,60}GDS|GDS[^.\n]{0,60}\brename\b/i,
+];
+
+// mentionsRatherThanUses — true when the row is talking ABOUT the word.
+function mentionsRatherThanUses(text) {
+  return MENTION_MARKERS.some((re) => re.test(text));
+}
+
+// ---------- the vocabulary rules ----------
+
+// THE ARTICLE PROBLEM, and why the default is to KEEP it.
+//
+// "the GDS router" must become "the Bongos router" — the acronym is modifying a
+// noun. "the GDS knows everything" must become "Bongos knows everything" — the
+// acronym IS the subject and the article has to go. Get it backwards in the
+// first case and you write "mounted outside Bongos router", which is broken
+// English; get it backwards in the second and you write "the Bongos knows
+// everything", which merely reads oddly.
+//
+// So the asymmetry decides the default: KEEP the article unless the very next
+// word is a finite verb. Dropping wrongly breaks a sentence; keeping wrongly
+// never does. The verb list is taken from the 41 distinct "<determiner> GDS
+// <word>" shapes actually present in the corpus, not invented.
+const ARTICLE_DROP_VERBS = [
+  'is', 'are', 'was', 'were', 'has', 'have', 'holds', 'knows', 'pushes', 'pulls',
+  'exists', 'builds', 'says', 'records', 'enforces', 'sits', 'lives', 'treats',
+  'expects', 'refuses', 'returns', 'becomes', 'remains', 'auto-posts',
+];
+// The same reasoning covers what follows a bare mention: a preposition, a
+// conjunction or an opening bracket all mean the acronym was the noun itself
+// ("poll the GDS for the next task", "its home is the GDS (goal + task rows)").
+const ARTICLE_DROP_FOLLOWERS = ['for', 'by', 'and', 'or', 'today', 'then', 'itself'];
+const ARTICLE_DROP_RE = new RegExp(
+  `\\b[Tt]he\\s+GDS\\b(?=\\s+(?:${ARTICLE_DROP_VERBS.join('|')}|${ARTICLE_DROP_FOLLOWERS.join('|')})\\b|\\s*[(,.;:])`,
+  'g',
+);
+
+// rewriteVocabulary — the substitution, on ALREADY-MASKED text. Pure, and
+// exported so every rule has a test that names its own input.
+function rewriteVocabulary(masked) {
+  let s = masked;
+  // 0. the product name already carries the word — "Cloud Bongos GDS Postgres"
+  //    must not become "Cloud Bongos Bongos Postgres".
+  s = s.replace(/\bCloud Bongos GDS\b/g, 'Cloud Bongos');
+  // 1. "the GDS <verb>" — the acronym is the subject, so the article goes with
+  //    the rename rather than being left stranded in front of it.
+  s = s.replace(ARTICLE_DROP_RE, 'Bongos');
+  // 2. everything else: the acronym as a name or a modifier. Any determiner in
+  //    front of it is left exactly where it was ("the Bongos router").
+  s = s.replace(/\bGDS\b/g, 'Bongos');
+  return s;
+}
+
+// rewrite — the whole pipeline for one string: mask the real names, rename the
+// vocabulary, restore the real names. Returns null when nothing changed.
+function rewrite(text) {
+  if (!text || !text.includes('GDS')) return null;
+  const { masked, masks } = maskIdentifiers(text);
+  if (!masked.includes('GDS')) return null; // identifiers only — not this script's business
+  const out = unmask(rewriteVocabulary(masked), masks);
+  return out === text ? null : out;
+}
+
+// ---------- row selection ----------
+
+// EDITABLE tells each kind which prose columns the API will accept, so the
+// script cannot propose an edit the route would reject.
+const EDITABLE = {
+  task: ['title', 'description'],
+  goal: ['title', 'subtitle', 'description'],
+};
+
+// proposeForRow — the pure half of selection: given one row, what would change.
+function proposeForRow(kind, row) {
+  const key = `${kind}:${row.id}`;
+  if (EXEMPT_ROWS.has(key)) return { skipped: 'exempt', kind, id: String(row.id), key, title: row.title };
+  if (FROZEN_VERSION_IDS.has(row.version_id)) return null; // frozen archive — silent, it is the whole point
+
+  const whole = EDITABLE[kind].map((c) => row[c] || '').join('\n');
+  if (!whole.includes('GDS')) return null;
+
+  const patch = {};
+  for (const col of EDITABLE[kind]) {
+    const next = rewrite(row[col]);
+    if (next !== null) patch[col] = next;
+  }
+  if (!Object.keys(patch).length) return null; // identifiers only
+
+  // Both checks below run AFTER the patch is computed, so a row is only
+  // reported as needing a human when it would OTHERWISE have been rewritten.
+  // Order matters for honesty: testing the raw text first would flag rows whose
+  // only occurrences are protected identifiers, i.e. rows with nothing wrong.
+  if (mentionsRatherThanUses(whole)) {
+    return { skipped: 'mentions-the-word', kind, id: String(row.id), key, title: row.title };
+  }
+
+  // A goal that is no longer open is a completed record, and the server says so
+  // itself: PATCH /goals/:id answers 409 goal_not_open on anything but `open`.
+  // That rule and this goal's rule are the same rule — "leave what it recorded
+  // about its past" — so this is not an obstacle to be worked around by
+  // reopening the goal. Reported rather than skipped silently: those rows do
+  // still read the old way, and a human should know which ones.
+  if (kind === 'goal' && row.status && row.status !== 'open') {
+    return { skipped: `goal-${row.status}`, kind, id: String(row.id), key, title: row.title };
+  }
+  return { kind, id: String(row.id), key, title: row.title, patch, before: row };
+}
+
+// ---------- the API (collectors; kept out of the pure half) ----------
+
+function api(method, urlPath, body) {
+  const args = [path.join(ROOT, 'scripts', 'gds', 'api.js'), method, urlPath];
+  const opts = { cwd: ROOT, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 };
+  if (body !== undefined) {
+    args.push('--body-file', '-');
+    opts.input = JSON.stringify(body);
+  }
+  const out = execFileSync('node', args, opts);
+  const brace = out.indexOf('{');
+  return brace === -1 ? {} : JSON.parse(out.slice(brace));
+}
+
+// The list route caps at 1000 and orders oldest-first, so the newest rows are
+// on the LAST page. Paging is not optional here: stopping at one page would
+// silently skip everything filed recently, which is exactly the class of bug
+// filed as task 1003699 against sequence.js.
+function allTasks() {
+  const rows = [];
+  let offset = 0;
+  for (;;) {
+    const q = offset ? `/api/gds/tasks?limit=1000&offset=${offset}` : '/api/gds/tasks?limit=1000';
+    const page = api('GET', q).tasks || [];
+    rows.push(...page);
+    if (page.length < 1000) break;
+    offset += 1000;
+  }
+  return rows;
+}
+
+function allGoals() {
+  const out = [];
+  for (const version of ['BONGOS-V1', 'CB-V1']) {
+    const r = api('GET', `/api/gds/goals?version=${version}`);
+    for (const g of r.goals || []) out.push(g);
+  }
+  return out;
+}
+
+function collectProposals() {
+  const proposals = [];
+  const skipped = [];
+  const take = (p) => {
+    if (!p) return;
+    (p.skipped ? skipped : proposals).push(p);
+  };
+  for (const t of allTasks()) take(proposeForRow('task', t));
+  for (const g of allGoals()) take(proposeForRow('goal', g));
+  return { proposals, skipped };
+}
+
+// ---------- write pacing ----------
+
+// The server allows 30 writes per minute per IP (PER_IP_LIMIT in
+// src/bongos/middleware/rate-limit.js). Learned the expensive way: the first
+// --apply of this script fired 123 PATCHes flat out, landed the first ~60, and
+// took a 429 for every one after that — leaving the ledger half-renamed, which
+// is the one outcome worse than not starting. Pace under the limit and retry
+// what still bounces, so a run either finishes or says exactly what it missed.
+const WRITES_PER_MIN = 25;                                    // under 30, with headroom for the reads
+const WRITE_SPACING_MS = Math.ceil(60000 / WRITES_PER_MIN);
+const MAX_RETRIES = 4;
+
+// A synchronous sleep, because the whole script is execFileSync-shaped and one
+// async conversion would buy nothing here.
+function sleep(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+// patchWithRetry — one write, retried on 429 with a widening backoff. Any other
+// error is returned immediately: a validation failure will not fix itself, and
+// retrying it just burns the rate budget the remaining rows need.
+function patchWithRetry(url, body) {
+  let wait = WRITE_SPACING_MS * 2;
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt += 1) {
+    try {
+      api('PATCH', url, body);
+      return { ok: true };
+    } catch (e) {
+      // api.js prints the status line to STDOUT and exits non-zero, so the
+      // 429 is in e.stdout, not in e.message. Reading only the message would
+      // silently turn every rate-limit into a permanent failure.
+      const message = `${e.message || ''}\n${e.stdout || ''}\n${e.stderr || ''}`;
+      if (!message.includes('429') || attempt === MAX_RETRIES) {
+        return { ok: false, message: message.slice(0, 300) };
+      }
+      console.log(`      rate-limited, waiting ${Math.round(wait / 1000)}s`);
+      sleep(wait);
+      wait *= 2;
+    }
+  }
+  return { ok: false, message: 'unreachable' };
+}
+
+// ---------- reporting ----------
+
+// changedLines — only the lines that actually differ, so a 4,000-character task
+// description does not drown the one line under review.
+function changedLines(before, after) {
+  const b = String(before).split('\n');
+  const a = String(after).split('\n');
+  const out = [];
+  for (let i = 0; i < Math.max(b.length, a.length); i += 1) {
+    if (b[i] !== a[i]) out.push({ before: b[i], after: a[i] });
+  }
+  return out;
+}
+
+function printProposals(proposals) {
+  for (const p of proposals) {
+    console.log(`\n${p.kind} ${p.id} — ${String(p.title).slice(0, 76)}`);
+    for (const [col, next] of Object.entries(p.patch)) {
+      for (const line of changedLines(p.before[col], next)) {
+        console.log(`  ${col}`);
+        console.log(`    - ${String(line.before).trim().slice(0, 200)}`);
+        console.log(`    + ${String(line.after).trim().slice(0, 200)}`);
+      }
+    }
+  }
+}
+
+function summarize(proposals) {
+  const byKind = {};
+  let edits = 0;
+  for (const p of proposals) {
+    byKind[p.kind] = (byKind[p.kind] || 0) + 1;
+    edits += Object.keys(p.patch).length;
+  }
+  return { rows: proposals.length, edits, byKind };
+}
+
+// ---------- CLI ----------
+
+function printSkipped(skipped) {
+  if (!skipped.length) return;
+  console.log(`\nLEFT FOR A HUMAN — ${skipped.length} row(s) that would have been rewritten wrongly:`);
+  for (const s of skipped) {
+    console.log(`  ${s.key}  [${s.skipped}]  ${String(s.title).slice(0, 76)}`);
+  }
+  console.log('\n  mentions-the-word — the row talks ABOUT the acronym; renaming it breaks the sentence.');
+  console.log('  exempt            — the row states the rename rule and must keep naming what it retires.');
+  console.log('  goal-achieved/archived — a closed goal is a completed record; the server refuses the edit');
+  console.log('                      (409 goal_not_open), which is the same rule this goal is built on.');
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const { proposals, skipped } = collectProposals();
+  const stats = summarize(proposals);
+
+  if (argv.includes('--json')) {
+    process.stdout.write(`${JSON.stringify({
+      stats,
+      proposals: proposals.map((p) => ({ kind: p.kind, id: p.id, patch: p.patch })),
+      skipped: skipped.map((s) => ({ key: s.key, reason: s.skipped, title: s.title })),
+    }, null, 2)}\n`);
+    return;
+  }
+
+  if (!argv.includes('--apply')) {
+    if (!argv.includes('--summary')) printProposals(proposals);
+    printSkipped(skipped);
+    console.log(`\ndry run — nothing written.`);
+    console.log(`  ${stats.rows} row(s), ${stats.edits} column edit(s): ${JSON.stringify(stats.byKind)}`);
+    console.log(`  ${skipped.length} row(s) left for a human`);
+    console.log(`  frozen versions skipped entirely: ${[...FROZEN_VERSION_IDS].join(', ')}`);
+    console.log('\n  apply with: node scripts/gds/rename-ledger-prose.js --apply');
+    return;
+  }
+
+  console.log(`applying ${proposals.length} row(s) at ${WRITES_PER_MIN}/min — about ${Math.ceil(proposals.length / WRITES_PER_MIN)} minute(s).`);
+  let ok = 0;
+  const failed = [];
+  for (const [i, p] of proposals.entries()) {
+    const url = p.kind === 'task' ? `/api/gds/tasks/${p.id}` : `/api/gds/goals/${p.id}`;
+    if (i) sleep(WRITE_SPACING_MS);
+    const r = patchWithRetry(url, p.patch);
+    if (r.ok) {
+      ok += 1;
+      console.log(`  ok  ${String(i + 1).padStart(3)}/${proposals.length}  ${p.kind} ${p.id}`);
+    } else {
+      failed.push({ key: p.key, message: r.message });
+      console.log(`  FAIL      ${p.kind} ${p.id}`);
+    }
+  }
+  console.log(`\napplied ${ok}/${proposals.length} row(s).`);
+  if (failed.length) {
+    console.log('failed:');
+    for (const f of failed) console.log(`  ${f.key}: ${f.message}`);
+    process.exitCode = 1;
+  }
+  console.log('re-run without --apply to confirm 0 remaining (the idempotency check).');
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  FROZEN_VERSION_IDS,
+  EXEMPT_ROWS,
+  IDENTIFIER_PATTERNS,
+  EDITABLE,
+  MENTION_MARKERS,
+  mentionsRatherThanUses,
+  maskIdentifiers,
+  unmask,
+  rewriteVocabulary,
+  rewrite,
+  proposeForRow,
+  changedLines,
+  summarize,
+};

package/src/module-api.js

@@ -55,7 +55,7 @@ const { buildInfo } = require('./build-info');
 // 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.607'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.608'; // 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/rename_ledger_prose.mjs

@@ -0,0 +1,192 @@
+// tests/rename_ledger_prose.mjs — criterion C4 of goal 1000073, "the live
+// ledger reads Bongos" (task 1003698).
+//
+// WHAT IS ACTUALLY AT RISK HERE. This script edits live rows through the API,
+// so the expensive failure is not "it missed one" — it is "it rewrote something
+// it should not have". Three kinds of thing must survive it byte for byte:
+// identifiers that are still the true names of live things, the frozen GDS-V3 /
+// GDS-V4 archives, and rows that MENTION the acronym rather than use it. Every
+// one of those gets a case below, and they are the load-bearing ones.
+//
+// The pure half of the script takes its inputs explicitly, so nothing here
+// touches the network or the tree.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const L = require(path.join(ROOT, 'scripts', 'gds', 'rename-ledger-prose.js'));
+
+// ---------- identifiers are not vocabulary ----------
+
+test('every identifier shape survives a rewrite byte for byte', () => {
+  for (const kept of [
+    'GDS_API_BASE', 'GDS_TOKEN', 'GDS_BRANDING_FILE', 'MEDUSA_GDS_ONLY',
+    '/api/gds', '/api/gds/tasks', 'scripts/gds/ship.js', 'src/gds/db.js',
+    'gds_session', 'gds-session.json', 'GDS-V3', 'GDS-V4',
+  ]) {
+    const text = `prose around ${kept} and more prose`;
+    const out = L.rewrite(text);
+    assert.ok(out === null || out.includes(kept), `${kept} must survive; got ${out}`);
+  }
+});
+
+test('a row carrying ONLY identifiers proposes no change at all', () => {
+  assert.equal(L.rewrite('set GDS_API_BASE, hit /api/gds, read the gds_session cookie'), null);
+  assert.equal(L.rewrite('run scripts/gds/ship.js'), null);
+});
+
+test('an identifier and real vocabulary in the same sentence: one changes, one does not', () => {
+  const out = L.rewrite('the GDS holds it; set GDS_API_BASE first');
+  assert.equal(out, 'Bongos holds it; set GDS_API_BASE first');
+});
+
+test('the mask round-trips exactly — a corrupted identifier would be silent', () => {
+  const text = 'GDS_TOKEN and /api/gds and GDS-V4 and scripts/gds/x.js';
+  const { masked, masks } = L.maskIdentifiers(text);
+  assert.ok(!masked.includes('GDS_TOKEN'));
+  assert.equal(L.unmask(masked, masks), text);
+});
+
+test('the version-id rule is SHARED with the C2 ratchet and the C5 pin, not re-declared', () => {
+  // The task asked for exactly this: "REUSE it rather than writing a second,
+  // divergent rule". Two copies drift the moment either side learns a new
+  // version id, and the drift is silent — this asserts one source.
+  const scan = require(path.join(ROOT, 'scripts', 'gds', 'gds-literal-scan.js'));
+  const history = require(path.join(ROOT, 'scripts', 'gds', 'rename-history-check.js'));
+  assert.ok(L.IDENTIFIER_PATTERNS.includes(scan.GDS_VERSION_ID_RE), 'the version-id regex must be the ratchet’s own object');
+  assert.deepEqual([...L.FROZEN_VERSION_IDS], history.PINNED_VERSION_IDS, 'the frozen set must come from the C5 pin');
+});
+
+// ---------- the article, which is where a regex usually breaks grammar ----------
+
+test('the article is KEPT when the acronym modifies a noun', () => {
+  assert.equal(L.rewrite('mounted outside the GDS router'), 'mounted outside the Bongos router');
+  assert.equal(L.rewrite('a GDS task and a GDS blocker'), 'a Bongos task and a Bongos blocker');
+  assert.equal(L.rewrite('The GDS `dependencies[]` say what ships'), 'The Bongos `dependencies[]` say what ships');
+});
+
+test('the article is DROPPED when the acronym is the subject', () => {
+  assert.equal(L.rewrite('The GDS knows everything'), 'Bongos knows everything');
+  assert.equal(L.rewrite('the GDS is the ledger'), 'Bongos is the ledger');
+  assert.equal(L.rewrite('poll the GDS for the next task'), 'poll Bongos for the next task');
+  assert.equal(L.rewrite('its home is the GDS (goal rows)'), 'its home is Bongos (goal rows)');
+});
+
+test('keeping the article is the DEFAULT, because dropping it wrongly breaks the sentence', () => {
+  // An unrecognised follower must not lose its article — "outside Bongos
+  // router" is broken English, while "the Bongos widget" merely reads plainly.
+  assert.equal(L.rewrite('inside the GDS widgetorium'), 'inside the Bongos widgetorium');
+});
+
+test('the product name is not doubled', () => {
+  assert.equal(L.rewrite('pg_dump of Cloud Bongos GDS Postgres DB'), 'pg_dump of Cloud Bongos Postgres DB');
+});
+
+// ---------- mention vs use ----------
+
+test('text that MENTIONS the word is detected, not rewritten', () => {
+  for (const mention of [
+    'GDS is a legacy term inherited from Primea',
+    'the primer still says GDS (should be Bongos)',
+    'fails the build on a NEW literal `GDS`',
+    'records the bongos-as-GDS-successor intent',
+    'a thing called GDS at the time',
+    'GDS → Bongos naming sweep',
+    'unchanged since the PMS→GDS rename',
+    'files under docs/ containing "GDS"',
+  ]) {
+    assert.equal(L.mentionsRatherThanUses(mention), true, `should be treated as a mention: ${mention}`);
+  }
+});
+
+test('ordinary usage is NOT mistaken for a mention', () => {
+  for (const use of [
+    'the GDS router has no rate limiting',
+    'Writes GDS records only',
+    'poll the GDS for the next claimable task',
+    'a GDS task must be claimed first',
+  ]) {
+    assert.equal(L.mentionsRatherThanUses(use), false, `should be treated as ordinary use: ${use}`);
+  }
+});
+
+// ---------- row selection ----------
+
+const taskRow = (over) => ({ id: '1', version_id: 'BONGOS-V1', title: 'the GDS holds it', description: 'x', ...over });
+
+test('a frozen-archive row is skipped entirely, and silently — it IS the record', () => {
+  assert.equal(L.proposeForRow('task', taskRow({ version_id: 'GDS-V3' })), null);
+  assert.equal(L.proposeForRow('task', taskRow({ version_id: 'GDS-V4' })), null);
+});
+
+test('a live row is proposed, patching only the columns that changed', () => {
+  const p = L.proposeForRow('task', taskRow({ description: 'nothing to see' }));
+  assert.deepEqual(Object.keys(p.patch), ['title']);
+  assert.equal(p.patch.title, 'Bongos holds it');
+});
+
+test('an exempt row is REPORTED, never silently dropped', () => {
+  const p = L.proposeForRow('goal', { id: '1000073', version_id: 'BONGOS-V1', title: 'Finish the GDS→Bongos rename' });
+  assert.equal(p.skipped, 'exempt');
+});
+
+test('a mention row is reported for a human instead of being rewritten', () => {
+  const p = L.proposeForRow('task', taskRow({ description: 'GDS is a legacy term inherited from Primea' }));
+  assert.equal(p.skipped, 'mentions-the-word');
+  assert.equal(p.patch, undefined, 'a skipped row must carry no patch — nothing can apply it by accident');
+});
+
+test('a closed goal is reported, not patched — the server refuses it and the goal rule agrees', () => {
+  for (const status of ['achieved', 'archived']) {
+    const p = L.proposeForRow('goal', { id: '9', version_id: 'BONGOS-V1', status, title: 'the GDS holds it' });
+    assert.equal(p.skipped, `goal-${status}`);
+    assert.equal(p.patch, undefined);
+  }
+  const open = L.proposeForRow('goal', { id: '9', version_id: 'BONGOS-V1', status: 'open', title: 'the GDS holds it' });
+  assert.equal(open.patch.title, 'Bongos holds it');
+});
+
+test('a closed goal whose only occurrences are IDENTIFIERS is not reported at all', () => {
+  // Reporting it would tell a human to look at a row with nothing wrong. The
+  // status check must run after the patch, not before it.
+  const p = L.proposeForRow('goal', {
+    id: '9', version_id: 'BONGOS-V1', status: 'achieved',
+    title: 'set GDS_API_BASE', description: 'and hit /api/gds',
+  });
+  assert.equal(p, null);
+});
+
+test('only columns the API accepts are ever proposed', () => {
+  assert.deepEqual(L.EDITABLE.task, ['title', 'description']);
+  assert.deepEqual(L.EDITABLE.goal, ['title', 'subtitle', 'description']);
+  const p = L.proposeForRow('task', taskRow({ notes: 'the GDS holds it' }));
+  assert.ok(!('notes' in p.patch), 'PATCH /tasks/:id does not accept notes');
+});
+
+// ---------- idempotency, by construction ----------
+
+test('a rewritten row proposes nothing on a second pass', () => {
+  const once = L.rewrite('the GDS holds it; the GDS router is fine');
+  assert.equal(L.rewrite(once), null, 'the second --apply must change zero rows');
+});
+
+test('summarize counts rows and column edits per kind', () => {
+  const stats = L.summarize([
+    { kind: 'task', patch: { title: 'a', description: 'b' } },
+    { kind: 'task', patch: { title: 'a' } },
+    { kind: 'goal', patch: { subtitle: 'c' } },
+  ]);
+  assert.equal(stats.rows, 3);
+  assert.equal(stats.edits, 4, 'edits counts COLUMNS, not rows — a row can change two');
+  assert.deepEqual(stats.byKind, { task: 2, goal: 1 });
+});
+
+test('changedLines reports only the lines that differ', () => {
+  const lines = L.changedLines('same\nthe GDS\nsame', 'same\nBongos\nsame');
+  assert.equal(lines.length, 1);
+  assert.equal(lines[0].after, 'Bongos');
+});