@bongos/core 1.21.175 → 1.21.176

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

@@ -1,482 +1,7 @@
 #!/usr/bin/env node
+// scripts/gds/rename-ledger-prose.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/rename-ledger-prose.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 '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,
-};
+require('../bongos/forwarder.js').forward(module, 'rename-ledger-prose.js');