@bongos/core 1.18.3 → 1.18.18

package/scripts/gds/fitness.js

@@ -939,8 +939,56 @@ const PROMPT_IDENTITY_LITERALS = [
   /amazonprimea/i,
 ];
 // Scan roots (recursive) + kernel-prompt CLIs that live outside them.
-const IDENTITY_SCAN_ROOTS = ['src/bongos', 'modules'];
+// scripts/gds joined at task 1002427: the builder CLI was UNSCANNED, which is how
+// paste-token.js kept a hardcoded 'https://amazonprimea.com' long after the task
+// 1002201 sweep replaced that literal everywhere else. The straggler surfaced as a
+// 401 that locked a builder out of re-authenticating — a valid token verified
+// against the wrong host — and nothing in CI could see it (idea 1000564).
+const IDENTITY_SCAN_ROOTS = ['src/bongos', 'modules', 'scripts/gds'];
 const IDENTITY_SCAN_EXTRA_FILES = ['scripts/gds/architect-audit.js'];
+// PERMANENT, COUNTED carve-outs for the scripts/gds root — {file: allowed hits}.
+//
+// Widening the root (task 1002427) surfaced 23 files. Task 1002428 swept them:
+// every one whose literal was a real runtime bug is FIXED (a wrong instance URL
+// printed to a builder, an `amazonprimea-*` User-Agent that should come from
+// branding().userAgent(), a hardcoded product name in user-facing copy). What is
+// left below is NOT a backlog — each entry is a literal that is CORRECT as
+// written, so this list is permanent rather than a ratchet-to-zero.
+//
+// The COUNT is still enforced, which is the point: an entry may not grow. A file
+// here that gains a NEW hardcoded host fails the build exactly like an unlisted
+// one, and any file NOT listed must have zero hits. Getting better never fails.
+//
+// Why each is legitimate:
+//   * box.js — REAL Cloudflare/DNS zone names for the operator plane
+//     (`dev.<host>`, the terminal zone). These are infrastructure identifiers,
+//     not an instance URL; routing them through branding would be wrong. (Its
+//     two genuine API-base defaults WERE fixed in 1002428.)
+//   * publish-manifest.js — the literal FILENAMES of two real committed docs
+//     (docs/recipes/amazonprimea-decouple-*.md). Renaming the strings without
+//     renaming the files would break the publish manifest.
+//   * backfill-sessions.js / version-close.js — one-time operator runbook text
+//     naming the actual prod DB + a historical local directory. Describing what
+//     an operator must literally type is the correct content.
+//   * seed-*.js — the hits are PROSE INSIDE seeded task descriptions: historical
+//     records of what those tasks said when they were filed. Rewriting them would
+//     falsify the record; deleting the files would destroy it. They are inert
+//     (idempotent on source_ref) and referenced only by generated manifests.
+const IDENTITY_SCAN_ALLOWED = {
+  'scripts/gds/backfill-sessions.js': 2,
+  'scripts/gds/box.js': 3,
+  'scripts/gds/publish-manifest.js': 2,
+  'scripts/gds/seed-bongos-coreB-tranche1-tasks.js': 1,
+  'scripts/gds/seed-bongos-coreB-tranche2-tasks.js': 1,
+  'scripts/gds/seed-bongos-goal-hierarchy-tasks.js': 1,
+  'scripts/gds/seed-bongos-tasks.js': 1,
+  'scripts/gds/seed-gds-v4-tasks.js': 1,
+  'scripts/gds/seed-medusa-tasks.js': 7,
+  'scripts/gds/seed-module-upstreaming.js': 1,
+  'scripts/gds/seed-productization-tasks.js': 6,
+  'scripts/gds/seed-provisioning-tasks.js': 2,
+  'scripts/gds/version-close.js': 1,
+};
 const IDENTITY_SCAN_EXTS = new Set(['.js', '.html', '.css']);
 // Path-prefix carve-outs (see the header note). Kept SMALL and documented.
 const IDENTITY_SCAN_EXCLUDE = ['modules/game/'];
@@ -954,7 +1002,14 @@ function stripCommentsForIdentity(text, ext) {
   let t = String(text == null ? '' : text);
   if (ext === '.html') return t.replace(/<!--[\s\S]*?-->/g, '');
   t = t.replace(/\/\*[\s\S]*?\*\//g, ''); // block comments (js + css)
-  if (ext === '.js') t = t.split('\n').map((l) => l.replace(/(^|[^:])\/\/.*$/, '$1')).join('\n');
+  // Split on /\r?\n/, NOT '\n' (task 1002428). On a CRLF checkout the old split
+  // left a trailing \r on every line, and since `.` does not match \r the `.*$`
+  // in the line-comment pattern could never reach end-of-string — so NO line
+  // comment was stripped and every rationale comment naming the old brand was
+  // scanned as if it were code. That silently broke this function's whole
+  // contract ("a rationale comment naming the old brand never trips the scan")
+  // on Windows, and made the check disagree with Linux CI on the same tree.
+  if (ext === '.js') t = t.split(/\r?\n/).map((l) => l.replace(/(^|[^:])\/\/.*$/, '$1')).join('\n');
   return t;
 }
 
@@ -1016,12 +1071,30 @@ function checkKernelPromptsNoHardcodedIdentity() {
   for (const extra of IDENTITY_SCAN_EXTRA_FILES) {
     if (!seen.has(extra)) { seen.add(extra); entries.push({ abs: path.join(CORE_ROOT, extra), rel: extra }); }
   }
+  let ratcheted = 0;
   for (const { abs, rel: relFile } of entries) {
     let text;
     try { text = fs.readFileSync(abs, 'utf8'); }
     catch { continue; } // a file moved/carved away is not a failure of this gate
     scanned += 1;
-    violations.push(...scanPromptIdentity(relFile, text));
+    const found = scanPromptIdentity(relFile, text);
+    // Permanently allowed at a COUNT (task 1002428): the listed literals are
+    // correct as written, but an entry may not GROW — a new hardcode in one of
+    // these files fails exactly like one in an unlisted file.
+    const allowed = IDENTITY_SCAN_ALLOWED[relFile];
+    if (allowed !== undefined) {
+      if (found.length > allowed) {
+        violations.push(
+          `${relFile} now hardcodes the host-brand identity ${found.length} time(s), above its allowed ${allowed} — ` +
+          `the carve-out covers the EXISTING literals (see IDENTITY_SCAN_ALLOWED), not new ones. ` +
+          `Read the host from branding()/window.__BRANDING__ instead (task 1002428).`
+        );
+      } else {
+        ratcheted += 1;
+      }
+      continue;
+    }
+    violations.push(...found);
   }
   return {
     name: 'portable code carries no hardcoded host identity (BV1.R76 / task 1705)',
@@ -1029,7 +1102,43 @@ function checkKernelPromptsNoHardcodedIdentity() {
     hardFail: violations.length > 0,
     violations,
     warnings: [],
-    note: `${scanned} portable source file(s) scanned (src/bongos/** + modules/** + kernel-prompt CLIs, minus the instance-1 product + generated dirs) — none may hardcode the host brand; identity comes from branding()/window.__BRANDING__ (ADR 0062 §3/§5).`,
+    note: `${scanned} portable source file(s) scanned (src/bongos/** + modules/** + scripts/gds/** + kernel-prompt CLIs, minus the instance-1 product + generated dirs) — none may hardcode the host brand; identity comes from branding()/window.__BRANDING__ (ADR 0062 §3/§5). ${ratcheted} scripts/gds file(s) hold documented permanent carve-outs (real DNS zones, real doc filenames, operator runbook text, historical seeded prose) capped at a count they may not exceed — task 1002428.`,
+  };
+}
+
+// ============================================================================
+// Check 15b — core-shipped NEUTRAL config packs carry no host identity (BV1.R102)
+// ============================================================================
+//
+// Sibling of Check 15 for the CONFIG class. IDENTITY_SCAN_EXTS is js/html/css, so
+// the scan above never opens a .json — yet config/*.neutral.json is precisely what
+// a vanilla instance boots from (branding R76, governance R96). A host name leaking
+// into a neutral pack ships one instance's brand to EVERY fresh instance, and until
+// this check nothing in CI could see it.
+//
+// Only the NEUTRAL packs are scanned, deliberately: an instance pack (config/
+// branding.json, config/governance.json) is host content that legitimately names
+// its host, and is boundary-excluded from the published core anyway.
+function checkNeutralConfigsNoHostIdentity() {
+  const violations = [];
+  const dir = path.join(CORE_ROOT, 'config');
+  let names = [];
+  try { names = fs.readdirSync(dir).filter((n) => n.endsWith('.neutral.json')).sort(); }
+  catch { /* no config/ dir in this root — nothing to gate */ }
+  for (const name of names) {
+    const relFile = `config/${name}`;
+    let text;
+    try { text = fs.readFileSync(path.join(dir, name), 'utf8'); }
+    catch { continue; } // a pack that moved away is not a failure of this gate
+    violations.push(...scanPromptIdentity(relFile, text, '.json'));
+  }
+  return {
+    name: 'neutral config packs carry no host identity (BV1.R102)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `${names.length} core-shipped config/*.neutral.json pack(s) scanned — a vanilla instance boots from these alone, so none may name a host brand. Instance packs (config/<name>.json) are host content and are deliberately NOT scanned.`,
   };
 }
 
@@ -1076,7 +1185,77 @@ function checkDesignContract() {
 // reskin/module-toggle reaches every widget). Self-contained: a pure scan of
 // index.html's <main>, no module/registry state needed. Exported for the unit test.
 // (The hall surface itself carved to modules/hall-ui/public/ in BV1.R85.)
+//
+// task 2177 — the check also asserts the HOME ZONE BUDGETS. builders.js caps how
+// many widgets each Home zone mounts (ZONE_BUDGETS); past the cap a widget still
+// mounts, but into a hidden overflow behind a "More" link. That graceful degrade
+// is the runtime safety net — it is NOT a licence to keep adding cards, and
+// because nothing goes red, a Home that has quietly outgrown its budget looks
+// fine. So CI counts the registrations statically and fails on a breach: the
+// budget becomes a decision someone has to make deliberately (raise the number
+// in builders.js, with a reason) instead of one that erodes.
+//
+// NOT statically checkable, by design: the `home-banner` rule is "at most ONE
+// VISIBLE", not "at most one registered" — both banner widgets (welcome,
+// getting-started) are hiddenByDefault and reveal themselves from onboarding
+// state, so only runtime knows the count. It is documented as a runtime
+// invariant in modules/hall-ui/CLAUDE.md rather than faked with a static count
+// that would either fail today or assert nothing.
 const HALL_INDEX = path.join(moduleDir('hall-ui'), 'public', 'index.html'); // hall-ui is a module — resolve its root (ADR 0108)
+const HALL_PUBLIC = path.join(moduleDir('hall-ui'), 'public');
+const HALL_BUILDERS_JS = path.join(HALL_PUBLIC, 'builders.js');
+
+// Parse builders.js's ZONE_BUDGETS object literal — the single source of truth
+// for the caps (this check must never carry its own copy of the numbers).
+function parseZoneBudgets(js) {
+  const block = js.match(/const\s+ZONE_BUDGETS\s*=\s*\{([^}]*)\}/);
+  if (!block) return null;
+  const budgets = {};
+  for (const [, zone, n] of block[1].matchAll(/['"]([\w-]+)['"]\s*:\s*(\d+)/g)) {
+    budgets[zone] = Number(n);
+  }
+  return Object.keys(budgets).length ? budgets : null;
+}
+
+// Count registrations per Home zone across every hall client script that calls
+// contributeHallWidget. The zones are static string literals in the registration
+// object, so a literal scan is exact for the code we have (and a computed zone
+// would be a placement smell in its own right — dom-utils' runtime validation
+// still rejects an unknown one). Requiring the contributeHallWidget mention is
+// what keeps an unrelated `zone:` key in some other object from eating budget.
+function scanHallZoneCounts(dir = HALL_PUBLIC, fsImpl = fs) {
+  const counts = {};
+  let files = [];
+  try { files = fsImpl.readdirSync(dir).filter((f) => f.endsWith('.js')); } catch { return counts; }
+  for (const file of files) {
+    let src = '';
+    try { src = fsImpl.readFileSync(path.join(dir, file), 'utf8'); } catch { continue; }
+    if (!src.includes('contributeHallWidget')) continue;
+    for (const [, zone] of src.matchAll(/\bzone:\s*['"]([\w-]+)['"]/g)) {
+      counts[zone] = (counts[zone] || 0) + 1;
+    }
+  }
+  return counts;
+}
+
+function checkHallZoneBudgets(fsImpl = fs) {
+  let js = '';
+  try { js = fsImpl.readFileSync(HALL_BUILDERS_JS, 'utf8'); } catch { return []; }
+  const budgets = parseZoneBudgets(js);
+  if (!budgets) {
+    return ['modules/hall-ui/public/builders.js no longer declares a parseable ZONE_BUDGETS literal — the Home zone budgets are unenforced (task 2177).'];
+  }
+  const counts = scanHallZoneCounts(HALL_PUBLIC, fsImpl);
+  const violations = [];
+  for (const [zone, budget] of Object.entries(budgets)) {
+    const n = counts[zone] || 0;
+    if (n > budget) {
+      violations.push(
+        `Home zone "${zone}" has ${n} registered hall widgets but its budget is ${budget} — the extras mount into the hidden overflow, so Home silently grew. Move it to its own page (see modules/hall-ui/CLAUDE.md §Placement), or raise ZONE_BUDGETS['${zone}'] in modules/hall-ui/public/builders.js deliberately (task 2177).`);
+    }
+  }
+  return violations;
+}
 
 function hallMainSlice(html) {
   // Strip HTML comments first so a comment that merely MENTIONS <main> or a
@@ -1107,13 +1286,14 @@ function checkHallSectionRegistry() {
   const hardcoded = scanHallSectionRegistry(html);
   const violations = hardcoded.map((s) =>
     `modules/hall-ui/public/index.html <main> hardcodes a hall section "${s}" — register it via window.OTB.contributeHallWidget (modules/hall-ui/public/hall-widgets.js for core, a module's client script otherwise), don't inline the markup (BV1.R75 / ADR 0062 §4).`);
+  violations.push(...checkHallZoneBudgets());
   return {
-    name: 'hall widgets are registry-owned (ADR 0062 §4)',
+    name: 'hall widgets are registry-owned + within zone budget (ADR 0062 §4, task 2177)',
     ok: violations.length === 0,
     hardFail: violations.length > 0,
     violations,
     warnings: [],
-    note: 'modules/hall-ui/public/index.html <main> contains no hardcoded <section class="scroll"> — the hall-widget registry is the single source of truth.',
+    note: 'modules/hall-ui/public/index.html <main> contains no hardcoded <section class="scroll">, and every Home zone is within the ZONE_BUDGETS cap builders.js declares — the registry is the single source of truth and Home cannot grow unnoticed.',
   };
 }
 
@@ -1126,8 +1306,9 @@ function checkHallSectionRegistry() {
 // config/modules.json, …) is boundary-EXCLUDED, so a bare `require('../../config/<excluded>.json')`
 // in core code throws MODULE_NOT_FOUND and CRASHES the boot on a fresh instance — the exact
 // class that shipped in R88 (two hard-requires in src/bongos/serve-internal.js; task 1824). The
-// cure is to guard the read (tryRequireConfig / fs.existsSync → fail-to-vanilla), which also
-// makes the require a non-literal so it no longer matches here. Check 1 (core↔host) scans
+// cure is to READ the config instead of requiring it, tolerating a missing file
+// (tryLoadInstanceConfig in src/bongos/serve-internal.js / fs.existsSync → fail-to-vanilla), which
+// also drops the require() literal so it no longer matches here. Check 1 (core↔host) scans
 // code→code IMPORTS and misses this code→config class. Only an EXCLUDED config is a violation;
 // a publishable neutral.*/schema config (which ships with the core) is fine.
 const CONFIG_REQUIRE_RE = /require\(\s*['"]([^'"]*config\/[^'"]*\.json)['"]\s*\)/g;
@@ -1155,7 +1336,7 @@ function checkCoreRequiresExcludedConfig() {
       while ((m = CONFIG_REQUIRE_RE.exec(raw))) {
         const relCfg = rel(path.resolve(path.dirname(abs), m[1]));
         if (!isPublishable(relCfg)) {
-          violations.push(`${relFile} → require('${m[1]}') hard-requires an instance-excluded config (${relCfg}) — guard the read (tryRequireConfig / fs.existsSync, fail-to-vanilla) so a fresh core boots (task 1824).`);
+          violations.push(`${relFile} → require('${m[1]}') hard-requires an instance-excluded config (${relCfg}) — guard the read (tryLoadInstanceConfig in src/bongos/serve-internal.js / fs.existsSync, fail-to-vanilla) so a fresh core boots (task 1824).`);
         }
       }
     }
@@ -1362,15 +1543,45 @@ const WRITE_VALIDATION_EXEMPT = new Set([
   'PATCH /me/display-name',       // { display_name }              — displayName.validate
 ]);
 
+// KNOWN GAPS, NOT EXEMPTIONS (task 1002551 / BV1.R109b → tracked by task 1002552).
+//
+// These three are NOT validated-by-lib and do NOT belong in WRITE_VALIDATION_EXEMPT
+// above — they are genuine ADR 0118 gaps that must grow a validateOrRespond schema.
+// They surface here only because R109b taught route discovery to see MULTI-LINE
+// `router.<method>(` declarations: this check reuses gen-api-docs.extractModel(), so
+// the same regex hole that hid them from the rank auditor hid them from Check 18 too.
+// They are pre-existing (never validated), not a regression.
+//
+// They are recorded rather than fixed because modules/*/routes/*.js was being migrated
+// concurrently by BV1.R105, so editing those files would have collided. This is the
+// Check-17 ratchet posture: a NAMED, non-growing baseline. The list may only ever
+// SHRINK — a new unvalidated write route is not on it and still hard-fails the build,
+// and a stale entry (one that HAS been fixed) also fails, so the list cannot rot.
+// Delete this constant when task 1002552 lands and Check 18 returns to hard-zero.
+// EMPTY as of BV1.R109c (task 1002552) — all three original entries now validate.
+// Kept (rather than deleted) as the ratchet itself: an empty named baseline states
+// the invariant is hard-zero, and any future entry has to be added deliberately.
+const WRITE_VALIDATION_BASELINE = new Set([]);
+
 function scanUnvalidatedWriteRoutes(model = genApiDocs.extractModel()) {
   const unvalidated = [];
+  const baselineSeen = new Set();
   for (const r of model) {
     if (!['POST', 'PUT', 'PATCH', 'DELETE'].includes(r.method)) continue;
     // Only routes that actually read a body have an input surface to validate;
     // a write that ignores req.body has nothing to declare.
     if (!r.body || !r.body.readsBody || r.body.validated) continue;
-    if (WRITE_VALIDATION_EXEMPT.has(`${r.method} ${r.route}`)) continue;
-    unvalidated.push(`${r.method} ${r.route}  [${r.file}]`);
+    const key = `${r.method} ${r.route}`;
+    if (WRITE_VALIDATION_EXEMPT.has(key)) continue;
+    if (WRITE_VALIDATION_BASELINE.has(key)) { baselineSeen.add(key); continue; }
+    unvalidated.push(`${key}  [${r.file}]`);
+  }
+  // A baseline entry that no longer reports as unvalidated has been FIXED — it must be
+  // removed, or the list would quietly license a future regression on that same route.
+  for (const key of WRITE_VALIDATION_BASELINE) {
+    if (!baselineSeen.has(key)) {
+      unvalidated.push(`${key}  [STALE BASELINE — this route now validates; remove it from WRITE_VALIDATION_BASELINE in scripts/gds/fitness.js]`);
+    }
   }
   return unvalidated;
 }
@@ -1389,7 +1600,7 @@ function checkWriteRoutesValidated() {
     hardFail: violations.length > 0,
     violations,
     warnings: [],
-    note: `body-reading POST/PUT/PATCH/DELETE routes must call validateOrRespond/validate (${WRITE_VALIDATION_EXEMPT.size} dynamic-key prefs routes validate by lib); ${unvalidated.length} unvalidated.`,
+    note: `body-reading POST/PUT/PATCH/DELETE routes must call validateOrRespond/validate (${WRITE_VALIDATION_EXEMPT.size} dynamic-key prefs routes validate by lib; ${WRITE_VALIDATION_BASELINE.size} known gaps tracked by task 1002552, list may only shrink); ${unvalidated.length} unvalidated.`,
   };
 }
 
@@ -1411,6 +1622,7 @@ const CHECKS = [
   checkMigrationNamespacing, // Check 11b — ADR 0108 §5 cross-repo migration filenames + stem collision
   checkDesignContract,
   checkKernelPromptsNoHardcodedIdentity, // BV1.R76 — kernel prompts read identity from branding()
+  checkNeutralConfigsNoHostIdentity, // Check 15b — BV1.R102: .json is outside the scan above
   checkHallSectionRegistry,
   checkCoreRequiresExcludedConfig, // task 1824 — core→instance-config require guard
   checkCoreRequiresExcludedModule, // Check 16b — task 2135: core→excluded-module require guard (R89 split)
@@ -1463,9 +1675,13 @@ module.exports = {
   checkKernelPromptsNoHardcodedIdentity, // BV1.R76 / task 1705
   scanPromptIdentity,                    // BV1.R76 — negative-test hook
   stripCommentsForIdentity,              // task 1705 — comment-strip helper (tested)
+  checkNeutralConfigsNoHostIdentity,     // Check 15b — BV1.R102 (tested)
   checkHallSectionRegistry,
   scanHallSectionRegistry,
   hallMainSlice,
+  parseZoneBudgets,      // task 2177 — hall Home zone budgets (tested)
+  scanHallZoneCounts,
+  checkHallZoneBudgets,
   checkErrorEnvelope,       // Check 17 — BV1 R03 / task 1990 (ADR 0116)
   scanFlatErrorSites,       // shared with the R04 sweep + its test
   countFlatErrors,          // per-text detector (tested)

package/scripts/gds/gds-db-backup.service

@@ -10,7 +10,22 @@ User=lars
 Group=lars
 # Run the canonical script from the deployed repo. Keep this path stable;
 # the recipe doc points at it for restore + manual-one-shot use cases.
-ExecStart=/home/lars/amazonprimea/scripts/gds/db-backup-nightly.sh
+#
+# Invoke through `bash` explicitly, NOT as a bare ExecStart path. Every .sh in
+# this repo is committed mode 100644 (they are run as `bash script.sh` — the
+# /backup/trigger route does exactly that via execFile('bash', …)), so a bare
+# ExecStart fails `203/EXEC` the moment the file lands without an exec bit.
+# That is not hypothetical: on cloudbongos this unit died silently for 13 days
+# (2026-07-15 → 07-28) because a core upgrade re-extracted the script 0664, and
+# a `chmod +x` fix does not survive the NEXT upgrade. Going through bash makes
+# the exec bit irrelevant (task 1002479).
+#
+# EDIT THIS PATH when installing — it must point at the deployed core scripts
+# dir for THIS instance, which differs by layout:
+#   vendored/standalone: /home/<user>/<instance>/node_modules/@bongos/core/scripts/gds/db-backup-nightly.sh
+#   full clone:          /home/<user>/<repo>/scripts/gds/db-backup-nightly.sh
+# See docs/recipes/gds-db-backup.md.
+ExecStart=/usr/bin/env bash /home/lars/amazonprimea/scripts/gds/db-backup-nightly.sh
 # Modest hardening — the script only needs read on the socket + write on
 # /var/backups/gds. Anything else is gravy for forensics.
 NoNewPrivileges=true

package/scripts/gds/gds-db-offsite.service

@@ -10,7 +10,15 @@ User=lars
 Group=lars
 # Run the canonical script from the deployed repo. Keep this path stable;
 # the recipe doc points at it for restore + manual-one-shot use cases.
-ExecStart=/home/lars/amazonprimea/scripts/gds/db-backup-offsite.sh
+#
+# Invoke through `bash`, NOT as a bare ExecStart path — see the long note in
+# gds-db-backup.service. Same trap, same fix: the .sh files here are committed
+# mode 100644, so a bare ExecStart dies `203/EXEC` and no chmod survives a core
+# upgrade. The nightly unit lost 13 days of backups to exactly this (1002479);
+# this unit would have hit it on its first run.
+#
+# EDIT THIS PATH when installing (layout differs — vendored vs full clone).
+ExecStart=/usr/bin/env bash /home/lars/amazonprimea/scripts/gds/db-backup-offsite.sh
 # S3 credentials for the Space live outside the repo (ADR 0022). systemd
 # injects them; the file is chmod 600, owned by lars. Missing-file is
 # tolerated here (the script fails loudly if the vars are unset) so a

package/scripts/gds/gen-api-client.js

@@ -439,7 +439,7 @@ function renderReadme(spec, ops) {
     `import { createClient, ApiError } from '@bongos/client';`,
     ``,
     `const api = createClient({`,
-    `  baseUrl: 'https://amazonprimea.com${base}', // or omit for same-origin (browser)`,
+    `  baseUrl: 'https://example.com${base}', // your instance origin — or omit for same-origin (browser)`,
     `  token: process.env.BONGOS_TOKEN,             // Authorization: Bearer <token>`,
     `});`,
     ``,

package/scripts/gds/gen-api-docs.js

@@ -41,6 +41,7 @@ const { API_PREFIX, API_VERSION, VERSIONED_API_PREFIX } = require('../../src/bon
 // category taxonomy the spec advertises (ADR 0116). Keep them pure — the generator
 // must never execute a route file or open a connection.
 const { LIMITS } = require('../../src/bongos/routes/_helpers');
+const { sameContent } = require('./gen-freshness'); // eol-insensitive freshness (CRLF checkouts)
 const apiErrors = require('../../src/bongos/api-errors');
 
 const CORE_ROOT = resolveCoreRoot();
@@ -451,6 +452,11 @@ function extractBody(lines, i, method, constants = {}) {
 function responseValueSchema(expr) {
   const v = String(expr).trim();
   if (v === 'true' || v === 'false') return { type: 'boolean' };
+  // `!!x` and `Boolean(x)` are boolean whatever x is — the two idioms routes use
+  // to coerce a truthy value before returning it (task 1002430). Without this a
+  // handler returning `{ ok: true }` in one branch and `{ ok: !!v }` in another
+  // documents `ok` as untyped, which is strictly worse than the truth.
+  if (/^!!/.test(v) || /^Boolean\s*\(/.test(v)) return { type: 'boolean' };
   if (/^pageMeta\s*\(/.test(v)) return { $ref: '#/components/schemas/PageInfo' };
   return {}; // a variable / call / ternary — the KEY is the win; leave the value open
 }
@@ -533,26 +539,38 @@ function tagFor(route) {
 
 // The full extracted model: [{ method, route, openapiPath, params, rank, tag,
 // description, body, file }], stable-sorted.
-function extractModel() {
+// `routeFiles` is injectable so a test can drive the model over a fixture route file
+// (the default is the live core + module route set).
+function extractModel({ routeFiles = rrc.discoverRouteFiles() } = {}) {
   const routes = [];
   const globals = globalConstants();
-  for (const { abs, rel } of rrc.discoverRouteFiles()) {
+  for (const { abs, rel } of routeFiles) {
     const text = fs.readFileSync(abs, 'utf8');
     const lines = text.split('\n');
     // Constants a validate() rule in THIS file may reference (LIMITS + file-local consts).
     const constants = Object.assign({}, globals, scanFileConstants(text));
-    for (let i = 0; i < lines.length; i++) {
-      const m = /^\s*router\.(get|post|patch|put|delete)\s*\(\s*['"]([^'"]+)['"]/.exec(lines[i]);
-      if (!m) continue;
-      const method = m[1].toUpperCase();
-      const route = m[2];
+    // rrc.scanDeclarations, not a second regex: the spec must enumerate EXACTLY the
+    // routes the ship-time gate enforces. Its own regex missed multi-line declarations,
+    // so 10 real endpoints (6 writes) were absent from the published contract entirely
+    // (BV1.R109b). An unresolvable path is skipped here and reported by checkRouteRanks.
+    for (const decl of rrc.scanDeclarations(text)) {
+      if (decl.route === null) continue;
+      const i = decl.line;
+      const method = decl.method;
+      const route = decl.route;
       const { openapiPath, names } = pathParams(route);
+      // classifyGate, not classifyRank: a route migrated to requirePermission(...)
+      // (BV1.R104-R107) resolves through the governance catalog to its real rank
+      // floor, and names the authority atoms it gates on. Before BV1.R109 those
+      // routes documented as 'any-builder' — enforcement was correct, the LABEL lied.
+      const { rank, perms } = rrc.classifyGate(lines, i);
       routes.push({
         method,
         route,
         openapiPath,
         params: names,
-        rank: rrc.classifyRank(lines, i),
+        rank,
+        perms,
         tag: tagFor(route),
         description: commentBlockAbove(lines, i),
         body: extractBody(lines, i, method, constants),
@@ -697,10 +715,14 @@ function buildOperation(r, stats, schemas) {
     tags: [r.tag],
     summary: `${r.method} ${r.route}`,
     description: (r.description ? r.description + '\n\n' : '')
-      + `**Rank:** \`${r.rank}\` — ${RANK_BLURB[r.rank] || RANK_BLURB.unknown}`,
+      + `**Rank:** \`${r.rank}\` — ${RANK_BLURB[r.rank] || RANK_BLURB.unknown}`
+      + (r.perms && r.perms.length ? `\n\n**Permissions:** \`${r.perms.join('`, `')}\` (all required).` : ''),
     'x-rank': r.rank,
     'x-source': r.file,
   };
+  // The authority ATOMS a migrated route gates on (ADR 0151). Absent on a route still
+  // gated by rank, so today's spec is byte-identical until BV1.R104-R107 land.
+  if (r.perms && r.perms.length) op['x-permissions'] = r.perms;
   if (r.params.length) {
     op.parameters = r.params.map((name) => ({
       name, in: 'path', required: true, schema: { type: 'string' },
@@ -768,11 +790,11 @@ function buildOpenapi(model) {
   const spec = {
     openapi: '3.1.0',
     info: {
-      title: `${productName()} — GDS API`,
+      title: `${productName()} — Bongos API`,
       version: specVersion(),
       license: { name: 'AGPL-3.0-or-later', url: 'https://www.gnu.org/licenses/agpl-3.0.html' },
       description: [
-        `The Game Development System (GDS) API — the build-methodology backend`,
+        `The Bongos API — the build-methodology backend`,
         `(builders, tasks, claims, credits, grading, memory, dev boxes).`,
         ``,
         `**API version:** \`${API_VERSION}\` — served at \`${VERSIONED_API_PREFIX}\`. The`,
@@ -843,7 +865,7 @@ function buildReferenceMd(model, spec) {
   const L = [];
   L.push(MD_BANNER);
   L.push('');
-  L.push('# GDS API reference');
+  L.push('# Bongos API reference');
   L.push('');
   L.push(`> **Generated from the live route files** — the route file is authoritative. ${model.length} endpoints across ${new Set(model.map((r) => r.file)).size} route files.`);
   L.push('> Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).');
@@ -986,8 +1008,8 @@ function main() {
   if (checkOnly) {
     const stale = files.filter((f) => {
       let cur = null;
-      try { cur = fs.readFileSync(f.full, 'utf8'); } catch { /* missing → stale */ }
-      return cur !== f.content;
+      try { cur = fs.readFileSync(f.full, 'utf8'); } catch { return true; /* missing → stale */ }
+      return !sameContent(cur, f.content);
     });
     if (stale.length) {
       console.error(`gen-api-docs --check: STALE — would update ${stale.map((f) => f.rel).join(', ')}. Run \`node scripts/gds/gen-api-docs.js\` and commit.`);